device.h

Go to the documentation of this file.

/*
 * Copyright (c) 2015 Intel Corporation.
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_DEVICE_H_
#define ZEPHYR_INCLUDE_DEVICE_H_
 
#include <stdint.h>
 
#include <zephyr/devicetree.h>
#include <zephyr/init.h>
#include <zephyr/linker/sections.h>
#include <zephyr/pm/state.h>
#include <zephyr/sys/device_mmio.h>
#include <zephyr/sys/iterable_sections.h>
#include <zephyr/sys/util.h>
#include <zephyr/toolchain.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define Z_DEVICE_DEPS_SEP INT16_MIN
 
#define Z_DEVICE_DEPS_ENDS INT16_MAX
 
#define Z_DEVICE_IS_MUTABLE(node_id)                                                               \
        COND_CODE_1(IS_ENABLED(CONFIG_DEVICE_MUTABLE), (DT_PROP(node_id, zephyr_mutable)), (0))
 
typedef int16_t device_handle_t;
 
#define DEVICE_HANDLE_NULL 0
 
#define DEVICE_NAME_GET(dev_id) _CONCAT(__device_, dev_id)
 
/* Node paths can exceed the maximum size supported by
 * device_get_binding() in user mode; this macro synthesizes a unique
 * dev_id from a devicetree node while staying within this maximum
 * size.
 *
 * The ordinal used in this name can be mapped to the path by
 * examining zephyr/include/generated/zephyr/devicetree_generated.h.
 */
#define Z_DEVICE_DT_DEV_ID(node_id) _CONCAT(dts_ord_, DT_DEP_ORD(node_id))
 
#define DEVICE_DEFINE(dev_id, name, init_fn, pm, data, config, level, prio,    \
                      api)                                                     \
        Z_DEVICE_STATE_DEFINE(dev_id);                                         \
        Z_DEVICE_DEFINE(DT_INVALID_NODE, dev_id, name, init_fn, pm, data,      \
                        config, level, prio, api,                              \
                        &Z_DEVICE_STATE_NAME(dev_id))
 
#define DEVICE_DT_NAME(node_id)                                                \
        DT_PROP_OR(node_id, label, DT_NODE_FULL_NAME(node_id))
 
#define DEVICE_DT_DEFER(node_id)                                               \
        DT_PROP(node_id, zephyr_deferred_init)
 
#define DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, level, prio, api, \
                         ...)                                                  \
        Z_DEVICE_STATE_DEFINE(Z_DEVICE_DT_DEV_ID(node_id));                    \
        Z_DEVICE_DEFINE(node_id, Z_DEVICE_DT_DEV_ID(node_id),                  \
                        DEVICE_DT_NAME(node_id), init_fn, pm, data, config,    \
                        level, prio, api,                                      \
                        &Z_DEVICE_STATE_NAME(Z_DEVICE_DT_DEV_ID(node_id)),     \
                        __VA_ARGS__)
 
#define DEVICE_DT_INST_DEFINE(inst, ...)                                       \
        DEVICE_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)
 
#define DEVICE_DT_NAME_GET(node_id) DEVICE_NAME_GET(Z_DEVICE_DT_DEV_ID(node_id))
 
#define DEVICE_DT_GET(node_id) (&DEVICE_DT_NAME_GET(node_id))
 
#define DEVICE_DT_INST_GET(inst) DEVICE_DT_GET(DT_DRV_INST(inst))
 
#define DEVICE_DT_GET_ANY(compat)                                              \
        COND_CODE_1(DT_HAS_COMPAT_STATUS_OKAY(compat),                         \
                    (DEVICE_DT_GET(DT_COMPAT_GET_ANY_STATUS_OKAY(compat))),    \
                    (NULL))
 
#define DEVICE_DT_GET_ONE(compat)                                              \
        COND_CODE_1(DT_HAS_COMPAT_STATUS_OKAY(compat),                         \
                    (DEVICE_DT_GET(DT_COMPAT_GET_ANY_STATUS_OKAY(compat))),    \
                    (ZERO_OR_COMPILE_ERROR(0)))
 
#define DEVICE_DT_GET_OR_NULL(node_id)                                         \
        COND_CODE_1(DT_NODE_HAS_STATUS(node_id, okay),                         \
                    (DEVICE_DT_GET(node_id)), (NULL))
 
#define DEVICE_GET(dev_id) (&DEVICE_NAME_GET(dev_id))
 
#define DEVICE_DECLARE(dev_id)                                                 \
        static const struct device DEVICE_NAME_GET(dev_id)
 
#define DEVICE_INIT_DT_GET(node_id)                                            \
        (&Z_INIT_ENTRY_NAME(DEVICE_DT_NAME_GET(node_id)))
 
#define DEVICE_INIT_GET(dev_id) (&Z_INIT_ENTRY_NAME(DEVICE_NAME_GET(dev_id)))
 
struct device_state {
        uint8_t init_res;
 
        bool initialized : 1;
};
 
struct pm_device_base;
struct pm_device;
struct pm_device_isr;
#if defined(CONFIG_DEVICE_DT_METADATA) || defined(__DOXYGEN__)
struct device_dt_metadata;
#endif
 
#ifdef CONFIG_DEVICE_DEPS_DYNAMIC
#define Z_DEVICE_DEPS_CONST
#else
#define Z_DEVICE_DEPS_CONST const
#endif
 
struct device {
        const char *name;
        const void *config;
        const void *api;
        struct device_state *state;
        void *data;
#if defined(CONFIG_DEVICE_DEPS) || defined(__DOXYGEN__)
        Z_DEVICE_DEPS_CONST device_handle_t *deps;
#endif /* CONFIG_DEVICE_DEPS */
#if defined(CONFIG_PM_DEVICE) || defined(__DOXYGEN__)
        union {
                struct pm_device_base *pm_base;
                struct pm_device *pm;
                struct pm_device_isr *pm_isr;
        };
#endif
#if defined(CONFIG_DEVICE_DT_METADATA) || defined(__DOXYGEN__)
        const struct device_dt_metadata *dt_meta;
#endif /* CONFIG_DEVICE_DT_METADATA */
};
 
static inline device_handle_t device_handle_get(const struct device *dev)
{
        device_handle_t ret = DEVICE_HANDLE_NULL;
        STRUCT_SECTION_START_EXTERN(device);
 
        /* TODO: If/when devices can be constructed that are not part of the
         * fixed sequence we'll need another solution.
         */
        if (dev != NULL) {
                ret = 1 + (device_handle_t)(dev - STRUCT_SECTION_START(device));
        }
 
        return ret;
}
 
static inline const struct device *
device_from_handle(device_handle_t dev_handle)
{
        STRUCT_SECTION_START_EXTERN(device);
        const struct device *dev = NULL;
        size_t numdev;
 
        STRUCT_SECTION_COUNT(device, &numdev);
 
        if ((dev_handle > 0) && ((size_t)dev_handle <= numdev)) {
                dev = &STRUCT_SECTION_START(device)[dev_handle - 1];
        }
 
        return dev;
}
 
#if defined(CONFIG_DEVICE_DEPS) || defined(__DOXYGEN__)
 
typedef int (*device_visitor_callback_t)(const struct device *dev,
                                         void *context);
 
static inline const device_handle_t *
device_required_handles_get(const struct device *dev, size_t *count)
{
        const device_handle_t *rv = dev->deps;
 
        if (rv != NULL) {
                size_t i = 0;
 
                while ((rv[i] != Z_DEVICE_DEPS_ENDS) &&
                       (rv[i] != Z_DEVICE_DEPS_SEP)) {
                        ++i;
                }
                *count = i;
        }
 
        return rv;
}
 
static inline const device_handle_t *
device_injected_handles_get(const struct device *dev, size_t *count)
{
        const device_handle_t *rv = dev->deps;
        size_t region = 0;
        size_t i = 0;
 
        if (rv != NULL) {
                /* Fast forward to injected devices */
                while (region != 1) {
                        if (*rv == Z_DEVICE_DEPS_SEP) {
                                region++;
                        }
                        rv++;
                }
                while ((rv[i] != Z_DEVICE_DEPS_ENDS) &&
                       (rv[i] != Z_DEVICE_DEPS_SEP)) {
                        ++i;
                }
                *count = i;
        }
 
        return rv;
}
 
static inline const device_handle_t *
device_supported_handles_get(const struct device *dev, size_t *count)
{
        const device_handle_t *rv = dev->deps;
        size_t region = 0;
        size_t i = 0;
 
        if (rv != NULL) {
                /* Fast forward to supporting devices */
                while (region != 2) {
                        if (*rv == Z_DEVICE_DEPS_SEP) {
                                region++;
                        }
                        rv++;
                }
                /* Count supporting devices.
                 * Trailing NULL's can be injected by gen_device_deps.py due to
                 * CONFIG_PM_DEVICE_POWER_DOMAIN_DYNAMIC_NUM
                 */
                while ((rv[i] != Z_DEVICE_DEPS_ENDS) &&
                       (rv[i] != DEVICE_HANDLE_NULL)) {
                        ++i;
                }
                *count = i;
        }
 
        return rv;
}
 
int device_required_foreach(const struct device *dev,
                            device_visitor_callback_t visitor_cb,
                            void *context);
 
int device_supported_foreach(const struct device *dev,
                             device_visitor_callback_t visitor_cb,
                             void *context);
 
#endif /* CONFIG_DEVICE_DEPS */
 
__syscall const struct device *device_get_binding(const char *name);
 
size_t z_device_get_all_static(const struct device **devices);
 
__syscall bool device_is_ready(const struct device *dev);
 
__syscall int device_init(const struct device *dev);
 
#define Z_DEVICE_STATE_NAME(dev_id) _CONCAT(__devstate_, dev_id)
 
#define Z_DEVICE_STATE_DEFINE(dev_id)                                          \
        static Z_DECL_ALIGN(struct device_state) Z_DEVICE_STATE_NAME(dev_id)   \
                __attribute__((__section__(".z_devstate")))
 
#if defined(CONFIG_DEVICE_DEPS) || defined(__DOXYGEN__)
 
#define Z_DEVICE_DEPS_NAME(dev_id) _CONCAT(__devicedeps_, dev_id)
 
#define Z_DEVICE_EXTRA_DEPS(...)                                            \
        FOR_EACH_NONEMPTY_TERM(IDENTITY, (,), __VA_ARGS__)
 
#define Z_DEVICE_DEPS_SECTION                                               \
        __attribute__((__section__(".__device_deps_pass1")))
 
#ifdef __cplusplus
#define Z_DEVICE_DEPS_EXTERN extern
#else
#define Z_DEVICE_DEPS_EXTERN
#endif
 
#define Z_DEVICE_DEPS_DEFINE(node_id, dev_id, ...)                             \
        extern Z_DEVICE_DEPS_CONST device_handle_t Z_DEVICE_DEPS_NAME(         \
                dev_id)[];                                                     \
        Z_DEVICE_DEPS_CONST Z_DECL_ALIGN(device_handle_t)                      \
        Z_DEVICE_DEPS_SECTION Z_DEVICE_DEPS_EXTERN __weak                      \
                Z_DEVICE_DEPS_NAME(dev_id)[] = {                               \
                COND_CODE_1(                                                   \
                        DT_NODE_EXISTS(node_id),                               \
                        (DT_DEP_ORD(node_id), DT_REQUIRES_DEP_ORDS(node_id)),  \
                        (DEVICE_HANDLE_NULL,))                             \
                Z_DEVICE_DEPS_SEP,                                             \
                Z_DEVICE_EXTRA_DEPS(__VA_ARGS__)                           \
                Z_DEVICE_DEPS_SEP,                                             \
                COND_CODE_1(DT_NODE_EXISTS(node_id),                           \
                            (DT_SUPPORTS_DEP_ORDS(node_id)), ())           \
        }
 
#endif /* CONFIG_DEVICE_DEPS */
#if defined(CONFIG_DEVICE_DT_METADATA) || defined(__DOXYGEN__)
struct device_dt_nodelabels {
        /* @brief number of elements in the nodelabels array */
        size_t num_nodelabels;
        /* @brief array of node labels as strings, exactly as they
         *        appear in the final devicetree
         */
        const char *nodelabels[];
};
 
struct device_dt_metadata {
        const struct device_dt_nodelabels *nl;
};
 
__syscall const struct device *device_get_by_dt_nodelabel(const char *nodelabel);
 
static inline const struct device_dt_nodelabels *
device_get_dt_nodelabels(const struct device *dev)
{
        if (dev->dt_meta == NULL) {
                return NULL;
        }
        return dev->dt_meta->nl;
}
 
#define Z_DEVICE_MAX_NODELABEL_LEN Z_DEVICE_MAX_NAME_LEN
 
#define Z_DEVICE_DT_METADATA_NAME_GET(dev_id) UTIL_CAT(__dev_dt_meta_, dev_id)
 
#define Z_DEVICE_DT_NODELABELS_NAME_GET(dev_id) UTIL_CAT(__dev_dt_nodelabels_, dev_id)
 
#define Z_DEVICE_DT_METADATA_DEFINE(node_id, dev_id)                    \
        static const struct device_dt_nodelabels                        \
        Z_DEVICE_DT_NODELABELS_NAME_GET(dev_id) = {                     \
                .num_nodelabels = DT_NUM_NODELABELS(node_id),           \
                .nodelabels = DT_NODELABEL_STRING_ARRAY(node_id),       \
        };                                                              \
                                                                        \
        static const struct device_dt_metadata                          \
        Z_DEVICE_DT_METADATA_NAME_GET(dev_id) = {                       \
                .nl = &Z_DEVICE_DT_NODELABELS_NAME_GET(dev_id),                 \
        };
#endif  /* CONFIG_DEVICE_DT_METADATA */
 
#define Z_DEVICE_INIT_SUB_PRIO(node_id)                                        \
        COND_CODE_1(DT_NODE_EXISTS(node_id),                                   \
                    (DT_DEP_ORD_STR_SORTABLE(node_id)), (0))
 
#define Z_DEVICE_MAX_NAME_LEN 48U
 
#define Z_DEVICE_NAME_CHECK(name)                                              \
        BUILD_ASSERT(sizeof(Z_STRINGIFY(name)) <= Z_DEVICE_MAX_NAME_LEN,       \
                            Z_STRINGIFY(DEVICE_NAME_GET(name)) " too long")
 
#define Z_DEVICE_INIT(name_, pm_, data_, config_, api_, state_, deps_, node_id_,        \
                      dev_id_)                                                          \
        {                                                                               \
                .name = name_,                                                          \
                .config = (config_),                                                    \
                .api = (api_),                                                          \
                .state = (state_),                                                      \
                .data = (data_),                                                        \
                IF_ENABLED(CONFIG_DEVICE_DEPS, (.deps = (deps_),))                      \
                IF_ENABLED(CONFIG_PM_DEVICE, Z_DEVICE_INIT_PM_BASE(pm_))                \
                IF_ENABLED(CONFIG_DEVICE_DT_METADATA,                                   \
                           (IF_ENABLED(DT_NODE_EXISTS(node_id_),                        \
                                       (.dt_meta = &Z_DEVICE_DT_METADATA_NAME_GET(      \
                                                dev_id_),))))                           \
        }
 
/*
 * Anonymous unions require C11. Some pre-C11 gcc versions have early support for anonymous
 * unions but they require these braces when combined with C99 designated initializers. For
 * more details see https://docs.zephyrproject.org/latest/develop/languages/cpp/
 */
#if defined(__STDC_VERSION__) && (__STDC_VERSION__) < 201100
#  define Z_DEVICE_INIT_PM_BASE(pm_) ({ .pm_base = (pm_),},)
#else
#  define Z_DEVICE_INIT_PM_BASE(pm_)   (.pm_base = (pm_),)
#endif
 
#define Z_DEVICE_SECTION_NAME(level, prio)                                     \
        _CONCAT(INIT_LEVEL_ORD(level), _##prio)
 
#define Z_DEVICE_BASE_DEFINE(node_id, dev_id, name, pm, data, config, level, prio, api, state,     \
                             deps)                                                    \
        COND_CODE_1(DT_NODE_EXISTS(node_id), (), (static))                                         \
        COND_CODE_1(Z_DEVICE_IS_MUTABLE(node_id), (), (const))                                     \
        STRUCT_SECTION_ITERABLE_NAMED_ALTERNATE(                                                   \
                device, COND_CODE_1(Z_DEVICE_IS_MUTABLE(node_id), (device_mutable), (device)),     \
                Z_DEVICE_SECTION_NAME(level, prio), DEVICE_NAME_GET(dev_id)) =                     \
                Z_DEVICE_INIT(name, pm, data, config, api, state, deps, node_id, dev_id)
 
#define Z_DEVICE_CHECK_INIT_LEVEL(level)                                       \
        COND_CODE_1(Z_INIT_PRE_KERNEL_1_##level, (),                           \
        (COND_CODE_1(Z_INIT_PRE_KERNEL_2_##level, (),                          \
        (COND_CODE_1(Z_INIT_POST_KERNEL_##level, (),                           \
        (ZERO_OR_COMPILE_ERROR(0)))))))
 
#define Z_DEVICE_INIT_ENTRY_DEFINE(node_id, dev_id, init_fn_, level, prio)                         \
        Z_DEVICE_CHECK_INIT_LEVEL(level)                                                           \
                                                                                                   \
        static const Z_DECL_ALIGN(struct init_entry) __used __noasan Z_INIT_ENTRY_SECTION(         \
                level, prio, Z_DEVICE_INIT_SUB_PRIO(node_id))                                      \
                Z_INIT_ENTRY_NAME(DEVICE_NAME_GET(dev_id)) = {                                     \
                        .init_fn = {COND_CODE_1(Z_DEVICE_IS_MUTABLE(node_id), (.dev_rw), (.dev)) = \
                                            (init_fn_)},                                           \
                        Z_DEVICE_INIT_ENTRY_DEV(node_id, dev_id),                                  \
        }
 
#define Z_DEFER_DEVICE_INIT_ENTRY_DEFINE(node_id, dev_id, init_fn_)                                \
        static const Z_DECL_ALIGN(struct init_entry) __used __noasan                               \
                __attribute__((__section__(".z_deferred_init")))                                   \
                Z_INIT_ENTRY_NAME(DEVICE_NAME_GET(dev_id)) = {                                     \
                        .init_fn = {COND_CODE_1(Z_DEVICE_IS_MUTABLE(node_id), (.dev_rw), (.dev)) = \
                                            (init_fn_)},                                           \
                        Z_DEVICE_INIT_ENTRY_DEV(node_id, dev_id),                                  \
        }
 
/*
 * Anonymous unions require C11. Some pre-C11 gcc versions have early support for anonymous
 * unions but they require these braces when combined with C99 designated initializers. For
 * more details see https://docs.zephyrproject.org/latest/develop/languages/cpp/
 */
#if defined(__STDC_VERSION__) && (__STDC_VERSION__) < 201100
#  define Z_DEVICE_INIT_ENTRY_DEV(node_id, dev_id) { Z_DEV_ENTRY_DEV(node_id, dev_id) }
#else
#  define Z_DEVICE_INIT_ENTRY_DEV(node_id, dev_id)   Z_DEV_ENTRY_DEV(node_id, dev_id)
#endif
 
#define Z_DEV_ENTRY_DEV(node_id, dev_id)                                                           \
        COND_CODE_1(Z_DEVICE_IS_MUTABLE(node_id), (.dev_rw), (.dev)) =  &DEVICE_NAME_GET(dev_id)
 
#define Z_DEVICE_DEFINE(node_id, dev_id, name, init_fn, pm, data, config,       \
                        level, prio, api, state, ...)                           \
        Z_DEVICE_NAME_CHECK(name);                                              \
                                                                                \
        IF_ENABLED(CONFIG_DEVICE_DEPS,                                          \
                   (Z_DEVICE_DEPS_DEFINE(node_id, dev_id, __VA_ARGS__);))       \
                                                                                \
        IF_ENABLED(CONFIG_DEVICE_DT_METADATA,                                   \
                   (IF_ENABLED(DT_NODE_EXISTS(node_id),                         \
                              (Z_DEVICE_DT_METADATA_DEFINE(node_id, dev_id);))))\
                                                                                \
        Z_DEVICE_BASE_DEFINE(node_id, dev_id, name, pm, data, config, level,    \
                prio, api, state, Z_DEVICE_DEPS_NAME(dev_id));                   \
        COND_CODE_1(DEVICE_DT_DEFER(node_id),                                   \
                    (Z_DEFER_DEVICE_INIT_ENTRY_DEFINE(node_id, dev_id,          \
                                                      init_fn)),                \
                    (Z_DEVICE_INIT_ENTRY_DEFINE(node_id, dev_id, init_fn,       \
                                                level, prio)));
 
#define Z_MAYBE_DEVICE_DECLARE_INTERNAL(node_id)                                                   \
        extern COND_CODE_1(Z_DEVICE_IS_MUTABLE(node_id), (),                                       \
                           (const)) struct device DEVICE_DT_NAME_GET(node_id);
 
DT_FOREACH_STATUS_OKAY_NODE(Z_MAYBE_DEVICE_DECLARE_INTERNAL)
 
 
#ifdef __cplusplus
}
#endif
 
#include <zephyr/syscalls/device.h>
 
#endif /* ZEPHYR_INCLUDE_DEVICE_H_ */