ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

IOMultiMemoryDescriptor

Inherits from:	IOMemoryDescriptor
Declared In:	IOMultiMemoryDescriptor.h

Overview

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

Discussion

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.

Functions

complete: Complete processing of the memory after an I/O transfer finishes.
getPhysicalAddress: Return the physical address of the first byte in the memory.
getPhysicalSegment: Return the physical address of the first byte in the memory.
initWithDescriptors: Initialize an IOMultiMemoryDescriptor to describe a memory area made up of several other IOMemoryDescriptors.
prepare: Prepare the memory for an I/O transfer.
readBytes: Copy data from the memory descriptor's buffer to the specified buffer.
withDescriptors(IOMemoryDescriptor **, UInt32, IODirection, bool): Create an IOMultiMemoryDescriptor to describe a memory area made up of several other IOMemoryDescriptors.
withDescriptors(IOMemoryDescriptor **, UInt32, IODirection, bool): Initialize an IOMultiMemoryDescriptor to describe a memory area made up of several other IOMemoryDescriptors.
writeBytes: Copy data to the memory descriptor's buffer from the specified buffer.

complete

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

public

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.

getPhysicalAddress

Return the physical address of the first byte in the memory.

public

virtual IOPhysicalAddress getPhysicalSegment(
    IOByteCount offset, 
    IOByteCount *length );

Return Value

A physical address.

Discussion

This method returns the physical address of the first byte in the memory. It is most useful on memory known to be physically contiguous.

getPhysicalSegment

Return the physical address of the first byte in the memory.

public

virtual IOPhysicalAddress getPhysicalSegment(
    IOByteCount offset, 
    IOByteCount *length );

Return Value

A physical address.

Discussion

This method returns the physical address of the first byte in the memory. It is most useful on memory known to be physically contiguous.

initWithDescriptors

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

public

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.

public

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.

readBytes

Copy data from the memory descriptor's buffer to the specified buffer.

public

virtual IOByteCount readBytes(
    IOByteCount offset, 
    void *bytes, 
    IOByteCount withLength );

Parameters

offset: A byte offset into the memory descriptor's memory.
bytes: The caller supplied buffer to copy the data to.
withLength: The length of the data to copy.

Return Value

The number of bytes copied, zero will be returned if the specified offset is beyond the length of the descriptor.

Discussion

This method copies data from the memory descriptor's memory at the given offset, to the caller's buffer.

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

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

public

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.

public

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

writeBytes

Copy data to the memory descriptor's buffer from the specified buffer.

public

virtual IOByteCount writeBytes(
    IOByteCount offset, 
    const void * bytes, 
    IOByteCount withLength );

Parameters

offset: A byte offset into the memory descriptor's memory.
bytes: The caller supplied buffer to copy the data from.
withLength: The length of the data to copy.

Return Value

The number of bytes copied, zero will be returned if the specified offset is beyond the length of the descriptor.

Discussion

This method copies data to the memory descriptor's memory at the given offset, from the caller's buffer.

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-12-19