fuchsia.power.broker

Added: HEAD

协议

ElementControl

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

提供对之前通过 Topology.AddElement 添加的元素的元素级访问权限。

AddDependency

向现有元素添加新的依赖项。 如果任何开放租约会纳入此依赖项，则所需元素和任何传递所需元素都必须完成所有必要的转换（通过 ElementRunner.SetLevel 调用），然后此方法才会返回。

请求

名称类型
payload LevelDependency

响应

名称类型
payload ElementControl_AddDependency_Result

OpenStatusChannel

注册一个新的状态通道，Power Broker 将在该通道上发送元素当前功率级别的只读更新。此方法旨在允许元素所有者通过打开和传输此通道，向客户端授予对元素当前功率级别的只读访问权限。

请求

名称类型
status_channel server_end:Status

RegisterDependencyToken

注册一个令牌，该令牌将允许持有者添加对此元素的依赖项。

请求

名称类型
token DependencyToken

响应

名称类型
payload ElementControl_RegisterDependencyToken_Result

UnregisterDependencyToken

取消注册之前通过 RegisterDependencyToken 注册的令牌。

请求

名称类型
token DependencyToken

响应

名称类型
payload ElementControl_UnregisterDependencyToken_Result

ElementInfoProvider

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

提供一个接口，用于检索由组件管理的 PowerElement 的相关信息。

GetElementPowerLevelNames

返回由组件管理的每个元素的 PowerLevels 到明文名称的映射。如果无法返回任何映射，则返回错误。

请求

<EMPTY>

响应

名称类型
payload ElementInfoProvider_GetElementPowerLevelNames_Result

GetStatusEndpoints

返回可用的状态客户端端点以及由组件管理的每个元素的稳定标识符。如果无法返回任何端点（即没有任何元素能够实现状态通道），则返回错误。

请求

<EMPTY>

响应

名称类型
payload ElementInfoProvider_GetStatusEndpoints_Result

ElementRunner

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

元素的运行器或运算符。 所有元素所有者都应实现此方法。 客户端通过 ElementSchema.element_runner 传递给 Power Broker。 Power Broker 会在初始阶段调用 SetLevel，之后每当元素的所需级别发生变化时，都会调用 SetLevel。

SetLevel

设置电源元素的级别。

服务器在进行关卡转换时会阻塞。一旦完成向新要求的级别转换，它就会返回。如果元素无法转换到新的必需级别，并且无法重试，则通道将关闭。

请求

名称类型
level PowerLevel

响应

名称类型
payload ElementRunner_SetLevel_Result

LeaseControl

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

提供对先前通过 Lessor.Lease 获取的租约可执行的操作的租约范围访问权限。关闭此控制通道会丢弃租用。 TODO(https://fxbug.dev/339474151): Switch from a protocol to an eventpair.

WatchStatus

获取租约的当前状态。 如果 last_status 为 UNKNOWN，则调用会立即返回当前状态。否则，调用将阻塞，直到当前状态与 last_status 不同。

Added: HEAD

请求

名称类型
last_status LeaseStatus

响应

名称类型
payload LeaseControl_WatchStatus_Result

出租人

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

已弃用。请改用 Topology.Lease。 提供元素级访问权限，以请求租约来提升之前通过 Topology.AddElement 添加的元素的级别。

租期

客户端发出请求，表示希望将元素提升到指定级别。当调用返回时，这并不意味着相应元素处于请求的级别，而仅表示请求的级别有效且请求正在处理中。

满足该请求会将该级别的所有直接和传递电源依赖项的级别提高到其所需级别。当 LeaseControl.WatchStatus 报告 LeaseStatus::SATISFIED 时，这意味着给定元素处于租约指定的级别。

请求无效级别会返回 LeaseError::INVALID_LEVEL。

请求

名称类型
level PowerLevel

响应

名称类型
payload Lessor_Lease_Result

状态

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

提供对元素当前 PowerLevel 的只读权限，以及监控元素功率级别变化的功能。通过在元素的 ElementControl 通道上调用 OpenStatus，可以获取此协议的新通道（并传递给需要访问元素当前功率级别的其他客户端）。

WatchPowerLevel

返回此元素的当前功率级别。对此通道的第一次调用将立即返回。后续调用将一直处于阻塞状态，直到当前功率级别发生变化。

请求

<EMPTY>

响应

名称类型
payload Status_WatchPowerLevel_Result

拓扑学

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

这是电源元件所有者用于与 Power Broker 通信的主要初始协议。电源元件所有者应通过 AddElement 将其拥有的元件添加到电源拓扑中。与 Power Broker 的所有进一步交互都是通过 AddElement 调用打开的通道完成的，这些通道的作用域限定为添加的元素。

AddElement

由电源元件所有者调用，用于注册新的电源元件并为该元件打开控制通道。

请求

名称类型
payload ElementSchema

响应

名称类型
payload Topology_AddElement_Result

租期

由客户端调用，用于直接在给定依赖项上打开租约，而无需创建和管理新元素。

请求

名称类型
payload LeaseSchema

响应

名称类型
payload Topology_Lease_Result

STRUCTS

ElementControl_AddDependency_Response

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

<EMPTY>

ElementControl_RegisterDependencyToken_Response

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

<EMPTY>

ElementControl_UnregisterDependencyToken_Response

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

<EMPTY>

ElementInfoProvider_GetElementPowerLevelNames_Response 资源

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

字段类型说明默认
level_names vector<ElementPowerLevelNames> 无默认应用

ElementInfoProvider_GetStatusEndpoints_Response 资源

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

字段类型说明默认
endpoints vector<ElementStatusEndpoint> 无默认应用

ElementRunner_SetLevel_Response

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

<EMPTY>

LeaseControl_WatchStatus_Response

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

字段类型说明默认
status LeaseStatus 无默认应用

Lessor_Lease_Response 资源

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

字段类型说明默认
lease_control client_end:LeaseControl

用于对租约执行操作的渠道。 当此通道关闭时，租约将被删除。

 无默认应用

Status_WatchPowerLevel_Response 资源

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

字段类型说明默认
current_level PowerLevel 无默认应用

Topology_AddElement_Response

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

<EMPTY>

Topology_Lease_Response

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

<EMPTY>

枚举

AddElementError flexible

类型：uint32

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

名称值说明
1
2

strict 类型的 BinaryPowerLevel

类型：uint8

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

BinaryPowerLevel 是一组众所周知的 PowerLevel，只有两种状态：OFF 和 ON。

名称值说明
0
1

ElementInfoProviderError flexible

类型：uint32

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

名称值说明
0
1

LeaseError flexible

类型：uint32

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

名称值说明
1
2
3
4

LeaseStatus flexible

类型：uint32

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

名称值说明
0
1

Power Broker 已收到租约，并且已开始向上功率转换，但尚未完成。也就是说，租用的 PowerLevel 的一个或多个依赖项尚未达到其所需级别。
2

租用的 PowerLevel 所需的所有依赖项都处于其所需的 PowerLevel，并且租用的 PowerElement 已转换为请求的级别。
3

客户端已放弃租用，Power Broker 已确认，并且已开始向下功率转换，但尚未完成。
4

租约已被移除，并且所有由此产生的电源转换均已完成。

ModifyDependencyError flexible

类型：uint32

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

名称值说明
1
2
3
4

RegisterDependencyTokenError flexible

类型：uint32

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

名称值说明
1
2

StatusError flexible

类型：uint32

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

名称值说明
1

UnregisterDependencyTokenError 灵活

类型：uint32

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

名称值说明
1
2

TABLES

ElementPowerLevelNames

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

通过明文名称将 fuchsia.power.broker/PowerLevelName 向量映射到电源元素。名称在元素之间应是唯一的，并且在同一 build 的重新启动过程中保持不变，但不同 build 之间不保证一致。

序数字段类型说明
identifier string:64
levels vector<PowerLevelName>:256

ElementSchema 资源

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

传递给 Topology.AddElement。

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

用于日志记录和调试目的的人类可读名称。
initial_current_level PowerLevel

元素的初始当前功率级别。 如需与 initial_lease_token 搭配使用，请参阅下面的说明。
valid_levels vector<PowerLevel>:256

对此元素有效的所有功率级别。此处未指定的任何级别都将被视为无效。

关卡必须按从低到高的升序排列。请注意，级别是枚举，其整数值没有固有含义。例如，理论上，二进制（关、开）可以用 (0, 1)、(1, 0)、(17, 19) 或任意两个数字的组合来表示。（但请使用上面的 BinaryPowerLevel！）
dependencies vector<LevelDependency>:128

此元素的功率级别依赖项列表。 注意：无法在此处添加依赖于此元素级别的依赖项。
lessor_channel server_end:Lessor

已移除：7：level_control_channels，请改用 element_runner（见下文）。

已弃用。请改用 Topology.Lease。 可选。如果通过，则可以通过此渠道请求此元素的租约。
element_control server_end:ElementControl

调用方提供的 ElementControl 通道，用于传递给 Power Broker。 当此通道被丢弃时，该元素将从拓扑中移除。与此元素关联的所有通道都将关闭，并且向此元素注册的所有令牌都将取消注册。
element_runner client_end:ElementRunner

Power Broker 应使用哪个客户端来设置此元素的功率级别。 应保留此 server_end，并由元素的运行程序实现 ElementRunner 协议。
initial_lease_token LeaseToken

如果设置了 initial_lease_token，则系统会立即在 initial_current_level 处获取租约，并且在达到 initial_current_level 之前的所有 SetLevel 调用都会被抑制。首次 SetLevel 调用将针对 initial_current_level。 客户端应在此处传递要由 Power Broker 保留的事件对的一半。密钥对的另一半应由客户端保留。 注意：此租约在返回时可能不会处于 SATISFIED 状态，因为这需要 ElementRunner 服务器已经收到并响应来自 Power Broker 的 SetLevel 请求。 客户端可以监听 LEASE_SIGNAL_SATISFIED，以了解租约何时SATISFIED。

ElementStatusEndpoint 资源

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

状态客户端端点和特定电源元素的明文名称。名称在元素之间应是唯一的，并且在同一 build 的重新启动过程中保持不变，但无法保证在不同 build 之间保持一致。

序数字段类型说明
identifier string:64
status client_end:Status

LeaseDependency 资源

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

序数字段类型说明
requires_token DependencyToken

必须提供通过所需元素的 ElementControl 协议的 RegisterDependencyToken 调用注册的令牌。
requires_level PowerLevel

必须提供元素级别。大多数客户端都会希望使用此字段，但为了实现向前兼容性，也可以改用 requires_level_by_preference。
requires_level_by_preference vector<PowerLevel>:256

高级选项

（可选）为了实现向前兼容性，电源代理应尝试使此依赖项满足要求的级别列表（按优先顺序递减）。列表中第一个有效的级别将成为必填级别。如果设置了此属性，系统会忽略 requires_level。

平台客户端可以使用此列表来保持与依赖项的向后兼容性，方法是提供依赖项可能已在较低 API 级别中实现的多个级别。

LeaseSchema 资源

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

传递给 Topology.Lease。

序数字段类型说明
lease_token LeaseToken

由 Power Broker 持有的事件对的一半。另一半应由客户端保留。如需了解更多使用详情，请参阅下文中的 LeaseToken。
lease_name string:64

用于日志记录和调试目的的人类可读名称。
dependencies vector<LeaseDependency>:128

此租约的依赖项列表。不得为空或缺失；没有依赖项的租约会被拒绝，并返回 LeaseError::INVALID_ARGUMENT。
should_return_pending_lease bool

（可选）默认情况下，Topology.Lease 会等待租约变为 SATISFIED，然后再返回。如果 should_return_pending_lease 为 true，则一旦 Power Broker 授予租约，它就会返回，但可能仍为 PENDING。客户端可以监听 LEASE_SIGNAL_SATISFIED，以了解租约何时SATISFIED。

LevelDependency 资源

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

描述一个电源元素的级别对另一个电源元素的级别的依赖关系。例如，如果元素 PowerElement_A 具有级别 PowerLevel_A3，而该级别取决于元素 PowerElement_B 处于 PowerLevel_B2，则我们会填充结构体以传达以下含义：

  • dependent_level = PowerLevel_A3
  • requires_token = PowerElement_B
  • requires_level_by_preference = [PowerLevel_B2] （请注意，上述值仅为符号，例如dependent_level 需要整数值，而不是字符串。）

此结构体中未指定依赖元素的身份，必须在请求中将其指定为单独的参数，或进行推断（可能是因为通道的作用域限定为依赖元素）。

序数字段类型说明
dependent_level PowerLevel

此 LevelDependency 结构体声明支持的电源元素级别。此级别依赖于 requires_level_by_preference。
requires_token DependencyToken

必须提供通过所需元素的 ElementControl 协议的 RegisterDependencyToken 调用注册的令牌。
requires_level_by_preference vector<PowerLevel>:256

按优先顺序降序排列的级别列表，电源代理应尝试将这些级别设为必需级别，以满足此依赖项。 列表中第一个有效的级别将成为必需级别。

平台客户端可以使用此列表来保持与依赖项的向后兼容性，方法是提供依赖项可能已在较低 API 级别中实现的多个级别。
remove_with_required_element bool

如果为 true，则在移除所需元素时，系统会自动移除此依赖项。

PowerLevelName

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

明文名称到 PowerLevel 的映射。名称在元素之间应是唯一的，并且在同一 build 的重新启动过程中保持不变，但无法保证不同 build 之间的一致性。

序数字段类型说明
level PowerLevel
name string:16

UNIONS

ElementControl_AddDependency_Result strict

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

序数变体类型说明
response ElementControl_AddDependency_Response
err ModifyDependencyError
framework_err internal

ElementControl_RegisterDependencyToken_Result strict

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

序数变体类型说明
response ElementControl_RegisterDependencyToken_Response
err RegisterDependencyTokenError
framework_err internal

ElementControl_UnregisterDependencyToken_Result strict

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

序数变体类型说明
response ElementControl_UnregisterDependencyToken_Response
err UnregisterDependencyTokenError
framework_err internal

ElementInfoProvider_GetElementPowerLevelNames_Result strict resource

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

序数变体类型说明
response ElementInfoProvider_GetElementPowerLevelNames_Response
err ElementInfoProviderError
framework_err internal

ElementInfoProvider_GetStatusEndpoints_Result strict resource

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

序数变体类型说明
response ElementInfoProvider_GetStatusEndpoints_Response
err ElementInfoProviderError
framework_err internal

ElementRunner_SetLevel_Result strict

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

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

LeaseControl_WatchStatus_Result strict

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

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

Lessor_Lease_Result strict resource

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

序数变体类型说明
response Lessor_Lease_Response
err LeaseError
framework_err internal

Status_WatchPowerLevel_Result strict resource

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

序数变体类型说明
response Status_WatchPowerLevel_Response
err StatusError
framework_err internal

Topology_AddElement_Result strict

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

序数变体类型说明
response Topology_AddElement_Response
err AddElementError
framework_err internal

Topology_Lease_Result strict

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

序数变体类型说明
response Topology_Lease_Response
err LeaseError
framework_err internal

BITS

权限严格

类型：uint32

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

元素权限

名称值说明
1
4

常量

名称值类型说明
LEASE_SIGNAL_SATISFIED 16777216 uint32

当租约满足时，Power Broker 在 LeaseToken 上发送的信号。
LEASE_TOKEN_RIGHTS

表示开放租约的令牌。应丢弃客户端的句柄，以指示应关闭租约。如果租约将被共享，则此句柄可能会重复；租约将保持打开状态，直到最后一个句柄被删除。
MAX_DEPENDENCIES_IN_ADD_ELEMENT 128 uint16
MAX_ELEMENT_NAME_LEN 64 uint8
MAX_LEVEL_NAME_LEN 16 uint16

PowerLevel 名称长度受限，以减少 Inspect 空间用量
MAX_TOKENS_IN_ADD_ELEMENT 128 uint16
MAX_VALID_POWER_LEVELS 256 uint16

别名

名称值说明
DependencyToken zx/Handle

一个令牌，表示对另一个元素添加依赖项的权限。应首先通过所需元素的 ElementControl.RegisterDependencyToken 向 Power Broker 注册。
LeaseToken zx/Handle
PowerLevel uint8

用于描述元素的能量等级。 可以进一步扩展此功能，以支持其他类型的功率级别，例如 ACPI。

服务

ElementInfoProviderService

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

名称类型传输
status_provider fuchsia.power.broker/ElementInfoProvider 渠道