Device

Device Power Management API. More...

Macros
#define	PM_DEVICE_DEFINE(dev_name, pm_action_cb)    Z_PM_DEVICE_DEFINE(DT_INVALID_NODE, dev_name, pm_action_cb)
#define	PM_DEVICE_DT_DEFINE(node_id, pm_action_cb)
#define	PM_DEVICE_DT_INST_DEFINE(idx, pm_action_cb)
#define	PM_DEVICE_GET(dev_name)    Z_PM_DEVICE_GET(dev_name)
	Obtain a reference to the device PM resources for the given device. More...
#define	PM_DEVICE_DT_GET(node_id)    PM_DEVICE_GET(Z_DEVICE_DT_DEV_NAME(node_id))
	Obtain a reference to the device PM resources for the given node. More...
#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. More...

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 ,   PM_DEVICE_ACTION_FORCE_SUSPEND }
	Device PM actions. More...

Functions
const char *	pm_device_state_str (enum pm_device_state state)
	Get name of device PM state. More...
int	pm_device_state_set (const struct device *dev, enum pm_device_state state)
	Set the power state of a device. More...
int	pm_device_state_get (const struct device *dev, enum pm_device_state *state)
	Obtain the power state of a device. More...
int	pm_device_action_run (const struct device *dev, enum pm_device_action action)
	Run a pm action on a device. More...
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. More...
void	pm_device_busy_set (const struct device *dev)
	Mark a device as busy. More...
void	pm_device_busy_clear (const struct device *dev)
	Clear a device busy status. More...
bool	pm_device_is_any_busy (void)
	Check if any device is busy. More...
bool	pm_device_is_busy (const struct device *dev)
	Check if a device is busy. More...
bool	pm_device_wakeup_enable (struct device *dev, bool enable)
	Enable or disable a device as a wake up source. More...
bool	pm_device_wakeup_is_enabled (const struct device *dev)
	Check if a device is enabled as a wake up source. More...
bool	pm_device_wakeup_is_capable (const struct device *dev)
	Check if a device is wake up capable. More...
void	pm_device_state_lock (const struct device *dev)
	Lock current device state. More...
void	pm_device_state_unlock (const struct device *dev)
	Unlock the current device state. More...
bool	pm_device_state_is_locked (const struct device *dev)
	Check if the device pm is locked. More...
bool	pm_device_on_power_domain (const struct device *dev)
	Check if the device is on a switchable power domain. More...
static void	device_busy_set (const struct device *dev)
static void	device_busy_clear (const struct device *dev)
	Clear busy status of a device. More...
static int	device_any_busy_check (void)
	Check if any device is busy. More...
static int	device_busy_check (const struct device *dev)
	Check if a device is busy. More...

Detailed Description

Device Power Management API.

Macro Definition Documentation

PM_DEVICE_DEFINE

#define PM_DEVICE_DEFINE	(		dev_name,
			pm_action_cb
	)		Z_PM_DEVICE_DEFINE(DT_INVALID_NODE, dev_name, pm_action_cb)

#include <include/pm/device.h>

Define device PM resources for the given device name.

Note

This macro is a no-op if

embed:rst:inline :kconfig:`CONFIG_PM_DEVICE` 

is not enabled.

Parameters

dev_name	Device name.
pm_action_cb	PM control callback.

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 <include/pm/device.h>

Value:

        Z_PM_DEVICE_DEFINE(node_id, Z_DEVICE_DT_DEV_NAME(node_id),      \
                           pm_action_cb)

Define device PM resources for the given node identifier.

Note

This macro is a no-op if

embed:rst:inline :kconfig:`CONFIG_PM_DEVICE` 

is not enabled.

Parameters

node_id	Node identifier.
pm_action_cb	PM control callback.

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

#include <include/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

embed:rst:inline :kconfig:`CONFIG_PM_DEVICE` 

is disabled).

PM_DEVICE_DT_INST_DEFINE

#define PM_DEVICE_DT_INST_DEFINE	(		idx,
			pm_action_cb
	)

#include <include/pm/device.h>

Value:

        Z_PM_DEVICE_DEFINE(DT_DRV_INST(idx),                            \
                           Z_DEVICE_DT_DEV_NAME(DT_DRV_INST(idx)),      \
                           pm_action_cb)

Define device PM resources for the given instance.

Note

This macro is a no-op if

embed:rst:inline :kconfig:`CONFIG_PM_DEVICE` 

is not enabled.

Parameters

idx	Instance index.
pm_action_cb	PM control callback.

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 <include/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

embed:rst:inline :kconfig:`CONFIG_PM_DEVICE` 

is disabled).

PM_DEVICE_GET

#define PM_DEVICE_GET

(

dev_name

)

Z_PM_DEVICE_GET(dev_name)

#include <include/pm/device.h>

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

Parameters

dev_name

Device name.

Returns

Reference to the device PM resources (NULL if device

embed:rst:inline :kconfig:`CONFIG_PM_DEVICE` 

is disabled).

Enumeration Type Documentation

pm_device_action

enum pm_device_action

#include <include/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_ACTION_FORCE_SUSPEND	Force suspend.

pm_device_state

enum pm_device_state

#include <include/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

device_any_busy_check()

static int device_any_busy_check ( void  )

inlinestatic

#include <include/pm/device.h>

Check if any device is busy.

Deprecated:

Use pm_device_is_any_busy() instead

Return values

0	No devices are busy.
-EBUSY	One or more devices are busy.

device_busy_check()

static int device_busy_check ( const struct device *  dev )

inlinestatic

#include <include/pm/device.h>

Check if a device is busy.

Deprecated:

Use pm_device_is_busy() instead

Parameters

dev	Device instance.

Return values

0	Device is not busy.
-EBUSY	Device is busy.

device_busy_clear()

static void device_busy_clear ( const struct device *  dev )

inlinestatic

#include <include/pm/device.h>

Clear busy status of a device.

Deprecated:

Use pm_device_busy_clear() instead

Parameters

dev	Device instance.

device_busy_set()

static void device_busy_set ( const struct device *  dev )

inlinestatic

#include <include/pm/device.h>

Mark a device as busy.

Deprecated:

Use pm_device_busy_set() instead

Parameters

dev	Device instance.

pm_device_action_run()

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

#include <include/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 <include/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 <include/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 <include/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_is_any_busy()

bool pm_device_is_any_busy

(

void

)

#include <include/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 <include/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_on_power_domain()

bool pm_device_on_power_domain

(

const struct device *

dev

)

#include <include/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_state_get()

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

#include <include/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_is_locked()

bool pm_device_state_is_locked

(

const struct device *

dev

)

#include <include/pm/device.h>

Check if the device pm is locked.

Parameters

dev	Device instance.

Return values

true	If device is locked.
false	If device is not locked.

pm_device_state_lock()

void pm_device_state_lock

(

const struct device *

dev

)

#include <include/pm/device.h>

Lock current device state.

This function locks the current device power state. Once locked the device power state will not be changed by system power management or device runtime power management until unlocked.

Note

The given device should not have device runtime enabled.

See also

pm_device_state_unlock

Parameters

dev	Device instance.

pm_device_state_set()

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

#include <include/pm/device.h>

Set the power state of a device.

Deprecated:

Use pm_device_action_run() instead.

This function calls the device PM control callback so that the device does the necessary operations to put the device into the given state.

Note

Some devices may not support all device power states.

Parameters

dev	Device instance.
state	Device power state to be set.

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

const char * pm_device_state_str

(

enum pm_device_state

state

)

#include <include/pm/device.h>

Get name of device PM state.

Parameters

state

State id which name should be returned

pm_device_state_unlock()

void pm_device_state_unlock

(

const struct device *

dev

)

#include <include/pm/device.h>

Unlock the current device state.

Unlocks a previously locked device pm.

See also

pm_device_state_lock

Parameters

dev	Device instance.

pm_device_wakeup_enable()

bool pm_device_wakeup_enable	(	struct device *	dev,
		bool	enable
	)

#include <include/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 <include/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 <include/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.