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/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
 
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/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_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;
 
#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__)
        struct pm_device *pm;
#endif
};
 
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);
 
bool z_device_is_ready(const struct device *dev);
 
__syscall bool device_is_ready(const struct device *dev);
 
static inline bool z_impl_device_is_ready(const struct device *dev)
{
        return z_device_is_ready(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 */
 
#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_)         \
        {                                                                      \
                .name = name_,                                                 \
                .config = (config_),                                           \
                .api = (api_),                                                 \
                .state = (state_),                                             \
                .data = (data_),                                               \
                IF_ENABLED(CONFIG_DEVICE_DEPS, (.deps = (deps_),))         \
                IF_ENABLED(CONFIG_PM_DEVICE, (.pm = (pm_),))               \
        }
 
#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))                     \
        const STRUCT_SECTION_ITERABLE_NAMED(device,                            \
                Z_DEVICE_SECTION_NAME(level, prio),                            \
                DEVICE_NAME_GET(dev_id)) =                                     \
                Z_DEVICE_INIT(name, pm, data, config, api, state, deps)
 
/* deprecated device initialization levels */
#define Z_DEVICE_LEVEL_DEPRECATED_EARLY                                        \
        __WARN("EARLY device driver level is deprecated")
#define Z_DEVICE_LEVEL_DEPRECATED_PRE_KERNEL_1
#define Z_DEVICE_LEVEL_DEPRECATED_PRE_KERNEL_2
#define Z_DEVICE_LEVEL_DEPRECATED_POST_KERNEL
#define Z_DEVICE_LEVEL_DEPRECATED_APPLICATION                                  \
        __WARN("APPLICATION device driver level is deprecated")
#define Z_DEVICE_LEVEL_DEPRECATED_SMP                                          \
        __WARN("SMP device driver level is deprecated")
 
#define Z_DEVICE_LEVEL_CHECK_DEPRECATED_LEVEL(level)                           \
        Z_DEVICE_LEVEL_DEPRECATED_##level
 
#define Z_DEVICE_INIT_ENTRY_DEFINE(node_id, dev_id, init_fn_, level, prio)     \
        Z_DEVICE_LEVEL_CHECK_DEPRECATED_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 = {.dev = (init_fn_)},                        \
                        .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__);))      \
                                                                               \
        Z_DEVICE_BASE_DEFINE(node_id, dev_id, name, pm, data, config, level,   \
                             prio, api, state, Z_DEVICE_DEPS_NAME(dev_id));    \
                                                                               \
        Z_DEVICE_INIT_ENTRY_DEFINE(node_id, dev_id, init_fn, level, prio)
 
#if defined(CONFIG_HAS_DTS) || defined(__DOXYGEN__)
#define Z_MAYBE_DEVICE_DECLARE_INTERNAL(node_id)                               \
        extern const struct device DEVICE_DT_NAME_GET(node_id);
 
DT_FOREACH_STATUS_OKAY_NODE(Z_MAYBE_DEVICE_DECLARE_INTERNAL)
#endif /* CONFIG_HAS_DTS */
 
#ifdef __cplusplus
}
#endif
 
#include <syscalls/device.h>
 
#endif /* ZEPHYR_INCLUDE_DEVICE_H_ */