-<h2>vm_map</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Map the specified memory object to a region of virtual memory.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t vm_map</strong>
\r <strong>(vm_task_t</strong> <var>target_task</var>,
\r <strong>vm_address_t</strong> <var>address</var>,
\r <strong>vm_size_t</strong> <var>size</var>,
\r <strong>vm_address_t</strong> <var>mask</var>,
\r <strong>boolean_t</strong> <var>anywhere</var>,
\r <strong>memory_object_t</strong> <var>memory_object</var>,
\r <strong>vm_offset_t</strong> <var>offset</var>,
\r <strong>boolean_t</strong> <var>copy</var>,
\r <strong>vm_prot_t</strong> <var>cur_protection</var>,
\r <strong>vm_prot_t</strong> <var>max_protection</var>,
\r <strong>vm_inherit_t</strong> <var>inheritance</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>target_task</var>
\r<dd>
\r[in task send right]
\rThe port for the task in whose address space the
\rmemory object is to be mapped.
\r<p>
\r<dt> <var>address</var>
\r<dd>
\r[pointer to in/out scalar]
\rThe starting address for the mapped object.
\rThe mapped object will start at the beginning of the page containing
\r<var>address</var>. If there is not enough room following the address, the kernel
\rdoes not map the object. The kernel returns the starting address
\ractually used for the mapped object.
\r<p>
\r<dt> <var>size</var>
\r<dd>
\r[in scalar]
\rThe number of bytes to allocate for the object. The kernel
\rrounds this number up to an integral number of virtual pages.
\r<p>
\r<dt> <var>mask</var>
\r<dd>
\r[in scalar]
\rAlignment restrictions for starting address. Bits turned on in
\rthe mask will not be turned on in the starting address.
\r<p>
\r<dt> <var>anywhere</var>
\r<dd>
\r[in scalar]
\rPlacement indicator. The valid values are:
\r<dl>
\r<p>
\r<dt> <strong>TRUE</strong>
\r<dd>
\rThe kernel allocates the region in the next unused space that
\ris sufficient within the address space. The kernel returns the
\rstarting address actually used in <var>address</var>.
\r<p>
\r<dt> <strong>FALSE</strong>
\r<dd>
\rThe kernel allocates the region starting at <var>address</var> unless that
\rspace is already allocated.
\r</dl>
\r<p>
\r<dt> <var>memory_object</var>
\r<dd>
\r[in memory-object send right]
\rThe port naming the
\rmemory object. If <strong>MEMORY_OBJECT_NULL</strong> is
\rspecified, the kernel allocates zero-filled memory, as with <strong>vm_allocate</strong>.
\r<p>
\r<dt> <var>offset</var>
\r<dd>
\r[in scalar]
\rAn offset within the memory object, in bytes. The kernel
\rmaps <var>address</var> to the specified offset.
\r<p>
\r<dt> <var>copy</var>
\r<dd>
\r[in scalar]
\rCopy indicator. If true, the kernel copies the region of the
\rmemory object to the specified task's address space. If false, the region
\ris directly mapped.
\r<p>
\r<dt> <var>cur_protection</var>
\r<dd>
\r[in scalar]
\rThe initial current protection for the region. Valid values are
\robtained by or'ing together the following values:
\r<dl>
\r<p>
\r<dt> <strong>VM_PROT_READ</strong>
\r<dd>
\rAllows read access.
\r<p>
\r<dt> <strong>VM_PROT_WRITE</strong>
\r<dd>
\rAllows write access.
\r<p>
\r<dt> <strong>VM_PROT_EXECUTE</strong>
\r<dd>
\rAllows execute access.
\r</dl>
\r<p>
\r<dt> <var>max_protection</var>
\r<dd>
\r[in scalar]
\rThe maximum protection for the region. Values are the same
\ras for <var>cur_protection</var>.
\r<p>
\r<dt> <var>inheritance</var>
\r<dd>
\r[in scalar]
\rThe initial inheritance attribute for the region. Valid values
\rare:
\r<dl>
\r<p>
\r<dt> <strong>VM_INHERIT_SHARE</strong>
\r<dd>
\rAllows child tasks to share the region.
\r<p>
\r<dt> <strong>VM_INHERIT_COPY</strong>
\r<dd>
\rGives child tasks a copy of the region.
\r<p>
\r<dt> <strong>VM_INHERIT_NONE</strong>
\r<dd>
\rProvides no access to the region for child tasks.
\r</dl>
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>vm_map</strong> function maps a portion of the specified
\rmemory object into the
\rvirtual address space belonging to <var>target_task</var>. The target task
\rcan be the calling
\rtask or another task, identified by its task kernel port.
\r<p>
\rThe portion of the memory object mapped is determined by <var>offset</var>
\rand <var>size</var>. The
\rkernel maps <var>address</var> to the offset, so that an access to the memory
\rstarts at the offset in the object.
\r<p>
\rThe <var>mask</var> parameter specifies additional alignment restrictions on
\rthe kernel's selection of the starting address. Uses for this mask include:
\r<ul>
\r<li>
\rForcing the memory address alignment for a mapping to be the same as the
\ralignment within the memory object.
\r<li>
\rQuickly finding the beginning of an allocated region by performing bit
\rarithmetic on an address known to be in the region.
\r<li>
\rEmulating a larger virtual page size.
\r</ul>
\r<p>
\rThe <var>cur_protection</var>, <var>max_protection</var>, and <var>inheritance</var>
\rparameters set the
\rprotection and inheritance attributes for the mapped object.
\rAs a rule, at least the
\rmaximum protection should be specified so that a server can make
\ra restricted (for
\rexample, read-only) mapping in a client atomically. The current
\rprotection and
\rinheritance parameters are provided for convenience so that the
\rcaller does not
\rhave to call <strong>vm_inherit</strong> and <strong>vm_protect</strong> separately.
\r<p>
\rThe same memory object can be mapped more than once and by more than one
\rtask. If an object is mapped by multiple tasks, the kernel maintains
\rconsistency
\rfor all the mappings if they use the same page alignment for <var>offset</var>
\rand are on
\rthe same host. In this case, the virtual memory to which the
\robject is mapped is
\rshared by all the tasks. Changes made by one task in its address space are
\rvisible to all the other tasks.
\rThe call will not return until the
\rmemory object is ready for
\ruse.
\r<h3>NOTES</h3>
\r<p>
\r<strong>vm_map</strong> allocates a region in a task's address space
\rand maps the specified
\rmemory object to this region. <strong>vm_allocate</strong> allocates
\ra zero-filled temporary
\rregion in a task's address space.
\r<p>
\rBefore a memory object can be mapped, a port naming it must be acquired from
\rthe memory manager serving it.
\r<p>
\rThis interface is machine word length specific because of the virtual address
\rparameter.
\r<h3>CAUTIONS</h3>
\r<p>
\rDo not attempt to map a memory object unless it has been provided by a
\rmemory manager that implements the memory object interface.
\rIf another type of port
\ris specified, a thread that accesses the mapped virtual memory may become
\rpermanently hung or may receive a memory exception.
\r<h3>RETURN VALUES</h3>
\r<dl>
\r<p>
\r<dt> <strong>KERN_NO_SPACE</strong>
\r<dd>
\rThere is not enough space in the task's address space to allocate the
\rnew region for the memory object.
\r<p>
\r<dt> <strong>KERN_PROTECTION_FAILURE</strong>
\r<dd>
\r<var>max_protection</var> or <var>cur_protection</var> exceeds
\rthat permitted by <var>memory_object</var>.
\r<p>
\r<dt> <strong>KERN_INVALID_OBJECT</strong>
\r<dd>
\rThe memory manager failed to map the memory object.
\r</dl>
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="vm_allocate.html"><strong>vm_allocate</strong></a>,
\r<a href="vm_remap.html"><strong>vm_remap</strong></a>.
\r\ No newline at end of file
+<h2>vm_map</h2>
+<hr>
+<p>
+<strong>Function</strong> - Map the specified memory object to a region of virtual memory.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t vm_map</strong>
+ <strong>(vm_task_t</strong> <var>target_task</var>,
+ <strong>vm_address_t</strong> <var>address</var>,
+ <strong>vm_size_t</strong> <var>size</var>,
+ <strong>vm_address_t</strong> <var>mask</var>,
+ <strong>boolean_t</strong> <var>anywhere</var>,
+ <strong>memory_object_t</strong> <var>memory_object</var>,
+ <strong>vm_offset_t</strong> <var>offset</var>,
+ <strong>boolean_t</strong> <var>copy</var>,
+ <strong>vm_prot_t</strong> <var>cur_protection</var>,
+ <strong>vm_prot_t</strong> <var>max_protection</var>,
+ <strong>vm_inherit_t</strong> <var>inheritance</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>target_task</var>
+<dd>
+[in task send right]
+The port for the task in whose address space the
+memory object is to be mapped.
+<p>
+<dt> <var>address</var>
+<dd>
+[pointer to in/out scalar]
+The starting address for the mapped object.
+The mapped object will start at the beginning of the page containing
+<var>address</var>. If there is not enough room following the address, the kernel
+does not map the object. The kernel returns the starting address
+actually used for the mapped object.
+<p>
+<dt> <var>size</var>
+<dd>
+[in scalar]
+The number of bytes to allocate for the object. The kernel
+rounds this number up to an integral number of virtual pages.
+<p>
+<dt> <var>mask</var>
+<dd>
+[in scalar]
+Alignment restrictions for starting address. Bits turned on in
+the mask will not be turned on in the starting address.
+<p>
+<dt> <var>anywhere</var>
+<dd>
+[in scalar]
+Placement indicator. The valid values are:
+<dl>
+<p>
+<dt> <strong>TRUE</strong>
+<dd>
+The kernel allocates the region in the next unused space that
+is sufficient within the address space. The kernel returns the
+starting address actually used in <var>address</var>.
+<p>
+<dt> <strong>FALSE</strong>
+<dd>
+The kernel allocates the region starting at <var>address</var> unless that
+space is already allocated.
+</dl>
+<p>
+<dt> <var>memory_object</var>
+<dd>
+[in memory-object send right]
+The port naming the
+memory object. If <strong>MEMORY_OBJECT_NULL</strong> is
+specified, the kernel allocates zero-filled memory, as with <strong>vm_allocate</strong>.
+<p>
+<dt> <var>offset</var>
+<dd>
+[in scalar]
+An offset within the memory object, in bytes. The kernel
+maps <var>address</var> to the specified offset.
+<p>
+<dt> <var>copy</var>
+<dd>
+[in scalar]
+Copy indicator. If true, the kernel copies the region of the
+memory object to the specified task's address space. If false, the region
+is directly mapped.
+<p>
+<dt> <var>cur_protection</var>
+<dd>
+[in scalar]
+The initial current protection for the region. Valid values are
+obtained by or'ing together the following values:
+<dl>
+<p>
+<dt> <strong>VM_PROT_READ</strong>
+<dd>
+Allows read access.
+<p>
+<dt> <strong>VM_PROT_WRITE</strong>
+<dd>
+Allows write access.
+<p>
+<dt> <strong>VM_PROT_EXECUTE</strong>
+<dd>
+Allows execute access.
+</dl>
+<p>
+<dt> <var>max_protection</var>
+<dd>
+[in scalar]
+The maximum protection for the region. Values are the same
+as for <var>cur_protection</var>.
+<p>
+<dt> <var>inheritance</var>
+<dd>
+[in scalar]
+The initial inheritance attribute for the region. Valid values
+are:
+<dl>
+<p>
+<dt> <strong>VM_INHERIT_SHARE</strong>
+<dd>
+Allows child tasks to share the region.
+<p>
+<dt> <strong>VM_INHERIT_COPY</strong>
+<dd>
+Gives child tasks a copy of the region.
+<p>
+<dt> <strong>VM_INHERIT_NONE</strong>
+<dd>
+Provides no access to the region for child tasks.
+</dl>
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>vm_map</strong> function maps a portion of the specified
+memory object into the
+virtual address space belonging to <var>target_task</var>. The target task
+can be the calling
+task or another task, identified by its task kernel port.
+<p>
+The portion of the memory object mapped is determined by <var>offset</var>
+and <var>size</var>. The
+kernel maps <var>address</var> to the offset, so that an access to the memory
+starts at the offset in the object.
+<p>
+The <var>mask</var> parameter specifies additional alignment restrictions on
+the kernel's selection of the starting address. Uses for this mask include:
+<ul>
+<li>
+Forcing the memory address alignment for a mapping to be the same as the
+alignment within the memory object.
+<li>
+Quickly finding the beginning of an allocated region by performing bit
+arithmetic on an address known to be in the region.
+<li>
+Emulating a larger virtual page size.
+</ul>
+<p>
+The <var>cur_protection</var>, <var>max_protection</var>, and <var>inheritance</var>
+parameters set the
+protection and inheritance attributes for the mapped object.
+As a rule, at least the
+maximum protection should be specified so that a server can make
+a restricted (for
+example, read-only) mapping in a client atomically. The current
+protection and
+inheritance parameters are provided for convenience so that the
+caller does not
+have to call <strong>vm_inherit</strong> and <strong>vm_protect</strong> separately.
+<p>
+The same memory object can be mapped more than once and by more than one
+task. If an object is mapped by multiple tasks, the kernel maintains
+consistency
+for all the mappings if they use the same page alignment for <var>offset</var>
+and are on
+the same host. In this case, the virtual memory to which the
+object is mapped is
+shared by all the tasks. Changes made by one task in its address space are
+visible to all the other tasks.
+The call will not return until the
+memory object is ready for
+use.
+<h3>NOTES</h3>
+<p>
+<strong>vm_map</strong> allocates a region in a task's address space
+and maps the specified
+memory object to this region. <strong>vm_allocate</strong> allocates
+a zero-filled temporary
+region in a task's address space.
+<p>
+Before a memory object can be mapped, a port naming it must be acquired from
+the memory manager serving it.
+<p>
+This interface is machine word length specific because of the virtual address
+parameter.
+<h3>CAUTIONS</h3>
+<p>
+Do not attempt to map a memory object unless it has been provided by a
+memory manager that implements the memory object interface.
+If another type of port
+is specified, a thread that accesses the mapped virtual memory may become
+permanently hung or may receive a memory exception.
+<h3>RETURN VALUES</h3>
+<dl>
+<p>
+<dt> <strong>KERN_NO_SPACE</strong>
+<dd>
+There is not enough space in the task's address space to allocate the
+new region for the memory object.
+<p>
+<dt> <strong>KERN_PROTECTION_FAILURE</strong>
+<dd>
+<var>max_protection</var> or <var>cur_protection</var> exceeds
+that permitted by <var>memory_object</var>.
+<p>
+<dt> <strong>KERN_INVALID_OBJECT</strong>
+<dd>
+The memory manager failed to map the memory object.
+</dl>
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="vm_allocate.html"><strong>vm_allocate</strong></a>,
+<a href="vm_remap.html"><strong>vm_remap</strong></a>.
projects / apple / xnu.git / blobdiff