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