Fuchsia.hardware.power.statecontrol

新增：7

协议

管理员

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

提供用于请求将系统转换为受支持电源状态的方法。

注意（请参阅 https://fxbug.dev/42136295）： 这些方法在状态转换完成之前不会返回。在大多数情况下（例如重启），成功转换意味着调用方实际上不会观察到完成，因为系统会在调用完成之前重启。这意味着，将同步 FIDL 客户端与这些方法结合使用会导致线程在调用期间甚至在组件的剩余生命周期内（对于 Reboot）被阻塞。因此，如果同步 FIDL 客户端要与此协议搭配使用，则应注意避免在用于发起转换的同一线程上处理任何因关停而引起的回调。回调示例包括 fuchsia.process.lifecycle/Lifecycle.Stop 和 fuchsia.hardware.power.statecontrol/RebootMethodsWatcher.OnReboot。 或者，调用方也可以选择将异步 FIDL 客户端与此协议搭配使用，以避免阻塞其调用线程。

Mexec

执行内核 mexec。

zx_system_mexec_payload_get() 指定的 ZBI 项预计尚未附加到提供的数据 ZBI。

已移除：NEXT

请求

名称类型
kernel_zbi handle<vmo>
data_zbi handle<vmo>

响应

名称类型
payload Admin_Mexec_Result

PerformReboot

请求设备重启。

参数：

  • options：执行此请求时使用的选项。 如果选项格式不正确（即 reasons 缺失或为空），则返回 ZX_ERR_INVALID_ARGS。

弃用

使用 Shutdown，它允许调用方指定预期操作和操作原因。

已移除：31 已弃用：29 已添加：26

请求

名称类型
options RebootOptions

响应

名称类型
payload Admin_PerformReboot_Result

PowerFullyOn

要求设备进入完全开启状态。

已移除：31 已弃用：29

请求

<EMPTY>

响应

名称类型
payload Admin_PowerFullyOn_Result

关机

要求所有设备进入关机状态。

弃用

使用 Shutdown，它允许调用方指定请求关机的原因。

已移除：31 已弃用：29

请求

<EMPTY>

响应

名称类型
payload Admin_Poweroff_Result

RebootToBootloader

请求设备重新启动并进入引导加载程序。

弃用

使用 Shutdown，它允许调用方指定请求重新启动到引导加载程序的原因。

已移除：31 已弃用：29

请求

<EMPTY>

响应

名称类型
payload Admin_RebootToBootloader_Result

RebootToRecovery

请求设备重新启动并进入 recovery 分区。

弃用

使用 Shutdown，它允许调用方指定请求重新启动到恢复模式的原因。

已移除：31 已弃用：29

请求

<EMPTY>

响应

名称类型
payload Admin_RebootToRecovery_Result

关闭

要求设备进入 options.action 指定的状态。

参数：

  • options：执行此请求时使用的选项。 如果 action 缺失，则返回 ZX_ERR_INVALID_ARGS。 reasons 可以省略，但强烈建议改为添加新的枚举值。
添加：29

请求

名称类型
options ShutdownOptions

响应

名称类型
payload Admin_Shutdown_Result

SuspendToRam

要求设备进入“挂起到 RAM”(S3) 电源状态。

下架

不支持挂起到 RAM。服务器始终返回 ZX_ERR_NOT_SUPPORTED。

已移除：NEXT

请求

<EMPTY>

响应

名称类型
payload Admin_SuspendToRam_Result

RebootMethodsWatcherRegister

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

允许组件注册一个回调，该回调将在调用 Reboot 方法时执行。此协议的主要用途是能够跟踪重启原因。如果您考虑使用此协议，请考虑依赖组件框架的有序关停。

已移除：31 已弃用：29

RegisterWatcher

注册一个观察器，以便在调用 Reboot 方法时收到通知。

成功向服务器注册观察器后，请求将完成，RebootMethodsWatcherRegister 通道将保持打开状态（不过客户端此时可以自由关闭该通道）。

如果注册观察器时出错，则 RebootMethodsWatcherRegister 通道将关闭，而不会完成请求。

提供的 watcher 渠道最多会使用一次，用于通知观察器即将重启，并让其有机会做出响应。

观察器可以通过关闭其 RebootWatcher 渠道来取消注册。

添加：26

请求

名称类型
watcher client_end:RebootWatcher

响应

<EMPTY>

RebootWatcher

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

允许在调用与重启相关的方法时通知组件。 在系统电源状态发生变化之前，观察器将有“MAX_REBOOT_WATCHER_RESPONSE_TIME_SECONDS”的时间来返回。该频道将用于向观察者发送一次通知。一旦观察器响应或超时，RebootWatcher 的客户端就会关闭通道。

已移除：31 已弃用：29 已添加：26

OnReboot

请求

名称类型
options RebootOptions

响应

<EMPTY>

ShutdownWatcher

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

允许在调用 Shutdown 方法时通知组件。 在系统电源状态发生变化之前，观察器将有 MAX_SHUTDOWN_WATCHER_RESPONSE_TIME_SECONDS 的时间来返回。该频道将用于向观察者发送一次通知。一旦观察器响应或超时，ShutdownWatcher 的客户端就会关闭通道。

添加：29

OnShutdown

请求

名称类型
options ShutdownOptions

响应

名称类型
payload ShutdownWatcher_OnShutdown_Result

ShutdownWatcherRegister

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

允许组件注册在发生重启或关机时执行的回调。 此协议的主要目的是能够跟踪关停原因，并向无法依赖组件框架有序关停的关键平台组件提供信号。 在依赖此协议之前，请考虑使用组件框架的有序关停模式或组件生命周期钩子。

添加：29

RegisterTerminalStateWatcher

注册一个观察器，以便在系统开始转换到终端状态时（无论触发器是什么）收到通知。

TerminalStateWatcher 会收到所有重新启动、关机和内核发起的关机的通知。它不提供原因或选项。

成功向服务器注册观察器后，请求将完成，并且 ShutdownWatcherRegister 通道将保持打开状态（不过客户端此时可以自由关闭它）。

如果注册监控器时出错，则 ShutdownWatcherRegister 通道将关闭，而不会完成请求。

提供的 watcher 渠道最多将使用一次，用于通知观察器即将关停，并让其有机会做出响应。

观察器可以通过关闭其 TerminalStateWatcher 渠道来取消注册。

Added: HEAD

请求

名称类型
watcher client_end:TerminalStateWatcher

响应

名称类型
payload ShutdownWatcherRegister_RegisterTerminalStateWatcher_Result

RegisterWatcher

注册一个观察器，以便在调用 Admin.Shutdown 方法时收到通知。

成功向服务器注册观察器后，请求将完成，并且 ShutdownWatcherRegister 通道将保持打开状态（不过客户端此时可以自由关闭它）。

如果注册监控器时出错，则 ShutdownWatcherRegister 通道将关闭，而不会完成请求。

提供的 watcher 渠道最多将使用一次，用于通知观察器即将关停，并使其有机会做出响应。

观察器可以通过关闭其 ShutdownWatcher 渠道来取消注册。

请求

名称类型
watcher client_end:ShutdownWatcher

响应

名称类型
payload ShutdownWatcherRegister_RegisterWatcher_Result

TerminalStateWatcher

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

允许在开始转换到终端状态时通知组件。 在系统电源状态发生变化之前，观察器将有“MAX_TERMINAL_STATE_WATCHER_RESPONSE_TIME_SECONDS”的时间来返回。该频道将用于向观察者发送一次通知。一旦观察器响应或超时，通道将由 TerminalStateWatcher 的客户端关闭。

Added: HEAD

OnTerminalStateTransitionStarted

请求

<EMPTY>

响应

名称类型
payload TerminalStateWatcher_OnTerminalStateTransitionStarted_Result

STRUCTS

Admin_Mexec_Response

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

<EMPTY>

Admin_PerformReboot_Response

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

<EMPTY>

Admin_PowerFullyOn_Response

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

<EMPTY>

Admin_Poweroff_Response

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

<EMPTY>

Admin_RebootToBootloader_Response

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

<EMPTY>

Admin_RebootToRecovery_Response

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

<EMPTY>

Admin_Shutdown_Response

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

<EMPTY>

Admin_SuspendToRam_Response

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

<EMPTY>

ShutdownWatcherRegister_RegisterTerminalStateWatcher_Response

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

<EMPTY>

ShutdownWatcherRegister_RegisterWatcher_Response

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

<EMPTY>

ShutdownWatcher_OnShutdown_Response

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

<EMPTY>

TerminalStateWatcher_OnTerminalStateTransitionStarted_Response

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

<EMPTY>

枚举

RebootReason2 灵活

类型：uint32

在 fuchsia.hardware.power.statecontrol/reboot_reason.fidl 中定义

系统重新启动的原因。

替换为 ShutdownReason。

已移除：31 已弃用：29 已添加：26

名称值说明
1

设备已重启，因为设备的最终用户发起了重启。

请勿用于任何与最终用户明确重启操作不直接相关的代码路径。 请改用下方的 DEVELOPER_REQUEST。
13

设备重启是因为开发者发起了重启，通常是通过 shell 命令或类似接口（包括在自动化测试中）发起的。

新增：28
2

已下载新的系统更新。
8

未能应用系统更新。
3
6
4

Sessionmgr 失败。
5

sysmgr 崩溃。
7

一个关键系统组件出现故障。
9

启动分区发生了更改。
10

系统可用内存已达到严重不足的阈值。
11

Netstack 组件正在更改版本。
12

Starnix 无法识别的 Android 发起的重启原因

新增：28
14

Android 启动了“RescueParty”。

添加：29
15

一个关键 Android 进程失败。

添加：29

ShutdownAction flexible

类型：uint32

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

添加：29

名称值说明
1
2
3
4

ShutdownReason flexible

类型：uint32

在 fuchsia.hardware.power.statecontrol/shutdown_reason.fidl 中定义

系统关闭的原因。

添加：29

名称值说明
1

设备的最终用户发起了关停。

请勿用于任何与最终用户明确关机操作不直接相关的代码路径。 请改用下方的 DEVELOPER_REQUEST。
16

设备的最终用户因设备卡住而启动了关机。

新增：31
2

开发者启动了关机，通常是通过 shell 命令或类似界面（包括在自动化测试中）。
3

已下载新的系统更新。
4

未能应用系统更新。
5

设备已超过高温阈值。
6

设备即将执行 FDR。
7

Sessionmgr 失败。
8

一个关键系统组件出现故障。
9

启动分区发生了更改。
10

系统可用内存已达到严重不足的阈值。
11

Netstack 组件正在更改版本。

已移除：NEXT
12

Starnix 无法识别的 Android 发起的关机原因。
15

Starnix 容器发起了关机，但 Starnix 不知道原因。

新增：30
13

Android 启动了“RescueParty”。
14

一个关键 Android 进程失败。
17

设备电池电量耗尽。

新增：31
18

系统未能在预期时间内暂停或恢复。

新增：32
19

关键驱动程序失败。

Added: HEAD

TABLES

RebootOptions

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

请求重新启动时指定的选项。

已移除：31 已弃用：29 已添加：26

序数字段类型说明
reasons vector<RebootReason2>:100

导致此重新启动请求的一组重新启动原因。

ShutdownOptions

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

请求关停时指定的选项。

添加：29

序数字段类型说明
action ShutdownAction
reasons vector<ShutdownReason>:100

导致此关停请求的一组关停原因。

UNIONS

Admin_Mexec_Result strict

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

序数变体类型说明
response Admin_Mexec_Response
err zx/Status

Admin_PerformReboot_Result strict

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

序数变体类型说明
response Admin_PerformReboot_Response
err zx/Status

Admin_PowerFullyOn_Result strict

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

序数变体类型说明
response Admin_PowerFullyOn_Response
err zx/Status

Admin_Poweroff_Result strict

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

序数变体类型说明
response Admin_Poweroff_Response
err zx/Status

Admin_RebootToBootloader_Result strict

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

序数变体类型说明
response Admin_RebootToBootloader_Response
err zx/Status

Admin_RebootToRecovery_Result strict

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

序数变体类型说明
response Admin_RebootToRecovery_Response
err zx/Status

Admin_Shutdown_Result strict

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

序数变体类型说明
response Admin_Shutdown_Response
err zx/Status

Admin_SuspendToRam_Result strict

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

序数变体类型说明
response Admin_SuspendToRam_Response
err zx/Status

ShutdownWatcherRegister_RegisterTerminalStateWatcher_Result strict

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

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

ShutdownWatcherRegister_RegisterWatcher_Result strict

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

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

ShutdownWatcher_OnShutdown_Result strict

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

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

TerminalStateWatcher_OnTerminalStateTransitionStarted_Result strict

在 fuchsia.hardware.power.statecontrol/admin.fidl 中定义

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

常量

名称值类型说明
MAX_REBOOT_REASONS 100 uint8

可归因于单个重启请求的重启原因数量上限。

已移除：31 已弃用：29 已添加：26
MAX_REBOOT_WATCHER_RESPONSE_TIME_SECONDS 5 uint32

服务器在更改系统电源状态之前，等待所有 RebootMethodsWatchers 响应的最长秒数。

已移除：31 已弃用：29
MAX_SHUTDOWN_REASONS 100 uint8

可归因于单个关停请求的关停原因数量上限。

添加：29
MAX_SHUTDOWN_WATCHER_RESPONSE_TIME_SECONDS 5 uint32

服务器在更改系统电源状态之前等待所有 ShutdownWatcher 响应的最长秒数。

添加：29
MAX_TERMINAL_STATE_WATCHER_RESPONSE_TIME_SECONDS 5 uint32

服务器在更改系统电源状态之前等待所有 TerminalStateWatcher 响应的最长秒数。

Added: HEAD