for more information on manipulating the command's doubly linked list entries.
The IODMACommand can be used in a 'weak-linked' manner. To do this you must avoid using any static member functions. Use the much slower but safe weakWithSpecification function. On success a DMA command instance will be returned. This instance can then be used to clone as many commands as is needed. Remember deriving from this class cannot be done weakly, in other words, no weak subclassing!
Functions
- clearMemoryDescriptor
Clears the DMACommand's current memory descriptor
- cloneCommand
Creates a new command based on the specification of the current one.
- complete
Complete processing of DMA mappings after an I/O transfer is finished.
- gen32IOVMSegments
Helper function for a type checked call to genIOVMSegments(qv), for use with an IODMACommand set up with the output function kIODMACommandOutputHost32, kIODMACommandOutputBig32, or kIODMACommandOutputLittle32. If the output function of the IODMACommand is not a 32 bit function, results will be incorrect.
- gen64IOVMSegments
Helper function for a type checked call to genIOVMSegments(qv), for use with an IODMACommand set up with the output function kIODMACommandOutputHost64, kIODMACommandOutputBig64, or kIODMACommandOutputLittle64. If the output function of the IODMACommand is not a 64 bit function, results will be incorrect.
- genIOVMSegments
Generates a physical scatter/gather for the current DMA command
- getMemoryDescriptor
Get the current memory descriptor
- initWithSpecification
Primary initializer for the IODMACommand class.
- OutputBig32
Output big-endian Segment32 output segment function.
- OutputBig64
Output big-endian Segment64 output segment function.
- OutputHost32
Output host natural Segment32 output segment function.
- OutputHost64
Output host natural Segment64 output segment function.
- OutputLittle32
Output little-endian Segment32 output segment function.
- OutputLittle64
Output little-endian Segment64 output segment function.
- prepare
Prepare the memory for an I/O transfer.
- prepareWithSpecification
Prepare the memory for an I/O transfer with a new specification.
- readBytes
Copy data from the IODMACommand's buffer to the specified buffer.
- setMemoryDescriptor
Sets and resets the DMACommand's current memory descriptor
- synchronize
Bring IOMemoryDescriptor and IODMACommand buffers into sync.
- weakWithSpecification
Creates and initializes an IODMACommand in one operation if this version of the operating system supports it.
- withSpecification
Creates and initializes an IODMACommand in one operation.
- writeBytes
Copy data to the IODMACommand's buffer from the specified buffer.
Clears the DMACommand's current memory descriptor
public
virtual IOReturn clearMemoryDescriptor(
bool autoComplete = true);
Parameters
autoComplete
An optional boolean variable that will call the complete() function automatically before the memory descriptor is processed. Defaults to true.
Discussion
completes and invalidates the cache if the DMA command is currently active, copies all data from bounce buffers if necessary and releases all resources acquired during setMemoryDescriptor.
Creates a new command based on the specification of the current one.
public
virtual IODMACommand *cloneCommand(
void *refCon = 0);
Return Value
Returns a new IODMACommand object if successfully created and initialized, 0 otherwise.
Discussion
Factory function to create and initialize an IODMACommand in one operation. The current command's specification will be duplicated in the new object, but none of its state will be duplicated. This means that it is safe to clone a command even if it is currently active and running, however you must be certain that the command to be duplicated does have a valid reference for the duration.
Complete processing of DMA mappings after an I/O transfer is finished.
public
virtual IOReturn complete(
bool invalidateCache = true,
bool synchronize = true);
Parameters
invalidCache
Invalidate the caches for the memory descriptor. Defaults to true for kNonCoherent and is ignored by the other types.
synchronize
Copy any buffered data back to the target IOMemoryDescriptor. Defaults to true, if synchronize() is being used to explicitly copy data, passing false may avoid an unneeded copy.
Return Value
kIOReturnNotReady if not prepared, kIOReturnSuccess otherwise.
Discussion
This method should not be called unless a prepare was previously issued; the prepare() and complete() must occur in pairs, before and after an I/O transfer
Helper function for a type checked call to genIOVMSegments(qv), for use with an IODMACommand set up with the output function kIODMACommandOutputHost32, kIODMACommandOutputBig32, or kIODMACommandOutputLittle32. If the output function of the IODMACommand is not a 32 bit function, results will be incorrect.
public
inline IOReturn gen32IOVMSegments(
UInt64 *offset,
Segment32 *segments,
UInt32 *numSegments) ;
Helper function for a type checked call to genIOVMSegments(qv), for use with an IODMACommand set up with the output function kIODMACommandOutputHost64, kIODMACommandOutputBig64, or kIODMACommandOutputLittle64. If the output function of the IODMACommand is not a 64 bit function, results will be incorrect.
public
inline IOReturn gen64IOVMSegments(
UInt64 *offset,
Segment64 *segments,
UInt32 *numSegments) ;
Generates a physical scatter/gather for the current DMA command
public
virtual IOReturn genIOVMSegments(
UInt64 *offset,
void *segments,
UInt32 *numSegments);
Parameters
offset
input/output parameter, defines the starting and ending offset in the memory descriptor, relative to any offset passed to the prepare() method.
segments
Void pointer to base of output physical scatter/gather list. Always passed directly onto the SegmentFunction.
numSegments
Input/output parameter Number of segments that can fit in the segment array and returns number of segments generated.
Return Value
kIOReturnSuccess on success, kIOReturnOverrun if the memory descriptor is exhausted, kIOReturnMessageTooLarge if the output segment function's address bits has insufficient resolution for a segment, kIOReturnNotReady if the DMA command has not be prepared, kIOReturnBadArgument if the DMA command doesn't have a memory descriptor yet or some of the parameters are NULL and kIOReturnNotReady if the DMA command is not prepared.
Discussion
Generates a list of physical segments from the given memory descriptor, relative to the current position of the descriptor. The constraints that are set during initialisation will be respected. This function maintains the state across multiple calls for efficiency. However the state is discarded if the new offset is not the expected one.
Get the current memory descriptor
public
virtual const IOMemoryDescriptor *getMemoryDescriptor() const;
Primary initializer for the IODMACommand class.
public
virtual bool initWithSpecification(
SegmentFunction outSegFunc,
UInt8 numAddressBits,
UInt64 maxSegmentSize,
MappingOptions mappingOptions = kMapped,
UInt64 maxTransferSize = 0,
UInt32 alignment = 1,
IOMapper *mapper = 0,
void *refCon = 0);
Parameters
outSegFunc
SegmentFunction to call to output one physical segment. A set of nine commonly required segment functions are provided.
numAddressBits
Number of bits that the hardware uses on its internal address bus. Typically 32 but may be more on modern hardware. A 0 implies no restriction other than that implied by the output segment function.
maxSegmentSize
Maximum allowable size for one segment. Defaults to 0, which means any size.
mappingOptions
The type of mapping that is required to translate an IOMemoryDescriptor into the desired number of bits. For example, if your hardware only supports 32 bits but must run on machines with > 4G of RAM some mapping will be required. Number of bits will be specified in numAddressBits
, see below.This parameter can take 3 values- kNonCoherent
- used for non-coherent hardware transfers, Mapped
- validates that all I/O bus generated addresses are within the number of addressing bits specified, Bypassed
indicates that bypassed addressing is required (this is used when the hardware transferes are into coherent memory but no mapping is required). See prepare for failure cases.
maxTransferSize
Maximum size of an entire transfer. Defaults to 0 indicating no maximum.
alignment
Alignment restriction, in bytes, on I/O bus addresses. Defaults to single byte alignment. Not currently implemented.
mapper
For mapping types kMapped
and kBypassed
mapper is used to define the hardware that will perform the mapping, defaults to the system mapper.
Return Value
Can fail if the mapping type is not recognized, if one of the 3 mandatory parameters are set to 0, if a 32 bit output function is selected when more than 32 bits of address is required or, if kBypassed
is requested on a machine that doesn't support bypassing. Returns true otherwise.
Output big-endian Segment32 output segment function.
public
static bool OutputBig32(
IODMACommand *target,
Segment64 seg,
void *segs,
UInt32 ind);
Output big-endian Segment64 output segment function.
public
static bool OutputBig64(
IODMACommand *target,
Segment64 seg,
void *segs,
UInt32 ind);
Output host natural Segment32 output segment function.
public
static bool OutputHost32(
IODMACommand *target,
Segment64 seg,
void *segs,
UInt32 ind);
Output host natural Segment64 output segment function.
public
static bool OutputHost64(
IODMACommand *target,
Segment64 seg,
void *segs,
UInt32 ind);
Output little-endian Segment32 output segment function.
public
static bool OutputLittle32(
IODMACommand *target,
Segment64 seg,
void *segs,
UInt32 ind);
Output little-endian Segment64 output segment function.
public
static bool OutputLittle64(
IODMACommand *target,
Segment64 seg,
void *segs,
UInt32 ind);
Prepare the memory for an I/O transfer.
public
virtual IOReturn prepare(
UInt64 offset = 0,
UInt64 length = 0,
bool flushCache = true,
bool synchronize = true);
Parameters
offset
defines the starting offset in the memory descriptor the DMA command will operate on. genIOVMSegments will produce its results based on the offset and length passed to the prepare method.
length
defines the ending position in the memory descriptor the DMA command will operate on. genIOVMSegments will produce its results based on the offset and length passed to the prepare method.
flushCache
Flush the caches for the memory descriptor and make certain that the memory cycles are complete. Defaults to true for kNonCoherent and is ignored by the other types.
synchronize
Copy any buffered data back from the target IOMemoryDescriptor. Defaults to true, if synchronize() is being used to explicitly copy data, passing false may avoid an unneeded copy.
Return Value
An IOReturn code.
Discussion
Allocate the mapping resources neccessary for this transfer, specifying a sub range of the IOMemoryDescriptor that will be the target of the I/O. The complete() method frees these resources. Data may be copied to buffers for kIODirectionOut memory descriptors, depending on hardware mapping resource availabilty or alignment restrictions. It should be noted that the this function may block and should only be called on the clients context, i.e never call this routine while gated; also the call itself is not thread safe though this should be an issue as each IODMACommand is independant.
Prepare the memory for an I/O transfer with a new specification.
public
virtual IOReturn prepareWithSpecification(
SegmentFunction outSegFunc,
UInt8 numAddressBits,
UInt64 maxSegmentSize,
MappingOptions mappingOptions = kMapped,
UInt64 maxTransferSize = 0,
UInt32 alignment = 1,
IOMapper *mapper = 0,
UInt64 offset = 0,
UInt64 length = 0,
bool flushCache = true,
bool synchronize = true);
Parameters
outSegFunc
SegmentFunction to call to output one physical segment. A set of nine commonly required segment functions are provided.
numAddressBits
Number of bits that the hardware uses on its internal address bus. Typically 32 but may be more on modern hardware. A 0 implies no-restriction other than that implied by the output segment function.
maxSegmentSize
Maximum allowable size for one segment. Defaults to 0 which means any size.
mappingOptions
is the type of mapping that is required to translate an IOMemoryDescriptor into the desired number of bits. For instance if your hardware only supports 32 bits but must run on machines with > 4G of RAM some mapping will be required. Number of bits will be specified in numAddressBits, see below.This parameter can take 3 values:- kNonCoherent - used for non-coherent hardware transfers, Mapped - Validate that all I/O bus generated addresses are within the number of addressing bits specified, Bypassed indicates that bypassed addressing is required, this is used when the hardware transferes are into coherent memory but no mapping is required. See also prepare() for failure cases.
maxTransferSize
Maximum size of an entire transfer. Defaults to 0 indicating no maximum.
alignment
Alignment restriction, in bytes, on I/O bus addresses. Defaults to single byte alignment.
mapper
For mapping types kMapped & kBypassed mapper is used to define the hardware that will perform the mapping, defaults to the system mapper.
offset
defines the starting offset in the memory descriptor the DMA command will operate on. genIOVMSegments will produce its results based on the offset and length passed to the prepare method.
length
defines the ending position in the memory descriptor the DMA command will operate on. genIOVMSegments will produce its results based on the offset and length passed to the prepare method.
flushCache
Flush the caches for the memory descriptor and make certain that the memory cycles are complete. Defaults to true for kNonCoherent and is ignored by the other types.
synchronize
Copy any buffered data back from the target IOMemoryDescriptor. Defaults to true, if synchronize() is being used to explicitly copy data, passing false may avoid an unneeded copy.
Return Value
An IOReturn code. Can fail if the mapping type is not recognised, if one of the 3 mandatory parameters are set to 0, if a 32 bit output function is selected when more than 32 bits of address is required or, if kBypassed is requested on a machine that doesn't support bypassing.
Discussion
Allocate the mapping resources neccessary for this transfer, specifying a sub range of the IOMemoryDescriptor that will be the target of the I/O. The complete() method frees these resources. Data may be copied to buffers for kIODirectionOut memory descriptors, depending on hardware mapping resource availabilty or alignment restrictions. It should be noted that the this function may block and should only be called on the clients context, i.e never call this routine while gated; also the call itself is not thread safe though this should be an issue as each IODMACommand is independant.
Copy data from the IODMACommand's buffer to the specified buffer.
public
UInt64 readBytes(
UInt64 offset,
void *bytes,
UInt64 length);
Parameters
offset
A byte offset into the IODMACommand's memory, relative to the prepared offset.
bytes
The caller supplied buffer to copy the data to.
length
The length of the data to copy.
Return Value
The number of bytes copied, zero will be returned if the specified offset is beyond the prepared length of the IODMACommand.
Discussion
This method copies data from the IODMACommand's memory at the given offset, to the caller's buffer. The IODMACommand must be prepared, and the offset is relative to the prepared offset.
Sets and resets the DMACommand's current memory descriptor
public
virtual IOReturn setMemoryDescriptor(
const IOMemoryDescriptor *mem,
bool autoPrepare = true);
Parameters
mem
A pointer to the current I/Os memory descriptor.
autoPrepare
An optional boolean variable that will call the prepare() function automatically after the memory descriptor is processed. Defaults to true.
Return Value
Returns kIOReturnSuccess, kIOReturnBusy if currently prepared, kIOReturnNoSpace if the length(mem) >= Maximum Transfer Size or the error codes returned by prepare() (qv).
Discussion
The DMA command will configure itself based on the information that it finds in the memory descriptor. It looks for things like the direction of the memory descriptor and whether the current memory descriptor is already mapped into some IOMMU. As a programmer convenience it can also prepare the memory descriptor immediately. See prepare(). Note the IODMACommand is designed to used multiple times with a succession of memory descriptors, making the pooling of commands possible. It is an error though to attempt to reset a currently prepared() DMA command. Warning: This routine may block so never try to autoprepare an IODMACommand while in a gated context, i.e. one of the WorkLoops action call outs.
Bring IOMemoryDescriptor and IODMACommand buffers into sync.
public
virtual IOReturn synchronize(
IOOptionBits options);
Parameters
options
Specifies the direction of the copy:
kIODirectionOut copy IOMemoryDesciptor memory to any IODMACommand buffers. By default this action takes place automatically at prepare().
kIODirectionIn copy any IODMACommand buffers back to the IOMemoryDescriptor. By default this action takes place automatically at complete().
kForceDoubleBuffer copy the entire prepared range to a new page aligned buffer.
Return Value
kIOReturnNotReady if not prepared, kIOReturnBadArgument if invalid options are passed, kIOReturnSuccess otherwise.
Discussion
This method should not be called unless a prepare was previously issued. If needed a caller may synchronize any IODMACommand buffers with the original IOMemoryDescriptor buffers.
Creates and initializes an IODMACommand in one operation if this version of the operating system supports it.
public
static inline IOReturn weakWithSpecification (
IODMACommand **newCommand,
SegmentFunction outSegFunc,
UInt8 numAddressBits,
UInt64 maxSegmentSize,
MappingOptions mapType = kMapped,
UInt64 maxTransferSize = 0,
UInt32 alignment = 1,
IOMapper *mapper = 0,
void *refCon = 0) __attribute__((always_inline));
Parameters
newCommand
Output reference variable of the newly created IODMACommand.
outSegFunc
SegmentFunction to call to output one physical segment. A set of nine commonly required segment functions are provided.
numAddressBits
Number of bits that the hardware uses on its internal address bus. Typically 32 but may be more on modern hardware. A 0 implies no restriction other than that implied by the output segment function.
maxSegmentSize
Maximum allowable size for one segment. Defaults to 0, which means any size.
mapType
The type of mapping that is required to translate an IOMemoryDescriptor into the desired number of bits. For example, if your hardware only supports 32 bits but must run on machines with > 4G of RAM some mapping will be required. Number of bits will be specified in numAddressBits
, see below. This parameter can take 3 values: kNonCoherent
- used for non-coherent hardware transfers, Mapped
- validates that all I/O bus generated addresses are within the number of addressing bits specified, Bypassed
- indicates that bypassed addressing is required (this is used when the hardware transfers are into coherent memory but no mapping is required). See prepare for failure cases.
maxTransferSize
Maximum size of an entire transfer. Defaults to 0 indicating no maximum.
alignment
Alignment restriction, in bytes, on I/O bus addresses. Defaults to single byte alignment. Not currently implemented.
mapper
For mapping types kMapped
and kBypassed
mapper is used to define the hardware that will perform the mapping, defaults to the system mapper.
Return Value
kIOReturnSuccess if everything is OK, otherwise kIOReturnBadArgument
if newCommand
is NULL; kIOReturnUnsupported
if the kernel doesn't export IODMACommand; IOReturnError
if the new command fails to init (see initWithSpecification).
Discussion
Factory function to create and initialize an IODMACommand in one operation. The function allows a developer to 'weak' link with IODMACommand. This function will return kIOReturnUnsupported if the IODMACommand is unavailable. This function is actually fairly slow so it will be better to call it once and then clone the successfully created command using cloneCommand.
Creates and initializes an IODMACommand in one operation.
public
static IODMACommand * withSpecification(
SegmentFunction outSegFunc,
UInt8 numAddressBits,
UInt64 maxSegmentSize,
MappingOptions mappingOptions = kMapped,
UInt64 maxTransferSize = 0,
UInt32 alignment = 1,
IOMapper *mapper = 0,
void *refCon = 0);
Parameters
outSegFunc
SegmentFunction to call to output one physical segment. A set of nine commonly required segment functions are provided.
numAddressBits
Number of bits that the hardware uses on its internal address bus. Typically 32 but may be more on modern hardware. A 0 implies no restriction other than that implied by the output segment function.
maxSegmentSize
Maximum allowable size for one segment. Defaults to 0, which means any size.
mappingOptions
The type of mapping that is required to translate an IOMemoryDescriptor into the desired number of bits. For example, if your hardware only supports 32 bits but must run on machines with > 4G of RAM some mapping will be required. Number of bits will be specified in numAddressBits, see below. This parameter can take 3 values: kNonCoherent
- used for non-coherent hardware transfers, Mapped
- validates that all I/O bus generated addresses are within the number of addressing bits specified, Bypassed
- bypassed addressing is required (this is used when the hardware transfers are into coherent memory but no mapping is required). See prepare for failure cases.
maxTransferSize
Maximum size of an entire transfer. Defaults to 0 indicating no maximum.
alignment
Alignment restriction, in bytes, on I/O bus addresses. Defaults to single byte alignment. Not currently implemented.
mapper
For mapping types kMapped
and kBypassed
mapper is used to define the hardware that will perform the mapping. Defaults to the system mapper.
Return Value
Returns a new IODMACommand object if successfully created and initialized, 0 otherwise.
Discussion
Factory function to create and initialize an IODMACommand in one operation.
Copy data to the IODMACommand's buffer from the specified buffer.
public
UInt64 writeBytes(
UInt64 offset,
const void *bytes,
UInt64 length);
Parameters
offset
A byte offset into the IODMACommand's memory, relative to the prepared offset.
bytes
The caller supplied buffer to copy the data from.
length
The length of the data to copy.
Return Value
The number of bytes copied, zero will be returned if the specified offset is beyond the prepared length of the IODMACommand.
Discussion
This method copies data to the IODMACommand's memory at the given offset, from the caller's buffer. The IODMACommand must be prepared, and the offset is relative to the prepared offset.
Typedefs
See Also:
-
Segment32
-
Segment64
-
MappingOptions
-
SegmentFunction
public
typedef bool ( *SegmentFunction)(
IODMACommand *target,
Segment64 segment,
void *segments,
UInt32 segmentIndex);
Discussion
A 32-bit I/O bus address/length pair
See Also:
-
Segment32
-
Segment64
-
MappingOptions
-
Segment32
public
typedef bool ( *SegmentFunction)(
IODMACommand *target,
Segment64 segment,
void *segments,
UInt32 segmentIndex);
Discussion
A 32-bit I/O bus address/length pair
public
typedef bool ( *SegmentFunction)(
IODMACommand *target,
Segment64 segment,
void *segments,
UInt32 segmentIndex);
Parameters
segment
The 64Bit I/O bus address and length.
segments
Base of the output vector of DMA address length pairs.
segmentIndex
Index to output 'segment' in the 'segments' array.
Return Value
Returns true if segment encoding succeeded. False may be returned if the current segment does not fit in an output segment, i.e. a 38-bit address won't fit into a 32 encoding.
Discussion
Pointer to a C function that translates a 64 segment and outputs a single desired segment to the array at the requested index. There are a group of pre-implemented SegmentFunctions that may be usefull to the developer below.
Structs and Unions
See Also:
-
Segment64
-
MappingOptions
-
Segment32
-
SegmentFunction
public
struct Segment32 {
UInt32 fIOVMAddr, fLength;
};
Discussion
A 32-bit I/O bus address/length pair
See Also:
-
Segment32
-
MappingOptions
-
Segment32
-
SegmentFunction
public
struct Segment64 {
UInt64 fIOVMAddr, fLength;
};
Discussion
A 32-bit I/O bus address/length pair
Member Data
protected
UInt32 fActive;
Discussion
fActive indicates that this DMA command is currently prepared and ready to go
protected
UInt32 fAlignMask;
Discussion
Alignment restriction mask.
protected
UInt64 fBypassMask;
Discussion
Mask to be OR'ed into the address to bypass the given IOMMU's mapping.
protected
IOMapper *fMapper;
Discussion
Client defined mapper.
protected
MappingOptions fMappingOptions;
Discussion
What type of I/O virtual address mapping is required for this command
protected
UInt64 fMaxSegmentSize;
Discussion
Maximum size of one segment in a scatter/gather list.
protected
UInt64 fMaxTransferSize;
Discussion
Maximum size of a transfer that this memory cursor is allowed to generate.
protected
const IOMemoryDescriptor *fMemory;
Discussion
memory descriptor for current I/O.
protected
UInt32 fNumAddressBits;
Discussion
Number of bits that the hardware can address
protected
UInt32 fNumSegments;
Discussion
Number of contiguous segments required for the current memory descriptor and desired mapping
protected
SegmentFunction fOutSeg;
Discussion
The action method called when an event has been delivered
public
void *fRefCon;
Discussion
Reference constant, client defined, publicly available
protected
struct IODMACommandInternal * reserved;
Discussion
Reserved for future use. (Internal use only)
Enumerations
See Also:
-
Segment32
-
Segment64
-
Segment32
-
SegmentFunction
public
enum MappingOptions {
kMapped = 0x00000000,
kBypassed = 0x00000001,
kNonCoherent = 0x00000002,
kTypeMask = 0x0000000f,
kNoCacheStore = 0x00000010,
kOnChip = 0x00000020,
};
Discussion
A 32-bit I/O bus address/length pair
#defines
Output big-endian Segment32 output segment function.
#define kIODMACommandOutputBig32
Output little-endian Segment64 output segment function.
See Also:
-
kIODMACommandOutputLittle64
#define kIODMACommandOutputBig64
Output big-endian Segment64 output segment function.
See Also:
-
kIODMACommandOutputLittle64
#define kIODMACommandOutputLittle64
Output host natural Segment32 output segment function.
#define kIODMACommandOutputHost32
Output host natural Segment64 output segment function.
#define kIODMACommandOutputHost64
Output little-endian Segment32 output segment function.
#define kIODMACommandOutputLittle32
Output little-endian Segment64 output segment function.
See Also:
-
kIODMACommandOutputBig64
#define kIODMACommandOutputBig64
Output big-endian Segment64 output segment function.
See Also:
-
kIODMACommandOutputBig64
#define kIODMACommandOutputLittle64
|
Did this document help you? |
Yes: Tell us what works for you.
|
|