1# Virtual Memory Address Region
2
3## NAME
4
5vm_address_region - A contiguous region of a virtual memory address space
6
7## SYNOPSIS
8
9Virtual Memory Address Regions (VMARs) represent contiguous parts of a virtual
10address space.
11
12## DESCRIPTION
13
14VMARs are used by the kernel and userspace to represent the allocation of an
15address space.
16
17Every process starts with a single VMAR (the root VMAR) that spans the entire
18address space (see [process_create](../syscalls/process_create.md)).  Each VMAR
19can be logically divided up into any number of non-overlapping parts, each
20representing a child VMARs, a virtual memory mapping, or a gap.  Child VMARs
21are created using [vmar_allocate](../syscalls/vmar_allocate.md).  VM mappings
22are created using [vmar_map](../syscalls/vmar_map.md).
23
24VMARs have a hierarchical permission model for allowable mapping permissions.
25For example, the root VMAR allows read, write, and executable mapping.  One
26could create a child VMAR that only allows read and write mappings, in which
27it would be illegal to create a child that allows executable mappings.
28
29When a VMAR is created using vmar_allocate, its parent VMAR retains a reference
30to it.  Because of this, if all handles to the child VMAR are closed, the child
31and its descendants will remain active in the address space.  In order to
32disconnect the child from the address space, [vmar_destroy](../syscalls/vmar_destroy.md)
33must be called on a handle to the child.
34
35By default, all allocations of address space are randomized.  At VMAR
36creation time, the caller can choose which randomization algorithm is used.
37The default allocator attempts to spread allocations widely across the full
38width of the VMAR.  The alternate allocator, selected with
39*ZX_VM_COMPACT*, attempts to keep allocations close together within the
40VMAR, but at a random location within the range.  It is recommended to use
41the default allocator.
42
43VMARs optionally support a fixed-offset mapping mode (called specific mapping).
44This mode can be used to create guard pages or ensure the relative locations of
45mappings.  Each VMAR may have the *ZX_VM_CAN_MAP_SPECIFIC* permission,
46regardless of whether or not its parent VMAR had that permission.
47
48## EXAMPLE
49
50```c
51#include <zircon/syscalls.h>
52
53/* Map this VMO into the given VMAR, with |before| bytes of unmapped guard space
54   before it and |after| bytes after it.  */
55zx_status_t map_with_guard(zx_handle_t vmar, size_t before, size_t after,
56                           zx_handle_t vmo, uint64_t vmo_offset,
57                           size_t mapping_len, uintptr_t* mapped_addr,
58                           zx_handle_t* wrapping_vmar) {
59
60    /* wrap around check elided */
61    const size_t child_vmar_size = before + after + mapping_len;
62    const zx_vm_option_t child_vmar_options = ZX_VM_CAN_MAP_READ |
63                                              ZX_VM_CAN_MAP_WRITE |
64                                              ZX_VM_CAN_MAP_SPECIFIC;
65    const zx_vm_option_t mapping_options = ZX_VM_SPECIFIC |
66                                           ZX_VM_PERM_READ |
67                                           ZX_VM_PERM_WRITE;
68
69    uintptr_t child_vmar_addr;
70    zx_handle_t child_vmar;
71    zx_status_t status = zx_vmar_allocate(vmar, child_vmar_options, 0,
72                                          child_vmar_size,
73                                          &child_vmar,
74                                          &child_vmar_addr);
75    if (status != ZX_OK) {
76        return status;
77    }
78
79    status = zx_vmar_map(child_vmar, mapping_options, before, vmo, vmo_offset,
80                         mapping_len, mapped_addr);
81    if (status != ZX_OK) {
82        zx_vmar_destroy(child_vmar);
83        zx_handle_close(child_vmar);
84        return status;
85    }
86
87    *wrapping_vmar = child_vmar;
88    return ZX_OK;
89}
90```
91
92## SEE ALSO
93
94+ [vm_object](vm_object.md) - Virtual Memory Objects
95
96## SYSCALLS
97
98+ [vmar_allocate](../syscalls/vmar_allocate.md) - create a new child VMAR
99+ [vmar_map](../syscalls/vmar_map.md) - map a VMO into a process
100+ [vmar_unmap](../syscalls/vmar_unmap.md) - unmap a memory region from a process
101+ [vmar_protect](../syscalls/vmar_protect.md) - adjust memory access permissions
102+ [vmar_destroy](../syscalls/vmar_destroy.md) - destroy a VMAR and all of its children
103