1/*
2 * Copyright (c) 1998-2007 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/*
29Copyright (c) 1998 Apple Computer, Inc.	 All rights reserved.
30HISTORY
31    1998-7-13	Godfrey van der Linden(gvdl)
32	Created.
33    1998-10-30	Godfrey van der Linden(gvdl)
34	Converted to C++
35*/
36
37#ifndef __IOKIT_IOWORKLOOP_H
38#define __IOKIT_IOWORKLOOP_H
39
40#include <libkern/c++/OSObject.h>
41#include <IOKit/IOReturn.h>
42#include <IOKit/IOLib.h>
43#include <IOKit/IOLocks.h>
44
45#include <IOKit/system.h>
46
47class IOEventSource;
48class IOTimerEventSource;
49class IOCommandGate;
50
51/*! @class IOWorkLoop
52    @discussion An IOWorkLoop is a thread of control that is intended to be used to provide single threaded access to hardware.  This class has no knowledge of the nature and type of the events that it marshals and forwards.  When a device driver successfully starts (see IOService::start), it is expected to create the event sources it will need to receive events.  Then a work loop is initialized and the events are added to the work loop for monitoring.  In general this set up will be automated by the family superclass of the specific device.
53<br><br>
54	The thread main method walks the event source linked list and messages each one requesting a work check.  At this point each event source is expected to notify its registered owner that the event has occurred.  After each event has been walked and each indicates that another loop isn't required (by setting the 'more' flag to false) the thread will go to sleep on a signaling semaphore.
55<br><br>
56	When an event source is registered with a work loop it is informed of the semaphore to use to wake up the loop.
57*/
58class IOWorkLoop : public OSObject
59{
60    OSDeclareDefaultStructors(IOWorkLoop)
61
62public:
63/*!
64    @typedef Action
65    @discussion Type and arguments of callout C function that is used when
66a runCommand is executed by a client.  Cast to this type when you want a C++
67member function to be used.  Note the arg1 - arg3 parameters are straight pass
68through from the runCommand to the action callout.
69    @param target
70	Target of the function, can be used as a refcon.  Note if a C++ function
71was specified, this parameter is implicitly the first parameter in the target
72member function's parameter list.
73    @param arg0 Argument to action from run operation.
74    @param arg1 Argument to action from run operation.
75    @param arg2 Argument to action from run operation.
76    @param arg3 Argument to action from run operation.
77*/
78    typedef IOReturn (*Action)(OSObject *target,
79			       void *arg0, void *arg1,
80			       void *arg2, void *arg3);
81    enum {
82	kPreciousStack = 0x00000001
83    };
84
85private:
86/*! @function threadMainContinuation
87    @abstract Static function that calls the threadMain function.
88*/
89    static void threadMainContinuation(IOWorkLoop *self);
90
91protected:
92
93/*! @typedef maintCommandEnum
94    @discussion Enumeration of commands that _maintCommand can deal with.
95    @constant mAddEvent Used to tag a Remove event source command.
96    @constant mRemoveEvent Used to tag a Remove event source command.
97*/
98    typedef enum { mAddEvent, mRemoveEvent } maintCommandEnum;
99
100/*! @var gateLock
101    Mutual exclusion lock that is used by close and open Gate functions.
102    This is a recursive lock, which allows multiple layers of code to share a single IOWorkLoop without deadlock.  This is common in IOKit since threads of execution tend to follow the service plane in the IORegistry, and multiple objects along the call path may acquire the gate for the same (shared) workloop.
103*/
104    IORecursiveLock *gateLock;
105
106/*! @var eventChain
107    Pointer to first event source in linked list.
108*/
109    IOEventSource *eventChain;
110
111/*! @var controlG
112    Internal control gate to maintain event system.
113*/
114    IOCommandGate *controlG;
115
116/*! @var workToDoLock
117    The spin lock that is used to guard the 'workToDo' variable.
118*/
119    IOSimpleLock *workToDoLock;
120
121/*! @var workThread
122    Work loop thread.
123*/
124    IOThread workThread;
125
126/*! @var workToDo
127    Used to to indicate that an interrupt has fired and needs to be processed.
128*/
129    volatile bool workToDo;
130
131/*! @var loopRestart
132    Set if an event chain has been changed and the system has to be rechecked from start.  (Internal use only)
133*/
134    bool loopRestart;
135
136/*! @struct ExpansionData
137    @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future.
138*/
139    struct ExpansionData {
140	IOOptionBits options;
141    };
142
143/*! @var reserved
144    Reserved for future use.  (Internal use only)
145*/
146    ExpansionData *reserved;
147
148/*! @function _maintRequest
149    @abstract Synchronous implementation of addEventSource and removeEventSource functions.
150    @discussion This function implements the commands as defined in the maintCommandEnum.  It can be subclassed but it isn't an external API in the usual sense.  A subclass implementation of _maintRequest would be called synchronously with respect to the work loop and it should be implemented in the usual way that an ioctl would be.
151    @return kIOReturnUnsupported if the command given is not implemented, kIOReturnSuccess otherwise.
152*/
153    virtual IOReturn _maintRequest(void *command, void *data, void *, void *);
154
155/*! @function free
156    @discussion Mandatory free of the object independent of the current retain count.  If the work loop is running, this method will not return until the thread has successfully terminated.  Each event source in the chain will be released and the working semaphore will be destroyed.
157<br><br>
158	If the client has some outstanding requests on an event they will never be informed of completion.  If an external thread is blocked on any of the event sources they will be awakened with a KERN_INTERUPTED status.
159*/
160    virtual void free();
161
162/*! @function threadMain
163    @discussion Work loop threads main function.  This function consists of 3
164    loops: the outermost loop is the semaphore clear and wait loop, the middle
165    loop terminates when there is no more work, and the inside loop walks the
166    event list calling the checkForWork method in each event source.  If an
167    event source has more work to do, it can set the more flag and the middle
168    loop will repeat.  When no more work is outstanding the outermost will
169    sleep until an event is signalled.
170*/
171    virtual void threadMain();
172
173public:
174
175/*! @function workLoop
176    @abstract Factory member function to construct and intialize a work loop.
177    @result Returns a workLoop instance if constructed successfully, 0 otherwise.
178*/
179    static IOWorkLoop *workLoop();
180
181/*! @function workLoopWithOptions(IOOptionBits options)
182    @abstract Factory member function to constuct and intialize a work loop.
183    @param options Options - kPreciousStack to avoid stack deallocation on paging path.
184    @result Returns a workLoop instance if constructed successfully, 0 otherwise.
185*/
186    static IOWorkLoop *workLoopWithOptions(IOOptionBits options);
187
188/*! @function init
189    @discussion Initializes an instance of the workloop.  This method creates and initializes the signaling semaphore, the controller gate lock, and spawns the thread that will continue executing.
190    @result Returns true if initialized successfully, false otherwise.
191*/
192    virtual bool init();
193
194/*! @function getThread
195    @abstract Gets the workThread.
196    @result Returns workThread.
197*/
198    virtual IOThread getThread() const;
199
200/*! @function onThread
201    @abstract Is the current execution context on the work thread?
202    @result Returns true if IOThreadSelf() == workThread.
203*/
204    virtual bool onThread() const;
205
206/*! @function inGate
207    @abstract Is the current execution context holding the work-loop's gate?
208    @result Returns true if IOThreadSelf() is gate holder.
209*/
210    virtual bool inGate() const;
211
212/*! @function addEventSource
213    @discussion Add an event source to be monitored by the work loop.  This function does not return until the work loop has acknowledged the arrival of the new event source.  When a new event has been added the threadMain will always restart its loop and check all outstanding events.  The event source is retained by the work loop.
214    @param newEvent Pointer to IOEventSource subclass to add.
215    @result Always returns kIOReturnSuccess.
216*/
217    virtual IOReturn addEventSource(IOEventSource *newEvent);
218
219/*! @function removeEventSource
220    @discussion Remove an event source from the work loop.  This function does not return until the work loop has acknowledged the removal of the event source.  When an event has been removed the threadMain will always restart its loop and check all outstanding events.  The event source will be released before return.
221    @param toRemove Pointer to IOEventSource subclass to remove.
222    @result Returns kIOReturnSuccess if successful, kIOReturnBadArgument if toRemove couldn't be found.
223*/
224    virtual IOReturn removeEventSource(IOEventSource *toRemove);
225
226/*! @function enableAllEventSources
227    @abstract Calls enable() in all event sources.
228    @discussion For all event sources in eventChain, call enable() function.  See IOEventSource::enable().
229*/
230    virtual void enableAllEventSources() const;
231
232/*! @function disableAllEventSources
233    @abstract Calls disable() in all event sources.
234    @discussion For all event sources in eventChain, call disable() function.  See IOEventSource::disable().
235*/
236    virtual void disableAllEventSources() const;
237
238/*! @function enableAllInterrupts
239    @abstract Calls enable() in all interrupt event sources.
240    @discussion For all event sources (ES) for which IODynamicCast(IOInterruptEventSource, ES) is valid, in eventChain call enable() function.  See IOEventSource::enable().
241*/
242    virtual void enableAllInterrupts() const;
243
244/*! @function disableAllInterrupts
245    @abstract Calls disable() in all interrupt event sources.
246    @discussion For all event sources (ES) for which IODynamicCast(IOInterruptEventSource, ES) is valid,  in eventChain call disable() function.  See IOEventSource::disable().
247*/
248    virtual void disableAllInterrupts() const;
249
250
251protected:
252    // Internal APIs used by event sources to control the thread
253    friend class IOEventSource;
254    friend class IOTimerEventSource;
255    virtual void signalWorkAvailable();
256    virtual void openGate();
257    virtual void closeGate();
258    virtual bool tryCloseGate();
259    virtual int  sleepGate(void *event, UInt32 interuptibleType);
260    virtual void wakeupGate(void *event, bool oneThread);
261
262public:
263    /* methods available in Mac OS X 10.1 or later */
264
265/*! @function runAction
266    @abstract Single thread a call to an action with the work-loop.
267    @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 runAction can cause direct or indirect re-entrancy.  When 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.
268    @param action Pointer to function to be executed in work-loop context.
269    @param arg0 Parameter for action parameter, defaults to 0.
270    @param arg1 Parameter for action parameter, defaults to 0.
271    @param arg2 Parameter for action parameter, defaults to 0.
272    @param arg3 Parameter for action parameter, defaults to 0.
273    @result Returns the value of the Action callout.
274*/
275    OSMetaClassDeclareReservedUsed(IOWorkLoop, 0);
276    virtual IOReturn runAction(Action action, OSObject *target,
277			       void *arg0 = 0, void *arg1 = 0,
278			       void *arg2 = 0, void *arg3 = 0);
279
280/*! @function runEventSources
281    @discussion Consists of the inner 2 loops of the threadMain function(qv).
282    The outer loop terminates when there is no more work, and the inside loop
283    walks the event list calling the checkForWork method in each event source.
284    If an event source has more work to do, it can set the more flag and the
285    outer loop will repeat.
286<br><br>
287    This function can be used to clear a priority inversion between the normal
288    workloop thread and multimedia's real time threads.  The problem is that
289    the interrupt action routine is often held off by high priority threads.
290    So if they want to get their data now they will have to call us and ask if
291    any data is available.  The multi-media user client will arrange for this
292    function to be called, which causes any pending interrupts to be processed
293    and the completion routines called.  By the time the function returns all
294    outstanding work will have been completed at the real time threads
295    priority.
296
297    @result Return false if the work loop is shutting down, true otherwise.
298*/
299    OSMetaClassDeclareReservedUsed(IOWorkLoop, 1);
300    virtual bool runEventSources();
301
302protected:
303
304    OSMetaClassDeclareReservedUnused(IOWorkLoop, 2);
305    OSMetaClassDeclareReservedUnused(IOWorkLoop, 3);
306    OSMetaClassDeclareReservedUnused(IOWorkLoop, 4);
307    OSMetaClassDeclareReservedUnused(IOWorkLoop, 5);
308    OSMetaClassDeclareReservedUnused(IOWorkLoop, 6);
309    OSMetaClassDeclareReservedUnused(IOWorkLoop, 7);
310};
311
312#endif /* !__IOKIT_IOWORKLOOP_H */
313