Zephyr API Documentation  3.6.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches

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 DT_INVALID_NODE
Name for an invalid node identifier.
Definition: devicetree.h:87
#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
#define IS_EMPTY(...)
Check if a macro has a replacement expression.
Definition: util_macro.h:277

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_idDevice id.
pm_action_cbPM 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_idNode identifier.
pm_action_cbPM 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_idNode 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 DT_DRV_INST(inst)
Node identifier for an instance of a DT_DRV_COMPAT compatible.
Definition: devicetree.h:3432

Define device PM resources for the given instance.

Note
This macro is a no-op if CONFIG_PM_DEVICE is not enabled.
Parameters
idxInstance index.
pm_action_cbPM 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
idxInstance 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_idDevice 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
devDevice instance.
actionRequested action.
Return values
0If successful.
-ENOTSUPIf the requested action is not supported.
ErrnoOther 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
devDevice that failed the action.
errReturn code of action failure.
Returns
True to continue iteration, false to halt iteration.

Enumeration Type Documentation

◆ 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

#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
devDevice instance.
actionDevice pm action.
Return values
0If successful.
-ENOTSUPIf requested state is not supported.
-EALREADYIf device is already at the requested state.
-EBUSYIf device is changing its state.
-ENOSYSIf device does not support PM.
-EPERMIf device has power state locked.
ErrnoOther 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
devDevice 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
devDevice 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
devDevice instance.
actionDevice pm action.
failure_cbFunction 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
devDevice instance.
action_cbDevice PM control callback function.
Return values
0On success.
-errnoError 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
devDevice 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
devDevice 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
falseIf no device is busy
trueIf 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
devDevice instance.
Return values
falseIf the device is not busy
trueIf 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
devDevice instance.
Return values
trueIf device is currently powered, or is assumed to be powered (i.e. it does not support PM or is not under a PM domain)
falseIf 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
devDevice instance.
Return values
trueIf device is on a switchable power domain.
falseIf 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
devDevice to be added to the power domain.
domainPower domain.
Return values
0If successful.
-EALREADYIf device is already part of the power domain.
-ENOSYSIf the application was built without power domain support.
-ENOSPCIf 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
devDevice to be removed from the power domain.
domainPower domain.
Return values
0If successful.
-ENOSYSIf the application was built without power domain support.
-ENOENTIf 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
devDevice instance.
statePointer where device power state will be stored.
Return values
0If successful.
-ENOSYSIf 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
stateState 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
devDevice instance.
enabletrue to enable or false to disable
Return values
trueIf the wakeup source was successfully enabled.
falseIf 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
devDevice instance.
Return values
trueIf the device is wake up capable.
falseIf 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
devDevice instance.
Return values
trueif the wakeup source is enabled.
falseif the wakeup source is not enabled.