Device

Device Power Management API. More...

Data Structures
struct	pm_device_base
	Device PM info. More...
struct	pm_device
	Runtime PM info for device with generic PM. More...
struct	pm_device_isr
	Runtime PM info for device with synchronous PM. More...

Macros
#define	PM_DEVICE_ISR_SAFE   1
	Flag indicating that runtime PM API for the device can be called from any context.
#define	PM_DEVICE_DEFINE(dev_id, pm_action_cb, ...)
	Define device PM resources for the given device name.
#define	PM_DEVICE_DT_DEFINE(node_id, pm_action_cb, ...)
	Define device PM resources for the given node identifier.
#define	PM_DEVICE_DT_INST_DEFINE(idx, pm_action_cb, ...)
	Define device PM resources for the given instance.
#define	PM_DEVICE_GET(dev_id)
	Obtain a reference to the device PM resources for the given device.
#define	PM_DEVICE_DT_GET(node_id)
	Obtain a reference to the device PM resources for the given node.
#define	PM_DEVICE_DT_INST_GET(idx)
	Obtain a reference to the device PM resources for the given instance.

Typedefs
typedef int(*	pm_device_action_cb_t) (const struct device *dev, enum pm_device_action action)
	Device PM action callback.
typedef bool(*	pm_device_action_failed_cb_t) (const struct device *dev, int err)
	Device PM action failed callback.

Enumerations
enum	pm_device_state { PM_DEVICE_STATE_ACTIVE , PM_DEVICE_STATE_SUSPENDED , PM_DEVICE_STATE_SUSPENDING , PM_DEVICE_STATE_OFF }
	Device power states. More...
enum	pm_device_action { PM_DEVICE_ACTION_SUSPEND , PM_DEVICE_ACTION_RESUME , PM_DEVICE_ACTION_TURN_OFF , PM_DEVICE_ACTION_TURN_ON }
	Device PM actions. More...

Functions
const char *	pm_device_state_str (enum pm_device_state state)
	Get name of device PM state.
int	pm_device_action_run (const struct device *dev, enum pm_device_action action)
	Run a pm action on a device.
void	pm_device_children_action_run (const struct device *dev, enum pm_device_action action, pm_device_action_failed_cb_t failure_cb)
	Run a pm action on all children of a device.
int	pm_device_state_get (const struct device *dev, enum pm_device_state *state)
	Obtain the power state of a device.
static void	pm_device_init_suspended (const struct device *dev)
	Initialize a device state to PM_DEVICE_STATE_SUSPENDED.
static void	pm_device_init_off (const struct device *dev)
	Initialize a device state to PM_DEVICE_STATE_OFF.
void	pm_device_busy_set (const struct device *dev)
	Mark a device as busy.
void	pm_device_busy_clear (const struct device *dev)
	Clear a device busy status.
bool	pm_device_is_any_busy (void)
	Check if any device is busy.
bool	pm_device_is_busy (const struct device *dev)
	Check if a device is busy.
bool	pm_device_wakeup_enable (const struct device *dev, bool enable)
	Enable or disable a device as a wake up source.
bool	pm_device_wakeup_is_enabled (const struct device *dev)
	Check if a device is enabled as a wake up source.
bool	pm_device_wakeup_is_capable (const struct device *dev)
	Check if a device is wake up capable.
bool	pm_device_on_power_domain (const struct device *dev)
	Check if the device is on a switchable power domain.
int	pm_device_power_domain_add (const struct device *dev, const struct device *domain)
	Add a device to a power domain.
int	pm_device_power_domain_remove (const struct device *dev, const struct device *domain)
	Remove a device from a power domain.
bool	pm_device_is_powered (const struct device *dev)
	Check if the device is currently powered.
int	pm_device_driver_init (const struct device *dev, pm_device_action_cb_t action_cb)
	Move a device driver into its initial device power state.
int	pm_device_driver_deinit (const struct device *dev, pm_device_action_cb_t action_cb)
	Prepare PM device for device driver deinit.

Detailed Description

Device Power Management API.

Macro Definition Documentation

PM_DEVICE_DEFINE

#define PM_DEVICE_DEFINE	(		dev_id,
			pm_action_cb,
			... )

#include <zephyr/pm/device.h>

Value:

        Z_PM_DEVICE_DEFINE(DT_INVALID_NODE, dev_id, pm_action_cb,        \
                        COND_CODE_1(IS_EMPTY(__VA_ARGS__), (0), (__VA_ARGS__)))

Define device PM resources for the given device name.

Note

This macro is a no-op if CONFIG_PM_DEVICE is not enabled.

Parameters

dev_id	Device id.
pm_action_cb	PM control callback.
...	Optional flag to indicate that ISR safe. Use PM_DEVICE_ISR_SAFE or 0.

See also

PM_DEVICE_DT_DEFINE, PM_DEVICE_DT_INST_DEFINE

PM_DEVICE_DT_DEFINE

#define PM_DEVICE_DT_DEFINE	(		node_id,
			pm_action_cb,
			... )

#include <zephyr/pm/device.h>

Value:

        Z_PM_DEVICE_DEFINE(node_id, Z_DEVICE_DT_DEV_ID(node_id), pm_action_cb, \
                        COND_CODE_1(IS_EMPTY(__VA_ARGS__), (0), (__VA_ARGS__)))

Define device PM resources for the given node identifier.

Note

This macro is a no-op if CONFIG_PM_DEVICE is not enabled.

Parameters

node_id	Node identifier.
pm_action_cb	PM control callback.
...	Optional flag to indicate that device is isr_ok. Use PM_DEVICE_ISR_SAFE or 0.

See also

PM_DEVICE_DT_INST_DEFINE, PM_DEVICE_DEFINE

PM_DEVICE_DT_GET

#define PM_DEVICE_DT_GET

(

node_id

)

#include <zephyr/pm/device.h>

Value:

        PM_DEVICE_GET(Z_DEVICE_DT_DEV_ID(node_id))

Obtain a reference to the device PM resources for the given node.

Parameters

node_id

Node identifier.

Returns

Reference to the device PM resources (NULL if device CONFIG_PM_DEVICE is disabled).

PM_DEVICE_DT_INST_DEFINE

#define PM_DEVICE_DT_INST_DEFINE	(		idx,
			pm_action_cb,
			... )

#include <zephyr/pm/device.h>

Value:

        Z_PM_DEVICE_DEFINE(DT_DRV_INST(idx),                         \
                           Z_DEVICE_DT_DEV_ID(DT_DRV_INST(idx)),     \
                           pm_action_cb,                                \
                           COND_CODE_1(IS_EMPTY(__VA_ARGS__), (0), (__VA_ARGS__)))

Define device PM resources for the given instance.

Note

This macro is a no-op if CONFIG_PM_DEVICE is not enabled.

Parameters

idx	Instance index.
pm_action_cb	PM control callback.
...	Optional flag to indicate that device is isr_ok. Use PM_DEVICE_ISR_SAFE or 0.

See also

PM_DEVICE_DT_DEFINE, PM_DEVICE_DEFINE

PM_DEVICE_DT_INST_GET

#define PM_DEVICE_DT_INST_GET

(

idx

)

#include <zephyr/pm/device.h>

Value:

        PM_DEVICE_DT_GET(DT_DRV_INST(idx))

Obtain a reference to the device PM resources for the given instance.

Parameters

idx	Instance index.

Returns

Reference to the device PM resources (NULL if device CONFIG_PM_DEVICE is disabled).

PM_DEVICE_GET

#define PM_DEVICE_GET

(

dev_id

)

#include <zephyr/pm/device.h>

Value:

        Z_PM_DEVICE_GET(dev_id)

Obtain a reference to the device PM resources for the given device.

Parameters

dev_id

Device id.

Returns

Reference to the device PM resources (NULL if device CONFIG_PM_DEVICE is disabled).

PM_DEVICE_ISR_SAFE

#define PM_DEVICE_ISR_SAFE   1

#include <zephyr/pm/device.h>

Flag indicating that runtime PM API for the device can be called from any context.

If PM_DEVICE_ISR_SAFE flag is used for device definition, it indicates that PM actions are synchronous and can be executed from any context. This approach can be used for cases where suspending and resuming is short as it is executed in the critical section. This mode requires less resources (~80 byte less RAM) and allows to use device runtime PM from any context (including interrupts).

Typedef Documentation

pm_device_action_cb_t

typedef int(* pm_device_action_cb_t) (const struct device *dev, enum pm_device_action action)

#include <zephyr/pm/device.h>

Device PM action callback.

Parameters

dev	Device instance.
action	Requested action.

Return values

0	If successful.
-ENOTSUP	If the requested action is not supported.
Errno	Other negative errno on failure.

pm_device_action_failed_cb_t

typedef bool(* pm_device_action_failed_cb_t) (const struct device *dev, int err)

#include <zephyr/pm/device.h>

Device PM action failed callback.

Parameters

dev	Device that failed the action.
err	Return code of action failure.

Returns

True to continue iteration, false to halt iteration.

Enumeration Type Documentation

pm_device_action

enum pm_device_action

#include <zephyr/pm/device.h>

Device PM actions.

Enumerator
PM_DEVICE_ACTION_SUSPEND	Suspend.
PM_DEVICE_ACTION_RESUME	Resume.
PM_DEVICE_ACTION_TURN_OFF	Turn off. Note Action triggered only by a power domain.
PM_DEVICE_ACTION_TURN_ON	Turn on. Note Action triggered only by a power domain.

pm_device_state

enum pm_device_state

#include <zephyr/pm/device.h>

Device power states.

Enumerator
PM_DEVICE_STATE_ACTIVE	Device hardware is powered, and the device is needed by the system. The device should be enabled in this state. Any device driver API may be called in this state.
PM_DEVICE_STATE_SUSPENDED	Device hardware is powered, but the device is not needed by the system. The device should be put into its lowest internal power state, commonly named "disabled" or "stopped". If a device has been specified as this device's power domain, and said device is no longer needed by the system, this device will be transitioned into the PM_DEVICE_STATE_OFF state, followed by the power domain device being transitioned to the PM_DEVICE_STATE_SUSPENDED state. A device driver may be deinitialized in this state. Once the device driver has been deinitialized, we implicitly move to the PM_DEVICE_STATE_OFF state as the device hardware may lose power, with no device driver to respond to the corresponding PM_DEVICE_ACTION_TURN_OFF action. Note This state is NOT a "low-power"/"partially operable" state, those are configured using device driver specific APIs, and apply only while the device is in the PM_DEVICE_STATE_ACTIVE state.
PM_DEVICE_STATE_SUSPENDING	Device hardware is powered, but the device has been scheduled to be suspended, as it is no longer needed by the system. This state is used when delegating suspension of a device to the PM subsystem, optionally with residency to avoid unnecessary suspend/resume cycles, resulting from a call to pm_device_runtime_put_async. The device will be unscheduled in case the device becomes needed by the system. No device driver API calls must occur in this state. Note that this state is opaque to the device driver (no pm_device_action is called as this state is entered) and is used solely by PM_DEVICE_RUNTIME.
PM_DEVICE_STATE_OFF	Device hardware is not powered. This is the initial state from which a device driver is initialized. When a device driver is initialized, we do not know the state of the device. As a result, the PM_DEVICE_ACTION_TURN_ON action should be able to transition the device from any internal state into PM_DEVICE_STATE_SUSPENDED, since no guarantees can be made across resets. This is typically achieved through toggling a reset pin or triggering a software reset through a register write before performing any additional configuration needed to meet the requirements of PM_DEVICE_STATE_SUSPENDED. For devices where this is not possible, the device driver must presume the device is in either the PM_DEVICE_STATE_OFF or PM_DEVICE_STATE_SUSPENDED state at time of initialization, as these are the states within which device drivers may be deinitialized. If a device has been specified as this device's power domain, and said device becomes needed by the system, the power domain device will be transitioned into the PM_DEVICE_STATE_ACTIVE state, followed by this device being transitioned to the PM_DEVICE_STATE_SUSPENDED state.

Function Documentation

pm_device_action_run()

int pm_device_action_run	(	const struct device *	dev,
		enum pm_device_action	action )

#include <zephyr/pm/device.h>

Run a pm action on a device.

This function calls the device PM control callback so that the device does the necessary operations to execute the given action.

Parameters

dev	Device instance.
action	Device pm action.

Return values

0	If successful.
-ENOTSUP	If requested state is not supported.
-EALREADY	If device is already at the requested state.
-EBUSY	If device is changing its state.
-ENOSYS	If device does not support PM.
-EPERM	If device has power state locked.
Errno	Other negative errno on failure.

pm_device_busy_clear()

void pm_device_busy_clear

(

const struct device *

dev

)

#include <zephyr/pm/device.h>

Clear a device busy status.

Parameters

dev	Device instance.

See also

pm_device_busy_set()

pm_device_busy_set()

void pm_device_busy_set

(

const struct device *

dev

)

#include <zephyr/pm/device.h>

Mark a device as busy.

Devices marked as busy will not be suspended when the system goes into low-power states. This can be useful if, for example, the device is in the middle of a transaction.

Parameters

dev	Device instance.

See also

pm_device_busy_clear()

pm_device_children_action_run()

void pm_device_children_action_run	(	const struct device *	dev,
		enum pm_device_action	action,
		pm_device_action_failed_cb_t	failure_cb )

#include <zephyr/pm/device.h>

Run a pm action on all children of a device.

This function calls all child devices PM control callback so that the device does the necessary operations to execute the given action.

Parameters

dev	Device instance.
action	Device pm action.
failure_cb	Function to call if a child fails the action, can be NULL.

pm_device_driver_deinit()

int pm_device_driver_deinit	(	const struct device *	dev,
		pm_device_action_cb_t	action_cb )

#include <zephyr/pm/device.h>

Prepare PM device for device driver deinit.

Ensures device is either SUSPENDED or OFF. If CONFIG_PM_DEVICE=y, the function checks whether power management has moved the device to either the SUSPENDED or OFF states. If CONFIG_PM_DEVICE=n, the function uses the device driver's internal PM hook to move the device to the SUSPENDED state.

Note

This function must be called at the beginning of a driver's deinit function.

Parameters

dev	Device instance.
action_cb	Device PM control callback function.

Return values

0	if success.
-EBUSY	Device is not SUSPENDED nor OFF
-errno	code if failure.

pm_device_driver_init()

int pm_device_driver_init	(	const struct device *	dev,
		pm_device_action_cb_t	action_cb )

#include <zephyr/pm/device.h>

Move a device driver into its initial device power state.

This function uses the device driver's internal PM hook to move the device from the OFF state to the initial power state expected by the system.

The initial power state expected by the system is:

• ACTIVE if CONFIG_PM_DEVICE=n or (CONFIG_PM_DEVICE=y and CONFIG_PM_DEVICE_RUNTIME=n) or (CONFIG_PM_DEVICE_RUNTIME=y and !pm_device_runtime_is_enabled(dev)).
• SUSPENDED if CONFIG_PM_DEVICE_RUNTIME=y and device's parent power domain is ACTIVE.
• OFF if CONFIG_PM_DEVICE_RUNTIME=y and device's parent power domain is SUSPENDED.

Note

This function must be called at the end of a driver's init function.

Parameters

dev	Device instance.
action_cb	Device PM control callback function.

Return values

0	On success.
-errno	Error code from action_cb on failure.

pm_device_init_off()

void pm_device_init_off ( const struct device * dev )

inlinestatic

#include <zephyr/pm/device.h>

Initialize a device state to PM_DEVICE_STATE_OFF.

By default device state is initialized to PM_DEVICE_STATE_ACTIVE. In general, this makes sense because the device initialization function will resume and configure a device, leaving it operational. However, when power domains are enabled, the device may be connected to a switchable power source, in which case it won't be powered at boot. This function can therefore be used to notify the PM subsystem that the device is in PM_DEVICE_STATE_OFF instead of the default.

Parameters

dev	Device instance.

pm_device_init_suspended()

void pm_device_init_suspended ( const struct device * dev )

inlinestatic

#include <zephyr/pm/device.h>

Initialize a device state to PM_DEVICE_STATE_SUSPENDED.

By default device state is initialized to PM_DEVICE_STATE_ACTIVE. However in order to save power some drivers may choose to only initialize the device to the suspended state, or actively put the device into the suspended state. This function can therefore be used to notify the PM subsystem that the device is in PM_DEVICE_STATE_SUSPENDED instead of the default.

Parameters

dev	Device instance.

pm_device_is_any_busy()

bool pm_device_is_any_busy

(

void

)

#include <zephyr/pm/device.h>

Check if any device is busy.

Return values

false	If no device is busy
true	If one or more devices are busy

pm_device_is_busy()

bool pm_device_is_busy

(

const struct device *

dev

)

#include <zephyr/pm/device.h>

Check if a device is busy.

Parameters

dev	Device instance.

Return values

false	If the device is not busy
true	If the device is busy

pm_device_is_powered()

bool pm_device_is_powered

(

const struct device *

dev

)

#include <zephyr/pm/device.h>

Check if the device is currently powered.

Parameters

dev	Device instance.

Return values

true	If device is currently powered, or is assumed to be powered (i.e. it does not support PM or is not under a PM domain)
false	If device is not currently powered

pm_device_on_power_domain()

bool pm_device_on_power_domain

(

const struct device *

dev

)

#include <zephyr/pm/device.h>

Check if the device is on a switchable power domain.

Parameters

dev	Device instance.

Return values

true	If device is on a switchable power domain.
false	If device is not on a switchable power domain.

pm_device_power_domain_add()

int pm_device_power_domain_add	(	const struct device *	dev,
		const struct device *	domain )

#include <zephyr/pm/device.h>

Add a device to a power domain.

This function adds a device to a given power domain.

Parameters

dev	Device to be added to the power domain.
domain	Power domain.

Return values

0	If successful.
-EALREADY	If device is already part of the power domain.
-ENOSYS	If the application was built without power domain support.
-ENOSPC	If there is no space available in the power domain to add the device.

pm_device_power_domain_remove()

int pm_device_power_domain_remove	(	const struct device *	dev,
		const struct device *	domain )

#include <zephyr/pm/device.h>

Remove a device from a power domain.

This function removes a device from a given power domain.

Parameters

dev	Device to be removed from the power domain.
domain	Power domain.

Return values

0	If successful.
-ENOSYS	If the application was built without power domain support.
-ENOENT	If device is not in the given domain.

pm_device_state_get()

int pm_device_state_get	(	const struct device *	dev,
		enum pm_device_state *	state )

#include <zephyr/pm/device.h>

Obtain the power state of a device.

Parameters

dev	Device instance.
state	Pointer where device power state will be stored.

Return values

0	If successful.
-ENOSYS	If device does not implement power management.

pm_device_state_str()

const char * pm_device_state_str

(

enum pm_device_state

state

)

#include <zephyr/pm/device.h>

Get name of device PM state.

Parameters

state

State id which name should be returned

pm_device_wakeup_enable()

bool pm_device_wakeup_enable	(	const struct device *	dev,
		bool	enable )

#include <zephyr/pm/device.h>

Enable or disable a device as a wake up source.

A device marked as a wake up source will not be suspended when the system goes into low-power modes, thus allowing to use it as a wake up source for the system.

Parameters

dev	Device instance.
enable	true to enable or false to disable

Return values

true	If the wakeup source was successfully enabled.
false	If the wakeup source was not successfully enabled.

pm_device_wakeup_is_capable()

bool pm_device_wakeup_is_capable

(

const struct device *

dev

)

#include <zephyr/pm/device.h>

Check if a device is wake up capable.

Parameters

dev	Device instance.

Return values

true	If the device is wake up capable.
false	If the device is not wake up capable.

pm_device_wakeup_is_enabled()

bool pm_device_wakeup_is_enabled

(

const struct device *

dev

)

#include <zephyr/pm/device.h>

Check if a device is enabled as a wake up source.

Parameters

dev	Device instance.

Return values

true	if the wakeup source is enabled.
false	if the wakeup source is not enabled.