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

/*
 * Copyright (c) 1998-2016 Apple 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>

#if IOKITSTATS
#include <IOKit/IOStatisticsPrivate.h>
#endif

#define _IOUSERCLIENT_SENDASYNCRESULT64WITHOPTIONS_		1

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

    kIOUCForegroundOnly = 0x00000010,
};

/*! @enum
    @abstract Constant to denote a variable length structure argument to IOUserClient.
    @constant kIOUCVariableStructureSize Use in the structures IOExternalMethod, IOExternalAsyncMethod, IOExternalMethodDispatch to specify the size of the structure is variable.
*/
enum {
    kIOUCVariableStructureSize = 0xffffffff
};


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
};

enum {
    kIOUserNotifyOptionCanDrop = 0x1 /* Fail if queue is full, rather than infinitely queuing. */
};

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

/*! @enum
    @abstract Constants to specify the maximum number of scalar arguments in the IOExternalMethodArguments structure. These constants are documentary since the scalarInputCount, scalarOutputCount fields reflect the actual number passed.
    @constant kIOExternalMethodScalarInputCountMax The maximum number of scalars able to passed on input.
    @constant kIOExternalMethodScalarOutputCountMax The maximum number of scalars able to passed on output.
*/
enum {
    kIOExternalMethodScalarInputCountMax  = 16,
    kIOExternalMethodScalarOutputCountMax = 16,
};


struct IOExternalMethodArguments
{
    uint32_t		version;

    uint32_t		selector;

    mach_port_t           asyncWakePort;
    io_user_reference_t * asyncReference;
    uint32_t              asyncReferenceCount;

    const uint64_t *    scalarInput;
    uint32_t		scalarInputCount;

    const void *	structureInput;
    uint32_t		structureInputSize;

    IOMemoryDescriptor * structureInputDescriptor;
   
    uint64_t *		scalarOutput;
    uint32_t		scalarOutputCount;

    void *		structureOutput;
    uint32_t		structureOutputSize;

    IOMemoryDescriptor * structureOutputDescriptor;
    uint32_t		 structureOutputDescriptorSize;

    uint32_t		__reservedA;

    OSObject **         structureVariableOutputData;

    uint32_t		__reserved[30];
};

typedef IOReturn (*IOExternalMethodAction)(OSObject * target, void * reference, 
					    IOExternalMethodArguments * arguments);
struct IOExternalMethodDispatch
{
    IOExternalMethodAction function;
    uint32_t		   checkScalarInputCount;
    uint32_t		   checkStructureInputSize;
    uint32_t		   checkScalarOutputCount;
    uint32_t		   checkStructureOutputSize;
};

enum {
#define IO_EXTERNAL_METHOD_ARGUMENTS_CURRENT_VERSION	2
    kIOExternalMethodArgumentsCurrentVersion = IO_EXTERNAL_METHOD_ARGUMENTS_CURRENT_VERSION
};


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

class IOUserClient : public IOService
{
    OSDeclareAbstractStructors(IOUserClient)
#if IOKITSTATS
    friend class IOStatistics;
#endif

protected:
/*! @struct ExpansionData
    @discussion This structure will be used to expand the capablilties of this class in the future.
*/    
    struct ExpansionData {
#if IOKITSTATS
	    IOUserClientCounter *counter;
#else
	    void *iokitstatsReserved;
#endif
    };

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

    bool reserve();

#ifdef XNU_KERNEL_PRIVATE

public:
    OSSet * mappings;
    UInt8   sharedInstance;
    UInt8   closed;
    UInt8   __ipcFinal;
    UInt8   __reservedA[1];
    volatile SInt32 __ipc;
    queue_head_t owners;
#if __LP64__
    void  * __reserved[5];
#else
    void  * __reserved[4];
#endif

#else /* XNU_KERNEL_PRIVATE */
private:
    void  * __reserved[9];
#endif /* XNU_KERNEL_PRIVATE */

public:
   virtual IOReturn externalMethod( uint32_t selector, IOExternalMethodArguments * arguments,
					IOExternalMethodDispatch * dispatch = 0, OSObject * target = 0, void * reference = 0 );

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

private:
#if __LP64__
    OSMetaClassDeclareReservedUnused(IOUserClient, 0);
    OSMetaClassDeclareReservedUnused(IOUserClient, 1);
#else
    OSMetaClassDeclareReservedUsed(IOUserClient, 0);
    OSMetaClassDeclareReservedUsed(IOUserClient, 1);
#endif
    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);

#ifdef XNU_KERNEL_PRIVATE

    /* Available within xnu source only */
public:
    static void initialize( void );
    static void destroyUserReferences( OSObject * obj );
    static bool finalizeUserReferences( OSObject * obj );
    IOMemoryMap * mapClientMemory64( IOOptionBits type,
                                    task_t task,
                                    IOOptionBits mapFlags = kIOMapAnywhere,
				    mach_vm_address_t atAddress = 0 );
    IOReturn registerOwner(task_t task);
    void     noMoreSenders(void);

#endif /* XNU_KERNEL_PRIVATE */

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);

    static IOReturn sendAsyncResult64(OSAsyncReference64 reference,
                                        IOReturn result, io_user_reference_t args[], UInt32 numArgs);

    /*! 
        @function sendAsyncResult64WithOptions
        @abstract Send a notification as with sendAsyncResult, but with finite queueing.
        @discussion IOUserClient::sendAsyncResult64() will infitely queue messages if the client
                is not processing them in a timely fashion.  This variant will not, for simple
                handling of situations where clients may be expected to stop processing messages.
     */
    static IOReturn sendAsyncResult64WithOptions(OSAsyncReference64 reference,
                                        IOReturn result, io_user_reference_t args[], UInt32 numArgs, 
					IOOptionBits options);

    static void setAsyncReference64(OSAsyncReference64 asyncRef,
					mach_port_t wakePort,
					mach_vm_address_t callback, io_user_reference_t refcon);

    static void setAsyncReference64(OSAsyncReference64 asyncRef,
					mach_port_t wakePort,
					mach_vm_address_t callback, io_user_reference_t refcon,
                    task_t task);

public:

    static IOReturn clientHasAuthorization( task_t task,
                                            IOService * service );

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

    static OSObject * copyClientEntitlement( task_t task,
                                             const char * entitlement );

    /*!
        @function releaseAsyncReference64
	@abstract Release the mach_port_t reference held within the OSAsyncReference64 structure.
	@discussion The OSAsyncReference64 structure passed to async methods holds a reference to the wakeup mach port, which should be released to balance each async method call. Behavior is undefined if these calls are not correctly balanced.
        @param reference The reference passed to the subclass IOAsyncMethod, or externalMethod() in the IOExternalMethodArguments.asyncReference field.
        @result A return code.
    */
    static IOReturn releaseAsyncReference64(OSAsyncReference64 reference);
    /*!
        @function releaseNotificationPort
	@abstract Release the mach_port_t passed to registerNotificationPort().
	@discussion The mach_port_t passed to the registerNotificationPort() methods should be released to balance each call to registerNotificationPort(). Behavior is undefined if these calls are not correctly balanced.
        @param port The mach_port_t argument previously passed to the subclass implementation of registerNotificationPort().
        @result A return code.
    */
    static IOReturn releaseNotificationPort(mach_port_t port);

    virtual bool init() APPLE_KEXT_OVERRIDE;
    virtual bool init( OSDictionary * dictionary ) APPLE_KEXT_OVERRIDE;
    // 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() APPLE_KEXT_OVERRIDE;

    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 );

#if !__LP64__
private:
	APPLE_KEXT_COMPATIBILITY_VIRTUAL
	IOMemoryMap * mapClientMemory( IOOptionBits type,
                                    task_t task,
                                    IOOptionBits mapFlags = kIOMapAnywhere,
									IOVirtualAddress atAddress = 0 );
#endif

    static IOReturn _sendAsyncResult64(OSAsyncReference64 reference,
                                    IOReturn result, io_user_reference_t args[], UInt32 numArgs, IOOptionBits options);
public:

    /*!
        @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 )
	APPLE_KEXT_DEPRECATED;
    virtual IOExternalAsyncMethod *
        getExternalAsyncMethodForIndex( UInt32 index )
	APPLE_KEXT_DEPRECATED;

    // 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 )
	APPLE_KEXT_DEPRECATED;

    virtual IOExternalTrap *
      getTargetAndTrapForIndex( IOService **targetP, UInt32 index );
};

#endif /* ! _IOKIT_IOUSERCLIENT_H */
Commit	Line	Data
1c79356b	1	/*
39037602	2	* Copyright (c) 1998-2016 Apple Inc. All rights reserved.
1c79356b	3	*
2d21ac55	4	* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
1c79356b	5	*
2d21ac55 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.
8f6c56a5	14	*
2d21ac55 A	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
8f6c56a5 A	20	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
8f6c56a5 A	21	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
2d21ac55 A	22	* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
	23	* Please see the License for the specific language governing rights and
	24	* limitations under the License.
8f6c56a5	25	*
2d21ac55	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
6d2010ae A	40	#if IOKITSTATS
	41	#include <IOKit/IOStatisticsPrivate.h>
	42	#endif
1c79356b	43
39236c6e A	44	#define _IOUSERCLIENT_SENDASYNCRESULT64WITHOPTIONS_ 1
39236c6e A	45
1c79356b A	46	enum {
	47	kIOUCTypeMask = 0x0000000f,
	48	kIOUCScalarIScalarO = 0,
	49	kIOUCScalarIStructO = 2,
	50	kIOUCStructIStructO = 3,
d1ecb069 A	51	kIOUCScalarIStructI = 4,
	52
	53	kIOUCForegroundOnly = 0x00000010,
1c79356b A	54	};
1c79356b A	55
2d21ac55 A	56	/*! @enum
	57	@abstract Constant to denote a variable length structure argument to IOUserClient.
	58	@constant kIOUCVariableStructureSize Use in the structures IOExternalMethod, IOExternalAsyncMethod, IOExternalMethodDispatch to specify the size of the structure is variable.
	59	*/
	60	enum {
	61	kIOUCVariableStructureSize = 0xffffffff
	62	};
	63
	64
1c79356b A	65	typedef IOReturn (IOService::IOMethod)(void p1, void * p2, void * p3,
	66	void * p4, void * p5, void * p6 );
	67
	68	typedef IOReturn (IOService::*IOAsyncMethod)(OSAsyncReference asyncRef,
	69	void * p1, void * p2, void * p3,
	70	void * p4, void * p5, void * p6 );
	71
	72	typedef IOReturn (IOService::IOTrap)(void p1, void * p2, void * p3,
	73	void * p4, void * p5, void * p6 );
	74
	75	struct IOExternalMethod {
	76	IOService * object;
	77	IOMethod func;
	78	IOOptionBits flags;
	79	IOByteCount count0;
	80	IOByteCount count1;
	81	};
	82
	83	struct IOExternalAsyncMethod {
	84	IOService * object;
	85	IOAsyncMethod func;
	86	IOOptionBits flags;
	87	IOByteCount count0;
	88	IOByteCount count1;
	89	};
	90
	91	struct IOExternalTrap {
	92	IOService * object;
	93	IOTrap func;
	94	};
	95
	96	enum {
	97	kIOUserNotifyMaxMessageSize = 64
	98	};
	99
39236c6e A	100	enum {
	101	kIOUserNotifyOptionCanDrop = 0x1 /* Fail if queue is full, rather than infinitely queuing. */
	102	};
	103
1c79356b A	104	// keys for clientHasPrivilege
	105	#define kIOClientPrivilegeAdministrator "root"
	106	#define kIOClientPrivilegeLocalUser "local"
d1ecb069	107	#define kIOClientPrivilegeForeground "foreground"
1c79356b	108
2d21ac55 A	109	/*! @enum
	110	@abstract Constants to specify the maximum number of scalar arguments in the IOExternalMethodArguments structure. These constants are documentary since the scalarInputCount, scalarOutputCount fields reflect the actual number passed.
	111	@constant kIOExternalMethodScalarInputCountMax The maximum number of scalars able to passed on input.
	112	@constant kIOExternalMethodScalarOutputCountMax The maximum number of scalars able to passed on output.
	113	*/
	114	enum {
	115	kIOExternalMethodScalarInputCountMax = 16,
	116	kIOExternalMethodScalarOutputCountMax = 16,
	117	};
	118
	119
	120	struct IOExternalMethodArguments
	121	{
	122	uint32_t version;
	123
	124	uint32_t selector;
	125
	126	mach_port_t asyncWakePort;
	127	io_user_reference_t * asyncReference;
	128	uint32_t asyncReferenceCount;
	129
	130	const uint64_t * scalarInput;
	131	uint32_t scalarInputCount;
	132
	133	const void * structureInput;
	134	uint32_t structureInputSize;
	135
	136	IOMemoryDescriptor * structureInputDescriptor;
	137
	138	uint64_t * scalarOutput;
	139	uint32_t scalarOutputCount;
	140
	141	void * structureOutput;
	142	uint32_t structureOutputSize;
	143
	144	IOMemoryDescriptor * structureOutputDescriptor;
	145	uint32_t structureOutputDescriptorSize;
	146
ebb1b9f4 A	147	uint32_t __reservedA;
	148
	149	OSObject ** structureVariableOutputData;
	150
	151	uint32_t __reserved[30];
2d21ac55 A	152	};
	153
	154	typedef IOReturn (IOExternalMethodAction)(OSObject target, void * reference,
	155	IOExternalMethodArguments * arguments);
	156	struct IOExternalMethodDispatch
	157	{
	158	IOExternalMethodAction function;
	159	uint32_t checkScalarInputCount;
	160	uint32_t checkStructureInputSize;
	161	uint32_t checkScalarOutputCount;
	162	uint32_t checkStructureOutputSize;
	163	};
	164
	165	enum {
ebb1b9f4	166	#define IO_EXTERNAL_METHOD_ARGUMENTS_CURRENT_VERSION 2
2d21ac55 A	167	kIOExternalMethodArgumentsCurrentVersion = IO_EXTERNAL_METHOD_ARGUMENTS_CURRENT_VERSION
	168	};
	169
	170
91447636 A	171	/*!
	172	@class IOUserClient
	173	@abstract Provides a basis for communication between client applications and I/O Kit objects.
	174	*/
	175
1c79356b A	176	class IOUserClient : public IOService
	177	{
	178	OSDeclareAbstractStructors(IOUserClient)
6d2010ae A	179	#if IOKITSTATS
	180	friend class IOStatistics;
	181	#endif
1c79356b A	182
	183	protected:
	184	/*! @struct ExpansionData
	185	@discussion This structure will be used to expand the capablilties of this class in the future.
91447636	186	*/
6d2010ae A	187	struct ExpansionData {
	188	#if IOKITSTATS
	189	IOUserClientCounter *counter;
	190	#else
	191	void *iokitstatsReserved;
	192	#endif
	193	};
1c79356b A	194
1c79356b A	195	/*! @var reserved
91447636 A	196	Reserved for future use. (Internal use only)
91447636 A	197	*/
1c79356b A	198	ExpansionData * reserved;
1c79356b A	199
6d2010ae A	200	bool reserve();
6d2010ae A	201
b0d623f7	202	#ifdef XNU_KERNEL_PRIVATE
7e41aa88	203
1c79356b A	204	public:
1c79356b A	205	OSSet * mappings;
0c530ab8	206	UInt8 sharedInstance;
c7d2c2c6	207	UInt8 closed;
490019cf A	208	UInt8 __ipcFinal;
	209	UInt8 __reservedA[1];
	210	volatile SInt32 __ipc;
7e41aa88	211	queue_head_t owners;
490019cf	212	#if __LP64__
7e41aa88	213	void * __reserved[5];
490019cf	214	#else
7e41aa88	215	void * __reserved[4];
490019cf	216	#endif
1c79356b	217
7e41aa88 A	218	#else /* XNU_KERNEL_PRIVATE */
	219	private:
	220	void * __reserved[9];
	221	#endif /* XNU_KERNEL_PRIVATE */
	222
b0d623f7 A	223	public:
b0d623f7 A	224	virtual IOReturn externalMethod( uint32_t selector, IOExternalMethodArguments * arguments,
2d21ac55	225	IOExternalMethodDispatch * dispatch = 0, OSObject * target = 0, void * reference = 0 );
2d21ac55	226
b0d623f7 A	227	virtual IOReturn registerNotificationPort(
b0d623f7 A	228	mach_port_t port, UInt32 type, io_user_reference_t refCon);
2d21ac55	229
b0d623f7 A	230	private:
	231	#if __LP64__
	232	OSMetaClassDeclareReservedUnused(IOUserClient, 0);
1c79356b	233	OSMetaClassDeclareReservedUnused(IOUserClient, 1);
b0d623f7 A	234	#else
	235	OSMetaClassDeclareReservedUsed(IOUserClient, 0);
	236	OSMetaClassDeclareReservedUsed(IOUserClient, 1);
	237	#endif
1c79356b A	238	OSMetaClassDeclareReservedUnused(IOUserClient, 2);
	239	OSMetaClassDeclareReservedUnused(IOUserClient, 3);
	240	OSMetaClassDeclareReservedUnused(IOUserClient, 4);
	241	OSMetaClassDeclareReservedUnused(IOUserClient, 5);
	242	OSMetaClassDeclareReservedUnused(IOUserClient, 6);
	243	OSMetaClassDeclareReservedUnused(IOUserClient, 7);
	244	OSMetaClassDeclareReservedUnused(IOUserClient, 8);
	245	OSMetaClassDeclareReservedUnused(IOUserClient, 9);
	246	OSMetaClassDeclareReservedUnused(IOUserClient, 10);
	247	OSMetaClassDeclareReservedUnused(IOUserClient, 11);
	248	OSMetaClassDeclareReservedUnused(IOUserClient, 12);
	249	OSMetaClassDeclareReservedUnused(IOUserClient, 13);
	250	OSMetaClassDeclareReservedUnused(IOUserClient, 14);
	251	OSMetaClassDeclareReservedUnused(IOUserClient, 15);
	252
b0d623f7	253	#ifdef XNU_KERNEL_PRIVATE
7e41aa88	254
b0d623f7 A	255	/* Available within xnu source only */
	256	public:
	257	static void initialize( void );
	258	static void destroyUserReferences( OSObject * obj );
490019cf	259	static bool finalizeUserReferences( OSObject * obj );
b0d623f7 A	260	IOMemoryMap * mapClientMemory64( IOOptionBits type,
	261	task_t task,
	262	IOOptionBits mapFlags = kIOMapAnywhere,
	263	mach_vm_address_t atAddress = 0 );
7e41aa88 A	264	IOReturn registerOwner(task_t task);
	265	void noMoreSenders(void);
	266
	267	#endif /* XNU_KERNEL_PRIVATE */
b0d623f7	268
1c79356b A	269	protected:
	270	static IOReturn sendAsyncResult(OSAsyncReference reference,
	271	IOReturn result, void *args[], UInt32 numArgs);
	272	static void setAsyncReference(OSAsyncReference asyncRef,
	273	mach_port_t wakePort,
	274	void callback, void refcon);
2d21ac55 A	275
	276	static IOReturn sendAsyncResult64(OSAsyncReference64 reference,
	277	IOReturn result, io_user_reference_t args[], UInt32 numArgs);
39236c6e A	278
	279	/*!
	280	@function sendAsyncResult64WithOptions
	281	@abstract Send a notification as with sendAsyncResult, but with finite queueing.
	282	@discussion IOUserClient::sendAsyncResult64() will infitely queue messages if the client
	283	is not processing them in a timely fashion. This variant will not, for simple
	284	handling of situations where clients may be expected to stop processing messages.
	285	*/
	286	static IOReturn sendAsyncResult64WithOptions(OSAsyncReference64 reference,
	287	IOReturn result, io_user_reference_t args[], UInt32 numArgs,
	288	IOOptionBits options);
	289
2d21ac55 A	290	static void setAsyncReference64(OSAsyncReference64 asyncRef,
	291	mach_port_t wakePort,
	292	mach_vm_address_t callback, io_user_reference_t refcon);
39236c6e A	293
	294	static void setAsyncReference64(OSAsyncReference64 asyncRef,
	295	mach_port_t wakePort,
	296	mach_vm_address_t callback, io_user_reference_t refcon,
	297	task_t task);
	298
1c79356b A	299	public:
1c79356b A	300
fe8ab488 A	301	static IOReturn clientHasAuthorization( task_t task,
	302	IOService * service );
	303
1c79356b A	304	static IOReturn clientHasPrivilege( void * securityToken,
	305	const char * privilegeName );
	306
fe8ab488 A	307	static OSObject * copyClientEntitlement( task_t task,
	308	const char * entitlement );
	309
b0d623f7 A	310	/*!
	311	@function releaseAsyncReference64
	312	@abstract Release the mach_port_t reference held within the OSAsyncReference64 structure.
	313	@discussion The OSAsyncReference64 structure passed to async methods holds a reference to the wakeup mach port, which should be released to balance each async method call. Behavior is undefined if these calls are not correctly balanced.
	314	@param reference The reference passed to the subclass IOAsyncMethod, or externalMethod() in the IOExternalMethodArguments.asyncReference field.
	315	@result A return code.
	316	*/
	317	static IOReturn releaseAsyncReference64(OSAsyncReference64 reference);
	318	/*!
	319	@function releaseNotificationPort
	320	@abstract Release the mach_port_t passed to registerNotificationPort().
	321	@discussion The mach_port_t passed to the registerNotificationPort() methods should be released to balance each call to registerNotificationPort(). Behavior is undefined if these calls are not correctly balanced.
39037602	322	@param port The mach_port_t argument previously passed to the subclass implementation of registerNotificationPort().
b0d623f7 A	323	@result A return code.
	324	*/
	325	static IOReturn releaseNotificationPort(mach_port_t port);
	326
3e170ce0 A	327	virtual bool init() APPLE_KEXT_OVERRIDE;
3e170ce0 A	328	virtual bool init( OSDictionary * dictionary ) APPLE_KEXT_OVERRIDE;
1c79356b A	329	// Currently ignores the all args, just passes up to IOService::init()
	330	virtual bool initWithTask(
	331	task_t owningTask, void * securityToken, UInt32 type,
	332	OSDictionary * properties);
	333
	334	virtual bool initWithTask(
	335	task_t owningTask, void * securityToken, UInt32 type);
	336
3e170ce0	337	virtual void free() APPLE_KEXT_OVERRIDE;
1c79356b A	338
	339	virtual IOReturn clientClose( void );
	340	virtual IOReturn clientDied( void );
	341
	342	virtual IOService * getService( void );
	343
	344	virtual IOReturn registerNotificationPort(
	345	mach_port_t port, UInt32 type, UInt32 refCon );
	346
	347	virtual IOReturn getNotificationSemaphore( UInt32 notification_type,
	348	semaphore_t * semaphore );
	349
	350	virtual IOReturn connectClient( IOUserClient * client );
	351
	352	// memory will be released by user client when last map is destroyed
	353	virtual IOReturn clientMemoryForType( UInt32 type,
	354	IOOptionBits * options,
	355	IOMemoryDescriptor ** memory );
	356
b0d623f7 A	357	#if !__LP64__
	358	private:
	359	APPLE_KEXT_COMPATIBILITY_VIRTUAL
	360	IOMemoryMap * mapClientMemory( IOOptionBits type,
1c79356b A	361	task_t task,
1c79356b A	362	IOOptionBits mapFlags = kIOMapAnywhere,
b0d623f7 A	363	IOVirtualAddress atAddress = 0 );
b0d623f7 A	364	#endif
483a1d10	365
39236c6e A	366	static IOReturn _sendAsyncResult64(OSAsyncReference64 reference,
39236c6e A	367	IOReturn result, io_user_reference_t args[], UInt32 numArgs, IOOptionBits options);
b0d623f7	368	public:
2d21ac55	369
483a1d10 A	370	/*!
	371	@function removeMappingForDescriptor
	372	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.
	373	@param memory The memory descriptor instance previously returned by the implementation of clientMemoryForType().
	374	@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.
	375	*/
	376	IOMemoryMap * removeMappingForDescriptor(IOMemoryDescriptor * memory);
	377
1c79356b A	378	/*!
	379	@function exportObjectToClient
	380	Make an arbitrary OSObject available to the client task.
91447636 A	381	@param task The task.
	382	@param obj The object we want to export to the client.
	383	@param clientObj Returned value is the client's port name.
1c79356b A	384	*/
	385	virtual IOReturn exportObjectToClient(task_t task,
	386	OSObject obj, io_object_t clientObj);
	387
	388	// Old methods for accessing method vector backward compatiblility only
	389	virtual IOExternalMethod *
b0d623f7 A	390	getExternalMethodForIndex( UInt32 index )
b0d623f7 A	391	APPLE_KEXT_DEPRECATED;
1c79356b	392	virtual IOExternalAsyncMethod *
b0d623f7 A	393	getExternalAsyncMethodForIndex( UInt32 index )
b0d623f7 A	394	APPLE_KEXT_DEPRECATED;
1c79356b A	395
	396	// Methods for accessing method vector.
	397	virtual IOExternalMethod *
	398	getTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
	399	virtual IOExternalAsyncMethod *
	400	getAsyncTargetAndMethodForIndex( IOService ** targetP, UInt32 index );
	401
	402	// Methods for accessing trap vector - old and new style
	403	virtual IOExternalTrap *
b0d623f7 A	404	getExternalTrapForIndex( UInt32 index )
	405	APPLE_KEXT_DEPRECATED;
	406
1c79356b A	407	virtual IOExternalTrap *
	408	getTargetAndTrapForIndex( IOService **targetP, UInt32 index );
	409	};
	410
	411	#endif /* ! _IOKIT_IOUSERCLIENT_H */
	412