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 <zephyr/device.h>
#include <zephyr/kernel.h>
#include <zephyr/sys/atomic.h>
#include <zephyr/sys/iterable_sections.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
struct device;
 
enum pm_device_flag {
        PM_DEVICE_FLAG_BUSY,
        PM_DEVICE_FLAG_TURN_ON_FAILED,
        PM_DEVICE_FLAG_PD_CLAIMED,
        PM_DEVICE_FLAG_WS_CAPABLE,
        PM_DEVICE_FLAG_WS_ENABLED,
        PM_DEVICE_FLAG_RUNTIME_ENABLED,
        PM_DEVICE_FLAG_PD,
        PM_DEVICE_FLAG_RUNTIME_AUTO,
        PM_DEVICE_FLAG_ISR_SAFE,
};
 
#define PM_DEVICE_ISR_SAFE 1
 
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,
};
 
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_base {
        atomic_t flags;
        enum pm_device_state state;
        pm_device_action_cb_t action_cb;
#if defined(CONFIG_PM_DEVICE_RUNTIME) || defined(__DOXYGEN__)
        uint32_t usage;
#endif /* CONFIG_PM_DEVICE_RUNTIME */
#ifdef CONFIG_PM_DEVICE_POWER_DOMAIN
        const struct device *domain;
#endif /* CONFIG_PM_DEVICE_POWER_DOMAIN */
};
 
struct pm_device {
        struct pm_device_base base;
#if defined(CONFIG_PM_DEVICE_RUNTIME) || defined(__DOXYGEN__)
        const struct device *dev;
        struct k_sem lock;
        struct k_event event;
#if defined(CONFIG_PM_DEVICE_RUNTIME_ASYNC) || defined(__DOXYGEN__)
        struct k_work_delayable work;
#endif /* CONFIG_PM_DEVICE_RUNTIME_ASYNC */
#endif /* CONFIG_PM_DEVICE_RUNTIME */
};
 
struct pm_device_isr {
        struct pm_device_base base;
#if defined(CONFIG_PM_DEVICE_RUNTIME) || defined(__DOXYGEN__)
        struct k_spinlock lock;
#endif
};
 
/* Base part must be the first element. */
BUILD_ASSERT(offsetof(struct pm_device, base) == 0);
BUILD_ASSERT(offsetof(struct pm_device_isr, base) == 0);
 
#ifdef CONFIG_PM_DEVICE_RUNTIME
#define Z_PM_DEVICE_RUNTIME_INIT(obj)                   \
        .lock = Z_SEM_INITIALIZER(obj.lock, 1, 1),      \
        .event = Z_EVENT_INITIALIZER(obj.event),
#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_domains)),
#else
#define Z_PM_DEVICE_POWER_DOMAIN_INIT(obj)
#endif /* CONFIG_PM_DEVICE_POWER_DOMAIN */
 
#define Z_PM_DEVICE_FLAGS(node_id)                                       \
        (COND_CODE_1(                                                    \
                 DT_NODE_EXISTS(node_id),                                \
                 ((DT_PROP_OR(node_id, wakeup_source, 0)                 \
                         << PM_DEVICE_FLAG_WS_CAPABLE) |                 \
                  (DT_PROP_OR(node_id, zephyr_pm_device_runtime_auto, 0) \
                         << PM_DEVICE_FLAG_RUNTIME_AUTO) |               \
                  (DT_NODE_HAS_COMPAT(node_id, power_domain) <<          \
                         PM_DEVICE_FLAG_PD)),                            \
                 (0)))
 
#define Z_PM_DEVICE_BASE_INIT(obj, node_id, pm_action_cb, _flags)            \
        {                                                                    \
                .flags = ATOMIC_INIT(Z_PM_DEVICE_FLAGS(node_id) | (_flags)), \
                .state = PM_DEVICE_STATE_ACTIVE,                             \
                .action_cb = pm_action_cb,                                   \
                Z_PM_DEVICE_POWER_DOMAIN_INIT(node_id)                       \
        }
 
#define Z_PM_DEVICE_INIT(obj, node_id, pm_action_cb, isr_safe)                  \
        {                                                                       \
                .base = Z_PM_DEVICE_BASE_INIT(obj, node_id, pm_action_cb,       \
                                isr_safe ? BIT(PM_DEVICE_FLAG_ISR_SAFE) : 0),   \
                COND_CODE_1(isr_safe, (), (Z_PM_DEVICE_RUNTIME_INIT(obj)))      \
        }
 
#define Z_PM_DEVICE_NAME(dev_id) _CONCAT(__pm_device_, dev_id)
 
#ifdef CONFIG_PM
#define Z_PM_DEVICE_DEFINE_SLOT(dev_id)                                 \
        static STRUCT_SECTION_ITERABLE_ALTERNATE(pm_device_slots, device, \
                        _CONCAT(__pm_slot_, dev_id))
#else
#define Z_PM_DEVICE_DEFINE_SLOT(dev_id)
#endif /* CONFIG_PM */
 
#ifdef CONFIG_PM_DEVICE
#define Z_PM_DEVICE_DEFINE(node_id, dev_id, pm_action_cb, isr_safe)             \
        Z_PM_DEVICE_DEFINE_SLOT(dev_id);                                        \
        static struct COND_CODE_1(isr_safe, (pm_device_isr), (pm_device))       \
                Z_PM_DEVICE_NAME(dev_id) =                                      \
                Z_PM_DEVICE_INIT(Z_PM_DEVICE_NAME(dev_id), node_id,             \
                                 pm_action_cb, isr_safe)
 
#define Z_PM_DEVICE_GET(dev_id) ((struct pm_device_base *)&Z_PM_DEVICE_NAME(dev_id))
 
#else
#define Z_PM_DEVICE_DEFINE(node_id, dev_id, pm_action_cb, isr_safe)
#define Z_PM_DEVICE_GET(dev_id) NULL
#endif /* CONFIG_PM_DEVICE */
 
#define PM_DEVICE_DEFINE(dev_id, pm_action_cb, ...)                     \
        Z_PM_DEVICE_DEFINE(DT_INVALID_NODE, dev_id, pm_action_cb,       \
                        COND_CODE_1(IS_EMPTY(__VA_ARGS__), (0), (__VA_ARGS__)))
 
#define PM_DEVICE_DT_DEFINE(node_id, pm_action_cb, ...) \
        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 PM_DEVICE_DT_INST_DEFINE(idx, pm_action_cb, ...)                \
        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 PM_DEVICE_GET(dev_id) \
        Z_PM_DEVICE_GET(dev_id)
 
#define PM_DEVICE_DT_GET(node_id) \
        PM_DEVICE_GET(Z_DEVICE_DT_DEV_ID(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);
 
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__)
int pm_device_state_get(const struct device *dev,
                        enum pm_device_state *state);
 
static inline void pm_device_init_suspended(const struct device *dev)
{
        struct pm_device_base *pm = dev->pm_base;
 
        pm->state = PM_DEVICE_STATE_SUSPENDED;
}
 
static inline void pm_device_init_off(const struct device *dev)
{
        struct pm_device_base *pm = dev->pm_base;
 
        pm->state = PM_DEVICE_STATE_OFF;
}
 
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(const 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);
 
bool pm_device_on_power_domain(const struct device *dev);
 
int pm_device_power_domain_add(const struct device *dev,
                               const struct device *domain);
 
int pm_device_power_domain_remove(const struct device *dev,
                                  const struct device *domain);
 
bool pm_device_is_powered(const struct device *dev);
 
int pm_device_driver_init(const struct device *dev, pm_device_action_cb_t action_cb);
 
int pm_device_driver_deinit(const struct device *dev, pm_device_action_cb_t action_cb);
#else
static inline int pm_device_state_get(const struct device *dev,
                                      enum pm_device_state *state)
{
        ARG_UNUSED(dev);
 
        *state = PM_DEVICE_STATE_ACTIVE;
 
        return 0;
}
 
static inline void pm_device_init_suspended(const struct device *dev)
{
        ARG_UNUSED(dev);
}
static inline void pm_device_init_off(const struct device *dev)
{
        ARG_UNUSED(dev);
}
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(const 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 bool pm_device_on_power_domain(const struct device *dev)
{
        ARG_UNUSED(dev);
        return false;
}
 
static inline int pm_device_power_domain_add(const struct device *dev,
                                             const struct device *domain)
{
        ARG_UNUSED(dev);
        ARG_UNUSED(domain);
        return -ENOSYS;
}
 
static inline int pm_device_power_domain_remove(const struct device *dev,
                                                const struct device *domain)
{
        ARG_UNUSED(dev);
        ARG_UNUSED(domain);
        return -ENOSYS;
}
 
static inline bool pm_device_is_powered(const struct device *dev)
{
        ARG_UNUSED(dev);
        return true;
}
 
static inline int pm_device_driver_init(const struct device *dev, pm_device_action_cb_t action_cb)
{
        int rc;
 
        /* When power management is not enabled, all drivers should initialise to active state */
        rc = action_cb(dev, PM_DEVICE_ACTION_TURN_ON);
        if ((rc < 0) && (rc != -ENOTSUP)) {
                return rc;
        }
 
        rc = action_cb(dev, PM_DEVICE_ACTION_RESUME);
        if (rc < 0) {
                return rc;
        }
 
        return 0;
}
 
static inline int pm_device_driver_deinit(const struct device *dev, pm_device_action_cb_t action_cb)
{
        return action_cb(dev, PM_DEVICE_ACTION_SUSPEND);
}
 
#endif /* CONFIG_PM_DEVICE */
 
#ifdef __cplusplus
}
#endif
 
#endif