[apple/xnu.git] / iokit / IOKit / IOCommandGate.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@
 */
/*[
 *   1999-8-10	Godfrey van der Linden(gvdl)
 *       Created.
 *  ]*/
/*! @language embedded-c++ */

#ifndef _IOKIT_IOCOMMANDGATE_H
#define _IOKIT_IOCOMMANDGATE_H

#include <IOKit/IOEventSource.h>

/*!
 *   @class IOCommandGate : public IOEventSource
 *   @abstract Single-threaded work loop client request mechanism.
 *   @discussion An IOCommandGate instance is an extremely lightweight mechanism
 *  that executes an action on the driver's work loop.  Although the code does not
 *  technically execute on the work loop itself, a single-threaded work loop semantic
 *  is maintained for this event source using the work loop gate.  The command gate
 *  tests for a potential self dead lock by checking if the runCommand request is
 *  made from the work loop's thread, it doesn't check for a mutual dead lock though
 *  where a pair of work loop's dead lock each other.
 *  <br><br>
 *       The IOCommandGate is a lighter weight version of the IOCommandQueue and
 *  should be used in preference.  Generally use a command queue whenever you need a
 *  client to submit a request to a work loop.  A typical command gate action would
 *  check if the hardware is active, if so it will add the request to a pending
 *  queue internal to the device or the device's family.  Otherwise if the hardware
 *  is inactive then this request can be acted upon immediately.
 *  <br><br>
 *   CAUTION: The runAction, runCommand, and attemptCommand functions cannot be called from an interrupt context.
 *
 */
class IOCommandGate : public IOEventSource
{
	OSDeclareDefaultStructors(IOCommandGate);

public:
/*!
 *   @typedef Action
 *   @discussion Type and arguments of callout C function that is used when
 *  a runCommand is executed by a client.  Cast to this type when you want a C++
 *  member function to be used.  Note the arg1 - arg3 parameters are straight pass
 *  through from the runCommand to the action callout.
 *   @param owner
 *       Target of the function, can be used as a refcon.  The owner is set
 *  during initialisation of the IOCommandGate instance.	 Note if a C++ function
 *  was specified this parameter is implicitly the first paramter in the target
 *  member function's parameter list.
 *   @param arg0 Argument to action from run operation.
 *   @param arg1 Argument to action from run operation.
 *   @param arg2 Argument to action from run operation.
 *   @param arg3 Argument to action from run operation.
 */
	typedef IOReturn (*Action)(OSObject *owner,
	    void *arg0, void *arg1,
	    void *arg2, void *arg3);

protected:

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

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

public:
/*! @function commandGate
 *   @abstract Factory method to create and initialise an IOCommandGate, See $link init.
 *   @result Returns a pointer to the new command gate if sucessful, 0 otherwise. */
	static IOCommandGate *commandGate(OSObject *owner, Action action = NULL);

/*! @function init
 *   @abstract Class initialiser.
 *   @discussion Initialiser for IOCommandGate operates only on newly 'newed'
 *  objects.  Shouldn't be used to re-init an existing instance.
 *   @param owner       Owner of this, newly created, instance of the IOCommandGate.  This argument will be used as the first parameter in the action callout.
 *   @param action
 *       Pointer to a C function that is called whenever a client of the
 *  IOCommandGate calls runCommand.	 NB Can be a C++ member function but caller
 *  must cast the member function to $link IOCommandGate::Action and they will get a
 *  compiler warning.  Defaults to zero, see $link IOEventSource::setAction.
 *   @result True if inherited classes initialise successfully. */
	virtual bool init(OSObject *owner, Action action = NULL);

// Superclass overrides
	virtual void free() APPLE_KEXT_OVERRIDE;
	virtual void setWorkLoop(IOWorkLoop *inWorkLoop) APPLE_KEXT_OVERRIDE;

/*! @function runCommand
 *   @abstract Single thread a command with the target work loop.
 *   @discussion Client function that causes the current action to be called in
 *  a single threaded manner.  Beware the work loop's gate is recursive and command
 *  gates can cause direct or indirect re-entrancy.	 When the executing on a
 *  client's thread runCommand will sleep until the work loop's gate opens for
 *  execution of client actions, the action is single threaded against all other
 *  work loop event sources.  If the command is disabled the attempt to run a command will be stalled until enable is called.
 *   @param arg0 Parameter for action of command gate, defaults to 0.
 *   @param arg1 Parameter for action of command gate, defaults to 0.
 *   @param arg2 Parameter for action of command gate, defaults to 0.
 *   @param arg3 Parameter for action of command gate, defaults to 0.
 *   @result kIOReturnSuccess if successful. kIOReturnAborted if a disabled command gate is free()ed before being reenabled, kIOReturnNoResources if no action available.
 */
	virtual IOReturn runCommand(void *arg0 = NULL, void *arg1 = NULL,
	    void *arg2 = NULL, void *arg3 = NULL);

/*! @function runAction
 *   @abstract Single thread a call to an action with the target work loop.
 *   @discussion Client function that causes the given action to be called in
 *  a single threaded manner.  Beware the work loop's gate is recursive and command
 *  gates can cause direct or indirect re-entrancy.	 When the executing on a
 *  client's thread runAction will sleep until the work loop's gate opens for
 *  execution of client actions, the action is single threaded against all other
 *  work loop event sources.  If the command is disabled the attempt to run a command will be stalled until enable is called.
 *   @param action Pointer to function to be executed in the context of the work loop.
 *   @param arg0 Parameter for action parameter, defaults to 0.
 *   @param arg1 Parameter for action parameter, defaults to 0.
 *   @param arg2 Parameter for action parameter, defaults to 0.
 *   @param arg3 Parameter for action parameter, defaults to 0.
 *   @result The return value of action if it was called, kIOReturnBadArgument if action is not defined, kIOReturnAborted if a disabled command gate is free()ed before being reenabled.
 */
	virtual IOReturn runAction(Action action,
	    void *arg0 = NULL, void *arg1 = NULL,
	    void *arg2 = NULL, void *arg3 = NULL);

#ifdef __BLOCKS__
/*! @function runActionBlock
 *   @abstract Single thread a call to an action with the target work loop.
 *   @discussion Client function that causes the given action to be called in
 *  a single threaded manner.  Beware the work loop's gate is recursive and command
 *  gates can cause direct or indirect re-entrancy.	 When the executing on a
 *  client's thread runAction will sleep until the work loop's gate opens for
 *  execution of client actions, the action is single threaded against all other
 *  work loop event sources.  If the command is disabled the attempt to run a command will be stalled until enable is called.
 *   @param action Block to be executed in the context of the work loop.
 *   @result The return value of action if it was called, kIOReturnBadArgument if action is not defined, kIOReturnAborted if a disabled command gate is free()ed before being reenabled.
 */
	IOReturn runActionBlock(ActionBlock action);
#endif /* __BLOCKS__ */

/*! @function attemptCommand
 *   @abstract Single thread a command with the target work loop.
 *   @discussion Client function that causes the current action to be called in
 *  a single threaded manner.  When the executing on a client's thread attemptCommand will fail if the work loop's gate is closed.
 *   @param arg0 Parameter for action of command gate, defaults to 0.
 *   @param arg1 Parameter for action of command gate, defaults to 0.
 *   @param arg2 Parameter for action of command gate, defaults to 0.
 *   @param arg3 Parameter for action of command gate, defaults to 0.
 *   @result kIOReturnSuccess if successful. kIOReturnNotPermitted if this event source is currently disabled, kIOReturnNoResources if no action available, kIOReturnCannotLock if lock attempt fails.
 */
	virtual IOReturn attemptCommand(void *arg0 = NULL, void *arg1 = NULL,
	    void *arg2 = NULL, void *arg3 = NULL);

/*! @function attemptAction
 *   @abstract Single thread a call to an action with the target work loop.
 *   @discussion Client function that causes the given action to be called in
 *  a single threaded manner.  Beware the work loop's gate is recursive and command
 *  gates can cause direct or indirect re-entrancy.	 When the executing on a
 *  client's thread attemptCommand will fail if the work loop's gate is closed.
 *   @param action Pointer to function to be executed in context of the work loop.
 *   @param arg0 Parameter for action parameter, defaults to 0.
 *   @param arg1 Parameter for action parameter, defaults to 0.
 *   @param arg2 Parameter for action parameter, defaults to 0.
 *   @param arg3 Parameter for action parameter, defaults to 0.
 *   @result kIOReturnSuccess if successful. kIOReturnBadArgument if action is not defined, kIOReturnNotPermitted if this event source is currently disabled, kIOReturnCannotLock if lock attempt fails.
 *
 */
	virtual IOReturn attemptAction(Action action,
	    void *arg0 = NULL, void *arg1 = NULL,
	    void *arg2 = NULL, void *arg3 = NULL);

/*! @function commandSleep
 *   @abstract Put a thread that is currently holding the command gate to sleep.
 *   @discussion Put a thread to sleep waiting for an event but release the gate first.  If the event occurs then the commandGate is closed before the function returns. If the thread does not hold the gate, panic.
 *   @param event Pointer to an address.
 *   @param interruptible THREAD_UNINT, THREAD_INTERRUPTIBLE or THREAD_ABORTSAFE.  THREAD_UNINT specifies that the sleep cannot be interrupted by a signal.  THREAD_INTERRUPTIBLE specifies that the sleep may be interrupted by a "kill -9" signal.  THREAD_ABORTSAFE (the default value) specifies that the sleep may be interrupted by any user signal.
 *   @result THREAD_AWAKENED - normal wakeup, THREAD_TIMED_OUT - timeout expired, THREAD_INTERRUPTED - interrupted, THREAD_RESTART - restart operation entirely. */
	virtual IOReturn commandSleep(void *event,
	    UInt32 interruptible = THREAD_ABORTSAFE);

/*! @function commandWakeup
 *   @abstract Wakeup one or more threads that are asleep on an event.
 *   @param event Pointer to an address.
 *   @param oneThread true to only wake up at most one thread, false otherwise. */
	virtual void commandWakeup(void *event, bool oneThread = false);

/*! @function disable
 *   @abstract Disable the command gate
 *   @discussion When a command gate is disabled all future calls to runAction and runCommand will stall until the gate is enable()d later.  This can be used to block client threads when a system sleep is requested.  The IOWorkLoop thread itself will never stall, even when making runAction/runCommand calls.  This call must be made from a gated context, to clear potential race conditions.  */
	virtual void disable() APPLE_KEXT_OVERRIDE;

/*! @function enable
 *   @abstract Enable command gate, this will unblock any blocked Commands and Actions.
 *   @discussion  Enable the command gate.  The attemptAction/attemptCommand calls will now be enabled and can succeeed.  Stalled runCommand/runAction calls will be woken up. */
	virtual void enable() APPLE_KEXT_OVERRIDE;

/*! @function commandSleep
 *   @abstract Put a thread that is currently holding the command gate to sleep.
 *   @discussion Put a thread to sleep waiting for an event but release the gate first.  If the event occurs or timeout occurs then the commandGate is closed before the function returns.  If the thread does not hold the gate, panic.
 *   @param event Pointer to an address.
 *       @param deadline Clock deadline to timeout the sleep.
 *   @param interruptible THREAD_UNINT, THREAD_INTERRUPTIBLE or THREAD_ABORTSAFE.  THREAD_UNINT specifies that the sleep cannot be interrupted by a signal.  THREAD_INTERRUPTIBLE specifies that the sleep may be interrupted by a "kill -9" signal.  THREAD_ABORTSAFE specifies that the sleep may be interrupted by any user signal.
 *   @result THREAD_AWAKENED - normal wakeup, THREAD_TIMED_OUT - timeout expired, THREAD_INTERRUPTED - interrupted, THREAD_RESTART - restart operation entirely. */
	virtual IOReturn commandSleep(void *event,
	    AbsoluteTime deadline,
	    UInt32 interruptible);

private:
#if __LP64__
	OSMetaClassDeclareReservedUnused(IOCommandGate, 0);
#else
	OSMetaClassDeclareReservedUsed(IOCommandGate, 0);
#endif
	OSMetaClassDeclareReservedUnused(IOCommandGate, 1);
	OSMetaClassDeclareReservedUnused(IOCommandGate, 2);
	OSMetaClassDeclareReservedUnused(IOCommandGate, 3);
	OSMetaClassDeclareReservedUnused(IOCommandGate, 4);
	OSMetaClassDeclareReservedUnused(IOCommandGate, 5);
	OSMetaClassDeclareReservedUnused(IOCommandGate, 6);
	OSMetaClassDeclareReservedUnused(IOCommandGate, 7);
};

#endif /* !_IOKIT_IOCOMMANDGATE_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	*/
1c79356b A	28	/*[
0a7de745 A	29	* 1999-8-10 Godfrey van der Linden(gvdl)
	30	* Created.
	31	* ]*/
1c79356b A	32	/! @language embedded-c++ /
	33
	34	#ifndef _IOKIT_IOCOMMANDGATE_H
	35	#define _IOKIT_IOCOMMANDGATE_H
	36
	37	#include <IOKit/IOEventSource.h>
	38
	39	/*!
0a7de745 A	40	* @class IOCommandGate : public IOEventSource
	41	* @abstract Single-threaded work loop client request mechanism.
	42	* @discussion An IOCommandGate instance is an extremely lightweight mechanism
	43	* that executes an action on the driver's work loop. Although the code does not
	44	* technically execute on the work loop itself, a single-threaded work loop semantic
	45	* is maintained for this event source using the work loop gate. The command gate
	46	* tests for a potential self dead lock by checking if the runCommand request is
	47	* made from the work loop's thread, it doesn't check for a mutual dead lock though
	48	* where a pair of work loop's dead lock each other.
	49	* <br><br>
	50	* The IOCommandGate is a lighter weight version of the IOCommandQueue and
	51	* should be used in preference. Generally use a command queue whenever you need a
	52	* client to submit a request to a work loop. A typical command gate action would
	53	* check if the hardware is active, if so it will add the request to a pending
	54	* queue internal to the device or the device's family. Otherwise if the hardware
	55	* is inactive then this request can be acted upon immediately.
	56	* <br><br>
	57	* CAUTION: The runAction, runCommand, and attemptCommand functions cannot be called from an interrupt context.
	58	*
	59	*/
1c79356b A	60	class IOCommandGate : public IOEventSource
1c79356b A	61	{
cb323159	62	OSDeclareDefaultStructors(IOCommandGate);
1c79356b A	63
	64	public:
	65	/*!
0a7de745 A	66	* @typedef Action
	67	* @discussion Type and arguments of callout C function that is used when
	68	* a runCommand is executed by a client. Cast to this type when you want a C++
	69	* member function to be used. Note the arg1 - arg3 parameters are straight pass
	70	* through from the runCommand to the action callout.
	71	* @param owner
	72	* Target of the function, can be used as a refcon. The owner is set
	73	* during initialisation of the IOCommandGate instance. Note if a C++ function
	74	* was specified this parameter is implicitly the first paramter in the target
	75	* member function's parameter list.
	76	* @param arg0 Argument to action from run operation.
	77	* @param arg1 Argument to action from run operation.
	78	* @param arg2 Argument to action from run operation.
	79	* @param arg3 Argument to action from run operation.
	80	*/
	81	typedef IOReturn (Action)(OSObject owner,
	82	void arg0, void arg1,
	83	void arg2, void arg3);
1c79356b A	84
1c79356b A	85	protected:
1c79356b A	86
1c79356b A	87	/*! @struct ExpansionData
0a7de745 A	88	* @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future.
	89	*/
	90	struct ExpansionData { };
1c79356b A	91
1c79356b A	92	/*! @var reserved
0a7de745 A	93	* Reserved for future use. (Internal use only) */
	94	APPLE_KEXT_WSHADOW_PUSH;
	95	ExpansionData *reserved;
	96	APPLE_KEXT_WSHADOW_POP;
1c79356b A	97
	98	public:
	99	/*! @function commandGate
0a7de745 A	100	* @abstract Factory method to create and initialise an IOCommandGate, See $link init.
0a7de745 A	101	* @result Returns a pointer to the new command gate if sucessful, 0 otherwise. */
cb323159	102	static IOCommandGate commandGate(OSObject owner, Action action = NULL);
1c79356b A	103
1c79356b A	104	/*! @function init
0a7de745 A	105	* @abstract Class initialiser.
	106	* @discussion Initialiser for IOCommandGate operates only on newly 'newed'
	107	* objects. Shouldn't be used to re-init an existing instance.
	108	* @param owner Owner of this, newly created, instance of the IOCommandGate. This argument will be used as the first parameter in the action callout.
	109	* @param action
	110	* Pointer to a C function that is called whenever a client of the
	111	* IOCommandGate calls runCommand. NB Can be a C++ member function but caller
	112	* must cast the member function to $link IOCommandGate::Action and they will get a
	113	* compiler warning. Defaults to zero, see $link IOEventSource::setAction.
	114	* @result True if inherited classes initialise successfully. */
cb323159	115	virtual bool init(OSObject *owner, Action action = NULL);
0a7de745 A	116
	117	// Superclass overrides
	118	virtual void free() APPLE_KEXT_OVERRIDE;
	119	virtual void setWorkLoop(IOWorkLoop *inWorkLoop) APPLE_KEXT_OVERRIDE;
0c530ab8	120
1c79356b	121	/*! @function runCommand
0a7de745 A	122	* @abstract Single thread a command with the target work loop.
	123	* @discussion Client function that causes the current action to be called in
	124	* a single threaded manner. Beware the work loop's gate is recursive and command
	125	* gates can cause direct or indirect re-entrancy. When the executing on a
	126	* client's thread runCommand will sleep until the work loop's gate opens for
	127	* execution of client actions, the action is single threaded against all other
	128	* work loop event sources. If the command is disabled the attempt to run a command will be stalled until enable is called.
	129	* @param arg0 Parameter for action of command gate, defaults to 0.
	130	* @param arg1 Parameter for action of command gate, defaults to 0.
	131	* @param arg2 Parameter for action of command gate, defaults to 0.
	132	* @param arg3 Parameter for action of command gate, defaults to 0.
	133	* @result kIOReturnSuccess if successful. kIOReturnAborted if a disabled command gate is free()ed before being reenabled, kIOReturnNoResources if no action available.
	134	*/
cb323159 A	135	virtual IOReturn runCommand(void arg0 = NULL, void arg1 = NULL,
cb323159 A	136	void arg2 = NULL, void arg3 = NULL);
1c79356b A	137
1c79356b A	138	/*! @function runAction
0a7de745 A	139	* @abstract Single thread a call to an action with the target work loop.
	140	* @discussion Client function that causes the given action to be called in
	141	* a single threaded manner. Beware the work loop's gate is recursive and command
	142	* gates can cause direct or indirect re-entrancy. When the executing on a
	143	* client's thread runAction will sleep until the work loop's gate opens for
	144	* execution of client actions, the action is single threaded against all other
	145	* work loop event sources. If the command is disabled the attempt to run a command will be stalled until enable is called.
	146	* @param action Pointer to function to be executed in the context of the work loop.
	147	* @param arg0 Parameter for action parameter, defaults to 0.
	148	* @param arg1 Parameter for action parameter, defaults to 0.
	149	* @param arg2 Parameter for action parameter, defaults to 0.
	150	* @param arg3 Parameter for action parameter, defaults to 0.
	151	* @result The return value of action if it was called, kIOReturnBadArgument if action is not defined, kIOReturnAborted if a disabled command gate is free()ed before being reenabled.
	152	*/
	153	virtual IOReturn runAction(Action action,
cb323159 A	154	void arg0 = NULL, void arg1 = NULL,
cb323159 A	155	void arg2 = NULL, void arg3 = NULL);
1c79356b	156
d9a64523 A	157	#ifdef __BLOCKS__
d9a64523 A	158	/*! @function runActionBlock
0a7de745 A	159	* @abstract Single thread a call to an action with the target work loop.
	160	* @discussion Client function that causes the given action to be called in
	161	* a single threaded manner. Beware the work loop's gate is recursive and command
	162	* gates can cause direct or indirect re-entrancy. When the executing on a
	163	* client's thread runAction will sleep until the work loop's gate opens for
	164	* execution of client actions, the action is single threaded against all other
	165	* work loop event sources. If the command is disabled the attempt to run a command will be stalled until enable is called.
	166	* @param action Block to be executed in the context of the work loop.
	167	* @result The return value of action if it was called, kIOReturnBadArgument if action is not defined, kIOReturnAborted if a disabled command gate is free()ed before being reenabled.
	168	*/
	169	IOReturn runActionBlock(ActionBlock action);
d9a64523 A	170	#endif /* __BLOCKS__ */
d9a64523 A	171
1c79356b	172	/*! @function attemptCommand
0a7de745 A	173	* @abstract Single thread a command with the target work loop.
	174	* @discussion Client function that causes the current action to be called in
	175	* a single threaded manner. When the executing on a client's thread attemptCommand will fail if the work loop's gate is closed.
	176	* @param arg0 Parameter for action of command gate, defaults to 0.
	177	* @param arg1 Parameter for action of command gate, defaults to 0.
	178	* @param arg2 Parameter for action of command gate, defaults to 0.
	179	* @param arg3 Parameter for action of command gate, defaults to 0.
	180	* @result kIOReturnSuccess if successful. kIOReturnNotPermitted if this event source is currently disabled, kIOReturnNoResources if no action available, kIOReturnCannotLock if lock attempt fails.
	181	*/
cb323159 A	182	virtual IOReturn attemptCommand(void arg0 = NULL, void arg1 = NULL,
cb323159 A	183	void arg2 = NULL, void arg3 = NULL);
1c79356b A	184
1c79356b A	185	/*! @function attemptAction
0a7de745 A	186	* @abstract Single thread a call to an action with the target work loop.
	187	* @discussion Client function that causes the given action to be called in
	188	* a single threaded manner. Beware the work loop's gate is recursive and command
	189	* gates can cause direct or indirect re-entrancy. When the executing on a
	190	* client's thread attemptCommand will fail if the work loop's gate is closed.
	191	* @param action Pointer to function to be executed in context of the work loop.
	192	* @param arg0 Parameter for action parameter, defaults to 0.
	193	* @param arg1 Parameter for action parameter, defaults to 0.
	194	* @param arg2 Parameter for action parameter, defaults to 0.
	195	* @param arg3 Parameter for action parameter, defaults to 0.
	196	* @result kIOReturnSuccess if successful. kIOReturnBadArgument if action is not defined, kIOReturnNotPermitted if this event source is currently disabled, kIOReturnCannotLock if lock attempt fails.
	197	*
	198	*/
	199	virtual IOReturn attemptAction(Action action,
cb323159 A	200	void arg0 = NULL, void arg1 = NULL,
cb323159 A	201	void arg2 = NULL, void arg3 = NULL);
0a7de745 A	202
	203	/*! @function commandSleep
	204	* @abstract Put a thread that is currently holding the command gate to sleep.
	205	* @discussion Put a thread to sleep waiting for an event but release the gate first. If the event occurs then the commandGate is closed before the function returns. If the thread does not hold the gate, panic.
	206	* @param event Pointer to an address.
	207	* @param interruptible THREAD_UNINT, THREAD_INTERRUPTIBLE or THREAD_ABORTSAFE. THREAD_UNINT specifies that the sleep cannot be interrupted by a signal. THREAD_INTERRUPTIBLE specifies that the sleep may be interrupted by a "kill -9" signal. THREAD_ABORTSAFE (the default value) specifies that the sleep may be interrupted by any user signal.
	208	* @result THREAD_AWAKENED - normal wakeup, THREAD_TIMED_OUT - timeout expired, THREAD_INTERRUPTED - interrupted, THREAD_RESTART - restart operation entirely. */
	209	virtual IOReturn commandSleep(void *event,
	210	UInt32 interruptible = THREAD_ABORTSAFE);
1c79356b A	211
1c79356b A	212	/*! @function commandWakeup
0a7de745 A	213	* @abstract Wakeup one or more threads that are asleep on an event.
	214	* @param event Pointer to an address.
	215	* @param oneThread true to only wake up at most one thread, false otherwise. */
	216	virtual void commandWakeup(void *event, bool oneThread = false);
1c79356b	217
0c530ab8	218	/*! @function disable
0a7de745 A	219	* @abstract Disable the command gate
	220	* @discussion When a command gate is disabled all future calls to runAction and runCommand will stall until the gate is enable()d later. This can be used to block client threads when a system sleep is requested. The IOWorkLoop thread itself will never stall, even when making runAction/runCommand calls. This call must be made from a gated context, to clear potential race conditions. */
	221	virtual void disable() APPLE_KEXT_OVERRIDE;
0c530ab8 A	222
0c530ab8 A	223	/*! @function enable
0a7de745 A	224	* @abstract Enable command gate, this will unblock any blocked Commands and Actions.
	225	* @discussion Enable the command gate. The attemptAction/attemptCommand calls will now be enabled and can succeeed. Stalled runCommand/runAction calls will be woken up. */
	226	virtual void enable() APPLE_KEXT_OVERRIDE;
	227
	228	/*! @function commandSleep
	229	* @abstract Put a thread that is currently holding the command gate to sleep.
	230	* @discussion Put a thread to sleep waiting for an event but release the gate first. If the event occurs or timeout occurs then the commandGate is closed before the function returns. If the thread does not hold the gate, panic.
	231	* @param event Pointer to an address.
	232	* @param deadline Clock deadline to timeout the sleep.
	233	* @param interruptible THREAD_UNINT, THREAD_INTERRUPTIBLE or THREAD_ABORTSAFE. THREAD_UNINT specifies that the sleep cannot be interrupted by a signal. THREAD_INTERRUPTIBLE specifies that the sleep may be interrupted by a "kill -9" signal. THREAD_ABORTSAFE specifies that the sleep may be interrupted by any user signal.
	234	* @result THREAD_AWAKENED - normal wakeup, THREAD_TIMED_OUT - timeout expired, THREAD_INTERRUPTED - interrupted, THREAD_RESTART - restart operation entirely. */
	235	virtual IOReturn commandSleep(void *event,
	236	AbsoluteTime deadline,
	237	UInt32 interruptible);
b0d623f7	238
1c79356b	239	private:
b0d623f7	240	#if __LP64__
0a7de745	241	OSMetaClassDeclareReservedUnused(IOCommandGate, 0);
b0d623f7	242	#else
0a7de745	243	OSMetaClassDeclareReservedUsed(IOCommandGate, 0);
b0d623f7	244	#endif
0a7de745 A	245	OSMetaClassDeclareReservedUnused(IOCommandGate, 1);
	246	OSMetaClassDeclareReservedUnused(IOCommandGate, 2);
	247	OSMetaClassDeclareReservedUnused(IOCommandGate, 3);
	248	OSMetaClassDeclareReservedUnused(IOCommandGate, 4);
	249	OSMetaClassDeclareReservedUnused(IOCommandGate, 5);
	250	OSMetaClassDeclareReservedUnused(IOCommandGate, 6);
	251	OSMetaClassDeclareReservedUnused(IOCommandGate, 7);
1c79356b A	252	};
	253
	254	#endif /* !_IOKIT_IOCOMMANDGATE_H */