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