createMappingInTask

Maps a IOMemoryDescriptor into a task.

Declaration

IOMemoryMap * createMappingInTask( 
 task_t intoTask, 
 mach_vm_address_t atAddress, 
 IOOptionBits options, 
 mach_vm_size_t offset = 0, 
 mach_vm_size_t length = 0 ); 

Parameters

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.

kIOMapUnique allows a special kind of mapping to be created that may be used with the IOMemoryMap::redirect() API. These mappings will not be shared as is the default - there will always be a unique mapping created for the caller, not an existing mapping with an extra reference.

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.

Return Value

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.

Overview

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.

See Also

Miscellaneous

- complete

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

- getDirection

Accessor to get the direction the memory descriptor was created with.

- getLength

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

- getPageCounts

Retrieve the number of resident and/or dirty pages encompassed by an IOMemoryDescriptor.

- getPhysicalAddress

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

- getPhysicalSegment

Break a memory descriptor into its physically contiguous segments.

- getTag

Accessor to the retrieve the tag for the memory descriptor.

- initWithOptions

Master initialiser for all variants of memory descriptors. For a more complete description see IOMemoryDescriptor::withOptions.

- map

Maps a IOMemoryDescriptor into the kernel map.

- performOperation

Perform an operation on the memory descriptor's memory.

- prepare

Prepare the memory for an I/O transfer.

- readBytes

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

- setMapping

Establishes an already existing mapping.

- setPurgeable

Control the purgeable status of a memory descriptors memory.

- setTag

Set the tag for the memory descriptor.

- withAddress

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

- withAddressRange

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

- withAddressRanges

Create an IOMemoryDescriptor to describe one or more virtual ranges.

- withOptions

Master initialiser for all variants of memory descriptors.

- withPersistentMemoryDescriptor

Copy constructor that generates a new memory descriptor if the backing memory for the same task's virtual address and length has changed.

- withPhysicalAddress

Create an IOMemoryDescriptor to describe one physical range.

- writeBytes

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