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

IOMemoryMap

Inherits from:	OSObject
Declared In:	IOMemoryDescriptor.h

Overview

An abstract base class defining common methods for describing a memory mapping.

Discussion

The IOMemoryMap object represents a mapped range of memory, described by an IOMemoryDescriptor. The mapping may be in the kernel or a non-kernel task and has processor cache mode attributes. IOMemoryMap instances are created by IOMemoryDescriptor when it creates mappings in its map method, and returned to the caller.

Functions

getAddressTask: Accessor to the task of the mapping.
getLength: Accessor to the length of the mapping.
getMapOptions: Accessor to the options the mapping was created with.
getMemoryDescriptor: Accessor to the IOMemoryDescriptor the mapping was created from.
getPhysicalAddress: Return the physical address of the first byte in the mapping.
getPhysicalSegment: Break a mapping into its physically contiguous segments.
redirect: Replace the memory mapped in a process with new backing memory.
unmap: Force the IOMemoryMap to unmap, without destroying the object.

getAddressTask

Accessor to the task of the mapping.

public

virtual task_t getAddressTask() = 0;

Return Value

A Mach task_t.

Discussion

This method returns the Mach task the mapping exists in. Note that in Mac OS X, each process is based on a Mach task and one or more Mach threads. For more information on the composition of a Mach task and its relationship with Mach threads, see "Tasks and Threads".

getLength

Accessor to the length of the mapping.

public

virtual IOByteCount getLength() = 0;

Return Value

A byte count.

Discussion

This method returns the length of the mapping.

getMapOptions

Accessor to the options the mapping was created with.

public

virtual IOOptionBits getMapOptions() = 0;

Return Value

Options for the mapping, including cache settings.

Discussion

This method returns the options to IOMemoryDescriptor::map the mapping was created with.

getMemoryDescriptor

Accessor to the IOMemoryDescriptor the mapping was created from.

public

virtual IOMemoryDescriptor * getMemoryDescriptor() = 0;

Return Value

An IOMemoryDescriptor reference, which is valid while the IOMemoryMap object is retained. It should not be released by the caller.

Discussion

This method returns the IOMemoryDescriptor the mapping was created from.

getPhysicalAddress

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

public

IOPhysicalAddress getPhysicalAddress();

Return Value

A physical address.

Discussion

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

getPhysicalSegment

Break a mapping into its physically contiguous segments.

public

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

Parameters

offset: A byte offset into the mapping 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 mapping.

Discussion

This method returns the physical address of the byte at the given offset into the mapping, and optionally the length of the physically contiguous segment from that offset. It functions similarly to IOMemoryDescriptor::getPhysicalSegment.

redirect

Replace the memory mapped in a process with new backing memory.

public

virtual IOReturn redirect(
    IOMemoryDescriptor *newBackingMemory, 
    IOOptionBits options, 
    IOByteCount offset = 0) = 0;

Parameters

newBackingMemory: The IOMemoryDescriptor that represents the physical memory that is to be now mapped in the virtual range the IOMemoryMap represents. If newBackingMemory is NULL, any access to the mapping will hang (in vm_fault()) until access has been restored by a new call to redirect with non-NULL newBackingMemory argument.
options: Mapping options are defined in IOTypes.h, and are documented in IOMemoryDescriptor::map().
offset: As with IOMemoryDescriptor::map(), a beginning offset into the IOMemoryDescriptor's memory where the mapping starts. Zero is the default.

Return Value

An IOReturn code.

Discussion

An IOMemoryMap created with the kIOMapUnique option to IOMemoryDescriptor::map can remapped to a new IOMemoryDescriptor backing object. If the new IOMemoryDescriptor is specified as NULL, client access to the memory map is blocked until a new backing object has been set. By blocking access and copying data, the caller can create atomic copies of the memory while the client is potentially reading or writing the memory.

unmap

Force the IOMemoryMap to unmap, without destroying the object.

public

virtual IOReturn unmap() = 0;

Return Value

An IOReturn code.

Discussion

IOMemoryMap instances will unmap themselves upon free, ie. when the last client with a reference calls release. This method forces the IOMemoryMap to destroy the mapping it represents, regardless of the number of clients. It is not generally used.

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