1.. _dt-design:
2
3Design goals
4############
5
6Zephyr's use of devicetree has evolved significantly over time, and further
7changes are expected. The following are the general design goals, along with
8specific examples about how they impact Zephyr's source code, and areas where
9more work remains to be done.
10
11Single source for hardware information
12**************************************
13
14Zephyr's built-in device drivers and sample applications shall obtain
15configurable hardware descriptions from devicetree.
16
17Examples
18========
19
20- New device drivers shall use devicetree APIs to determine which :ref:`devices
21  to create <dt-create-devices>`.
22
23- In-tree sample applications shall use :ref:`aliases <dt-alias-chosen>` to
24  determine which of multiple possible generic devices of a given type will be
25  used in the current build. For example, the :zephyr:code-sample:`blinky` sample uses this to
26  determine the LED to blink.
27
28- Boot-time pin muxing and pin control for new SoCs shall be accomplished via a
29  devicetree-based pinctrl driver
30
31Example remaining work
32======================
33
34- Zephyr's :ref:`twister_script` currently use :file:`board.yaml` files to
35  determine the hardware supported by a board. This should be obtained from
36  devicetree instead.
37
38- Legacy device drivers currently use Kconfig to determine which instances of a
39  particular compatible are enabled. This can and should be done with devicetree
40  overlays instead.
41
42- Board-level documentation still contains tables of hardware support which are
43  generated and maintained by hand. This can and should be obtained from the
44  board level devicetree instead.
45
46- Runtime determination of ``struct device`` relationships should be done using
47  information obtained from devicetree, e.g. for device power management.
48
49.. _dt-source-compatibility:
50
51Source compatibility with other operating systems
52*************************************************
53
54Zephyr's devicetree tooling is based on a generic layer which is interoperable
55with other devicetree users, such as the Linux kernel.
56
57Zephyr's binding language *semantics* can support Zephyr-specific attributes,
58but shall not express Zephyr-specific relationships.
59
60Examples
61========
62
63- Zephyr's devicetree source parser, :ref:`dtlib.py <dt-scripts>`, is
64  source-compatible with other tools like `dtc`_ in both directions:
65  :file:`dtlib.py` can parse ``dtc`` output, and ``dtc`` can parse
66  :file:`dtlib.py` output.
67
68- Zephyr's "extended dtlib" library, :file:`edtlib.py`, shall not include
69  Zephyr-specific features. Its purpose is to provide a higher-level view of the
70  devicetree for common elements like interrupts and buses.
71
72  Only the high-level :file:`gen_defines.py` script, which is built on top of
73  :file:`edtlib.py`, contains Zephyr-specific knowledge and features.
74
75.. _dtc: https://git.kernel.org/pub/scm/utils/dtc/dtc.git/about/
76
77Example remaining work
78======================
79
80- Zephyr has a custom :ref:`dt-bindings` language *syntax*. While Linux's
81  dtschema does not yet meet Zephyr's needs, we should try to follow what it is
82  capable of representing in Zephyr's own bindings.
83
84- Due to inflexibility in the bindings language, Zephyr cannot support the full
85  set of bindings supported by Linux.
86
87- Devicetree source sharing between Zephyr and Linux is not done.
88