Line data Source code
1 0 : /*
2 : * Copyright (c) 2015 Intel Corporation.
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : #ifndef ZEPHYR_INCLUDE_DEVICE_H_
8 : #define ZEPHYR_INCLUDE_DEVICE_H_
9 :
10 : #include <stdint.h>
11 :
12 : #include <zephyr/devicetree.h>
13 : #include <zephyr/init.h>
14 : #include <zephyr/linker/sections.h>
15 : #include <zephyr/pm/state.h>
16 : #include <zephyr/sys/device_mmio.h>
17 : #include <zephyr/sys/iterable_sections.h>
18 : #include <zephyr/sys/util.h>
19 : #include <zephyr/toolchain.h>
20 :
21 : #ifdef CONFIG_LLEXT
22 : #include <zephyr/llext/symbol.h>
23 : #endif
24 :
25 : #ifdef __cplusplus
26 : extern "C" {
27 : #endif
28 :
29 : /**
30 : * @brief Device Model
31 : * @defgroup device_model Device Model
32 : * @since 1.0
33 : * @version 1.1.0
34 : * @{
35 : */
36 :
37 : /** @cond INTERNAL_HIDDEN */
38 :
39 : /**
40 : * @brief Flag value used in lists of device dependencies to separate distinct
41 : * groups.
42 : */
43 : #define Z_DEVICE_DEPS_SEP INT16_MIN
44 :
45 : /**
46 : * @brief Flag value used in lists of device dependencies to indicate the end of
47 : * the list.
48 : */
49 : #define Z_DEVICE_DEPS_ENDS INT16_MAX
50 :
51 : /** @brief Determine if a DT node is mutable */
52 : #define Z_DEVICE_IS_MUTABLE(node_id) \
53 : COND_CODE_1(IS_ENABLED(CONFIG_DEVICE_MUTABLE), (DT_PROP(node_id, zephyr_mutable)), (0))
54 :
55 : /** @endcond */
56 :
57 : /**
58 : * @brief Type used to represent a "handle" for a device.
59 : *
60 : * Every @ref device has an associated handle. You can get a pointer to a
61 : * @ref device from its handle and vice versa, but the handle uses less space
62 : * than a pointer. The device.h API mainly uses handles to store lists of
63 : * multiple devices in a compact way.
64 : *
65 : * The extreme values and zero have special significance. Negative values
66 : * identify functionality that does not correspond to a Zephyr device, such as
67 : * the system clock or a SYS_INIT() function.
68 : *
69 : * @see device_handle_get()
70 : * @see device_from_handle()
71 : */
72 1 : typedef int16_t device_handle_t;
73 :
74 : /** @brief Flag value used to identify an unknown device. */
75 1 : #define DEVICE_HANDLE_NULL 0
76 :
77 : /**
78 : * @brief Expands to the name of a global device object.
79 : *
80 : * Return the full name of a device object symbol created by DEVICE_DEFINE(),
81 : * using the `dev_id` provided to DEVICE_DEFINE(). This is the name of the
82 : * global variable storing the device structure, not a pointer to the string in
83 : * the @ref device.name field.
84 : *
85 : * It is meant to be used for declaring extern symbols pointing to device
86 : * objects before using the DEVICE_GET macro to get the device object.
87 : *
88 : * This macro is normally only useful within device driver source code. In other
89 : * situations, you are probably looking for device_get_binding().
90 : *
91 : * @param dev_id Device identifier.
92 : *
93 : * @return The full name of the device object defined by device definition
94 : * macros.
95 : */
96 1 : #define DEVICE_NAME_GET(dev_id) _CONCAT(__device_, dev_id)
97 :
98 : /* This macro synthesizes a unique dev_id from a devicetree node by using
99 : * the node's dependency ordinal.
100 : *
101 : * The ordinal used in this name can be mapped to the path by
102 : * examining zephyr/include/generated/zephyr/devicetree_generated.h.
103 : */
104 : #define Z_DEVICE_DT_DEV_ID(node_id) _CONCAT(dts_ord_, DT_DEP_ORD(node_id))
105 :
106 : #if defined(CONFIG_LLEXT_EXPORT_DEVICES)
107 : /* Export device identifiers using the builtin name */
108 : #define Z_DEVICE_EXPORT(node_id) EXPORT_SYMBOL(DEVICE_DT_NAME_GET(node_id))
109 : #endif
110 :
111 : /**
112 : * @brief Create a device object and set it up for boot time initialization.
113 : *
114 : * This macro defines a @ref device that is automatically configured by the
115 : * kernel during system initialization. This macro should only be used when the
116 : * device is not being allocated from a devicetree node. If you are allocating a
117 : * device from a devicetree node, use DEVICE_DT_DEFINE() or
118 : * DEVICE_DT_INST_DEFINE() instead.
119 : *
120 : * @param dev_id A unique token which is used in the name of the global device
121 : * structure as a C identifier.
122 : * @param name A string name for the device, which will be stored in
123 : * @ref device.name. This name can be used to look up the device with
124 : * device_get_binding(). This must be less than Z_DEVICE_MAX_NAME_LEN characters
125 : * (including terminating `NULL`) in order to be looked up from user mode.
126 : * @param init_fn Pointer to the device's initialization function, which will be
127 : * run by the kernel during system initialization. Can be `NULL`.
128 : * @param pm Pointer to the device's power management resources, a
129 : * @ref pm_device, which will be stored in @ref device.pm field. Use `NULL` if
130 : * the device does not use PM.
131 : * @param data Pointer to the device's private mutable data, which will be
132 : * stored in @ref device.data.
133 : * @param config Pointer to the device's private constant data, which will be
134 : * stored in @ref device.config.
135 : * @param level The device's initialization level (PRE_KERNEL_1, PRE_KERNEL_2 or
136 : * POST_KERNEL).
137 : * @param prio The device's priority within its initialization level. See
138 : * SYS_INIT() for details.
139 : * @param api Pointer to the device's API structure. Can be `NULL`.
140 : */
141 : #define DEVICE_DEFINE(dev_id, name, init_fn, pm, data, config, level, prio, \
142 1 : api) \
143 : Z_DEVICE_STATE_DEFINE(dev_id); \
144 : Z_DEVICE_DEFINE(DT_INVALID_NODE, dev_id, name, init_fn, pm, data, \
145 : config, level, prio, api, \
146 : &Z_DEVICE_STATE_NAME(dev_id))
147 :
148 : /**
149 : * @brief Return a string name for a devicetree node.
150 : *
151 : * This macro returns a string literal usable as a device's name from a
152 : * devicetree node identifier.
153 : *
154 : * @param node_id The devicetree node identifier.
155 : *
156 : * @return The value of the node's `label` property, if it has one.
157 : * Otherwise, the node's full name in `node-name@unit-address` form.
158 : */
159 1 : #define DEVICE_DT_NAME(node_id) \
160 : DT_PROP_OR(node_id, label, DT_NODE_FULL_NAME(node_id))
161 :
162 : /**
163 : * @brief Determine if a devicetree node initialization should be deferred.
164 : *
165 : * @param node_id The devicetree node identifier.
166 : *
167 : * @return Boolean stating if node initialization should be deferred.
168 : */
169 1 : #define DEVICE_DT_DEFER(node_id) \
170 : DT_PROP(node_id, zephyr_deferred_init)
171 :
172 : /**
173 : * @brief Create a device object from a devicetree node identifier and set it up
174 : * for boot time initialization.
175 : *
176 : * This macro defines a @ref device that is automatically configured by the
177 : * kernel during system initialization. The global device object's name as a C
178 : * identifier is derived from the node's dependency ordinal. @ref device.name is
179 : * set to `DEVICE_DT_NAME(node_id)`.
180 : *
181 : * The device is declared with extern visibility, so a pointer to a global
182 : * device object can be obtained with `DEVICE_DT_GET(node_id)` from any source
183 : * file that includes `<zephyr/device.h>` (even from extensions, when
184 : * @kconfig{CONFIG_LLEXT_EXPORT_DEVICES} is enabled). Before using the
185 : * pointer, the referenced object should be checked using device_is_ready().
186 : *
187 : * @param node_id The devicetree node identifier.
188 : * @param init_fn Pointer to the device's initialization function, which will be
189 : * run by the kernel during system initialization. Can be `NULL`.
190 : * @param pm Pointer to the device's power management resources, a
191 : * @ref pm_device, which will be stored in @ref device.pm. Use `NULL` if the
192 : * device does not use PM.
193 : * @param data Pointer to the device's private mutable data, which will be
194 : * stored in @ref device.data.
195 : * @param config Pointer to the device's private constant data, which will be
196 : * stored in @ref device.config field.
197 : * @param level The device's initialization level (PRE_KERNEL_1, PRE_KERNEL_2 or
198 : * POST_KERNEL).
199 : * @param prio The device's priority within its initialization level. See
200 : * SYS_INIT() for details.
201 : * @param api Pointer to the device's API structure. Can be `NULL`.
202 : */
203 : #define DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, level, prio, api, \
204 1 : ...) \
205 : Z_DEVICE_STATE_DEFINE(Z_DEVICE_DT_DEV_ID(node_id)); \
206 : Z_DEVICE_DEFINE(node_id, Z_DEVICE_DT_DEV_ID(node_id), \
207 : DEVICE_DT_NAME(node_id), init_fn, pm, data, config, \
208 : level, prio, api, \
209 : &Z_DEVICE_STATE_NAME(Z_DEVICE_DT_DEV_ID(node_id)), \
210 : __VA_ARGS__)
211 :
212 : /**
213 : * @brief Like DEVICE_DT_DEFINE(), but uses an instance of a `DT_DRV_COMPAT`
214 : * compatible instead of a node identifier.
215 : *
216 : * @param inst Instance number. The `node_id` argument to DEVICE_DT_DEFINE() is
217 : * set to `DT_DRV_INST(inst)`.
218 : * @param ... Other parameters as expected by DEVICE_DT_DEFINE().
219 : */
220 1 : #define DEVICE_DT_INST_DEFINE(inst, ...) \
221 : DEVICE_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)
222 :
223 : /**
224 : * @brief The name of the global device object for @p node_id
225 : *
226 : * Returns the name of the global device structure as a C identifier. The device
227 : * must be allocated using DEVICE_DT_DEFINE() or DEVICE_DT_INST_DEFINE() for
228 : * this to work.
229 : *
230 : * This macro is normally only useful within device driver source code. In other
231 : * situations, you are probably looking for DEVICE_DT_GET().
232 : *
233 : * @param node_id Devicetree node identifier
234 : *
235 : * @return The name of the device object as a C identifier
236 : */
237 1 : #define DEVICE_DT_NAME_GET(node_id) DEVICE_NAME_GET(Z_DEVICE_DT_DEV_ID(node_id))
238 :
239 : /**
240 : * @brief Get a @ref device reference from a devicetree node identifier.
241 : *
242 : * Returns a pointer to a device object created from a devicetree node, if any
243 : * device was allocated by a driver.
244 : *
245 : * If no such device was allocated, this will fail at linker time. If you get an
246 : * error that looks like `undefined reference to __device_dts_ord_<N>`, that is
247 : * what happened. Check to make sure your device driver is being compiled,
248 : * usually by enabling the Kconfig options it requires.
249 : *
250 : * @param node_id A devicetree node identifier
251 : *
252 : * @return A pointer to the device object created for that node
253 : */
254 1 : #define DEVICE_DT_GET(node_id) (&DEVICE_DT_NAME_GET(node_id))
255 :
256 : /**
257 : * @brief Get a @ref device reference for an instance of a `DT_DRV_COMPAT`
258 : * compatible.
259 : *
260 : * This is equivalent to `DEVICE_DT_GET(DT_DRV_INST(inst))`.
261 : *
262 : * @param inst `DT_DRV_COMPAT` instance number
263 : * @return A pointer to the device object created for that instance
264 : */
265 1 : #define DEVICE_DT_INST_GET(inst) DEVICE_DT_GET(DT_DRV_INST(inst))
266 :
267 : /**
268 : * @brief Get a @ref device reference from a devicetree compatible.
269 : *
270 : * If an enabled devicetree node has the given compatible and a device
271 : * object was created from it, this returns a pointer to that device.
272 : *
273 : * If there no such devices, this returns NULL.
274 : *
275 : * If there are multiple, this returns an arbitrary one.
276 : *
277 : * If this returns non-NULL, the device must be checked for readiness
278 : * before use, e.g. with device_is_ready().
279 : *
280 : * @param compat lowercase-and-underscores devicetree compatible
281 : * @return a pointer to a device, or NULL
282 : */
283 1 : #define DEVICE_DT_GET_ANY(compat) \
284 : COND_CODE_1(DT_HAS_COMPAT_STATUS_OKAY(compat), \
285 : (DEVICE_DT_GET(DT_COMPAT_GET_ANY_STATUS_OKAY(compat))), \
286 : (NULL))
287 :
288 : /**
289 : * @brief Get a @ref device reference from a devicetree compatible.
290 : *
291 : * If an enabled devicetree node has the given compatible and a device object
292 : * was created from it, this returns a pointer to that device.
293 : *
294 : * If there are no such devices, this will fail at compile time.
295 : *
296 : * If there are multiple, this returns an arbitrary one.
297 : *
298 : * If this returns non-NULL, the device must be checked for readiness before
299 : * use, e.g. with device_is_ready().
300 : *
301 : * @param compat lowercase-and-underscores devicetree compatible
302 : * @return a pointer to a device
303 : */
304 1 : #define DEVICE_DT_GET_ONE(compat) \
305 : COND_CODE_1(DT_HAS_COMPAT_STATUS_OKAY(compat), \
306 : (DEVICE_DT_GET(DT_COMPAT_GET_ANY_STATUS_OKAY(compat))), \
307 : (ZERO_OR_COMPILE_ERROR(0)))
308 :
309 : /**
310 : * @brief Utility macro to obtain an optional reference to a device.
311 : *
312 : * If the node identifier refers to a node with status `okay`, this returns
313 : * `DEVICE_DT_GET(node_id)`. Otherwise, it returns `NULL`.
314 : *
315 : * @param node_id devicetree node identifier
316 : *
317 : * @return a @ref device reference for the node identifier, which may be `NULL`.
318 : */
319 1 : #define DEVICE_DT_GET_OR_NULL(node_id) \
320 : COND_CODE_1(DT_NODE_HAS_STATUS_OKAY(node_id), \
321 : (DEVICE_DT_GET(node_id)), (NULL))
322 :
323 : /**
324 : * @brief Obtain a pointer to a device object by name
325 : *
326 : * @details Return the address of a device object created by
327 : * DEVICE_DEFINE(), using the dev_id provided to DEVICE_DEFINE().
328 : *
329 : * @param dev_id Device identifier.
330 : *
331 : * @return A pointer to the device object created by DEVICE_DEFINE()
332 : */
333 1 : #define DEVICE_GET(dev_id) (&DEVICE_NAME_GET(dev_id))
334 :
335 : /**
336 : * @brief Declare a static device object
337 : *
338 : * This macro can be used at the top-level to declare a device, such
339 : * that DEVICE_GET() may be used before the full declaration in
340 : * DEVICE_DEFINE().
341 : *
342 : * This is often useful when configuring interrupts statically in a
343 : * device's init or per-instance config function, as the init function
344 : * itself is required by DEVICE_DEFINE() and use of DEVICE_GET()
345 : * inside it creates a circular dependency.
346 : *
347 : * @param dev_id Device identifier.
348 : */
349 1 : #define DEVICE_DECLARE(dev_id) \
350 : static const struct device DEVICE_NAME_GET(dev_id)
351 :
352 : /**
353 : * @brief Get a @ref init_entry reference from a devicetree node.
354 : *
355 : * @param node_id A devicetree node identifier
356 : *
357 : * @return A pointer to the @ref init_entry object created for that node
358 : */
359 1 : #define DEVICE_INIT_DT_GET(node_id) \
360 : (&Z_INIT_ENTRY_NAME(DEVICE_DT_NAME_GET(node_id)))
361 :
362 : /**
363 : * @brief Get a @ref init_entry reference from a device identifier.
364 : *
365 : * @param dev_id Device identifier.
366 : *
367 : * @return A pointer to the init_entry object created for that device
368 : */
369 1 : #define DEVICE_INIT_GET(dev_id) (&Z_INIT_ENTRY_NAME(DEVICE_NAME_GET(dev_id)))
370 :
371 : /**
372 : * @brief Runtime device dynamic structure (in RAM) per driver instance
373 : *
374 : * Fields in this are expected to be default-initialized to zero. The
375 : * kernel driver infrastructure and driver access functions are
376 : * responsible for ensuring that any non-zero initialization is done
377 : * before they are accessed.
378 : */
379 1 : struct device_state {
380 : /**
381 : * Device initialization return code (positive errno value).
382 : *
383 : * Device initialization functions return a negative errno code if they
384 : * fail. In Zephyr, errno values do not exceed 255, so we can store the
385 : * positive result value in a uint8_t type.
386 : */
387 1 : uint8_t init_res;
388 :
389 : /** Indicates the device initialization function has been
390 : * invoked.
391 : */
392 1 : bool initialized : 1;
393 : };
394 :
395 : struct pm_device_base;
396 : struct pm_device;
397 : struct pm_device_isr;
398 : #if defined(CONFIG_DEVICE_DT_METADATA) || defined(__DOXYGEN__)
399 : struct device_dt_metadata;
400 : #endif
401 :
402 : #ifdef CONFIG_DEVICE_DEPS_DYNAMIC
403 : #define Z_DEVICE_DEPS_CONST
404 : #else
405 : #define Z_DEVICE_DEPS_CONST const
406 : #endif
407 :
408 : /**
409 : * @brief Runtime device structure (in ROM) per driver instance
410 : */
411 1 : struct device {
412 : /** Name of the device instance */
413 1 : const char *name;
414 : /** Address of device instance config information */
415 1 : const void *config;
416 : /** Address of the API structure exposed by the device instance */
417 1 : const void *api;
418 : /** Address of the common device state */
419 1 : struct device_state *state;
420 : /** Address of the device instance private data */
421 1 : void *data;
422 : #if defined(CONFIG_DEVICE_DEPS) || defined(__DOXYGEN__)
423 : /**
424 : * Optional pointer to dependencies associated with the device.
425 : *
426 : * This encodes a sequence of sets of device handles that have some
427 : * relationship to this node. The individual sets are extracted with
428 : * dedicated API, such as device_required_handles_get(). Only available
429 : * if @kconfig{CONFIG_DEVICE_DEPS} is enabled.
430 : */
431 1 : Z_DEVICE_DEPS_CONST device_handle_t *deps;
432 : #endif /* CONFIG_DEVICE_DEPS */
433 : #if defined(CONFIG_PM_DEVICE) || defined(__DOXYGEN__)
434 : /**
435 : * Reference to the device PM resources (only available if
436 : * @kconfig{CONFIG_PM_DEVICE} is enabled).
437 : */
438 : union {
439 0 : struct pm_device_base *pm_base;
440 0 : struct pm_device *pm;
441 0 : struct pm_device_isr *pm_isr;
442 1 : };
443 : #endif
444 : #if defined(CONFIG_DEVICE_DT_METADATA) || defined(__DOXYGEN__)
445 0 : const struct device_dt_metadata *dt_meta;
446 : #endif /* CONFIG_DEVICE_DT_METADATA */
447 : };
448 :
449 : /**
450 : * @brief Get the handle for a given device
451 : *
452 : * @param dev the device for which a handle is desired.
453 : *
454 : * @return the handle for the device, or DEVICE_HANDLE_NULL if the device does
455 : * not have an associated handle.
456 : */
457 1 : static inline device_handle_t device_handle_get(const struct device *dev)
458 : {
459 : device_handle_t ret = DEVICE_HANDLE_NULL;
460 : STRUCT_SECTION_START_EXTERN(device);
461 :
462 : /* TODO: If/when devices can be constructed that are not part of the
463 : * fixed sequence we'll need another solution.
464 : */
465 : if (dev != NULL) {
466 : ret = 1 + (device_handle_t)(dev - STRUCT_SECTION_START(device));
467 : }
468 :
469 : return ret;
470 : }
471 :
472 : /**
473 : * @brief Get the device corresponding to a handle.
474 : *
475 : * @param dev_handle the device handle
476 : *
477 : * @return the device that has that handle, or a null pointer if @p dev_handle
478 : * does not identify a device.
479 : */
480 : static inline const struct device *
481 1 : device_from_handle(device_handle_t dev_handle)
482 : {
483 : STRUCT_SECTION_START_EXTERN(device);
484 : const struct device *dev = NULL;
485 : size_t numdev;
486 :
487 : STRUCT_SECTION_COUNT(device, &numdev);
488 :
489 : if ((dev_handle > 0) && ((size_t)dev_handle <= numdev)) {
490 : dev = &STRUCT_SECTION_START(device)[dev_handle - 1];
491 : }
492 :
493 : return dev;
494 : }
495 :
496 : #if defined(CONFIG_DEVICE_DEPS) || defined(__DOXYGEN__)
497 :
498 : /**
499 : * @brief Prototype for functions used when iterating over a set of devices.
500 : *
501 : * Such a function may be used in API that identifies a set of devices and
502 : * provides a visitor API supporting caller-specific interaction with each
503 : * device in the set.
504 : *
505 : * The visit is said to succeed if the visitor returns a non-negative value.
506 : *
507 : * @param dev a device in the set being iterated
508 : * @param context state used to support the visitor function
509 : *
510 : * @return A non-negative number to allow walking to continue, and a negative
511 : * error code to case the iteration to stop.
512 : *
513 : * @see device_required_foreach()
514 : * @see device_supported_foreach()
515 : */
516 1 : typedef int (*device_visitor_callback_t)(const struct device *dev,
517 : void *context);
518 :
519 : /**
520 : * @brief Get the device handles for devicetree dependencies of this device.
521 : *
522 : * This function returns a pointer to an array of device handles. The length of
523 : * the array is stored in the @p count parameter.
524 : *
525 : * The array contains a handle for each device that @p dev requires directly, as
526 : * determined from the devicetree. This does not include transitive
527 : * dependencies; you must recursively determine those.
528 : *
529 : * @param dev the device for which dependencies are desired.
530 : * @param count pointer to where this function should store the length of the
531 : * returned array. No value is stored if the call returns a null pointer. The
532 : * value may be set to zero if the device has no devicetree dependencies.
533 : *
534 : * @return a pointer to a sequence of @p count device handles, or a null pointer
535 : * if @p dev does not have any dependency data.
536 : */
537 : static inline const device_handle_t *
538 1 : device_required_handles_get(const struct device *dev, size_t *count)
539 : {
540 : const device_handle_t *rv = dev->deps;
541 :
542 : if (rv != NULL) {
543 : size_t i = 0;
544 :
545 : while ((rv[i] != Z_DEVICE_DEPS_ENDS) &&
546 : (rv[i] != Z_DEVICE_DEPS_SEP)) {
547 : ++i;
548 : }
549 : *count = i;
550 : }
551 :
552 : return rv;
553 : }
554 :
555 : /**
556 : * @brief Get the device handles for injected dependencies of this device.
557 : *
558 : * This function returns a pointer to an array of device handles. The length of
559 : * the array is stored in the @p count parameter.
560 : *
561 : * The array contains a handle for each device that @p dev manually injected as
562 : * a dependency, via providing extra arguments to Z_DEVICE_DEFINE. This does not
563 : * include transitive dependencies; you must recursively determine those.
564 : *
565 : * @param dev the device for which injected dependencies are desired.
566 : * @param count pointer to where this function should store the length of the
567 : * returned array. No value is stored if the call returns a null pointer. The
568 : * value may be set to zero if the device has no devicetree dependencies.
569 : *
570 : * @return a pointer to a sequence of @p *count device handles, or a null
571 : * pointer if @p dev does not have any dependency data.
572 : */
573 : static inline const device_handle_t *
574 1 : device_injected_handles_get(const struct device *dev, size_t *count)
575 : {
576 : const device_handle_t *rv = dev->deps;
577 : size_t region = 0;
578 : size_t i = 0;
579 :
580 : if (rv != NULL) {
581 : /* Fast forward to injected devices */
582 : while (region != 1) {
583 : if (*rv == Z_DEVICE_DEPS_SEP) {
584 : region++;
585 : }
586 : rv++;
587 : }
588 : while ((rv[i] != Z_DEVICE_DEPS_ENDS) &&
589 : (rv[i] != Z_DEVICE_DEPS_SEP)) {
590 : ++i;
591 : }
592 : *count = i;
593 : }
594 :
595 : return rv;
596 : }
597 :
598 : /**
599 : * @brief Get the set of handles that this device supports.
600 : *
601 : * This function returns a pointer to an array of device handles. The length of
602 : * the array is stored in the @p count parameter.
603 : *
604 : * The array contains a handle for each device that @p dev "supports" -- that
605 : * is, devices that require @p dev directly -- as determined from the
606 : * devicetree. This does not include transitive dependencies; you must
607 : * recursively determine those.
608 : *
609 : * @param dev the device for which supports are desired.
610 : * @param count pointer to where this function should store the length of the
611 : * returned array. No value is stored if the call returns a null pointer. The
612 : * value may be set to zero if nothing in the devicetree depends on @p dev.
613 : *
614 : * @return a pointer to a sequence of @p *count device handles, or a null
615 : * pointer if @p dev does not have any dependency data.
616 : */
617 : static inline const device_handle_t *
618 1 : device_supported_handles_get(const struct device *dev, size_t *count)
619 : {
620 : const device_handle_t *rv = dev->deps;
621 : size_t region = 0;
622 : size_t i = 0;
623 :
624 : if (rv != NULL) {
625 : /* Fast forward to supporting devices */
626 : while (region != 2) {
627 : if (*rv == Z_DEVICE_DEPS_SEP) {
628 : region++;
629 : }
630 : rv++;
631 : }
632 : /* Count supporting devices.
633 : * Trailing NULL's can be injected by gen_device_deps.py due to
634 : * CONFIG_PM_DEVICE_POWER_DOMAIN_DYNAMIC_NUM
635 : */
636 : while ((rv[i] != Z_DEVICE_DEPS_ENDS) &&
637 : (rv[i] != DEVICE_HANDLE_NULL)) {
638 : ++i;
639 : }
640 : *count = i;
641 : }
642 :
643 : return rv;
644 : }
645 :
646 : /**
647 : * @brief Visit every device that @p dev directly requires.
648 : *
649 : * Zephyr maintains information about which devices are directly required by
650 : * another device; for example an I2C-based sensor driver will require an I2C
651 : * controller for communication. Required devices can derive from
652 : * statically-defined devicetree relationships or dependencies registered at
653 : * runtime.
654 : *
655 : * This API supports operating on the set of required devices. Example uses
656 : * include making sure required devices are ready before the requiring device is
657 : * used, and releasing them when the requiring device is no longer needed.
658 : *
659 : * There is no guarantee on the order in which required devices are visited.
660 : *
661 : * If the @p visitor_cb function returns a negative value iteration is halted,
662 : * and the returned value from the visitor is returned from this function.
663 : *
664 : * @note This API is not available to unprivileged threads.
665 : *
666 : * @param dev a device of interest. The devices that this device depends on will
667 : * be used as the set of devices to visit. This parameter must not be null.
668 : * @param visitor_cb the function that should be invoked on each device in the
669 : * dependency set. This parameter must not be null.
670 : * @param context state that is passed through to the visitor function. This
671 : * parameter may be null if @p visitor_cb tolerates a null @p context.
672 : *
673 : * @return The number of devices that were visited if all visits succeed, or
674 : * the negative value returned from the first visit that did not succeed.
675 : */
676 1 : int device_required_foreach(const struct device *dev,
677 : device_visitor_callback_t visitor_cb,
678 : void *context);
679 :
680 : /**
681 : * @brief Visit every device that @p dev directly supports.
682 : *
683 : * Zephyr maintains information about which devices are directly supported by
684 : * another device; for example an I2C controller will support an I2C-based
685 : * sensor driver. Supported devices can derive from statically-defined
686 : * devicetree relationships.
687 : *
688 : * This API supports operating on the set of supported devices. Example uses
689 : * include iterating over the devices connected to a regulator when it is
690 : * powered on.
691 : *
692 : * There is no guarantee on the order in which required devices are visited.
693 : *
694 : * If the @p visitor_cb function returns a negative value iteration is halted,
695 : * and the returned value from the visitor is returned from this function.
696 : *
697 : * @note This API is not available to unprivileged threads.
698 : *
699 : * @param dev a device of interest. The devices that this device supports
700 : * will be used as the set of devices to visit. This parameter must not be null.
701 : * @param visitor_cb the function that should be invoked on each device in the
702 : * support set. This parameter must not be null.
703 : * @param context state that is passed through to the visitor function. This
704 : * parameter may be null if @p visitor_cb tolerates a null @p context.
705 : *
706 : * @return The number of devices that were visited if all visits succeed, or the
707 : * negative value returned from the first visit that did not succeed.
708 : */
709 1 : int device_supported_foreach(const struct device *dev,
710 : device_visitor_callback_t visitor_cb,
711 : void *context);
712 :
713 : #endif /* CONFIG_DEVICE_DEPS */
714 :
715 : /**
716 : * @brief Get a @ref device reference from its @ref device.name field.
717 : *
718 : * This function iterates through the devices on the system. If a device with
719 : * the given @p name field is found, and that device initialized successfully at
720 : * boot time, this function returns a pointer to the device.
721 : *
722 : * If no device has the given @p name, this function returns `NULL`.
723 : *
724 : * This function also returns NULL when a device is found, but it failed to
725 : * initialize successfully at boot time. (To troubleshoot this case, set a
726 : * breakpoint on your device driver's initialization function.)
727 : *
728 : * @param name device name to search for. A null pointer, or a pointer to an
729 : * empty string, will cause NULL to be returned.
730 : *
731 : * @return pointer to device structure with the given name; `NULL` if the device
732 : * is not found or if the device with that name's initialization function
733 : * failed.
734 : */
735 1 : __syscall const struct device *device_get_binding(const char *name);
736 :
737 : /**
738 : * @brief Get access to the static array of static devices.
739 : *
740 : * @param devices where to store the pointer to the array of statically
741 : * allocated devices. The array must not be mutated through this pointer.
742 : *
743 : * @return the number of statically allocated devices.
744 : */
745 : size_t z_device_get_all_static(const struct device **devices);
746 :
747 : /**
748 : * @brief Verify that a device is ready for use.
749 : *
750 : * Indicates whether the provided device pointer is for a device known to be
751 : * in a state where it can be used with its standard API.
752 : *
753 : * This can be used with device pointers captured from DEVICE_DT_GET(), which
754 : * does not include the readiness checks of device_get_binding(). At minimum
755 : * this means that the device has been successfully initialized.
756 : *
757 : * @param dev pointer to the device in question.
758 : *
759 : * @retval true If the device is ready for use.
760 : * @retval false If the device is not ready for use or if a NULL device pointer
761 : * is passed as argument.
762 : */
763 1 : __syscall bool device_is_ready(const struct device *dev);
764 :
765 : /**
766 : * @brief Initialize a device.
767 : *
768 : * A device whose initialization was deferred (by marking it as
769 : * ``zephyr,deferred-init`` on devicetree) needs to be initialized manually via
770 : * this call. Note that only devices whose initialization was deferred can be
771 : * initialized via this call - one can not try to initialize a non
772 : * initialization deferred device that failed initialization with this call.
773 : *
774 : * @param dev device to be initialized.
775 : *
776 : * @retval -ENOENT If device was not found - or isn't a deferred one.
777 : * @retval -errno For other errors.
778 : */
779 1 : __syscall int device_init(const struct device *dev);
780 :
781 : /**
782 : * @}
783 : */
784 :
785 : /** @cond INTERNAL_HIDDEN */
786 :
787 : /**
788 : * @brief Synthesize a unique name for the device state associated with
789 : * @p dev_id.
790 : */
791 : #define Z_DEVICE_STATE_NAME(dev_id) _CONCAT(__devstate_, dev_id)
792 :
793 : /**
794 : * @brief Utility macro to define and initialize the device state.
795 : *
796 : * @param dev_id Device identifier.
797 : */
798 : #define Z_DEVICE_STATE_DEFINE(dev_id) \
799 : static Z_DECL_ALIGN(struct device_state) Z_DEVICE_STATE_NAME(dev_id) \
800 : __attribute__((__section__(".z_devstate")))
801 :
802 : #if defined(CONFIG_DEVICE_DEPS) || defined(__DOXYGEN__)
803 :
804 : /**
805 : * @brief Synthesize the name of the object that holds device ordinal and
806 : * dependency data.
807 : *
808 : * @param dev_id Device identifier.
809 : */
810 : #define Z_DEVICE_DEPS_NAME(dev_id) _CONCAT(__devicedeps_, dev_id)
811 :
812 : /**
813 : * @brief Expand extra dependencies with a comma in between.
814 : *
815 : * @param ... Extra dependencies.
816 : */
817 : #define Z_DEVICE_EXTRA_DEPS(...) \
818 : FOR_EACH_NONEMPTY_TERM(IDENTITY, (,), __VA_ARGS__)
819 :
820 : /** @brief Linker section were device dependencies are placed. */
821 : #define Z_DEVICE_DEPS_SECTION \
822 : __attribute__((__section__(".__device_deps_pass1")))
823 :
824 : #ifdef __cplusplus
825 : #define Z_DEVICE_DEPS_EXTERN extern
826 : #else
827 : #define Z_DEVICE_DEPS_EXTERN
828 : #endif
829 :
830 : /**
831 : * @brief Define device dependencies.
832 : *
833 : * Initial build provides a record that associates the device object with its
834 : * devicetree ordinal, and provides the dependency ordinals. These are provided
835 : * as weak definitions (to prevent the reference from being captured when the
836 : * original object file is compiled), and in a distinct pass1 section (which
837 : * will be replaced by postprocessing).
838 : *
839 : * Before processing in gen_device_deps.py, the array format is:
840 : * {
841 : * DEVICE_ORDINAL (or DEVICE_HANDLE_NULL if not a devicetree node),
842 : * List of devicetree dependency ordinals (if any),
843 : * Z_DEVICE_DEPS_SEP,
844 : * List of injected dependency ordinals (if any),
845 : * Z_DEVICE_DEPS_SEP,
846 : * List of devicetree supporting ordinals (if any),
847 : * }
848 : *
849 : * After processing in gen_device_deps.py, the format is updated to:
850 : * {
851 : * List of existing devicetree dependency handles (if any),
852 : * Z_DEVICE_DEPS_SEP,
853 : * List of injected devicetree dependency handles (if any),
854 : * Z_DEVICE_DEPS_SEP,
855 : * List of existing devicetree support handles (if any),
856 : * DEVICE_HANDLE_NULL
857 : * }
858 : *
859 : * It is also (experimentally) necessary to provide explicit alignment on each
860 : * object. Otherwise x86-64 builds will introduce padding between objects in the
861 : * same input section in individual object files, which will be retained in
862 : * subsequent links both wasting space and resulting in aggregate size changes
863 : * relative to pass2 when all objects will be in the same input section.
864 : */
865 : #define Z_DEVICE_DEPS_DEFINE(node_id, dev_id, ...) \
866 : extern Z_DEVICE_DEPS_CONST device_handle_t Z_DEVICE_DEPS_NAME( \
867 : dev_id)[]; \
868 : Z_DEVICE_DEPS_CONST Z_DECL_ALIGN(device_handle_t) \
869 : Z_DEVICE_DEPS_SECTION Z_DEVICE_DEPS_EXTERN __weak \
870 : Z_DEVICE_DEPS_NAME(dev_id)[] = { \
871 : COND_CODE_1( \
872 : DT_NODE_EXISTS(node_id), \
873 : (DT_DEP_ORD(node_id), DT_REQUIRES_DEP_ORDS(node_id)), \
874 : (DEVICE_HANDLE_NULL,)) /**/ \
875 : Z_DEVICE_DEPS_SEP, \
876 : Z_DEVICE_EXTRA_DEPS(__VA_ARGS__) /**/ \
877 : Z_DEVICE_DEPS_SEP, \
878 : COND_CODE_1(DT_NODE_EXISTS(node_id), \
879 : (DT_SUPPORTS_DEP_ORDS(node_id)), ()) /**/ \
880 : }
881 :
882 : #endif /* CONFIG_DEVICE_DEPS */
883 : #if defined(CONFIG_DEVICE_DT_METADATA) || defined(__DOXYGEN__)
884 : /**
885 : * @brief Devicetree node labels associated with a device
886 : */
887 : struct device_dt_nodelabels {
888 : /* @brief number of elements in the nodelabels array */
889 : size_t num_nodelabels;
890 : /* @brief array of node labels as strings, exactly as they
891 : * appear in the final devicetree
892 : */
893 : const char *nodelabels[];
894 : };
895 :
896 : /**
897 : * @brief Devicetree metadata associated with a device
898 : *
899 : * This is currently limited to node labels, but the structure is
900 : * generic enough to be extended later without requiring breaking
901 : * changes.
902 : */
903 : struct device_dt_metadata {
904 : /**
905 : * @brief Node labels associated with the device
906 : * @see device_get_dt_nodelabels()
907 : */
908 : const struct device_dt_nodelabels *nl;
909 : };
910 :
911 : /**
912 : * @brief Get a @ref device reference from a devicetree node label.
913 : *
914 : * If:
915 : *
916 : * 1. a device was defined from a devicetree node, for example
917 : * with DEVICE_DT_DEFINE() or another similar macro, and
918 : * 2. that devicetree node has @p nodelabel as one of its node labels, and
919 : * 3. the device initialized successfully at boot time,
920 : *
921 : * then this function returns a pointer to the device. Otherwise, it
922 : * returns NULL.
923 : *
924 : * @param nodelabel a devicetree node label
925 : * @return a device reference for a device created from a node with that
926 : * node label, or NULL if either no such device exists or the device
927 : * failed to initialize
928 : */
929 : __syscall const struct device *device_get_by_dt_nodelabel(const char *nodelabel);
930 :
931 : /**
932 : * @brief Get the devicetree node labels associated with a device
933 : * @param dev device whose metadata to look up
934 : * @return information about the devicetree node labels or NULL if not available
935 : */
936 : static inline const struct device_dt_nodelabels *
937 : device_get_dt_nodelabels(const struct device *dev)
938 : {
939 : if (dev->dt_meta == NULL) {
940 : return NULL;
941 : }
942 : return dev->dt_meta->nl;
943 : }
944 :
945 : /**
946 : * @brief Maximum devicetree node label length.
947 : *
948 : * The maximum length is set so that device_get_by_dt_nodelabel() can
949 : * be used from userspace.
950 : */
951 : #define Z_DEVICE_MAX_NODELABEL_LEN Z_DEVICE_MAX_NAME_LEN
952 :
953 : /**
954 : * @brief Name of the identifier for a device's DT metadata structure
955 : * @param dev_id device identifier
956 : */
957 : #define Z_DEVICE_DT_METADATA_NAME_GET(dev_id) UTIL_CAT(__dev_dt_meta_, dev_id)
958 :
959 : /**
960 : * @brief Name of the identifier for the array of node label strings
961 : * saved for a device.
962 : */
963 : #define Z_DEVICE_DT_NODELABELS_NAME_GET(dev_id) UTIL_CAT(__dev_dt_nodelabels_, dev_id)
964 :
965 : /**
966 : * @brief Initialize an entry in the device DT node label lookup table
967 : *
968 : * Allocates and initializes a struct device_dt_metadata in the
969 : * appropriate iterable section for use finding devices.
970 : */
971 : #define Z_DEVICE_DT_METADATA_DEFINE(node_id, dev_id) \
972 : static const struct device_dt_nodelabels \
973 : Z_DEVICE_DT_NODELABELS_NAME_GET(dev_id) = { \
974 : .num_nodelabels = DT_NUM_NODELABELS(node_id), \
975 : .nodelabels = DT_NODELABEL_STRING_ARRAY(node_id), \
976 : }; \
977 : \
978 : static const struct device_dt_metadata \
979 : Z_DEVICE_DT_METADATA_NAME_GET(dev_id) = { \
980 : .nl = &Z_DEVICE_DT_NODELABELS_NAME_GET(dev_id), \
981 : };
982 : #endif /* CONFIG_DEVICE_DT_METADATA */
983 :
984 : /**
985 : * @brief Init sub-priority of the device
986 : *
987 : * The sub-priority is defined by the devicetree ordinal, which ensures that
988 : * multiple drivers running at the same priority level run in an order that
989 : * respects the devicetree dependencies.
990 : */
991 : #define Z_DEVICE_INIT_SUB_PRIO(node_id) \
992 : COND_CODE_1(DT_NODE_EXISTS(node_id), \
993 : (DT_DEP_ORD_STR_SORTABLE(node_id)), (0))
994 :
995 : /**
996 : * @brief Maximum device name length.
997 : *
998 : * The maximum length is set so that device_get_binding() can be used from
999 : * userspace.
1000 : */
1001 : #define Z_DEVICE_MAX_NAME_LEN 48U
1002 :
1003 : /**
1004 : * @brief Compile time check for device name length
1005 : *
1006 : * @param name Device name.
1007 : */
1008 : #define Z_DEVICE_NAME_CHECK(name) \
1009 : BUILD_ASSERT(sizeof(Z_STRINGIFY(name)) <= Z_DEVICE_MAX_NAME_LEN, \
1010 : Z_STRINGIFY(name) " too long")
1011 :
1012 : /**
1013 : * @brief Initializer for @ref device.
1014 : *
1015 : * @param name_ Name of the device.
1016 : * @param pm_ Reference to @ref pm_device_base (optional).
1017 : * @param data_ Reference to device data.
1018 : * @param config_ Reference to device config.
1019 : * @param api_ Reference to device API ops.
1020 : * @param state_ Reference to device state.
1021 : * @param deps_ Reference to device dependencies.
1022 : * @param node_id_ Devicetree node identifier
1023 : * @param dev_id_ Device identifier token, as passed to Z_DEVICE_BASE_DEFINE
1024 : */
1025 : #define Z_DEVICE_INIT(name_, pm_, data_, config_, api_, state_, deps_, node_id_, \
1026 : dev_id_) \
1027 : { \
1028 : .name = name_, \
1029 : .config = (config_), \
1030 : .api = (api_), \
1031 : .state = (state_), \
1032 : .data = (data_), \
1033 : IF_ENABLED(CONFIG_DEVICE_DEPS, (.deps = (deps_),)) /**/ \
1034 : IF_ENABLED(CONFIG_PM_DEVICE, Z_DEVICE_INIT_PM_BASE(pm_)) /**/ \
1035 : IF_ENABLED(CONFIG_DEVICE_DT_METADATA, \
1036 : (IF_ENABLED(DT_NODE_EXISTS(node_id_), \
1037 : (.dt_meta = &Z_DEVICE_DT_METADATA_NAME_GET( \
1038 : dev_id_),)))) \
1039 : }
1040 :
1041 : /*
1042 : * Anonymous unions require C11. Some pre-C11 gcc versions have early support for anonymous
1043 : * unions but they require these braces when combined with C99 designated initializers. For
1044 : * more details see https://docs.zephyrproject.org/latest/develop/languages/cpp/
1045 : */
1046 : #if defined(__STDC_VERSION__) && (__STDC_VERSION__) < 201100
1047 : # define Z_DEVICE_INIT_PM_BASE(pm_) ({ .pm_base = (pm_),},)
1048 : #else
1049 : # define Z_DEVICE_INIT_PM_BASE(pm_) (.pm_base = (pm_),)
1050 : #endif
1051 :
1052 : /**
1053 : * @brief Device section name (used for sorting purposes).
1054 : *
1055 : * @param level Initialization level
1056 : * @param prio Initialization priority
1057 : */
1058 : #define Z_DEVICE_SECTION_NAME(level, prio) \
1059 : _CONCAT(INIT_LEVEL_ORD(level), _##prio)
1060 :
1061 : /**
1062 : * @brief Define a @ref device
1063 : *
1064 : * @param node_id Devicetree node id for the device (DT_INVALID_NODE if a
1065 : * software device).
1066 : * @param dev_id Device identifier (used to name the defined @ref device).
1067 : * @param name Name of the device.
1068 : * @param pm Reference to @ref pm_device_base associated with the device.
1069 : * (optional).
1070 : * @param data Reference to device data.
1071 : * @param config Reference to device config.
1072 : * @param level Initialization level.
1073 : * @param prio Initialization priority.
1074 : * @param api Reference to device API.
1075 : * @param ... Optional dependencies, manually specified.
1076 : */
1077 : #define Z_DEVICE_BASE_DEFINE(node_id, dev_id, name, pm, data, config, level, prio, api, state, \
1078 : deps) \
1079 : COND_CODE_1(DT_NODE_EXISTS(node_id), (), (static)) \
1080 : COND_CODE_1(Z_DEVICE_IS_MUTABLE(node_id), (), (const)) \
1081 : STRUCT_SECTION_ITERABLE_NAMED_ALTERNATE( \
1082 : device, COND_CODE_1(Z_DEVICE_IS_MUTABLE(node_id), (device_mutable), (device)), \
1083 : Z_DEVICE_SECTION_NAME(level, prio), DEVICE_NAME_GET(dev_id)) = \
1084 : Z_DEVICE_INIT(name, pm, data, config, api, state, deps, node_id, dev_id)
1085 :
1086 : /**
1087 : * @brief Issue an error if the given init level is not supported.
1088 : *
1089 : * @param level Init level
1090 : */
1091 : #define Z_DEVICE_CHECK_INIT_LEVEL(level) \
1092 : COND_CODE_1(Z_INIT_PRE_KERNEL_1_##level, (), \
1093 : (COND_CODE_1(Z_INIT_PRE_KERNEL_2_##level, (), \
1094 : (COND_CODE_1(Z_INIT_POST_KERNEL_##level, (), \
1095 : (ZERO_OR_COMPILE_ERROR(0)))))))
1096 :
1097 : /**
1098 : * @brief Define the init entry for a device.
1099 : *
1100 : * @param node_id Devicetree node id for the device (DT_INVALID_NODE if a
1101 : * software device).
1102 : * @param dev_id Device identifier.
1103 : * @param init_fn_ Device init function.
1104 : * @param level Initialization level.
1105 : * @param prio Initialization priority.
1106 : */
1107 : #define Z_DEVICE_INIT_ENTRY_DEFINE(node_id, dev_id, init_fn_, level, prio) \
1108 : Z_DEVICE_CHECK_INIT_LEVEL(level) \
1109 : \
1110 : static const Z_DECL_ALIGN(struct init_entry) __used __noasan Z_INIT_ENTRY_SECTION( \
1111 : level, prio, Z_DEVICE_INIT_SUB_PRIO(node_id)) \
1112 : Z_INIT_ENTRY_NAME(DEVICE_NAME_GET(dev_id)) = { \
1113 : .init_fn = {COND_CODE_1(Z_DEVICE_IS_MUTABLE(node_id), (.dev_rw), (.dev)) = \
1114 : (init_fn_)}, \
1115 : Z_DEVICE_INIT_ENTRY_DEV(node_id, dev_id), \
1116 : }
1117 :
1118 : #define Z_DEFER_DEVICE_INIT_ENTRY_DEFINE(node_id, dev_id, init_fn_) \
1119 : static const Z_DECL_ALIGN(struct init_entry) __used __noasan \
1120 : __attribute__((__section__(".z_deferred_init"))) \
1121 : Z_INIT_ENTRY_NAME(DEVICE_NAME_GET(dev_id)) = { \
1122 : .init_fn = {COND_CODE_1(Z_DEVICE_IS_MUTABLE(node_id), (.dev_rw), (.dev)) = \
1123 : (init_fn_)}, \
1124 : Z_DEVICE_INIT_ENTRY_DEV(node_id, dev_id), \
1125 : }
1126 :
1127 : /*
1128 : * Anonymous unions require C11. Some pre-C11 gcc versions have early support for anonymous
1129 : * unions but they require these braces when combined with C99 designated initializers. For
1130 : * more details see https://docs.zephyrproject.org/latest/develop/languages/cpp/
1131 : */
1132 : #if defined(__STDC_VERSION__) && (__STDC_VERSION__) < 201100
1133 : # define Z_DEVICE_INIT_ENTRY_DEV(node_id, dev_id) { Z_DEV_ENTRY_DEV(node_id, dev_id) }
1134 : #else
1135 : # define Z_DEVICE_INIT_ENTRY_DEV(node_id, dev_id) Z_DEV_ENTRY_DEV(node_id, dev_id)
1136 : #endif
1137 :
1138 : #define Z_DEV_ENTRY_DEV(node_id, dev_id) \
1139 : COND_CODE_1(Z_DEVICE_IS_MUTABLE(node_id), (.dev_rw), (.dev)) = &DEVICE_NAME_GET(dev_id)
1140 :
1141 : /**
1142 : * @brief Define a @ref device and all other required objects.
1143 : *
1144 : * This is the common macro used to define @ref device objects. It can be used
1145 : * to define both Devicetree and software devices.
1146 : *
1147 : * @param node_id Devicetree node id for the device (DT_INVALID_NODE if a
1148 : * software device).
1149 : * @param dev_id Device identifier (used to name the defined @ref device).
1150 : * @param name Name of the device.
1151 : * @param init_fn Device init function.
1152 : * @param pm Reference to @ref pm_device_base associated with the device.
1153 : * (optional).
1154 : * @param data Reference to device data.
1155 : * @param config Reference to device config.
1156 : * @param level Initialization level.
1157 : * @param prio Initialization priority.
1158 : * @param api Reference to device API.
1159 : * @param state Reference to device state.
1160 : * @param ... Optional dependencies, manually specified.
1161 : */
1162 : #define Z_DEVICE_DEFINE(node_id, dev_id, name, init_fn, pm, data, config, \
1163 : level, prio, api, state, ...) \
1164 : Z_DEVICE_NAME_CHECK(name); \
1165 : \
1166 : IF_ENABLED(CONFIG_DEVICE_DEPS, \
1167 : (Z_DEVICE_DEPS_DEFINE(node_id, dev_id, __VA_ARGS__);)) \
1168 : \
1169 : IF_ENABLED(CONFIG_DEVICE_DT_METADATA, \
1170 : (IF_ENABLED(DT_NODE_EXISTS(node_id), \
1171 : (Z_DEVICE_DT_METADATA_DEFINE(node_id, dev_id);))))\
1172 : \
1173 : Z_DEVICE_BASE_DEFINE(node_id, dev_id, name, pm, data, config, level, \
1174 : prio, api, state, Z_DEVICE_DEPS_NAME(dev_id)); \
1175 : COND_CODE_1(DEVICE_DT_DEFER(node_id), \
1176 : (Z_DEFER_DEVICE_INIT_ENTRY_DEFINE(node_id, dev_id, \
1177 : init_fn)), \
1178 : (Z_DEVICE_INIT_ENTRY_DEFINE(node_id, dev_id, init_fn, \
1179 : level, prio))); \
1180 : IF_ENABLED(CONFIG_LLEXT_EXPORT_DEVICES, \
1181 : (IF_ENABLED(DT_NODE_EXISTS(node_id), \
1182 : (Z_DEVICE_EXPORT(node_id);))))
1183 :
1184 : /**
1185 : * @brief Declare a device for each status "okay" devicetree node.
1186 : *
1187 : * @note Disabled nodes should not result in devices, so not predeclaring these
1188 : * keeps drivers honest.
1189 : *
1190 : * This is only "maybe" a device because some nodes have status "okay", but
1191 : * don't have a corresponding @ref device allocated. There's no way to figure
1192 : * that out until after we've built the zephyr image, though.
1193 : */
1194 : #define Z_MAYBE_DEVICE_DECLARE_INTERNAL(node_id) \
1195 : extern COND_CODE_1(Z_DEVICE_IS_MUTABLE(node_id), (), \
1196 : (const)) struct device DEVICE_DT_NAME_GET(node_id);
1197 :
1198 : DT_FOREACH_STATUS_OKAY_NODE(Z_MAYBE_DEVICE_DECLARE_INTERNAL)
1199 :
1200 : /** @brief Expands to the full type. */
1201 : #define Z_DEVICE_API_TYPE(_class) _CONCAT(_class, _driver_api)
1202 :
1203 : /** @endcond */
1204 :
1205 : /**
1206 : * @brief Wrapper macro for declaring device API structs inside iterable sections.
1207 : *
1208 : * @param _class The device API class.
1209 : * @param _name The API instance name.
1210 : */
1211 1 : #define DEVICE_API(_class, _name) const STRUCT_SECTION_ITERABLE(Z_DEVICE_API_TYPE(_class), _name)
1212 :
1213 : /**
1214 : * @brief Expands to the pointer of a device's API for a given class.
1215 : *
1216 : * @param _class The device API class.
1217 : * @param _dev The device instance pointer.
1218 : *
1219 : * @return the pointer to the device API.
1220 : */
1221 1 : #define DEVICE_API_GET(_class, _dev) ((const struct Z_DEVICE_API_TYPE(_class) *)_dev->api)
1222 :
1223 : /**
1224 : * @brief Macro that evaluates to a boolean that can be used to check if
1225 : * a device is of a particular class.
1226 : *
1227 : * @param _class The device API class.
1228 : * @param _dev The device instance pointer.
1229 : *
1230 : * @retval true If the device is of the given class
1231 : * @retval false If the device is not of the given class
1232 : */
1233 1 : #define DEVICE_API_IS(_class, _dev) \
1234 : ({ \
1235 : STRUCT_SECTION_START_EXTERN(Z_DEVICE_API_TYPE(_class)); \
1236 : STRUCT_SECTION_END_EXTERN(Z_DEVICE_API_TYPE(_class)); \
1237 : (DEVICE_API_GET(_class, _dev) < STRUCT_SECTION_END(Z_DEVICE_API_TYPE(_class)) && \
1238 : DEVICE_API_GET(_class, _dev) >= STRUCT_SECTION_START(Z_DEVICE_API_TYPE(_class))); \
1239 : })
1240 :
1241 : #ifdef __cplusplus
1242 : }
1243 : #endif
1244 :
1245 : #include <zephyr/syscalls/device.h>
1246 :
1247 : #endif /* ZEPHYR_INCLUDE_DEVICE_H_ */
|
