prepare

Prepare the memory for an I/O transfer.

Declaration

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.

Overview

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.

See Also

Miscellaneous

- 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

- getPreparedOffsetAndLength

Returns the offset and length into the target IOMemoryDescriptor of a prepared IODDMACommand.

- 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.

- 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 initialises 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.