Mac Developer Library

Developer

IOMemoryMap Class Reference

Options
Deployment Target:

On This Page
Language:

IOMemoryMap

A class defining common methods for describing a memory mapping. More...

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable @import Kernel;

Availability


Available in OS X v10.0 and later.
  • Accessor to the length of the mapping.

    Declaration

    C++

    inline mach_vm_address_t getAddress() __attribute__((always_inline));

    Return Value

    A byte count.

    Discussion

    This method returns the length of the mapping.

    Import Statement

  • Accessor to the length of the mapping.

    Declaration

    C++

    virtual mach_vm_address_t getAddress();

    Return Value

    A byte count.

    Discussion

    This method returns the length of the mapping.

    Import Statement

  • Accessor to the task of the mapping.

    Declaration

    C++

    virtual task_t getAddressTask();

    Return Value

    A mach task_t.

    Discussion

    This method returns the mach task the mapping exists in.

    Import Statement

  • Accessor to the length of the mapping.

    Declaration

    C++

    virtual IOByteCount getLength();

    Return Value

    A byte count.

    Discussion

    This method returns the length of the mapping.

    Import Statement

  • Accessor to the options the mapping was created with.

    Declaration

    C++

    virtual IOOptionBits getMapOptions();

    Return Value

    Options for the mapping, including cache settings.

    Discussion

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

    Import Statement

  • Accessor to the IOMemoryDescriptor the mapping was created from.

    Declaration

    C++

    virtual IOMemoryDescriptor * getMemoryDescriptor();

    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.

    Import Statement

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

    Declaration

    C++

    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.

    Import Statement

  • Break a mapping into its physically contiguous segments.

    Declaration

    C++

    #ifdef __LP64__ virtual IOPhysicalAddress getPhysicalSegment( IOByteCount offset, IOByteCount *length, IOOptionBits options = 0); #else /* !__LP64__ */ virtual IOPhysicalAddress getPhysicalSegment( IOByteCount offset, IOByteCount *length); #endif /* !__LP64__ */

    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.

    Import Statement

  • Accessor to the length of the mapping.

    Declaration

    C++

    inline mach_vm_address_t getAddress() __attribute__((always_inline));

    Return Value

    A byte count.

    Discussion

    This method returns the length of the mapping.

    Import Statement

  • Accessor to the length of the mapping.

    Declaration

    C++

    virtual mach_vm_address_t getAddress();

    Return Value

    A byte count.

    Discussion

    This method returns the length of the mapping.

    Import Statement

  • Accessor to the virtual address of the first byte in the mapping.

    Declaration

    C++

    virtual IOVirtualAddress getVirtualAddress();

    Return Value

    A virtual address.

    Discussion

    This method returns the virtual address of the first byte in the mapping. Since the IOVirtualAddress is only 32bit in 32bit kernels, the getAddress() method should be used for compatibility with 64bit task mappings.

    Import Statement

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

    Declaration

    C++

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

    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.

    Import Statement

  • Force the IOMemoryMap to unmap, without destroying the object.

    Declaration

    C++

    virtual IOReturn unmap();

    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.

    Import Statement