1# zx_vmar_map
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7vmar_map - add a memory mapping
8
9## SYNOPSIS
10
11<!-- Updated by update-docs-from-abigen, do not edit. -->
12
13```
14#include <zircon/syscalls.h>
15
16zx_status_t zx_vmar_map(zx_handle_t handle,
17                        zx_vm_option_t options,
18                        uint64_t vmar_offset,
19                        zx_handle_t vmo,
20                        uint64_t vmo_offset,
21                        uint64_t len,
22                        zx_vaddr_t* mapped_addr);
23```
24
25## DESCRIPTION
26
27Maps the given VMO into the given virtual memory address region.  The mapping
28retains a reference to the underlying virtual memory object, which means
29closing the VMO handle does not remove the mapping added by this function.
30
31*options* is a bit vector of the following:
32- **ZX_VM_SPECIFIC**  Use the *vmar_offset* to place the mapping, invalid if
33  *handle* does not have the **ZX_VM_CAN_MAP_SPECIFIC** permission.
34  *vmar_offset* is an offset relative to the base address of the given VMAR.
35  It is an error to specify a range that overlaps with another VMAR or mapping.
36- **ZX_VM_SPECIFIC_OVERWRITE**  Same as **ZX_VM_SPECIFIC**, but can
37  overlap another mapping.  It is still an error to partially-overlap another VMAR.
38  If the range meets these requirements, it will atomically (with respect to all
39  other map/unmap/protect operations) replace existing mappings in the area.
40- **ZX_VM_PERM_READ**  Map *vmo* as readable.  It is an error if *handle*
41  does not have **ZX_VM_CAN_MAP_READ** permissions, the *handle* does
42  not have the **ZX_RIGHT_READ** right, or the *vmo* handle does not have the
43  **ZX_RIGHT_READ** right.
44- **ZX_VM_PERM_WRITE**  Map *vmo* as writable.  It is an error if *handle*
45  does not have **ZX_VM_CAN_MAP_WRITE** permissions, the *handle* does
46  not have the **ZX_RIGHT_WRITE** right, or the *vmo* handle does not have the
47  **ZX_RIGHT_WRITE** right.
48- **ZX_VM_PERM_EXECUTE**  Map *vmo* as executable.  It is an error if *handle*
49  does not have **ZX_VM_CAN_MAP_EXECUTE** permissions, the *handle* handle does
50  not have the **ZX_RIGHT_EXECUTE** right, or the *vmo* handle does not have the
51  **ZX_RIGHT_EXECUTE** right.
52- **ZX_VM_MAP_RANGE**  Immediately page into the new mapping all backed
53  regions of the VMO.  This cannot be specified if
54  **ZX_VM_SPECIFIC_OVERWRITE** is used.
55- **ZX_VM_REQUIRE_NON_RESIZABLE** Maps the VMO only if the VMO is non-resizable,
56  that is, it was created with the **ZX_VMO_NON_RESIZABLE** option.
57
58*vmar_offset* must be 0 if *options* does not have **ZX_VM_SPECIFIC** or
59**ZX_VM_SPECIFIC_OVERWRITE** set.  If neither of those are set, then
60the mapping will be assigned an offset at random by the kernel (with an
61allocator determined by policy set on the target VMAR).
62
63*len* must be page-aligned.
64
65## RIGHTS
66
67<!-- Updated by update-docs-from-abigen, do not edit. -->
68
69*handle* must be of type **ZX_OBJ_TYPE_VMAR**.
70
71*vmo* must be of type **ZX_OBJ_TYPE_VMO**.
72
73## RETURN VALUE
74
75`zx_vmar_map()` returns **ZX_OK** and the absolute base address of the
76mapping (via *mapped_addr*) on success.  The base address will be page-aligned
77and non-zero.  In the event of failure, a negative error value is returned.
78
79## ERRORS
80
81**ZX_ERR_BAD_HANDLE**  *handle* or *vmo* is not a valid handle.
82
83**ZX_ERR_WRONG_TYPE**  *handle* or *vmo* is not a VMAR or VMO handle, respectively.
84
85**ZX_ERR_BAD_STATE**  *handle* refers to a destroyed VMAR.
86
87**ZX_ERR_INVALID_ARGS** *mapped_addr* or *options* are not valid, *vmar_offset* is
88non-zero when neither **ZX_VM_SPECIFIC** nor
89**ZX_VM_SPECIFIC_OVERWRITE** are given,
90**ZX_VM_SPECIFIC_OVERWRITE** and **ZX_VM_MAP_RANGE** are both given,
91*vmar_offset* and *len* describe an unsatisfiable allocation due to exceeding the region bounds,
92*vmar_offset* or *vmo_offset* or *len* are not page-aligned,
93`vmo_offset + ROUNDUP(len, PAGE_SIZE)` overflows.
94
95**ZX_ERR_ACCESS_DENIED**  Insufficient privileges to make the requested mapping.
96
97**ZX_ERR_NOT_SUPPORTED** The VMO is resizable and **ZX_VM_REQUIRE_NON_RESIZABLE** was
98requested.
99
100**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
101There is no good way for userspace to handle this (unlikely) error.
102In a future build this error will no longer occur.
103
104## NOTES
105
106The VMO that backs a memory mapping can be resized to a smaller size. This can cause the
107thread is reading or writing to the VMAR region to fault. To avoid this hazard, services
108that receive VMOs from clients should use **ZX_VM_REQUIRE_NON_RESIZABLE** when mapping
109the VMO.
110
111## SEE ALSO
112
113 - [`zx_vmar_allocate()`]
114 - [`zx_vmar_destroy()`]
115 - [`zx_vmar_protect()`]
116 - [`zx_vmar_unmap()`]
117
118<!-- References updated by update-docs-from-abigen, do not edit. -->
119
120[`zx_vmar_allocate()`]: vmar_allocate.md
121[`zx_vmar_destroy()`]: vmar_destroy.md
122[`zx_vmar_protect()`]: vmar_protect.md
123[`zx_vmar_unmap()`]: vmar_unmap.md
124