fuchsia.hardware.hrtimer

Added: HEAD

协议

设备

在 fuchsia.hardware.hrtimer/hrtimer.fidl 中定义

提供高分辨率计时器支持的驱动程序。 此 API 适用于由独立于 CPU 的硬件提供的计时器。例如，此驱动程序可以抽象化由 SoC 提供的硬件。

GetProperties

获取驱动程序属性。

请求

<EMPTY>

响应

名称类型
payload Device_GetProperties_Result

GetTicksLeft

获取计时器 id 距离到期还剩的当前时间（以 tick 为单位）。

如果指定的 id 无效，则此调用将返回 INVALID_ARGS。

请求

名称类型
id uint64

响应

名称类型
payload Device_GetTicksLeft_Result

ReadClock

读取当前计时器的时钟值。

返回的 tick 采用相对于给定分辨率的时间单位。 使用 GetProperties() 确定可用的分辨率。

错误： BAD_STATE：当前没有时钟在运行。 INVALID_ARGS：id 或 resolution 是无效或不受支持的值。 NOT_SUPPORTED：如果 supports_read 为 false，或者该方法未以其他方式实现。 INTERNAL_ERROR：内部运行时错误。

请求

名称类型
id uint64
resolution Resolution

响应

名称类型
payload Device_ReadClock_Result

ReadTimer

读取当前计时器的设置值或超时值。

返回的 tick 采用相对于给定分辨率的时间单位。 使用 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 个 tick（立即）后到期。 如果计时器 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 后到期，并等待计时器到期，同时支持通过电源框架防止暂停。

使用 ZX_EVENT_SIGNALED 信号设置计时器后，驱动程序将发出 setup_event 事件信号。这样，客户端便可以知道允许系统暂停是安全的。客户端负责清除此事件。

在计时器触发之前，驱动程序不会响应此调用（挂起）。 对计时器调用 Stop 会中止此调用并返回 CANCELED。请注意，这可能会与计时器到期发生竞态。

支持此调用的驱动程序必须能够获取电源元件上的租约，以防止系统挂起。此租约通过 keep_alive LeaseToken 渠道字段返回给客户端。当 keep_alive 关闭时，阻止系统挂起的驱动程序租约将被丢弃。因此，为确保系统不会被电源框架挂起，客户端必须在系统需要不挂起的时间内保留此 keep_alive 令牌，或者客户端必须从电源框架获取自己的租约，以防止在丢弃 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 个 tick 后到期。

在计时器触发之前，驱动程序不会响应此调用（挂起）。 对计时器调用 Stop 会中止此调用并返回 CANCELED。请注意，这可能会与计时器到期发生竞态。

此方法会在使用强制传入的 setup_keep_alive LeaseToken 设置计时器时使系统保持唤醒状态（防止挂起）。当计时器到期时，此方法会返回第二个 expiration_keep_alive LeaseToken，以防止在到期时暂停。这些保持唤醒状态的唤醒租用令牌由电源框架的系统活动调节器提供。支持此调用的驱动程序必须能够从系统活动调节器获取 expiration_keep_alive。

当 expiration_keep_alive 关闭时，此驱动程序创建的唤醒租约（用于防止系统在计时器到期时挂起）将被丢弃。因此，为确保系统不会被电源框架挂起，客户端必须在系统需要保持唤醒状态期间一直保留此 expiration_keep_alive，或者必须在丢弃 expiration_keep_alive 之前从电源框架获取自己的唤醒租约，以防止挂起。

错误：

  • 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 资源

在 fuchsia.hardware.hrtimer/hrtimer.fidl 中定义

字段类型说明默认
expiration_keep_alive fuchsia.power.system/LeaseToken 无默认应用

Device_StartAndWait_Response 资源

在 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 flexible

类型：uint32

在 fuchsia.hardware.hrtimer/hrtimer.fidl 中定义

此驱动程序可能返回的错误。

名称值说明
1

驱动程序在执行操作时遇到了未指明的错误。
2

该操作未实现、不受支持或未启用。
3

参数无效。
4

操作失败，因为驱动程序的当前状态不允许执行该操作，或者未满足该操作的前提条件。
5

正在进行的操作已取消。

PowerUpState flexible

类型：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 对于给定的计时器是稳定的，即它不会在不同的客户端或来自同一客户端的不同连接之间发生变化。

必填。
supported_resolutions vector<Resolution>:64

检索此计时器支持的分辨率。

必填。
max_ticks uint64

范围（以刻度为单位）。

这是启动计时器时可以设置的最长时间（以 tick 为单位）。实际时间（例如纳秒）的最大范围取决于所用的分辨率。

注意：此处报告的值无需与硬件实际支持的值相同。驱动程序可以提供对所报告 max_ticks 的支持，该值大于可放入设备硬件寄存器的最大 tick 值。驱动程序通过使用其支持的最大间隔多次重新编程硬件计数器来支持更大的 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 中定义

序数变体类型说明
response Device_GetProperties_Response
framework_err internal

Device_GetTicksLeft_Result strict

在 fuchsia.hardware.hrtimer/hrtimer.fidl 中定义

序数变体类型说明
response Device_GetTicksLeft_Response
err DriverError
framework_err internal

Device_ReadClock_Result strict

在 fuchsia.hardware.hrtimer/hrtimer.fidl 中定义

序数变体类型说明
response Device_ReadClock_Response
err DriverError
framework_err internal

Device_ReadTimer_Result strict

在 fuchsia.hardware.hrtimer/hrtimer.fidl 中定义

序数变体类型说明
response Device_ReadTimer_Response
err DriverError
framework_err internal

Device_SetEvent_Result strict

在 fuchsia.hardware.hrtimer/hrtimer.fidl 中定义

序数变体类型说明
response Device_SetEvent_Response
err DriverError
framework_err internal

Device_StartAndWait2_Result strict resource

在 fuchsia.hardware.hrtimer/hrtimer.fidl 中定义

序数变体类型说明
response Device_StartAndWait2_Response
err DriverError
framework_err internal

Device_StartAndWait_Result strict resource

在 fuchsia.hardware.hrtimer/hrtimer.fidl 中定义

序数变体类型说明
response Device_StartAndWait_Response
err DriverError
framework_err internal

Device_Start_Result strict

在 fuchsia.hardware.hrtimer/hrtimer.fidl 中定义

序数变体类型说明
response Device_Start_Response
err DriverError
framework_err internal

Device_Stop_Result strict

在 fuchsia.hardware.hrtimer/hrtimer.fidl 中定义

序数变体类型说明
response Device_Stop_Response
err DriverError
framework_err internal

分辨率灵活

在 fuchsia.hardware.hrtimer/hrtimer.fidl 中定义

计时器一个刻度的时间。

序数变体类型说明
duration zx/Duration

为单个刻度指定的分辨率。

常量

名称值类型说明
MAX_COUNT_RESOLUTIONS 64 uint32

给定计时器支持的分辨率数量上限，任意。
MAX_COUNT_TIMERS 64 uint32

此协议支持的定时器数量上限，任意。

服务

服务

在 fuchsia.hardware.hrtimer/hrtimer.fidl 中定义

名称类型传输
设备 fuchsia.hardware.hrtimer/Device 渠道