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.
Result: An IOReturn code.
Name Description forDirection The direction of the I/O just completed, or kIODirectionNone for the direction specified by the memory descriptor.
public:
virtual IODirection getDirection() const;
This method returns the direction the memory descriptor was created with.
Result: The direction.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.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.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.
Result: A physical address, or zero if the offset is beyond the length of the memory.
Name Description 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.
public:
virtual IOOptionBits getTag( void );
This method returns the tag for the memory descriptor. Tag bits are not interpreted by IOMemoryDescriptor.
Result: The tag.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.
Result: true on success, false on failure.
Name Description address The virtual address of the first byte in the memory. withLength The length of memory. 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.
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.
Result: true on success, false on failure.
Name Description address The virtual address of the first byte in the memory. withLength The length of memory. 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. withTask The task the virtual ranges are mapped into.
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.
Result: true on success, false on failure.
Name Description address The physical address of the first byte in the memory. withLength The length of memory. 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.
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.
Result: true on success, false on failure.
Name Description ranges An array of IOPhysicalRange structures which specify the physical ranges which make up the memory to be described. withCount The member count of the ranges 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 IOMemoryDescriptor object will make a copy of the ranges array, otherwise, the array will be used in situ, avoiding an extra allocation.
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.
Result: true on success, false on failure.
Name Description ranges An array of IOVirtualRange structures which specify the virtual ranges in the specified map which make up the memory to be described. withCount The member count of the ranges 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. withTask The task each of the virtual ranges are mapped into. asReference If false, the IOMemoryDescriptor object will make a copy of the ranges array, otherwise, the array will be used in situ, avoiding an extra allocation.
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.
Result: See the full version of the map method.
Name Description options Mapping options as in the full version of the map method, with kIOMapAnywhere assumed.
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.
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.
Name Description intoTask Sets the target task for the mapping. Pass kernel_task for the kernel address space. atAddress If a placed mapping is requested, atAddress specifies its address, and the kIOMapAnywhere should not be set. Otherwise, atAddress is ignored. options Mapping 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.offset Is a beginning offset into the IOMemoryDescriptor's memory where the mapping starts. Zero is the default to map all the memory. length Is the length of the mapping requested for a subset of the IOMemoryDescriptor. Zero is the default to map all the memory.
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.
Result: An IOReturn code.
Name Description forDirection The direction of the I/O just completed, or kIODirectionNone for the direction specified by the memory descriptor.
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.
Result: The number of bytes copied, zero will be returned if the specified offset is beyond the length of the descriptor.
Name Description 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.
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.
Result: A IOMemoryMap object created to represent the mapping.
Name Description task Address space in which the mapping exists. mapAddress Virtual address of the mapping. options Caching and read-only attributes of the mapping.
public:
virtual void setTag( IOOptionBits tag );
This method sets the tag for the memory descriptor. Tag bits are not interpreted by IOMemoryDescriptor.
Name Description tag The tag.
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.
Result: The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure.
Name Description address The virtual address of the first byte in the memory. withLength The length of memory. 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. withTask The task the virtual ranges are mapped into.
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.
Result: The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure.
Name Description address The virtual address of the first byte in the memory. withLength The length of memory. 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.
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.
Result: The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure.
Name Description address The physical address of the first byte in the memory. withLength The length of memory. 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.
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.
Result: The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure.
Name Description ranges An array of IOPhysicalRange structures which specify the physical ranges which make up the memory to be described. withCount The member count of the ranges 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 IOMemoryDescriptor object will make a copy of the ranges array, otherwise, the array will be used in situ, avoiding an extra allocation.
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.
Result: The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure.
Name Description ranges An array of IOVirtualRange structures which specify the virtual ranges in the specified map which make up the memory to be described. withCount The member count of the ranges 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. withTask The task each of the virtual ranges are mapped into. asReference If false, the IOMemoryDescriptor object will make a copy of the ranges array, otherwise, the array will be used in situ, avoiding an extra allocation.
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.
Result: The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure.
Name Description of The parent IOMemoryDescriptor of which a subrange is to be used for the new descriptor, which will be retained by the subrange IOMemoryDescriptor. offset A byte offset into the parent memory descriptor's memory. length The length of the subrange. 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. This is used over the direction of the parent descriptor.
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.
Result: The number of bytes copied, zero will be returned if the specified offset is beyond the length of the descriptor.
Name Description 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.
© 2000 Apple Computer, Inc. (Last Updated 2/23/2000)