States

System Power Management States. More...

Data Structures
struct	pm_state_info
	Information about a power management state. More...
struct	pm_state_constraint
	Information needed to be able to reference a power state as a constraint on some device or system functions. More...
struct	pm_state_constraints
	Collection of multiple power state constraints. 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)
	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.
#define	PM_STATE_CONSTRAINT_INIT(node_id)
	initialize a device pm constraint with information from devicetree.
#define	PM_STATE_CONSTRAINTS_LIST_DEFINE(node_id, prop)
	Define a list of power state constraints from devicetree.
#define	PM_STATE_CONSTRAINTS_GET(node_id, prop)
	Get power state constraints structure from devicetree.

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.
const struct pm_state_info *	pm_state_get (uint8_t cpu, enum pm_state state, uint8_t substate_id)
	Get power state structure.
const char *	pm_state_to_str (enum pm_state state)
	Convert a pm_state enum value to its string representation.
int	pm_state_from_str (const char *name, enum pm_state *out)
	Parse a string and convert it to a pm_state enum value.
bool	pm_state_in_constraints (const struct pm_state_constraints *constraints, const struct pm_state_constraint match)
	Check if a power management constraint matches any in a set of constraints.

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

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

Parameters

node_id

A CPU node identifier.

Returns

Number of supported and enabled CPU power states.

PM_STATE_CONSTRAINT_INIT

#define PM_STATE_CONSTRAINT_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),           \
        }

initialize a device pm constraint with information from devicetree.

Parameters

node_id

Node identifier.

PM_STATE_CONSTRAINTS_GET

#define PM_STATE_CONSTRAINTS_GET	(		node_id,
			prop )

#include <zephyr/pm/state.h>

Value:

        {                                                                                  \
                .list = Z_PM_STATE_CONSTRAINTS_LIST_NAME(node_id, prop),                   \
                .count = DT_PROP_LEN(node_id, prop),                                       \
        }

Get power state constraints structure from devicetree.

This macro creates a structure containing a pointer to the constraints list and the count of constraints, suitable for initializing a pm_state_constraints structure. Must be used after the PM_STATE_CONSTRAINTS_LIST_DEFINE call for the same

Parameters

prop	to refer to the array of constraints.
node_id	Devicetree node identifier.
prop	Property name containing the list of power state phandles.

PM_STATE_CONSTRAINTS_LIST_DEFINE

#define PM_STATE_CONSTRAINTS_LIST_DEFINE	(		node_id,
			prop )

#include <zephyr/pm/state.h>

Value:

        struct pm_state_constraint Z_PM_STATE_CONSTRAINTS_LIST_NAME(node_id, prop)[] =     \
        {                                                                                  \
                DT_FOREACH_PROP_ELEM_SEP(node_id, prop, Z_PM_STATE_CONSTRAINT_REF, (,))    \
        }

Define a list of power state constraints from devicetree.

This macro creates an array of pm_state_constraint structures initialized with power state information from the specified devicetree property.

Parameters

node_id	Devicetree node identifier.
prop	Property name containing the list of power state phandles.

PM_STATE_DT_INIT

#define PM_STATE_DT_INIT

(

node_id

)

#include <zephyr/pm/state.h>

Value:

        DT_ENUM_IDX(node_id, power_state_name)

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

Parameters

node_id

A 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),    \
        }

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

Parameters

node_id

A 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)              \
        }

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

Parameters

node_id

A 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));

Parameters

node_id

A 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

cpu	CPU index.
states	Where to store the list of supported states.

Returns

Number of supported states.

pm_state_from_str()

int pm_state_from_str	(	const char *	name,
		enum pm_state *	out )

#include <zephyr/pm/state.h>

Parse a string and convert it to a pm_state enum value.

Parameters

name	Input string (e.g., "suspend-to-ram").
out	Pointer to store the parsed pm_state value.

Returns

0 on success, -EINVAL if the string is invalid or NULL.

pm_state_get()

const struct pm_state_info * pm_state_get	(	uint8_t	cpu,
		enum pm_state	state,
		uint8_t	substate_id )

#include <zephyr/pm/state.h>

Get power state structure.

Function searches in all states assigned to the CPU and in disabled states.

Parameters

cpu	CPU index.
state	Power state.
substate_id	Substate.

Returns

Pointer to the power state structure or NULL if state is not found.

pm_state_in_constraints()

bool pm_state_in_constraints	(	const struct pm_state_constraints *	constraints,
		const struct pm_state_constraint	match )

#include <zephyr/pm/state.h>

Check if a power management constraint matches any in a set of constraints.

Parameters

constraints	Pointer to the power state constraints structure.
match	The constraint to match against.

Returns

true if the constraint matches, false otherwise.

pm_state_to_str()

const char * pm_state_to_str

(

enum pm_state

state

)

#include <zephyr/pm/state.h>

Convert a pm_state enum value to its string representation.

Parameters

state

Power state.

Returns

A constant string representing the state.