IOKit/IODMACommand.h Kernel.framework

@function OutputHost32 @abstract Output host natural Segment32 output segment function.

@function OutputBig32 @abstract Output big-endian Segment32 output segment function.

@function OutputLittle32 @abstract Output little-endian Segment32 output segment function.

@function OutputHost64 @abstract Output host natural Segment64 output segment function.

@function OutputBig64 @abstract Output big-endian Segment64 output segment function.

@function OutputLittle64 @abstract Output little-endian Segment64 output segment function.

static OSPtr<IODMACommand> withSpecification(
	SegmentFunction outSegFunc,
	UInt8 numAddressBits,
	UInt64 maxSegmentSize,
	MappingOptions mappingOptions = kMapped,
	UInt64 maxTransferSize = 0,
	UInt32 alignment = 1,
	IOMapper *mapper = NULL,
	void *refCon = NULL
)

@function withSpecification @abstract Creates and initializes an IODMACommand in one operation. @discussion Factory function to create and initialize an IODMACommand in one operation. @param outSegFunc SegmentFunction to call to output one physical segment. A set of nine commonly required segment functions are provided. @param 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. @param maxSegmentSize Maximum allowable size for one segment. If 0 is passed the maximum segment size is unlimited. @param 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. @param maxTransferSize Maximum size of an entire transfer. Defaults to 0 indicating no maximum. @param alignment Alignment restriction, in bytes, on I/O bus addresses. Defaults to single byte alignment. @param mapper For mapping types kMapped & kBypassed mapper is used to define the hardware that will perform the mapping, defaults to the system mapper. @param refCon Reference Constant @result Returns a new IODMACommand if successfully created and initialized, 0 otherwise.

__attribute__((always_inline))
static inline IOReturn weakWithSpecification(
	IODMACommand **newCommand,
	SegmentFunction outSegFunc,
	UInt8 numAddressBits,
	UInt64 maxSegmentSize,
	MappingOptions mapType = kMapped,
	UInt64 maxTransferSize = 0,
	UInt32 alignment = 1,
	IOMapper *mapper = NULL,
	void *refCon = NULL
)

@function weakWithSpecification @abstract Creates and initialises an IODMACommand in one operation if this version of the operating system supports it. @discussion Factory function to create and initialise 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 then clone the successfully create command using cloneCommand (q.v.). @param newCommand Output reference variable of the newly created IODMACommand. @param outSegFunc SegmentFunction to call to output one physical segment. A set of nine commonly required segment functions are provided. @param 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. @param maxSegmentSize Maximum allowable size for one segment. Zero is treated as an unlimited segment size. @param mapType 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 transfers are into coherent memory but no mapping is required. See also prepare() for failure cases. @param maxTransferSize Maximum size of an entire transfer. Defaults to 0 indicating no maximum. @param alignment Alignment restriction, in bytes, on I/O bus addresses. Defaults to single byte alignment. @param mapper For mapping types kMapped & kBypassed mapper is used to define the hardware that will perform the mapping, defaults to the system mapper. @param refCon Reference Constant @result kIOReturnSuccess if everything is OK, otherwise kIOReturnBadArgument if newCommand is NULL, kIOReturnUnsupported if the kernel doesn't export IODMACommand or IOReturnError if the new command fails to init, q.v. initWithSpecification. Note that the function has the attribute always_inline. The point of this function is to make a call into the kernel without generating an undefined symbol. If the client could call the code as a function then the goal of no undefined symbols would be lost thus defeating the purpose.

@function withRefCon @abstract Creates and initializes an unspecified IODMACommand. @discussion Factory function to create and initialize an unspecified IODMACommand. prepareWithSpecification() must be used to prepare the IODMACommand before use. @param refCon Reference Constant @result Returns a new IODMACommand if successfully created and initialized, 0 otherwise.

@function cloneCommand @abstract Creates a new command based on the specification of the current one. @discussion Factory function to create and initialise an IODMACommand in one operation. The current command's specification will be duplicated in the new object, but however 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. @result Returns a new IODMACommand if successfully created and initialised, 0 otherwise.

virtual bool initWithSpecification(
	SegmentFunction outSegFunc,
	UInt8 numAddressBits,
	UInt64 maxSegmentSize,
	MappingOptions mappingOptions = kMapped,
	UInt64 maxTransferSize = 0,
	UInt32 alignment = 1,
	IOMapper *mapper = NULL,
	void *refCon = NULL
)

@function initWithSpecification @abstract Primary initializer for the IODMACommand class. @param outSegFunc SegmentFunction to call to output one physical segment. A set of nine commonly required segment functions are provided. @param 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. @param maxSegmentSize Maximum allowable size for one segment. Defaults to 0 which means any size. @param 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. @param maxTransferSize Maximum size of an entire transfer. Defaults to 0 indicating no maximum. @param alignment Alignment restriction, in bytes, on I/O bus addresses. Defaults to single byte alignment. @param mapper For mapping types kMapped & kBypassed mapper is used to define the hardware that will perform the mapping, defaults to the system mapper. @param refCon Reference Constant @result 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. Returns true otherwise.

virtual IOReturn setMemoryDescriptor(
	const IOMemoryDescriptor *mem,
	bool autoPrepare = true
)

@function setMemoryDescriptor @abstract Sets and resets the DMACommand's current memory descriptor @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 DMA command 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. @param mem A pointer to the current I/Os memory descriptor. @param autoPrepare An optional boolean variable that will call the prepare() function automatically after the memory descriptor is processed. Defaults to true. @result Returns kIOReturnSuccess, kIOReturnBusy if currently prepared, kIOReturnNoSpace if the length(mem) >= Maximum Transfer Size, kIOReturnCannotLock if called from the interrupt context or with a spinlock held, or the error codes returned by prepare() (qv).

@function clearMemoryDescriptor @abstract Clears the DMACommand's current memory descriptor @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. @param autoComplete An optional boolean variable that will call the complete() function automatically before the memory descriptor is processed. Defaults to true.

@function getMemoryDescriptor @abstract Get the current memory descriptor

@function getIOMemoryDescriptor @abstract Get the memory descriptor to be used for DMA

@function genIOVMSegments @abstract Generates a physical scatter/gather for the current DMA command @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. @param offset input/output parameter, defines the starting and ending offset in the memory descriptor, relative to any offset passed to the prepare() method. @param segments Void pointer to base of output physical scatter/gather list. Always passed directly onto the SegmentFunction. @param numSegments Input/output parameter Number of segments that can fit in the segment array and returns number of segments generated. @result 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.

inline IOReturn gen32IOVMSegments(
	UInt64 *offset,
	Segment32 *segments,
	UInt32 *numSegments
)

@function gen32IOVMSegments @abstract 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.

inline IOReturn gen64IOVMSegments(
	UInt64 *offset,
	Segment64 *segments,
	UInt32 *numSegments
)

@function gen64IOVMSegments @abstract 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.