Mac Developer Library

Developer

IOInterleavedMemoryDescriptor Class Reference

Options
Deployment Target:

On This Page
Language:

IOInterleavedMemoryDescriptor

Inheritance


  • IOInterleavedMemoryDescriptor

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.5 and later.

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.

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

    Declaration

    C++

    virtual void clearMemoryDescriptors( IODirection direction = direction );

    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 processing of the memory after an I/O transfer finishes.

    Declaration

    C++

    virtual IOReturn complete( IODirection forDirection = forDirection);

    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.

  • Break a memory descriptor into its physically contiguous segments.

    Declaration

    C++

    virtual addr64_t getPhysicalSegment( IOByteCountoffset, 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.

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

    Declaration

    C++

    virtual bool initWithCapacity( IOByteCountcapacity, IODirectiondirection );

    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 the memory for an I/O transfer.

    Declaration

    C++

    virtual IOReturn prepare( IODirection forDirection = forDirection);

    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.

  • Add a portion of an IOMemoryDescriptor to the IOInterleavedMemoryDescriptor.

    Declaration

    C++

    virtual bool setMemoryDescriptor( IOMemoryDescriptor *descriptor, IOByteCountoffset, IOByteCountlength );

    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.

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

    Declaration

    C++

    static IOInterleavedMemoryDescriptor * withCapacity( IOByteCountcapacity, IODirectiondirection);

    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.