iokit/IOKit/IOCommandPool.h

   1 /*
   2  * Copyright (c) 2000-2016 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
  62 /*!
  63  * @class IOCommandPool
  64  * @abstract Manipulates a pool of commands which inherit from IOCommand.
  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
  75 class IOCommandPool : public OSObject
  76 {
  77         OSDeclareDefaultStructors(IOCommandPool)
  78
  79
  80 protected:
  81
  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 */
  85
  86 /*! @struct ExpansionData
  87  *   @discussion This structure will be used to expand the capablilties of the IOEventSource in the future.
  88  */
  89         struct ExpansionData { };
  90
  91 /*! @var reserved
  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
 113 public:
 114
 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
 184 protected:
 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  */
 202         virtual IOReturn gatedGetCommand(IOCommand **command, bool blockForCommand);
 203
 204 /*!
 205  * @function gatedReturnCommand
 206  * @discussion
 207  * The gatedReturnCommand method is used to serialize the return of a
 208  * command to the pool behind a command gate, runAction-ed by returnCommand.
 209  * @param command
 210  * A pointer to the IOCommand object to be returned to the pool.
 211  * @result
 212  * Always returns kIOReturnSuccess if the vCommand argument is valid.
 213  */
 214         virtual IOReturn gatedReturnCommand(IOCommand *command);
 215
 216 private:
 217         OSMetaClassDeclareReservedUnused(IOCommandPool, 0);
 218         OSMetaClassDeclareReservedUnused(IOCommandPool, 1);
 219         OSMetaClassDeclareReservedUnused(IOCommandPool, 2);
 220         OSMetaClassDeclareReservedUnused(IOCommandPool, 3);
 221         OSMetaClassDeclareReservedUnused(IOCommandPool, 4);
 222         OSMetaClassDeclareReservedUnused(IOCommandPool, 5);
 223         OSMetaClassDeclareReservedUnused(IOCommandPool, 6);
 224         OSMetaClassDeclareReservedUnused(IOCommandPool, 7);
 225 };
 226
 227 #endif  /* defined(KERNEL) && defined(__cplusplus) */
 228
 229 #endif  /* _IOKIT_IO_COMMAND_POOL_H_ */