]> git.saurik.com Git - apple/xnu.git/blame - iokit/IOKit/IOCommandPool.h
xnu-6153.121.1.tar.gz
[apple/xnu.git] / iokit / IOKit / IOCommandPool.h
CommitLineData
1c79356b 1/*
cb323159 2 * Copyright (c) 2000-2019 Apple Inc. All rights reserved.
1c79356b 3 *
2d21ac55 4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
0a7de745 5 *
2d21ac55
A
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.
0a7de745 14 *
2d21ac55
A
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
0a7de745 17 *
2d21ac55
A
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
8f6c56a5
A
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
2d21ac55
A
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.
0a7de745 25 *
2d21ac55 26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
1c79356b
A
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
62/*!
63 * @class IOCommandPool
91447636 64 * @abstract Manipulates a pool of commands which inherit from IOCommand.
1c79356b
A
65 * @discussion
66 * The IOCommandPool class is used to manipulate a pool of commands which
67 * inherit from IOCommand. It includes a factory method to create a pool
68 * of a certain size. Once the factory method is invoked, the semaphore
69 * is set to zero. The caller must then put commands in the pool by creating
70 * the command (via the controller's factory method or a memory allocation)
71 * and calling the returnCommand method with the newly created command as its
72 * argument.
73 */
74
75class IOCommandPool : public OSObject
76{
cb323159 77 OSDeclareDefaultStructors(IOCommandPool);
0a7de745
A
78
79
1c79356b
A
80protected:
81
0a7de745
A
82 queue_head_t fQueueHead; /* head of the queue of elements available */
83 UInt32 fSleepers; /* Count of threads sleeping on this pool */
84 IOCommandGate *fSerializer; /* command gate used for serializing pool access */
1c79356b
A
85
86/*! @struct ExpansionData
0a7de745
A
87 * @discussion This structure will be used to expand the capablilties of the IOEventSource in the future.
88 */
89 struct ExpansionData { };
1c79356b
A
90
91/*! @var reserved
0a7de745
A
92 * Reserved for future use. (Internal use only) */
93 ExpansionData *reserved;
94
95/*!
96 * @const kIOCommandPoolDefaultSize
97 * @abstract The default size of any command pool.
98 * @discussion
99 * kIOCommandPoolDefaultSize is the default size of any command pool.
100 * The default size was determined to be the smallest size for which
101 * a pool makes sense.
102 */
103
104 static const UInt32 kIOCommandPoolDefaultSize = 2;
105
106/*
107 * Free all of this object's outstanding resources.
108 */
109
110 virtual void free(void) APPLE_KEXT_OVERRIDE;
111
112
1c79356b
A
113public:
114
0a7de745
A
115/*!
116 * @function initWithWorkLoop
117 * @abstract Primary initializer for an IOCommandPool object.
118 * @discussion Primary initializer for an IOCommandPool.
119 * Should probably use IOCommandPool::withWorkLoop() as it is easier to use.
120 * @param workLoop
121 * The workloop that this command pool should synchronize with.
122 * @result Returns true if command pool was successfully initialized.
123 */
124 virtual bool initWithWorkLoop(IOWorkLoop *workLoop);
125
126/*!
127 * @function withWorkLoop
128 * @abstract Primary factory method for the IOCommandPool class
129 * @discussion
130 * The withWorkLoop method is what is known as a factory method. It creates
131 * a new instance of an IOCommandPool and returns a pointer to that object.
132 * @param inWorkLoop
133 * The workloop that this command pool should synchronize with.
134 * @result
135 * Returns a pointer to an instance of IOCommandPool if successful,
136 * otherwise NULL.
137 */
138
139 static IOCommandPool *withWorkLoop(IOWorkLoop *inWorkLoop);
140
141/*!
142 * @function init
143 * @abstract Should never be used, obsolete. See initWithWorkLoop.
144 */
145 virtual bool init(IOService *inOwner,
146 IOWorkLoop *inWorkLoop,
147 UInt32 inSize = kIOCommandPoolDefaultSize);
148
149/*!
150 * @function withWorkLoop
151 * @abstract Should never be used, obsolete. See IOCommandPool::withWorkLoop.
152 */
153 static IOCommandPool *commandPool(IOService *inOwner,
154 IOWorkLoop *inWorkLoop,
155 UInt32 inSize = kIOCommandPoolDefaultSize);
156
157
158/*!
159 * @function getCommand
160 * @discussion The getCommand method is used to get a pointer to an object of type IOCommand from the pool.
161 * @param blockForCommand
162 * If the caller would like to have its thread slept until a command is
163 * available, it should pass true, else false.
164 * @result
165 * If the caller passes true in blockForCommand, getCommand guarantees that
166 * the result will be a pointer to an IOCommand object from the pool. If
167 * the caller passes false, s/he is responsible for checking whether a non-NULL
168 * pointer was returned.
169 */
170
171 virtual IOCommand *getCommand(bool blockForCommand = true);
172
173/*!
174 * @function returnCommand
175 * @discussion
176 * The returnCommand method is used to place an object of type IOCommand
177 * into the pool, whether it be the first time, or the 1000th time.
178 * @param command
179 * The command to place in the pool.
180 */
181
182 virtual void returnCommand(IOCommand *command);
183
1c79356b 184protected:
0a7de745
A
185
186/*!
187 * @function gatedGetCommand
188 * @discussion
189 * The gatedGetCommand method is used to serialize the extraction of a
190 * command from the pool behind a command gate, runAction-ed by getCommand.
191 * @param command
192 * A pointer to a pointer to an IOCommand object where the returned
193 * command will be stored.
194 * @param blockForCommand
195 * A bool that indicates whether to block the request until a command
196 * becomes available.
197 * @result
198 * Returns kIOReturnNoResources if no command is available and the client
199 * doesn't wish to block until one does become available.
200 * kIOReturnSuccess if the vCommand argument is valid.
201 */
cb323159
A
202 virtual IOReturn gatedGetCommand(
203 LIBKERN_RETURNS_NOT_RETAINED IOCommand **command, bool blockForCommand);
0a7de745
A
204
205/*!
206 * @function gatedReturnCommand
207 * @discussion
208 * The gatedReturnCommand method is used to serialize the return of a
209 * command to the pool behind a command gate, runAction-ed by returnCommand.
210 * @param command
211 * A pointer to the IOCommand object to be returned to the pool.
212 * @result
213 * Always returns kIOReturnSuccess if the vCommand argument is valid.
214 */
215 virtual IOReturn gatedReturnCommand(IOCommand *command);
1c79356b
A
216
217private:
0a7de745
A
218 OSMetaClassDeclareReservedUnused(IOCommandPool, 0);
219 OSMetaClassDeclareReservedUnused(IOCommandPool, 1);
220 OSMetaClassDeclareReservedUnused(IOCommandPool, 2);
221 OSMetaClassDeclareReservedUnused(IOCommandPool, 3);
222 OSMetaClassDeclareReservedUnused(IOCommandPool, 4);
223 OSMetaClassDeclareReservedUnused(IOCommandPool, 5);
224 OSMetaClassDeclareReservedUnused(IOCommandPool, 6);
225 OSMetaClassDeclareReservedUnused(IOCommandPool, 7);
1c79356b
A
226};
227
0a7de745 228#endif /* defined(KERNEL) && defined(__cplusplus) */
1c79356b 229
0a7de745 230#endif /* _IOKIT_IO_COMMAND_POOL_H_ */