Mac Developer Library

Developer

IOMultiMemoryDescriptor Class Reference

Options
Deployment Target:

On This Page
Language:

IOMultiMemoryDescriptor

Inheritance


  • IOMultiMemoryDescriptor

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.0 and later.

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.

  • 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 IOMultiMemoryDescriptor to describe a memory area made up of several other IOMemoryDescriptors.

    Declaration

    C++

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

    Declaration

    C++

    virtual IOReturn prepare( 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 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.

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

    Declaration

    C++

    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.

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

    Declaration

    C++

    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.