Allocate a new subregion.
#include <zircon/syscalls.h> zx_status_t zx_vmar_allocate(zx_handle_t parent_vmar, zx_vm_option_t options, size_t offset, size_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:
and continues up to
Using ZX_VM_ALIGN flags with ZX_VM_SPECIFIC will fail if the parent_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 This may be due to the following:
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 zx_vmar_destroy()
.
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.