zx_vmar_map_clock

Summary

Map a kernel clock object's state.

Declaration

zx_status_t zx_vmar_map_clock(zx_handle_t handle,
                              zx_vm_option_t options,
                              uint64_t vmar_offset,
                              zx_handle_t clock_handle,
                              uint64_t len,
                              user_out_ptr<zx_vaddr_t> mapped_addr);

Description

Maps the given clock's state into the given virtual memory address region. The mapping retains a reference to the underlying virtual memory object, which means closing the clock handle does not remove the mapping added by this function. Specified options are identical to those used in a call to zx_vmar_map(), except that the following options are explicitly disallowed and will always result in an error:

ZX_VM_PERM_WRITE
ZX_VM_PERM_EXECUTE
ZX_VM_PERM_READ_IF_XOM_UNSUPPORTED

Additionally, no vmo_offet is provided, and the length passed must be the length reported using a call to zx_object_get_info() executed against the clock object with the ZX_INFO_CLOCK_MAPPED_SIZE topic. Partial mappings of clock state are not allowed.

Mappings created using this syscall are always non-resizeable, regardless of options passed by the user.

In addition to having sufficient VMAR rights to create a mapping, the clock_handle must also have the ZX_RIGHT_READ and ZX_RIGHT_MAP rights.

Unmapping a clock is achieved the same way it is with a VMO, by passing the original mapped address and length to a call to zx_vmar_unmap().

User‘s may close their clock’s handle after mapping it and still read the clock's state. Closing the clock handle will not destroy the mapping, only a properly constructed call to zx_vmar_unmap() can do so.

Rights

handle must be of type ZX_OBJ_TYPE_VMAR.

clock_handle must be of type ZX_OBJ_TYPE_CLOCK.

Return value

zx_vmar_map_clock() 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 handle or clock_handle is not a valid handle.

ZX_ERR_WRONG_TYPE handle or clock_handle is not a VMAR or Clock handle, respectively.

ZX_ERR_BAD_STATE handle refers to a destroyed VMAR.

ZX_ERR_INVALID_ARGS for any of the following:

len does not match the mapped size reported by ZX_INFO_CLOCK_MAPPED_SIZE.
options contains one of the explicitly disallowed flags specified above.

Please also refer to the errors which may be returned by zx_vmar_map() for additional possible error common to both syscalls.

Notes

Mappings enumerated using the ZX_INFO_VMAR_MAPS or ZX_INFO_PROCESS_MAPS topics with the zx_object_get_info() syscall will contain the same information as a mapped VMO, with the following exceptions:

The string “kernel-clock” will be returned as the name of the mapping
The KOID of the mapping reported as the clock object's KOID.