blob: 0c91bf012486022502dfdeb01de83697d0e6d2a6 [file] [log] [blame]
Andy Gross252da092017-05-24 00:24:50 -05001.. _device-tree:
2
3Device Tree in Zephyr
4########################
5
6Introduction to Device Tree
7***************************
8
9Device tree is a way of describing hardware and configuration information
10for boards. Device tree was adopted for use in the Linux kernel for the
11PowerPC architecture. However, it is now in use for ARM and other
12architectures.
13
14The device tree is a data structure for dynamically describing hardware
15using a Device Tree Source (DTS) data structure language, and compiled
16into a compact Device Tree Blob (DTB) using a Device Tree Compiler (DTC).
17Rather than hard coding every detail of a board's hardware into the
18operating system, the hardware-describing DTB is passed to the operating
19system at boot time. This allows the same compiled Linux kernel to support
20different hardware configurations within an architecture family (e.g., ARM,
David B. Kinder547c74c2017-06-13 15:16:40 -070021x86, PowerPC) and moves a significant part of the hardware description out of
Andy Gross252da092017-05-24 00:24:50 -050022the kernel binary itself.
23
24Traditional usage of device tree involves storing of the Device Tree Blob.
25The DTB is then used during runtime for configuration of device drivers. In
26Zephyr, the DTS information will be used only during compile time.
27Information about the system is extracted from the compiled DTS and used to
28create the application image.
29
30Device tree uses a specific format to describe the device nodes in a system.
31This format is described in `EPAPR document`_.
32
33.. _EPAPR document: http://www.devicetree.org/specifications-pdf
34
35More device tree information can be found at the `device tree repository`_.
36
37.. _device tree repository: https://git.kernel.org/pub/scm/utils/dtc/dtc.git
38
39
40System build requirements
41*************************
42
43The Zephyr device tree feature requires a device tree compiler (DTC) and Python
44YAML packages. Refer to the installation guide for your specific host OS.
45
46:ref:`installing_zephyr_win`
47
48:ref:`installation_linux`
49
50:ref:`installing_zephyr_mac`
51
52
53Zephyr and Device Tree
54**********************
55
56In Zephyr, device tree is used to not only describe hardware, but also to
57describe Zephyr-specific configuration information. The Zephyr-specific
58information is intended to augment the device tree descriptions. The main
59reason for this is to leverage existing device tree files that a SoC vendor may
60already have defined for a given platform.
61
62Today, configuration in Zephyr comes from a number of different places. It can
63come from Kconfig files, CMSIS header files, vendor header files, prj.conf
64files, and other miscellaneous sources. The intent of using device tree is to
65replace or curtail the use of Kconfig files throughout the system, and instead
66use device tree files to describe the configuration of device nodes. CMSIS and
67vendor header files can be used in conjunction with the device tree to fully
68describe hardware. Device tree is not intended to replace CMSIS or vendor
69include files.
70
71The device tree files are compiled using the device tree compiler. The compiler
72runs the .dts file through the C preprocessor to resolve any macro or #defines
73utilized in the file. The output of the compile is another dts formatted file.
74
75After compilation, a python script extracts information from the compiled device
76tree file using a set of rules specified in YAML files. The extracted
77information is placed in a header file that is used by the rest of the code as
78the project is compiled.
79
80A temporary fixup file is required for device tree support on most devices.
81This .fixup file resides in the dts architecture directory and has the same
82name as the master .dts file. The only difference is the suffix is .fixup.
83This fixup file maps the generated include information to the current
84driver/source usage.
85
86Device tree file formats
87************************
88Hardware and software is described inside of device tree files in clear text format.
89These files have the file suffix of .dtsi or .dts. The .dtsi files are meant to
90be included by other files. Typically for a given board you have some number of
91.dtsi include files that pull in common device descriptions that are used across
92a given SoC family.
93
94-----------------------------------------
95Example: FRDM K64F Board and Hexiwear K64
96-----------------------------------------
97Both of these boards are based on the same NXP Kinetis SoC family, the K6X. The
98following shows the include hierarchy for both boards.
99
100dts/arm/frdm_k64.dts includes the following two files::
101
102 dts/arm/nxp/nxp_k6x.dtsi
103 dts/arm/armv7-m.dtsi
104
105dts/arm/hexiwear_k64.dts includes the same two files::
106
107 dts/arm/nxp/nxp_k6x.dtsi
108 dts/arm/armv7-m.dtsi
109
110The board-specific .dts files enable nodes, define the Zephyr-specific items,
111and also adds board-specific changes like gpio/pinmux assignments. These types
112of things will vary based on the board layout and application use.
113
114Currently supported boards
115**************************
116
117Device tree is currently supported on all ARM targets. Support for all other
118architectures is to be completed by release 1.9.
119
120Adding support for a board
121**************************
122
123Adding device tree support for a given board requires adding a number of files.
124These files will contain the DTS information that describes a platform, the
125YAML descriptions that define the contents of a given Device Tree peripheral
126node, and also any fixup files required to support the platform.
127
128When writing Device Tree Source files, it is good to separate out common
129peripheral information that could be used across multiple SoC families or
130boards. DTS files are identified by their file suffix. A .dtsi suffix denotes
131a DTS file that is used as an include in another DTS file. A .dts suffix
132denotes the primary DTS file for a given board.
133
134The primary DTS file will contain at a minimum a version line, optional
135includes, and the root node definition. The root node will contain a model and
136compatible that denotes the unique board described by the .dts file.
137
138--------------------------------
139Device Tree Source File Template
140--------------------------------
141
142.. code::
143
144 /dts-v1/
145 / {
146 model = "Model name for your board";
147 compatible = "compatible for your board";
148 /* rest of file */
149 };
150
151
152One suggestion for starting from scratch on a platform/board is to examine other
153boards and their device tree source files.
154
155The following is a more precise list of required files:
156
157* Base architecture support
158
159 * Add architecture-specific DTS directory, if not already present.
160 Example: dts/arm for ARM.
161 * Add target to dts/<ARCH>/Makefile or create Makefile if not present
162 * Add target specific device tree files for base SoC. These should be
163 .dtsi files to be included in the board-specific device tree files.
164 * Add target specific YAML files in the dts/<ARCH>/yaml directory.
165 Create the yaml directory if not present.
166
167* SoC family support
168
169 * Add one or more SoC family .dtsi files that describe the hardware
170 for a set of devices. The file should contain all the relevant
171 nodes and base configuration that would be applicable to all boards
172 utilizing that SoC family.
173 * Add SoC family YAML files that describe the nodes present in the .dtsi file.
174
175* Board specific support
176
177 * Add a board level .dts file that includes the SoC family .dtsi files
178 and enables the nodes required for that specific board.
179 * Board .dts file should specify the SRAM and FLASH devices, if present.
180 * Add board-specific YAML files, if required. This would occur if the
181 board has additional hardware that is not covered by the SoC family
182 .dtsi/.yaml files.
183
184* Fixup files
185
186 * Fixup files contain mappings from existing Kconfig options to the actual
187 underlying DTS derived configuration #defines. Fixup files are temporary
188 artifacts until additional DTS changes are made to make them unnecessary.
189
190Adding support for device tree in drivers
191*****************************************
192
193As drivers and other source code is converted over to make use of device tree
194generated information, these drivers may require changes to match the generated
195#define information.
196
197
198Source Tree Hierarchy
199*********************
200
201The device tree files are located in a couple of different directories. The
202directory split is done based on architecture, and there is also a common
203directory where architecture agnostic device tree and yaml files are located.
204
205Assuming the current working directory is the ZEPHYR_BASE, the directory
206hierarchy looks like the following::
207
208 dts/common/
209 dts/common/yaml
210 dts/<ARCH>/
211 dts/<ARCH>/yaml
212
213The common directories contain a skeleton.dtsi include file that defines the
214address and size cells. The yaml subdirectory contains common yaml files for
215Zephyr-specific nodes/properties and generic device properties common across
216architectures.
217
218Example: DTS/YAML files for NXP FRDM K64F::
219
220 dts/arm/armv7-m.dtsi
221 dts/arm/k6x/nxp_k6x.dtsi
222 dts/arm/frdm_k64f.dts
223 dts/arm/yaml/arm,v7m-nvic.yaml
224 dts/arm/yaml/k64gpio.yaml
225 dts/arm/yaml/k64pinmux.yaml
226 dts/arm/yaml/k64uart.yaml
227
228YAML definitions for device nodes
229*********************************
230
231Device tree can describe hardware and configuration, but it doesn't tell the
232system which pieces of information are useful, or how to generate configuration
233data from the device tree nodes. For this, we rely on YAML files to describe
234the contents or definition of a device tree node.
235
236A YAML description must be provided for every device node that is to be a source
237of information for the system. This YAML description can be used for more than
238one purpose. It can be used in conjunction with the device tree to generate
239include information. It can also be used to validate the device tree files
240themselves. A device tree file can successfully compile and still not contain
241the necessary pieces required to build the rest of the software. YAML provides
242a means to detect that issue.
243
244YAML files reside in a subdirectory inside the common and architecture-specific
245device tree directories. A YAML template file is provided to show the required
246format. This file is located at:
247
248 dts/common/yaml/device_node.yaml.template
249
250YAML files must end in a .yaml suffix. YAML files are scanned during the
251information extraction phase and are matched to device tree nodes via the
252compatible property.