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             |
                             |          +---------------------------------+
                             |
                             |          +---------------------------------+
                             |          |       **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

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`

TakeWakeLease

Creates a lease that blocks suspension of the hardware platform.

The hardware platform will not suspend as long as a valid WakeLeaseToken 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`

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_TakeWakeLease_Response resource

Defined in fuchsia.power.system/system.fidl

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

ENUMS

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`

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`

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.

Name	Value	Description
INACTIVE	`0`
ACTIVE	`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.

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`	`ActivityGovernorListener`	The client end of the service that receives activity governor events. Required.

1

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.

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

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.

Ordinal	Field	Type
1	`opportunistic_dependency_token`	`fuchsia.power.broker/DependencyToken`
2	`assertive_dependency_token`	`fuchsia.power.broker/DependencyToken`
3	`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.

Ordinal	Field	Type	Description
1	`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.

Ordinal	Field	Type	Description
1	`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.

Ordinal	Field	Type
1	`execution_state`	`ExecutionState`
2	`execution_resume_latency`	`ExecutionResumeLatency`
3	`application_activity`	`ApplicationActivity`
4	`full_wake_handling`	`FullWakeHandling`
5	`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_TakeWakeLease_Result strict resource

Defined in fuchsia.power.system/system.fidl

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

ALIASES

Name	Value	Description
WakeLeaseToken	`zx/Handle`

fuchsia.power.system

Internal Dependency Diagram

Usage

PROTOCOLS

ActivityGovernor

GetPowerElements

Request

Response

RegisterListener

Request

Response

TakeWakeLease

Request

Response

ActivityGovernorListener

OnResume

Request

Response

OnSuspendFail

Request

Response

OnSuspendStarted

Request

Response

STRUCTS

ActivityGovernorListener_OnSuspendFail_Response

ActivityGovernorListener_OnSuspendStarted_Response

ActivityGovernor_RegisterListener_Response

ActivityGovernor_TakeWakeLease_Response resource

ENUMS

ApplicationActivityLevel flexible

INACTIVE

ACTIVE

ExecutionStateLevel flexible

INACTIVE

SUSPENDING

ACTIVE

FullWakeHandlingLevel flexible

INACTIVE

ACTIVE

WakeHandlingLevel flexible

INACTIVE

ACTIVE

TABLES

ActivityGovernorRegisterListenerRequest resource

1

ApplicationActivity resource

1

ExecutionResumeLatency resource

1

2

3

ExecutionState resource

1

FullWakeHandling resource

1

PowerElements resource

1

2

3

4

5

WakeHandling resource

1

UNIONS

ActivityGovernorListener_OnSuspendFail_Result strict

1

3

ActivityGovernorListener_OnSuspendStarted_Result strict

1

3

ActivityGovernor_GetPowerElements_Result strict resource

1

3

ActivityGovernor_RegisterListener_Result strict

1

3

ActivityGovernor_TakeWakeLease_Result strict resource

1

3