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，硬體平台就不會暫停。

這適用於預期會長期持有的租約。與一般喚醒租約不同，伺服器不會監控未監控喚醒租約的時間長度，也不會在超過預先設定的警示門檻時提交當機報告。

新增：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 用戶端的所有控制代碼都已關閉。

新增：HEAD

要求

名稱類型
payload ActivityGovernorAcquireWakeLease2Request

回應

名稱類型
payload ActivityGovernor_AcquireWakeLease2_Result

AcquireWakeLeaseWithToken

建立租約，防止硬體平台遭到停權。警告：只有在用戶端收到這項呼叫的回應後，才能將暫停視為已封鎖。舉例來說，這表示只有在收到無錯誤的回應後，才能確認中斷或捨棄其他喚醒租約。

硬體平台會維持恢復狀態，直到 server_token 觀察到 PEER_CLOSED，表示 LeaseToken 用戶端的所有控制代碼都已關閉。

新增：HEAD

要求

名稱類型
name string:64
server_token LeaseToken

回應

名稱類型
payload ActivityGovernor_AcquireWakeLeaseWithToken_Result

GetPowerElements

取得活動管理工具擁有的電源元素。

如果伺服器向電源代理程式註冊電源元素時發生錯誤，或為電源元素建立權杖時發生錯誤，伺服器會關閉 ActivityGovernor 的管道，且不會傳回任何回應。

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

建立租約，防止系統低於應用程式活動「Active」狀態。具體來說，這會阻止硬體平台暫停。

在 SuspendBlocker.BeforeSuspend 期間，呼叫這個方法並不安全。

如果為活動租約建立權杖時發生錯誤，伺服器會關閉 ActivityGovernor 的管道，且不會傳回任何回應。

新增：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 相關電源元素。

新增：HEAD

AddExecutionStateDependency

在 power_level，新增從執行狀態電源元素到 dependency_token 識別的目標電源元素的依附元件。

建立執行狀態電源元素後，日後的呼叫會傳回 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

用於公開執行狀態管理功能的服務。

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

系統活動調節器發現硬體平台已恢復運作後，就會呼叫這個方法。

在呼叫期間，ExecutionState 處於 INACTIVE 層級，但保證 ExecutionStateLevel::SUSPENDING 的所有依附元件都符合條件。

因此，SuspendBlocker 不得呼叫 ActivityGovernor.TakeApplicationActivityLease，也不得執行任何其他動作，以免在執行狀態達到 INACTIVE 以外的層級時遭到封鎖。否則會導致死結。(不過，AcquireWakeLease 不會以這種方式封鎖，因此可以安全呼叫)。

要求

<EMPTY>

回應

名稱類型
payload SuspendBlocker_AfterResume_Result

BeforeSuspend

系統活動調節器開始作業以暫停硬體平台後，系統會呼叫這個函式。

伺服器應在執行必要作業，準備好暫停後回應。在呼叫期間，系統會確保 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 resource

定義於 fuchsia.power.system/system.fidl

欄位類型說明預設
token LeaseToken

這個權杖可防止應用程式活動低於「Active」狀態。

 無預設值

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 彈性

類型：uint32

定義於 fuchsia.power.system/system.fidl

ActivityGovernor/AcquireWakeLease 和 AcquireWakeLease2 傳回的錯誤。

新增：26

名稱值說明
1

服務嘗試發出喚醒租約時發生錯誤。
2

喚醒租約名稱空白或無效。
3

未提供必要的 server_token 引數。

新增：HEAD
4

previous_client_token 引數無效 (例如，參照與 server_token 相同的權杖組合)。

新增：HEAD

AddApplicationActivityDependencyError flexible

類型：uint32

定義於 fuchsia.power.system/system.fidl

fuchsia.power.system/ActivityGovernor 中 AddApplicationActivityDependency 回應的錯誤代碼。

新增：HEAD

名稱值說明
1

已有這個依附元件。
2

未提供必要引數或引數無效。
3

服務嘗試新增依附元件時發生錯誤。

AddExecutionStateDependencyError 彈性

類型：uint32

定義於 fuchsia.power.system/system.fidl

fuchsia.power.system/CpuElementManager 中 AddExecutionStateDependency 回應的錯誤代碼。

新增：HEAD

名稱值說明
1

未提供必要引數或引數無效。
2

伺服器目前的狀態無法處理要求。

ApplicationActivityLevel 彈性

類型：uint8

定義於 fuchsia.power.system/system.fidl

應用程式活動耗電量

需要防止系統暫停的元素應明確依附 ApplicationActivityLevel::ACTIVE。這些元件執行工作時，應要求租約以確保系統保持運作，並在完成工作後釋出租約。

新增：HEAD

名稱值說明
0
1

CpuLevel 彈性

類型：uint8

定義於 fuchsia.power.system/system.fidl

CPU 功率等級

元素應對 CpuLevel::ACTIVE 採取明確依附關係，確保元素會在 CPU 暫停前暫停。

新增：HEAD

名稱值說明
0
1

ExecutionStateLevel 彈性

類型：uint8

定義於 fuchsia.power.system/system.fidl

執行狀態功率等級

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

保留應用程式活動電源元素的權杖。

fuchsia.power.system/ApplicationActivityLevel 定義這個電源元素支援的電源等級。

新增：HEAD

序數欄位類型說明
assertive_dependency_token fuchsia.power.broker/DependencyToken

資源

定義於 fuchsia.power.system/system.fidl

保留 CPU 電源元素的權杖。

fuchsia.power.system/CpuLevel 定義這個電源元素支援的電源等級。

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

保留執行狀態電源元素的依附元件權杖。

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

由活動調節器管理的一組電源元素。

新增：HEAD

序數欄位類型說明
application_activity ApplicationActivity

UNIONS

ActivityGovernor_AcquireUnmonitoredWakeLease_Result strict resource

定義於 fuchsia.power.system/system.fidl

序數Variant類型說明
response ActivityGovernor_AcquireUnmonitoredWakeLease_Response
err AcquireWakeLeaseError
framework_err internal

ActivityGovernor_AcquireWakeLease2_Result strict

定義於 fuchsia.power.system/system.fidl

序數Variant類型說明
response ActivityGovernor_AcquireWakeLease2_Response
err AcquireWakeLeaseError
framework_err internal

ActivityGovernor_AcquireWakeLeaseWithToken_Result strict

定義於 fuchsia.power.system/system.fidl

序數Variant類型說明
response ActivityGovernor_AcquireWakeLeaseWithToken_Response
err AcquireWakeLeaseError
framework_err internal

ActivityGovernor_AcquireWakeLease_Result strict resource

定義於 fuchsia.power.system/system.fidl

序數Variant類型說明
response ActivityGovernor_AcquireWakeLease_Response
err AcquireWakeLeaseError
framework_err internal

ActivityGovernor_GetPowerElements_Result strict resource

定義於 fuchsia.power.system/system.fidl

序數Variant類型說明
response PowerElements
framework_err internal

ActivityGovernor_RegisterSuspendBlocker_Result strict resource

定義於 fuchsia.power.system/system.fidl

序數Variant類型說明
response ActivityGovernor_RegisterSuspendBlocker_Response
err RegisterSuspendBlockerError
framework_err internal

ActivityGovernor_TakeApplicationActivityLease_Result strict resource

定義於 fuchsia.power.system/system.fidl

序數Variant類型說明
response ActivityGovernor_TakeApplicationActivityLease_Response
framework_err internal

BootControl_SetBootComplete_Result strict

定義於 fuchsia.power.system/system.fidl

序數Variant類型說明
response BootControl_SetBootComplete_Response
framework_err internal

CpuElementManager_AddExecutionStateDependency_Result strict

定義於 fuchsia.power.system/system.fidl

序數Variant類型說明
response CpuElementManager_AddExecutionStateDependency_Response
err AddExecutionStateDependencyError
framework_err internal

CpuElementManager_GetCpuDependencyToken_Result strict resource

定義於 fuchsia.power.system/system.fidl

序數Variant類型說明
response Cpu
framework_err internal

ExecutionStateManager_AddApplicationActivityDependency_Result strict

定義於 fuchsia.power.system/system.fidl

序數Variant類型說明
response ExecutionStateManager_AddApplicationActivityDependency_Response
err AddApplicationActivityDependencyError
framework_err internal

ExecutionStateManager_GetExecutionStateDependencyToken_Result strict resource

定義於 fuchsia.power.system/system.fidl

序數Variant類型說明
response ExecutionState
framework_err internal

SuspendBlocker_AfterResume_Result strict

定義於 fuchsia.power.system/system.fidl

序數Variant類型說明
response SuspendBlocker_AfterResume_Response
framework_err internal

SuspendBlocker_BeforeSuspend_Result strict

定義於 fuchsia.power.system/system.fidl

序數Variant類型說明
response SuspendBlocker_BeforeSuspend_Response
framework_err internal

常數

名稱值類型說明
MAX_ELEMENT_NAME_LEN 64 uint8
新增：26

別名

名稱值說明
LeaseToken zx/Handle
新增：26