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