IOMemoryDescriptor



Member Functions

complete

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

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

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.

Parameters

NameDescription
forDirectionThe direction of the I/O just completed, or kIODirectionNone for the direction specified by the memory descriptor.
Result: An IOReturn code.

getDirection

Abstract: Accessor to get the direction the memory descriptor was created with.
public:

virtual IODirection getDirection() const;

This method returns the direction the memory descriptor was created with.

Result: The direction.

getLength

Abstract: Accessor to get the length of the memory descriptor (over all its ranges).
public:

virtual IOByteCount getLength() const;

This method returns the total length of the memory described by the descriptor, ie. the sum of its ranges' lengths.

Result: The byte count.

getPhysicalAddress

Abstract: Return the physical address of the first byte in the memory.
public:

inline IOPhysicalAddress getPhysicalAddress() { return( getPhysicalSegment( 0, 0 )); }

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

Result: A physical address.

getPhysicalSegment

Abstract: Break a memory descriptor into its physically contiguous segments.
public:

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

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.

Parameters

NameDescription
offsetA byte offset into the memory whose physical address to return.
lengthIf non-zero, getPhysicalSegment will store here the length of the physically contiguous segement at the given offset.
Result: A physical address, or zero if the offset is beyond the length of the memory.

getTag

Abstract: Accessor to the retrieve the tag for the memory descriptor.
public:

virtual IOOptionBits getTag( void );

This method returns the tag for the memory descriptor. Tag bits are not interpreted by IOMemoryDescriptor.

Result: The tag.

initWithAddress

Abstract: Initialize or reinitialize an IOMemoryDescriptor to describe one virtual range of the kernel task.
public:

virtual bool initWithAddress(void * address, IOByteCount withLength, IODirection withDirection) = 0;

This method initializes an IOMemoryDescriptor for memory consisting of a single virtual memory range mapped into the kernel map. An IOMemoryDescriptor can be re-used by calling initWithAddress or initWithRanges again on an existing instance -- note this behavior is not commonly supported in other IOKit classes, although it is supported here.

Parameters

NameDescription
addressThe virtual address of the first byte in the memory.
withLengthThe length of memory.
withDirectionAn I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
Result: true on success, false on failure.

initWithAddress

Abstract: Initialize or reinitialize an IOMemoryDescriptor to describe one virtual range of the specified map.
public:

virtual bool initWithAddress(vm_address_t address, IOByteCount withLength, IODirection withDirection, task_t withTask) = 0;

This method initializes an IOMemoryDescriptor for memory consisting of a single virtual memory range mapped into the specified map. An IOMemoryDescriptor can be re-used by calling initWithAddress or initWithRanges again on an existing instance -- note this behavior is not commonly supported in other IOKit classes, although it is supported here.

Parameters

NameDescription
addressThe virtual address of the first byte in the memory.
withLengthThe length of memory.
withDirectionAn I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
withTaskThe task the virtual ranges are mapped into.
Result: true on success, false on failure.

initWithPhysicalAddress

Abstract: Initialize or reinitialize an IOMemoryDescriptor to describe one physical range.
public:

virtual bool initWithPhysicalAddress( IOPhysicalAddress address, IOByteCount withLength, IODirection withDirection ) = 0;

This method initializes an IOMemoryDescriptor for memory consisting of a single physical memory range. An IOMemoryDescriptor can be re-used by calling initWithAddress or initWithRanges again on an existing instance -- note this behavior is not commonly supported in other IOKit classes, although it is supported here.

Parameters

NameDescription
addressThe physical address of the first byte in the memory.
withLengthThe length of memory.
withDirectionAn I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
Result: true on success, false on failure.

initWithPhysicalRanges

Abstract: Initialize or reinitialize an IOMemoryDescriptor to describe one or more physical ranges.
public:

virtual bool initWithPhysicalRanges(IOPhysicalRange * ranges, UInt32 withCount, IODirection withDirection, bool asReference = false) = 0;

This method initializes an IOMemoryDescriptor for memory consisting of an array of physical memory ranges. An IOMemoryDescriptor can be re-used by calling initWithAddress or initWithRanges again on an existing instance -- note this behavior is not commonly supported in other IOKit classes, although it is supported here.

Parameters

NameDescription
rangesAn array of IOPhysicalRange structures which specify the physical ranges which make up the memory to be described.
withCountThe member count of the ranges array.
withDirectionAn I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
asReferenceIf false, the IOMemoryDescriptor object will make a copy of the ranges array, otherwise, the array will be used in situ, avoiding an extra allocation.
Result: true on success, false on failure.

initWithRanges

Abstract: Initialize or reinitialize an IOMemoryDescriptor to describe one or more virtual ranges.
public:

virtual bool initWithRanges( IOVirtualRange * ranges, UInt32 withCount, IODirection withDirection, task_t withTask, bool asReference = false) = 0;

This method initializes an IOMemoryDescriptor for memory consisting of an array of virtual memory ranges each mapped into a specified source task. An IOMemoryDescriptor can be re-used by calling initWithAddress or initWithRanges again on an existing instance -- note this behavior is not commonly supported in other IOKit classes, although it is supported here.

Parameters

NameDescription
rangesAn array of IOVirtualRange structures which specify the virtual ranges in the specified map which make up the memory to be described.
withCountThe member count of the ranges array.
withDirectionAn I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
withTaskThe task each of the virtual ranges are mapped into.
asReferenceIf false, the IOMemoryDescriptor object will make a copy of the ranges array, otherwise, the array will be used in situ, avoiding an extra allocation.
Result: true on success, false on failure.

map

Abstract: Maps a IOMemoryDescriptor into the kernel map.
public:

virtual IOMemoryMap * map( IOOptionBits options = 0 );

This is a shortcut method to map all the memory described by a memory descriptor into the kernel map at any available address. See the full version of the map method for further details.

Parameters

NameDescription
optionsMapping options as in the full version of the map method, with kIOMapAnywhere assumed.
Result: See the full version of the map method.

map

Abstract: Maps a IOMemoryDescriptor into a task.
public:

virtual IOMemoryMap * map( task_t intoTask, IOVirtualAddress atAddress, IOOptionBits options, IOByteCount offset = 0, IOByteCount length = 0 );

This is the general purpose method to map all or part of the memory described by a memory descriptor into a task at any available address, or at a fixed address if possible. Caching & read-only options may be set for the mapping. The mapping is represented as a returned reference to a IOMemoryMap object, which may be shared if the mapping is compatible with an existing mapping of the IOMemoryDescriptor. The IOMemoryMap object returned should be released only when the caller has finished accessing the mapping, as freeing the object destroys the mapping.

Parameters

NameDescription
intoTaskSets the target task for the mapping. Pass kernel_task for the kernel address space.
atAddressIf a placed mapping is requested, atAddress specifies its address, and the kIOMapAnywhere should not be set. Otherwise, atAddress is ignored.
optionsMapping options are defined in IOTypes.h,
kIOMapAnywhere should be passed if the mapping can be created anywhere. If not set, the atAddress parameter sets the location of the mapping, if it is available in the target map.
kIOMapDefaultCache to inhibit the cache in I/O areas, kIOMapCopybackCache in general purpose RAM.
kIOMapInhibitCache, kIOMapWriteThruCache, kIOMapCopybackCache to set the appropriate caching.
kIOMapReadOnly to allow only read only accesses to the memory - writes will cause and access fault.
kIOMapReference will only succeed if the mapping already exists, and the IOMemoryMap object is just an extra reference, ie. no new mapping will be created.
offsetIs a beginning offset into the IOMemoryDescriptor's memory where the mapping starts. Zero is the default to map all the memory.
lengthIs the length of the mapping requested for a subset of the IOMemoryDescriptor. Zero is the default to map all the memory.
Result: A reference to an IOMemoryMap object representing the mapping, which can supply the virtual address of the mapping and other information. The mapping may be shared with multiple callers - multiple maps are avoided if a compatible one exists. The IOMemoryMap object returned should be released only when the caller has finished accessing the mapping, as freeing the object destroys the mapping. The IOMemoryMap instance also retains the IOMemoryDescriptor it maps while it exists.

prepare

Abstract: Prepare the memory for an I/O transfer.
public:

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

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.

Parameters

NameDescription
forDirectionThe direction of the I/O just completed, or kIODirectionNone for the direction specified by the memory descriptor.
Result: An IOReturn code.

readBytes

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

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

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

Parameters

NameDescription
offsetA byte offset into the memory descriptor's memory.
bytesThe caller supplied buffer to copy the data to.
withLengthThe length of the data to copy.
Result: The number of bytes copied, zero will be returned if the specified offset is beyond the length of the descriptor.

setMapping

Abstract: Establishes an already existing mapping.
public:

virtual IOMemoryMap * setMapping( task_t task, IOVirtualAddress mapAddress, IOOptionBits options = 0 );

This method tells the IOMemoryDescriptor about a mapping that exists, but was created elsewhere. It allows later callers of the map method to share this externally created mapping. The IOMemoryMap object returned is created to represent it. This method is not commonly needed.

Parameters

NameDescription
taskAddress space in which the mapping exists.
mapAddressVirtual address of the mapping.
optionsCaching and read-only attributes of the mapping.
Result: A IOMemoryMap object created to represent the mapping.

setTag

Abstract: Set the tag for the memory descriptor.
public:

virtual void setTag( IOOptionBits tag );

This method sets the tag for the memory descriptor. Tag bits are not interpreted by IOMemoryDescriptor.

Parameters

NameDescription
tagThe tag.

withAddress

Abstract: Create an IOMemoryDescriptor to describe one virtual range of the specified map.
public:

static IOMemoryDescriptor * withAddress(vm_address_t address, IOByteCount withLength, IODirection withDirection, task_t withTask);

This method creates and initializes an IOMemoryDescriptor for memory consisting of a single virtual memory range mapped into the specified map.

Parameters

NameDescription
addressThe virtual address of the first byte in the memory.
withLengthThe length of memory.
withDirectionAn I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
withTaskThe task the virtual ranges are mapped into.
Result: The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure.

withAddress

Abstract: Create an IOMemoryDescriptor to describe one virtual range of the kernel task.
public:

static IOMemoryDescriptor * withAddress(void * address, IOByteCount withLength, IODirection withDirection);

This method creates and initializes an IOMemoryDescriptor for memory consisting of a single virtual memory range mapped into the kernel map.

Parameters

NameDescription
addressThe virtual address of the first byte in the memory.
withLengthThe length of memory.
withDirectionAn I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
Result: The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure.

withPhysicalAddress

Abstract: Create an IOMemoryDescriptor to describe one physical range.
public:

static IOMemoryDescriptor * withPhysicalAddress( IOPhysicalAddress address, IOByteCount withLength, IODirection withDirection );

This method creates and initializes an IOMemoryDescriptor for memory consisting of a single physical memory range.

Parameters

NameDescription
addressThe physical address of the first byte in the memory.
withLengthThe length of memory.
withDirectionAn I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
Result: The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure.

withPhysicalRanges

Abstract: Create an IOMemoryDescriptor to describe one or more physical ranges.
public:

static IOMemoryDescriptor * withPhysicalRanges( IOPhysicalRange * ranges, UInt32 withCount, IODirection withDirection, bool asReference = false);

This method creates and initializes an IOMemoryDescriptor for memory consisting of an array of physical memory ranges.

Parameters

NameDescription
rangesAn array of IOPhysicalRange structures which specify the physical ranges which make up the memory to be described.
withCountThe member count of the ranges array.
withDirectionAn I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
asReferenceIf false, the IOMemoryDescriptor object will make a copy of the ranges array, otherwise, the array will be used in situ, avoiding an extra allocation.
Result: The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure.

withRanges

Abstract: Create an IOMemoryDescriptor to describe one or more virtual ranges.
public:

static IOMemoryDescriptor * withRanges(IOVirtualRange * ranges, UInt32 withCount, IODirection withDirection, task_t withTask, bool asReference = false);

This method creates and initializes an IOMemoryDescriptor for memory consisting of an array of virtual memory ranges each mapped into a specified source task.

Parameters

NameDescription
rangesAn array of IOVirtualRange structures which specify the virtual ranges in the specified map which make up the memory to be described.
withCountThe member count of the ranges array.
withDirectionAn I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
withTaskThe task each of the virtual ranges are mapped into.
asReferenceIf false, the IOMemoryDescriptor object will make a copy of the ranges array, otherwise, the array will be used in situ, avoiding an extra allocation.
Result: The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure.

withSubRange

Abstract: Create an IOMemoryDescriptor to describe a subrange of an existing descriptor.
public:

static IOMemoryDescriptor * withSubRange(IOMemoryDescriptor * of, IOByteCount offset, IOByteCount length, IODirection withDirection);

This method creates and initializes an IOMemoryDescriptor for memory consisting of a subrange of the specified memory descriptor. The parent memory descriptor is retained by the new descriptor.

Parameters

NameDescription
ofThe parent IOMemoryDescriptor of which a subrange is to be used for the new descriptor, which will be retained by the subrange IOMemoryDescriptor.
offsetA byte offset into the parent memory descriptor's memory.
lengthThe length of the subrange.
withDirectionAn I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures. This is used over the direction of the parent descriptor.
Result: The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure.

writeBytes

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

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

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

Parameters

NameDescription
offsetA byte offset into the memory descriptor's memory.
bytesThe caller supplied buffer to copy the data from.
withLengthThe length of the data to copy.
Result: The number of bytes copied, zero will be returned if the specified offset is beyond the length of the descriptor.

© 2000 Apple Computer, Inc. — (Last Updated 2/23/2000)