Lines Matching +full:check +full:- +full:common +full:- +full:files
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
16 common node definitions via ``#include`` preprocessor directives. This at least
18 is by opening these files, e.g. by looking 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
122 (This check is done for you by :c:func:`device_get_binding`.)
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
162 successfully, the last thing to check is if the device is ready, like this:
164 .. code-block:: c
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
227 list of overlay files to use. If :makevar:`DTC_OVERLAY_FILE` specifies multiple
228 files, they are included in that order by the C preprocessor. A file in a
230 like ``\${ZEPHYR_<module>_MODULE_DIR}/<path-to>/dts.overlay``
233 You can set :makevar:`DTC_OVERLAY_FILE` to contain exactly the files you want
234 to use. Here is an :ref:`example <west-building-dtc-overlay-file>` using
238 these steps, looking for files in your application configuration directory to
245 #. If one or more files have been found in the previous steps, the build system
246 stops looking and just uses those files.
248 system will stop looking for more files.
260 All configuration files will be taken from the application's configuration
261 directory except for files with an absolute path that are given with the
264 See :ref:`Application Configuration Directory <application-configuration-directory>`
267 Using :ref:`shields` will also add devicetree overlay files.
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
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
623 common definitions for devices addressable via a specific bus. This enables
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>`.