fuchsia.hardware.hrtimer

新增：HEAD

通訊協定

裝置

定義於 fuchsia.hardware.hrtimer/hrtimer.fidl

提供高解析度計時器支援的驅動程式。這個 API 適用於 CPU 以外硬體提供的計時器，例如這個驅動程式庫可能會抽象化 SoC 提供的硬體。

GetProperties

取得驅動程式庫屬性。

要求

<EMPTY>

回應

名稱類型
payload Device_GetProperties_Result

GetTicksLeft

取得計時器 id 到期前剩餘的刻度。

如果指定的 id 無效，這項呼叫會傳回 INVALID_ARGS。

要求

名稱類型
id uint64

回應

名稱類型
payload Device_GetTicksLeft_Result

ReadClock

讀取目前計時器的時鐘值。

傳回的刻度是以指定解析度的相對時間單位表示。使用 GetProperties() 判斷可用的解析度。

錯誤： BAD_STATE：目前沒有任何時鐘正在執行。 INVALID_ARGS：id 或 resolution 無效或不支援。 NOT_SUPPORTED：如果 supports_read 為 false，或未實作方法。INTERNAL_ERROR：內部執行階段錯誤。

要求

名稱類型
id uint64
resolution Resolution

回應

名稱類型
payload Device_ReadClock_Result

ReadTimer

讀取目前計時器的設定或逾時值。

傳回的刻度是以指定解析度的相對時間單位表示。使用 GetProperties() 判斷可用的解析度。

錯誤： BAD_STATE：目前沒有可讀取的計時器。 INVALID_ARGS：id 或 resolution 無效或不支援。 NOT_SUPPORTED：如果 supports_read 為 false，或未實作方法。INTERNAL_ERROR：內部執行階段錯誤。

要求

名稱類型
id uint64
resolution Resolution

回應

名稱類型
payload Device_ReadTimer_Result

SetEvent

設定 Zircon 事件，在計時器到期時通知。

計時器到期時，系統會透過 ZX_EVENT_SIGNALED 信號通知。用戶端必須負責清除 ZX_EVENT_SIGNALED 信號。系統會取代先前為特定 id 設定的任何事件。請注意，這可能會與已啟動計時器到期時發出的事件信號發生競爭。為確保計時器到期時會傳送事件，請務必先呼叫這個方法，再呼叫 Start。

如果指定的 id 無效，這項呼叫會傳回 INVALID_ARGS。如果指定的 id 不支援這個方法，則這項呼叫會傳回 NOT_SUPPORTED。如果驅動程式庫發生內部錯誤，這項呼叫會傳回 INTERNAL_ERROR。

已淘汰：HEAD

要求

名稱類型
id uint64
event handle<event>

回應

名稱類型
payload Device_SetEvent_Result

開始

啟動計時器 id，在 ticks後到期。

如果 ticks 為 0，計時器會在 0 個刻度後 (立即) 到期。 如果計時器 id 已啟動，系統會取消先前的 Start，並重新啟動計時器。請注意，這可能會與先前計時器的到期時間發生競爭，例如通知程序可能已經啟動，而新的 Start 呼叫將無法停止已在進行中的通知。如果指定的 id 無效，這項呼叫會傳回 INVALID_ARGS。如果 GetProperties 提供的 resolutions 不支援指定的 resolution，則這項呼叫會傳回 INVALID_ARGS。如果指定的 ticks 超出 GetProperties 提供的計時器支援範圍，則此呼叫會傳回 INVALID_ARGS。如果驅動程式庫發生內部錯誤，這項呼叫會傳回 INTERNAL_ERROR。

已淘汰：HEAD

要求

名稱類型
id uint64
resolution Resolution
ticks uint64

回應

名稱類型
payload Device_Start_Result

StartAndWait

啟動計時器 id，在 ticks 後到期，並等待計時器到期，支援透過 Power Framework 防止暫停。

使用 ZX_EVENT_SIGNALED 信號設定計時器後，驅動程式會發出 setup_event 事件信號。這樣一來，用戶端就能知道可以安全地允許系統暫停。用戶端必須負責清除這項事件。

在計時器觸發前，驅動程式不會回應這個呼叫 (停止)。在計時器上呼叫 Stop 會取消這項呼叫，並傳回 CANCELED。請注意，這可能會與計時器到期時間發生競爭。

支援這項呼叫的驅動程式必須能夠取得電源元件的租約，防止系統暫停。這項租約會透過 keep_alive LeaseToken 管道欄位傳回用戶端。keep_alive 關閉時，系統會捨棄防止系統暫停的驅動程式庫租約。因此，為確保系統不會遭到 Power Framework 暫停，用戶端必須在系統不需要暫停時保留這個 keep_alive 權杖，或用戶端必須從 Power Framework 取得自己的租約，以防止在捨棄 keep_alive 之前暫停。

如果指定的 id 無效，這項呼叫會傳回 INVALID_ARGS。如果指定的 id 不支援這個方法，則這項呼叫會傳回 NOT_SUPPORTED。如果驅動程式庫沒有可提供給用戶端的 keep_alive 權杖，這項呼叫會傳回 BAD_STATE。如果驅動程式庫發生內部錯誤，這項呼叫會傳回 INTERNAL_ERROR。

要求

名稱類型
id uint64
resolution Resolution
ticks uint64
setup_event handle<event>

回應

名稱類型
payload Device_StartAndWait_Result

StartAndWait2

啟動計時器 id，並等待計時器在 ticks 個刻度後到期。

在計時器觸發前，驅動程式不會回應這個呼叫 (停止)。在計時器上呼叫 Stop 會取消這項呼叫，並傳回 CANCELED。請注意，這可能會與計時器到期時間發生競爭。

這個方法會在使用強制傳入的 setup_keep_alive LeaseToken 設定計時器時，讓系統保持喚醒狀態 (防止暫停)。計時器到期時，這個方法會傳回第二個 expiration_keep_alive LeaseToken，防止在到期時暫停。這些保持運作喚醒租約權杖是由 Power Framework 的系統活動管理工具提供。支援這項呼叫的驅動程式必須能從系統活動調節器取得 expiration_keep_alive。

expiration_keep_alive 關閉時，系統會捨棄這個驅動程式庫建立的喚醒租約，避免系統在計時器到期時暫停。因此，為確保系統不會遭到 Power Framework 暫停，用戶端必須在系統需要保持喚醒狀態時保留此 expiration_keep_alive，或在捨棄 expiration_keep_alive 之前，從 Power Framework 取得自己的喚醒租約，以防止暫停。

錯誤：

  • INVALID_ARGS：指定的 id 無效。
  • NOT_SUPPORTED：指定 id 不支援這個方法。
  • BAD_STATE：驅動程式處於不良狀態，例如沒有可提供給用戶端的 expiration_keep_alive 權杖。
  • INTERNAL_ERROR：驅動程式發生內部錯誤。

要求

名稱類型
id uint64
resolution Resolution
ticks uint64
setup_keep_alive fuchsia.power.system/LeaseToken

回應

名稱類型
payload Device_StartAndWait2_Result

停止

停止計時器 id。

請注意，這可能會與計時器到期時間發生競爭，例如透過 SetEvent 設定的事件通知可能已經在傳送中。如果指定的 id 無效，這項呼叫會傳回 INVALID_ARGS。如果驅動程式庫發生內部錯誤，這項呼叫會傳回 INTERNAL_ERROR。

要求

名稱類型
id uint64

回應

名稱類型
payload Device_Stop_Result

STRUCTS

Device_GetProperties_Response 資源

定義於 fuchsia.hardware.hrtimer/hrtimer.fidl

欄位類型說明預設
properties Properties 無預設值

Device_GetTicksLeft_Response

定義於 fuchsia.hardware.hrtimer/hrtimer.fidl

欄位類型說明預設
ticks uint64 無預設值

Device_ReadClock_Response

定義於 fuchsia.hardware.hrtimer/hrtimer.fidl

欄位類型說明預設
ticks uint64 無預設值

Device_ReadTimer_Response

定義於 fuchsia.hardware.hrtimer/hrtimer.fidl

欄位類型說明預設
ticks uint64 無預設值

Device_SetEvent_Response

定義於 fuchsia.hardware.hrtimer/hrtimer.fidl

<EMPTY>

Device_StartAndWait2_Response resource

定義於 fuchsia.hardware.hrtimer/hrtimer.fidl

欄位類型說明預設
expiration_keep_alive fuchsia.power.system/LeaseToken 無預設值

Device_StartAndWait_Response resource

定義於 fuchsia.hardware.hrtimer/hrtimer.fidl

欄位類型說明預設
keep_alive fuchsia.power.system/LeaseToken 無預設值

Device_Start_Response

定義於 fuchsia.hardware.hrtimer/hrtimer.fidl

<EMPTY>

Device_Stop_Response

定義於 fuchsia.hardware.hrtimer/hrtimer.fidl

<EMPTY>

列舉

DriverError 彈性

類型：uint32

定義於 fuchsia.hardware.hrtimer/hrtimer.fidl

這個驅動程式庫可能傳回的錯誤。

名稱值說明
1

驅動程式在執行作業時發生不明錯誤。
2

系統未導入、不支援或未啟用這項作業。
3

引數無效。
4

作業失敗，因為驅動程式庫目前狀態不允許，或未滿足作業的前提條件。
5

已取消進行中的作業。

PowerUpState 彈性

類型：uint32

定義於 fuchsia.hardware.hrtimer/hrtimer.fidl

指出計時器硬體在啟動時的開機狀態。

名稱值說明
0

開機狀態不明或硬體未回報。
1

硬體正常啟動 (備用電源維持運作)。
2

電池耗盡或完全斷電後，硬體重新啟動 (備份網域暫存器已重設)。

TABLES

資源資源

定義於 fuchsia.hardware.hrtimer/hrtimer.fidl

驅動程式屬性。

序數欄位類型說明
timers_properties vector<TimerProperties>:64

擷取支援的計時器屬性。

(選用)
driver_node_token handle<event>

司機的節點權杖。

如果驅動程式庫提供這個值，呼叫端就能使用這個值要求驅動程式庫其他資訊。

選用。司機可能沒有代幣可提供。

TimerProperties

定義於 fuchsia.hardware.hrtimer/hrtimer.fidl

由驅動程式庫抽象化的特定計時器屬性。

序數欄位類型說明
id uint64

這個計時器的專屬 ID。

id 對於特定計時器而言是穩定的，也就是說，它不會在不同的用戶端或來自同一用戶端的不同連線之間變更。

必填。
supported_resolutions vector<Resolution>:64

擷取這個計時器支援的解析度。

必填。
max_ticks uint64

範圍 (以刻度為單位)。

這是計時器啟動時，可設定的最長時間 (以刻度為單位)。實際時間 (例如奈秒) 的最大範圍取決於所用解析度。

注意：此處回報的值不一定要與硬體實際支援的值相同。驅動程式「可以」支援回報的 max_ticks，其值大於可放入裝置硬體暫存器的最大刻度值。驅動程式支援較大的 max_ticks 值，方法是以硬體支援的最大間隔多次重新設定硬體計數器，並在每次重新設定後產生中斷。如果想盡可能減少重新程式設計 (和中斷) 的次數，例如在感知電源的情境中使用 hrtimer 時，請從 [supported_resolutions] 中選取最粗略的可用解析度。這樣一來，就能確保在不重新編程的情況下，盡可能延長實際時間。

必填。
supports_event bool

如果為 true，則支援 SetEvent 方法；如果為 false 或不存在，則不支援。

(選用)

已淘汰：HEAD
supports_wait bool

如果為 true，則支援 StartAndWait 和 StartAndWait2 方法；如果為 false 或不存在，則不支援這些方法。

(選用)
supports_read bool

如果為 true，則支援 TimerRead 和 ClockRead 方法；如果為 false 或不存在，則不支援這些方法。

(選用)
power_up_state PowerUpState

指出計時器硬體在啟動時的開機狀態。

如果沒有，則開機狀態為 PowerUpState.UNKNOWN。

(選用)

UNIONS

Device_GetProperties_Result strict resource

定義於 fuchsia.hardware.hrtimer/hrtimer.fidl

序數Variant類型說明
response Device_GetProperties_Response
framework_err internal

Device_GetTicksLeft_Result strict

定義於 fuchsia.hardware.hrtimer/hrtimer.fidl

序數Variant類型說明
response Device_GetTicksLeft_Response
err DriverError
framework_err internal

Device_ReadClock_Result strict

定義於 fuchsia.hardware.hrtimer/hrtimer.fidl

序數Variant類型說明
response Device_ReadClock_Response
err DriverError
framework_err internal

Device_ReadTimer_Result strict

定義於 fuchsia.hardware.hrtimer/hrtimer.fidl

序數Variant類型說明
response Device_ReadTimer_Response
err DriverError
framework_err internal

Device_SetEvent_Result strict

定義於 fuchsia.hardware.hrtimer/hrtimer.fidl

序數Variant類型說明
response Device_SetEvent_Response
err DriverError
framework_err internal

Device_StartAndWait2_Result strict resource

定義於 fuchsia.hardware.hrtimer/hrtimer.fidl

序數Variant類型說明
response Device_StartAndWait2_Response
err DriverError
framework_err internal

Device_StartAndWait_Result strict resource

定義於 fuchsia.hardware.hrtimer/hrtimer.fidl

序數Variant類型說明
response Device_StartAndWait_Response
err DriverError
framework_err internal

Device_Start_Result strict

定義於 fuchsia.hardware.hrtimer/hrtimer.fidl

序數Variant類型說明
response Device_Start_Response
err DriverError
framework_err internal

Device_Stop_Result strict

定義於 fuchsia.hardware.hrtimer/hrtimer.fidl

序數Variant類型說明
response Device_Stop_Response
err DriverError
framework_err internal

解析度彈性

定義於 fuchsia.hardware.hrtimer/hrtimer.fidl

計時器一個刻度的時間長度。

序數Variant類型說明
duration zx/Duration

為一個刻度指定的解析度。

常數

名稱值類型說明
MAX_COUNT_RESOLUTIONS 64 uint32

指定計時器支援的解析度數量上限，可任意設定。
MAX_COUNT_TIMERS 64 uint32

這項通訊協定支援的計時器數量上限，可任意設定。

服務

服務

定義於 fuchsia.hardware.hrtimer/hrtimer.fidl

名稱類型傳輸
device fuchsia.hardware.hrtimer/Device 版本