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 syscall更新時鐘的參數為 從系統內所有其他使用者的角度來看，單一不可分割的運算。

時鐘維護器執行的第一項更新作業必須包含有效的 值。本次更新是啟動時鐘並定義其初始的更新 值。在這項更新作業完成前，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 可能有助於瞭解下述作業帶來的影響。

使用明確提供的參照時間更新綜合值。

當使用者以明確方式更新時鐘的合成值 (S) 時 提供的參考時間 (R)，但他們是透過[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);
}

附註、規則和限制。

  • 不需要明確的參照值。您仍可 參照值。更新作業將會 而是在作業處理完成後，使用目前的參考時間。
  • 為時鐘更新作業提供明確的參照值時， 你也必須同時提供綜合值和/或費率調整項 或更新提示嘗試只更新 明確參照值。
  • 為持續更新作業明確提供參照值 切勿使用時鐘，因為這樣幾乎一定會表示不中斷。
  • 為單調的更新作業明確提供參照值 允許時鐘，但只有代表時鐘行為仍為單調 。
  • 在更新作業期間明確提供的參照值， 導致系統在「現在」的參照時間執行讀取作業違反已設定的 時鐘的回溯時間會導致作業遭到拒絕。
  • 更新單調時鐘時，無法同時 綜合值更新和費率調整。

詳細資料來源 RFC-0077 可能有助於瞭解部分規則和限制背後的原因。

傳回值

成功時傳回 ZX_OK。

錯誤

  • ZX_ERR_BAD_HANDLE：帳號代碼是無效的帳號代碼，或是 不是 ZX_OBJ_TYPE_CLOCK 的物件類型。
  • ZX_ERR_ACCESS_DENIED：帳號代碼缺少 ZX_RIGHT_WRITE 的右側。
  • ZX_ERR_INVALID_ARGS：提出的更新要求與 時鐘的屬性詳情請參閱DESCRIPTION一節 許可的時鐘更新作業。如果不是的話，則會執行 引數結構不正確

另請參閱