[apple/xnu.git] / iokit / IOKit / IOUserClient.h

/*
 * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_OSREFERENCE_HEADER_START@
 * 
 * This file contains Original Code and/or Modifications of Original Code 
 * as defined in and that are subject to the Apple Public Source License 
 * Version 2.0 (the 'License'). You may not use this file except in 
 * compliance with the License.  The rights granted to you under the 
 * License may not be used to create, or enable the creation or 
 * redistribution of, unlawful or unlicensed copies of an Apple operating 
 * system, or to circumvent, violate, or enable the circumvention or 
 * violation of, any terms of an Apple operating system software license 
 * agreement.
 *
 * Please obtain a copy of the License at 
 * http://www.opensource.apple.com/apsl/ and read it before using this 
 * file.
 *
 * The Original Code and all software distributed under the License are 
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 
 * Please see the License for the specific language governing rights and 
 * limitations under the License.
 *
 * @APPLE_LICENSE_OSREFERENCE_HEADER_END@
 */

/*
 * Changes to this API are expected.
 */

#ifndef _IOKIT_IOUSERCLIENT_H
#define _IOKIT_IOUSERCLIENT_H

#include <IOKit/IOTypes.h>
#include <IOKit/IOService.h>
#include <IOKit/OSMessageNotification.h>


enum {
    kIOUCTypeMask	= 0x0000000f,
    kIOUCScalarIScalarO = 0,
    kIOUCScalarIStructO = 2,
    kIOUCStructIStructO = 3,
    kIOUCScalarIStructI = 4
};

typedef IOReturn (IOService::*IOMethod)(void * p1, void * p2, void * p3,
                                        void * p4, void * p5, void * p6 );

typedef IOReturn (IOService::*IOAsyncMethod)(OSAsyncReference asyncRef,
                                        void * p1, void * p2, void * p3,
                                        void * p4, void * p5, void * p6 );

typedef IOReturn (IOService::*IOTrap)(void * p1, void * p2, void * p3,
                                      void * p4, void * p5, void * p6 );

struct IOExternalMethod {
    IOService *		object;
    IOMethod		func;
    IOOptionBits	flags;
    IOByteCount		count0;
    IOByteCount		count1;
};

struct IOExternalAsyncMethod {
    IOService *		object;
    IOAsyncMethod	func;
    IOOptionBits	flags;
    IOByteCount		count0;
    IOByteCount		count1;
};

struct IOExternalTrap {
    IOService *		object;
    IOTrap		func;
};

enum {
    kIOUserNotifyMaxMessageSize = 64
};

// keys for clientHasPrivilege
#define kIOClientPrivilegeAdministrator	"root"
#define kIOClientPrivilegeLocalUser	"local"

/*!
    @class IOUserClient
    @abstract   Provides a basis for communication between client applications and I/O Kit objects.
*/


class IOUserClient : public IOService
{
    OSDeclareAbstractStructors(IOUserClient)

protected:
/*! @struct ExpansionData
    @discussion This structure will be used to expand the capablilties of this class in the future.
*/    
    struct ExpansionData { };

/*! @var reserved
    Reserved for future use.  (Internal use only) 
*/
    ExpansionData * reserved;

public:
    OSSet * mappings;
    UInt8   sharedInstance;

    UInt8   __reservedA[3];
    void  * __reserved[7];

private:
    OSMetaClassDeclareReservedUnused(IOUserClient, 0);
    OSMetaClassDeclareReservedUnused(IOUserClient, 1);
    OSMetaClassDeclareReservedUnused(IOUserClient, 2);
    OSMetaClassDeclareReservedUnused(IOUserClient, 3);
    OSMetaClassDeclareReservedUnused(IOUserClient, 4);
    OSMetaClassDeclareReservedUnused(IOUserClient, 5);
    OSMetaClassDeclareReservedUnused(IOUserClient, 6);
    OSMetaClassDeclareReservedUnused(IOUserClient, 7);
    OSMetaClassDeclareReservedUnused(IOUserClient, 8);
    OSMetaClassDeclareReservedUnused(IOUserClient, 9);
    OSMetaClassDeclareReservedUnused(IOUserClient, 10);
    OSMetaClassDeclareReservedUnused(IOUserClient, 11);
    OSMetaClassDeclareReservedUnused(IOUserClient, 12);
    OSMetaClassDeclareReservedUnused(IOUserClient, 13);
    OSMetaClassDeclareReservedUnused(IOUserClient, 14);
    OSMetaClassDeclareReservedUnused(IOUserClient, 15);

protected:
    static IOReturn sendAsyncResult(OSAsyncReference reference,
                                    IOReturn result, void *args[], UInt32 numArgs);
    static void setAsyncReference(OSAsyncReference asyncRef,
                                  mach_port_t wakePort,
                                  void *callback, void *refcon);
public:

    static void initialize( void );

    static void destroyUserReferences( OSObject * obj );

    static IOReturn clientHasPrivilege( void * securityToken,
                                        const char * privilegeName );

#if !(defined(__ppc__) && defined(KPI_10_4_0_PPC_COMPAT))
    virtual bool init();
    virtual bool init( OSDictionary * dictionary );
#endif
    // Currently ignores the all args, just passes up to IOService::init()
    virtual bool initWithTask(
                    task_t owningTask, void * securityToken, UInt32 type,
                    OSDictionary * properties);

    virtual bool initWithTask(
                    task_t owningTask, void * securityToken, UInt32 type);

    virtual void free();

    virtual IOReturn clientClose( void );
    virtual IOReturn clientDied( void );

    virtual IOService * getService( void );

    virtual IOReturn registerNotificationPort(
		mach_port_t port, UInt32 type, UInt32 refCon );

    virtual IOReturn getNotificationSemaphore( UInt32 notification_type,
                                    semaphore_t * semaphore );

    virtual IOReturn connectClient( IOUserClient * client );

    // memory will be released by user client when last map is destroyed
    virtual IOReturn clientMemoryForType( UInt32 type,
			        IOOptionBits * options,
				IOMemoryDescriptor ** memory );

    virtual IOMemoryMap * mapClientMemory( IOOptionBits type,
                                    task_t task,
                                    IOOptionBits mapFlags = kIOMapAnywhere,
				    IOVirtualAddress atAddress = 0 );

    /*!
        @function removeMappingForDescriptor
        Remove the first mapping created from the memory descriptor returned by clientMemoryForType() from IOUserClient's list of mappings. If such a mapping exists, it is retained and the reference currently held by IOUserClient is returned to the caller.
        @param memory The memory descriptor instance previously returned by the implementation of clientMemoryForType().
        @result A reference to the first IOMemoryMap instance found in the list of mappings created by IOUserClient from that passed memory descriptor is returned, or zero if none exist. The caller should release this reference.
    */
    IOMemoryMap * removeMappingForDescriptor(IOMemoryDescriptor * memory);

    /*!
        @function exportObjectToClient
        Make an arbitrary OSObject available to the client task.
        @param task The task.
        @param obj The object we want to export to the client.
        @param clientObj Returned value is the client's port name.
    */
    virtual IOReturn exportObjectToClient(task_t task,
				OSObject *obj, io_object_t *clientObj);

    // Old methods for accessing method vector backward compatiblility only
    virtual IOExternalMethod *
        getExternalMethodForIndex( UInt32 index );
    virtual IOExternalAsyncMethod *
        getExternalAsyncMethodForIndex( UInt32 index );

    // Methods for accessing method vector.
    virtual IOExternalMethod *
        getTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
    virtual IOExternalAsyncMethod *
        getAsyncTargetAndMethodForIndex( IOService ** targetP, UInt32 index );

    // Methods for accessing trap vector - old and new style
    virtual IOExternalTrap *
      getExternalTrapForIndex( UInt32 index );
    virtual IOExternalTrap *
      getTargetAndTrapForIndex( IOService **targetP, UInt32 index );
};

#endif /* ! _IOKIT_IOUSERCLIENT_H */
Commit	Line	Data
1c79356b A	1	/*
	2	* Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
	3	*
8ad349bb	4	* @APPLE_LICENSE_OSREFERENCE_HEADER_START@
1c79356b	5	*
8ad349bb A	6	* This file contains Original Code and/or Modifications of Original Code
	7	* as defined in and that are subject to the Apple Public Source License
	8	* Version 2.0 (the 'License'). You may not use this file except in
	9	* compliance with the License. The rights granted to you under the
	10	* License may not be used to create, or enable the creation or
	11	* redistribution of, unlawful or unlicensed copies of an Apple operating
	12	* system, or to circumvent, violate, or enable the circumvention or
	13	* violation of, any terms of an Apple operating system software license
	14	* agreement.
	15	*
	16	* Please obtain a copy of the License at
	17	* http://www.opensource.apple.com/apsl/ and read it before using this
	18	* file.
	19	*
	20	* The Original Code and all software distributed under the License are
	21	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
	22	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
	23	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
	24	* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
	25	* Please see the License for the specific language governing rights and
	26	* limitations under the License.
	27	*
	28	* @APPLE_LICENSE_OSREFERENCE_HEADER_END@
1c79356b A	29	*/
	30
	31	/*
	32	* Changes to this API are expected.
	33	*/
	34
	35	#ifndef _IOKIT_IOUSERCLIENT_H
	36	#define _IOKIT_IOUSERCLIENT_H
	37
	38	#include <IOKit/IOTypes.h>
	39	#include <IOKit/IOService.h>
	40	#include <IOKit/OSMessageNotification.h>
	41
	42
	43	enum {
	44	kIOUCTypeMask = 0x0000000f,
	45	kIOUCScalarIScalarO = 0,
	46	kIOUCScalarIStructO = 2,
	47	kIOUCStructIStructO = 3,
55e303ae	48	kIOUCScalarIStructI = 4
1c79356b A	49	};
	50
	51	typedef IOReturn (IOService::IOMethod)(void p1, void * p2, void * p3,
	52	void * p4, void * p5, void * p6 );
	53
	54	typedef IOReturn (IOService::*IOAsyncMethod)(OSAsyncReference asyncRef,
	55	void * p1, void * p2, void * p3,
	56	void * p4, void * p5, void * p6 );
	57
	58	typedef IOReturn (IOService::IOTrap)(void p1, void * p2, void * p3,
	59	void * p4, void * p5, void * p6 );
	60
	61	struct IOExternalMethod {
	62	IOService * object;
	63	IOMethod func;
	64	IOOptionBits flags;
	65	IOByteCount count0;
	66	IOByteCount count1;
	67	};
	68
	69	struct IOExternalAsyncMethod {
	70	IOService * object;
	71	IOAsyncMethod func;
	72	IOOptionBits flags;
	73	IOByteCount count0;
	74	IOByteCount count1;
	75	};
	76
	77	struct IOExternalTrap {
	78	IOService * object;
	79	IOTrap func;
	80	};
	81
	82	enum {
	83	kIOUserNotifyMaxMessageSize = 64
	84	};
	85
	86	// keys for clientHasPrivilege
	87	#define kIOClientPrivilegeAdministrator "root"
	88	#define kIOClientPrivilegeLocalUser "local"
	89
91447636 A	90	/*!
	91	@class IOUserClient
	92	@abstract Provides a basis for communication between client applications and I/O Kit objects.
	93	*/
	94
	95
1c79356b A	96	class IOUserClient : public IOService
	97	{
	98	OSDeclareAbstractStructors(IOUserClient)
	99
	100	protected:
	101	/*! @struct ExpansionData
	102	@discussion This structure will be used to expand the capablilties of this class in the future.
91447636	103	*/
1c79356b A	104	struct ExpansionData { };
	105
	106	/*! @var reserved
91447636 A	107	Reserved for future use. (Internal use only)
91447636 A	108	*/
1c79356b A	109	ExpansionData * reserved;
	110
	111	public:
	112	OSSet * mappings;
5d5c5d0d A	113	UInt8 sharedInstance;
	114
	115	UInt8 __reservedA[3];
	116	void * __reserved[7];
1c79356b A	117
	118	private:
	119	OSMetaClassDeclareReservedUnused(IOUserClient, 0);
	120	OSMetaClassDeclareReservedUnused(IOUserClient, 1);
	121	OSMetaClassDeclareReservedUnused(IOUserClient, 2);
	122	OSMetaClassDeclareReservedUnused(IOUserClient, 3);
	123	OSMetaClassDeclareReservedUnused(IOUserClient, 4);
	124	OSMetaClassDeclareReservedUnused(IOUserClient, 5);
	125	OSMetaClassDeclareReservedUnused(IOUserClient, 6);
	126	OSMetaClassDeclareReservedUnused(IOUserClient, 7);
	127	OSMetaClassDeclareReservedUnused(IOUserClient, 8);
	128	OSMetaClassDeclareReservedUnused(IOUserClient, 9);
	129	OSMetaClassDeclareReservedUnused(IOUserClient, 10);
	130	OSMetaClassDeclareReservedUnused(IOUserClient, 11);
	131	OSMetaClassDeclareReservedUnused(IOUserClient, 12);
	132	OSMetaClassDeclareReservedUnused(IOUserClient, 13);
	133	OSMetaClassDeclareReservedUnused(IOUserClient, 14);
	134	OSMetaClassDeclareReservedUnused(IOUserClient, 15);
	135
	136	protected:
	137	static IOReturn sendAsyncResult(OSAsyncReference reference,
	138	IOReturn result, void *args[], UInt32 numArgs);
	139	static void setAsyncReference(OSAsyncReference asyncRef,
	140	mach_port_t wakePort,
	141	void callback, void refcon);
	142	public:
	143
	144	static void initialize( void );
	145
	146	static void destroyUserReferences( OSObject * obj );
	147
	148	static IOReturn clientHasPrivilege( void * securityToken,
	149	const char * privilegeName );
	150
5d5c5d0d A	151	#if !(defined(__ppc__) && defined(KPI_10_4_0_PPC_COMPAT))
	152	virtual bool init();
	153	virtual bool init( OSDictionary * dictionary );
	154	#endif
1c79356b A	155	// Currently ignores the all args, just passes up to IOService::init()
	156	virtual bool initWithTask(
	157	task_t owningTask, void * securityToken, UInt32 type,
	158	OSDictionary * properties);
	159
	160	virtual bool initWithTask(
	161	task_t owningTask, void * securityToken, UInt32 type);
	162
	163	virtual void free();
	164
	165	virtual IOReturn clientClose( void );
	166	virtual IOReturn clientDied( void );
	167
	168	virtual IOService * getService( void );
	169
	170	virtual IOReturn registerNotificationPort(
	171	mach_port_t port, UInt32 type, UInt32 refCon );
	172
	173	virtual IOReturn getNotificationSemaphore( UInt32 notification_type,
	174	semaphore_t * semaphore );
	175
	176	virtual IOReturn connectClient( IOUserClient * client );
	177
	178	// memory will be released by user client when last map is destroyed
	179	virtual IOReturn clientMemoryForType( UInt32 type,
	180	IOOptionBits * options,
	181	IOMemoryDescriptor ** memory );
	182
	183	virtual IOMemoryMap * mapClientMemory( IOOptionBits type,
	184	task_t task,
	185	IOOptionBits mapFlags = kIOMapAnywhere,
	186	IOVirtualAddress atAddress = 0 );
483a1d10 A	187
	188	/*!
	189	@function removeMappingForDescriptor
	190	Remove the first mapping created from the memory descriptor returned by clientMemoryForType() from IOUserClient's list of mappings. If such a mapping exists, it is retained and the reference currently held by IOUserClient is returned to the caller.
	191	@param memory The memory descriptor instance previously returned by the implementation of clientMemoryForType().
	192	@result A reference to the first IOMemoryMap instance found in the list of mappings created by IOUserClient from that passed memory descriptor is returned, or zero if none exist. The caller should release this reference.
	193	*/
	194	IOMemoryMap * removeMappingForDescriptor(IOMemoryDescriptor * memory);
	195
1c79356b A	196	/*!
	197	@function exportObjectToClient
	198	Make an arbitrary OSObject available to the client task.
91447636 A	199	@param task The task.
	200	@param obj The object we want to export to the client.
	201	@param clientObj Returned value is the client's port name.
1c79356b A	202	*/
	203	virtual IOReturn exportObjectToClient(task_t task,
	204	OSObject obj, io_object_t clientObj);
	205
	206	// Old methods for accessing method vector backward compatiblility only
	207	virtual IOExternalMethod *
	208	getExternalMethodForIndex( UInt32 index );
	209	virtual IOExternalAsyncMethod *
	210	getExternalAsyncMethodForIndex( UInt32 index );
	211
	212	// Methods for accessing method vector.
	213	virtual IOExternalMethod *
	214	getTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
	215	virtual IOExternalAsyncMethod *
	216	getAsyncTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
	217
	218	// Methods for accessing trap vector - old and new style
	219	virtual IOExternalTrap *
	220	getExternalTrapForIndex( UInt32 index );
	221	virtual IOExternalTrap *
	222	getTargetAndTrapForIndex( IOService **targetP, UInt32 index );
	223	};
	224
	225	#endif /* ! _IOKIT_IOUSERCLIENT_H */
	226