Allocate a new subregion.
#include <zircon/syscalls.h> zx_status_t zx_vmar_allocate(zx_handle_t parent_vmar, zx_vm_option_t options, uint64_t offset, uint64_t size, zx_handle_t* child_vmar, zx_vaddr_t* child_addr);
Creates a new VMAR within the one specified by parent_vmar.
options is a bit vector that contains one more of the following:
offset must be 0 if options does not have ZX_VM_SPECIFIC set.
In addition, the following power-of-two alignment flags can added:
TODO(ZX-3978): Currently, alignment flags greater than 4KB cannot be used when allocating a new VMAR within a compact VMAR.
Using ZX_VM_ALIGN flags with ZX_VM_SPECIFIC will fail if the partent_vmar base address + offset are not aligned to the requested value.
If options & ZX_VM_CAN_MAP_READ, parent_vmar must be of type ZX_OBJ_TYPE_VMAR and have ZX_RIGHT_READ.
If options & ZX_VM_CAN_MAP_WRITE, parent_vmar must be of type ZX_OBJ_TYPE_VMAR and have ZX_RIGHT_WRITE.
If options & ZX_VM_CAN_MAP_EXECUTE, parent_vmar must be of type ZX_OBJ_TYPE_VMAR and have ZX_RIGHT_EXECUTE.
zx_vmar_allocate() returns ZX_OK, the absolute base address of the subregion (via child_addr), and a handle to the new subregion (via child_vmar) on success. The base address will be page-aligned and non-zero. In the event of failure, a negative error value is returned.
ZX_ERR_BAD_HANDLE parent_vmar is not a valid handle.
ZX_ERR_WRONG_TYPE parent_vmar is not a VMAR handle.
ZX_ERR_BAD_STATE parent_vmar refers to a destroyed VMAR.
ZX_ERR_INVALID_ARGS child_vmar or child_addr are not valid, offset is non-zero when ZX_VM_SPECIFIC is not given, offset and size describe an unsatisfiable allocation due to exceeding the region bounds, offset or size is not page-aligned, or size is 0.
ZX_ERR_NO_MEMORY Failure due to lack of memory. There is no good way for userspace to handle this (unlikely) error. In a future build this error will no longer occur.
ZX_ERR_ACCESS_DENIED Insufficient privileges to make the requested allocation.
The address space occupied by a VMAR will remain allocated (within its parent VMAR) until the VMAR is destroyed by calling
Note that just closing the VMAR's handle does not deallocate the address space occupied by the VMAR.
The kernel interprets this flag as a request to reduce sprawl in allocations. While this does not necessitate reducing the absolute entropy of the allocated addresses, there will potentially be a very high correlation between allocations. This is a trade-off that the developer can make to increase locality of allocations and reduce the number of page tables necessary, if they are willing to have certain addresses be more correlated.