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 CONFIG_LLEXT
#include <zephyr/llext/symbol.h>
#endif
 
#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)
 
/* This macro synthesizes a unique dev_id from a devicetree node by using
 * the node's dependency ordinal.
 *
 * 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_DEP_ORD(node_id) _CONCAT(dts_ord_, DT_DEP_ORD(node_id))
 
/* Same as above, but uses the hash of the node path instead of the ordinal.
 *
 * The hash used in this name can be mapped to the path by
 * examining zephyr/include/generated/zephyr/devicetree_generated.h.
 */
#define Z_DEVICE_DT_HASH(node_id) _CONCAT(dts_, DT_NODE_HASH(node_id))
 
/* By default, device identifiers are obtained using the dependency ordinal.
 * When LLEXT_EXPORT_DEV_IDS_BY_HASH is defined, the main Zephyr binary exports
 * DT identifiers via EXPORT_GROUP_SYMBOL_NAMED as hashed versions of their
 * paths. When matching extensions are built, that is what they need to look
 * for.
 *
 * The ordinal or hash used in this name can be mapped to the path by
 * examining zephyr/include/generated/zephyr/devicetree_generated.h.
 */
#if defined(LL_EXTENSION_BUILD) && defined(CONFIG_LLEXT_EXPORT_DEV_IDS_BY_HASH)
#define Z_DEVICE_DT_DEV_ID(node_id) Z_DEVICE_DT_HASH(node_id)
#else
#define Z_DEVICE_DT_DEV_ID(node_id) Z_DEVICE_DT_DEP_ORD(node_id)
#endif
 
#if defined(CONFIG_LLEXT_EXPORT_DEV_IDS_BY_HASH)
/* Export device identifiers by hash */
#define Z_DEVICE_EXPORT(node_id)                                               \
        EXPORT_GROUP_SYMBOL_NAMED(DEVICE,                                      \
                                  DEVICE_DT_NAME_GET(node_id),                 \
                                  DEVICE_NAME_GET(Z_DEVICE_DT_HASH(node_id)))
#else
/* Export device identifiers using the builtin name */
#define Z_DEVICE_EXPORT(node_id)                                               \
        EXPORT_GROUP_SYMBOL(DEVICE, DEVICE_DT_NAME_GET(node_id))
#endif

#define DEVICE_DEINIT_DEFINE(dev_id, name, init_fn, deinit_fn, pm, data,       \
                             config, level, prio, api)                         \
        Z_DEVICE_STATE_DEFINE(dev_id);                                         \
        Z_DEVICE_DEFINE(DT_INVALID_NODE, dev_id, name, init_fn, deinit_fn, 0U, \
                        pm, data, config, level, prio, api,                    \
                        &Z_DEVICE_STATE_NAME(dev_id))

#define DEVICE_DEFINE(dev_id, name, init_fn, pm, data, config, level, prio,    \
                      api)                                                     \
        DEVICE_DEINIT_DEFINE(dev_id, name, init_fn, NULL, pm, data, config,    \
                             level, prio, api)

#define DEVICE_DT_NAME(node_id)                                                \
        DT_PROP_OR(node_id, label, DT_NODE_FULL_NAME(node_id))

#define DEVICE_DT_DEINIT_DEFINE(node_id, init_fn, deinit_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, deinit_fn,           \
                        Z_DEVICE_DT_FLAGS(node_id), pm, data, config, level,   \
                        prio, api,                                             \
                        &Z_DEVICE_STATE_NAME(Z_DEVICE_DT_DEV_ID(node_id)),     \
                        __VA_ARGS__)

#define DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, level, prio, api, \
                         ...)                                                  \
        DEVICE_DT_DEINIT_DEFINE(node_id, init_fn, NULL, pm, data, config,      \
                                level, prio, api, __VA_ARGS__)

#define DEVICE_DT_INST_DEINIT_DEFINE(inst, ...)                                \
        DEVICE_DT_DEINIT_DEFINE(DT_DRV_INST(inst), __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_OKAY(node_id),                          \
                    (DEVICE_DT_GET(node_id)), (NULL))

#define DEVICE_DT_GET_BY_IDX(node_id, prop, idx) \
        DEVICE_DT_GET(DT_PHANDLE_BY_IDX(node_id, prop, idx))

#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

typedef uint8_t device_flags_t;


#define DEVICE_FLAG_INIT_DEFERRED BIT(0)


struct device_ops {
        int (*init)(const struct device *dev);
#ifdef CONFIG_DEVICE_DEINIT_SUPPORT
        int (*deinit)(const struct device *dev);
#endif /* CONFIG_DEVICE_DEINIT_SUPPORT */
};

struct device {
        const char *name;
        const void *config;
        const void *api;
        struct device_state *state;
        void *data;
        struct device_ops ops;
        device_flags_t flags;
#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);

__syscall int device_deinit(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")))

#define Z_DEVICE_DT_FLAGS(node_id)                                             \
        (DT_PROP_OR(node_id, zephyr_deferred_init, 0U) * DEVICE_FLAG_INIT_DEFERRED)
 
#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(name) " too long")

#define Z_DEVICE_OPS(init_fn_, deinit_fn_)                                     \
        {                                                                      \
                .init = (init_fn_),                                            \
                IF_ENABLED(CONFIG_DEVICE_DEINIT_SUPPORT,                       \
                           (.deinit = (deinit_fn_),))                          \
        }

#define Z_DEVICE_INIT(name_, init_fn_, deinit_fn_, flags_, pm_, data_, config_, api_,   \
                      state_, deps_, node_id_, dev_id_)                                 \
        {                                                                               \
                .name = name_,                                                          \
                .config = (config_),                                                    \
                .api = (api_),                                                          \
                .state = (state_),                                                      \
                .data = (data_),                                                        \
                .ops = Z_DEVICE_OPS(init_fn_, deinit_fn_),                              \
                .flags = (flags_),                                                      \
                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, init_fn, deinit_fn, flags, 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, init_fn, deinit_fn, flags, pm, data, config, api, state, deps, \
                              node_id, dev_id)

#define Z_DEVICE_CHECK_INIT_LEVEL(level)                                       \
        COND_CASE_1(Z_INIT_PRE_KERNEL_1_##level, (),                           \
                    Z_INIT_PRE_KERNEL_2_##level, (),                           \
                    Z_INIT_POST_KERNEL_##level, (),                            \
                    (ZERO_OR_COMPILE_ERROR(0)))

#define Z_DEVICE_INIT_ENTRY_DEFINE(node_id, dev_id, 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 = NULL,                                                           \
                        .dev = (const struct device *)&DEVICE_NAME_GET(dev_id),                    \
                }

#define Z_DEVICE_DEFINE(node_id, dev_id, name, init_fn, deinit_fn, flags, 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, init_fn, deinit_fn, flags,  \
                             pm, data, config, level, prio, api, state,         \
                             Z_DEVICE_DEPS_NAME(dev_id));                       \
                                                                                \
        Z_DEVICE_INIT_ENTRY_DEFINE(node_id, dev_id, level, prio);               \
                                                                                \
        IF_ENABLED(CONFIG_LLEXT,                                                \
                   (IF_ENABLED(DT_NODE_EXISTS(node_id),                         \
                                (Z_DEVICE_EXPORT(node_id);))))

#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)
 

#define Z_DEVICE_API_TYPE(_class) _CONCAT(_class, _driver_api)


#define DEVICE_API(_class, _name) const STRUCT_SECTION_ITERABLE(Z_DEVICE_API_TYPE(_class), _name)

#define DEVICE_API_GET(_class, _dev) ((const struct Z_DEVICE_API_TYPE(_class) *)_dev->api)

#define DEVICE_API_IS(_class, _dev)                                                                \
        ({                                                                                         \
                STRUCT_SECTION_START_EXTERN(Z_DEVICE_API_TYPE(_class));                            \
                STRUCT_SECTION_END_EXTERN(Z_DEVICE_API_TYPE(_class));                              \
                (DEVICE_API_GET(_class, _dev) < STRUCT_SECTION_END(Z_DEVICE_API_TYPE(_class)) &&   \
                 DEVICE_API_GET(_class, _dev) >= STRUCT_SECTION_START(Z_DEVICE_API_TYPE(_class))); \
        })
 
#ifdef __cplusplus
}
#endif
 
#include <zephyr/syscalls/device.h>
 
#endif /* ZEPHYR_INCLUDE_DEVICE_H_ */