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