fuchsia.power.broker

PROTOCOLS

CurrentLevel

Defined in fuchsia.power.broker/broker.fidl

CurrentLevel and RequiredLevel must both be used by all managed Power Elements as part of the power level handshake with Power Broker:

• The element operator calls RequiredLevel.Watch to receive the next required level from Power Broker.
• The operator makes the changes necessary to transition to the new required level.
• The operator calls CurrentLevel.Update to inform Power Broker that it has completed the transition to the new level. Established via Topology.AddElement.

Update

Sent by the element on initial startup and whenever there is a change in power level.

Request

Name	Type
current_level	PowerLevel

Response

Name	Type
payload	CurrentLevel_Update_Result

ElementControl

Defined in fuchsia.power.broker/broker.fidl

Provides element-scoped access to an element previously added via Topology.AddElement.

OpenStatusChannel

Register a new Status channel on which Power Broker will send read-only updates of the element's current power level. This method is intended to allow element owners to give read-only access to the element's current power level to clients by opening and transferring this channel.

Request

Name	Type
status_channel	server_end:Status

RegisterDependencyToken

Register a token which will permit the bearer to add either an assertive or opportunistic dependency upon this element, depending on the dependency_type specified.

Request

Name	Type
token	DependencyToken
dependency_type	DependencyType

Response

Name	Type
payload	ElementControl_RegisterDependencyToken_Result

UnregisterDependencyToken

Unregister a token previously registered via RegisterDependencyToken.

Request

Name	Type
token	DependencyToken

Response

Name	Type
payload	ElementControl_UnregisterDependencyToken_Result

ElementInfoProvider

Defined in fuchsia.power.broker/broker.fidl

Provides an interface to retrieve information about PowerElements managed by a component.

GetElementPowerLevelNames

Returns mappings of PowerLevels to plaintext names for each element managed by a component. Returns an error if no mappings can be returned.

Request

<EMPTY>

Response

Name	Type
payload	ElementInfoProvider_GetElementPowerLevelNames_Result

GetStatusEndpoints

Returns available Status client endpoints and stable identifiers for each element managed by a component. Returns an error if no endpoints can be returned (i.e. no elements were able to implement the Status channel).

Request

<EMPTY>

Response

Name	Type
payload	ElementInfoProvider_GetStatusEndpoints_Result

LeaseControl

Defined in fuchsia.power.broker/broker.fidl

Provides lease-scoped access to actions that can be taken on a lease previously acquired via Lessor.Lease. Closing this control channel drops the lease. TODO(https://fxbug.dev/339474151): Switch from a protocol to an eventpair.

WatchStatus

Get the current status of the lease. If last_status is UNKNOWN, the call will return immediately with the current status. Otherwise, the call will block until the current status differs from last_status.

Request

Name	Type
last_status	LeaseStatus

Response

Name	Type
payload	LeaseControl_WatchStatus_Result

Lessor

Defined in fuchsia.power.broker/broker.fidl

Provides element-scoped access to request leases to raise the levels of an element previously added via Topology.AddElement.

Lease

Request made to indicate client intends to raise the given element to the given power level and wants to have its direct and transitive power dependencies satisfied. When LeaseControl.WatchStatus reports LeaseStatus::SATISFIED this does not indicate the PowerElement is at the leased PowerLevel. Instead this indicates that the dependencies of the leased PowerLevel are at level required by the PowerLevel.

Requesting an invalid level returns LeaseError::INVALID_LEVEL.

Request

Name	Type
level	PowerLevel

Response

Name	Type
payload	Lessor_Lease_Result

RequiredLevel

Defined in fuchsia.power.broker/broker.fidl

Part of the power level handshake with Power Broker used for receiving required levels from Power Broker. See above note on CurrentLevel. Established via Topology.AddElement.

Watch

Returns the required power level for this element. The first call on this channel will return immediately. Subsequent calls will block until the required power level has changed.

Request

<EMPTY>

Response

Name	Type
payload	RequiredLevel_Watch_Result

Status

Defined in fuchsia.power.broker/broker.fidl

Provides read-only access to the current PowerLevel of an element and the ability to watch changes to an element's power level. A new channel to this protocol can be obtained by calling OpenStatus on the element's ElementControl channel (and passed to other clients who need access to the element's current power level).

WatchPowerLevel

Returns the current power level for this element. The first call on this channel will return immediately. Subsequent calls will block until the current power level has changed.

Request

<EMPTY>

Response

Name	Type
payload	Status_WatchPowerLevel_Result

Topology

Defined in fuchsia.power.broker/broker.fidl

This is the primary initial protocol used by Power Element Owners to communicate with Power Broker. Power Element Owners should add the elements they own to the Power Topology through AddElement. All further interactions with Power Broker are done through channels opened by the AddElement call, which are scoped to the added element.

AddElement

Called by a Power Element owner to register a new Power Element and open control channels for that element.

Request

Name	Type
payload	ElementSchema

Response

Name	Type
payload	Topology_AddElement_Result

STRUCTS

CurrentLevel_Update_Response

Defined in fuchsia.power.broker/broker.fidl

<EMPTY>

ElementControl_RegisterDependencyToken_Response

Defined in fuchsia.power.broker/broker.fidl

<EMPTY>

ElementControl_UnregisterDependencyToken_Response

Defined in fuchsia.power.broker/broker.fidl

<EMPTY>

ElementInfoProvider_GetElementPowerLevelNames_Response resource

Defined in fuchsia.power.broker/broker.fidl

Field	Type	Description	Default
level_names	vector<ElementPowerLevelNames>		No default

ElementInfoProvider_GetStatusEndpoints_Response resource

Defined in fuchsia.power.broker/broker.fidl

Field	Type	Description	Default
endpoints	vector<ElementStatusEndpoint>		No default

LeaseControl_WatchStatus_Response

Defined in fuchsia.power.broker/broker.fidl

Field	Type	Description	Default
status	LeaseStatus		No default

Lessor_Lease_Response resource

Defined in fuchsia.power.broker/broker.fidl

Field	Type	Description	Default
lease_control	client_end:LeaseControl	Channel for actions to be taken on the lease. When this channel is closed, the lease will be dropped.	No default

LevelControlChannels resource

Defined in fuchsia.power.broker/broker.fidl

Field	Type	Description	Default
current	server_end:CurrentLevel	Channel on which Power Broker will receive current level updates for this element.	No default
required	server_end:RequiredLevel	Channel on which Power Broker will send required power levels for this element.	No default

LevelDependency resource

Defined in fuchsia.power.broker/broker.fidl

Describes a dependency from one power element's level on another power element's level. For example if element PowerElement_A has a level PowerLevel_A3 which depends on an element PowerElement_B being at PowerLevel_B2 where the dependency is DependencyType::ASSERTIVE then we would fill out the struct to convey the meaning:

• dependent_level = PowerLevel_A3
• requires_token = PowerElement_B,
• dependency_type = ASSERTIVE`,
• requires_level_by_preference = [PowerLevel_B2] (Note the values above are only symbolic, eg. dependent_level requires an integer value, not a string.)

The dependent Element's identity is not specified in this struct and must be specified as a separate argument in a request or be inferred, perhaps because a channel is scoped to the dependent element.

Field	Type	Description	Default
dependency_type	DependencyType	Must match the expected type of the DependencyToken, i.e. ASSERTIVE must be used if the token is specified to be an assertive dependency token and OPPORTUNISTIC must be used if the token is specified to be an opportunistic dependency token.	No default
dependent_level	PowerLevel	The power element level that this LevelDependency struct declaration supports. This is level that has a dependency on requires_level_by_preference.	No default
requires_token	DependencyToken	Must supply a token registered via the RegisterDependencyToken call of the required element's ElementControl protocol.	No default
requires_level_by_preference	vector<PowerLevel>:256	A list of levels in decreasing preferential order that power broker should attempt to make required for this dependency to be satisfied. The first level in list that is a valid level will become the required level. Platform clients can use this list to keep backwards compatibility with dependencies by providing multiple levels that the dependency may have implemented in older API levels.	No default

RequiredLevel_Watch_Response resource

Defined in fuchsia.power.broker/broker.fidl

Field	Type	Description	Default
required_level	PowerLevel		No default

Status_WatchPowerLevel_Response resource

Defined in fuchsia.power.broker/broker.fidl

Field	Type	Description	Default
current_level	PowerLevel		No default

Topology_AddElement_Response

Defined in fuchsia.power.broker/broker.fidl

<EMPTY>

ENUMS

AddElementError flexible

Type: uint32

Defined in fuchsia.power.broker/broker.fidl

Name	Value	Description
INVALID	1
NOT_AUTHORIZED	2

BinaryPowerLevel strict

Type: uint8

Defined in fuchsia.power.broker/broker.fidl

BinaryPowerLevel is a well-known set of PowerLevels with only two states: OFF and ON.

Name	Value	Description
OFF	0
ON	1

CurrentLevelError flexible

Type: uint32

Defined in fuchsia.power.broker/broker.fidl

Name	Value	Description
NOT_AUTHORIZED	1

DependencyType flexible

Type: uint32

Defined in fuchsia.power.broker/broker.fidl

An assertive dependency is strongly-fulfilled and orderly-on-termination. An opportunistic dependency is weakly-fulfilled but still orderly-on-termination.

See https://fuchsia.dev/fuchsia-src/contribute/governance/rfcs/0250_power_topology#dependency_types for more details on these definitions.

Name	Value	Description
ASSERTIVE	1
OPPORTUNISTIC	2

ElementInfoProviderError flexible

Type: uint32

Defined in fuchsia.power.broker/broker.fidl

Name	Value	Description
UNKNOWN	0
FAILED	1

LeaseError flexible

Type: uint32

Defined in fuchsia.power.broker/broker.fidl

Name	Value	Description
INTERNAL	1
NOT_AUTHORIZED	2
INVALID_LEVEL	3

LeaseStatus flexible

Type: uint32

Defined in fuchsia.power.broker/broker.fidl

Name	Value	Description
UNKNOWN	0
PENDING	1	The dependencies of the leased PowerLevel are not at their required levels.
SATISFIED	2	The PowerElement is not necessarily at the PowerLevel leased, but the PowerElements requried by the leased PowerLevel' are at their required PowerLevels.

ModifyDependencyError flexible

Type: uint32

Defined in fuchsia.power.broker/broker.fidl

Name	Value	Description
ALREADY_EXISTS	1
INVALID	2
NOT_AUTHORIZED	3
NOT_FOUND	4

RegisterDependencyTokenError flexible

Type: uint32

Defined in fuchsia.power.broker/broker.fidl

Name	Value	Description
ALREADY_IN_USE	1
INTERNAL	2

RequiredLevelError flexible

Type: uint32

Defined in fuchsia.power.broker/broker.fidl

Name	Value	Description
INTERNAL	1
NOT_AUTHORIZED	2
UNKNOWN	3

StatusError flexible

Type: uint32

Defined in fuchsia.power.broker/broker.fidl

Name	Value	Description
UNKNOWN	1

UnregisterDependencyTokenError flexible

Type: uint32

Defined in fuchsia.power.broker/broker.fidl

Name	Value	Description
NOT_AUTHORIZED	1
NOT_FOUND	2

TABLES

ElementPowerLevelNames

Defined in fuchsia.power.broker/broker.fidl

Mapping of a vector of fuchsia.power.broker/PowerLevelName to a Power Element via its plaintext name. Names are expected to be unique between elements and persistent across reboots of the same build, but consistency is not guaranteed between different builds.

Ordinal	Field	Type	Description
1	identifier	string:64
2	levels	vector<PowerLevelName>:256

ElementSchema resource

Defined in fuchsia.power.broker/broker.fidl

Passed to Topology.AddElement.

Ordinal	Field	Type	Description
1	element_name	string:64	Human-readable name for logging and debug purposes.
2	initial_current_level	PowerLevel	The initial current power level of the element.
3	valid_levels	vector<PowerLevel>:256	All power levels that are valid for this element. Any level not specified here will be treated as invalid.
4	dependencies	vector<LevelDependency>:128	List of dependencies for this element's power levels. Note: dependencies UPON this element's levels cannot be added here.
7	level_control_channels	LevelControlChannels	Channels on which Power Broker will send required power levels and receive current level updates.
8	lessor_channel	server_end:Lessor	Optional. If passed, this will be treated as a consumer element and Leases for this element can be requested via this channel.
9	element_control	server_end:ElementControl	Caller-provided ElementControl channel to be passed to Power Broker. When this channel is dropped, the element will be removed from the topology. All channels associated with this element will be closed and all tokens registered to this element will be unregistered.

ElementStatusEndpoint resource

Defined in fuchsia.power.broker/broker.fidl

Status client endpoint and a plaintext name for a specific Power Element. Names are expected to be unique between elements and persistent across reboots of the same build, but consistency is not guaranteed between different builds.

Ordinal	Field	Type	Description
1	identifier	string:64
2	status	client_end:Status

PowerLevelName

Defined in fuchsia.power.broker/broker.fidl

Mapping of a plaintext name to a PowerLevel. Names are expected to be unique between elements and persistent across reboots of the same build, but consistency is not guaranteed between different builds.

Ordinal	Field	Type	Description
1	level	PowerLevel
2	name	string:16

UNIONS

CurrentLevel_Update_Result strict

Defined in fuchsia.power.broker/broker.fidl

Ordinal	Variant	Type	Description
1	response	CurrentLevel_Update_Response
2	err	CurrentLevelError
3	framework_err	internal

ElementControl_RegisterDependencyToken_Result strict

Defined in fuchsia.power.broker/broker.fidl

Ordinal	Variant	Type	Description
1	response	ElementControl_RegisterDependencyToken_Response
2	err	RegisterDependencyTokenError
3	framework_err	internal

ElementControl_UnregisterDependencyToken_Result strict

Defined in fuchsia.power.broker/broker.fidl

Ordinal	Variant	Type	Description
1	response	ElementControl_UnregisterDependencyToken_Response
2	err	UnregisterDependencyTokenError
3	framework_err	internal

ElementInfoProvider_GetElementPowerLevelNames_Result strict resource

Defined in fuchsia.power.broker/broker.fidl

Ordinal	Variant	Type	Description
1	response	ElementInfoProvider_GetElementPowerLevelNames_Response
2	err	ElementInfoProviderError
3	framework_err	internal

ElementInfoProvider_GetStatusEndpoints_Result strict resource

Defined in fuchsia.power.broker/broker.fidl

Ordinal	Variant	Type	Description
1	response	ElementInfoProvider_GetStatusEndpoints_Response
2	err	ElementInfoProviderError
3	framework_err	internal

LeaseControl_WatchStatus_Result strict

Defined in fuchsia.power.broker/broker.fidl

Ordinal	Variant	Type	Description
1	response	LeaseControl_WatchStatus_Response
3	framework_err	internal

Lessor_Lease_Result strict resource

Defined in fuchsia.power.broker/broker.fidl

Ordinal	Variant	Type	Description
1	response	Lessor_Lease_Response
2	err	LeaseError
3	framework_err	internal

RequiredLevel_Watch_Result strict resource

Defined in fuchsia.power.broker/broker.fidl

Ordinal	Variant	Type	Description
1	response	RequiredLevel_Watch_Response
2	err	RequiredLevelError
3	framework_err	internal

Status_WatchPowerLevel_Result strict resource

Defined in fuchsia.power.broker/broker.fidl

Ordinal	Variant	Type	Description
1	response	Status_WatchPowerLevel_Response
2	err	StatusError
3	framework_err	internal

Topology_AddElement_Result strict

Defined in fuchsia.power.broker/broker.fidl

Ordinal	Variant	Type	Description
1	response	Topology_AddElement_Response
2	err	AddElementError
3	framework_err	internal

BITS

Permissions strict

Type: uint32

Defined in fuchsia.power.broker/broker.fidl

Element Permissions

Name	Value	Description
MODIFY_ASSERTIVE_DEPENDENT	1
MODIFY_OPPORTUNISTIC_DEPENDENT	2
MODIFY_DEPENDENCY	4

CONSTANTS

Name	Value	Type	Description
MAX_DEPENDENCIES_IN_ADD_ELEMENT	128	uint16
MAX_ELEMENT_NAME_LEN	64	uint8
MAX_LEVEL_NAME_LEN	16	uint16	PowerLevel name lengths are limited to reduce Inspect space usage
MAX_TOKENS_IN_ADD_ELEMENT	128	uint16
MAX_VALID_POWER_LEVELS	256	uint16

ALIASES

Name	Value	Description
DependencyToken	zx/Handle	A token that represents the right to add a dependency upon another element. Should first be registered with Power Broker via ElementControl.RegisterDependencyToken of the required element.
LeaseId	string[64]
PowerLevel	uint8	Used to describe the power level of an element. Could extend this further to support additional types of power levels, such as ACPI.

SERVICES

ElementInfoProviderService

Defined in fuchsia.power.broker/broker.fidl

Name	Type	Transport
status_provider	fuchsia.power.broker/ElementInfoProvider	Channel