zx_vmar_map

NAME

vmar_map - add a memory mapping

SYNOPSIS

#include <zircon/syscalls.h>

zx_status_t zx_vmar_map(zx_handle_t vmar, uint64_t vmar_offset,
                        zx_handle_t vmo, uint64_t vmo_offset, uint64_t len,
                        uint32_t map_flags, zx_vaddr_t* mapped_addr)

DESCRIPTION

Maps the given VMO into the given virtual memory address region. The mapping retains a reference to the underlying virtual memory object, which means closing the VMO handle does not remove the mapping added by this function.

map_flags is a bit vector of the following flags:

ZX_VM_FLAG_SPECIFIC Use the vmar_offset to place the mapping, invalid if vmar does not have the ZX_VM_FLAG_CAN_MAP_SPECIFIC permission. vmar_offset is an offset relative to the base address of the given VMAR. It is an error to specify a range that overlaps with another VMAR or mapping.
ZX_VM_FLAG_SPECIFIC_OVERWRITE Same as ZX_VM_FLAG_SPECIFIC, but can overlap another mapping. It is still an error to partially-overlap another VMAR. If the range meets these requirements, it will atomically (with respect to all other map/unmap/protect operations) replace existing mappings in the area.
ZX_VM_FLAG_PERM_READ Map vmo as readable. It is an error if vmar does not have ZX_VM_FLAG_CAN_MAP_READ permissions, the vmar handle does not have the ZX_RIGHT_READ right, or the vmo handle does not have the ZX_RIGHT_READ right.
ZX_VM_FLAG_PERM_WRITE Map vmo as writable. It is an error if vmar does not have ZX_VM_FLAG_CAN_MAP_WRITE permissions, the vmar handle does not have the ZX_RIGHT_WRITE right, or the vmo handle does not have the ZX_RIGHT_WRITE right.
ZX_VM_FLAG_PERM_EXECUTE Map vmo as executable. It is an error if vmar does not have ZX_VM_FLAG_CAN_MAP_EXECUTE permissions, the vmar handle does not have the ZX_RIGHT_EXECUTE right, or the vmo handle does not have the ZX_RIGHT_EXECUTE right.
ZX_VM_FLAG_MAP_RANGE Immediately page into the new mapping all backed regions of the VMO. This cannot be specified if ZX_VM_FLAG_SPECIFIC_OVERWRITE is used.
ZX_VM_FLAG_REQUIRE_NON_RESIZABLE Maps the VMO only if the VMO is non-resizable, that is, it was created with the ZX_VMO_NON_RESIZABLE option.

vmar_offset must be 0 if map_flags does not have ZX_VM_FLAG_SPECIFIC or ZX_VM_FLAG_SPECIFIC_OVERWRITE set. If neither of those flags are set, then the mapping will be assigned an offset at random by the kernel (with an allocator determined by policy set on the target VMAR).

RETURN VALUE

vmar_map() returns ZX_OK and the absolute base address of the mapping (via mapped_addr) on success. The base address will be page-aligned and non-zero. In the event of failure, a negative error value is returned.

ERRORS

ZX_ERR_BAD_HANDLE vmar or vmo is not a valid handle.

ZX_ERR_WRONG_TYPE vmar or vmo is not a VMAR or VMO handle, respectively.

ZX_ERR_BAD_STATE vmar refers to a destroyed VMAR.

ZX_ERR_INVALID_ARGS mapped_addr or map_flags are not valid, vmar_offset is non-zero when neither ZX_VM_FLAG_SPECIFIC nor ZX_VM_FLAG_SPECIFIC_OVERWRITE are given, ZX_VM_FLAG_SPECIFIC_OVERWRITE and ZX_VM_FLAG_MAP_RANGE are both given, vmar_offset and len describe an unsatisfiable allocation due to exceeding the region bounds, vmar_offset or vmo_offset are not page-aligned, vmo_offset + ROUNDUP(len, PAGE_SIZE) overflows, or len is 0.

ZX_ERR_ACCESS_DENIED Insufficient privileges to make the requested mapping.

ZX_ERR_NOT_SUPPORTED The VMO is resizable and ZX_VM_FLAG_REQUIRE_NON_RESIZABLE was requested.

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.

NOTES

The VMO that backs a memory mapping can be resized to a smaller size. This can cause the thread is reading or writting to the VMAR region to fault. To avoid this hazard, services that receive VMOs from clients should use ZX_VM_FLAG_REQUIRE_NON_RESIZABLE when mapping the VMO.