Device Runtime

Device Runtime Power Management API. More...

Files
file	device_runtime.h
	Header file for the Device Runtime Power Management API.

Macros
#define	LOG_DBG_PM_DEVICE_RUNTIME_GET(dev, ...)
	Writes a "failed to resume" debug message to the log.
#define	LOG_WRN_PM_DEVICE_RUNTIME_GET(dev, ...)
	Writes a "failed to resume" warning message to the log.
#define	LOG_ERR_PM_DEVICE_RUNTIME_GET(dev, ...)
	Writes a "failed to resume" error message to the log.
#define	LOG_DBG_PM_DEVICE_RUNTIME_PUT(dev, ...)
	Writes a "failed to suspend" debug message to the log.
#define	LOG_WRN_PM_DEVICE_RUNTIME_PUT(dev, ...)
	Writes a "failed to suspend" warning message to the log.
#define	LOG_ERR_PM_DEVICE_RUNTIME_PUT(dev, ...)
	Writes a "failed to suspend" error message to the log.
#define	LOG_INST_DBG_PM_DEVICE_RUNTIME_GET(_log_inst, dev, ...)
	Writes a "failed to resume" debug message to the log for the logging instance.
#define	LOG_INST_WRN_PM_DEVICE_RUNTIME_GET(_log_inst, dev, ...)
	Writes a "failed to resume" warning message to the log for the logging instance.
#define	LOG_INST_ERR_PM_DEVICE_RUNTIME_GET(_log_inst, dev, ...)
	Writes a "failed to resume" error message to the log for the logging instance.
#define	LOG_INST_DBG_PM_DEVICE_RUNTIME_PUT(_log_inst, dev, ...)
	Writes a "failed to suspend" debug message to the log for the logging instance.
#define	LOG_INST_WRN_PM_DEVICE_RUNTIME_PUT(_log_inst, dev, ...)
	Writes a "failed to suspend" warning message to the log for the logging instance.
#define	LOG_INST_ERR_PM_DEVICE_RUNTIME_PUT(_log_inst, dev, ...)
	Writes a "failed to suspend" error message to the log for the logging instance.

Functions
int	pm_device_runtime_auto_enable (const struct device *dev)
	Automatically enable device runtime based on devicetree properties.
int	pm_device_runtime_enable (const struct device *dev)
	Enable device runtime PM.
int	pm_device_runtime_disable (const struct device *dev)
	Disable device runtime PM.
int	pm_device_runtime_get (const struct device *dev)
	Resume a device based on usage count.
int	pm_device_runtime_put (const struct device *dev)
	Suspend a device based on usage count.
int	pm_device_runtime_put_async (const struct device *dev, k_timeout_t delay)
	Suspend a device based on usage count (asynchronously).
bool	pm_device_runtime_is_enabled (const struct device *dev)
	Check if device runtime is enabled for a given device.
int	pm_device_runtime_usage (const struct device *dev)
	Return the current device usage counter.

Detailed Description

Device Runtime Power Management API.

Since

3.0

Version

1.0.0

Macro Definition Documentation

LOG_DBG_PM_DEVICE_RUNTIME_GET

#define LOG_DBG_PM_DEVICE_RUNTIME_GET	(		dev,
			... )

#include <device_runtime.h>

Value:

COND_CODE_1(IS_EQ(NUM_VA_ARGS(__VA_ARGS__), 0), \
            (LOG_DBG("Failed to resume %s", (dev) ? (dev)->name : "(null)")), \
            (LOG_DBG("Failed to resume %s (%d)", (dev) ? (dev)->name : "(null)", \
                     GET_ARGS_FIRST_N(1, __VA_ARGS__))))

Writes a "failed to resume" debug message to the log.

Writes a "failed to resume" debug message to the log using the device name as reference, meant to be used in pm_device_runtime_get() checks.

Parameters

dev	pointer to a struct device.
...	optional return code for pm_device_runtime_get(). Only the first argument is used; all others will be discarded.

LOG_DBG_PM_DEVICE_RUNTIME_PUT

#define LOG_DBG_PM_DEVICE_RUNTIME_PUT	(		dev,
			... )

#include <device_runtime.h>

Value:

COND_CODE_1(IS_EQ(NUM_VA_ARGS(__VA_ARGS__), 0), \
            (LOG_DBG("Failed to suspend %s", (dev) ? (dev)->name : "(null)")), \
            (LOG_DBG("Failed to suspend %s (%d)", (dev) ? (dev)->name : "(null)", \
                     GET_ARGS_FIRST_N(1, __VA_ARGS__))))

Writes a "failed to suspend" debug message to the log.

Writes a "failed to suspend" debug message to the log using the device name as reference, meant to be used in pm_device_runtime_put() checks.

Parameters

dev	pointer to a struct device.
...	optional return code for pm_device_runtime_put(). Only the first argument is used; all others will be discarded.

LOG_ERR_PM_DEVICE_RUNTIME_GET

#define LOG_ERR_PM_DEVICE_RUNTIME_GET	(		dev,
			... )

#include <device_runtime.h>

Value:

COND_CODE_1(IS_EQ(NUM_VA_ARGS(__VA_ARGS__), 0), \
            (LOG_ERR("Failed to resume %s", (dev) ? (dev)->name : "(null)")), \
            (LOG_ERR("Failed to resume %s (%d)", (dev) ? (dev)->name : "(null)", \
                     GET_ARGS_FIRST_N(1, __VA_ARGS__))))

Writes a "failed to resume" error message to the log.

Writes a "failed to resume" error message to the log using the device name as reference, meant to be used in pm_device_runtime_get() checks.

Parameters

dev	pointer to a struct device.
...	optional return code for pm_device_runtime_get(). Only the first argument is used; all others will be discarded.

LOG_ERR_PM_DEVICE_RUNTIME_PUT

#define LOG_ERR_PM_DEVICE_RUNTIME_PUT	(		dev,
			... )

#include <device_runtime.h>

Value:

COND_CODE_1(IS_EQ(NUM_VA_ARGS(__VA_ARGS__), 0), \
            (LOG_ERR("Failed to suspend %s", (dev) ? (dev)->name : "(null)")), \
            (LOG_ERR("Failed to suspend %s (%d)", (dev) ? (dev)->name : "(null)", \
                     GET_ARGS_FIRST_N(1, __VA_ARGS__))))

Writes a "failed to suspend" error message to the log.

Writes a "failed to suspend" error message to the log using the device name as reference, meant to be used in pm_device_runtime_put() checks.

Parameters

dev	pointer to a struct device.
...	optional return code for pm_device_runtime_put(). Only the first argument is used; all others will be discarded.

LOG_INST_DBG_PM_DEVICE_RUNTIME_GET

#define LOG_INST_DBG_PM_DEVICE_RUNTIME_GET	(		_log_inst,
			dev,
			... )

#include <device_runtime.h>

Value:

COND_CODE_1(IS_EQ(NUM_VA_ARGS(__VA_ARGS__), 0), \
            (LOG_INST_DBG(_log_inst, "Failed to resume %s", \
                          (dev) ? (dev)->name : "(null)")), \
            (LOG_INST_DBG(_log_inst, "Failed to resume %s (%d)", \
                          (dev) ? (dev)->name : "(null)", \
                          GET_ARGS_FIRST_N(1, __VA_ARGS__))))

Writes a "failed to resume" debug message to the log for the logging instance.

Writes a "failed to resume" debug message to the log using the device name as reference, meant to be used in pm_device_runtime_get() checks.

Parameters

_log_inst	pointer to the log structure associated with the instance.
dev	pointer to a struct device.
...	optional return code for pm_device_runtime_get(). Only the first argument is used; all others will be discarded.

LOG_INST_DBG_PM_DEVICE_RUNTIME_PUT

#define LOG_INST_DBG_PM_DEVICE_RUNTIME_PUT	(		_log_inst,
			dev,
			... )

#include <device_runtime.h>

Value:

COND_CODE_1(IS_EQ(NUM_VA_ARGS(__VA_ARGS__), 0), \
            (LOG_INST_DBG(_log_inst, "Failed to suspend %s", \
                          (dev) ? (dev)->name : "(null)")), \
            (LOG_INST_DBG(_log_inst, "Failed to suspend %s (%d)", \
                          (dev) ? (dev)->name : "(null)", \
                          GET_ARGS_FIRST_N(1, __VA_ARGS__))))

Writes a "failed to suspend" debug message to the log for the logging instance.

Writes a "failed to suspend" debug message to the log using the device name as reference, meant to be used in pm_device_runtime_put() checks.

Parameters

_log_inst	pointer to the log structure associated with the instance.
dev	pointer to a struct device.
...	optional return code for pm_device_runtime_put(). Only the first argument is used; all others will be discarded.

LOG_INST_ERR_PM_DEVICE_RUNTIME_GET

#define LOG_INST_ERR_PM_DEVICE_RUNTIME_GET	(		_log_inst,
			dev,
			... )

#include <device_runtime.h>

Value:

COND_CODE_1(IS_EQ(NUM_VA_ARGS(__VA_ARGS__), 0), \
            (LOG_INST_ERR(_log_inst, "Failed to resume %s", \
                          (dev) ? (dev)->name : "(null)")), \
            (LOG_INST_ERR(_log_inst, "Failed to resume %s (%d)", \
                          (dev) ? (dev)->name : "(null)", \
                          GET_ARGS_FIRST_N(1, __VA_ARGS__))))

Writes a "failed to resume" error message to the log for the logging instance.

Writes a "failed to resume" error message to the log using the device name as reference, meant to be used in pm_device_runtime_get() checks.

Parameters

_log_inst	pointer to the log structure associated with the instance.
dev	pointer to a struct device.
...	optional return code for pm_device_runtime_get(). Only the first argument is used; all others will be discarded.

LOG_INST_ERR_PM_DEVICE_RUNTIME_PUT

#define LOG_INST_ERR_PM_DEVICE_RUNTIME_PUT	(		_log_inst,
			dev,
			... )

#include <device_runtime.h>

Value:

COND_CODE_1(IS_EQ(NUM_VA_ARGS(__VA_ARGS__), 0), \
            (LOG_INST_ERR(_log_inst, "Failed to suspend %s", \
                          (dev) ? (dev)->name : "(null)")), \
            (LOG_INST_ERR(_log_inst, "Failed to suspend %s (%d)", \
                          (dev) ? (dev)->name : "(null)", \
                          GET_ARGS_FIRST_N(1, __VA_ARGS__))))

Writes a "failed to suspend" error message to the log for the logging instance.

Writes a "failed to suspend" error message to the log using the device name as reference, meant to be used in pm_device_runtime_put() checks.

Parameters

_log_inst	pointer to the log structure associated with the instance.
dev	pointer to a struct device.
...	optional return code for pm_device_runtime_put(). Only the first argument is used; all others will be discarded.

LOG_INST_WRN_PM_DEVICE_RUNTIME_GET

#define LOG_INST_WRN_PM_DEVICE_RUNTIME_GET	(		_log_inst,
			dev,
			... )

#include <device_runtime.h>

Value:

COND_CODE_1(IS_EQ(NUM_VA_ARGS(__VA_ARGS__), 0), \
            (LOG_INST_WRN(_log_inst, "Failed to resume %s", \
                          (dev) ? (dev)->name : "(null)")), \
            (LOG_INST_WRN(_log_inst, "Failed to resume %s (%d)", \
                          (dev) ? (dev)->name : "(null)", \
                          GET_ARGS_FIRST_N(1, __VA_ARGS__))))

Writes a "failed to resume" warning message to the log for the logging instance.

Writes a "failed to resume" warning message to the log using the device name as reference, meant to be used in pm_device_runtime_get() checks.

Parameters

_log_inst	pointer to the log structure associated with the instance.
dev	pointer to a struct device.
...	optional return code for pm_device_runtime_get(). Only the first argument is used; all others will be discarded.

LOG_INST_WRN_PM_DEVICE_RUNTIME_PUT

#define LOG_INST_WRN_PM_DEVICE_RUNTIME_PUT	(		_log_inst,
			dev,
			... )

#include <device_runtime.h>

Value:

COND_CODE_1(IS_EQ(NUM_VA_ARGS(__VA_ARGS__), 0), \
            (LOG_INST_WRN(_log_inst, "Failed to suspend %s", \
                          (dev) ? (dev)->name : "(null)")), \
            (LOG_INST_WRN(_log_inst, "Failed to suspend %s (%d)", \
                          (dev) ? (dev)->name : "(null)", \
                          GET_ARGS_FIRST_N(1, __VA_ARGS__))))

Writes a "failed to suspend" warning message to the log for the logging instance.

Writes a "failed to suspend" warning message to the log using the device name as reference, meant to be used in pm_device_runtime_put() checks.

Parameters

_log_inst	pointer to the log structure associated with the instance.
dev	pointer to a struct device.
...	optional return code for pm_device_runtime_put(). Only the first argument is used; all others will be discarded.

LOG_WRN_PM_DEVICE_RUNTIME_GET

#define LOG_WRN_PM_DEVICE_RUNTIME_GET	(		dev,
			... )

#include <device_runtime.h>

Value:

COND_CODE_1(IS_EQ(NUM_VA_ARGS(__VA_ARGS__), 0), \
            (LOG_WRN("Failed to resume %s", (dev) ? (dev)->name : "(null)")), \
            (LOG_WRN("Failed to resume %s (%d)", (dev) ? (dev)->name : "(null)", \
                     GET_ARGS_FIRST_N(1, __VA_ARGS__))))

Writes a "failed to resume" warning message to the log.

Writes a "failed to resume" warning message to the log using the device name as reference, meant to be used in pm_device_runtime_get() checks.

Parameters

dev	pointer to a struct device.
...	optional return code for pm_device_runtime_get(). Only the first argument is used; all others will be discarded.

LOG_WRN_PM_DEVICE_RUNTIME_PUT

#define LOG_WRN_PM_DEVICE_RUNTIME_PUT	(		dev,
			... )

#include <device_runtime.h>

Value:

COND_CODE_1(IS_EQ(NUM_VA_ARGS(__VA_ARGS__), 0), \
            (LOG_WRN("Failed to suspend %s", (dev) ? (dev)->name : "(null)")), \
            (LOG_WRN("Failed to suspend %s (%d)", (dev) ? (dev)->name : "(null)", \
                     GET_ARGS_FIRST_N(1, __VA_ARGS__))))

Writes a "failed to suspend" warning message to the log.

Writes a "failed to suspend" warning message to the log using the device name as reference, meant to be used in pm_device_runtime_put() checks.

Parameters

dev	pointer to a struct device.
...	optional return code for pm_device_runtime_put(). Only the first argument is used; all others will be discarded.

Function Documentation

pm_device_runtime_auto_enable()

int pm_device_runtime_auto_enable

(

const struct device *

dev

)

#include <device_runtime.h>

Automatically enable device runtime based on devicetree properties.

Note

Must not be called from application code. See the zephyr,pm-device-runtime-auto property in pm.yaml and z_sys_init_run_level.

Parameters

dev	Device instance.

Returns

0 if the device runtime PM is enabled successfully or it has not been requested for this device in devicetree, negative errno value on failure.

pm_device_runtime_disable()

int pm_device_runtime_disable ( const struct device * dev )

pre-kernel-ok

#include <device_runtime.h>

Disable device runtime PM.

If the device is currently suspended it will be resumed.

Parameters

dev	Device instance.

Returns

0 on success, negative errno value on failure.

Return values

-ENOTSUP

Device does not support PM.

pm_device_runtime_enable()

int pm_device_runtime_enable ( const struct device * dev )

pre-kernel-ok

#include <device_runtime.h>

Enable device runtime PM.

This function will enable runtime PM on the given device. If the device is in PM_DEVICE_STATE_ACTIVE state, the device will be suspended.

Parameters

dev	Device instance.

Returns

0 on success, negative errno value on failure.

Return values

-EBUSY	Device is busy.
-ENOTSUP	Device does not support PM.

See also

pm_device_init_suspended()

pm_device_runtime_get()

int pm_device_runtime_get ( const struct device * dev )

pre-kernel-ok

#include <device_runtime.h>

Resume a device based on usage count.

This function will resume the device if the device is suspended (usage count equal to 0). In case of a resume failure, usage count and device state will be left unchanged. In all other cases, usage count will be incremented.

If the device is still being suspended as a result of calling pm_device_runtime_put_async(), this function will wait for the operation to finish to then resume the device.

Note

It is safe to use this function in contexts where blocking is not allowed, e.g. ISR, provided the device PM implementation does not block.

Parameters

dev	Device instance.

Returns

0 on success (including when runtime PM is not enabled or not available), negative errno value on failure.

Return values

-EWOULDBLOCK

Call would block but it is not allowed (e.g. in ISR).

pm_device_runtime_is_enabled()

bool pm_device_runtime_is_enabled ( const struct device * dev )

pre-kernel-ok

#include <device_runtime.h>

Check if device runtime is enabled for a given device.

Parameters

dev	Device instance.

Return values

true	Device has device runtime PM enabled.
false	Device has device runtime PM disabled.

See also

pm_device_runtime_enable()

pm_device_runtime_put()

int pm_device_runtime_put ( const struct device * dev )

pre-kernel-ok

#include <device_runtime.h>

Suspend a device based on usage count.

This function will suspend the device if the device is no longer required (usage count equal to 0). In case of suspend failure, usage count and device state will be left unchanged. In all other cases, usage count will be decremented (down to 0).

Parameters

dev	Device instance.

Returns

0 on success (including when runtime PM is not enabled or not available), negative errno value on failure.

Return values

-EALREADY

Device is already suspended (can only happen if get/put calls are unbalanced).

See also

pm_device_runtime_put_async()

pm_device_runtime_put_async()

int pm_device_runtime_put_async ( const struct device * dev, k_timeout_t delay )

pre-kernel-okasyncisr-ok

#include <device_runtime.h>

Suspend a device based on usage count (asynchronously).

This function will schedule the device suspension if the device is no longer required (usage count equal to 0). In all other cases, usage count will be decremented (down to 0).

Note

Asynchronous operations are not supported when in pre-kernel mode. In this case, the function will be blocking (equivalent to pm_device_runtime_put()).

Parameters

dev	Device instance.
delay	Minimum amount of time before triggering the action.

Returns

0 on success (including when runtime PM is not enabled or not available), negative errno value on failure.

Return values

-EBUSY	Device is busy.
-EALREADY	Device is already suspended (can only happen if get/put calls are unbalanced).

See also

pm_device_runtime_put()

pm_device_runtime_usage()

int pm_device_runtime_usage

(

const struct device *

dev

)

#include <device_runtime.h>

Return the current device usage counter.

Parameters

dev	Device instance.

Returns

The current usage counter.

Return values

-ENOTSUP	Device is not using runtime PM.
-ENOSYS	Runtime PM is not enabled in this build (CONFIG_PM_DEVICE_RUNTIME is disabled).