fuchsia.hardware.power.statecontrol

新增：7

通訊協定

管理員

定義於 fuchsia.hardware.power.statecontrol/admin.fidl

提供方法，要求系統轉換為支援的電源狀態。

注意 (請參閱 https://fxbug.dev/42136295)： 這些方法在狀態轉換完成後才會傳回。在大多數情況下 (例如重新啟動)，成功轉換代表呼叫端實際上不會觀察到完成，因為系統會在呼叫完成前重新啟動。這表示如果使用同步 FIDL 用戶端搭配這些方法，會導致執行緒在呼叫期間遭到封鎖，甚至在元件剩餘的生命週期內 (如果是重新啟動) 也是如此。因此，如果同步 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

Poweroff

要求所有裝置進入關機狀態。

淘汰

使用 Shutdown，讓呼叫者指定要求關機的原因。

已移除：31 已淘汰：29

要求

<EMPTY>

回應

名稱類型
payload Admin_Poweroff_Result

RebootToBootloader

要求裝置重新啟動至系統啟動載入程式。

淘汰

使用 Shutdown，讓呼叫端指定要求重新啟動至 bootloader 的原因。

已移除：31 已淘汰：29

要求

<EMPTY>

回應

名稱類型
payload Admin_RebootToBootloader_Result

RebootToRecovery

要求裝置重新啟動並進入復原分區。

淘汰

使用 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 管道，取消註冊。

新增：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 的用戶端會關閉管道。

新增：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

開發人員啟動重新啟動程序，通常是透過殼層指令或類似介面 (包括在自動化測試中)，因此裝置重新啟動。

新增：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 彈性

類型：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

開發人員啟動關閉程序，通常是透過殼層指令或類似介面，包括在自動化測試中。
3

已下載新的系統更新。
4

無法套用系統更新。
5

裝置溫度已超過高溫門檻。
6

裝置即將恢復原廠設定。
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

重要驅動程式庫失敗。

新增：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

序數Variant類型說明
response Admin_Mexec_Response
err zx/Status

Admin_PerformReboot_Result strict

定義於 fuchsia.hardware.power.statecontrol/admin.fidl

序數Variant類型說明
response Admin_PerformReboot_Response
err zx/Status

Admin_PowerFullyOn_Result strict

定義於 fuchsia.hardware.power.statecontrol/admin.fidl

序數Variant類型說明
response Admin_PowerFullyOn_Response
err zx/Status

Admin_Poweroff_Result strict

定義於 fuchsia.hardware.power.statecontrol/admin.fidl

序數Variant類型說明
response Admin_Poweroff_Response
err zx/Status

Admin_RebootToBootloader_Result strict

定義於 fuchsia.hardware.power.statecontrol/admin.fidl

序數Variant類型說明
response Admin_RebootToBootloader_Response
err zx/Status

Admin_RebootToRecovery_Result strict

定義於 fuchsia.hardware.power.statecontrol/admin.fidl

序數Variant類型說明
response Admin_RebootToRecovery_Response
err zx/Status

Admin_Shutdown_Result strict

定義於 fuchsia.hardware.power.statecontrol/admin.fidl

序數Variant類型說明
response Admin_Shutdown_Response
err zx/Status

Admin_SuspendToRam_Result strict

定義於 fuchsia.hardware.power.statecontrol/admin.fidl

序數Variant類型說明
response Admin_SuspendToRam_Response
err zx/Status

ShutdownWatcherRegister_RegisterTerminalStateWatcher_Result strict

定義於 fuchsia.hardware.power.statecontrol/admin.fidl

序數Variant類型說明
response ShutdownWatcherRegister_RegisterTerminalStateWatcher_Response
framework_err internal

ShutdownWatcherRegister_RegisterWatcher_Result strict

定義於 fuchsia.hardware.power.statecontrol/admin.fidl

序數Variant類型說明
response ShutdownWatcherRegister_RegisterWatcher_Response
framework_err internal

ShutdownWatcher_OnShutdown_Result strict

定義於 fuchsia.hardware.power.statecontrol/admin.fidl

序數Variant類型說明
response ShutdownWatcher_OnShutdown_Response
framework_err internal

TerminalStateWatcher_OnTerminalStateTransitionStarted_Result strict

定義於 fuchsia.hardware.power.statecontrol/admin.fidl

序數Variant類型說明
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 回應的最長秒數。

新增：HEAD