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