/*
* Copyright (c) 2000-2019 Apple Inc. All rights reserved.
*
* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
*
* This file contains Original Code and/or Modifications of Original Code
* as defined in and that are subject to the Apple Public Source License
* Version 2.0 (the 'License'). You may not use this file except in
* compliance with the License. The rights granted to you under the License
* may not be used to create, or enable the creation or redistribution of,
* unlawful or unlicensed copies of an Apple operating system, or to
* circumvent, violate, or enable the circumvention or violation of, any
* terms of an Apple operating system software license agreement.
*
* Please obtain a copy of the License at
* http://www.opensource.apple.com/apsl/ and read it before using this file.
*
* The Original Code and all software distributed under the License are
* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
* Please see the License for the specific language governing rights and
* limitations under the License.
*
* @APPLE_OSREFERENCE_LICENSE_HEADER_END@
*/
/*
*
* Copyright (c) 2000 Apple Computer, Inc. All rights reserved.
*
* HISTORY
*
* 2001-01-17 gvdl Re-implement on IOCommandGate::commandSleep
* 11/13/2000 CJS Created IOCommandPool class and implementation
*
*/
/*!
* @header IOCommandPool
* @abstract
* This header contains the IOCommandPool class definition.
*/
#ifndef _IOKIT_IO_COMMAND_POOL_H_
#define _IOKIT_IO_COMMAND_POOL_H_
/*
* Kernel
*/
#if defined(KERNEL) && defined(__cplusplus)
#include <kern/kern_types.h>
#include <kern/queue.h>
#include <IOKit/IOCommand.h>
#include <IOKit/IOCommandGate.h>
#include <IOKit/IOService.h>
#include <IOKit/IOWorkLoop.h>
#include <libkern/c++/OSPtr.h>
/*!
* @class IOCommandPool
* @abstract Manipulates a pool of commands which inherit from IOCommand.
* @discussion
* The IOCommandPool class is used to manipulate a pool of commands which
* inherit from IOCommand. It includes a factory method to create a pool
* of a certain size. Once the factory method is invoked, the semaphore
* is set to zero. The caller must then put commands in the pool by creating
* the command (via the controller's factory method or a memory allocation)
* and calling the returnCommand method with the newly created command as its
* argument.
*/
class IOCommandPool : public OSObject
{
OSDeclareDefaultStructors(IOCommandPool);
protected:
queue_head_t fQueueHead; /* head of the queue of elements available */
UInt32 fSleepers; /* Count of threads sleeping on this pool */
OSPtr<IOCommandGate> fSerializer; /* command gate used for serializing pool access */
/*! @struct ExpansionData
* @discussion This structure will be used to expand the capablilties of the IOEventSource in the future.
*/
struct ExpansionData { };
/*! @var reserved
* Reserved for future use. (Internal use only) */
ExpansionData *reserved;
/*!
* @const kIOCommandPoolDefaultSize
* @abstract The default size of any command pool.
* @discussion
* kIOCommandPoolDefaultSize is the default size of any command pool.
* The default size was determined to be the smallest size for which
* a pool makes sense.
*/
static const UInt32 kIOCommandPoolDefaultSize = 2;
/*
* Free all of this object's outstanding resources.
*/
virtual void free(void) APPLE_KEXT_OVERRIDE;
public:
/*!
* @function initWithWorkLoop
* @abstract Primary initializer for an IOCommandPool object.
* @discussion Primary initializer for an IOCommandPool.
* Should probably use IOCommandPool::withWorkLoop() as it is easier to use.
* @param workLoop
* The workloop that this command pool should synchronize with.
* @result Returns true if command pool was successfully initialized.
*/
virtual bool initWithWorkLoop(IOWorkLoop *workLoop);
/*!
* @function withWorkLoop
* @abstract Primary factory method for the IOCommandPool class
* @discussion
* The withWorkLoop method is what is known as a factory method. It creates
* a new instance of an IOCommandPool and returns a pointer to that object.
* @param inWorkLoop
* The workloop that this command pool should synchronize with.
* @result
* Returns a pointer to an instance of IOCommandPool if successful,
* otherwise NULL.
*/
static OSPtr<IOCommandPool> withWorkLoop(IOWorkLoop *inWorkLoop);
/*!
* @function init
* @abstract Should never be used, obsolete. See initWithWorkLoop.
*/
virtual bool init(IOService *inOwner,
IOWorkLoop *inWorkLoop,
UInt32 inSize = kIOCommandPoolDefaultSize);
/*!
* @function withWorkLoop
* @abstract Should never be used, obsolete. See IOCommandPool::withWorkLoop.
*/
static OSPtr<IOCommandPool> commandPool(IOService *inOwner,
IOWorkLoop *inWorkLoop,
UInt32 inSize = kIOCommandPoolDefaultSize);
/*!
* @function getCommand
* @discussion The getCommand method is used to get a pointer to an object of type IOCommand from the pool.
* @param blockForCommand
* If the caller would like to have its thread slept until a command is
* available, it should pass true, else false.
* @result
* If the caller passes true in blockForCommand, getCommand guarantees that
* the result will be a pointer to an IOCommand object from the pool. If
* the caller passes false, s/he is responsible for checking whether a non-NULL
* pointer was returned.
*/
virtual OSPtr<IOCommand> getCommand(
bool blockForCommand = true);
/*!
* @function returnCommand
* @discussion
* The returnCommand method is used to place an object of type IOCommand
* into the pool, whether it be the first time, or the 1000th time.
* @param command
* The command to place in the pool.
*/
virtual void returnCommand(LIBKERN_CONSUMED IOCommand *command);
protected:
/*!
* @function gatedGetCommand
* @discussion
* The gatedGetCommand method is used to serialize the extraction of a
* command from the pool behind a command gate, runAction-ed by getCommand.
* @param command
* A pointer to a pointer to an IOCommand object where the returned
* command will be stored.
* @param blockForCommand
* A bool that indicates whether to block the request until a command
* becomes available.
* @result
* Returns kIOReturnNoResources if no command is available and the client
* doesn't wish to block until one does become available.
* kIOReturnSuccess if the vCommand argument is valid.
*/
virtual IOReturn gatedGetCommand(
LIBKERN_RETURNS_NOT_RETAINED IOCommand **command, bool blockForCommand);
/*!
* @function gatedReturnCommand
* @discussion
* The gatedReturnCommand method is used to serialize the return of a
* command to the pool behind a command gate, runAction-ed by returnCommand.
* @param command
* A pointer to the IOCommand object to be returned to the pool.
* @result
* Always returns kIOReturnSuccess if the vCommand argument is valid.
*/
virtual IOReturn gatedReturnCommand(IOCommand *command);
private:
OSMetaClassDeclareReservedUnused(IOCommandPool, 0);
OSMetaClassDeclareReservedUnused(IOCommandPool, 1);
OSMetaClassDeclareReservedUnused(IOCommandPool, 2);
OSMetaClassDeclareReservedUnused(IOCommandPool, 3);
OSMetaClassDeclareReservedUnused(IOCommandPool, 4);
OSMetaClassDeclareReservedUnused(IOCommandPool, 5);
OSMetaClassDeclareReservedUnused(IOCommandPool, 6);
OSMetaClassDeclareReservedUnused(IOCommandPool, 7);
};
#endif /* defined(KERNEL) && defined(__cplusplus) */
#endif /* _IOKIT_IO_COMMAND_POOL_H_ */