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:
- fuchsia.power.system/ExecutionState
- fuchsia.power.system/ExecutionResumeLatency
- fuchsia.power.system/WakeHandling
- fuchsia.power.system/FullWakeHandling
- fuchsia.power.system/ApplicationActivity
- fuchsia.power.system/Cpu
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.
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
|
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
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 |
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 |
---|---|---|---|
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
|
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. |
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 | Description |
---|---|---|---|
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 | Description |
---|---|---|---|
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_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 | Description |
---|---|---|---|
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 |