1# zx_vmar_allocate
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7vmar_allocate - allocate a new subregion
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_allocate(zx_handle_t parent_vmar,
17                             zx_vm_option_t options,
18                             uint64_t offset,
19                             uint64_t size,
20                             zx_handle_t* child_vmar,
21                             zx_vaddr_t* child_addr);
22```
23
24## DESCRIPTION
25
26Creates a new VMAR within the one specified by *parent_vmar*.
27
28*options* is a bit vector that contains one more of the following:
29- **ZX_VM_COMPACT**  A hint to the kernel that allocations and mappings
30  within the newly created subregion should be kept close together.   See the
31  NOTES section below for discussion.
32- **ZX_VM_SPECIFIC**  Use the *offset* to place the mapping, invalid if
33  vmar does not have the **ZX_VM_CAN_MAP_SPECIFIC** permission.  *offset*
34  is an offset relative to the base address of the parent region.  It is an error
35  to specify an address range that overlaps with another VMAR or mapping.
36- **ZX_VM_CAN_MAP_SPECIFIC**  The new VMAR can have subregions/mappings
37  created with **ZX_VM_SPECIFIC**.  It is NOT an error if the parent does
38  not have **ZX_VM_CAN_MAP_SPECIFIC** permissions.
39- **ZX_VM_CAN_MAP_READ**  The new VMAR can contain readable mappings.
40  It is an error if the parent does not have **ZX_VM_CAN_MAP_READ** permissions.
41- **ZX_VM_CAN_MAP_WRITE**  The new VMAR can contain writable mappings.
42  It is an error if the parent does not have **ZX_VM_CAN_MAP_WRITE** permissions.
43- **ZX_VM_CAN_MAP_EXECUTE**  The new VMAR can contain executable mappings.
44  It is an error if the parent does not have **ZX_VM_CAN_MAP_EXECUTE** permissions.
45
46*offset* must be 0 if *options* does not have **ZX_VM_SPECIFIC** set.
47
48## RIGHTS
49
50<!-- Updated by update-docs-from-abigen, do not edit. -->
51
52If *options* & **ZX_VM_CAN_MAP_READ**, *parent_vmar* must be of type **ZX_OBJ_TYPE_VMAR** and have **ZX_RIGHT_READ**.
53
54If *options* & **ZX_VM_CAN_MAP_WRITE**, *parent_vmar* must be of type **ZX_OBJ_TYPE_VMAR** and have **ZX_RIGHT_WRITE**.
55
56If *options* & **ZX_VM_CAN_MAP_EXECUTE**, *parent_vmar* must be of type **ZX_OBJ_TYPE_VMAR** and have **ZX_RIGHT_EXECUTE**.
57
58## RETURN VALUE
59
60`zx_vmar_allocate()` returns **ZX_OK**, the absolute base address of the
61subregion (via *child_addr*), and a handle to the new subregion (via
62*child_vmar*) on success.  The base address will be page-aligned and non-zero.
63In the event of failure, a negative error value is returned.
64
65## ERRORS
66
67**ZX_ERR_BAD_HANDLE**  *parent_vmar* is not a valid handle.
68
69**ZX_ERR_WRONG_TYPE**  *parent_vmar* is not a VMAR handle.
70
71**ZX_ERR_BAD_STATE**  *parent_vmar* refers to a destroyed VMAR.
72
73**ZX_ERR_INVALID_ARGS**  *child_vmar* or *child_addr* are not valid, *offset* is
74non-zero when **ZX_VM_SPECIFIC** is not given, *offset* and *size* describe
75an unsatisfiable allocation due to exceeding the region bounds, *offset*
76or *size* is not page-aligned, or *size* is 0.
77
78**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
79There is no good way for userspace to handle this (unlikely) error.
80In a future build this error will no longer occur.
81
82**ZX_ERR_ACCESS_DENIED**  Insufficient privileges to make the requested allocation.
83
84## NOTES
85
86### Deallocation
87
88The address space occupied by a VMAR will remain allocated (within its
89parent VMAR) until the VMAR is destroyed by calling [`zx_vmar_destroy()`].
90
91Note that just closing the VMAR's handle does not deallocate the address
92space occupied by the VMAR.
93
94### The COMPACT flag
95
96The kernel interprets this flag as a request to reduce sprawl in allocations.
97While this does not necessitate reducing the absolute entropy of the allocated
98addresses, there will potentially be a very high correlation between allocations.
99This is a trade-off that the developer can make to increase locality of
100allocations and reduce the number of page tables necessary, if they are willing
101to have certain addresses be more correlated.
102
103## SEE ALSO
104
105 - [`zx_vmar_destroy()`]
106 - [`zx_vmar_map()`]
107 - [`zx_vmar_protect()`]
108 - [`zx_vmar_unmap()`]
109
110<!-- References updated by update-docs-from-abigen, do not edit. -->
111
112[`zx_vmar_destroy()`]: vmar_destroy.md
113[`zx_vmar_map()`]: vmar_map.md
114[`zx_vmar_protect()`]: vmar_protect.md
115[`zx_vmar_unmap()`]: vmar_unmap.md
116