Lines Matching +full:driver +full:- +full:bar
1 .. _dt-howtos:
6 This page has step-by-step advice for getting things done with devicetree.
8 .. tip:: See :ref:`dt-trouble` for troubleshooting advice.
10 .. _get-devicetree-outputs:
15 A board's devicetree (:ref:`BOARD.dts <devicetree-in-out-files>`) pulls in
26 You can build :zephyr:code-sample:`hello_world` to see the "base" devicetree for your board
27 without any additional changes from :ref:`overlay files <dt-input-files>`.
30 :zephyr:code-sample:`hello_world`:
32 .. code-block:: sh
34 # --cmake-only here just forces CMake to run, skipping the
36 west build -b qemu_cortex_m3 samples/hello_world --cmake-only
42 .. code-block:: none
44 -- Found BOARD.dts: .../zephyr/boards/arm/qemu_cortex_m3/qemu_cortex_m3.dts
45 -- Generated zephyr.dts: .../zephyr/build/zephyr/zephyr.dts
46 …-- Generated devicetree_generated.h: .../zephyr/build/zephyr/include/generated/zephyr/devicetree_g…
52 See :ref:`devicetree-in-out-files` for details about these files.
54 .. _dt-get-device:
59 When writing Zephyr applications, you'll often want to get a driver-level
65 .. code-block:: devicetree
71 current-speed = <115200>;
77 my-serial = &serial0;
85 Start by making a :ref:`node identifier <dt-node-identifiers>` for the device
89 .. code-block:: c
106 .. code-block:: c
112 return -ENODEV;
118 build-time, which means there is no runtime penalty. This method is useful if
124 In some situations the device cannot be known at build-time, e.g., if it depends
129 .. code-block:: c
138 If you're having trouble, see :ref:`dt-trouble`. The first thing to check is
141 .. code-block:: c
155 .. code-block:: none
160 This likely means there's a Kconfig issue preventing the device driver from
164 .. code-block:: c
171 initialization function failed. Enabling logging or debugging driver code may
174 device's driver failed to initialize or that it does not exist.
176 .. _dts-find-binding:
181 :ref:`dt-bindings` are YAML files which declare what you can do with the nodes
185 If you don't have them already, :ref:`get-devicetree-outputs`. To find a node's
189 .. code-block:: c
207 .. code-block:: c
213 * Binding (compatible = soc-nv-flash):
214 * $ZEPHYR_BASE/dts/bindings/mtd/soc-nv-flash.yaml
218 See :ref:`missing-dt-binding` for troubleshooting.
220 .. _set-devicetree-overlays:
225 Devicetree overlays are explained in :ref:`devicetree-intro`. The CMake
226 variable :makevar:`DTC_OVERLAY_FILE` contains a space- or semicolon-separated
230 like ``\${ZEPHYR_<module>_MODULE_DIR}/<path-to>/dts.overlay``
234 to use. Here is an :ref:`example <west-building-dtc-overlay-file>` using
264 See :ref:`Application Configuration Directory <application-configuration-directory>`
275 .. code-block:: none
277 -- Found devicetree overlay: .../some/file.overlay
279 .. _use-dt-overlays:
284 See :ref:`set-devicetree-overlays` for how to add an overlay to the build.
289 .. code-block:: devicetree
295 current-speed = <115200>;
301 These are equivalent ways to override the ``current-speed`` value in an
305 .. code-block:: none
309 current-speed = <9600>;
314 current-speed = <9600>;
322 .. code-block:: devicetree
326 my-serial = &serial0;
332 .. code-block:: devicetree
343 .. code-block:: devicetree
346 /delete-property/ some-unwanted-property;
352 .. code-block:: devicetree
356 my_spi_device: temp-sensor@0 {
365 spi-max-frequency = <4000000>;
385 - create the device as a subnode of the parent bus
386 - set its properties according to its binding
388 Assuming you have a suitable device driver associated with the
390 enable the driver via Kconfig and :ref:`get the struct device <dt-get-device>`
391 for your newly added bus node, then use it with that driver API.
393 .. _dt-create-devices:
398 "Devicetree-aware" :ref:`device drivers <device_model_api>` should create a
400 particular :ref:`compatible <dt-important-props>` (or related set of
401 compatibles) supported by the driver.
403 Writing a devicetree-aware driver begins by defining a :ref:`devicetree binding
404 <dt-bindings>` for the devices supported by the driver. Use existing bindings
408 .. code-block:: yaml
410 description: <Human-readable description of your binding>
411 compatible: "foo-company,bar-device"
414 See :ref:`dts-find-binding` for more advice on locating existing bindings.
416 After writing your binding, your driver C file can then use the devicetree API
423 - Each ``struct device``\ 's name should be set to its devicetree node's
424 ``label`` property. This allows the driver's users to :ref:`dt-get-device` in
427 - Each device's initial configuration should use values from devicetree
428 properties whenever practical. This allows users to configure the driver
429 using :ref:`devicetree overlays <use-dt-overlays>`.
432 device-specific configuration and data structures and API functions, like this:
434 .. code-block:: c
441 /* per-device values to store in RAM */
448 /* Implement driver API functions (drivers/some_api.h callbacks): */
450 static int my_driver_api_func2(const struct device *dev, uint64_t bar) { /* ... */ }
456 .. _dt-create-devices-inst:
461 Use this option, which uses :ref:`devicetree-inst-apis`, if possible. However,
462 they only work when devicetree nodes for your driver's ``compatible`` are all
465 To use instance-based APIs, begin by defining ``DT_DRV_COMPAT`` to the
466 lowercase-and-underscores version of the compatible that the device driver
467 supports. For example, if your driver's compatible is ``"vnd,my-device"`` in
469 driver C file:
471 .. code-block:: c
489 .. code-block:: c
520 .. code-block:: c
535 peripheral driver which relies on vendor HAL APIs specialized for individual IP
536 blocks to implement Zephyr driver callbacks. Cases like this should use
539 :ref:`devicetree-generic-apis` can then be used to access node data.
541 For this to work, your :ref:`SoC's dtsi file <dt-input-files>` must define node
543 your driver supports. The resulting devicetree usually looks something like
546 .. code-block:: devicetree
551 compatible = "vnd,my-device";
554 compatible = "vnd,my-device";
559 The driver can use the ``mydevice0`` and ``mydevice1`` node labels in the
562 .. code-block:: c
596 .. code-block:: c
606 Since this style does not use ``DT_INST_FOREACH_STATUS_OKAY()``, the driver
610 .. _dt-drivers-that-depend:
619 - Write your devicetree binding in a way that permits use of
620 :ref:`devicetree-hw-api` from devicetree.h if possible.
621 - In particular, for bus devices, your driver's binding should include a
622 file like :zephyr_file:`dts/bindings/spi/spi-device.yaml` which provides
625 node. You can then :ref:`dt-get-device` for the bus in the usual way.
629 .. _dt-apps-that-depend:
631 Applications that depend on board-specific devices
636 done in the :zephyr:code-sample:`blinky` sample. The application can then be configured in
637 :ref:`BOARD.dts <devicetree-in-out-files>` files or via :ref:`devicetree
638 overlays <use-dt-overlays>`.