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