withSpecification

Creates and initializes an IODMACommand in one operation.

Declaration

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. If 0 is passed the maximum segment size is unlimited.

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.

Return Value

Returns a new memory cursor if successfully created and initialized, 0 otherwise.

Overview

Factory function to create and initialize an IODMACommand in one operation.

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.

- 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 initialises an IODMACommand in one operation if this version of the operating system supports it.

- writeBytes

Copy data to the IODMACommand's buffer from the specified buffer.