![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to IOCommandGate.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Apple XNU] / XNU / iokit / IOKit|
Return to IOCommandGate.h CVS log | Up to [Apple XNU] / XNU / iokit / IOKit |
1.1 root 1: /*
2: * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
3: *
4: * @APPLE_LICENSE_HEADER_START@
5: *
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.
11: *
12: * This Original Code and all software distributed under the License are
13: * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
14: * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
15: * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
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.
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: public:
86: /*! @function commandGate
87: @abstract Factory method to create and initialise an IOCommandGate, See $link init.
88: @result Returns a pointer to the new command gate if sucessful, 0 otherwise. */
89: static IOCommandGate *commandGate(OSObject *owner, Action action = 0);
90:
91: /*! @function init
92: @abstract Class initialiser.
93: @discussion Initialiser for IOCommandGate operates only on newly 'newed'
94: objects. Shouldn't be used to re-init an existing instance.
95: @param owner Owner of this, newly created, instance of the IOCommandGate. This argument will be used as the first parameter in the action callout.
96: @param action
97: Pointer to a C function that is called whenever a client of the
98: IOCommandGate calls runCommand. NB Can be a C++ member function but caller
99: must cast the member function to $link IOCommandGate::Action and they will get a
100: compiler warning. Defaults to zero, see $link IOEventSource::setAction.
101: @result True if inherited classes initialise successfully. */
102: virtual bool init(OSObject *owner, Action action = 0);
103:
104: /*! @function runCommand
105: @abstract Single thread a command with the target work-loop.
106: @discussion Client function that causes the current action to be called in
107: a single threaded manner. Beware the work-loop's gate is recursive and command
108: gates can cause direct or indirect re-entrancy. When the executing on a
109: client's thread runCommand will sleep until the work-loop's gate opens for
110: execution of client actions, the action is single threaded against all other
111: work-loop event sources.
112: @param arg0 Parameter for action of command gate, defaults to 0.
113: @param arg1 Parameter for action of command gate, defaults to 0.
114: @param arg2 Parameter for action of command gate, defaults to 0.
115: @param arg3 Parameter for action of command gate, defaults to 0.
116: @result kIOReturnSuccess if successful. kIOReturnNotPermitted if this
117: event source is currently disabled, kIOReturnNoResources if no action available.
118: */
119: virtual IOReturn runCommand(void *arg0 = 0, void *arg1 = 0,
120: void *arg2 = 0, void *arg3 = 0);
121:
122: /*! @function runAction
123: @abstract Single thread a call to an action with the target work-loop.
124: @discussion Client function that causes the given action to be called in
125: a single threaded manner. Beware the work-loop's gate is recursive and command
126: gates can cause direct or indirect re-entrancy. When the executing on a
127: client's thread runCommand will sleep until the work-loop's gate opens for
128: execution of client actions, the action is single threaded against all other
129: work-loop event sources.
130: @param action Pointer to function to be executed in work-loop context.
131: @param arg0 Parameter for action of command gate, defaults to 0.
132: @param arg1 Parameter for action of command gate, defaults to 0.
133: @param arg2 Parameter for action of command gate, defaults to 0.
134: @param arg3 Parameter for action of command gate, defaults to 0.
135: @result kIOReturnSuccess if successful. kIOReturnBadArgument if action is not defined, kIOReturnNoResources if no action available.
136: */
137: virtual IOReturn runAction(Action action,
138: void *arg0 = 0, void *arg1 = 0,
139: void *arg2 = 0, void *arg3 = 0);
140: };
141:
142: #endif /* !_IOKIT_IOCOMMANDGATE_H */
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.