iokit/IOKit/IOCommandPool.h

   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_ */