Zephyr API Documentation  3.7.0
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
Data Structures | Macros | Enumerations | Functions
States
Operating System Services » Power Management (PM)

System Power Management States. More...

Data Structures

struct  pm_state_info
 Information about a power management state. More...
 
struct  pm_state_constraint
 Power state information needed to lock a power state. More...
 

Macros

#define PM_STATE_INFO_DT_INIT(node_id)
 Initializer for struct pm_state_info given a DT node identifier with zephyr,power-state compatible.
 
#define PM_STATE_DT_INIT(node_id)    DT_ENUM_IDX(node_id, power_state_name)
 Initializer for enum pm_state given a DT node identifier with zephyr,power-state compatible.
 
#define DT_NUM_CPU_POWER_STATES(node_id)
 Obtain number of CPU power states supported and enabled by the given CPU node identifier.
 
#define PM_STATE_INFO_LIST_FROM_DT_CPU(node_id)
 Initialize an array of struct pm_state_info with information from all the states present and enabled in the given CPU node identifier.
 
#define PM_STATE_LIST_FROM_DT_CPU(node_id)
 Initialize an array of struct pm_state with information from all the states present and enabled in the given CPU node identifier.
 

Enumerations

enum  pm_state {
  PM_STATE_ACTIVE , PM_STATE_RUNTIME_IDLE , PM_STATE_SUSPEND_TO_IDLE , PM_STATE_STANDBY ,
  PM_STATE_SUSPEND_TO_RAM , PM_STATE_SUSPEND_TO_DISK , PM_STATE_SOFT_OFF , PM_STATE_COUNT
}
 Power management state. More...
 

Functions

uint8_t pm_state_cpu_get_all (uint8_t cpu, const struct pm_state_info **states)
 Obtain information about all supported states by a CPU.
 

Detailed Description

System Power Management States.

Macro Definition Documentation

◆ DT_NUM_CPU_POWER_STATES

#define DT_NUM_CPU_POWER_STATES (   node_id)

#include <zephyr/pm/state.h>

Value:
COND_CODE_1(DT_NODE_HAS_PROP(node_id, cpu_power_states), \
(DT_FOREACH_PROP_ELEM_SEP(node_id, cpu_power_states, Z_DT_PHANDLE_01, (+))), \
(0))
DT_NODE_HAS_PROP
#define DT_NODE_HAS_PROP(node_id, prop)
Does a devicetree node have a property?
Definition: devicetree.h:3479
DT_FOREACH_PROP_ELEM_SEP
#define DT_FOREACH_PROP_ELEM_SEP(node_id, prop, fn, sep)
Invokes fn for each element in the value of property prop with separator.
Definition: devicetree.h:3103
COND_CODE_1
#define COND_CODE_1(_flag, _if_1_code, _else_code)
Insert code depending on whether _flag expands to 1 or not.
Definition: util_macro.h:179

Obtain number of CPU power states supported and enabled by the given CPU node identifier.

Parameters
node_idA CPU node identifier.
Returns
Number of supported and enabled CPU power states.

◆ PM_STATE_DT_INIT

#define PM_STATE_DT_INIT (   node_id)     DT_ENUM_IDX(node_id, power_state_name)

#include <zephyr/pm/state.h>

Initializer for enum pm_state given a DT node identifier with zephyr,power-state compatible.

Parameters
node_idA node identifier with compatible zephyr,power-state

◆ PM_STATE_INFO_DT_INIT

#define PM_STATE_INFO_DT_INIT (   node_id)

#include <zephyr/pm/state.h>

Value:
{ \
.state = PM_STATE_DT_INIT(node_id), \
.substate_id = DT_PROP_OR(node_id, substate_id, 0), \
.min_residency_us = DT_PROP_OR(node_id, min_residency_us, 0), \
.exit_latency_us = DT_PROP_OR(node_id, exit_latency_us, 0), \
.pm_device_disabled = DT_PROP(node_id, zephyr_pm_device_disabled), \
}
DT_PROP_OR
#define DT_PROP_OR(node_id, prop, default_value)
Like DT_PROP(), but with a fallback to default_value.
Definition: devicetree.h:825
DT_PROP
#define DT_PROP(node_id, prop)
Get a devicetree property value.
Definition: devicetree.h:663
PM_STATE_DT_INIT
#define PM_STATE_DT_INIT(node_id)
Initializer for enum pm_state given a DT node identifier with zephyr,power-state compatible.
Definition: state.h:249

Initializer for struct pm_state_info given a DT node identifier with zephyr,power-state compatible.

Parameters
node_idA node identifier with compatible zephyr,power-state

◆ PM_STATE_INFO_LIST_FROM_DT_CPU

#define PM_STATE_INFO_LIST_FROM_DT_CPU (   node_id)

#include <zephyr/pm/state.h>

Value:
{ \
LISTIFY(DT_PROP_LEN_OR(node_id, cpu_power_states, 0), \
Z_PM_STATE_INFO_FROM_DT_CPU, (), node_id) \
}
DT_PROP_LEN_OR
#define DT_PROP_LEN_OR(node_id, prop, default_value)
Like DT_PROP_LEN(), but with a fallback to default_value.
Definition: devicetree.h:713

Initialize an array of struct pm_state_info with information from all the states present and enabled in the given CPU node identifier.

Example devicetree fragment:

cpus {
...
cpu0: cpu@0 {
device_type = "cpu";
...
cpu-power-states = <&state0 &state1>;
};
power-states {
state0: state0 {
compatible = "zephyr,power-state";
power-state-name = "suspend-to-idle";
min-residency-us = <10000>;
exit-latency-us = <100>;
};
state1: state1 {
compatible = "zephyr,power-state";
power-state-name = "suspend-to-ram";
min-residency-us = <50000>;
exit-latency-us = <500>;
zephyr,pm-device-disabled;
};
};
};

Example usage:

const struct pm_state_info states[] =
PM_STATE_INFO_LIST_FROM_DT_CPU(DT_NODELABEL(cpu0));
DT_NODELABEL
#define DT_NODELABEL(label)
Get a node identifier for a node label.
Definition: devicetree.h:200
PM_STATE_INFO_LIST_FROM_DT_CPU
#define PM_STATE_INFO_LIST_FROM_DT_CPU(node_id)
Initialize an array of struct pm_state_info with information from all the states present and enabled ...
Definition: state.h:308
pm_state_info
Information about a power management state.
Definition: state.h:114
Parameters
node_idA CPU node identifier.

◆ PM_STATE_LIST_FROM_DT_CPU

#define PM_STATE_LIST_FROM_DT_CPU (   node_id)

#include <zephyr/pm/state.h>

Value:
{ \
LISTIFY(DT_PROP_LEN_OR(node_id, cpu_power_states, 0), \
Z_PM_STATE_FROM_DT_CPU, (), node_id) \
}

Initialize an array of struct pm_state with information from all the states present and enabled in the given CPU node identifier.

Example devicetree fragment:

cpus {
...
cpu0: cpu@0 {
device_type = "cpu";
...
cpu-power-states = <&state0 &state1>;
};
power-states {
state0: state0 {
compatible = "zephyr,power-state";
power-state-name = "suspend-to-idle";
min-residency-us = <10000>;
exit-latency-us = <100>;
};
state1: state1 {
compatible = "zephyr,power-state";
power-state-name = "suspend-to-ram";
min-residency-us = <50000>;
exit-latency-us = <500>;
};
};
};

Example usage:

const enum pm_state states[] = PM_STATE_LIST_FROM_DT_CPU(DT_NODELABEL(cpu0));
pm_state
pm_state
Power management state.
Definition: state.h:27
PM_STATE_LIST_FROM_DT_CPU
#define PM_STATE_LIST_FROM_DT_CPU(node_id)
Initialize an array of struct pm_state with information from all the states present and enabled in th...
Definition: state.h:355
Parameters
node_idA CPU node identifier.

Enumeration Type Documentation

◆ pm_state

enum pm_state

#include <zephyr/pm/state.h>

Power management state.

Enumerator
PM_STATE_ACTIVE 

Runtime active state.

The system is fully powered and active.

Note
This state is correlated with ACPI G0/S0 state
PM_STATE_RUNTIME_IDLE 

Runtime idle state.

Runtime idle is a system sleep state in which all of the cores enter deepest possible idle state and wait for interrupts, no requirements for the devices, leaving them at the states where they are.

Note
This state is correlated with ACPI S0ix state
PM_STATE_SUSPEND_TO_IDLE 

Suspend to idle state.

The system goes through a normal platform suspend where it puts all of the cores in deepest possible idle state and may puts peripherals into low-power states. No operating state is lost (ie. the cpu core does not lose execution context), so the system can go back to where it left off easily enough.

Note
This state is correlated with ACPI S1 state
PM_STATE_STANDBY 

Standby state.

In addition to putting peripherals into low-power states all non-boot CPUs are powered off. It should allow more energy to be saved relative to suspend to idle, but the resume latency will generally be greater than for that state. But it should be the same state with suspend to idle state on uniprocessor system.

Note
This state is correlated with ACPI S2 state
PM_STATE_SUSPEND_TO_RAM 

Suspend to ram state.

This state offers significant energy savings by powering off as much of the system as possible, where memory should be placed into the self-refresh mode to retain its contents. The state of devices and CPUs is saved and held in memory, and it may require some boot- strapping code in ROM to resume the system from it.

Note
This state is correlated with ACPI S3 state
PM_STATE_SUSPEND_TO_DISK 

Suspend to disk state.

This state offers significant energy savings by powering off as much of the system as possible, including the memory. The contents of memory are written to disk or other non-volatile storage, and on resume it's read back into memory with the help of boot-strapping code, restores the system to the same point of execution where it went to suspend to disk.

Note
This state is correlated with ACPI S4 state
PM_STATE_SOFT_OFF 

Soft off state.

This state consumes a minimal amount of power and requires a large latency in order to return to runtime active state. The contents of system(CPU and memory) will not be preserved, so the system will be restarted as if from initial power-up and kernel boot.

Note
This state is correlated with ACPI G2/S5 state
PM_STATE_COUNT 

Number of power management states (internal use)

Function Documentation

◆ pm_state_cpu_get_all()

uint8_t pm_state_cpu_get_all ( uint8_t  cpu,
const struct pm_state_info **  states 
)

#include <zephyr/pm/state.h>

Obtain information about all supported states by a CPU.

Parameters
cpuCPU index.
statesWhere to store the list of supported states.
Returns
Number of supported states.