device.h

Go to the documentation of this file.

/*
 * Copyright (c) 2015 Intel Corporation.
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_PM_DEVICE_H_
#define ZEPHYR_INCLUDE_PM_DEVICE_H_
 
#include <device.h>
#include <kernel.h>
#include <sys/atomic.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
struct device;
 
enum pm_device_flag {
        PM_DEVICE_FLAG_BUSY,
        PM_DEVICE_FLAG_WS_CAPABLE,
        PM_DEVICE_FLAG_WS_ENABLED,
        PM_DEVICE_FLAG_RUNTIME_ENABLED,
        PM_DEVICE_FLAG_STATE_LOCKED,
};
 
enum pm_device_state {
        PM_DEVICE_STATE_ACTIVE,
        PM_DEVICE_STATE_SUSPENDED,
        PM_DEVICE_STATE_SUSPENDING,
        PM_DEVICE_STATE_OFF
};
 
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,
};
 
typedef int (*pm_device_action_cb_t)(const struct device *dev,
                                     enum pm_device_action action);
 
typedef bool (*pm_device_action_failed_cb_t)(const struct device *dev,
                                         int err);
 
struct pm_device {
#if defined(CONFIG_PM_DEVICE_RUNTIME) || defined(__DOXYGEN__)
        const struct device *dev;
        struct k_mutex lock;
        uint32_t usage;
        struct k_work_delayable work;
        struct k_condvar condvar;
#endif /* CONFIG_PM_DEVICE_RUNTIME */
#ifdef CONFIG_PM_DEVICE_POWER_DOMAIN
        const struct device *domain;
#endif /* CONFIG_PM_DEVICE_POWER_DOMAIN */
        /* Device PM status flags. */
        atomic_t flags;
        enum pm_device_state state;
        pm_device_action_cb_t action_cb;
};
 
#ifdef CONFIG_PM_DEVICE_RUNTIME
#define Z_PM_DEVICE_RUNTIME_INIT(obj)                   \
        .lock = Z_MUTEX_INITIALIZER(obj.lock),          \
        .condvar = Z_CONDVAR_INITIALIZER(obj.condvar),
#else
#define Z_PM_DEVICE_RUNTIME_INIT(obj)
#endif /* CONFIG_PM_DEVICE_RUNTIME */
 
#ifdef CONFIG_PM_DEVICE_POWER_DOMAIN
#define Z_PM_DEVICE_POWER_DOMAIN_INIT(_node_id)                 \
        .domain = DEVICE_DT_GET_OR_NULL(DT_PHANDLE(_node_id,    \
                                   power_domain)),
#else
#define Z_PM_DEVICE_POWER_DOMAIN_INIT(obj)
#endif /* CONFIG_PM_DEVICE_POWER_DOMAIN */
 
#define Z_PM_DEVICE_INIT(obj, node_id, pm_action_cb)                    \
        {                                                               \
                Z_PM_DEVICE_RUNTIME_INIT(obj)                           \
                .action_cb = pm_action_cb,                              \
                .state = PM_DEVICE_STATE_ACTIVE,                        \
                .flags = ATOMIC_INIT(COND_CODE_1(                       \
                                DT_NODE_EXISTS(node_id),                \
                                (DT_PROP_OR(node_id, wakeup_source, 0)),\
                                (0)) << PM_DEVICE_FLAG_WS_CAPABLE),     \
                Z_PM_DEVICE_POWER_DOMAIN_INIT(node_id)                  \
        }
 
#define Z_PM_DEVICE_NAME(dev_name) _CONCAT(__pm_device__, dev_name)
 
#define Z_PM_DEVICE_DEFINE_SLOT(dev_name)                               \
        static const Z_DECL_ALIGN(struct device *)                      \
        _CONCAT(Z_PM_DEVICE_NAME(dev_name), slot) __used                \
        __attribute__((__section__(".z_pm_device_slots")))
 
#ifdef CONFIG_PM_DEVICE
#define Z_PM_DEVICE_DEFINE(node_id, dev_name, pm_action_cb)             \
        Z_PM_DEVICE_DEFINE_SLOT(dev_name);                              \
        static struct pm_device Z_PM_DEVICE_NAME(dev_name) =            \
        Z_PM_DEVICE_INIT(Z_PM_DEVICE_NAME(dev_name), node_id,           \
                         pm_action_cb)
 
#define Z_PM_DEVICE_GET(dev_name) (&Z_PM_DEVICE_NAME(dev_name))
 
#else
#define Z_PM_DEVICE_DEFINE(node_id, dev_name, pm_action_cb)
#define Z_PM_DEVICE_GET(dev_name) NULL
#endif /* CONFIG_PM_DEVICE */
 
#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)                      \
        Z_PM_DEVICE_DEFINE(node_id, Z_DEVICE_DT_DEV_NAME(node_id),      \
                           pm_action_cb)
 
#define PM_DEVICE_DT_INST_DEFINE(idx, pm_action_cb)                     \
        Z_PM_DEVICE_DEFINE(DT_DRV_INST(idx),                            \
                           Z_DEVICE_DT_DEV_NAME(DT_DRV_INST(idx)),      \
                           pm_action_cb)
 
#define PM_DEVICE_GET(dev_name) \
        Z_PM_DEVICE_GET(dev_name)
 
#define PM_DEVICE_DT_GET(node_id) \
        PM_DEVICE_GET(Z_DEVICE_DT_DEV_NAME(node_id))
 
#define PM_DEVICE_DT_INST_GET(idx) \
        PM_DEVICE_DT_GET(DT_DRV_INST(idx))
 
const char *pm_device_state_str(enum pm_device_state state);
 
__deprecated int pm_device_state_set(const struct device *dev,
                        enum pm_device_state state);
 
int pm_device_state_get(const struct device *dev,
                        enum pm_device_state *state);
 
int pm_device_action_run(const struct device *dev,
                enum pm_device_action action);
 
void pm_device_children_action_run(const struct device *dev,
                enum pm_device_action action,
                pm_device_action_failed_cb_t failure_cb);
 
#if defined(CONFIG_PM_DEVICE) || defined(__DOXYGEN__)
void pm_device_busy_set(const struct device *dev);
 
void pm_device_busy_clear(const struct device *dev);
 
bool pm_device_is_any_busy(void);
 
bool pm_device_is_busy(const struct device *dev);
 
bool pm_device_wakeup_enable(struct device *dev, bool enable);
 
bool pm_device_wakeup_is_enabled(const struct device *dev);
 
bool pm_device_wakeup_is_capable(const struct device *dev);
 
void pm_device_state_lock(const struct device *dev);
 
void pm_device_state_unlock(const struct device *dev);
 
bool pm_device_state_is_locked(const struct device *dev);
 
bool pm_device_on_power_domain(const struct device *dev);
 
#else
static inline void pm_device_busy_set(const struct device *dev)
{
        ARG_UNUSED(dev);
}
static inline void pm_device_busy_clear(const struct device *dev)
{
        ARG_UNUSED(dev);
}
static inline bool pm_device_is_any_busy(void) { return false; }
static inline bool pm_device_is_busy(const struct device *dev)
{
        ARG_UNUSED(dev);
        return false;
}
static inline bool pm_device_wakeup_enable(struct device *dev, bool enable)
{
        ARG_UNUSED(dev);
        ARG_UNUSED(enable);
        return false;
}
static inline bool pm_device_wakeup_is_enabled(const struct device *dev)
{
        ARG_UNUSED(dev);
        return false;
}
static inline bool pm_device_wakeup_is_capable(const struct device *dev)
{
        ARG_UNUSED(dev);
        return false;
}
static inline void pm_device_state_lock(const struct device *dev)
{
        ARG_UNUSED(dev);
}
static inline void pm_device_state_unlock(const struct device *dev)
{
        ARG_UNUSED(dev);
}
static inline bool pm_device_state_is_locked(const struct device *dev)
{
        ARG_UNUSED(dev);
        return false;
}
static inline bool pm_device_on_power_domain(const struct device *dev)
{
        ARG_UNUSED(dev);
        return false;
}
#endif /* CONFIG_PM_DEVICE */
 
__deprecated static inline void device_busy_set(const struct device *dev)
{
        pm_device_busy_set(dev);
}
 
__deprecated static inline void device_busy_clear(const struct device *dev)
{
        pm_device_busy_clear(dev);
}
 
__deprecated static inline int device_any_busy_check(void)
{
        return pm_device_is_any_busy() ? -EBUSY : 0;
}
 
__deprecated static inline int device_busy_check(const struct device *dev)
{
        return pm_device_is_busy(dev) ? -EBUSY : 0;
}
 
#ifdef __cplusplus
}
#endif
 
#endif