fuchsia.power.system

The system activity governor (SAG) is a subsystem of the power framework that manages the execution and suspend state of the hardware platform. It also allows observers to watch for suspend/resume transitions of the platform.

Other components can create dependencies on SAG's power elements with fuchsia.power.broker/ElementControl to influence SAG's behavior including preventing system suspension.

The power elements that SAG creates and manages are as follows:

Internal Dependency Diagram

               +--------------------+                  +---------------------------------+
               | **ExecutionState** |                  |     **ApplicationActivity**     |
               +--------------------+                  +---------------------------------+
               |       ACTIVE       |<-----------------|             ACTIVE              |
               +--------------------+                  +---------------------------------+
+--------------|     SUSPENDING     |<--------+        |            INACTIVE             |
|              |                    |         |        +---------------------------------+
|              +--------------------+         |
|              |      INACTIVE      |         |        +---------------------------------+
|              +--------------------+         |        |         **WakeHandling**        |
|                                             |        +---------------------------------+
|                                             +--------|             ACTIVE              |
|                                                      +---------------------------------+
|                                                      |            INACTIVE             |
|                                                      +---------------------------------+
|
|    +---------------------------------+
|    |             **CPU**             |
|    +---------------------------------+
+--->|             ACTIVE              |
     +---------------------------------+
     |            INACTIVE             |
     +---------------------------------+

Usage

To prevent system suspension, a component can create an assertive dependency using the assertive_dependency_token from ApplicationActivity or WakeHandling. If the dependency causes the power level of ApplicationActivity and/or WakeHandling to be raised to fuchsia.power.system/ApplicationActivityPowerLevel.ACTIVE and/or fuchsia.power.system/WakeHandlingPowerLevel.ACTIVE, respectively, SAG will not trigger system suspension until their power levels drop to INACTIVE.

If a component is managing a power element that requires the platform to be in a specific state, an opportunistic dependency can be created on ExecutionState. When ExecutionState changes its power level, all dependent power elements will power down first. Ideally, this forces the entire system into a configuration with a lower power consumption as the power level of ExecutionState decreases.

Added: HEAD

PROTOCOLS

ActivityGovernor

Defined in fuchsia.power.system/system.fidl

A service for exposing events and power elements managed by the system activity governor (SAG).

SAG is responsible for managing the execution state of the hardware platform. The hardware platform consists of the components required to execute code on the device. This typically includes the CPU, memory, operating system, and other components required for these components to function (clock trees, power domains, etc.).

GetPowerElements

Gets the power elements owned by the activity governor.

If an error occurs while the server is registering a power element with the power broker or an error occurs while creating a token for a power element, then the channel to ActivityGovernor will be closed by the server and no response will be returned.

Request

<EMPTY>

Response

Name	Type
`payload`	`ActivityGovernor_GetPowerElements_Result`

RegisterListener

Registers a listener for activity governor events.

If there is an error in registering the listener, then the given ActivityGovernorListener channel will be closed before the response is sent.

To unregister, close the ActivityGovernorListener channel.

Request

Name	Type
`payload`	`ActivityGovernorRegisterListenerRequest`

Response

Name	Type
`payload`	`ActivityGovernor_RegisterListener_Result`

TakeApplicationActivityLease

Creates a lease that blocks the system from dropping below the Application Activity 'Active' state. In particular, this blocks suspension of the hardware platform.

Additionally, during a given boot, SAG will not suspend the hardware platform until the first time a lease provided by this method is acquired and dropped. Due to this effect, clients wishing to block suspension should default to using TakeWakeLease.

If an error occurs while creating a token for the activity lease, then the channel to ActivityGovernor will be closed by the server and no response will be returned.

Request

Name	Type
`name`	`string:64`

Response

Name	Type
`payload`	`ActivityGovernor_TakeApplicationActivityLease_Result`

TakeWakeLease

Creates a lease that blocks suspension of the hardware platform.

The hardware platform will not suspend as long as a valid LeaseToken exists.

If an error occurs while creating a token for the wake lease, then the channel to ActivityGovernor will be closed by the server and no response will be returned.

Request

Name	Type
`name`	`string:64`

Response

Name	Type
`payload`	`ActivityGovernor_TakeWakeLease_Result`

ActivityGovernorListener

Defined in fuchsia.power.system/system.fidl

A listener for activity governor events.

OnResume

Called when the activity governor detects a system resume.

This is only called when the wakeup reason returned by the platform requires a full system resume. The server is expected to respond once it has performed the operations required to keep the system awake, if needed.

Request

<EMPTY>

Response

<EMPTY>

OnSuspendFail

Called when the activity governor detects a suspend failure.

The server is expected to respond to this notification. The activity governor will not attempt to suspend again until it receives the respond.

Request

<EMPTY>

Response

Name	Type
`payload`	`ActivityGovernorListener_OnSuspendFail_Result`

OnSuspendStarted

Called before the activity governor initiates a system suspension.

The server is expected to respond once it has performed the operations it needs to prepare itself for suspend, if any.

Request

<EMPTY>

Response

Name	Type
`payload`	`ActivityGovernorListener_OnSuspendStarted_Result`

CpuElementManager

Defined in fuchsia.power.system/system.fidl

A service that provides access to CPU-related power elements.

AddExecutionStateDependency

Adds a dependency from the Execution State power element to the target power element identified by dependency_token at power_level.

Once the Execution State power element is created, future calls will return fuchsia.power.system/AddExecutionStateDependencyError.BAD_STATE and no changes to Execution State dependencies will be made.

If any required entries in the request are missing, the server will return fuchsia.power.system/AddExecutionStateDependencyError.INVALID_ARGS.

Request

Name	Type
`payload`	`CpuElementManagerAddExecutionStateDependencyRequest`

Response

Name	Type
`payload`	`CpuElementManager_AddExecutionStateDependency_Result`

GetCpuDependencyToken

Gets the assertive dependency token for the CPU power element.

Request

<EMPTY>

Response

Name	Type
`payload`	`CpuElementManager_GetCpuDependencyToken_Result`

STRUCTS

ActivityGovernorListener_OnSuspendFail_Response

Defined in fuchsia.power.system/system.fidl

<EMPTY>

ActivityGovernorListener_OnSuspendStarted_Response

Defined in fuchsia.power.system/system.fidl

<EMPTY>

ActivityGovernor_RegisterListener_Response

Defined in fuchsia.power.system/system.fidl

<EMPTY>

ActivityGovernor_TakeApplicationActivityLease_Response resource

Defined in fuchsia.power.system/system.fidl

Field	Type	Description	Default
`token`	`LeaseToken`	The token that blocks application activity from dropping below the 'Active' state.	No default

ActivityGovernor_TakeWakeLease_Response resource

Defined in fuchsia.power.system/system.fidl

Field	Type	Description	Default
`token`	`LeaseToken`	The token that blocks hardware platform suspension.	No default

CpuElementManager_AddExecutionStateDependency_Response

Defined in fuchsia.power.system/system.fidl

<EMPTY>

ENUMS

AddExecutionStateDependencyError flexible

Type: uint32

Defined in fuchsia.power.system/system.fidl

Error codes for responses from AddExecutionStateDependency in fuchsia.power.system/CpuElementManager.

Name	Value	Description
INVALID_ARGS	`1`	Required arguments are either not given or are not valid.
BAD_STATE	`2`	The server is not in a state to handle the request.

ApplicationActivityLevel flexible

Type: uint8

Defined in fuchsia.power.system/system.fidl

Application activity power levels

Elements that need to keep the system from suspending should take an assertive dependency on ApplicationActivityLevel::ACTIVE. When these components are performing work, they should request a lease to ensure the system remains active, and drop the lease when they are done.

Name	Value	Description
INACTIVE	`0`
ACTIVE	`1`

CpuLevel flexible

Type: uint8

Defined in fuchsia.power.system/system.fidl

CPU power levels

Elements should take an assertive dependency on CpuLevel::ACTIVE to ensure that the element will be suspended before the CPU suspends.

Name	Value	Description
INACTIVE	`0`
ACTIVE	`1`

ExecutionStateLevel flexible

Type: uint8

Defined in fuchsia.power.system/system.fidl

Execution state power levels

Elements should take an opportunistic dependency on ExecutionStateLevel::ACTIVE to ensure that the element will be suspended when the rest of the system suspends.

Drivers can take an opportunistic dependency on either ExecutionStateLevel::SUSPENDING or ExecutionStateLevel::ACTIVE and request a persistent lease on this state to ensure that their element's power level is always activated when the system comes out of a suspend state.

Name	Value	Description
INACTIVE	`0`
SUSPENDING	`1`
ACTIVE	`2`

WakeHandlingLevel flexible

Type: uint8

Defined in fuchsia.power.system/system.fidl

Wake handling power levels

Driver power elements should take an assertive dependency on WakeHandlingLevel::ACTIVE if it does NOT expect the system to perform a full wakeup. While the drivers are handling a wake event, they should request a lease to pull the state to Active, and drop the release once the event is fully handled.

Name	Value	Description
INACTIVE	`0`
ACTIVE	`1`

TABLES

ActivityGovernorRegisterListenerRequest resource

Defined in fuchsia.power.system/system.fidl

Ordinal Field Type Description

Ordinal	Field	Type	Description
1	`listener`	`client_end:ActivityGovernorListener`	The client end of the service that receives activity governor events. Required.

1

listener

client_end:ActivityGovernorListener

The client end of the service that receives activity governor events.

Required.

ApplicationActivity resource

Defined in fuchsia.power.system/system.fidl

Holds tokens to the application activity power element.

fuchsia.power.system/ApplicationActivityLevel defines the power levels supported by this power element.

Ordinal	Field	Type	Description
1	`assertive_dependency_token`	`fuchsia.power.broker/DependencyToken`

Cpu resource

Defined in fuchsia.power.system/system.fidl

Holds tokens to the CPU power element.

fuchsia.power.system/CpuLevel defines the power levels supported by this power element.

Ordinal	Field	Type	Description
1	`assertive_dependency_token`	`fuchsia.power.broker/DependencyToken`

CpuElementManagerAddExecutionStateDependencyRequest resource

Defined in fuchsia.power.system/system.fidl

Ordinal	Field	Type	Description
1	`dependency_token`	`fuchsia.power.broker/DependencyToken`	The assertive dependency token representing the target power element of the dependency. Required.
2	`power_level`	`fuchsia.power.broker/PowerLevel`	The power level of the target power element. Required.

ExecutionState resource

Defined in fuchsia.power.system/system.fidl

Holds a token to the execution state power element.

Power elements intentionally cannot take assertive dependencies on this power element. Elements that need to force the execution state to ACTIVE can use ApplicationActivity which provides more semantic meaning to the dependencies.

fuchsia.power.system/ExecutionStateLevel defines the power levels supported by this power element.

Ordinal	Field	Type	Description
1	`opportunistic_dependency_token`	`fuchsia.power.broker/DependencyToken`

PowerElements resource

Defined in fuchsia.power.system/system.fidl

A collection of power elements that are managed by the activity governor.

Ordinal	Field	Type
1	`execution_state`	`ExecutionState`
3	`application_activity`	`ApplicationActivity`
4	`wake_handling`	`WakeHandling`

WakeHandling resource

Defined in fuchsia.power.system/system.fidl

Holds tokens to the wake handling power element.

fuchsia.power.system/WakeHandlingLevel defines the power levels supported by this power element.

Ordinal	Field	Type	Description
1	`assertive_dependency_token`	`fuchsia.power.broker/DependencyToken`

UNIONS

ActivityGovernorListener_OnSuspendFail_Result strict

Defined in fuchsia.power.system/system.fidl

Ordinal	Variant	Type	Description
1	`response`	`ActivityGovernorListener_OnSuspendFail_Response`
3	`framework_err`	`internal`

ActivityGovernorListener_OnSuspendStarted_Result strict

Defined in fuchsia.power.system/system.fidl

Ordinal	Variant	Type	Description
1	`response`	`ActivityGovernorListener_OnSuspendStarted_Response`
3	`framework_err`	`internal`

ActivityGovernor_GetPowerElements_Result strict resource

Defined in fuchsia.power.system/system.fidl

Ordinal	Variant	Type	Description
1	`response`	`PowerElements`
3	`framework_err`	`internal`

ActivityGovernor_RegisterListener_Result strict

Defined in fuchsia.power.system/system.fidl

Ordinal	Variant	Type	Description
1	`response`	`ActivityGovernor_RegisterListener_Response`
3	`framework_err`	`internal`

ActivityGovernor_TakeApplicationActivityLease_Result strict resource

Defined in fuchsia.power.system/system.fidl

Ordinal	Variant	Type	Description
1	`response`	`ActivityGovernor_TakeApplicationActivityLease_Response`
3	`framework_err`	`internal`

ActivityGovernor_TakeWakeLease_Result strict resource

Defined in fuchsia.power.system/system.fidl

Ordinal	Variant	Type	Description
1	`response`	`ActivityGovernor_TakeWakeLease_Response`
3	`framework_err`	`internal`

CpuElementManager_AddExecutionStateDependency_Result strict

Defined in fuchsia.power.system/system.fidl

Ordinal	Variant	Type
1	`response`	`CpuElementManager_AddExecutionStateDependency_Response`
2	`err`	`AddExecutionStateDependencyError`
3	`framework_err`	`internal`

CpuElementManager_GetCpuDependencyToken_Result strict resource

Defined in fuchsia.power.system/system.fidl

Ordinal	Variant	Type	Description
1	`response`	`Cpu`
3	`framework_err`	`internal`

ALIASES

Name	Value	Description
LeaseToken	`zx/Handle`

fuchsia.power.system

Internal Dependency Diagram

Usage

PROTOCOLS

ActivityGovernor

GetPowerElements

Request

Response

RegisterListener

Request

Response

TakeApplicationActivityLease

Request

Response

TakeWakeLease

Request

Response

ActivityGovernorListener

OnResume

Request

Response

OnSuspendFail

Request

Response

OnSuspendStarted

Request

Response

CpuElementManager

AddExecutionStateDependency

Request

Response

GetCpuDependencyToken

Request

Response

STRUCTS

ActivityGovernorListener_OnSuspendFail_Response

ActivityGovernorListener_OnSuspendStarted_Response

ActivityGovernor_RegisterListener_Response

ActivityGovernor_TakeApplicationActivityLease_Response resource

ActivityGovernor_TakeWakeLease_Response resource

CpuElementManager_AddExecutionStateDependency_Response

ENUMS

AddExecutionStateDependencyError flexible

INVALID_ARGS

BAD_STATE

ApplicationActivityLevel flexible

INACTIVE

ACTIVE

CpuLevel flexible

INACTIVE

ACTIVE

ExecutionStateLevel flexible

INACTIVE

SUSPENDING

ACTIVE

WakeHandlingLevel flexible

INACTIVE

ACTIVE

TABLES

ActivityGovernorRegisterListenerRequest resource

1

ApplicationActivity resource

1

Cpu resource

1

CpuElementManagerAddExecutionStateDependencyRequest resource

1

2

ExecutionState resource

1

PowerElements resource

1

3

4

WakeHandling resource

1

UNIONS

ActivityGovernorListener_OnSuspendFail_Result strict

1

3