/*
 * Copyright (c) 1998-2000 Apple Computer, 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@
 */
#ifndef _IOMEMORYCURSOR_H
#define _IOMEMORYCURSOR_H

#include <libkern/c++/OSObject.h>
#include <IOKit/IOTypes.h>

class IOMemoryDescriptor;

/**************************** class IOMemoryCursor ***************************/

/*!
    @class IOMemoryCursor
    @abstract A mechanism to convert memory references to physical addresses.
    @discussion The IOMemoryCursor declares the super class that all
specific memory cursors must inherit from, but a memory cursor can be created without a specific format subclass by just providing a segment function to the initializers.  This class does the difficult stuff of dividing a memory descriptor into a physical scatter/gather list appropriate for the target hardware.
<br><br>
    A driver is expected to create a memory cursor and configure it to the limitations of its DMA hardware; for instance the memory cursor used by the FireWire SBP-2 protocol has a maximum physical segment size of 2^16 - 1 but the actual transfer size is unlimited.  Thus it would create a cursor with a maxSegmentSize of 65535 and a maxTransfer size of UINT_MAX.   It would also provide a SegmentFunction that can output a pagelist entry.
<br><br>
Below is the simplest example of a SegmentFunction:<br>
void IONaturalMemoryCursor::outputSegment(PhysicalSegment segment,<br>
					  void *	  outSegments,<br>
					  UInt32	  outSegmentIndex)<br>
{<br>
    ((PhysicalSegment *) outSegments)[outSegmentIndex] = segment;<br>
}

*/
class IOMemoryCursor : public OSObject
{
    OSDeclareDefaultStructors(IOMemoryCursor)

public:
/*!
    @typedef PhysicalSegment
    @discussion A physical address/length pair.
*/
    struct PhysicalSegment
    {
	IOPhysicalAddress location;
	IOPhysicalLength  length;
    };

/*! @defined IOPhysicalSegment
    @discussion Backward compatibility define for the old non-class scoped type definition.  See IOMemoryCursor::PhysicalSegment 
*/
#define IOPhysicalSegment IOMemoryCursor::PhysicalSegment

/*!
    @typedef SegmentFunction
    @discussion Pointer to a C function that outputs a single physical segment to an element in the array as defined by the segments and segmentIndex parameters.
    @param segment The physical address and length that is next to be output.
    @param segments Base of the output vector of DMA address length pairs.
    @param segmentIndex Index to output 'segment' in the 'segments' array.
*/
    typedef void (*SegmentFunction)(PhysicalSegment segment,
				    void *	    segments,
				    UInt32	    segmentIndex);

/*! @defined OutputSegmentFunc
    @discussion Backward compatibility define for the old non-class scoped type definition.  See IOMemoryCursor::SegmentFunction */
#define OutputSegmentFunc IOMemoryCursor::SegmentFunction

protected:
/*! @var outSeg The action method called when an event has been delivered */
    SegmentFunction outSeg;

/*! @var maxSegmentSize Maximum size of one segment in a scatter/gather list */
    IOPhysicalLength  maxSegmentSize;

/*! @var maxTransferSize
    Maximum size of a transfer that this memory cursor is allowed to generate */
    IOPhysicalLength  maxTransferSize;

/*! @var alignMask
    Currently unused.  Reserved for automated aligment restriction code. */
    IOPhysicalLength  alignMask;

public:
/*! @function withSpecification
    @abstract Creates and initializes an IOMemoryCursor in one operation.
    @discussion Factory function to create and initialize an IOMemoryCursor in one operation.  For more information, see IOMemoryCursor::initWithSpecification.
    @param outSegFunc SegmentFunction to call to output one physical segment.
    @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
    @param maxTransferSize Maximum size of an entire transfer.	Defaults to 0 indicating no maximum.
    @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
    @result Returns a new memory cursor if successfully created and initialized, 0 otherwise.
*/
    static IOMemoryCursor *
	withSpecification(SegmentFunction  outSegFunc,
			  IOPhysicalLength maxSegmentSize = 0,
			  IOPhysicalLength maxTransferSize = 0,
			  IOPhysicalLength alignment = 1);

/*! @function initWithSpecification
    @abstract Primary initializer for the IOMemoryCursor class.
    @param outSegFunc SegmentFunction to call to output one physical segment.
    @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
    @param maxTransferSize Maximum size of an entire transfer.	Defaults to 0 indicating no maximum.
    @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
    @result Returns true if the inherited classes and this instance initialize
successfully.
*/
    virtual bool initWithSpecification(SegmentFunction	outSegFunc,
				       IOPhysicalLength maxSegmentSize = 0,
				       IOPhysicalLength maxTransferSize = 0,
				       IOPhysicalLength alignment = 1);

/*! @function genPhysicalSegments
    @abstract Generates a physical scatter/gather list given a memory descriptor.
    @discussion Generates a list of physical segments from the given memory descriptor, relative to the current position of the descriptor.
    @param descriptor IOMemoryDescriptor that describes the data associated with an I/O request. 
    @param fromPosition Starting location of the I/O within a memory descriptor. 
    @param segments Void pointer to base of output physical scatter/gather list.  Always passed directly onto the SegmentFunction without interpretation by the cursor. 
    @param maxSegments Maximum number of segments that can be written to segments array.
    @param maxTransferSize Maximum transfer size is limited to that many bytes, otherwise it defaults to the maximum transfer size specified when the memory cursor was initialized.
    @param transferSize Pointer to an IOByteCount variable that can contain the total size of the transfer being described.  Defaults to 0 indicating that no transfer size need be returned. 
    @result If the descriptor is exhausted of memory, a zero is returned, otherwise the number of segments that were filled in is returned.
*/
    virtual UInt32 genPhysicalSegments(
				      IOMemoryDescriptor *descriptor,
				      IOByteCount	  fromPosition,
				      void *		  segments,
				      UInt32		  maxSegments,
				      UInt32		  maxTransferSize = 0,
				      IOByteCount	 *transferSize = 0);
};

/************************ class IONaturalMemoryCursor ************************/


/*!
    @class IONaturalMemoryCursor
    @abstract An IOMemoryCursor subclass that outputs a vector of PhysicalSegments in the natural byte orientation for the CPU.  
    @discussion The IONaturalMemoryCursor would be used when it is too difficult to safely describe a SegmentFunction that is more appropriate for your hardware.  This cursor just outputs an array of PhysicalSegments.
*/
class IONaturalMemoryCursor : public IOMemoryCursor
{
    OSDeclareDefaultStructors(IONaturalMemoryCursor)

public:
/*! @function outputSegment
    @abstract Outputs the given segment into the output segments array in natural byte order.
    @param segment The physical address and length that is next to be output.
    @param segments Base of the output vector of DMA address length pairs.
    @param segmentIndex Index to output 'segment' in the 'segments' array.
*/
    static void outputSegment(PhysicalSegment segment,
			      void *	      segments,
			      UInt32	      segmentIndex);

/*! @defined naturalOutputSegment
    @discussion Backward compatibility define for the old global function definition.  See IONaturalMemoryCursor::outputSegment.
*/
#define naturalOutputSegment IONaturalMemoryCursor::outputSegment

/*! @function withSpecification
    @abstract Creates and initializes an IONaturalMemoryCursor in one operation.
    @discussion Factory function to create and initialize an IONaturalMemoryCursor in one operation.  For more information, see IONaturalMemoryCursor::initWithSpecification.
    @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
    @param maxTransferSize Maximum size of an entire transfer.	Defaults to 0 indicating no maximum.
    @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
    @result Returns a new memory cursor if successfully created and initialized, 0 otherwise.
*/
    static IONaturalMemoryCursor * 
	withSpecification(IOPhysicalLength maxSegmentSize,
			  IOPhysicalLength maxTransferSize,
			  IOPhysicalLength alignment = 1);

/*! @function initWithSpecification
    @abstract Primary initializer for the IONaturalMemoryCursor class.
    @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
    @param maxTransferSize Maximum size of an entire transfer.	Defaults to 0 indicating no maximum.
    @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
    @result Returns true if the inherited classes and this instance initialize successfully.
*/
    virtual bool initWithSpecification(IOPhysicalLength	 maxSegmentSize,
				       IOPhysicalLength	 maxTransferSize,
				       IOPhysicalLength	 alignment = 1);


/*! @function getPhysicalSegments
    @abstract Generates a CPU natural physical scatter/gather list given a memory descriptor.
    @discussion Generates a list of physical segments from the given memory descriptor, relative to the current position of the descriptor.  Wraps IOMemoryCursor::genPhysicalSegments.
    @param descriptor IOMemoryDescriptor that describes the data associated with an I/O request. 
    @param fromPosition Starting location of the I/O within a memory descriptor. 
    @param segments Pointer to an array of IOMemoryCursor::PhysicalSegments for the output physical scatter/gather list.
    @param maxSegments Maximum number of segments that can be written to segments array.
    @param inMaxTransferSize Maximum transfer size is limited to that many bytes, otherwise it defaults to the maximum transfer size specified when the memory cursor was initialized.
    @param transferSize Pointer to an IOByteCount variable that can contain the total size of the transfer being described.  Defaults to 0 indicating that no transfer size need be returned. 
    @result If the descriptor is exhausted of memory, a zero is returned, otherwise the number of segments that were filled in is returned.
*/
    virtual UInt32 getPhysicalSegments(IOMemoryDescriptor *descriptor,
				       IOByteCount	   fromPosition,
				       PhysicalSegment	  *segments,
				       UInt32		   maxSegments,
				       UInt32		   inMaxTransferSize = 0,
				       IOByteCount	  *transferSize = 0)
    {
	return genPhysicalSegments(descriptor, fromPosition, segments,
				maxSegments, inMaxTransferSize, transferSize);
    }
};

/************************** class IOBigMemoryCursor **************************/

/*!
    @class IOBigMemoryCursor
    @abstract An IOMemoryCursor subclass that outputs a vector of PhysicalSegments in the big endian byte order.  
    @discussion The IOBigMemoryCursor would be used when the DMA hardware requires a big endian address and length pair.  This cursor outputs an array of PhysicalSegments that are encoded in big-endian format.
*/
class IOBigMemoryCursor : public IOMemoryCursor
{
    OSDeclareDefaultStructors(IOBigMemoryCursor)

public:
/*! @function outputSegment
    @abstract Outputs the given segment into the output segments array in big endian byte order.
    @param segment The physical address and length that is next to be output.
    @param segments Base of the output vector of DMA address length pairs.
    @param segmentIndex Index to output 'segment' in the 'segments' array.
*/
    static void outputSegment(PhysicalSegment segment,
			      void *	      segments,
			      UInt32	      segmentIndex);

/*! @defined bigOutputSegment
    @discussion Backward compatibility define for the old global function definition.  See IOBigMemoryCursor::outputSegment 
*/
#define bigOutputSegment IOBigMemoryCursor::outputSegment

/*! @function withSpecification
    @abstract Creates and initializes an IOBigMemoryCursor in one operation.
    @discussion Factory function to create and initialize an IOBigMemoryCursor in one operation.  See also IOBigMemoryCursor::initWithSpecification.
    @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
    @param maxTransferSize Maximum size of an entire transfer.	Defaults to 0 indicating no maximum.
    @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
    @result Returns a new memory cursor if successfully created and initialized, 0 otherwise.
*/
    static IOBigMemoryCursor *
	withSpecification(IOPhysicalLength maxSegmentSize,
			  IOPhysicalLength maxTransferSize,
			  IOPhysicalLength alignment = 1);

/*! @function initWithSpecification
    @abstract Primary initializer for the IOBigMemoryCursor class.
    @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
    @param maxTransferSize Maximum size of an entire transfer.	Defaults to 0 indicating no maximum.
    @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
    @result Returns true if the inherited classes and this instance initialize
successfully.
*/
    virtual bool initWithSpecification(IOPhysicalLength	 maxSegmentSize,
				       IOPhysicalLength	 maxTransferSize,
				       IOPhysicalLength	 alignment = 1);


/*! @function getPhysicalSegments
    @abstract Generates a big endian physical scatter/gather list given a memory descriptor.
    @discussion Generates a list of physical segments from the given memory descriptor, relative to the current position of the descriptor.  Wraps IOMemoryCursor::genPhysicalSegments.
    @param descriptor IOMemoryDescriptor that describes the data associated with an I/O request. 
    @param fromPosition Starting location of the I/O within a memory descriptor. 
    @param segments Pointer to an array of IOMemoryCursor::PhysicalSegments for the output physical scatter/gather list.
    @param maxSegments Maximum number of segments that can be written to segments array.
    @param inMaxTransferSize Maximum transfer size is limited to that many bytes, otherwise it defaults to the maximum transfer size specified when the memory cursor was initialized.
    @param transferSize Pointer to an IOByteCount variable that can contain the total size of the transfer being described.  Defaults to 0 indicating that no transfer size need be returned. 
    @result If the descriptor is exhausted of memory, a zero is returned, otherwise the number of segments that were filled in is returned.
*/
    virtual UInt32 getPhysicalSegments(IOMemoryDescriptor * descriptor,
				       IOByteCount	    fromPosition,
				       PhysicalSegment *    segments,
				       UInt32		    maxSegments,
				       UInt32		    inMaxTransferSize = 0,
				       IOByteCount	 *  transferSize = 0)
    {
	return genPhysicalSegments(descriptor, fromPosition, segments,
				maxSegments, inMaxTransferSize, transferSize);
    }
};

/************************* class IOLittleMemoryCursor ************************/

/*!
    @class IOLittleMemoryCursor
    @abstract An IOMemoryCursor subclass that outputs a vector of PhysicalSegments in the little endian byte order.  
    @discussion The IOLittleMemoryCursor would be used when the DMA hardware requires a little endian address and length pair.	This cursor outputs an array of PhysicalSegments that are encoded in little endian format.
*/
class IOLittleMemoryCursor : public IOMemoryCursor
{
    OSDeclareDefaultStructors(IOLittleMemoryCursor)

public:
/*! @function outputSegment
    @abstract Outputs the given segment into the output segments array in little endian byte order.
    @param segment The physical address and length that is next to be output.
    @param segments Base of the output vector of DMA address length pairs.
    @param segmentIndex Index to output 'segment' in the 'segments' array.
*/
    static void outputSegment(PhysicalSegment segment,
			      void *	      segments,
			      UInt32	      segmentIndex);

/*! @defined littleOutputSegment
    @discussion Backward compatibility define for the old global function definition.  See also IOLittleMemoryCursor::outputSegment. */
#define littleOutputSegment IOLittleMemoryCursor::outputSegment

/*! @function withSpecification
    @abstract Creates and initializes an IOLittleMemoryCursor in one operation.
    @discussion Factory function to create and initialize an IOLittleMemoryCursor in one operation.  See also IOLittleMemoryCursor::initWithSpecification.
    @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
    @param maxTransferSize Maximum size of an entire transfer.	Defaults to 0 indicating no maximum.
    @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
    @result Returns a new memory cursor if successfully created and initialized, 0 otherwise.
*/
    static IOLittleMemoryCursor *
	withSpecification(IOPhysicalLength maxSegmentSize,
			  IOPhysicalLength maxTransferSize,
			  IOPhysicalLength alignment = 1);

/*! @function initWithSpecification
    @abstract Primary initializer for the IOLittleMemoryCursor class.
    @param maxSegmentSize Maximum allowable size for one segment.  Defaults to 0.
    @param maxTransferSize Maximum size of an entire transfer.	Defaults to 0 indicating no maximum.
    @param alignment Alignment restrictions on output physical addresses.  Not currently implemented.  Defaults to single byte alignment.
    @result Returns true if the inherited classes and this instance initialize successfully.
*/
    virtual bool initWithSpecification(IOPhysicalLength	 maxSegmentSize,
				       IOPhysicalLength	 maxTransferSize,
				       IOPhysicalLength	 alignment = 1);


/*! @function getPhysicalSegments
    @abstract Generates a little endian physical scatter/gather list given a memory descriptor.
    @discussion Generates a list of physical segments from the given memory descriptor, relative to the current position of the descriptor.  Wraps IOMemoryCursor::genPhysicalSegments.
    @param descriptor IOMemoryDescriptor that describes the data associated with an I/O request. 
    @param fromPosition Starting location of the I/O within a memory descriptor. 
    @param segments Pointer to an array of IOMemoryCursor::PhysicalSegments for the output physical scatter/gather list.
    @param maxSegments Maximum number of segments that can be written to segments array.
    @param inMaxTransferSize Maximum transfer size is limited to that many bytes, otherwise it defaults to the maximum transfer size specified when the memory cursor was initialized.
    @param transferSize Pointer to an IOByteCount variable that can contain the total size of the transfer being described.  Defaults to 0 indicating that no transfer size need be returned. 
    @result If the descriptor is exhausted of memory, a zero is returned, otherwise the number of segments that were filled in is returned.
*/
    virtual UInt32 getPhysicalSegments(IOMemoryDescriptor * descriptor,
				       IOByteCount	    fromPosition,
				       PhysicalSegment *    segments,
				       UInt32		    maxSegments,
				       UInt32		    inMaxTransferSize = 0,
				       IOByteCount	 *  transferSize = 0)
    {
	return genPhysicalSegments(descriptor, fromPosition, segments,
				maxSegments, inMaxTransferSize, transferSize);
    }
};

#endif /* !_IOMEMORYCURSOR_H */