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      |
|              +--------------------+
|
|    +---------------------------------+
|    |             **CPU**             |
|    +---------------------------------+
+--->|             ACTIVE              |
     +---------------------------------+
     |            INACTIVE             |
     +---------------------------------+

Usage

To prevent system suspension, a component can create an assertive dependency using the assertive_dependency_token from ApplicationActivity. If the dependency causes the power level of ApplicationActivity to be raised to fuchsia.power.system/ApplicationActivityPowerLevel.ACTIVE, 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: 26

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.).

Added: 26

AcquireWakeLease

Creates a lease that blocks suspension of the hardware platform.

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

Added: 26

Request

NameType
name string:64

Response

NameType
payload ActivityGovernor_AcquireWakeLease_Result

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.

Added: HEAD

Request

<EMPTY>

Response

NameType
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.

Added: HEAD

Request

NameType
payload ActivityGovernorRegisterListenerRequest

Response

NameType
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.

This method is not safe to call during ActivityGovernorListener.OnSuspendStarted.

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.

Added: HEAD

Request

NameType
name string:64

Response

NameType
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.

DEPRECATED - Use AcquireWakeLease instead

Added: HEAD
#### Request {:#ActivityGovernor.TakeWakeLease_Request transformation="converted"}
NameType
name string:64
#### Response {:#ActivityGovernor.TakeWakeLease_Response transformation="converted"}
NameType
payload ActivityGovernor_TakeWakeLease_Result
## ActivityGovernorListener {:#ActivityGovernorListener transformation="converted"} *Defined in [fuchsia.power.system/system.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.power.system/system.fidl;l=166)*

A listener for activity governor events.

Added: HEAD

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. All dependencies of ExecutionStateLevel::SUSPENDING are guaranteed to be satisified when this call is issued, and the listener's OnSuspendStarted method will be invoked before that guarantee is removed.

SAG does not block on the response to this method, so the listener may safely take actions that block on raising Execution State's power level. In particular, it is not affected by https://fxbug.dev/391429689.

Request

<EMPTY>

Response

<EMPTY>

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. All dependencies of ExecutionStateLevel::SUSPENDING are guaranteed to be satisified for the duration of this call.

It is not safe for this method to call ActivityGovernor.TakeApplicationActivityLease or to perform any other action that blocks on raising Execution State above its Inactive level. (However, AcquireWakeLease does not block in this way and is safe to call.) Doing so will currently result in a deadlock. This constraint will eventually be removed; see https://fxbug.dev/391429689.

Request

<EMPTY>

Response

NameType
payload ActivityGovernorListener_OnSuspendStarted_Result

BootControl

Defined in fuchsia.power.system/system.fidl

A service that processes notification about the system boot state.

SetBootComplete

Notify the SAG that the system has booted. SAG will not suspend the hardware platform until this method is called at least once per boot.

Request

<EMPTY>

Response

NameType
payload BootControl_SetBootComplete_Result

CpuElementManager

Defined in fuchsia.power.system/system.fidl

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

Added: HEAD

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

NameType
payload CpuElementManagerAddExecutionStateDependencyRequest

Response

NameType
payload CpuElementManager_AddExecutionStateDependency_Result

GetCpuDependencyToken

Gets the assertive dependency token for the CPU power element.

Request

<EMPTY>

Response

NameType
payload CpuElementManager_GetCpuDependencyToken_Result

STRUCTS

ActivityGovernorListener_OnSuspendStarted_Response

Defined in fuchsia.power.system/system.fidl

<EMPTY>

ActivityGovernor_AcquireWakeLease_Response resource

Defined in fuchsia.power.system/system.fidl

FieldTypeDescriptionDefault
token LeaseToken

The token that blocks hardware platform suspension.

 No default

ActivityGovernor_RegisterListener_Response

Defined in fuchsia.power.system/system.fidl

<EMPTY>

ActivityGovernor_TakeApplicationActivityLease_Response resource

Defined in fuchsia.power.system/system.fidl

FieldTypeDescriptionDefault
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

FieldTypeDescriptionDefault
token LeaseToken

The token that blocks hardware platform suspension.

 No default

BootControl_SetBootComplete_Response

Defined in fuchsia.power.system/system.fidl

<EMPTY>

CpuElementManager_AddExecutionStateDependency_Response

Defined in fuchsia.power.system/system.fidl

<EMPTY>

ENUMS

AcquireWakeLeaseError flexible

Type: uint32

Defined in fuchsia.power.system/system.fidl

Errors returned by ActivityGovernor/AcquireWakeLease.

Added: 26

NameValueDescription
1

The service encountered an error while attempting to issue a wake lease.
2

The name for the wake lease is empty or invalid.

AddExecutionStateDependencyError flexible

Type: uint32

Defined in fuchsia.power.system/system.fidl

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

Added: HEAD

NameValueDescription
1

Required arguments are either not given or are not valid.
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.

Added: HEAD

NameValueDescription
0
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.

Added: HEAD

NameValueDescription
0
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.

Added: HEAD

NameValueDescription
0
1
2

TABLES

ActivityGovernorRegisterListenerRequest resource

Defined in fuchsia.power.system/system.fidl

OrdinalFieldTypeDescription
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.

Added: HEAD

OrdinalFieldTypeDescription
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.

Added: HEAD

OrdinalFieldTypeDescription
assertive_dependency_token fuchsia.power.broker/DependencyToken

CpuElementManagerAddExecutionStateDependencyRequest resource

Defined in fuchsia.power.system/system.fidl

OrdinalFieldTypeDescription
dependency_token fuchsia.power.broker/DependencyToken

The assertive dependency token representing the target power element of the dependency. Required.
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.

Added: HEAD

OrdinalFieldTypeDescription
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.

Added: HEAD

OrdinalFieldTypeDescription
execution_state ExecutionState
application_activity ApplicationActivity

UNIONS

ActivityGovernorListener_OnSuspendStarted_Result strict

Defined in fuchsia.power.system/system.fidl

OrdinalVariantTypeDescription
response ActivityGovernorListener_OnSuspendStarted_Response
framework_err internal

ActivityGovernor_AcquireWakeLease_Result strict resource

Defined in fuchsia.power.system/system.fidl

OrdinalVariantTypeDescription
response ActivityGovernor_AcquireWakeLease_Response
err AcquireWakeLeaseError
framework_err internal

ActivityGovernor_GetPowerElements_Result strict resource

Defined in fuchsia.power.system/system.fidl

OrdinalVariantTypeDescription
response PowerElements
framework_err internal

ActivityGovernor_RegisterListener_Result strict

Defined in fuchsia.power.system/system.fidl

OrdinalVariantTypeDescription
response ActivityGovernor_RegisterListener_Response
framework_err internal

ActivityGovernor_TakeApplicationActivityLease_Result strict resource

Defined in fuchsia.power.system/system.fidl

OrdinalVariantTypeDescription
response ActivityGovernor_TakeApplicationActivityLease_Response
framework_err internal

ActivityGovernor_TakeWakeLease_Result strict resource

Defined in fuchsia.power.system/system.fidl

OrdinalVariantTypeDescription
response ActivityGovernor_TakeWakeLease_Response
framework_err internal

BootControl_SetBootComplete_Result strict

Defined in fuchsia.power.system/system.fidl

OrdinalVariantTypeDescription
response BootControl_SetBootComplete_Response
framework_err internal

CpuElementManager_AddExecutionStateDependency_Result strict

Defined in fuchsia.power.system/system.fidl

OrdinalVariantTypeDescription
response CpuElementManager_AddExecutionStateDependency_Response
err AddExecutionStateDependencyError
framework_err internal

CpuElementManager_GetCpuDependencyToken_Result strict resource

Defined in fuchsia.power.system/system.fidl

OrdinalVariantTypeDescription
response Cpu
framework_err internal

CONSTANTS

NameValueTypeDescription
MAX_ELEMENT_NAME_LEN 64 uint8
Added: 26

ALIASES

NameValueDescription
LeaseToken zx/Handle
Added: 26