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

/*
 * Copyright (c) 1998-2019 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>
#include <DriverKit/IOUserClient.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
{
	OSDeclareAbstractStructorsWithDispatch(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)
 */
	APPLE_KEXT_WSHADOW_PUSH;
	ExpansionData * reserved;
	APPLE_KEXT_WSHADOW_POP;

	bool reserve();

#ifdef XNU_KERNEL_PRIVATE

public:
	OSSet * mappings;
	UInt8   sharedInstance;
	UInt8   closed;
	UInt8   __ipcFinal;
	UInt8   messageAppSuspended;
	volatile SInt32 __ipc;
	queue_head_t owners;
	IOLock * lock;
#if __LP64__
	void  * __reserved[4];
#else
	void  * __reserved[3];
#endif

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

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

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

	static OSDictionary * copyClientEntitlements(task_t task);

/*!
 *   @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 );

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

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

#if KERNEL_PRIVATE

/*!
 *   @function copyPortNameForObjectInTask
 *   Make an arbitrary OSObject available to the client task as a port name.
 *   The port does not respond to any IOKit IPC calls.
 *   @param task The task.
 *   @param object The object we want to export to the client.
 *   The port holds a reference on the object, this function does not consume any reference on the object.
 *   @param port_name Returned value is the task's port name. It has one send right created by this function.
 *   @result A return code.
 */
	static IOReturn copyPortNameForObjectInTask(task_t task, OSObject *object,
	    mach_port_name_t * port_name);

/*!
 *   @function copyObjectForPortNameInTask
 *   Look up an OSObject given a task's port name created with copyPortNameForObjectInTask().
 *   @param task The task.
 *   @param port_name The task's port name. This function does not consume any reference on the port name.
 *   @param object If the port name is valid, a reference to the object is returned. It should be released by the caller.
 *   @result A return code.
 */
	static IOReturn copyObjectForPortNameInTask(task_t task, mach_port_name_t port_name,
	    OSObject **object);

/*!
 *   @function adjustPortNameReferencesInTask
 *   Adjust the send rights for a port name created with copyPortNameForObjectInTask().
 *   @param task The task.
 *   @param port_name The task's port name.
 *   @param delta Signed value change to the number of user references.
 *   @result A return code.
 */
	static IOReturn adjustPortNameReferencesInTask(task_t task, mach_port_name_t port_name, mach_port_delta_t delta);

#define IOUC_COPYPORTNAMEFOROBJECTINTASK    1

#endif /* KERNEL_PRIVATE */

// 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(
		LIBKERN_RETURNS_NOT_RETAINED IOService ** targetP, UInt32 index );
	virtual IOExternalAsyncMethod *
	getAsyncTargetAndMethodForIndex(
		LIBKERN_RETURNS_NOT_RETAINED IOService ** targetP, UInt32 index );

// Methods for accessing trap vector - old and new style
	virtual IOExternalTrap *
	getExternalTrapForIndex( UInt32 index )
	APPLE_KEXT_DEPRECATED;

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

#ifdef XNU_KERNEL_PRIVATE
extern "C" void IOMachPortDestroyUserReferences(OSObject * obj, natural_t type);
#endif /* XNU_KERNEL_PRIVATE */

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