[apple/xnu.git] / iokit / IOKit / IOCommandPool.h

/*
 * Copyright (c) 2000-2016 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>

/*!
 * @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 */
    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 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 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 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(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(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_ */
Commit	Line	Data
1c79356b	1	/*
39037602	2	* Copyright (c) 2000-2016 Apple Inc. All rights reserved.
1c79356b	3	*
2d21ac55	4	* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
1c79356b	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.
8f6c56a5	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.
	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
8f6c56a5 A	20	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
8f6c56a5 A	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.
8f6c56a5	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
	75	class IOCommandPool : public OSObject
	76	{
	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	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	/*!
91447636 A	97	* @const kIOCommandPoolDefaultSize
91447636 A	98	* @abstract The default size of any command pool.
1c79356b A	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
3e170ce0	111	virtual void free(void) APPLE_KEXT_OVERRIDE;
1c79356b A	112
	113
	114	public:
	115
	116	/*!
	117	* @function initWithWorkLoop
91447636 A	118	* @abstract Primary initializer for an IOCommandPool object.
91447636 A	119	* @discussion Primary initializer for an IOCommandPool.
1c79356b	120	* Should probably use IOCommandPool::withWorkLoop() as it is easier to use.
39037602	121	* @param workLoop
91447636 A	122	* The workloop that this command pool should synchronize with.
91447636 A	123	* @result Returns true if command pool was successfully initialized.
1c79356b A	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
91447636	134	* The workloop that this command pool should synchronize with.
1c79356b A	135	* @result
	136	* Returns a pointer to an instance of IOCommandPool if successful,
	137	* otherwise NULL.
	138	*/
	139
	140	static IOCommandPool withWorkLoop(IOWorkLoop inWorkLoop);
	141
	142	/*!
	143	* @function init
91447636	144	* @abstract Should never be used, obsolete. See initWithWorkLoop.
1c79356b A	145	*/
	146	virtual bool init(IOService *inOwner,
	147	IOWorkLoop *inWorkLoop,
	148	UInt32 inSize = kIOCommandPoolDefaultSize);
	149
	150	/*!
	151	* @function withWorkLoop
91447636	152	* @abstract Should never be used, obsolete. See IOCommandPool::withWorkLoop.
1c79356b A	153	*/
	154	static IOCommandPool commandPool(IOService inOwner,
	155	IOWorkLoop *inWorkLoop,
	156	UInt32 inSize = kIOCommandPoolDefaultSize);
	157
	158
	159	/*!
	160	* @function getCommand
91447636	161	* @discussion The getCommand method is used to get a pointer to an object of type IOCommand from the pool.
1c79356b A	162	* @param blockForCommand
1c79356b A	163	* If the caller would like to have its thread slept until a command is
91447636	164	* available, it should pass true, else false.
1c79356b A	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 IOCommand *getCommand(bool blockForCommand = true);
	173
	174	/*!
	175	* @function returnCommand
	176	* @discussion
	177	* The returnCommand method is used to place an object of type IOCommand
	178	* into the pool, whether it be the first time, or the 1000th time.
39037602	179	* @param command
1c79356b A	180	* The command to place in the pool.
	181	*/
	182
	183	virtual void returnCommand(IOCommand *command);
	184
	185	protected:
	186
	187	/*!
	188	* @function gatedGetCommand
	189	* @discussion
	190	* The gatedGetCommand method is used to serialize the extraction of a
91447636	191	* command from the pool behind a command gate, runAction-ed by getCommand.
39037602	192	* @param command
1c79356b	193	* A pointer to a pointer to an IOCommand object where the returned
91447636	194	* command will be stored.
39037602	195	* @param blockForCommand
1c79356b A	196	* A bool that indicates whether to block the request until a command
	197	* becomes available.
	198	* @result
	199	* Returns kIOReturnNoResources if no command is available and the client
91447636	200	* doesn't wish to block until one does become available.
1c79356b A	201	* kIOReturnSuccess if the vCommand argument is valid.
	202	*/
	203	virtual IOReturn gatedGetCommand(IOCommand **command, bool blockForCommand);
	204
	205	/*!
	206	* @function gatedReturnCommand
	207	* @discussion
	208	* The gatedReturnCommand method is used to serialize the return of a
91447636	209	* command to the pool behind a command gate, runAction-ed by returnCommand.
39037602	210	* @param command
1c79356b A	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);
	216
	217	private:
	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);
	226	};
	227
	228	#endif /* defined(KERNEL) && defined(__cplusplus) */
	229
	230	#endif /* _IOKIT_IO_COMMAND_POOL_H_ */