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 and/or changing the platform resume latency for the next 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             |    |
     +---------------------------------+    |
                                            |          +---------------------------------+
                                            |          |       **FullWakeHandling**      |
                                            |          +---------------------------------+
                                            +----------|             ACTIVE              |
                                                       +---------------------------------+
                                                       |            INACTIVE             |
                                                       +---------------------------------+

+---------------------------------+
|   **ExecutionResumeLatency**    |
+---------------------------------+
|         SUSPEND_STATE_N         |
+---------------------------------+
|               ...               |
+---------------------------------+
|         SUSPEND_STATE_1         |
+---------------------------------+
|         SUSPEND_STATE_0         |
+---------------------------------+

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.

To change the platform resume latency, a component can create an assertive dependency using the assertive_dependency_token from ExecutionResumeLatency. If the dependency causes the power level of ExecutionResumeLatency to be raised, SAG will request a suspend state with an appropriate resume latency for that power level.

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 and resume-from-suspend latency 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

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.

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.

Note that when this lease is acquired for the first time, SAG will exit the "booting" stage and begin enforcing the suspend power policy.

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

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.

Request

NameType
name string[64]

Response

NameType
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

NameType
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

NameType
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

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_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

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

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.

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.

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.

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.

NameValueDescription
0
1
2

FullWakeHandlingLevel flexible

Type: uint8

Defined in fuchsia.power.system/system.fidl

Full wake handling power levels

Driver power elements should take an assertive dependency on FullWakeHandlingLevel::ACTIVE if it expects 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.

NameValueDescription
0
1

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.

NameValueDescription
0
1

TABLES

ActivityGovernorRegisterListenerRequest resource

Defined in fuchsia.power.system/system.fidl

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

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.

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.

ExecutionResumeLatency resource

Defined in fuchsia.power.system/system.fidl

Holds tokens to the execution resume latency power element and its supported resume latencies.

The execution resume latency power element represents the suspension-to-resume delay that must be met by the hardware platform.

The execution resume latency power element's power levels are platform and hardware dependent. The power levels supported by the power element match the index of the resume latency in the table, i.e. The item at index 0 in resume_latencies is represented by power level 0, the item at index 1 is represented by power level 1, and so on.

OrdinalFieldTypeDescription
opportunistic_dependency_token fuchsia.power.broker/DependencyToken
assertive_dependency_token fuchsia.power.broker/DependencyToken
resume_latencies vector<int64>

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.

OrdinalFieldTypeDescription
opportunistic_dependency_token fuchsia.power.broker/DependencyToken

FullWakeHandling resource

Defined in fuchsia.power.system/system.fidl

Holds tokens to the full wake handling power element.

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

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

OrdinalFieldTypeDescription
execution_state ExecutionState
execution_resume_latency ExecutionResumeLatency
application_activity ApplicationActivity
full_wake_handling FullWakeHandling
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.

OrdinalFieldTypeDescription
assertive_dependency_token fuchsia.power.broker/DependencyToken

UNIONS

ActivityGovernorListener_OnSuspendFail_Result strict

Defined in fuchsia.power.system/system.fidl

OrdinalVariantTypeDescription
response ActivityGovernorListener_OnSuspendFail_Response
framework_err internal

ActivityGovernorListener_OnSuspendStarted_Result strict

Defined in fuchsia.power.system/system.fidl

OrdinalVariantTypeDescription
response ActivityGovernorListener_OnSuspendStarted_Response
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

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

ALIASES

NameValueDescription
LeaseToken zx/Handle