IOMultiMemoryDescriptor

Inherits from
IOMemoryDescriptor
Availability
Available in OS X v10.0 and later.
Declared in
IOMultiMemoryDescriptor.h

Overview

The IOMultiMemoryDescriptor object describes a memory area made up of several other IOMemoryDescriptors.

The IOMultiMemoryDescriptor object represents multiple ranges of memory, specified as an ordered list of IOMemoryDescriptors. The descriptors are chained end-to-end to make up a single contiguous buffer.

Tasks

Miscellaneous

Instance Methods

complete

Complete processing of the memory after an I/O transfer finishes.

virtual IOReturn complete( IODirection forDirection = kIODirectionNone);
Parameters
forDirection

The direction of the I/O just completed, or kIODirectionNone for the direction specified by the memory descriptor.

Return Value

An IOReturn code.

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 involving pageable memory.

getPhysicalSegment

Break a memory descriptor into its physically contiguous segments.

virtual addr64_t getPhysicalSegment( IOByteCount offset, IOByteCount *length, IOOptionBits options = 0 );
Parameters
offset

A byte offset into the memory whose physical address to return.

length

If non-zero, getPhysicalSegment will store here the length of the physically contiguous segement at the given offset.

Return Value

A physical address, or zero if the offset is beyond the length of the memory.

Discussion

This method returns the physical address of the byte at the given offset into the memory, and optionally the length of the physically contiguous segment from that offset.

initWithDescriptors

Initialize an IOMultiMemoryDescriptor to describe a memory area made up of several other IOMemoryDescriptors.

virtual bool initWithDescriptors( IOMemoryDescriptor **descriptors, UInt32 withCount, IODirection withDirection, bool asReference = false );
Parameters
descriptors

An array of IOMemoryDescriptors which make up the memory to be described.

withCount

The object count for the descriptors array.

withDirection

An I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.

asReference

If false, the IOMultiMemoryDescriptor object will make a copy of the descriptors array, otherwise, the array will be used in situ, avoiding an extra allocation.

Return Value

The created IOMultiMemoryDescriptor on success, to be released by the caller, or zero on failure.

Discussion

This method initializes an IOMultiMemoryDescriptor for memory consisting of a number of other IOMemoryDescriptors, chained end-to-end (in the order they appear in the array) to represent a single contiguous memory buffer. Passing the descriptor array as a reference will avoid an extra allocation.

prepare

Prepare the memory for an I/O transfer.

virtual IOReturn prepare( IODirection forDirection = kIODirectionNone);
Parameters
forDirection

The direction of the I/O just completed, or kIODirectionNone for the direction specified by the memory descriptor.

Return Value

An IOReturn code.

Discussion

This involves paging in the memory, if necessary, and wiring it down for the duration of the transfer. The complete() method completes the processing of the memory after the I/O transfer finishes. This method needn't called for non-pageable memory.

withDescriptors(IOMemoryDescriptor **, UInt32, IODirection, bool)

Create an IOMultiMemoryDescriptor to describe a memory area made up of several other IOMemoryDescriptors.

static IOMultiMemoryDescriptor * withDescriptors( IOMemoryDescriptor **descriptors, UInt32 withCount, IODirection withDirection, bool asReference = false );
Parameters
descriptors

An array of IOMemoryDescriptors which make up the memory to be described.

withCount

The object count for the descriptors array.

withDirection

An I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.

asReference

If false, the IOMultiMemoryDescriptor object will make a copy of the descriptors array, otherwise, the array will be used in situ, avoiding an extra allocation.

Return Value

The created IOMultiMemoryDescriptor on success, to be released by the caller, or zero on failure.

Discussion

This method creates and initializes an IOMultiMemoryDescriptor for memory consisting of a number of other IOMemoryDescriptors, chained end-to-end (in the order they appear in the array) to represent a single contiguous memory buffer. Passing the descriptor array as a reference will avoid an extra allocation.

withDescriptors(IOMemoryDescriptor **, UInt32, IODirection, bool)

Initialize an IOMultiMemoryDescriptor to describe a memory area made up of several other IOMemoryDescriptors.

virtual bool initWithDescriptors( IOMemoryDescriptor **descriptors, UInt32 withCount, IODirection withDirection, bool asReference = false );
Parameters
descriptors

An array of IOMemoryDescriptors which make up the memory to be described.

withCount

The object count for the descriptors array.

withDirection

An I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.

asReference

If false, the IOMultiMemoryDescriptor object will make a copy of the descriptors array, otherwise, the array will be used in situ, avoiding an extra allocation.

Return Value

The created IOMultiMemoryDescriptor on success, to be released by the caller, or zero on failure.

Discussion

This method initializes an IOMultiMemoryDescriptor for memory consisting of a number of other IOMemoryDescriptors, chained end-to-end (in the order they appear in the array) to represent a single contiguous memory buffer. Passing the descriptor array as a reference will avoid an extra allocation.