IOInterleavedMemoryDescriptor

Inherits from
IOMemoryDescriptor
Availability
Available in OS X v10.5 and later.
Declared in
IOInterleavedMemoryDescriptor.h

Overview

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

The IOInterleavedMemoryDescriptor object represents interleaved ranges of memory, specified as an ordered list of portions of individual IOMemoryDescriptors. The portions are chained end-to-end to make up a single contiguous buffer.

Tasks

Miscellaneous

Instance Methods

clearMemoryDescriptors

Clear all of the IOMemoryDescriptors currently contained in and reset the IOInterleavedMemoryDescriptor.

virtual void clearMemoryDescriptors( IODirection direction = kIODirectionNone );
Parameters
direction

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

Discussion

Clears each IOMemoryDescriptor by completing (if needed) and releasing. The IOInterleavedMemoryDescriptor is then reset and may accept new descriptors up to the capacity specified when it was created.

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.

initWithCapacity

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

virtual bool initWithCapacity( IOByteCount capacity, IODirection direction );
Parameters
capacity

The maximum number of IOMemoryDescriptors that may be subsequently added to this IOInterleavedMemoryDescriptor.

direction

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

Return Value

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

Discussion

This method initializes an IOInterleavedMemoryDescriptor for memory consisting of portions 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.

prepare

Prepare the memory for an I/O transfer.

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

The direction of the I/O to be performed, 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 need not called for non-pageable memory.

setMemoryDescriptor

Add a portion of an IOMemoryDescriptor to the IOInterleavedMemoryDescriptor.

virtual bool setMemoryDescriptor( IOMemoryDescriptor *descriptor, IOByteCount offset, IOByteCount length );
Parameters
descriptor

An IOMemoryDescriptor to be added to the IOInterleavedMemoryDescriptor. Its direction must be compatible with that of the IOInterleavedMemoryDescriptor.

offset

The offset into the IOMemoryDescriptor of the portion that will be added to the virtualized buffer.

length

The length of the portion of the IOMemoryDescriptor to be added to the virtualized buffer.

Return Value

Returns true the portion was successfully added.

Discussion

This method adds the portion of an IOMemoryDescriptor described by the offset and length parameters to the end of the IOInterleavedMemoryDescriptor. A single IOMemoryDescriptor may be added as many times as there is room for it. The offset and length must describe a portion entirely within the IOMemoryDescriptor.

withCapacity

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

static IOInterleavedMemoryDescriptor * withCapacity( IOByteCount capacity, IODirection direction);
Parameters
capacity

The maximum number of IOMemoryDescriptors that may be subsequently added to this IOInterleavedMemoryDescriptor.

direction

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

Return Value

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

Discussion

This method creates and initializes an IOInterleavedMemoryDescriptor for memory consisting of portions 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.