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