Lines Matching +full:dts +full:- +full:bindings
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
19 ``dts/<ARCH>/<vendor>/<soc>.dtsi``, but this can be time consuming.
22 application and open the :file:`zephyr.dts` file in the build directory.
27 without any additional changes from :ref:`overlay files <dt-input-files>`.
31 .. code-block:: sh
33 # --cmake-only here just forces CMake to run, skipping the
35 west build -b qemu_cortex_m3 samples/hello_world --cmake-only
41 .. code-block:: none
43 -- Found BOARD.dts: .../zephyr/boards/arm/qemu_cortex_m3/qemu_cortex_m3.dts
44 -- Generated zephyr.dts: .../zephyr/build/zephyr/zephyr.dts
45 …-- Generated devicetree_generated.h: .../zephyr/build/zephyr/include/generated/devicetree_generate…
47 The :file:`zephyr.dts` file is the final devicetree in DTS format.
51 See :ref:`devicetree-in-out-files` for details about these files.
53 .. _dt-get-device:
58 When writing Zephyr applications, you'll often want to get a driver-level
64 .. code-block:: devicetree
70 current-speed = <115200>;
76 my-serial = &serial0;
84 Start by making a :ref:`node identifier <dt-node-identifiers>` for the device
88 .. code-block:: c
105 .. code-block:: c
111 return -ENODEV;
117 build-time, which means there is no runtime penalty. This method is useful if
123 In some situations the device cannot be known at build-time, e.g., if it depends
128 .. code-block:: c
137 If you're having trouble, see :ref:`dt-trouble`. The first thing to check is
140 .. code-block:: c
154 .. code-block:: none
163 .. code-block:: c
175 .. _dts-find-binding:
180 :ref:`dt-bindings` are YAML files which declare what you can do with the nodes
184 If you don't have them already, :ref:`get-devicetree-outputs`. To find a node's
188 .. code-block:: c
206 .. code-block:: c
212 * Binding (compatible = soc-nv-flash):
213 * $ZEPHYR_BASE/dts/bindings/mtd/soc-nv-flash.yaml
217 See :ref:`missing-dt-binding` for troubleshooting.
219 .. _set-devicetree-overlays:
224 Devicetree overlays are explained in :ref:`devicetree-intro`. The CMake
225 variable :makevar:`DTC_OVERLAY_FILE` contains a space- or semicolon-separated
229 like ``\${ZEPHYR_<module>_MODULE_DIR}/<path-to>/dts.overlay``
233 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.
287 For example, if your BOARD.dts contains this node:
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
341 how to set a boolean property to false if it's true in BOARD.dts):
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
390 enable the driver via Kconfig and :ref:`get the struct device <dt-get-device>`
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
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.
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
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 */
456 .. _dt-create-devices-inst:
461 Use this option, which uses :ref:`devicetree-inst-apis`, if possible. However,
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
471 .. code-block:: c
489 .. code-block:: c
520 .. code-block:: c
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
546 .. code-block:: devicetree
551 compatible = "vnd,my-device";
554 compatible = "vnd,my-device";
562 .. code-block:: c
596 .. code-block:: c
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.
627 Search existing bindings and device drivers for examples.
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>`.