1 | /* |
2 | * Copyright (c) 2000-2019 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 | /* |
30 | * |
31 | * Copyright (c) 2000 Apple Computer, Inc. All rights reserved. |
32 | * |
33 | * HISTORY |
34 | * |
35 | * 2001-01-17 gvdl Re-implement on IOCommandGate::commandSleep |
36 | * 11/13/2000 CJS Created IOCommandPool class and implementation |
37 | * |
38 | */ |
39 | |
40 | /*! |
41 | * @header IOCommandPool |
42 | * @abstract |
43 | * This header contains the IOCommandPool class definition. |
44 | */ |
45 | |
46 | #ifndef _IOKIT_IO_COMMAND_POOL_H_ |
47 | #define _IOKIT_IO_COMMAND_POOL_H_ |
48 | |
49 | /* |
50 | * Kernel |
51 | */ |
52 | |
53 | #if defined(KERNEL) && defined(__cplusplus) |
54 | |
55 | #include <kern/kern_types.h> |
56 | #include <kern/queue.h> |
57 | #include <IOKit/IOCommand.h> |
58 | #include <IOKit/IOCommandGate.h> |
59 | #include <IOKit/IOService.h> |
60 | #include <IOKit/IOWorkLoop.h> |
61 | #include <libkern/c++/OSPtr.h> |
62 | |
63 | /*! |
64 | * @class IOCommandPool |
65 | * @abstract Manipulates a pool of commands which inherit from IOCommand. |
66 | * @discussion |
67 | * The IOCommandPool class is used to manipulate a pool of commands which |
68 | * inherit from IOCommand. It includes a factory method to create a pool |
69 | * of a certain size. Once the factory method is invoked, the semaphore |
70 | * is set to zero. The caller must then put commands in the pool by creating |
71 | * the command (via the controller's factory method or a memory allocation) |
72 | * and calling the returnCommand method with the newly created command as its |
73 | * argument. |
74 | */ |
75 | |
76 | class IOCommandPool : public OSObject |
77 | { |
78 | OSDeclareDefaultStructors(IOCommandPool); |
79 | |
80 | |
81 | protected: |
82 | |
83 | queue_head_t fQueueHead; /* head of the queue of elements available */ |
84 | UInt32 fSleepers; /* Count of threads sleeping on this pool */ |
85 | OSPtr<IOCommandGate> fSerializer; /* command gate used for serializing pool access */ |
86 | |
87 | /*! @struct ExpansionData |
88 | * @discussion This structure will be used to expand the capablilties of the IOEventSource in the future. |
89 | */ |
90 | struct ExpansionData { }; |
91 | |
92 | /*! @var reserved |
93 | * Reserved for future use. (Internal use only) */ |
94 | ExpansionData *reserved; |
95 | |
96 | /*! |
97 | * @const kIOCommandPoolDefaultSize |
98 | * @abstract The default size of any command pool. |
99 | * @discussion |
100 | * kIOCommandPoolDefaultSize is the default size of any command pool. |
101 | * The default size was determined to be the smallest size for which |
102 | * a pool makes sense. |
103 | */ |
104 | |
105 | static const UInt32 kIOCommandPoolDefaultSize = 2; |
106 | |
107 | /* |
108 | * Free all of this object's outstanding resources. |
109 | */ |
110 | |
111 | virtual void free(void) APPLE_KEXT_OVERRIDE; |
112 | |
113 | |
114 | public: |
115 | |
116 | /*! |
117 | * @function initWithWorkLoop |
118 | * @abstract Primary initializer for an IOCommandPool object. |
119 | * @discussion Primary initializer for an IOCommandPool. |
120 | * Should probably use IOCommandPool::withWorkLoop() as it is easier to use. |
121 | * @param workLoop |
122 | * The workloop that this command pool should synchronize with. |
123 | * @result Returns true if command pool was successfully initialized. |
124 | */ |
125 | virtual bool initWithWorkLoop(IOWorkLoop *workLoop); |
126 | |
127 | /*! |
128 | * @function withWorkLoop |
129 | * @abstract Primary factory method for the IOCommandPool class |
130 | * @discussion |
131 | * The withWorkLoop method is what is known as a factory method. It creates |
132 | * a new instance of an IOCommandPool and returns a pointer to that object. |
133 | * @param inWorkLoop |
134 | * The workloop that this command pool should synchronize with. |
135 | * @result |
136 | * Returns a pointer to an instance of IOCommandPool if successful, |
137 | * otherwise NULL. |
138 | */ |
139 | |
140 | static OSPtr<IOCommandPool> withWorkLoop(IOWorkLoop *inWorkLoop); |
141 | |
142 | /*! |
143 | * @function init |
144 | * @abstract Should never be used, obsolete. See initWithWorkLoop. |
145 | */ |
146 | virtual bool init(IOService *inOwner, |
147 | IOWorkLoop *inWorkLoop, |
148 | UInt32 inSize = kIOCommandPoolDefaultSize); |
149 | |
150 | /*! |
151 | * @function withWorkLoop |
152 | * @abstract Should never be used, obsolete. See IOCommandPool::withWorkLoop. |
153 | */ |
154 | static OSPtr<IOCommandPool> commandPool(IOService *inOwner, |
155 | IOWorkLoop *inWorkLoop, |
156 | UInt32 inSize = kIOCommandPoolDefaultSize); |
157 | |
158 | |
159 | /*! |
160 | * @function getCommand |
161 | * @discussion The getCommand method is used to get a pointer to an object of type IOCommand from the pool. |
162 | * @param blockForCommand |
163 | * If the caller would like to have its thread slept until a command is |
164 | * available, it should pass true, else false. |
165 | * @result |
166 | * If the caller passes true in blockForCommand, getCommand guarantees that |
167 | * the result will be a pointer to an IOCommand object from the pool. If |
168 | * the caller passes false, s/he is responsible for checking whether a non-NULL |
169 | * pointer was returned. |
170 | */ |
171 | |
172 | virtual OSPtr<IOCommand> getCommand( |
173 | bool blockForCommand = true); |
174 | |
175 | /*! |
176 | * @function returnCommand |
177 | * @discussion |
178 | * The returnCommand method is used to place an object of type IOCommand |
179 | * into the pool, whether it be the first time, or the 1000th time. |
180 | * @param command |
181 | * The command to place in the pool. |
182 | */ |
183 | |
184 | virtual void returnCommand(LIBKERN_CONSUMED IOCommand *command); |
185 | |
186 | protected: |
187 | |
188 | /*! |
189 | * @function gatedGetCommand |
190 | * @discussion |
191 | * The gatedGetCommand method is used to serialize the extraction of a |
192 | * command from the pool behind a command gate, runAction-ed by getCommand. |
193 | * @param command |
194 | * A pointer to a pointer to an IOCommand object where the returned |
195 | * command will be stored. |
196 | * @param blockForCommand |
197 | * A bool that indicates whether to block the request until a command |
198 | * becomes available. |
199 | * @result |
200 | * Returns kIOReturnNoResources if no command is available and the client |
201 | * doesn't wish to block until one does become available. |
202 | * kIOReturnSuccess if the vCommand argument is valid. |
203 | */ |
204 | virtual IOReturn gatedGetCommand( |
205 | LIBKERN_RETURNS_NOT_RETAINED IOCommand **command, bool blockForCommand); |
206 | |
207 | /*! |
208 | * @function gatedReturnCommand |
209 | * @discussion |
210 | * The gatedReturnCommand method is used to serialize the return of a |
211 | * command to the pool behind a command gate, runAction-ed by returnCommand. |
212 | * @param command |
213 | * A pointer to the IOCommand object to be returned to the pool. |
214 | * @result |
215 | * Always returns kIOReturnSuccess if the vCommand argument is valid. |
216 | */ |
217 | virtual IOReturn gatedReturnCommand(IOCommand *command); |
218 | |
219 | private: |
220 | OSMetaClassDeclareReservedUnused(IOCommandPool, 0); |
221 | OSMetaClassDeclareReservedUnused(IOCommandPool, 1); |
222 | OSMetaClassDeclareReservedUnused(IOCommandPool, 2); |
223 | OSMetaClassDeclareReservedUnused(IOCommandPool, 3); |
224 | OSMetaClassDeclareReservedUnused(IOCommandPool, 4); |
225 | OSMetaClassDeclareReservedUnused(IOCommandPool, 5); |
226 | OSMetaClassDeclareReservedUnused(IOCommandPool, 6); |
227 | OSMetaClassDeclareReservedUnused(IOCommandPool, 7); |
228 | }; |
229 | |
230 | #endif /* defined(KERNEL) && defined(__cplusplus) */ |
231 | |
232 | #endif /* _IOKIT_IO_COMMAND_POOL_H_ */ |
233 | |