fuchsia.power.system

系统活动调节器 (SAG) 是电源框架的一个子系统，用于管理硬件平台的执行和暂停状态。它还允许观察器监视平台的暂停/恢复转换。

其他组件可以使用 fuchsia.power.broker/ElementControl 创建对 SAG 电源元素的依赖项，以影响 SAG 的行为，包括防止系统挂起。

SAG 创建和管理的电源元素如下：

内部依赖关系图

               +--------------------+                  +---------------------------------+
               | **ExecutionState** |                  |     **ApplicationActivity**     |
               +--------------------+                  +---------------------------------+
               |       ACTIVE       |<-----------------|             ACTIVE              |
               +--------------------+                  +---------------------------------+
+--------------|     SUSPENDING     |                  |            INACTIVE             |
|              |                    |                  +---------------------------------+
|              +--------------------+
|              |      INACTIVE      |
|              +--------------------+
|
|    +---------------------------------+
|    |             **CPU**             |
|    +---------------------------------+
+--->|             ACTIVE              |
     +---------------------------------+
     |            INACTIVE             |
     +---------------------------------+

用法

为防止系统挂起，组件可以使用 ApplicationActivity 中的 assertive_dependency_token 创建断言依赖项。如果依赖项导致 ApplicationActivity 的电源级别提升到 fuchsia.power.system/ApplicationActivityPowerLevel.ACTIVE，SAG 将不会触发系统挂起，直到其电源级别降至 INACTIVE。

或者，组件可以调用 fuchsia.power.system/ActivityGovernor.AcquireWakeLease。

添加：26

协议

ActivityGovernor

在 fuchsia.power.system/system.fidl 中定义

一项用于公开由系统活动调节器 (SAG) 管理的事件和电源元素的服务。

SAG 负责管理硬件平台的执行状态。硬件平台由在设备上执行代码所需的组件组成。这通常包括 CPU、内存、操作系统以及这些组件正常运行所需的其他组件（时钟树、电源域等）。

添加：26

AcquireUnmonitoredWakeLease

创建不受监控的租约，以阻止硬件平台暂停。

只要存在有效的 LeaseToken，硬件平台就不会暂停。

这适用于预计会长期持有的租赁。 与普通唤醒租约不同，服务器不会监控不受监控的唤醒租约的持续时间，并且如果其超出预配置的提醒阈值，也不会提交崩溃报告。

Added: HEAD

请求

名称类型
name string:64

响应

名称类型
payload ActivityGovernor_AcquireUnmonitoredWakeLease_Result

AcquireWakeLease

创建阻止硬件平台暂停的租约。

只要存在有效的 LeaseToken，硬件平台就不会暂停。

添加：26

请求

名称类型
name string:64

响应

名称类型
payload ActivityGovernor_AcquireWakeLease_Result

AcquireWakeLease2

创建阻止硬件平台暂停的租约，并可选择将其与前置租约 (previous_client_token) 相关联。

警告：只有在客户端收到对此调用的响应后，才能认为暂停已被阻止，除非提供了 previous_client_token 并且正在主动阻止暂停。如果提供了 previous_client_token，SAG 会保留 previous_client_token 句柄，直到注册新的唤醒租约，以防止暂停。

硬件平台将保持恢复状态，直到 server_token 观察到 PEER_CLOSED，这表示 LeaseToken 客户端的所有句柄都已关闭。

Added: HEAD

请求

名称类型
payload ActivityGovernorAcquireWakeLease2Request

响应

名称类型
payload ActivityGovernor_AcquireWakeLease2_Result

AcquireWakeLeaseWithToken

创建阻止硬件平台暂停的租用。 警告：只有在客户端收到对此调用的响应后，才能认为暂停操作已被阻止。例如，这意味着只有在收到无错误响应之后，才应确认中断或丢弃其他唤醒租约。

硬件平台将保持恢复状态，直到 server_token 观察到 PEER_CLOSED，这表示 LeaseToken 客户端的所有句柄都已关闭。

Added: HEAD

请求

名称类型
name string:64
server_token LeaseToken

响应

名称类型
payload ActivityGovernor_AcquireWakeLeaseWithToken_Result

GetPowerElements

获取活动调节器拥有的电源元素。

如果服务器在向电源代理注册电源元素时出错，或者在为电源元素创建令牌时出错，则服务器将关闭与 ActivityGovernor 的通道，并且不会返回任何响应。

Added: HEAD

请求

<EMPTY>

响应

名称类型
payload ActivityGovernor_GetPowerElements_Result

RegisterSuspendBlocker

注册暂停屏蔽器。

注册成功后，系统会返回一个唤醒租约令牌。此令牌存在时，可防止硬件平台暂停。客户端应在持有此令牌时对给定 suspend_blocker 服务器执行任何初始化。此外，这意味着 suspend_blocker 将收到的第一个调用是 BeforeSuspend。

如需取消注册，请关闭 SuspendBlocker 通道。

如果缺少表的任何必填字段，系统会返回错误 RegisterSuspendBlockerError.INVALID_ARGS。

如果在注册 suspend_blocker 期间发生错误，则会将其丢弃，并关闭通道。

新增：27

请求

名称类型
payload ActivityGovernorRegisterSuspendBlockerRequest

响应

名称类型
payload ActivityGovernor_RegisterSuspendBlocker_Result

TakeApplicationActivityLease

创建租约，以阻止系统降至应用 activity“活跃”状态以下。具体而言，这会阻止硬件平台暂停。

在 SuspendBlocker.BeforeSuspend 期间调用此方法不安全。

如果在为活动租约创建令牌时发生错误，则服务器将关闭指向 ActivityGovernor 的通道，并且不会返回任何响应。

Added: HEAD

请求

名称类型
name string:64

响应

名称类型
payload ActivityGovernor_TakeApplicationActivityLease_Result

BootControl

在 fuchsia.power.system/system.fidl 中定义

处理有关系统启动状态的通知的服务。

SetBootComplete

通知 SAG 系统已启动。在每次启动时至少调用一次此方法之前，SAG 不会暂停硬件平台。

请求

<EMPTY>

响应

名称类型
payload BootControl_SetBootComplete_Result

CpuElementManager

在 fuchsia.power.system/system.fidl 中定义

一项提供对 CPU 相关电源元素访问权限的服务。

Added: HEAD

AddExecutionStateDependency

添加从执行状态电源元素到由 dependency_token 标识的目标电源元素（位于 power_level）的依赖项。

创建执行状态电源元素后，未来的调用将返回 fuchsia.power.system/AddExecutionStateDependencyError.BAD_STATE，并且不会对执行状态依赖项进行任何更改。

如果请求中缺少任何必需条目，服务器将返回 fuchsia.power.system/AddExecutionStateDependencyError.INVALID_ARGS。

请求

名称类型
payload CpuElementManagerAddExecutionStateDependencyRequest

响应

名称类型
payload CpuElementManager_AddExecutionStateDependency_Result

GetCpuDependencyToken

获取 CPU 电源元素的断言依赖项令牌。

请求

<EMPTY>

响应

名称类型
payload CpuElementManager_GetCpuDependencyToken_Result

ExecutionStateManager

在 fuchsia.power.system/system.fidl 中定义

一项用于公开执行状态管理功能的服务。

Added: HEAD

AddApplicationActivityDependency

在 power_level 处，添加从应用 activity 电源元素到由 dependency_token 标识的目标电源元素的依赖项。请注意以下客户端条件：

  • 如果 SAG 未完全初始化，则调用会阻塞，直到初始化完成。
  • 根据 fuchsia.power.broker/ElementControl.AddDependency 的要求，该调用可能会阻塞，在撰写本文时，该调用可能会对关联的电源元素调用 fuchsia.power.ElementControl.SetLevel。

请求

名称类型
payload ExecutionStateManagerAddApplicationActivityDependencyRequest

响应

名称类型
payload ExecutionStateManager_AddApplicationActivityDependency_Result

GetExecutionStateDependencyToken

获取执行状态电源元素的依赖项令牌。如果 SAG 未完全初始化，此操作将阻塞。

请求

<EMPTY>

响应

名称类型
payload ExecutionStateManager_GetExecutionStateDependencyToken_Result

SuspendBlocker

在 fuchsia.power.system/system.fidl 中定义

一个实体，用于阻止挂起，直到它处理完硬件平台挂起和恢复之间的转换。

新增：27

AfterResume

在系统 activity 调节器知道硬件平台已恢复后调用。

在此调用期间，ExecutionState 处于 INACTIVE 级别，但 ExecutionStateLevel::SUSPENDING 的所有依赖项都保证得到满足。

因此，SuspendBlocker 不得调用 ActivityGovernor.TakeApplicationActivityLease，也不得执行任何其他操作来阻止执行状态达到 INACTIVE 以外的级别。否则会导致死锁。（不过，AcquireWakeLease 不会以这种方式阻塞，可以安全调用。）

请求

<EMPTY>

响应

名称类型
payload SuspendBlocker_AfterResume_Result

BeforeSuspend

在系统 activity 调节器开始执行暂停硬件平台的操作后调用。

服务器在执行完为暂停做准备所需的操作（如有）后，应做出响应。在调用期间，ExecutionStateLevel::SUSPENDING 的所有依赖项都保证得到满足，并且可能会在服务器回复后撤消。

暂停硬件平台的操作可能因硬件平台和产品配置而异。客户端和服务器至少必须假定常规代码执行会继续，直到客户端收到对此调用的回复。如果 SuspendBlocker 想要抢占挂起操作，则必须在回复此调用之前调用 ActivityGovernor.AcquireWakeLease。

在调用期间，ExecutionState 将处于 SUSPENDING 级别。因此，SuspendBlocker 不得调用 ActivityGovernor.TakeApplicationActivityLease，也不得执行任何其他操作来阻止执行状态达到 INACTIVE 以外的级别。否则会导致死锁。（不过，AcquireWakeLease 不会以这种方式阻塞，可以安全调用。）

请求

<EMPTY>

响应

名称类型
payload SuspendBlocker_BeforeSuspend_Result

STRUCTS

ActivityGovernor_AcquireUnmonitoredWakeLease_Response 资源

在 fuchsia.power.system/system.fidl 中定义

字段类型说明默认
token LeaseToken

用于阻止硬件平台暂停的令牌。

 无默认应用

ActivityGovernor_AcquireWakeLease2_Response

在 fuchsia.power.system/system.fidl 中定义

<EMPTY>

ActivityGovernor_AcquireWakeLeaseWithToken_Response

在 fuchsia.power.system/system.fidl 中定义

<EMPTY>

ActivityGovernor_AcquireWakeLease_Response 资源

在 fuchsia.power.system/system.fidl 中定义

字段类型说明默认
token LeaseToken

用于阻止硬件平台暂停的令牌。

 无默认应用

ActivityGovernor_RegisterSuspendBlocker_Response 资源

在 fuchsia.power.system/system.fidl 中定义

字段类型说明默认
token LeaseToken

用于阻止硬件平台暂停的令牌。

 无默认应用

ActivityGovernor_TakeApplicationActivityLease_Response 资源

在 fuchsia.power.system/system.fidl 中定义

字段类型说明默认
token LeaseToken

阻止应用 activity 降至“活跃”状态以下的令牌。

 无默认应用

BootControl_SetBootComplete_Response

在 fuchsia.power.system/system.fidl 中定义

<EMPTY>

CpuElementManager_AddExecutionStateDependency_Response

在 fuchsia.power.system/system.fidl 中定义

<EMPTY>

ExecutionStateManager_AddApplicationActivityDependency_Response

在 fuchsia.power.system/system.fidl 中定义

<EMPTY>

SuspendBlocker_AfterResume_Response

在 fuchsia.power.system/system.fidl 中定义

<EMPTY>

SuspendBlocker_BeforeSuspend_Response

在 fuchsia.power.system/system.fidl 中定义

<EMPTY>

枚举

AcquireWakeLeaseError flexible

类型：uint32

在 fuchsia.power.system/system.fidl 中定义

ActivityGovernor/AcquireWakeLease 和 AcquireWakeLease2 返回的错误。

添加：26

名称值说明
1

服务在尝试发放唤醒租约时出错。
2

唤醒租约的名称为空或无效。
3

未提供必需的 server_token 参数。

Added: HEAD
4

previous_client_token 实参无效（例如，它引用了与 server_token 相同的令牌对）。

Added: HEAD

AddApplicationActivityDependencyError flexible

类型：uint32

在 fuchsia.power.system/system.fidl 中定义

fuchsia.power.system/ActivityGovernor 中来自 AddApplicationActivityDependency 的响应的错误代码。

Added: HEAD

名称值说明
1

依赖项已存在。
2

未提供必需的参数，或提供的参数无效。
3

服务在尝试添加依赖项时遇到错误。

AddExecutionStateDependencyError flexible

类型：uint32

在 fuchsia.power.system/system.fidl 中定义

fuchsia.power.system/CpuElementManager 中 AddExecutionStateDependency 响应的错误代码。

Added: HEAD

名称值说明
1

未提供必需的参数，或提供的参数无效。
2

服务器未处于可处理请求的状态。

ApplicationActivityLevel flexible

类型：uint8

在 fuchsia.power.system/system.fidl 中定义

应用活动功耗级别

需要阻止系统挂起的元素应采用对 ApplicationActivityLevel::ACTIVE 的断言依赖项。当这些组件执行工作时，它们应请求租约以确保系统保持活跃状态，并在完成后释放租约。

Added: HEAD

名称值说明
0
1

CPU 级别 灵活

类型：uint8

在 fuchsia.power.system/system.fidl 中定义

CPU 功率级别

元素应主动依赖于 CpuLevel::ACTIVE，以确保元素在 CPU 挂起之前挂起。

Added: HEAD

名称值说明
0
1

ExecutionStateLevel flexible

类型：uint8

在 fuchsia.power.system/system.fidl 中定义

执行状态功率级别

Added: HEAD

名称值说明
0
1
2

RegisterSuspendBlockerError 灵活

类型：uint32

在 fuchsia.power.system/system.fidl 中定义

fuchsia.power.system/ActivityGovernor 中来自 RegisterSuspendBlocker 的响应的错误代码。

新增：27

名称值说明
1

服务在尝试发放唤醒租约时出错。
2

未提供必需的参数，或提供的参数无效。

TABLES

ActivityGovernorAcquireWakeLease2Request 资源

在 fuchsia.power.system/system.fidl 中定义

序数字段类型说明
name string:64

租赁的名称。

必需。名称不能为空，但不必具有全局唯一性。
server_token LeaseToken

阻止硬件平台暂停的令牌的服务器端。

必需。调用方应向与此 server_token 对等的 LeaseToken 的客户端提供句柄。
previous_client_token LeaseToken

正在交换的租约的可选前置客户端令牌。

如果存在，SAG 会保留此句柄，直到新的唤醒租约在 SAG 的内部跟踪结构中注册，并在 Inspect 中记录新的唤醒租约与前置租约 (replaces_lease_id) 相关联。如果其客户端令牌的其他句柄保持打开状态，则提供 previous_client_token 不会销毁之前的租约。
unmonitored bool

可选标志，用于指示唤醒租约是否不受监控。

如果存在且为 true，则行为类似于 AcquireUnmonitoredWakeLease：SAG 不会监控此租约的时长，并且如果此租约的时长超过预配置的提醒阈值，则不会提交崩溃报告。如果不存在，则默认为 false。

ActivityGovernorRegisterSuspendBlockerRequest 资源

在 fuchsia.power.system/system.fidl 中定义

序数字段类型说明
suspend_blocker client_end:SuspendBlocker

SuspendBlocker 服务的客户端。

必填。
name string:64

暂停阻止器的名称。

必填。

名称不能为空，但不必具有全局唯一性。

ApplicationActivity 资源

在 fuchsia.power.system/system.fidl 中定义

持有应用 activity 电源元素的令牌。

fuchsia.power.system/ApplicationActivityLevel 用于定义此电源元素支持的电源级别。

Added: HEAD

序数字段类型说明
assertive_dependency_token fuchsia.power.broker/DependencyToken

CPU 资源

在 fuchsia.power.system/system.fidl 中定义

保存 CPU 电源元素的令牌。

fuchsia.power.system/CpuLevel 定义了此电源元素支持的电源级别。

Added: HEAD

序数字段类型说明
assertive_dependency_token fuchsia.power.broker/DependencyToken

CpuElementManagerAddExecutionStateDependencyRequest 资源

在 fuchsia.power.system/system.fidl 中定义

序数字段类型说明
dependency_token fuchsia.power.broker/DependencyToken

表示依赖项的目标电源元素的断言依赖项令牌。 必填。
power_level fuchsia.power.broker/PowerLevel

目标电源元素的功率级别。 必填。

ExecutionState 资源

在 fuchsia.power.system/system.fidl 中定义

保存执行状态电源元素的依赖项令牌。

Added: HEAD

序数字段类型说明
dependency_token fuchsia.power.broker/DependencyToken

ExecutionStateManagerAddApplicationActivityDependencyRequest 资源

在 fuchsia.power.system/system.fidl 中定义

序数字段类型说明
dependency_token fuchsia.power.broker/DependencyToken

表示此依赖项的目标电源元素的依赖项令牌。 必填。
power_level fuchsia.power.broker/PowerLevel

目标电源元素的功率级别。 必填。

PowerElements 资源

在 fuchsia.power.system/system.fidl 中定义

由 activity 调节器管理的一组电源元素。

Added: HEAD

序数字段类型说明
application_activity ApplicationActivity

UNIONS

ActivityGovernor_AcquireUnmonitoredWakeLease_Result strict resource

在 fuchsia.power.system/system.fidl 中定义

序数变体类型说明
response ActivityGovernor_AcquireUnmonitoredWakeLease_Response
err AcquireWakeLeaseError
framework_err internal

ActivityGovernor_AcquireWakeLease2_Result strict

在 fuchsia.power.system/system.fidl 中定义

序数变体类型说明
response ActivityGovernor_AcquireWakeLease2_Response
err AcquireWakeLeaseError
framework_err internal

ActivityGovernor_AcquireWakeLeaseWithToken_Result strict

在 fuchsia.power.system/system.fidl 中定义

序数变体类型说明
response ActivityGovernor_AcquireWakeLeaseWithToken_Response
err AcquireWakeLeaseError
framework_err internal

ActivityGovernor_AcquireWakeLease_Result strict resource

在 fuchsia.power.system/system.fidl 中定义

序数变体类型说明
response ActivityGovernor_AcquireWakeLease_Response
err AcquireWakeLeaseError
framework_err internal

ActivityGovernor_GetPowerElements_Result strict resource

在 fuchsia.power.system/system.fidl 中定义

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

ActivityGovernor_RegisterSuspendBlocker_Result strict resource

在 fuchsia.power.system/system.fidl 中定义

序数变体类型说明
response ActivityGovernor_RegisterSuspendBlocker_Response
err RegisterSuspendBlockerError
framework_err internal

ActivityGovernor_TakeApplicationActivityLease_Result strict resource

在 fuchsia.power.system/system.fidl 中定义

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

BootControl_SetBootComplete_Result strict

在 fuchsia.power.system/system.fidl 中定义

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

CpuElementManager_AddExecutionStateDependency_Result strict

在 fuchsia.power.system/system.fidl 中定义

序数变体类型说明
response CpuElementManager_AddExecutionStateDependency_Response
err AddExecutionStateDependencyError
framework_err internal

CpuElementManager_GetCpuDependencyToken_Result strict resource

在 fuchsia.power.system/system.fidl 中定义

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

ExecutionStateManager_AddApplicationActivityDependency_Result strict

在 fuchsia.power.system/system.fidl 中定义

序数变体类型说明
response ExecutionStateManager_AddApplicationActivityDependency_Response
err AddApplicationActivityDependencyError
framework_err internal

ExecutionStateManager_GetExecutionStateDependencyToken_Result strict resource

在 fuchsia.power.system/system.fidl 中定义

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

SuspendBlocker_AfterResume_Result strict

在 fuchsia.power.system/system.fidl 中定义

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

SuspendBlocker_BeforeSuspend_Result strict

在 fuchsia.power.system/system.fidl 中定义

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

常量

名称值类型说明
MAX_ELEMENT_NAME_LEN 64 uint8
添加：26

别名

名称值说明
LeaseToken zx/Handle
添加：26