fuchsia.power.broker

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

傳回可用的狀態用戶端端點，以及元件管理的每個元素穩定 ID。如果無法傳回任何端點 (即沒有任何元素能實作狀態管道)，則會傳回錯誤。

要求

<EMPTY>

回應

名稱類型
payload ElementInfoProvider_GetStatusEndpoints_Result

ElementRunner

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

元素的執行者或操作者。所有元素擁有者都應實作這個方法。用戶端端點會透過 ElementSchema.element_runner 傳遞至 Power Broker。Power Broker 會先呼叫 SetLevel，然後在元素所需等級變更時呼叫。

SetLevel

設定能量元素等級。

伺服器在轉換關卡時會封鎖。轉換至新的必要等級後，系統會傳回。如果元素無法轉換至新的必要層級，且無法重試，管道就會關閉。

要求

名稱類型
level PowerLevel

回應

名稱類型
payload ElementRunner_SetLevel_Result

LeaseControl

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

提供租約範圍的存取權，可對先前透過 Lessor.Lease 取得的租約執行動作。關閉這個控制管道會捨棄租約。TODO(https://fxbug.dev/339474151)：從通訊協定切換至 eventpair。

WatchStatus

取得租約的目前狀態。如果 last_status 為 UNKNOWN，呼叫會立即傳回目前狀態。否則，呼叫會遭到封鎖，直到目前狀態與 last_status 不同。

新增：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 Element 擁有者與 Power Broker 通訊時，主要使用的初始通訊協定。電源元素擁有者應透過 AddElement，將擁有的元素新增至電源拓撲。與 Power Broker 的所有後續互動，都是透過 AddElement 呼叫開啟的管道進行，這些管道的範圍限定為新增的元素。

AddElement

由 Power Element 擁有者呼叫，用於註冊新的 Power Element，並開啟該元素的控制管道。

要求

名稱類型
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 resource

定義於 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

BinaryPowerLevel strict

類型：uint8

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

BinaryPowerLevel 是一組知名的 PowerLevel，只有兩種狀態：OFF 和 ON。

名稱值說明
0
1

ElementInfoProviderError 彈性

類型：uint32

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

名稱值說明
0
1

彈性 LeaseError

類型：uint32

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

名稱值說明
1
2
3
4

LeaseStatus 彈性

類型：uint32

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

名稱值說明
0
1

Power Broker 已收到租約，並已開始向上轉換功率，但尚未完成。也就是說，租用的 PowerLevel 有一或多個依附元件尚未達到必要層級。
2

租用的 PowerLevel 所需的所有依附元件都位於其必要的 PowerLevel，且租用的 PowerElement 已轉換至要求的層級。
3

用戶端已捨棄租約，Power Broker 也已確認，且降低功率的轉換作業已開始，但尚未完成。
4

租約已移除，所有相關的電源轉換作業也已完成。

ModifyDependencyError 彈性

類型：uint32

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

名稱值說明
1
2
3
4

RegisterDependencyTokenError 彈性

類型：uint32

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

名稱值說明
1
2

StatusError 彈性

類型：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 向量對應至電源元素。元素之間的名稱不得重複，且在重新啟動相同版本後仍會保留，但不同版本之間的名稱不一定會保持一致。

序數欄位類型說明
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

狀態用戶端端點和特定 Power Element 的純文字名稱。名稱在元素之間應為不重複，且在相同建構作業重新啟動時保持不變，但不同建構作業之間不保證一致。

序數欄位類型說明
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 必須是整數值，而非字串。

這個 struct 未指定依附元素的識別，必須在要求中指定為獨立引數，或由系統推論 (可能因為管道範圍限定為依附元素)。

序數欄位類型說明
dependent_level PowerLevel

這個 LevelDependency struct 宣告支援的電源元素層級。這個層級具有 requires_level_by_preference 的依附元件。
requires_token DependencyToken

必須提供透過必要元素的 ElementControl 通訊協定 RegisterDependencyToken 呼叫註冊的權杖。
requires_level_by_preference vector<PowerLevel>:256

依偏好程度遞減排序的層級清單，Power Broker 應嘗試要求這些層級，以滿足這項依附元件。清單中第一個有效層級會成為必要層級。

平台用戶端可以使用這份清單，提供依附元件在舊版 API 級別中可能實作的多個級別，藉此維持與依附元件的回溯相容性。
remove_with_required_element bool

如果為 true，則在移除必要元素時，系統會自動移除這個依附元件。

PowerLevelName

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

將明文名稱對應至 PowerLevel。元素之間的名稱應不重複，且在重新啟動相同版本後仍會保留，但不同版本之間的名稱不一定會一致。

序數欄位類型說明
level PowerLevel
name string:16

UNIONS

ElementControl_AddDependency_Result strict

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

序數Variant類型說明
response ElementControl_AddDependency_Response
err ModifyDependencyError
framework_err internal

ElementControl_RegisterDependencyToken_Result strict

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

序數Variant類型說明
response ElementControl_RegisterDependencyToken_Response
err RegisterDependencyTokenError
framework_err internal

ElementControl_UnregisterDependencyToken_Result strict

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

序數Variant類型說明
response ElementControl_UnregisterDependencyToken_Response
err UnregisterDependencyTokenError
framework_err internal

ElementInfoProvider_GetElementPowerLevelNames_Result strict resource

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

序數Variant類型說明
response ElementInfoProvider_GetElementPowerLevelNames_Response
err ElementInfoProviderError
framework_err internal

ElementInfoProvider_GetStatusEndpoints_Result strict resource

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

序數Variant類型說明
response ElementInfoProvider_GetStatusEndpoints_Response
err ElementInfoProviderError
framework_err internal

ElementRunner_SetLevel_Result strict

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

序數Variant類型說明
response ElementRunner_SetLevel_Response
framework_err internal

LeaseControl_WatchStatus_Result strict

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

序數Variant類型說明
response LeaseControl_WatchStatus_Response
framework_err internal

Lessor_Lease_Result strict resource

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

序數Variant類型說明
response Lessor_Lease_Response
err LeaseError
framework_err internal

Status_WatchPowerLevel_Result strict resource

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

序數Variant類型說明
response Status_WatchPowerLevel_Response
err StatusError
framework_err internal

Topology_AddElement_Result strict

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

序數Variant類型說明
response Topology_AddElement_Response
err AddElementError
framework_err internal

Topology_Lease_Result strict

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

序數Variant類型說明
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 版本