zx_clock_update

NAME

Make adjustments to a clock object.

SYNOPSIS

  1. #include <zircon/syscalls.h>
  3. zx_status_t zx_clock_update(zx_handle_t handle,
  4.                             uint64_t options,
  5.                             const void* args);

RIGHTS

handle must be of type ZX_OBJ_TYPE_CLOCK and have ZX_RIGHT_WRITE.

DESCRIPTION

Three different parameters may be dynamically controlled by a clock maintainer. They are

  • The clock’s current value.
  • The clock’s rate adjustment, expressed in PPM deviation from nominal.
  • The clock’s current estimated error bounds.

When a clock maintainer wishes to change one or more of these parameters, they may do so using the zx_clock_update syscall. Updating a clock’s parameters is an atomic operation from the perspective of all other users in the system.

The first update operation performed by a clock maintainer must include a valid value. This update is the update that starts the clock and defines its initial value. Before this update operation has succeeded, the ZX_CLOCK_STARTED signal will be de-asserted, and afterwards it will be asserted and remain so for the lifetime of the clock.

In order to update a clock, a user fills out the fields of a zx_clock_update_args_v1_t structure that they wish to adjust, then passes the structure to the update call, setting the bits in options that indicate which of these fields are valid and should be set. Defined options bits are

  • ZX_CLOCK_UPDATE_OPTION_VALUE_VALID
  • ZX_CLOCK_UPDATE_OPTION_RATE_ADJUST_VALID
  • ZX_CLOCK_UPDATE_OPTION_ERROR_BOUND_VALID

In addition, maintainer must indicate that they are using the V1 version of the struct using the ZX_CLOCK_ARGS_VERSION(…) macro.

For example

  1. #include <zircon/syscalls.h>
  2. #include <zircon/syscalls/clock.h>
  4. void MaintainMyClock(zx_handle_t the_clock) {
  5.   zx_clock_update_args_v1_t args;
  6.   zx_handle_t the_clock;
  7.   zx_status_t status;
  9.   // Set the clock's value to 1500. Note that this also starts the clock.
  10.   args.value = 1500;
  11.   status = zx_clock_update(the_clock,
  12.                            ZX_CLOCK_ARGS_VERSION(1) | ZX_CLOCK_UPDATE_OPTION_VALUE_VALID,
  13.                            &args);
  14.   if (status != ZX_OK) {
  15.     // Panic!
  16.     return;
  17.   }
  19.   // Make the clock run 23 PPM slower than nominal relative to clock monotonic.
  20.   args.rate_adjust = -23;
  21.   status = zx_clock_update(the_clock,
  22.                            ZX_CLOCK_ARGS_VERSION(1) | ZX_CLOCK_UPDATE_OPTION_RATE_ADJUST_VALID,
  23.                            &args);
  24.   if (status != ZX_OK) {
  25.     // Halt and catch fire
  26.     return;
  27.   }
  29.   // Set the clock to 100,000, make it run 50 PPM faster than nominal, and specify an error bound of
  30.   // +/- 400mSec, all at the same time.
  31.   const uint64_t options = ZX_CLOCK_ARGS_VERSION(1) |
  32.                            ZX_CLOCK_UPDATE_OPTION_VALUE_VALID |
  33.                            ZX_CLOCK_UPDATE_OPTION_RATE_ADJUST_VALID |
  34.                            ZX_CLOCK_UPDATE_OPTION_ERROR_BOUND_VALID;
  35.   args.value = 100000;
  36.   args.rate_adjust = 50;
  37.   args.error_bound = ZX_MSEC(400);
  38.   status = zx_clock_update(the_clock, options, &args);
  39.   if (status != ZX_OK) {
  40.     // Burn down, fall over, and then sink into the swamp.
  41.     return;
  42.   }
  43. }

RETURN VALUE

On success, returns ZX_OK.

ERRORS

  • ZX_ERR_BAD_HANDLE : handle is either an invalid handle, or a handle to an object type that is not ZX_OBJ_TYPE_CLOCK.
  • ZX_ERR_ACCESS_DENIED : handle lacks the ZX_RIGHT_WRITE right.
  • ZX_ERR_INVALID_ARGS : The update request made is incompatible with the properties of the clock. See the DESCRIPTION section for details of permissible clock update operations. Otherwise, the version/pointer of the arguments structure is incorrect.

SEE ALSO