ZX_Clock_update

摘要

調整時鐘物件。

宣告

#include <zircon/syscalls.h>

zx_status_t zx_clock_update(zx_handle_t handle,
                            uint64_t options,
                            const void* args);

權限

handle 必須是 ZX_OBJ_TYPE_CLOCK 類型，且具有 ZX_RIGHT_WRITE。

說明

三個不同的參數可以由時鐘維護器動態控制。這些

  • 時鐘目前的值。
  • 時鐘費率調整，以與名詞的 PPM 差表示。
  • 時鐘目前的預估錯誤範圍。

當時鐘維護人員想要變更一或多個參數時，可使用 zx_clock_update 系統呼叫執行這項作業。從系統中其他使用者的角度來看，更新時鐘的參數是一項不可部分完成的作業。

時鐘維護器執行的第一次更新作業必須包含有效的值。這項更新會啟動時鐘並定義其初始值。在這項更新作業成功前，ZX_CLOCK_STARTED 信號會退出宣告，之後會宣告，並在時鐘的生命週期內保持不變。

為了更新時鐘，使用者填寫想調整的 zx_clock_update_args_v2_t 結構欄位，然後將結構傳遞至更新呼叫，在 options 中設定位元，表示結構的明確版本 (第 2 版)，以及以下哪些欄位有效且應設定。已定義的 options 位元

  • ZX_CLOCK_UPDATE_OPTION_SYNTHETIC_VALUE_VALID
  • ZX_CLOCK_UPDATE_OPTION_REFERENCE_VALUE_VALID
  • ZX_CLOCK_UPDATE_OPTION_RATE_ADJUST_VALID
  • ZX_CLOCK_UPDATE_OPTION_ERROR_BOUND_VALID

結構版本是透過 ZX_CLOCK_ARGS_VERSION(...) 巨集傳遞，尤其是第 2 版結構的 ZX_CLOCK_ARGS_VERSION(2)。

例如：

#include <zircon/syscalls.h>
#include <zircon/syscalls/clock.h>

void MaintainMyClock(zx_handle_t the_clock) {
  zx_clock_update_args_v2_t args;
  zx_status_t status;

  // Set the clock's value to 1500. Note that this also starts the clock.
  args.synthetic_value = 1500;
  status = zx_clock_update(the_clock,
                           ZX_CLOCK_ARGS_VERSION(2) | ZX_CLOCK_UPDATE_OPTION_SYNTHETIC_VALUE_VALID,
                           &args);
  if (status != ZX_OK) {
    // Panic!
    return;
  }

  // Make the clock run 23 PPM slower than nominal relative to clock monotonic.
  args.rate_adjust = -23;
  status = zx_clock_update(the_clock,
                           ZX_CLOCK_ARGS_VERSION(2) | ZX_CLOCK_UPDATE_OPTION_RATE_ADJUST_VALID,
                           &args);
  if (status != ZX_OK) {
    // Halt and catch fire
    return;
  }

  // Set the clock to 100,000, make it run 50 PPM faster than nominal, and specify an error bound of
  // +/- 400mSec, all at the same time.
  const uint64_t options = ZX_CLOCK_ARGS_VERSION(2) |
                           ZX_CLOCK_UPDATE_OPTION_SYNTHETIC_VALUE_VALID |
                           ZX_CLOCK_UPDATE_OPTION_RATE_ADJUST_VALID |
                           ZX_CLOCK_UPDATE_OPTION_ERROR_BOUND_VALID;
  args.synthetic_value = 100000;
  args.rate_adjust = 50;
  args.error_bound = ZX_MSEC(400);
  status = zx_clock_update(the_clock, options, &args);
  if (status != ZX_OK) {
    // Burn down, fall over, and then sink into the swamp.
    return;
  }
}

明確提供的參考時間。

有了 V2 更新結構，現在可明確控制時鐘更新作業的參考時間 (但有一些限制)。請注意，成功時，使用者更新引數指定的實際新參照 <-> 合成轉換將取代呼叫 zx_clock_update 期間的舊轉換。提供明確的參照時間「不會」影響實際轉換更新的時間，而且會在呼叫 zx_clock_update 時一律生效。

RFC-0077 中提供的圖表可協助您瞭解以下作業的影響。

利用明確提供的參考時間更新綜合值。

當使用者以明確提供的參考時間 (R) 更新時鐘的合成值 (S) 時，他們會指定新轉換將傳遞的點 ([R, S])。換句話說，新的轉換會明確指定「在參考時間軸上是時間 R 時，會是合成時間軸的 S 時間」。

#include <zircon/syscalls.h>
#include <zircon/syscalls/clock.h>

// Set the syntheic value of the clock to be "synth" at the explicitly provided
// reference time "ref". In other words, upon success, this update operation will
// cause the clock's transformation from reference to synthetic time to
// specifically pass through the point (ref, synth)
zx_status_t SetSynthAtRef(zx_handle_t the_clock, zx_time_t ref, zx_time_t synth) {
  zx_clock_update_args_v2_t args;

  uint64_t options = ZX_CLOCK_ARGS_VERSION(2) |
                     ZX_CLOCK_UPDATE_OPTION_REFERENCE_VALUE_VALID |
                     ZX_CLOCK_UPDATE_OPTION_SYNTHETIC_VALUE_VALID;

  // Note that these options are equivalent, they just use a shorthand to
  // specify that both values are valid.
  options = ZX_CLOCK_ARGS_VERSION(2) | ZX_CLOCK_UPDATE_OPTION_BOTH_VALUES_VALID;

  args.reference_value = ref;
  args.synthetic_value = synth;
  return zx_clock_update(the_clock, options, args);
}

以明確提供的參考時間更新費率調整。

允許 T(R) 做為更新作業前時鐘的綜合時間轉換函式，方法是將參照時間 R 轉換為綜合時間。當使用者透過明確提供的參考時間 (R) 調整時鐘速率時，就會指定時鐘的新轉換 T'(R) 的斜率，例如 T'(R) = T(R)。也就是說，在參照時間 R 時，新轉換將會經過舊轉換的合成時間，但斜率不同。

#include <zircon/syscalls.h>
#include <zircon/syscalls/clock.h>

zx_status_t SetRateAtRef(zx_handle_t the_clock, zx_time_t ref, int32_t ppm_adj) {
  zx_clock_update_args_v2_t args;

  const uint64_t options = ZX_CLOCK_ARGS_VERSION(2) |
                           ZX_CLOCK_UPDATE_OPTION_REFERENCE_VALUE_VALID |
                           ZX_CLOCK_UPDATE_OPTION_RATE_ADJUST_VALID;
  args.reference_value = ref;
  args.rate_adjust = ppm_adj;

  return zx_clock_update(the_clock, options, args);
}

附註、規則和限制。

  • 特定的參照值非必要。更新作業期間，您仍可省略參照值。更新作業會直接在處理作業時使用目前的參考時間。
  • 為時鐘更新作業提供明確參照值時，必須一併提供綜合值和/或費率調整。嘗試只更新明確參照值的錯誤範圍並不合法。
  • 一律不允許針對連續的更新作業明確提供參照值，因為幾乎一律暗示不中斷。
  • 系統「可以」針對單數時鐘更新作業的更新作業參照值，但「只有」在更新後時鐘的行為維持單調模式時才有效。
  • 在更新作業期間明確提供的參照值，會導致在「現在」的參照期間執行的讀取作業違反所設的 Backstop 時間，會導致作業遭到拒絕。
  • 更新單時鐘時，無法同時更新綜合值和費率調整。

RFC-0077 中提供的詳細資料可協助您瞭解部分規則和限制背後的原因。

傳回值

成功後，會傳回 ZX_OK。

錯誤

  • ZX_ERR_BAD_HANDLE：控制代碼是無效控制代碼，或是非 ZX_OBJ_TYPE_CLOCK 物件類型的控制代碼。
  • ZX_ERR_ACCESS_DENIED：處理常式缺少 ZX_RIGHT_WRITE。
  • ZX_ERR_INVALID_ARGS：提出的更新要求與時鐘的屬性不相容。請參閱 DESCRIPTION 一節，進一步瞭解允許的時鐘更新作業。否則，引數結構的版本/指標不正確。

另請參閱