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

/*
 * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * The contents of this file constitute Original Code as defined in and
 * are subject to the Apple Public Source License Version 1.1 (the
 * "License").  You may not use this file except in compliance with the
 * License.  Please obtain a copy of the License at
 * http://www.apple.com/publicsource and read it before using this file.
 * 
 * This 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 OR NON-INFRINGEMENT.  Please see the
 * License for the specific language governing rights and limitations
 * under the License.
 * 
 * @APPLE_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 light way mechanism
that executes an action on the driver's work-loop.  'On the work-loop' is
actually a lie but the work-loop single threaded semantic is maintained for this
event source.  Using the work-loop gate rather than execution by the workloop.
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 doens'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 and runCommand functions can not 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:
/*!
    @function checkForWork
    @abstract Not used, $link IOEventSource::checkForWork(). */
    virtual bool checkForWork();

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

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

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

/*! @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.
    @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.
*/
    virtual IOReturn runCommand(void *arg0 = 0, void *arg1 = 0,
				void *arg2 = 0, void *arg3 = 0);

/*! @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.
    @param action Pointer to function to be executed in work-loop context.
    @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.
*/
    virtual IOReturn runAction(Action action,
			       void *arg0 = 0, void *arg1 = 0,
			       void *arg2 = 0, void *arg3 = 0);

/*! @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.  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 open.
    @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 = 0, void *arg1 = 0,
                                    void *arg2 = 0, void *arg3 = 0);

/*! @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 open.
    @param action Pointer to function to be executed in work-loop context.
    @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 = 0, void *arg1 = 0,
                                   void *arg2 = 0, void *arg3 = 0);

/*! @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  returns.
    @param event Pointer to an address.
    @param interruptible THREAD_UNINT, THREAD_INTERRUPTIBLE or THREAD_ABORTSAFE,  defaults to THREAD_ABORTSAFE.
    @result THREAD_AWAKENED - normal wakeup, THREAD_TIMED_OUT - timeout expired, THREAD_INTERRUPTED - interrupted by clear_wait, THREAD_RESTART - restart operation entirely, kIOReturnNotPermitted if the calling thread does not hold the command gate. */
    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 onlyOneThread true to only wake up at most one thread, false otherwise. */
    virtual void commandWakeup(void *event, bool oneThread = false);

private:
    OSMetaClassDeclareReservedUnused(IOCommandGate, 0);
    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 A	1	/*
	2	* Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
	3	*
	4	* @APPLE_LICENSE_HEADER_START@
	5	*
e5568f75 A	6	* The contents of this file constitute Original Code as defined in and
	7	* are subject to the Apple Public Source License Version 1.1 (the
	8	* "License"). You may not use this file except in compliance with the
	9	* License. Please obtain a copy of the License at
	10	* http://www.apple.com/publicsource and read it before using this file.
1c79356b	11	*
e5568f75 A	12	* This Original Code and all software distributed under the License are
e5568f75 A	13	* distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
1c79356b A	14	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
1c79356b A	15	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
e5568f75 A	16	* FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the
	17	* License for the specific language governing rights and limitations
	18	* under the License.
1c79356b A	19	*
	20	* @APPLE_LICENSE_HEADER_END@
	21	*/
	22	/*[
	23	1999-8-10 Godfrey van der Linden(gvdl)
	24	Created.
	25	]*/
	26	/! @language embedded-c++ /
	27
	28	#ifndef _IOKIT_IOCOMMANDGATE_H
	29	#define _IOKIT_IOCOMMANDGATE_H
	30
	31	#include <IOKit/IOEventSource.h>
	32
	33	/*!
	34	@class IOCommandGate : public IOEventSource
	35	@abstract Single-threaded work-loop client request mechanism.
	36	@discussion An IOCommandGate instance is an extremely light way mechanism
	37	that executes an action on the driver's work-loop. 'On the work-loop' is
	38	actually a lie but the work-loop single threaded semantic is maintained for this
	39	event source. Using the work-loop gate rather than execution by the workloop.
	40	The command gate tests for a potential self dead lock by checking if the
	41	runCommand request is made from the work-loop's thread, it doens't check for a
	42	mutual dead lock though where a pair of work loop's dead lock each other.
	43	<br><br>
	44	The IOCommandGate is a lighter weight version of the IOCommandQueue and
	45	should be used in preference. Generally use a command queue whenever you need a
	46	client to submit a request to a work loop. A typical command gate action would
	47	check if the hardware is active, if so it will add the request to a pending
	48	queue internal to the device or the device's family. Otherwise if the hardware
	49	is inactive then this request can be acted upon immediately.
	50	<br><br>
	51	CAUTION: The runAction and runCommand functions can not be called from an interrupt context.
	52
	53	*/
	54	class IOCommandGate : public IOEventSource
	55	{
	56	OSDeclareDefaultStructors(IOCommandGate)
	57
	58	public:
	59	/*!
	60	@typedef Action
	61	@discussion Type and arguments of callout C function that is used when
	62	a runCommand is executed by a client. Cast to this type when you want a C++
	63	member function to be used. Note the arg1 - arg3 parameters are straight pass
	64	through from the runCommand to the action callout.
	65	@param owner
	66	Target of the function, can be used as a refcon. The owner is set
	67	during initialisation of the IOCommandGate instance. Note if a C++ function
	68	was specified this parameter is implicitly the first paramter in the target
	69	member function's parameter list.
	70	@param arg0 Argument to action from run operation.
	71	@param arg1 Argument to action from run operation.
	72	@param arg2 Argument to action from run operation.
	73	@param arg3 Argument to action from run operation.
	74	*/
	75	typedef IOReturn (Action)(OSObject owner,
	76	void arg0, void arg1,
	77	void arg2, void arg3);
	78
	79	protected:
	80	/*!
	81	@function checkForWork
	82	@abstract Not used, $link IOEventSource::checkForWork(). */
83	virtual bool checkForWork();
84
85	/*! @struct ExpansionData
86	@discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future.
87	*/
88	struct ExpansionData { };
89
90	/*! @var reserved
91	Reserved for future use. (Internal use only) */
92	ExpansionData *reserved;
93
94	public:
95	/*! @function commandGate
96	@abstract Factory method to create and initialise an IOCommandGate, See $link init.
97	@result Returns a pointer to the new command gate if sucessful, 0 otherwise. */
98	static IOCommandGate commandGate(OSObject owner, Action action = 0);
99
100	/*! @function init
101	@abstract Class initialiser.
102	@discussion Initialiser for IOCommandGate operates only on newly 'newed'
103	objects. Shouldn't be used to re-init an existing instance.
104	@param owner Owner of this, newly created, instance of the IOCommandGate. This argument will be used as the first parameter in the action callout.
105	@param action
106	Pointer to a C function that is called whenever a client of the
107	IOCommandGate calls runCommand. NB Can be a C++ member function but caller
108	must cast the member function to $link IOCommandGate::Action and they will get a
109	compiler warning. Defaults to zero, see $link IOEventSource::setAction.
110	@result True if inherited classes initialise successfully. */
111	virtual bool init(OSObject *owner, Action action = 0);
112
113	/*! @function runCommand
114	@abstract Single thread a command with the target work-loop.
115	@discussion Client function that causes the current action to be called in
116	a single threaded manner. Beware the work-loop's gate is recursive and command
117	gates can cause direct or indirect re-entrancy. When the executing on a
118	client's thread runCommand will sleep until the work-loop's gate opens for
119	execution of client actions, the action is single threaded against all other
120	work-loop event sources.
121	@param arg0 Parameter for action of command gate, defaults to 0.
122	@param arg1 Parameter for action of command gate, defaults to 0.
123	@param arg2 Parameter for action of command gate, defaults to 0.
124	@param arg3 Parameter for action of command gate, defaults to 0.
125	@result kIOReturnSuccess if successful. kIOReturnNotPermitted if this
126	event source is currently disabled, kIOReturnNoResources if no action available.
127	*/
128	virtual IOReturn runCommand(void arg0 = 0, void arg1 = 0,
129	void arg2 = 0, void arg3 = 0);
130
131	/*! @function runAction
132	@abstract Single thread a call to an action with the target work-loop.
133	@discussion Client function that causes the given action to be called in
134	a single threaded manner. Beware the work-loop's gate is recursive and command
135	gates can cause direct or indirect re-entrancy. When the executing on a
0b4e3aa0	136	client's thread runAction will sleep until the work-loop's gate opens for
1c79356b A	137	execution of client actions, the action is single threaded against all other
	138	work-loop event sources.
	139	@param action Pointer to function to be executed in work-loop context.
	140	@param arg0 Parameter for action parameter, defaults to 0.
	141	@param arg1 Parameter for action parameter, defaults to 0.
	142	@param arg2 Parameter for action parameter, defaults to 0.
	143	@param arg3 Parameter for action parameter, defaults to 0.
	144	@result kIOReturnSuccess if successful. kIOReturnBadArgument if action is not defined, kIOReturnNotPermitted if this event source is currently disabled.
	145	*/
	146	virtual IOReturn runAction(Action action,
	147	void arg0 = 0, void arg1 = 0,
	148	void arg2 = 0, void arg3 = 0);
	149
	150	/*! @function attemptCommand
	151	@abstract Single thread a command with the target work-loop.
	152	@discussion Client function that causes the current action to be called in
	153	a single threaded manner. Beware the work-loop's gate is recursive and command
	154	gates can cause direct or indirect re-entrancy. When the executing on a
	155	client's thread attemptCommand will fail if the work-loop's gate is open.
	156	@param arg0 Parameter for action of command gate, defaults to 0.
	157	@param arg1 Parameter for action of command gate, defaults to 0.
	158	@param arg2 Parameter for action of command gate, defaults to 0.
	159	@param arg3 Parameter for action of command gate, defaults to 0.
	160	@result kIOReturnSuccess if successful. kIOReturnNotPermitted if this event source is currently disabled, kIOReturnNoResources if no action available, kIOReturnCannotLock if lock attempt fails.
	161	*/
	162	virtual IOReturn attemptCommand(void arg0 = 0, void arg1 = 0,
	163	void arg2 = 0, void arg3 = 0);
	164
	165	/*! @function attemptAction
	166	@abstract Single thread a call to an action with the target work-loop.
	167	@discussion Client function that causes the given action to be called in
	168	a single threaded manner. Beware the work-loop's gate is recursive and command
	169	gates can cause direct or indirect re-entrancy. When the executing on a
	170	client's thread attemptCommand will fail if the work-loop's gate is open.
	171	@param action Pointer to function to be executed in work-loop context.
	172	@param arg0 Parameter for action parameter, defaults to 0.
	173	@param arg1 Parameter for action parameter, defaults to 0.
	174	@param arg2 Parameter for action parameter, defaults to 0.
	175	@param arg3 Parameter for action parameter, defaults to 0.
	176	@result kIOReturnSuccess if successful. kIOReturnBadArgument if action is not defined, kIOReturnNotPermitted if this event source is currently disabled, kIOReturnCannotLock if lock attempt fails.
	177
	178	*/
	179	virtual IOReturn attemptAction(Action action,
	180	void arg0 = 0, void arg1 = 0,
	181	void arg2 = 0, void arg3 = 0);
	182
	183	/*! @function commandSleep
	184	@abstract Put a thread that is currently holding the command gate to sleep.
	185	@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 returns.
	186	@param event Pointer to an address.
	187	@param interruptible THREAD_UNINT, THREAD_INTERRUPTIBLE or THREAD_ABORTSAFE, defaults to THREAD_ABORTSAFE.
	188	@result THREAD_AWAKENED - normal wakeup, THREAD_TIMED_OUT - timeout expired, THREAD_INTERRUPTED - interrupted by clear_wait, THREAD_RESTART - restart operation entirely, kIOReturnNotPermitted if the calling thread does not hold the command gate. */
	189	virtual IOReturn commandSleep(void *event,
	190	UInt32 interruptible = THREAD_ABORTSAFE);
	191
	192	/*! @function commandWakeup
	193	@abstract Wakeup one or more threads that are asleep on an event.
	194	@param event Pointer to an address.
	195	@param onlyOneThread true to only wake up at most one thread, false otherwise. */
	196	virtual void commandWakeup(void *event, bool oneThread = false);
	197
	198	private:
	199	OSMetaClassDeclareReservedUnused(IOCommandGate, 0);
	200	OSMetaClassDeclareReservedUnused(IOCommandGate, 1);
201	OSMetaClassDeclareReservedUnused(IOCommandGate, 2);
202	OSMetaClassDeclareReservedUnused(IOCommandGate, 3);
203	OSMetaClassDeclareReservedUnused(IOCommandGate, 4);
204	OSMetaClassDeclareReservedUnused(IOCommandGate, 5);
205	OSMetaClassDeclareReservedUnused(IOCommandGate, 6);
206	OSMetaClassDeclareReservedUnused(IOCommandGate, 7);
207	};
208
209	#endif /* !_IOKIT_IOCOMMANDGATE_H */