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)    Z_PM_DEVICE_GET(dev_id)
	Obtain a reference to the device PM resources for the given device.
#define	PM_DEVICE_DT_GET(node_id)    PM_DEVICE_GET(Z_DEVICE_DT_DEV_ID(node_id))
	Obtain a reference to the device PM resources for the given node.
#define	PM_DEVICE_DT_INST_GET(idx)    PM_DEVICE_DT_GET(DT_DRV_INST(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)
	Setup a device driver into the lowest valid power mode.

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

)

PM_DEVICE_GET(Z_DEVICE_DT_DEV_ID(node_id))

#include <zephyr/pm/device.h>

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

)

PM_DEVICE_DT_GET(DT_DRV_INST(idx))

#include <zephyr/pm/device.h>

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

)

Z_PM_DEVICE_GET(dev_id)

#include <zephyr/pm/device.h>

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 is in active or regular state.
PM_DEVICE_STATE_SUSPENDED	Device is suspended. Note Device context may be lost.
PM_DEVICE_STATE_SUSPENDING	Device is being suspended.
PM_DEVICE_STATE_OFF	Device is turned off (power removed). Note Device context is lost.

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

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

#include <zephyr/pm/device.h>

Setup a device driver into the lowest valid power mode.

This helper function is intended to be called at the end of a driver init function to automatically setup the device into the lowest power mode. It assumes that the device has been configured as if it is in PM_DEVICE_STATE_OFF.

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

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

static 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.