Branch data Line data Source code
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 : : /**
11 : : * @brief Device Driver APIs
12 : : * @defgroup io_interfaces Device Driver APIs
13 : : * @{
14 : : * @}
15 : : */
16 : : /**
17 : : * @brief Miscellaneous Drivers APIs
18 : : * @defgroup misc_interfaces Miscellaneous Drivers APIs
19 : : * @ingroup io_interfaces
20 : : * @{
21 : : * @}
22 : : */
23 : : /**
24 : : * @brief Device Model APIs
25 : : * @defgroup device_model Device Model APIs
26 : : * @{
27 : : */
28 : :
29 : : #include <init.h>
30 : : #include <linker/sections.h>
31 : : #include <sys/device_mmio.h>
32 : : #include <sys/util.h>
33 : :
34 : : #ifdef __cplusplus
35 : : extern "C" {
36 : : #endif
37 : :
38 : : /**
39 : : * @brief Type used to represent a "handle" for a device.
40 : : *
41 : : * Every struct device has an associated handle. You can get a pointer
42 : : * to a device structure from its handle and vice versa, but the
43 : : * handle uses less space than a pointer. The device.h API mainly uses
44 : : * handles to store lists of multiple devices in a compact way.
45 : : *
46 : : * The extreme values and zero have special significance. Negative
47 : : * values identify functionality that does not correspond to a Zephyr
48 : : * device, such as the system clock or a SYS_INIT() function.
49 : : *
50 : : * @see device_handle_get()
51 : : * @see device_from_handle()
52 : : */
53 : : typedef int16_t device_handle_t;
54 : :
55 : : /** @brief Flag value used in lists of device handles to separate
56 : : * distinct groups.
57 : : *
58 : : * This is the minimum value for the device_handle_t type.
59 : : */
60 : : #define DEVICE_HANDLE_SEP INT16_MIN
61 : :
62 : : /** @brief Flag value used in lists of device handles to indicate the
63 : : * end of the list.
64 : : *
65 : : * This is the maximum value for the device_handle_t type.
66 : : */
67 : : #define DEVICE_HANDLE_ENDS INT16_MAX
68 : :
69 : : /** @brief Flag value used to identify an unknown device. */
70 : : #define DEVICE_HANDLE_NULL 0
71 : :
72 : : #define Z_DEVICE_MAX_NAME_LEN 48
73 : :
74 : : /**
75 : : * @def DEVICE_NAME_GET
76 : : *
77 : : * @brief Expands to the name of a global device object.
78 : : *
79 : : * @details Return the full name of a device object symbol created by
80 : : * DEVICE_DEFINE(), using the dev_name provided to DEVICE_DEFINE().
81 : : * This is the name of the global variable storing the device
82 : : * structure, not a pointer to the string in the device's @p name
83 : : * 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
89 : : * code. In other situations, you are probably looking for
90 : : * device_get_binding().
91 : : *
92 : : * @param name The same @p dev_name token given to DEVICE_DEFINE()
93 : : *
94 : : * @return The full name of the device object defined by DEVICE_DEFINE()
95 : : */
96 : : #define DEVICE_NAME_GET(name) _CONCAT(__device_, name)
97 : :
98 : : /**
99 : : * @def SYS_DEVICE_DEFINE
100 : : *
101 : : * @brief Run an initialization function at boot at specified priority.
102 : : *
103 : : * @deprecated Use SYS_INIT() instead.
104 : : *
105 : : * @param drv_name A string name for the pseudo-device (unused).
106 : : * @param init_fn Pointer to the function which should run at boot time.
107 : : * @param level Initialization level to run the function in.
108 : : * @param prio Function's priority within its initialization level.
109 : : */
110 : : #define SYS_DEVICE_DEFINE(drv_name, init_fn, level, prio) \
111 : : __DEPRECATED_MACRO SYS_INIT(init_fn, level, prio)
112 : :
113 : : /* Node paths can exceed the maximum size supported by device_get_binding() in user mode,
114 : : * so synthesize a unique dev_name from the devicetree node.
115 : : *
116 : : * The ordinal used in this name can be mapped to the path by
117 : : * examining zephyr/include/generated/device_extern.h header. If the
118 : : * format of this conversion changes, gen_defines should be updated to
119 : : * match it.
120 : : */
121 : : #define Z_DEVICE_DT_DEV_NAME(node_id) _CONCAT(dts_ord_, DT_DEP_ORD(node_id))
122 : :
123 : : /* Synthesize a unique name for the device state associated with
124 : : * dev_name.
125 : : */
126 : : #define Z_DEVICE_STATE_NAME(dev_name) _CONCAT(__devstate_, dev_name)
127 : :
128 : : /**
129 : : * @brief Utility macro to define and initialize the device state.
130 : : *
131 : : * @param node_id Devicetree node id of the device.
132 : : * @param dev_name Device name.
133 : : */
134 : : #define Z_DEVICE_STATE_DEFINE(node_id, dev_name) \
135 : : static struct device_state Z_DEVICE_STATE_NAME(dev_name) \
136 : : __attribute__((__section__(".z_devstate")));
137 : :
138 : : /**
139 : : * @def DEVICE_DEFINE
140 : : *
141 : : * @brief Create a device object and set it up for boot time initialization.
142 : : *
143 : : * @details This macro defines a <tt>struct device</tt> that is
144 : : * automatically configured by the kernel during system
145 : : * initialization. This macro should only be used when the device is
146 : : * not being allocated from a devicetree node. If you are allocating a
147 : : * device from a devicetree node, use DEVICE_DT_DEFINE() or
148 : : * DEVICE_DT_INST_DEFINE() instead.
149 : : *
150 : : * @param dev_name A unique token which is used in the name of the
151 : : * global device structure as a C identifier.
152 : : *
153 : : * @param drv_name A string name for the device, which will be stored
154 : : * in the device structure's @p name field. This name can be used to
155 : : * look up the device with device_get_binding(). This must be less
156 : : * than Z_DEVICE_MAX_NAME_LEN characters (including terminating NUL)
157 : : * in order to be looked up from user mode.
158 : : *
159 : : * @param init_fn Pointer to the device's initialization function,
160 : : * which will be run by the kernel during system initialization.
161 : : *
162 : : * @param pm_device Pointer to the device's power management
163 : : * resources, a <tt>struct pm_device</tt>, which will be stored in the
164 : : * device structure's @p pm field. Use NULL if the device does not use
165 : : * PM.
166 : : *
167 : : * @param data_ptr Pointer to the device's private mutable data, which
168 : : * will be stored in the device structure's @p data field.
169 : : *
170 : : * @param cfg_ptr Pointer to the device's private constant data, which
171 : : * will be stored in the device structure's @p config field.
172 : : *
173 : : * @param level The device's initialization level. See SYS_INIT() for
174 : : * details.
175 : : *
176 : : * @param prio The device's priority within its initialization level.
177 : : * See SYS_INIT() for details.
178 : : *
179 : : * @param api_ptr Pointer to the device's API structure. Can be NULL.
180 : : */
181 : : #define DEVICE_DEFINE(dev_name, drv_name, init_fn, pm_device, \
182 : : data_ptr, cfg_ptr, level, prio, api_ptr) \
183 : : Z_DEVICE_STATE_DEFINE(DT_INVALID_NODE, dev_name) \
184 : : Z_DEVICE_DEFINE(DT_INVALID_NODE, dev_name, drv_name, init_fn, \
185 : : pm_device, \
186 : : data_ptr, cfg_ptr, level, prio, api_ptr, \
187 : : &Z_DEVICE_STATE_NAME(dev_name))
188 : :
189 : : /**
190 : : * @def DEVICE_DT_NAME
191 : : *
192 : : * @brief Return a string name for a devicetree node.
193 : : *
194 : : * @details This macro returns a string literal usable as a device's
195 : : * @p name field from a devicetree node identifier.
196 : : *
197 : : * @param node_id The devicetree node identifier.
198 : : *
199 : : * @return The value of the node's "label" property, if it has one.
200 : : * Otherwise, the node's full name in "node-name@@unit-address" form.
201 : : */
202 : : #define DEVICE_DT_NAME(node_id) \
203 : : DT_PROP_OR(node_id, label, DT_NODE_FULL_NAME(node_id))
204 : :
205 : : /**
206 : : * @def DEVICE_DT_DEFINE
207 : : *
208 : : * @brief Create a device object from a devicetree node identifier and
209 : : * set it up for boot time initialization.
210 : : *
211 : : * @details This macro defines a <tt>struct device</tt> that is
212 : : * automatically configured by the kernel during system
213 : : * initialization. The global device object's name as a C identifier
214 : : * is derived from the node's dependency ordinal. The device
215 : : * structure's @p name field is set to
216 : : * <tt>DEVICE_DT_NAME(node_id)</tt>.
217 : : *
218 : : * The device is declared with extern visibility, so a pointer to a
219 : : * global device object can be obtained with
220 : : * <tt>DEVICE_DT_GET(node_id)</tt> from any source file that includes
221 : : * device.h. Before using the pointer, the referenced object should be
222 : : * checked using device_is_ready().
223 : : *
224 : : * @param node_id The devicetree node identifier.
225 : : *
226 : : * @param init_fn Pointer to the device's initialization function,
227 : : * which will be run by the kernel during system initialization.
228 : : *
229 : : * @param pm_device Pointer to the device's power management
230 : : * resources, a <tt>struct pm_device</tt>, which will be stored in the
231 : : * device structure's @p pm field. Use NULL if the device does not use
232 : : * PM.
233 : : *
234 : : * @param data_ptr Pointer to the device's private mutable data, which
235 : : * will be stored in the device structure's @p data field.
236 : : *
237 : : * @param cfg_ptr Pointer to the device's private constant data, which
238 : : * will be stored in the device structure's @p config field.
239 : : *
240 : : * @param level The device's initialization level. See SYS_INIT() for
241 : : * details.
242 : : *
243 : : * @param prio The device's priority within its initialization level.
244 : : * See SYS_INIT() for details.
245 : : *
246 : : * @param api_ptr Pointer to the device's API structure. Can be NULL.
247 : : */
248 : : #define DEVICE_DT_DEFINE(node_id, init_fn, pm_device, \
249 : : data_ptr, cfg_ptr, level, prio, \
250 : : api_ptr, ...) \
251 : : Z_DEVICE_STATE_DEFINE(node_id, Z_DEVICE_DT_DEV_NAME(node_id)) \
252 : : Z_DEVICE_DEFINE(node_id, Z_DEVICE_DT_DEV_NAME(node_id), \
253 : : DEVICE_DT_NAME(node_id), init_fn, \
254 : : pm_device, \
255 : : data_ptr, cfg_ptr, level, prio, \
256 : : api_ptr, \
257 : : &Z_DEVICE_STATE_NAME(Z_DEVICE_DT_DEV_NAME(node_id)), \
258 : : __VA_ARGS__)
259 : :
260 : : /**
261 : : * @def DEVICE_DT_INST_DEFINE
262 : : *
263 : : * @brief Like DEVICE_DT_DEFINE(), but uses an instance of a
264 : : * DT_DRV_COMPAT compatible instead of a node identifier.
265 : : *
266 : : * @param inst instance number. The @p node_id argument to
267 : : * DEVICE_DT_DEFINE is set to <tt>DT_DRV_INST(inst)</tt>.
268 : : *
269 : : * @param ... other parameters as expected by DEVICE_DT_DEFINE.
270 : : */
271 : : #define DEVICE_DT_INST_DEFINE(inst, ...) \
272 : : DEVICE_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)
273 : :
274 : : /**
275 : : * @def DEVICE_DT_NAME_GET
276 : : *
277 : : * @brief The name of the global device object for @p node_id
278 : : *
279 : : * @details Returns the name of the global device structure as a C
280 : : * identifier. The device must be allocated using DEVICE_DT_DEFINE()
281 : : * or DEVICE_DT_INST_DEFINE() for this to work.
282 : : *
283 : : * This macro is normally only useful within device driver source
284 : : * code. In other situations, you are probably looking for
285 : : * DEVICE_DT_GET().
286 : : *
287 : : * @param node_id Devicetree node identifier
288 : : *
289 : : * @return The name of the device object as a C identifier
290 : : */
291 : : #define DEVICE_DT_NAME_GET(node_id) DEVICE_NAME_GET(Z_DEVICE_DT_DEV_NAME(node_id))
292 : :
293 : : /**
294 : : * @def DEVICE_DT_GET
295 : : *
296 : : * @brief Get a <tt>const struct device*</tt> from a devicetree node
297 : : * identifier
298 : : *
299 : : * @details Returns a pointer to a device object created from a
300 : : * devicetree node, if any device was allocated by a driver.
301 : : *
302 : : * If no such device was allocated, this will fail at linker time. If
303 : : * you get an error that looks like <tt>undefined reference to
304 : : * __device_dts_ord_<N></tt>, that is what happened. Check to make
305 : : * sure your device driver is being compiled, usually by enabling the
306 : : * Kconfig options it requires.
307 : : *
308 : : * @param node_id A devicetree node identifier
309 : : * @return A pointer to the device object created for that node
310 : : */
311 : : #define DEVICE_DT_GET(node_id) (&DEVICE_DT_NAME_GET(node_id))
312 : :
313 : : /** @def DEVICE_DT_INST_GET
314 : : *
315 : : * @brief Get a <tt>const struct device*</tt> for an instance of a
316 : : * DT_DRV_COMPAT compatible
317 : : *
318 : : * @details This is equivalent to <tt>DEVICE_DT_GET(DT_DRV_INST(inst))</tt>.
319 : : *
320 : : * @param inst DT_DRV_COMPAT instance number
321 : : * @return A pointer to the device object created for that instance
322 : : */
323 : : #define DEVICE_DT_INST_GET(inst) DEVICE_DT_GET(DT_DRV_INST(inst))
324 : :
325 : : /**
326 : : * @def DEVICE_DT_GET_ANY
327 : : *
328 : : * @brief Get a <tt>const struct device*</tt> 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 : : #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 : : * @def DEVICE_DT_GET_ONE
350 : : *
351 : : * @brief Get a <tt>const struct device*</tt> from a devicetree compatible
352 : : *
353 : : * @details If an enabled devicetree node has the given compatible and
354 : : * a device object was created from it, this returns a pointer to that
355 : : * device.
356 : : *
357 : : * If there no such devices, this will fail at compile time.
358 : : *
359 : : * If there are multiple, this returns an arbitrary one.
360 : : *
361 : : * If this returns non-NULL, the device must be checked for readiness
362 : : * before use, e.g. with device_is_ready().
363 : : *
364 : : * @param compat lowercase-and-underscores devicetree compatible
365 : : * @return a pointer to a device
366 : : */
367 : : #define DEVICE_DT_GET_ONE(compat) \
368 : : COND_CODE_1(DT_HAS_COMPAT_STATUS_OKAY(compat), \
369 : : (DEVICE_DT_GET(DT_COMPAT_GET_ANY_STATUS_OKAY(compat))), \
370 : : (ZERO_OR_COMPILE_ERROR(0)))
371 : :
372 : : /**
373 : : * @def DEVICE_DT_GET_OR_NULL
374 : : *
375 : : * @brief Utility macro to obtain an optional reference to a device.
376 : : *
377 : : * @details If the node identifier refers to a node with status
378 : : * "okay", this returns <tt>DEVICE_DT_GET(node_id)</tt>. Otherwise, it
379 : : * returns NULL.
380 : : *
381 : : * @param node_id devicetree node identifier
382 : : *
383 : : * @return a <tt>const struct device*</tt> for the node identifier,
384 : : * which may be NULL.
385 : : */
386 : : #define DEVICE_DT_GET_OR_NULL(node_id) \
387 : : COND_CODE_1(DT_NODE_HAS_STATUS(node_id, okay), \
388 : : (DEVICE_DT_GET(node_id)), (NULL))
389 : :
390 : : /**
391 : : * @def DEVICE_GET
392 : : *
393 : : * @brief Obtain a pointer to a device object by name
394 : : *
395 : : * @details Return the address of a device object created by
396 : : * DEVICE_DEFINE(), using the dev_name provided to DEVICE_DEFINE().
397 : : *
398 : : * @param name The same as dev_name provided to DEVICE_DEFINE()
399 : : *
400 : : * @return A pointer to the device object created by DEVICE_DEFINE()
401 : : */
402 : : #define DEVICE_GET(name) (&DEVICE_NAME_GET(name))
403 : :
404 : : /** @def DEVICE_DECLARE
405 : : *
406 : : * @brief Declare a static device object
407 : : *
408 : : * This macro can be used at the top-level to declare a device, such
409 : : * that DEVICE_GET() may be used before the full declaration in
410 : : * DEVICE_DEFINE().
411 : : *
412 : : * This is often useful when configuring interrupts statically in a
413 : : * device's init or per-instance config function, as the init function
414 : : * itself is required by DEVICE_DEFINE() and use of DEVICE_GET()
415 : : * inside it creates a circular dependency.
416 : : *
417 : : * @param name Device name
418 : : */
419 : : #define DEVICE_DECLARE(name) static const struct device DEVICE_NAME_GET(name)
420 : :
421 : : /**
422 : : * @brief Runtime device dynamic structure (in RAM) per driver instance
423 : : *
424 : : * Fields in this are expected to be default-initialized to zero. The
425 : : * kernel driver infrastructure and driver access functions are
426 : : * responsible for ensuring that any non-zero initialization is done
427 : : * before they are accessed.
428 : : */
429 : : struct device_state {
430 : : /** Non-negative result of initializing the device.
431 : : *
432 : : * The absolute value returned when the device initialization
433 : : * function was invoked, or `UINT8_MAX` if the value exceeds
434 : : * an 8-bit integer. If initialized is also set, a zero value
435 : : * indicates initialization succeeded.
436 : : */
437 : : unsigned int init_res : 8;
438 : :
439 : : /** Indicates the device initialization function has been
440 : : * invoked.
441 : : */
442 : : bool initialized : 1;
443 : : };
444 : :
445 : : struct pm_device;
446 : :
447 : : #ifdef CONFIG_HAS_DYNAMIC_DEVICE_HANDLES
448 : : #define Z_DEVICE_HANDLES_CONST
449 : : #else
450 : : #define Z_DEVICE_HANDLES_CONST const
451 : : #endif
452 : :
453 : : /**
454 : : * @brief Runtime device structure (in ROM) per driver instance
455 : : */
456 : : struct device {
457 : : /** Name of the device instance */
458 : : const char *name;
459 : : /** Address of device instance config information */
460 : : const void *config;
461 : : /** Address of the API structure exposed by the device instance */
462 : : const void *api;
463 : : /** Address of the common device state */
464 : : struct device_state * const state;
465 : : /** Address of the device instance private data */
466 : : void * const data;
467 : : /** optional pointer to handles associated with the device.
468 : : *
469 : : * This encodes a sequence of sets of device handles that have
470 : : * some relationship to this node. The individual sets are
471 : : * extracted with dedicated API, such as
472 : : * device_required_handles_get().
473 : : */
474 : : Z_DEVICE_HANDLES_CONST device_handle_t * const handles;
475 : :
476 : : #ifdef CONFIG_PM_DEVICE
477 : : /** Reference to the device PM resources. */
478 : : struct pm_device * const pm;
479 : : #endif
480 : : };
481 : :
482 : : /**
483 : : * @brief Get the handle for a given device
484 : : *
485 : : * @param dev the device for which a handle is desired.
486 : : *
487 : : * @return the handle for the device, or DEVICE_HANDLE_NULL if the
488 : : * device does not have an associated handle.
489 : : */
490 : : static inline device_handle_t
491 : : device_handle_get(const struct device *dev)
492 : : {
493 : : device_handle_t ret = DEVICE_HANDLE_NULL;
494 : : extern const struct device __device_start[];
495 : :
496 : : /* TODO: If/when devices can be constructed that are not part of the
497 : : * fixed sequence we'll need another solution.
498 : : */
499 : : if (dev != NULL) {
500 : : ret = 1 + (device_handle_t)(dev - __device_start);
501 : : }
502 : :
503 : : return ret;
504 : : }
505 : :
506 : : /**
507 : : * @brief Get the device corresponding to a handle.
508 : : *
509 : : * @param dev_handle the device handle
510 : : *
511 : : * @return the device that has that handle, or a null pointer if @p
512 : : * dev_handle does not identify a device.
513 : : */
514 : : static inline const struct device *
515 : 0 : device_from_handle(device_handle_t dev_handle)
516 : : {
517 : : extern const struct device __device_start[];
518 : : extern const struct device __device_end[];
519 : 0 : const struct device *dev = NULL;
520 : 0 : size_t numdev = __device_end - __device_start;
521 : :
522 [ # # # # ]: 0 : if ((dev_handle > 0) && ((size_t)dev_handle <= numdev)) {
523 : 0 : dev = &__device_start[dev_handle - 1];
524 : : }
525 : :
526 : 0 : return dev;
527 : : }
528 : :
529 : : /**
530 : : * @brief Prototype for functions used when iterating over a set of devices.
531 : : *
532 : : * Such a function may be used in API that identifies a set of devices and
533 : : * provides a visitor API supporting caller-specific interaction with each
534 : : * device in the set.
535 : : *
536 : : * The visit is said to succeed if the visitor returns a non-negative value.
537 : : *
538 : : * @param dev a device in the set being iterated
539 : : *
540 : : * @param context state used to support the visitor function
541 : : *
542 : : * @return A non-negative number to allow walking to continue, and a negative
543 : : * error code to case the iteration to stop.
544 : : *
545 : : * @see device_required_foreach()
546 : : * @see device_supported_foreach()
547 : : */
548 : : typedef int (*device_visitor_callback_t)(const struct device *dev, void *context);
549 : :
550 : : /**
551 : : * @brief Get the device handles for devicetree dependencies of this device.
552 : : *
553 : : * This function returns a pointer to an array of device handles. The
554 : : * length of the array is stored in the @p count parameter.
555 : : *
556 : : * The array contains a handle for each device that @p dev requires
557 : : * directly, as determined from the devicetree. This does not include
558 : : * transitive dependencies; you must recursively determine those.
559 : : *
560 : : * @param dev the device for which dependencies are desired.
561 : : *
562 : : * @param count pointer to where this function should store the length
563 : : * of the returned array. No value is stored if the call returns a
564 : : * null pointer. The value may be set to zero if the device has no
565 : : * devicetree dependencies.
566 : : *
567 : : * @return a pointer to a sequence of @p *count device handles, or a null
568 : : * pointer if @p dev does not have any dependency data.
569 : : */
570 : : static inline const device_handle_t *
571 : 0 : device_required_handles_get(const struct device *dev,
572 : : size_t *count)
573 : : {
574 : 0 : const device_handle_t *rv = dev->handles;
575 : :
576 [ # # ]: 0 : if (rv != NULL) {
577 : 0 : size_t i = 0;
578 : :
579 [ # # ]: 0 : while ((rv[i] != DEVICE_HANDLE_ENDS)
580 [ # # ]: 0 : && (rv[i] != DEVICE_HANDLE_SEP)) {
581 : 0 : ++i;
582 : : }
583 : 0 : *count = i;
584 : : }
585 : :
586 : 0 : return rv;
587 : : }
588 : :
589 : : /**
590 : : * @brief Get the set of handles that this device supports.
591 : : *
592 : : * This function returns a pointer to an array of device handles. The
593 : : * length of the array is stored in the @p count parameter.
594 : : *
595 : : * The array contains a handle for each device that @p dev "supports"
596 : : * -- that is, devices that require @p dev directly -- as determined
597 : : * from the devicetree. This does not include transitive dependencies;
598 : : * you must recursively determine those.
599 : : *
600 : : * @param dev the device for which supports are desired.
601 : : *
602 : : * @param count pointer to where this function should store the length
603 : : * of the returned array. No value is stored if the call returns a
604 : : * null pointer. The value may be set to zero if nothing in the
605 : : * devicetree depends on @p dev.
606 : : *
607 : : * @return a pointer to a sequence of @p *count device handles, or a null
608 : : * pointer if @p dev does not have any dependency data.
609 : : */
610 : : static inline const device_handle_t *
611 : 0 : device_supported_handles_get(const struct device *dev,
612 : : size_t *count)
613 : : {
614 : 0 : const device_handle_t *rv = dev->handles;
615 : 0 : size_t region = 0;
616 : 0 : size_t i = 0;
617 : :
618 [ # # ]: 0 : if (rv != NULL) {
619 : : /* Fast forward to supporting devices */
620 [ # # ]: 0 : while (region != 2) {
621 [ # # ]: 0 : if (*rv == DEVICE_HANDLE_SEP) {
622 : 0 : region++;
623 : : }
624 : 0 : rv++;
625 : : }
626 : : /* Count supporting devices */
627 [ # # ]: 0 : while (rv[i] != DEVICE_HANDLE_ENDS) {
628 : 0 : ++i;
629 : : }
630 : 0 : *count = i;
631 : : }
632 : :
633 : 0 : return rv;
634 : : }
635 : :
636 : : /**
637 : : * @brief Visit every device that @p dev directly requires.
638 : : *
639 : : * Zephyr maintains information about which devices are directly required by
640 : : * another device; for example an I2C-based sensor driver will require an I2C
641 : : * controller for communication. Required devices can derive from
642 : : * statically-defined devicetree relationships or dependencies registered
643 : : * at runtime.
644 : : *
645 : : * This API supports operating on the set of required devices. Example uses
646 : : * include making sure required devices are ready before the requiring device
647 : : * is used, and releasing them when the requiring device is no longer needed.
648 : : *
649 : : * There is no guarantee on the order in which required devices are visited.
650 : : *
651 : : * If the @p visitor function returns a negative value iteration is halted,
652 : : * and the returned value from the visitor is returned from this function.
653 : : *
654 : : * @note This API is not available to unprivileged threads.
655 : : *
656 : : * @param dev a device of interest. The devices that this device depends on
657 : : * will be used as the set of devices to visit. This parameter must not be
658 : : * null.
659 : : *
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 : : *
663 : : * @param context state that is passed through to the visitor function. This
664 : : * parameter may be null if @p visitor tolerates a null @p context.
665 : : *
666 : : * @return The number of devices that were visited if all visits succeed, or
667 : : * the negative value returned from the first visit that did not succeed.
668 : : */
669 : : int device_required_foreach(const struct device *dev,
670 : : device_visitor_callback_t visitor_cb,
671 : : void *context);
672 : :
673 : : /**
674 : : * @brief Visit every device that @p dev directly supports.
675 : : *
676 : : * Zephyr maintains information about which devices are directly supported by
677 : : * another device; for example an I2C controller will support an I2C-based
678 : : * sensor driver. Supported devices can derive from statically-defined
679 : : * devicetree relationships.
680 : : *
681 : : * This API supports operating on the set of supported devices. Example uses
682 : : * include iterating over the devices connected to a regulator when it is
683 : : * powered on.
684 : : *
685 : : * There is no guarantee on the order in which required devices are visited.
686 : : *
687 : : * If the @p visitor function returns a negative value iteration is halted,
688 : : * and the returned value from the visitor is returned from this function.
689 : : *
690 : : * @note This API is not available to unprivileged threads.
691 : : *
692 : : * @param dev a device of interest. The devices that this device supports
693 : : * will be used as the set of devices to visit. This parameter must not be
694 : : * null.
695 : : *
696 : : * @param visitor_cb the function that should be invoked on each device in the
697 : : * support set. This parameter must not be null.
698 : : *
699 : : * @param context state that is passed through to the visitor function. This
700 : : * parameter may be null if @p visitor tolerates a null @p context.
701 : : *
702 : : * @return The number of devices that were visited if all visits succeed, or
703 : : * the negative value returned from the first visit that did not succeed.
704 : : */
705 : : int device_supported_foreach(const struct device *dev,
706 : : device_visitor_callback_t visitor_cb,
707 : : void *context);
708 : :
709 : : /**
710 : : * @brief Get a <tt>const struct device*</tt> from its @p name field
711 : : *
712 : : * @details This function iterates through the devices on the system.
713 : : * If a device with the given @p name field is found, and that device
714 : : * initialized successfully at boot time, this function returns a
715 : : * pointer to the device.
716 : : *
717 : : * If no device has the given name, this function returns NULL.
718 : : *
719 : : * This function also returns NULL when a device is found, but it
720 : : * failed to initialize successfully at boot time. (To troubleshoot
721 : : * this case, set a breakpoint on your device driver's initialization
722 : : * function.)
723 : : *
724 : : * @param name device name to search for. A null pointer, or a pointer
725 : : * to an empty string, will cause NULL to be returned.
726 : : *
727 : : * @return pointer to device structure with the given name; NULL if
728 : : * the device is not found or if the device with that name's
729 : : * initialization function failed.
730 : : */
731 : : __syscall const struct device *device_get_binding(const char *name);
732 : :
733 : : /** @brief Get access to the static array of static devices.
734 : : *
735 : : * @param devices where to store the pointer to the array of
736 : : * statically allocated devices. The array must not be mutated
737 : : * through this pointer.
738 : : *
739 : : * @return the number of statically allocated devices.
740 : : */
741 : : size_t z_device_get_all_static(const struct device * *devices);
742 : :
743 : : /**
744 : : * @brief Verify that a device is ready for use.
745 : : *
746 : : * This is the implementation underlying device_is_ready(), without the overhead
747 : : * of a syscall wrapper.
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 : : * @see device_is_ready()
756 : : */
757 : : bool z_device_is_ready(const struct device *dev);
758 : :
759 : : /** @brief Verify that a device is ready for use.
760 : : *
761 : : * Indicates whether the provided device pointer is for a device known to be
762 : : * in a state where it can be used with its standard API.
763 : : *
764 : : * This can be used with device pointers captured from DEVICE_DT_GET(), which
765 : : * does not include the readiness checks of device_get_binding(). At minimum
766 : : * this means that the device has been successfully initialized.
767 : : *
768 : : * @param dev pointer to the device in question.
769 : : *
770 : : * @retval true If the device is ready for use.
771 : : * @retval false If the device is not ready for use or if a NULL device pointer
772 : : * is passed as argument.
773 : : */
774 : : __syscall bool device_is_ready(const struct device *dev);
775 : :
776 : 1 : static inline bool z_impl_device_is_ready(const struct device *dev)
777 : : {
778 : 1 : return z_device_is_ready(dev);
779 : : }
780 : :
781 : : /**
782 : : * @brief Determine whether a device is ready for use
783 : : *
784 : : * This is equivalent to device_usable_check(), without the overhead of a
785 : : * syscall wrapper.
786 : : *
787 : : * @deprecated Use z_device_is_ready() instead.
788 : : *
789 : : * @param dev Device instance.
790 : : *
791 : : * @retval 0 If device is usable.
792 : : * @retval -ENODEV If device is not usable.
793 : : */
794 : : __deprecated static inline int z_device_usable_check(const struct device *dev)
795 : : {
796 : : return z_device_is_ready(dev) ? 0 : -ENODEV;
797 : : }
798 : :
799 : : /**
800 : : * @brief Determine whether a device is ready for use
801 : : *
802 : : * @deprecated Use device_is_ready() instead.
803 : : *
804 : : * @param dev Device instance.
805 : : *
806 : : * @retval 0 If device is usable.
807 : : * @retval -ENODEV If device is not usable.
808 : : */
809 : : __deprecated static inline int device_usable_check(const struct device *dev)
810 : : {
811 : : return device_is_ready(dev) ? 0 : -ENODEV;
812 : : }
813 : :
814 : : /**
815 : : * @}
816 : : */
817 : :
818 : : /* Synthesize the name of the object that holds device ordinal and
819 : : * dependency data. If the object doesn't come from a devicetree
820 : : * node, use dev_name.
821 : : */
822 : : #define Z_DEVICE_HANDLE_NAME(node_id, dev_name) \
823 : : _CONCAT(__devicehdl_, \
824 : : COND_CODE_1(DT_NODE_EXISTS(node_id), \
825 : : (node_id), \
826 : : (dev_name)))
827 : :
828 : : #define Z_DEVICE_EXTRA_HANDLES(...) \
829 : : FOR_EACH_NONEMPTY_TERM(IDENTITY, (,), __VA_ARGS__)
830 : :
831 : : /*
832 : : * Utility macro to define and initialize the device state.
833 : : *
834 : : * @param node_id Devicetree node id of the device.
835 : : * @param dev_name Device name.
836 : : */
837 : : #define Z_DEVICE_STATE_DEFINE(node_id, dev_name) \
838 : : static struct device_state Z_DEVICE_STATE_NAME(dev_name) \
839 : : __attribute__((__section__(".z_devstate")));
840 : :
841 : : /* Construct objects that are referenced from struct device. These
842 : : * include power management and dependency handles.
843 : : */
844 : : #define Z_DEVICE_DEFINE_PRE(node_id, dev_name, ...) \
845 : : Z_DEVICE_DEFINE_HANDLES(node_id, dev_name, __VA_ARGS__)
846 : :
847 : : /* Initial build provides a record that associates the device object
848 : : * with its devicetree ordinal, and provides the dependency ordinals.
849 : : * These are provided as weak definitions (to prevent the reference
850 : : * from being captured when the original object file is compiled), and
851 : : * in a distinct pass1 section (which will be replaced by
852 : : * postprocessing).
853 : : *
854 : : * Before processing in gen_handles.py, the array format is:
855 : : * {
856 : : * DEVICE_ORDINAL (or DEVICE_HANDLE_NULL if not a devicetree node),
857 : : * List of devicetree dependency ordinals (if any),
858 : : * DEVICE_HANDLE_SEP,
859 : : * List of injected dependency ordinals (if any),
860 : : * DEVICE_HANDLE_SEP,
861 : : * List of devicetree supporting ordinals (if any),
862 : : * }
863 : : *
864 : : * After processing in gen_handles.py, the format is updated to:
865 : : * {
866 : : * List of existing devicetree dependency handles (if any),
867 : : * DEVICE_HANDLE_SEP,
868 : : * List of injected dependency ordinals (if any),
869 : : * DEVICE_HANDLE_SEP,
870 : : * List of existing devicetree support handles (if any),
871 : : * DEVICE_HANDLE_NULL
872 : : * }
873 : : *
874 : : * It is also (experimentally) necessary to provide explicit alignment
875 : : * on each object. Otherwise x86-64 builds will introduce padding
876 : : * between objects in the same input section in individual object
877 : : * files, which will be retained in subsequent links both wasting
878 : : * space and resulting in aggregate size changes relative to pass2
879 : : * when all objects will be in the same input section.
880 : : *
881 : : * The build assert will fail if device_handle_t changes size, which
882 : : * means the alignment directives in the linker scripts and in
883 : : * `gen_handles.py` must be updated.
884 : : */
885 : : BUILD_ASSERT(sizeof(device_handle_t) == 2, "fix the linker scripts");
886 : : #define Z_DEVICE_DEFINE_HANDLES(node_id, dev_name, ...) \
887 : : extern Z_DEVICE_HANDLES_CONST device_handle_t \
888 : : Z_DEVICE_HANDLE_NAME(node_id, dev_name)[]; \
889 : : Z_DEVICE_HANDLES_CONST device_handle_t \
890 : : __aligned(sizeof(device_handle_t)) \
891 : : __attribute__((__weak__, \
892 : : __section__(".__device_handles_pass1"))) \
893 : : Z_DEVICE_HANDLE_NAME(node_id, dev_name)[] = { \
894 : : COND_CODE_1(DT_NODE_EXISTS(node_id), ( \
895 : : DT_DEP_ORD(node_id), \
896 : : DT_REQUIRES_DEP_ORDS(node_id) \
897 : : ), ( \
898 : : DEVICE_HANDLE_NULL, \
899 : : )) \
900 : : DEVICE_HANDLE_SEP, \
901 : : Z_DEVICE_EXTRA_HANDLES(__VA_ARGS__) \
902 : : DEVICE_HANDLE_SEP, \
903 : : COND_CODE_1(DT_NODE_EXISTS(node_id), \
904 : : (DT_SUPPORTS_DEP_ORDS(node_id)), ()) \
905 : : };
906 : :
907 : : #define Z_DEVICE_DEFINE_INIT(node_id, dev_name) \
908 : : .handles = Z_DEVICE_HANDLE_NAME(node_id, dev_name),
909 : :
910 : : /* Like DEVICE_DEFINE but takes a node_id AND a dev_name, and trailing
911 : : * dependency handles that come from outside devicetree.
912 : : */
913 : : #define Z_DEVICE_DEFINE(node_id, dev_name, drv_name, init_fn, pm_device,\
914 : : data_ptr, cfg_ptr, level, prio, api_ptr, state_ptr, ...) \
915 : : Z_DEVICE_DEFINE_PRE(node_id, dev_name, __VA_ARGS__) \
916 : : COND_CODE_1(DT_NODE_EXISTS(node_id), (), (static)) \
917 : : const Z_DECL_ALIGN(struct device) \
918 : : DEVICE_NAME_GET(dev_name) __used \
919 : : __attribute__((__section__(".z_device_" #level STRINGIFY(prio)"_"))) = { \
920 : : .name = drv_name, \
921 : : .config = (cfg_ptr), \
922 : : .api = (api_ptr), \
923 : : .state = (state_ptr), \
924 : : .data = (data_ptr), \
925 : : COND_CODE_1(CONFIG_PM_DEVICE, (.pm = pm_device,), ()) \
926 : : Z_DEVICE_DEFINE_INIT(node_id, dev_name) \
927 : : }; \
928 : : BUILD_ASSERT(sizeof(Z_STRINGIFY(drv_name)) <= Z_DEVICE_MAX_NAME_LEN, \
929 : : Z_STRINGIFY(DEVICE_NAME_GET(drv_name)) " too long"); \
930 : : Z_INIT_ENTRY_DEFINE(DEVICE_NAME_GET(dev_name), init_fn, \
931 : : (&DEVICE_NAME_GET(dev_name)), level, prio)
932 : :
933 : : #ifdef __cplusplus
934 : : }
935 : : #endif
936 : :
937 : : /* device_extern is generated based on devicetree nodes */
938 : : #include <device_extern.h>
939 : :
940 : : #include <syscalls/device.h>
941 : :
942 : : #endif /* ZEPHYR_INCLUDE_DEVICE_H_ */
|