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

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