blob: 761806409a66b4b7d307561902393d0eee20865a [file] [log] [blame]
Andy Gross252da092017-05-24 00:24:50 -05001.. _device-tree:
2
Marti Bolivar85fa5232019-10-04 13:34:15 -07003Devicetree
4##########
Andy Gross252da092017-05-24 00:24:50 -05005
Marti Bolivar85fa5232019-10-04 13:34:15 -07006Zephyr uses the *devicetree* data structure to describe the hardware available
7on a board, as well as its initial configuration in an application. Note that
Josh Gao88ac2922019-12-12 23:01:12 -08008"devicetree" -- without spaces -- is preferred to "device tree". The
Marti Bolivar85fa5232019-10-04 13:34:15 -07009`Devicetree specification`_ fully defines this data structure and its source
10and binary representations.
11
12.. _device-tree-intro:
Anas Nashif03eada32019-02-01 10:09:13 -050013
Anas Nashif276c5892019-01-05 10:23:34 -050014Introduction
15************
Andy Gross252da092017-05-24 00:24:50 -050016
Marti Bolivar85fa5232019-10-04 13:34:15 -070017.. _Devicetree specification: https://www.devicetree.org/
Andy Gross252da092017-05-24 00:24:50 -050018
Marti Bolivar85fa5232019-10-04 13:34:15 -070019This figure shows how devicetree fits into the Zephyr build system:
Erwan Gouriou8223cfb2019-02-19 09:38:49 +010020
Marti Bolivar85fa5232019-10-04 13:34:15 -070021.. figure:: zephyr_dt_build_flow.png
22 :figclass: align-center
Andy Gross252da092017-05-24 00:24:50 -050023
Marti Bolivar85fa5232019-10-04 13:34:15 -070024 Devicetree build flow
Andy Gross252da092017-05-24 00:24:50 -050025
Marti Bolivar85fa5232019-10-04 13:34:15 -070026Zephyr's build system can use a devicetree to generate C language code. This
27code generation uses rules in additional files called :ref:`devicetree bindings
28<bindings>` to control how devicetree data is converted to C definitions. The
29generated code can be included by Zephyr :ref:`device drivers <device_drivers>`
30and other C sources. The C macros generated by this process all begin with
31``DT_``.
Andy Gross252da092017-05-24 00:24:50 -050032
Marti Bolivar85fa5232019-10-04 13:34:15 -070033This differs significantly from how devicetree is used on Linux. The
34Linux kernel would instead read the entire devicetree data structure in its
35binary form, parsing it at runtime in order to load and initialize device
36drivers. Zephyr does not work this way because the size of the devicetree
37binary and associated handling code would be too large to fit comfortably on
38the relatively constrained devices Zephyr supports.
Andy Gross252da092017-05-24 00:24:50 -050039
Marti Bolivar85fa5232019-10-04 13:34:15 -070040As the name indicates, a devicetree is a tree. The human-readable text format
41for this tree is called DTS (for devicetree source), and is defined in the
42Devicetree Specification. Here is an example DTS file:
Andy Gross252da092017-05-24 00:24:50 -050043
Marti Bolivar85fa5232019-10-04 13:34:15 -070044.. code-block:: none
Andy Gross252da092017-05-24 00:24:50 -050045
Marti Bolivar85fa5232019-10-04 13:34:15 -070046 /dts-v1/;
Andy Gross252da092017-05-24 00:24:50 -050047
Marti Bolivar85fa5232019-10-04 13:34:15 -070048 / {
49 a-node {
50 subnode_label: a-sub-node {
51 foo = <3>;
52 };
53 };
54 };
Andy Gross252da092017-05-24 00:24:50 -050055
Marti Bolivar85fa5232019-10-04 13:34:15 -070056This example has three nodes:
Andy Gross252da092017-05-24 00:24:50 -050057
Marti Bolivar85fa5232019-10-04 13:34:15 -070058#. A root node
59#. A node named ``a-node``, which is a child of the root node
60#. A node named ``a-sub-node``, which is a child of ``a-node``
Andy Gross252da092017-05-24 00:24:50 -050061
Marti Bolivar85fa5232019-10-04 13:34:15 -070062Nodes can be given *labels*, which are unique shorthands that can be used to
63refer to the labeled node elsewhere in the devicetree. Above, ``a-sub-node``
64has label ``subnode_label``.
Andy Gross252da092017-05-24 00:24:50 -050065
Marti Bolivar85fa5232019-10-04 13:34:15 -070066Devicetree nodes have *paths* identifying their locations in the tree. Like
67Unix file system paths, devicetree paths are strings separated by slashes
68(``/``), and the root node's path is a single slash: ``/``. Otherwise, each
69node's path is formed by concatenating the node's ancestors' names with the
70node's own name, separated by slashes. For example, the full path to
71``a-sub-node`` is ``/a-node/a-sub-node``.
72
73Devicetree nodes can also have *properties*. Properties are name/value
74pairs. The values are simple byte arrays. Node ``a-sub-node`` has a property
75named ``foo``, whose value is a 32-bit big-endian unsigned integer with value
763. The size and type of ``foo``\ 's value are implied by the enclosing angle
77brackets (``<`` and ``>``) in the DTS. Refer to the Devicetree Specification
78for a complete list of ways to write a property value in a DTS file.
79
80In practice, devicetree nodes correspond to some hardware, and the node
81hierarchy reflects the hardware's physical layout. For example, let's consider
82a board with three I2C peripherals connected to an I2C bus master on an SoC,
83like this:
84
85.. figure:: zephyr_dt_i2c_high_level.png
86 :alt: representation of a board with three I2C peripherals
87 :figclass: align-center
88
89Nodes corresponding to the I2C bus master and each I2C peripheral would be
90present in this board's devicetree. Reflecting the hardware layout, the
91devicetree's peripheral nodes would be children of the bus master node. Similar
92conventions exist for representing other types of hardware in devicetree.
93
94The corresponding DTS would look something like this:
95
96.. code-block:: none
97
98 / {
99 soc {
100 i2c-bus-master {
101 i2c-peripheral-1 {
102 };
103 i2c-peripheral-2 {
104 };
105 i2c-peripheral-3 {
106 };
107 };
108 };
109 };
110
111Properties are used in practice to describe or configure the hardware the node
112represents. For example, an I2C peripheral's node has a property whose value is
113the peripheral's address on the bus.
114
115Here's a tree representing the same example, but with real-world node
116names and properties you might see when working with I2C devices.
117
118.. figure:: zephyr_dt_i2c_example.png
119 :figclass: align-center
120
121 I2C devicetree example with real-world names and properties
122
123Above, node names -- like ``i2c@40003000`` -- are at the top of each node, with
124a gray background, except for the root node, which is shown using its path
125``/``. Properties are shown as ``name=value`` pairs below the node names.
126
127Some important properties are:
128
129- **compatible**: this says what "kind" of device the node represents. Its
130 value is a null-terminated string in the format "vendor,device", like
131 ``"avago,apds9960"``, or a sequence of these, like ``"ti,hdc",
132 "ti,hdc1010"``. The build system uses the compatible property to find the
133 right bindings for the node.
134- **label**: the device's name according to Zephyr's :ref:`device_drivers`. The
135 value can be passed to :c:func:`device_get_binding()` to retrieve the
136 corresponding driver-level :ref:`struct device* <device_struct>`. This
137 pointer can then be passed to the correct driver API by application code to
138 interact with the device. For example, calling
139 ``device_get_binding("I2C_0")`` would return a pointer to a device
140 structure which could be passed to :ref:`I2C API <i2c_api>` functions like
141 :c:func:`i2c_transfer()`. The generated C header will also contain a macro
142 which expands to this string.
143- **reg**: information used to address the device. This could be a
144 memory-mapped I/O address range (as with ``i2c@40003000``\ 's reg property),
145 an I2C bus address (as with ``apds9960@39`` and its devicetree siblings), a
146 SPI chip select line, or some other value depending on the kind of device the
147 node represents.
148
149This tree has the following DTS.
150
151.. code-block:: none
152
153 / {
154 soc {
155 i2c@40003000 {
156 compatible = "nordic,nrf-twim";
157 label = "I2C_0";
158 reg = <0x40003000 0x1000>;
159
160 apds9960@39 {
161 compatible = "avago,apds9960";
162 label = "APDS9960";
163 reg = <0x39>;
164 };
165 ti_hdc@43 {
166 compatible = "ti,hdc", "ti,hdc1010";
167 label = "HDC1010;
168 reg = <0x43>;
169 };
170 mma8652fc@1d {
171 compatible = "nxp,fxos8700", "nxp,mma8652fc";
172 label = "MMA8652FC";
173 reg = <0x1d>;
174 };
175 };
176 };
177 };
178
179Input and output files
Andy Gross252da092017-05-24 00:24:50 -0500180**********************
181
Marti Bolivar85fa5232019-10-04 13:34:15 -0700182The first figure in the :ref:`device-tree-intro` shows how devicetree fits into
183the Zephyr build system. This section describes the input and output files in
184more detail.
Andy Gross252da092017-05-24 00:24:50 -0500185
Marti Bolivar85fa5232019-10-04 13:34:15 -0700186.. figure:: zephyr_dt_inputs_outputs.png
187 :figclass: align-center
Erwan Gouriou8223cfb2019-02-19 09:38:49 +0100188
Marti Bolivar85fa5232019-10-04 13:34:15 -0700189 Devicetree input (green) and output (yellow) files
Andy Gross252da092017-05-24 00:24:50 -0500190
Marti Bolivar85fa5232019-10-04 13:34:15 -0700191DTS files usually have ``.dts`` or ``.dtsi`` (for Devicetree Source Include)
192extensions. Zephyr's build system looks for a file named :file:`BOARD.dts` in
193the board definition directory; this file contains the board's base
194devicetree. See :ref:`dt_k6x_example` for real-world examples.
Andy Gross252da092017-05-24 00:24:50 -0500195
Marti Bolivar85fa5232019-10-04 13:34:15 -0700196The build system combines the board's DTS with additional input files called
197*overlays* to produce a final devicetree source file. Overlays are also written
198in the DTS format, but have a :file:`.overlay` extension to make it clear that
199they're overlays. You can specify the overlay files to use at build time using
200the :makevar:`DTC_OVERLAY_FILE` CMake variable described in
201:ref:`important-build-vars`. The build system also looks for devicetree
202overlays in several locations by default; see :ref:`application_dt` for the
203list.
Andy Gross252da092017-05-24 00:24:50 -0500204
Marti Bolivar85fa5232019-10-04 13:34:15 -0700205Overlays can be used to add or delete nodes from the tree, or to modify node
206properties and their values. Along with Kconfig, devicetree overlays let you
207reconfigure the kernel and device drivers without modifying their source code.
208
209Before they are combined, the C preprocessor is run on :file:`BOARD.dts` and any
210overlays. This allows these files to use C macros and include directives.
211
212The combined devicetree is written to a DTS file named
213:file:`BOARD.dts_compiled` in the application build directory. This file
214contains the final devicetree.
215
216This devicetree and the set of :ref:`bindings` are then used to generate C
217definitions using scripts in :zephyr_file:`scripts/dts/`. These definitions can
218be included via the ``generated_dts_board.h`` header file, which the build
219system places on the C preprocessor include path. This file is not generated;
220it is in :zephyr_file:`include/generated_dts_board.h`. (Its name was chosen
221for backwards compatibility.)
222
223**Do not include the generated C headers in the build directory directly**. Use
224``generated_dts_board.h`` instead.
225
226Zephyr device drivers typically use information from ``generated_dts_board.h``
227to statically allocate and initialize :ref:`struct device <device_struct>`
228instances. Property values from ``generated_dts_board.h`` are usually stored in
229ROM in the value pointed to by a ``device->config->config_info`` field. For
230example, a ``struct device`` corresponding to an I2C peripheral would store the
231peripheral address in its ``reg`` property there.
232
233Application source code with a pointer to the ``struct device`` can then pass
234it to driver APIs in :zephyr_file:`include/drivers/`. These API functions
235usually take a ``struct device*`` as their first argument. This allows the
236driver API to use information from devicetree to interact with the device
237hardware.
238
239Temporary "fixup" files are currently required for devicetree support on most
240devices. These fixup files by default reside in the board and soc directories
241and are named ``dts_fixup.h``. These fixup files map the generated include
242information to the current driver/source usage. They exist for historical
243reasons; Zephyr is moving away from needing or using these files.
Ulf Magnusson850e3622019-07-26 15:53:58 +0200244
Marti Bolivar9935fdd2019-10-07 11:04:55 -0700245.. _dt_k6x_example:
246
247Example: FRDM-K64F and Hexiwear K64
248===================================
249
250.. Give the filenames instead of the full paths below, as it's easier to read.
251 The cramped 'foo.dts<path>' style avoids extra spaces before commas.
252
253The FRDM-K64F and Hexiwear K64 board devicetrees are defined in
254:zephyr_file:`frdm_k64fs.dts <boards/arm/frdm_k64f/frdm_k64f.dts>` and
255:zephyr_file:`hexiwear_k64.dts <boards/arm/hexiwear_k64/hexiwear_k64.dts>`
256respectively. Both boards have NXP SoCs from the same Kinetis SoC family, the
257K6X.
258
259Common devicetree definitions for K6X are stored in :zephyr_file:`nxp_k6x.dtsi
260<dts/arm/nxp/nxp_k6x.dtsi>`, which is included by both board :file:`.dts`
261files. :zephyr_file:`nxp_k6x.dtsi<dts/arm/nxp/nxp_k6x.dtsi>` in turn includes
262:zephyr_file:`armv7-m.dtsi<dts/arm/armv7-m.dtsi>`, which has common definitions
263for Arm v7-M cores.
264
265Since :zephyr_file:`nxp_k6x.dtsi<dts/arm/nxp/nxp_k6x.dtsi>` is meant to be
266generic across K6X-based boards, it leaves many devices disabled by default
267using ``status`` properties. For example, there is a CAN controller defined as
268follows (with unimportant parts skipped):
269
270.. code-block:: none
271
272 can0: can@40024000 {
273 ...
274 status = "disabled";
275 ...
276 };
277
278It is up to the board :file:`.dts` or application overlay files to enable these
279devices as desired, by setting ``status = "okay"``. The board :file:`.dts`
280files are also responsible for any board-specific configuration of the device,
281such as adding nodes for on-board sensors, LEDs, buttons, etc.
282
283For example, FRDM-K64 (but not Hexiwear K64) :file:`.dts` enables the CAN
284controller and sets the bus speed:
285
286.. code-block:: none
287
288 &can0 {
289 status = "okay";
290 bus-speed = <125000>;
291 };
292
293The ``&can0 { ... };`` syntax adds/overrides properties on the node with label
294``can0``, i.e. the ``can@4002400`` node defined in the :file:`.dtsi` file.
295
296Other examples of board-specific customization is pointing properties in
297``aliases`` and ``chosen`` to the right nodes (see :ref:`dt-alias-chosen`), and
298making GPIO/pinmux assignments.
299
Carles Cufi45745052018-06-21 12:08:32 +0200300.. _dt_vs_kconfig:
301
Marti Bolivar85fa5232019-10-04 13:34:15 -0700302Devicetree vs Kconfig
303*********************
Carles Cufi45745052018-06-21 12:08:32 +0200304
Marti Bolivar85fa5232019-10-04 13:34:15 -0700305Along with devicetree, Zephyr also uses the Kconfig language to configure the
306source code. Whether to use devicetree or Kconfig for a particular purpose can
307sometimes be confusing. This section should help you decide which one to use.
Carles Cufi45745052018-06-21 12:08:32 +0200308
Marti Bolivar85fa5232019-10-04 13:34:15 -0700309In short:
Carles Cufi45745052018-06-21 12:08:32 +0200310
Marti Bolivar85fa5232019-10-04 13:34:15 -0700311* Use devicetree to describe **hardware** and its **boot-time configuration**.
312 Examples include peripherals on a board, boot-time clock frequencies,
313 interrupt lines, etc.
314* Use Kconfig to configure **software support** to build into the final
315 image. Examples include whether to add networking support, which drivers are
316 needed by the application, etc.
Carles Cufi45745052018-06-21 12:08:32 +0200317
Marti Bolivar85fa5232019-10-04 13:34:15 -0700318In other words, devicetree mainly deals with hardware, and Kconfig with
319software.
Carles Cufi45745052018-06-21 12:08:32 +0200320
Marti Bolivar85fa5232019-10-04 13:34:15 -0700321For example, consider a board containing a SoC with 2 UART, or serial port,
322instances.
Carles Cufi45745052018-06-21 12:08:32 +0200323
Marti Bolivar85fa5232019-10-04 13:34:15 -0700324* The fact that the board has this UART **hardware** is described with two UART
325 nodes in the devicetree. These provide the UART type (via the ``compatible``
326 property) and certain settings such as the address range of the hardware
327 peripheral registers in memory (via the ``reg`` property).
328* Additionally, the UART **boot-time configuration** is also described with
329 devicetree. This could include configuration such as the RX IRQ line's
330 priority and the UART baud rate. These may be modifiable at runtime, but
331 their boot-time configuration is described in devicetree.
332* Whether or not to include **software support** for UART in the build is
333 controlled via Kconfig. Applications which do not need to use the UARTs can
334 remove the driver source code from the build using Kconfig, even though the
335 board's devicetree still includes UART nodes.
Carles Cufi45745052018-06-21 12:08:32 +0200336
Marti Bolivar85fa5232019-10-04 13:34:15 -0700337As another example, consider a device with a 2.4GHz, multi-protocol radio
338supporting both the Bluetooth Low Energy and 802.15.4 wireless technologies.
Carles Cufi45745052018-06-21 12:08:32 +0200339
Marti Bolivar85fa5232019-10-04 13:34:15 -0700340* Devicetree should be used to describe the presence of the radio **hardware**,
341 what driver or drivers it's compatible with, etc.
342* **Boot-time configuration** for the radio, such as TX power in dBm, should
343 also be specified using devicetree.
344* Kconfig should determine which **software features** should be built for the
345 radio, such as selecting a BLE or 802.15.4 protocol stack.
Carles Cufi45745052018-06-21 12:08:32 +0200346
Marti Bolivar85fa5232019-10-04 13:34:15 -0700347There are two noteworthy **exceptions** to these rules:
Carles Cufi45745052018-06-21 12:08:32 +0200348
Marti Bolivar85fa5232019-10-04 13:34:15 -0700349* Devicetree's ``chosen`` keyword, which allows the user to select a specific
350 instance of a hardware device to be used for a particular purpose. An example
351 of this is selecting a particular UART for use as the system's console.
352* Devicetree's ``status`` keyword, which allows the user to enable or disable a
353 particular instance of a hardware device. This takes precedence over related
354 Kconfig options which serve a similar purpose.
David B. Kinder2670bd62017-06-19 10:13:50 -0700355
Andy Gross252da092017-05-24 00:24:50 -0500356Currently supported boards
357**************************
358
Marti Bolivar85fa5232019-10-04 13:34:15 -0700359Devicetree is currently supported on all embedded targets except posix
Daniel Leungb7eb04b2019-10-24 12:57:57 -0700360(boards/posix).
Andy Gross252da092017-05-24 00:24:50 -0500361
362Adding support for a board
363**************************
364
Marti Bolivar85fa5232019-10-04 13:34:15 -0700365Adding devicetree support for a given board requires adding a number of files.
Andy Gross252da092017-05-24 00:24:50 -0500366These files will contain the DTS information that describes a platform, the
Marti Bolivar85fa5232019-10-04 13:34:15 -0700367bindings in YAML format, and any fixup files required to support the platform.
Andy Gross252da092017-05-24 00:24:50 -0500368
Marti Bolivar85fa5232019-10-04 13:34:15 -0700369It is best practice to separate common peripheral information that could be
370used across multiple cores, SoC families, or boards in :file:`.dtsi` files,
371reserving the :file:`.dts` suffix for the primary DTS file for a given board.
Andy Gross252da092017-05-24 00:24:50 -0500372
Marti Bolivar85fa5232019-10-04 13:34:15 -0700373Devicetree Source File Template
374===============================
Andy Gross252da092017-05-24 00:24:50 -0500375
Marti Bolivar85fa5232019-10-04 13:34:15 -0700376A board's :file:`.dts` file contains at least a version line, optional
377includes, and a root node definition with ``model`` and ``compatible``
378properties. These property values denote the particular board.
Andy Gross252da092017-05-24 00:24:50 -0500379
Ulf Magnussondd5ff392019-02-26 17:20:43 +0100380.. code-block:: none
Andy Gross252da092017-05-24 00:24:50 -0500381
Marti Bolivar85fa5232019-10-04 13:34:15 -0700382 /dts-v1/;
Ulf Magnussondd5ff392019-02-26 17:20:43 +0100383
Marti Bolivar85fa5232019-10-04 13:34:15 -0700384 #include <vendor/soc.dtsi>
Andy Gross252da092017-05-24 00:24:50 -0500385
Marti Bolivar85fa5232019-10-04 13:34:15 -0700386 / {
387 model = "Human readable board name";
388 compatible = "vendor,soc-on-your-board's-mcu";
389 /* rest of file */
390 };
Andy Gross252da092017-05-24 00:24:50 -0500391
Marti Bolivar85fa5232019-10-04 13:34:15 -0700392You can use other board :file:`.dts` files as a starting point.
Andy Gross252da092017-05-24 00:24:50 -0500393
394The following is a more precise list of required files:
395
396* Base architecture support
397
398 * Add architecture-specific DTS directory, if not already present.
Marti Bolivar85fa5232019-10-04 13:34:15 -0700399 Example: dts/arm for Arm.
400 * Add target specific devicetree files for base SoC. These should be
401 .dtsi files to be included in the board-specific devicetree files.
Erwan Gouriou8223cfb2019-02-19 09:38:49 +0100402 * Add target specific YAML binding files in the dts/bindings/ directory.
Andy Gross252da092017-05-24 00:24:50 -0500403 Create the yaml directory if not present.
404
405* SoC family support
406
407 * Add one or more SoC family .dtsi files that describe the hardware
408 for a set of devices. The file should contain all the relevant
409 nodes and base configuration that would be applicable to all boards
410 utilizing that SoC family.
Erwan Gouriou8223cfb2019-02-19 09:38:49 +0100411 * Add SoC family YAML binding files that describe the nodes present in the .dtsi file.
Andy Gross252da092017-05-24 00:24:50 -0500412
413* Board specific support
414
415 * Add a board level .dts file that includes the SoC family .dtsi files
416 and enables the nodes required for that specific board.
417 * Board .dts file should specify the SRAM and FLASH devices, if present.
Andrzej Puzdrowski77532ae2018-01-17 11:33:20 +0100418
419 * Flash device node might specify flash partitions. For more details see
Xuan Ze8c94b532018-07-02 20:25:02 +0800420 :ref:`flash_partitions`
Andrzej Puzdrowski77532ae2018-01-17 11:33:20 +0100421
Erwan Gouriou8223cfb2019-02-19 09:38:49 +0100422 * Add board-specific YAML binding files, if required. This would occur if the
Andy Gross252da092017-05-24 00:24:50 -0500423 board has additional hardware that is not covered by the SoC family
424 .dtsi/.yaml files.
425
426* Fixup files
427
428 * Fixup files contain mappings from existing Kconfig options to the actual
429 underlying DTS derived configuration #defines. Fixup files are temporary
430 artifacts until additional DTS changes are made to make them unnecessary.
431
Carles Cufi1cce63a2018-01-31 18:00:49 +0100432* Overlay Files (optional)
433
434 * Overlay files contain tweaks or changes to the SoC and Board support files
Marti Bolivar85fa5232019-10-04 13:34:15 -0700435 described above. They can be used to modify devicetree configurations
Carles Cufi1cce63a2018-01-31 18:00:49 +0100436 without having to change the SoC and Board files. See
437 :ref:`application_dt` for more information on overlay files and the Zephyr
438 build system.
439
Carles Cufi60751332018-12-05 18:58:47 +0100440.. _dt-alias-chosen:
441
442``aliases`` and ``chosen`` nodes
443================================
444
445Using an alias with a common name for a particular node makes it easier for you
Marti Bolivar85fa5232019-10-04 13:34:15 -0700446to write board-independent source code. Devicetree ``aliases`` nodes are used
Carles Cufi60751332018-12-05 18:58:47 +0100447for this purpose, by mapping certain generic, commonly used names to specific
448hardware resources:
449
450.. code-block:: yaml
451
452 aliases {
453 led0 = &led0;
454 sw0 = &button0;
455 sw1 = &button1;
456 uart-0 = &uart0;
457 uart-1 = &uart1;
458 };
459
460Certain software subsystems require a specific hardware resource to bind to in
461order to function properly. Some of those subsystems are used with many
Marti Bolivar85fa5232019-10-04 13:34:15 -0700462different boards, which makes using the devicetree ``chosen`` nodes very
Carles Cufi60751332018-12-05 18:58:47 +0100463convenient. By doing, so the software subsystem can rely on having the specific
464hardware peripheral assigned to it. In the following example we bind the shell
465to ``uart1`` in this board:
466
467.. code-block:: yaml
468
469 chosen {
470 zephyr,shell-uart = &uart1;
471 };
472
473The full set of Zephyr-specific ``chosen`` nodes follows:
474
475.. list-table::
476 :header-rows: 1
477
478 * - ``chosen`` node name
479 - Generated symbol
480
481 * - ``zephyr,flash``
482 - ``CONFIG_FLASH``
483 * - ``zephyr,sram``
Ulf Magnusson4099b972019-02-26 15:34:44 +0100484 - ``CONFIG_SRAM_SIZE``/``CONFIG_SRAM_BASE_ADDRESS``
485 (via ``DT_SRAM_SIZE``/``DT_SRAM_BASE_ADDRESS``)
Carles Cufi60751332018-12-05 18:58:47 +0100486 * - ``zephyr,ccm``
Kumar Galabfaaa6b2019-02-08 08:09:47 -0600487 - ``DT_CCM``
Carles Cufi60751332018-12-05 18:58:47 +0100488 * - ``zephyr,console``
Erwan Gouriou8223cfb2019-02-19 09:38:49 +0100489 - ``DT_UART_CONSOLE_ON_DEV_NAME``
Carles Cufi60751332018-12-05 18:58:47 +0100490 * - ``zephyr,shell-uart``
Erwan Gouriou8223cfb2019-02-19 09:38:49 +0100491 - ``DT_UART_SHELL_ON_DEV_NAME``
Carles Cufi60751332018-12-05 18:58:47 +0100492 * - ``zephyr,bt-uart``
Erwan Gouriou8223cfb2019-02-19 09:38:49 +0100493 - ``DT_BT_UART_ON_DEV_NAME``
Carles Cufi60751332018-12-05 18:58:47 +0100494 * - ``zephyr,uart-pipe``
Erwan Gouriou8223cfb2019-02-19 09:38:49 +0100495 - ``DT_UART_PIPE_ON_DEV_NAME``
Carles Cufi60751332018-12-05 18:58:47 +0100496 * - ``zephyr,bt-mon-uart``
Erwan Gouriou8223cfb2019-02-19 09:38:49 +0100497 - ``DT_BT_MONITOR_ON_DEV_NAME``
Carles Cufi60751332018-12-05 18:58:47 +0100498 * - ``zephyr,uart-mcumgr``
Erwan Gouriou8223cfb2019-02-19 09:38:49 +0100499 - ``DT_UART_MCUMGR_ON_DEV_NAME``
Carles Cufi60751332018-12-05 18:58:47 +0100500
Erwan Gouriou8223cfb2019-02-19 09:38:49 +0100501
Marti Bolivar85fa5232019-10-04 13:34:15 -0700502Adding support for devicetree in drivers
503****************************************
Andy Gross252da092017-05-24 00:24:50 -0500504
Marti Bolivar85fa5232019-10-04 13:34:15 -0700505As drivers and other source code is converted over to make use of devicetree
Andy Gross252da092017-05-24 00:24:50 -0500506generated information, these drivers may require changes to match the generated
507#define information.
508
509
510Source Tree Hierarchy
511*********************
512
Marti Bolivar85fa5232019-10-04 13:34:15 -0700513The devicetree files are located in a couple of different directories. The
Andy Gross252da092017-05-24 00:24:50 -0500514directory split is done based on architecture, and there is also a common
Marti Bolivar85fa5232019-10-04 13:34:15 -0700515directory where architecture agnostic devicetree and YAML binding files are
Erwan Gouriou8223cfb2019-02-19 09:38:49 +0100516located.
Andy Gross252da092017-05-24 00:24:50 -0500517
518Assuming the current working directory is the ZEPHYR_BASE, the directory
519hierarchy looks like the following::
520
521 dts/common/
Andy Gross252da092017-05-24 00:24:50 -0500522 dts/<ARCH>/
Kumar Gala2b50be62017-12-01 11:33:17 -0600523 dts/bindings/
524 boards/<ARCH>/<BOARD>/
Andy Gross252da092017-05-24 00:24:50 -0500525
Marti Bolivar85fa5232019-10-04 13:34:15 -0700526The common directory contains a ``skeleton.dtsi`` which provides devicetree root
Erwan Gouriou8223cfb2019-02-19 09:38:49 +0100527node definition. The bindings subdirectory contains YAML binding files used
528to instruct how the python DTS parsing script should extract nodes information
529in a format that will be usable by the system.
Andy Gross252da092017-05-24 00:24:50 -0500530
Kumar Gala2b50be62017-12-01 11:33:17 -0600531Example: Subset of DTS/YAML files for NXP FRDM K64F (Subject to Change)::
Andy Gross252da092017-05-24 00:24:50 -0500532
533 dts/arm/armv7-m.dtsi
534 dts/arm/k6x/nxp_k6x.dtsi
Kumar Gala2b50be62017-12-01 11:33:17 -0600535 boards/arm/frdm_k64f/frdm_k64f.dts
536 dts/bindings/interrupt-controller/arm,v7m-nvic.yaml
537 dts/bindings/gpio/nxp,kinetis-gpio.yaml
538 dts/bindings/pinctrl/nxp,kinetis-pinmux.yaml
539 dts/bindings/serial/nxp,kinetis-uart.yaml
Andy Gross252da092017-05-24 00:24:50 -0500540
Ulf Magnusson850e3622019-07-26 15:53:58 +0200541.. _bindings:
Andy Gross252da092017-05-24 00:24:50 -0500542
Marti Bolivar85fa5232019-10-04 13:34:15 -0700543Devicetree Bindings
544*******************
Andy Gross252da092017-05-24 00:24:50 -0500545
Ulf Magnusson850e3622019-07-26 15:53:58 +0200546``.dts`` files describe the available hardware devices, but don't tell the
547system which pieces of information are useful, or what kind of configuration
548output (``#define``'s) should be generated. *Bindings* provide this
549information. Bindings are files in YAML format.
Andy Gross252da092017-05-24 00:24:50 -0500550
Ulf Magnusson850e3622019-07-26 15:53:58 +0200551Configuration output is only generated for devices that have bindings.
Andy Gross252da092017-05-24 00:24:50 -0500552
Ulf Magnusson850e3622019-07-26 15:53:58 +0200553Nodes are mapped to bindings via their ``compatible`` string(s). Take
554the following node as an example:
Andy Gross252da092017-05-24 00:24:50 -0500555
Ulf Magnusson850e3622019-07-26 15:53:58 +0200556.. code-block:: none
557
558 bar-device {
559 compatible = "foo-company,bar-device";
560 ...
561 };
562
563This node would get mapped to a binding with this in it:
564
565.. code-block:: yaml
566
Ulf Magnussona0fceff2019-08-19 20:32:25 +0200567 compatible: "foo-company,bar-device"
568
569You might also run across this legacy syntax, which works the same way:
570
571.. code-block:: yaml
572
Ulf Magnusson850e3622019-07-26 15:53:58 +0200573 ...
574
575 properties:
576 compatible:
577 constraint: "foo-company,bar-device"
578
579 ...
580
581Bindings are stored in :zephyr_file:`dts/bindings/`. The filename usually
582matches the ``compatible`` string.
583
584If a node has more than one ``compatible`` string, then the first binding found
585is used, going from the first string to the last. For example, a node with
586``compatible = "foo-company,bar-device", "generic-bar-device"`` would get
587mapped to the binding for ``generic-bar-device`` if there is no binding for
588``foo-company,bar-device``.
589
590If a node appears on a bus (e.g. I2C or SPI), then the bus type is also taken
591into account when mapping nodes to bindings. See the description of ``parent``
592and ``child`` in the template below.
593
594Below is a template that shows the format of binding files, stored in
Kumar Galac24a7912019-08-15 11:59:40 -0500595:zephyr_file:`dts/binding-template.yaml`.
Ulf Magnusson850e3622019-07-26 15:53:58 +0200596
Kumar Galac24a7912019-08-15 11:59:40 -0500597.. literalinclude:: ../../../dts/binding-template.yaml
Ulf Magnusson850e3622019-07-26 15:53:58 +0200598 :language: yaml
Anas Nashif03eada32019-02-01 10:09:13 -0500599
Ulf Magnusson5bc06e82019-09-16 19:04:41 +0200600.. _legacy_binding_syntax:
601
602Legacy binding syntax
603=====================
604
605Various parts of the binding syntax were simplified and generalized for the
606Zephyr 2.1 release.
607
608The binding below shows various legacy syntax.
609
610.. code-block:: yaml
611
612 title: ...
613 description: ...
614
615 inherits:
616 !include foo.yaml
617
618 parent:
619 bus: spi
620
621 properties:
622 compatible:
623 constraint: "company,device"
624 type: string-array
625
626 frequency:
627 type: int
628 category: optional
629
630 sub-node:
631 properties:
632 child-prop:
633 type: int
634 category: required
635
Ulf Magnussona7788682019-10-03 05:28:26 +0200636 # Assume this is a binding for an interrupt controller
637 "#cells":
638 - irq
639 - priority
640 - flags
641
Ulf Magnusson5bc06e82019-09-16 19:04:41 +0200642This should now be written like this:
643
644.. code-block:: yaml
645
646 title: ...
647 description: ...
648
649 compatible: "company,device"
650
651 include: foo.yaml
652
653 parent-bus: spi
654
655 properties:
656 frequency:
657 type: int
658 required: false
659
Ulf Magnusson842e1d42019-10-03 00:37:06 +0200660 child-binding:
Ulf Magnusson5bc06e82019-09-16 19:04:41 +0200661 title: ...
662 description: ...
663
664 properties:
665 child-prop:
666 type: int
667 required: true
668
Ulf Magnussona7788682019-10-03 05:28:26 +0200669 interrupt-cells:
670 - irq
671 - priority
672 - cells
673
Ulf Magnusson5bc06e82019-09-16 19:04:41 +0200674The legacy syntax is still supported for backwards compatibility, but generates
675deprecation warnings. Support will be dropped in the Zephyr 2.3 release.
Anas Nashif03eada32019-02-01 10:09:13 -0500676
Erwan Gouriou8223cfb2019-02-19 09:38:49 +0100677Include files generation
678************************
679
680At build time, after a board's ``.dts`` file has been processed by the DTC
Marti Bolivar85fa5232019-10-04 13:34:15 -0700681(Devicetree Compiler), a corresponding ``.dts_compiled`` file is generated
Erwan Gouriou8223cfb2019-02-19 09:38:49 +0100682under the ``zephyr`` directory.
683This ``.dts_compiled`` file is processed by the python DTS parsing script
684and generates an include file named
685``include/generated/generated_dts_board_unfixed.h``
686that holds all the information extracted from the DTS file with
687the format specified by the YAML bindings. For example:
688
689.. code-block:: c
690
691 /* gpio_keys */
692 #define DT_GPIO_KEYS_0 1
693
694 /* button_0 */
Kumar Galaa614a022019-06-22 10:51:09 -0500695 #define DT_GPIO_KEYS_BUTTON_0_GPIOS_CONTROLLER "GPIO_2"
696 #define DT_GPIO_KEYS_BUTTON_0_GPIOS_FLAGS 0
697 #define DT_GPIO_KEYS_BUTTON_0_GPIOS_PIN 6
Erwan Gouriou8223cfb2019-02-19 09:38:49 +0100698 #define DT_GPIO_KEYS_BUTTON_0_LABEL "User SW2"
Kumar Gala284bc9d2019-06-22 10:57:14 -0500699
700 #define DT_GPIO_KEYS_SW1_GPIOS_CONTROLLER DT_GPIO_KEYS_BUTTON_0_GPIOS_CONTROLLER
701 #define DT_GPIO_KEYS_SW1_GPIOS_FLAGS DT_GPIO_KEYS_BUTTON_0_GPIOS_FLAGS
702 #define DT_GPIO_KEYS_SW1_GPIOS_PIN DT_GPIO_KEYS_BUTTON_0_GPIOS_PIN
703 #define DT_ALIAS_SW1_GPIOS_CONTROLLE DT_GPIO_KEYS_BUTTON_0_GPIOS_CONTROLLER
704 #define DT_ALIAS_SW1_GPIOS_FLAGS DT_GPIO_KEYS_BUTTON_0_GPIOS_FLAGS
705 #define DT_ALIAS_SW1_GPIOS_PIN DT_GPIO_KEYS_BUTTON_0_GPIOS_PIN
706 #define DT_ALIAS_SW1_LABEL DT_GPIO_KEYS_BUTTON_0_LABEL
707
Erwan Gouriou8223cfb2019-02-19 09:38:49 +0100708
709Additionally, a file named ``generated_dts_board_fixups.h`` is
710generated in the same directory concatenating all board-related fixup files.
711
712The include file ``include/generated_dts_board.h`` includes both these generated
Marti Bolivar85fa5232019-10-04 13:34:15 -0700713files, giving Zephyr C source files access to the board's devicetree information.
Anas Nashif03eada32019-02-01 10:09:13 -0500714
Peter Bigot4d972522019-10-17 16:47:44 -0500715GPIO Nexus Nodes
716****************
717
718Each board has a set of General Purpose Input/Output (GPIO)
719peripherals that can be accessed through the :ref:`GPIO<gpio>` module.
720Many boards provide headers that allow :ref:`shields<shields>` from
721other vendors to be mounted on their boards. Each shield identifies
722its hardware in a devicetree overlay.
723
724GPIOs accessed by the shield peripherals must be identified using the
725shield GPIO abstraction, for example from the ``arduino-r3-header``
726compatible. Boards that provide the header must map the header pins
727to SOC-specific pins. This is accomplished by including a `nexus
728node`_ that looks like the following into the board devicetree file:
729
730.. _nexus node:
731 https://github.com/devicetree-org/devicetree-specification/blob/4b1dac80eaca45b4babf5299452a951008a5d864/source/devicetree-basics.rst#nexus-nodes-and-specifier-mapping
732
733.. code-block:: none
734
735 arduino_header: connector {
736 compatible = "arduino-header-r3";
737 #gpio-cells = <2>;
738 gpio-map-mask = <0xffffffff 0xffffffc0>;
739 gpio-map-pass-thru = <0 0x3f>;
740 gpio-map = <0 0 &gpioa 0 0>, /* A0 */
741 <1 0 &gpioa 1 0>, /* A1 */
742 <2 0 &gpioa 4 0>, /* A2 */
743 <3 0 &gpiob 0 0>, /* A3 */
744 <4 0 &gpioc 1 0>, /* A4 */
745 <5 0 &gpioc 0 0>, /* A5 */
746 <6 0 &gpioa 3 0>, /* D0 */
747 <7 0 &gpioa 2 0>, /* D1 */
748 <8 0 &gpioa 10 0>, /* D2 */
749 <9 0 &gpiob 3 0>, /* D3 */
750 <10 0 &gpiob 5 0>, /* D4 */
751 <11 0 &gpiob 4 0>, /* D5 */
752 <12 0 &gpiob 10 0>, /* D6 */
753 <13 0 &gpioa 8 0>, /* D7 */
754 <14 0 &gpioa 9 0>, /* D8 */
755 <15 0 &gpioc 7 0>, /* D9 */
756 <16 0 &gpiob 6 0>, /* D10 */
757 <17 0 &gpioa 7 0>, /* D11 */
758 <18 0 &gpioa 6 0>, /* D12 */
759 <19 0 &gpioa 5 0>, /* D13 */
760 <20 0 &gpiob 9 0>, /* D14 */
761 <21 0 &gpiob 8 0>; /* D15 */
762 };
763
764This specifies how Arduino pin references like ``<&arduino_header 11
7650>`` are converted to SOC gpio pin references like ``<&gpiob 4 0>``.
766
767In Zephyr GPIO specifiers generally have two parameters (indicated by
768``#gpio-cells = <2>``): the pin number and a set of flags. The low 6
769bits of the flags correspond to features that can be configured in
770devicetree. In some cases it's necessary to use a non-zero flag value
771to tell the driver how a particular pin behaves, as with:
772
773.. code-block:: none
774
775 drdy-gpios = <&arduino_header 11 GPIO_ACTIVE_LOW>;
776
777After preprocessing this becomes ``<&arduino_header 11 1>``. Normally
778the presence of such a flag would cause the map lookup to fail,
779because there is no map entry with a non-zero flags value. The
780``gpio-map-mask`` property specifies that, for lookup, all bits of the
781pin and all but the low 6 bits of the flags are used to identify the
782specifier. Then the ``gpio-map-pass-thru`` specifies that the low 6
783bits of the flags are copied over, so the SOC GPIO reference becomes
784``<&gpiob 4 1>`` as intended.
785
786See `nexus node`_ for more information about this capability.
787
Anas Nashif03eada32019-02-01 10:09:13 -0500788.. include:: flash_partitions.inc