main/syscalls/vmar_map_clock.md

<!--
Copyright 2023 The Fuchsia Authors. All rights reserved.
Use of this source code is governed by a BSD-style license that can be
found in the LICENSE file.

DO NOT EDIT. Generated from FIDL library zx by zither, a Fuchsia platform tool.

See //docs/reference/syscalls/README.md#documentation-generation for
regeneration instructions.
-->

# 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](vmar_map.md#Description) 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()](vmar_map.md#Errors)
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.

## See also

 - [mappable_clocks]
 - [`zx_vmar_map()`]
 - [`zx_vmar_unmap()`]
 - [`zx_object_get_info()`]
 - [`ZX_INFO_CLOCK_MAPPED_SIZE`]: object_get_info.md#zx_info_clock_mapped_size
 - [`ZX_INFO_VMAR_MAPS`]: object_get_info.md#zx_info_vmar_maps
 - [`ZX_INFO_PROCESS_MAPS`]: object_get_info.md#zx_info_process_maps

[mappable_clocks]: /docs/reference/kernel_objects/clock.md#mappable_clocks
[`zx_vmar_map()`]: vmar_map.md
[`zx_vmar_unmap()`]: vmar_unmap.md
[`zx_object_get_info()`]: object_get_info.md
[`ZX_INFO_CLOCK_MAPPED_SIZE`]: object_get_info.md#zx_info_clock_mapped_size
[`ZX_INFO_VMAR_MAPS`]: object_get_info.md#zx_info_vmar_maps
[`ZX_INFO_PROCESS_MAPS`]: object_get_info.md#zx_info_process_maps