1 /*
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 typedef int16_t device_handle_t;
73
74 /** @brief Flag value used to identify an unknown device. */
75 #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 #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 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 #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 #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 ...) \
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 #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 #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 #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 #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 #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 #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 #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 #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 #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 #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 #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 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 uint8_t init_res;
388
389 /** Indicates the device initialization function has been
390 * invoked.
391 */
392 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 struct device {
412 /** Name of the device instance */
413 const char *name;
414 /** Address of device instance config information */
415 const void *config;
416 /** Address of the API structure exposed by the device instance */
417 const void *api;
418 /** Address of the common device state */
419 struct device_state *state;
420 /** Address of the device instance private data */
421 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 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 struct pm_device_base *pm_base;
440 struct pm_device *pm;
441 struct pm_device_isr *pm_isr;
442 };
443 #endif
444 #if defined(CONFIG_DEVICE_DT_METADATA) || defined(__DOXYGEN__)
445 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 */
device_handle_get(const struct device * dev)457 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 *
device_from_handle(device_handle_t dev_handle)481 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 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 *
device_required_handles_get(const struct device * dev,size_t * count)538 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 *
device_injected_handles_get(const struct device * dev,size_t * count)574 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 *
device_supported_handles_get(const struct device * dev,size_t * count)618 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 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 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 __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 __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 __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 *
device_get_dt_nodelabels(const struct device * dev)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 #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 #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 #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_ */
1248
