/* * Copyright (c) 1998-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@ */ #ifndef _IOMEMORYCURSOR_H #define _IOMEMORYCURSOR_H #include <libkern/c++/OSObject.h> #include <libkern/c++/OSPtr.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 OSPtr<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 = NULL); }; /************************ 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 OSPtr<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 = NULL) { 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 OSPtr<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 = NULL) { 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 OSPtr<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 = NULL) { return genPhysicalSegments(descriptor, fromPosition, segments, maxSegments, inMaxTransferSize, transferSize); } }; #endif /* !_IOMEMORYCURSOR_H */