Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 1 | .. _device-tree: |
| 2 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 3 | Devicetree |
| 4 | ########## |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 5 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 6 | Zephyr uses the *devicetree* data structure to describe the hardware available |
| 7 | on a board, as well as its initial configuration in an application. Note that |
Josh Gao | 88ac292 | 2019-12-12 23:01:12 -0800 | [diff] [blame^] | 8 | "devicetree" -- without spaces -- is preferred to "device tree". The |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 9 | `Devicetree specification`_ fully defines this data structure and its source |
| 10 | and binary representations. |
| 11 | |
| 12 | .. _device-tree-intro: |
Anas Nashif | 03eada3 | 2019-02-01 10:09:13 -0500 | [diff] [blame] | 13 | |
Anas Nashif | 276c589 | 2019-01-05 10:23:34 -0500 | [diff] [blame] | 14 | Introduction |
| 15 | ************ |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 16 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 17 | .. _Devicetree specification: https://www.devicetree.org/ |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 18 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 19 | This figure shows how devicetree fits into the Zephyr build system: |
Erwan Gouriou | 8223cfb | 2019-02-19 09:38:49 +0100 | [diff] [blame] | 20 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 21 | .. figure:: zephyr_dt_build_flow.png |
| 22 | :figclass: align-center |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 23 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 24 | Devicetree build flow |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 25 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 26 | Zephyr's build system can use a devicetree to generate C language code. This |
| 27 | code generation uses rules in additional files called :ref:`devicetree bindings |
| 28 | <bindings>` to control how devicetree data is converted to C definitions. The |
| 29 | generated code can be included by Zephyr :ref:`device drivers <device_drivers>` |
| 30 | and other C sources. The C macros generated by this process all begin with |
| 31 | ``DT_``. |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 32 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 33 | This differs significantly from how devicetree is used on Linux. The |
| 34 | Linux kernel would instead read the entire devicetree data structure in its |
| 35 | binary form, parsing it at runtime in order to load and initialize device |
| 36 | drivers. Zephyr does not work this way because the size of the devicetree |
| 37 | binary and associated handling code would be too large to fit comfortably on |
| 38 | the relatively constrained devices Zephyr supports. |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 39 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 40 | As the name indicates, a devicetree is a tree. The human-readable text format |
| 41 | for this tree is called DTS (for devicetree source), and is defined in the |
| 42 | Devicetree Specification. Here is an example DTS file: |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 43 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 44 | .. code-block:: none |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 45 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 46 | /dts-v1/; |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 47 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 48 | / { |
| 49 | a-node { |
| 50 | subnode_label: a-sub-node { |
| 51 | foo = <3>; |
| 52 | }; |
| 53 | }; |
| 54 | }; |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 55 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 56 | This example has three nodes: |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 57 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 58 | #. 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 Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 61 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 62 | Nodes can be given *labels*, which are unique shorthands that can be used to |
| 63 | refer to the labeled node elsewhere in the devicetree. Above, ``a-sub-node`` |
| 64 | has label ``subnode_label``. |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 65 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 66 | Devicetree nodes have *paths* identifying their locations in the tree. Like |
| 67 | Unix file system paths, devicetree paths are strings separated by slashes |
| 68 | (``/``), and the root node's path is a single slash: ``/``. Otherwise, each |
| 69 | node's path is formed by concatenating the node's ancestors' names with the |
| 70 | node's own name, separated by slashes. For example, the full path to |
| 71 | ``a-sub-node`` is ``/a-node/a-sub-node``. |
| 72 | |
| 73 | Devicetree nodes can also have *properties*. Properties are name/value |
| 74 | pairs. The values are simple byte arrays. Node ``a-sub-node`` has a property |
| 75 | named ``foo``, whose value is a 32-bit big-endian unsigned integer with value |
| 76 | 3. The size and type of ``foo``\ 's value are implied by the enclosing angle |
| 77 | brackets (``<`` and ``>``) in the DTS. Refer to the Devicetree Specification |
| 78 | for a complete list of ways to write a property value in a DTS file. |
| 79 | |
| 80 | In practice, devicetree nodes correspond to some hardware, and the node |
| 81 | hierarchy reflects the hardware's physical layout. For example, let's consider |
| 82 | a board with three I2C peripherals connected to an I2C bus master on an SoC, |
| 83 | like 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 | |
| 89 | Nodes corresponding to the I2C bus master and each I2C peripheral would be |
| 90 | present in this board's devicetree. Reflecting the hardware layout, the |
| 91 | devicetree's peripheral nodes would be children of the bus master node. Similar |
| 92 | conventions exist for representing other types of hardware in devicetree. |
| 93 | |
| 94 | The 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 | |
| 111 | Properties are used in practice to describe or configure the hardware the node |
| 112 | represents. For example, an I2C peripheral's node has a property whose value is |
| 113 | the peripheral's address on the bus. |
| 114 | |
| 115 | Here's a tree representing the same example, but with real-world node |
| 116 | names 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 | |
| 123 | Above, node names -- like ``i2c@40003000`` -- are at the top of each node, with |
| 124 | a 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 | |
| 127 | Some 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 | |
| 149 | This 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 | |
| 179 | Input and output files |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 180 | ********************** |
| 181 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 182 | The first figure in the :ref:`device-tree-intro` shows how devicetree fits into |
| 183 | the Zephyr build system. This section describes the input and output files in |
| 184 | more detail. |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 185 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 186 | .. figure:: zephyr_dt_inputs_outputs.png |
| 187 | :figclass: align-center |
Erwan Gouriou | 8223cfb | 2019-02-19 09:38:49 +0100 | [diff] [blame] | 188 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 189 | Devicetree input (green) and output (yellow) files |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 190 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 191 | DTS files usually have ``.dts`` or ``.dtsi`` (for Devicetree Source Include) |
| 192 | extensions. Zephyr's build system looks for a file named :file:`BOARD.dts` in |
| 193 | the board definition directory; this file contains the board's base |
| 194 | devicetree. See :ref:`dt_k6x_example` for real-world examples. |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 195 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 196 | The 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 |
| 198 | in the DTS format, but have a :file:`.overlay` extension to make it clear that |
| 199 | they're overlays. You can specify the overlay files to use at build time using |
| 200 | the :makevar:`DTC_OVERLAY_FILE` CMake variable described in |
| 201 | :ref:`important-build-vars`. The build system also looks for devicetree |
| 202 | overlays in several locations by default; see :ref:`application_dt` for the |
| 203 | list. |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 204 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 205 | Overlays can be used to add or delete nodes from the tree, or to modify node |
| 206 | properties and their values. Along with Kconfig, devicetree overlays let you |
| 207 | reconfigure the kernel and device drivers without modifying their source code. |
| 208 | |
| 209 | Before they are combined, the C preprocessor is run on :file:`BOARD.dts` and any |
| 210 | overlays. This allows these files to use C macros and include directives. |
| 211 | |
| 212 | The combined devicetree is written to a DTS file named |
| 213 | :file:`BOARD.dts_compiled` in the application build directory. This file |
| 214 | contains the final devicetree. |
| 215 | |
| 216 | This devicetree and the set of :ref:`bindings` are then used to generate C |
| 217 | definitions using scripts in :zephyr_file:`scripts/dts/`. These definitions can |
| 218 | be included via the ``generated_dts_board.h`` header file, which the build |
| 219 | system places on the C preprocessor include path. This file is not generated; |
| 220 | it is in :zephyr_file:`include/generated_dts_board.h`. (Its name was chosen |
| 221 | for backwards compatibility.) |
| 222 | |
| 223 | **Do not include the generated C headers in the build directory directly**. Use |
| 224 | ``generated_dts_board.h`` instead. |
| 225 | |
| 226 | Zephyr device drivers typically use information from ``generated_dts_board.h`` |
| 227 | to statically allocate and initialize :ref:`struct device <device_struct>` |
| 228 | instances. Property values from ``generated_dts_board.h`` are usually stored in |
| 229 | ROM in the value pointed to by a ``device->config->config_info`` field. For |
| 230 | example, a ``struct device`` corresponding to an I2C peripheral would store the |
| 231 | peripheral address in its ``reg`` property there. |
| 232 | |
| 233 | Application source code with a pointer to the ``struct device`` can then pass |
| 234 | it to driver APIs in :zephyr_file:`include/drivers/`. These API functions |
| 235 | usually take a ``struct device*`` as their first argument. This allows the |
| 236 | driver API to use information from devicetree to interact with the device |
| 237 | hardware. |
| 238 | |
| 239 | Temporary "fixup" files are currently required for devicetree support on most |
| 240 | devices. These fixup files by default reside in the board and soc directories |
| 241 | and are named ``dts_fixup.h``. These fixup files map the generated include |
| 242 | information to the current driver/source usage. They exist for historical |
| 243 | reasons; Zephyr is moving away from needing or using these files. |
Ulf Magnusson | 850e362 | 2019-07-26 15:53:58 +0200 | [diff] [blame] | 244 | |
Marti Bolivar | 9935fdd | 2019-10-07 11:04:55 -0700 | [diff] [blame] | 245 | .. _dt_k6x_example: |
| 246 | |
| 247 | Example: 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 | |
| 253 | The 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>` |
| 256 | respectively. Both boards have NXP SoCs from the same Kinetis SoC family, the |
| 257 | K6X. |
| 258 | |
| 259 | Common 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` |
| 261 | files. :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 |
| 263 | for Arm v7-M cores. |
| 264 | |
| 265 | Since :zephyr_file:`nxp_k6x.dtsi<dts/arm/nxp/nxp_k6x.dtsi>` is meant to be |
| 266 | generic across K6X-based boards, it leaves many devices disabled by default |
| 267 | using ``status`` properties. For example, there is a CAN controller defined as |
| 268 | follows (with unimportant parts skipped): |
| 269 | |
| 270 | .. code-block:: none |
| 271 | |
| 272 | can0: can@40024000 { |
| 273 | ... |
| 274 | status = "disabled"; |
| 275 | ... |
| 276 | }; |
| 277 | |
| 278 | It is up to the board :file:`.dts` or application overlay files to enable these |
| 279 | devices as desired, by setting ``status = "okay"``. The board :file:`.dts` |
| 280 | files are also responsible for any board-specific configuration of the device, |
| 281 | such as adding nodes for on-board sensors, LEDs, buttons, etc. |
| 282 | |
| 283 | For example, FRDM-K64 (but not Hexiwear K64) :file:`.dts` enables the CAN |
| 284 | controller and sets the bus speed: |
| 285 | |
| 286 | .. code-block:: none |
| 287 | |
| 288 | &can0 { |
| 289 | status = "okay"; |
| 290 | bus-speed = <125000>; |
| 291 | }; |
| 292 | |
| 293 | The ``&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 | |
| 296 | Other examples of board-specific customization is pointing properties in |
| 297 | ``aliases`` and ``chosen`` to the right nodes (see :ref:`dt-alias-chosen`), and |
| 298 | making GPIO/pinmux assignments. |
| 299 | |
Carles Cufi | 4574505 | 2018-06-21 12:08:32 +0200 | [diff] [blame] | 300 | .. _dt_vs_kconfig: |
| 301 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 302 | Devicetree vs Kconfig |
| 303 | ********************* |
Carles Cufi | 4574505 | 2018-06-21 12:08:32 +0200 | [diff] [blame] | 304 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 305 | Along with devicetree, Zephyr also uses the Kconfig language to configure the |
| 306 | source code. Whether to use devicetree or Kconfig for a particular purpose can |
| 307 | sometimes be confusing. This section should help you decide which one to use. |
Carles Cufi | 4574505 | 2018-06-21 12:08:32 +0200 | [diff] [blame] | 308 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 309 | In short: |
Carles Cufi | 4574505 | 2018-06-21 12:08:32 +0200 | [diff] [blame] | 310 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 311 | * 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 Cufi | 4574505 | 2018-06-21 12:08:32 +0200 | [diff] [blame] | 317 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 318 | In other words, devicetree mainly deals with hardware, and Kconfig with |
| 319 | software. |
Carles Cufi | 4574505 | 2018-06-21 12:08:32 +0200 | [diff] [blame] | 320 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 321 | For example, consider a board containing a SoC with 2 UART, or serial port, |
| 322 | instances. |
Carles Cufi | 4574505 | 2018-06-21 12:08:32 +0200 | [diff] [blame] | 323 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 324 | * 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 Cufi | 4574505 | 2018-06-21 12:08:32 +0200 | [diff] [blame] | 336 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 337 | As another example, consider a device with a 2.4GHz, multi-protocol radio |
| 338 | supporting both the Bluetooth Low Energy and 802.15.4 wireless technologies. |
Carles Cufi | 4574505 | 2018-06-21 12:08:32 +0200 | [diff] [blame] | 339 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 340 | * 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 Cufi | 4574505 | 2018-06-21 12:08:32 +0200 | [diff] [blame] | 346 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 347 | There are two noteworthy **exceptions** to these rules: |
Carles Cufi | 4574505 | 2018-06-21 12:08:32 +0200 | [diff] [blame] | 348 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 349 | * 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. Kinder | 2670bd6 | 2017-06-19 10:13:50 -0700 | [diff] [blame] | 355 | |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 356 | Currently supported boards |
| 357 | ************************** |
| 358 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 359 | Devicetree is currently supported on all embedded targets except posix |
Daniel Leung | b7eb04b | 2019-10-24 12:57:57 -0700 | [diff] [blame] | 360 | (boards/posix). |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 361 | |
| 362 | Adding support for a board |
| 363 | ************************** |
| 364 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 365 | Adding devicetree support for a given board requires adding a number of files. |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 366 | These files will contain the DTS information that describes a platform, the |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 367 | bindings in YAML format, and any fixup files required to support the platform. |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 368 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 369 | It is best practice to separate common peripheral information that could be |
| 370 | used across multiple cores, SoC families, or boards in :file:`.dtsi` files, |
| 371 | reserving the :file:`.dts` suffix for the primary DTS file for a given board. |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 372 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 373 | Devicetree Source File Template |
| 374 | =============================== |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 375 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 376 | A board's :file:`.dts` file contains at least a version line, optional |
| 377 | includes, and a root node definition with ``model`` and ``compatible`` |
| 378 | properties. These property values denote the particular board. |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 379 | |
Ulf Magnusson | dd5ff39 | 2019-02-26 17:20:43 +0100 | [diff] [blame] | 380 | .. code-block:: none |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 381 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 382 | /dts-v1/; |
Ulf Magnusson | dd5ff39 | 2019-02-26 17:20:43 +0100 | [diff] [blame] | 383 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 384 | #include <vendor/soc.dtsi> |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 385 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 386 | / { |
| 387 | model = "Human readable board name"; |
| 388 | compatible = "vendor,soc-on-your-board's-mcu"; |
| 389 | /* rest of file */ |
| 390 | }; |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 391 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 392 | You can use other board :file:`.dts` files as a starting point. |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 393 | |
| 394 | The 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 Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 399 | 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 Gouriou | 8223cfb | 2019-02-19 09:38:49 +0100 | [diff] [blame] | 402 | * Add target specific YAML binding files in the dts/bindings/ directory. |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 403 | 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 Gouriou | 8223cfb | 2019-02-19 09:38:49 +0100 | [diff] [blame] | 411 | * Add SoC family YAML binding files that describe the nodes present in the .dtsi file. |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 412 | |
| 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 Puzdrowski | 77532ae | 2018-01-17 11:33:20 +0100 | [diff] [blame] | 418 | |
| 419 | * Flash device node might specify flash partitions. For more details see |
Xuan Ze | 8c94b53 | 2018-07-02 20:25:02 +0800 | [diff] [blame] | 420 | :ref:`flash_partitions` |
Andrzej Puzdrowski | 77532ae | 2018-01-17 11:33:20 +0100 | [diff] [blame] | 421 | |
Erwan Gouriou | 8223cfb | 2019-02-19 09:38:49 +0100 | [diff] [blame] | 422 | * Add board-specific YAML binding files, if required. This would occur if the |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 423 | 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 Cufi | 1cce63a | 2018-01-31 18:00:49 +0100 | [diff] [blame] | 432 | * Overlay Files (optional) |
| 433 | |
| 434 | * Overlay files contain tweaks or changes to the SoC and Board support files |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 435 | described above. They can be used to modify devicetree configurations |
Carles Cufi | 1cce63a | 2018-01-31 18:00:49 +0100 | [diff] [blame] | 436 | 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 Cufi | 6075133 | 2018-12-05 18:58:47 +0100 | [diff] [blame] | 440 | .. _dt-alias-chosen: |
| 441 | |
| 442 | ``aliases`` and ``chosen`` nodes |
| 443 | ================================ |
| 444 | |
| 445 | Using an alias with a common name for a particular node makes it easier for you |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 446 | to write board-independent source code. Devicetree ``aliases`` nodes are used |
Carles Cufi | 6075133 | 2018-12-05 18:58:47 +0100 | [diff] [blame] | 447 | for this purpose, by mapping certain generic, commonly used names to specific |
| 448 | hardware 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 | |
| 460 | Certain software subsystems require a specific hardware resource to bind to in |
| 461 | order to function properly. Some of those subsystems are used with many |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 462 | different boards, which makes using the devicetree ``chosen`` nodes very |
Carles Cufi | 6075133 | 2018-12-05 18:58:47 +0100 | [diff] [blame] | 463 | convenient. By doing, so the software subsystem can rely on having the specific |
| 464 | hardware peripheral assigned to it. In the following example we bind the shell |
| 465 | to ``uart1`` in this board: |
| 466 | |
| 467 | .. code-block:: yaml |
| 468 | |
| 469 | chosen { |
| 470 | zephyr,shell-uart = &uart1; |
| 471 | }; |
| 472 | |
| 473 | The 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 Magnusson | 4099b97 | 2019-02-26 15:34:44 +0100 | [diff] [blame] | 484 | - ``CONFIG_SRAM_SIZE``/``CONFIG_SRAM_BASE_ADDRESS`` |
| 485 | (via ``DT_SRAM_SIZE``/``DT_SRAM_BASE_ADDRESS``) |
Carles Cufi | 6075133 | 2018-12-05 18:58:47 +0100 | [diff] [blame] | 486 | * - ``zephyr,ccm`` |
Kumar Gala | bfaaa6b | 2019-02-08 08:09:47 -0600 | [diff] [blame] | 487 | - ``DT_CCM`` |
Carles Cufi | 6075133 | 2018-12-05 18:58:47 +0100 | [diff] [blame] | 488 | * - ``zephyr,console`` |
Erwan Gouriou | 8223cfb | 2019-02-19 09:38:49 +0100 | [diff] [blame] | 489 | - ``DT_UART_CONSOLE_ON_DEV_NAME`` |
Carles Cufi | 6075133 | 2018-12-05 18:58:47 +0100 | [diff] [blame] | 490 | * - ``zephyr,shell-uart`` |
Erwan Gouriou | 8223cfb | 2019-02-19 09:38:49 +0100 | [diff] [blame] | 491 | - ``DT_UART_SHELL_ON_DEV_NAME`` |
Carles Cufi | 6075133 | 2018-12-05 18:58:47 +0100 | [diff] [blame] | 492 | * - ``zephyr,bt-uart`` |
Erwan Gouriou | 8223cfb | 2019-02-19 09:38:49 +0100 | [diff] [blame] | 493 | - ``DT_BT_UART_ON_DEV_NAME`` |
Carles Cufi | 6075133 | 2018-12-05 18:58:47 +0100 | [diff] [blame] | 494 | * - ``zephyr,uart-pipe`` |
Erwan Gouriou | 8223cfb | 2019-02-19 09:38:49 +0100 | [diff] [blame] | 495 | - ``DT_UART_PIPE_ON_DEV_NAME`` |
Carles Cufi | 6075133 | 2018-12-05 18:58:47 +0100 | [diff] [blame] | 496 | * - ``zephyr,bt-mon-uart`` |
Erwan Gouriou | 8223cfb | 2019-02-19 09:38:49 +0100 | [diff] [blame] | 497 | - ``DT_BT_MONITOR_ON_DEV_NAME`` |
Carles Cufi | 6075133 | 2018-12-05 18:58:47 +0100 | [diff] [blame] | 498 | * - ``zephyr,uart-mcumgr`` |
Erwan Gouriou | 8223cfb | 2019-02-19 09:38:49 +0100 | [diff] [blame] | 499 | - ``DT_UART_MCUMGR_ON_DEV_NAME`` |
Carles Cufi | 6075133 | 2018-12-05 18:58:47 +0100 | [diff] [blame] | 500 | |
Erwan Gouriou | 8223cfb | 2019-02-19 09:38:49 +0100 | [diff] [blame] | 501 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 502 | Adding support for devicetree in drivers |
| 503 | **************************************** |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 504 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 505 | As drivers and other source code is converted over to make use of devicetree |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 506 | generated information, these drivers may require changes to match the generated |
| 507 | #define information. |
| 508 | |
| 509 | |
| 510 | Source Tree Hierarchy |
| 511 | ********************* |
| 512 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 513 | The devicetree files are located in a couple of different directories. The |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 514 | directory split is done based on architecture, and there is also a common |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 515 | directory where architecture agnostic devicetree and YAML binding files are |
Erwan Gouriou | 8223cfb | 2019-02-19 09:38:49 +0100 | [diff] [blame] | 516 | located. |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 517 | |
| 518 | Assuming the current working directory is the ZEPHYR_BASE, the directory |
| 519 | hierarchy looks like the following:: |
| 520 | |
| 521 | dts/common/ |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 522 | dts/<ARCH>/ |
Kumar Gala | 2b50be6 | 2017-12-01 11:33:17 -0600 | [diff] [blame] | 523 | dts/bindings/ |
| 524 | boards/<ARCH>/<BOARD>/ |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 525 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 526 | The common directory contains a ``skeleton.dtsi`` which provides devicetree root |
Erwan Gouriou | 8223cfb | 2019-02-19 09:38:49 +0100 | [diff] [blame] | 527 | node definition. The bindings subdirectory contains YAML binding files used |
| 528 | to instruct how the python DTS parsing script should extract nodes information |
| 529 | in a format that will be usable by the system. |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 530 | |
Kumar Gala | 2b50be6 | 2017-12-01 11:33:17 -0600 | [diff] [blame] | 531 | Example: Subset of DTS/YAML files for NXP FRDM K64F (Subject to Change):: |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 532 | |
| 533 | dts/arm/armv7-m.dtsi |
| 534 | dts/arm/k6x/nxp_k6x.dtsi |
Kumar Gala | 2b50be6 | 2017-12-01 11:33:17 -0600 | [diff] [blame] | 535 | 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 Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 540 | |
Ulf Magnusson | 850e362 | 2019-07-26 15:53:58 +0200 | [diff] [blame] | 541 | .. _bindings: |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 542 | |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 543 | Devicetree Bindings |
| 544 | ******************* |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 545 | |
Ulf Magnusson | 850e362 | 2019-07-26 15:53:58 +0200 | [diff] [blame] | 546 | ``.dts`` files describe the available hardware devices, but don't tell the |
| 547 | system which pieces of information are useful, or what kind of configuration |
| 548 | output (``#define``'s) should be generated. *Bindings* provide this |
| 549 | information. Bindings are files in YAML format. |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 550 | |
Ulf Magnusson | 850e362 | 2019-07-26 15:53:58 +0200 | [diff] [blame] | 551 | Configuration output is only generated for devices that have bindings. |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 552 | |
Ulf Magnusson | 850e362 | 2019-07-26 15:53:58 +0200 | [diff] [blame] | 553 | Nodes are mapped to bindings via their ``compatible`` string(s). Take |
| 554 | the following node as an example: |
Andy Gross | 252da09 | 2017-05-24 00:24:50 -0500 | [diff] [blame] | 555 | |
Ulf Magnusson | 850e362 | 2019-07-26 15:53:58 +0200 | [diff] [blame] | 556 | .. code-block:: none |
| 557 | |
| 558 | bar-device { |
| 559 | compatible = "foo-company,bar-device"; |
| 560 | ... |
| 561 | }; |
| 562 | |
| 563 | This node would get mapped to a binding with this in it: |
| 564 | |
| 565 | .. code-block:: yaml |
| 566 | |
Ulf Magnusson | a0fceff | 2019-08-19 20:32:25 +0200 | [diff] [blame] | 567 | compatible: "foo-company,bar-device" |
| 568 | |
| 569 | You might also run across this legacy syntax, which works the same way: |
| 570 | |
| 571 | .. code-block:: yaml |
| 572 | |
Ulf Magnusson | 850e362 | 2019-07-26 15:53:58 +0200 | [diff] [blame] | 573 | ... |
| 574 | |
| 575 | properties: |
| 576 | compatible: |
| 577 | constraint: "foo-company,bar-device" |
| 578 | |
| 579 | ... |
| 580 | |
| 581 | Bindings are stored in :zephyr_file:`dts/bindings/`. The filename usually |
| 582 | matches the ``compatible`` string. |
| 583 | |
| 584 | If a node has more than one ``compatible`` string, then the first binding found |
| 585 | is 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 |
| 587 | mapped to the binding for ``generic-bar-device`` if there is no binding for |
| 588 | ``foo-company,bar-device``. |
| 589 | |
| 590 | If a node appears on a bus (e.g. I2C or SPI), then the bus type is also taken |
| 591 | into account when mapping nodes to bindings. See the description of ``parent`` |
| 592 | and ``child`` in the template below. |
| 593 | |
| 594 | Below is a template that shows the format of binding files, stored in |
Kumar Gala | c24a791 | 2019-08-15 11:59:40 -0500 | [diff] [blame] | 595 | :zephyr_file:`dts/binding-template.yaml`. |
Ulf Magnusson | 850e362 | 2019-07-26 15:53:58 +0200 | [diff] [blame] | 596 | |
Kumar Gala | c24a791 | 2019-08-15 11:59:40 -0500 | [diff] [blame] | 597 | .. literalinclude:: ../../../dts/binding-template.yaml |
Ulf Magnusson | 850e362 | 2019-07-26 15:53:58 +0200 | [diff] [blame] | 598 | :language: yaml |
Anas Nashif | 03eada3 | 2019-02-01 10:09:13 -0500 | [diff] [blame] | 599 | |
Ulf Magnusson | 5bc06e8 | 2019-09-16 19:04:41 +0200 | [diff] [blame] | 600 | .. _legacy_binding_syntax: |
| 601 | |
| 602 | Legacy binding syntax |
| 603 | ===================== |
| 604 | |
| 605 | Various parts of the binding syntax were simplified and generalized for the |
| 606 | Zephyr 2.1 release. |
| 607 | |
| 608 | The 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 Magnusson | a778868 | 2019-10-03 05:28:26 +0200 | [diff] [blame] | 636 | # Assume this is a binding for an interrupt controller |
| 637 | "#cells": |
| 638 | - irq |
| 639 | - priority |
| 640 | - flags |
| 641 | |
Ulf Magnusson | 5bc06e8 | 2019-09-16 19:04:41 +0200 | [diff] [blame] | 642 | This 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 Magnusson | 842e1d4 | 2019-10-03 00:37:06 +0200 | [diff] [blame] | 660 | child-binding: |
Ulf Magnusson | 5bc06e8 | 2019-09-16 19:04:41 +0200 | [diff] [blame] | 661 | title: ... |
| 662 | description: ... |
| 663 | |
| 664 | properties: |
| 665 | child-prop: |
| 666 | type: int |
| 667 | required: true |
| 668 | |
Ulf Magnusson | a778868 | 2019-10-03 05:28:26 +0200 | [diff] [blame] | 669 | interrupt-cells: |
| 670 | - irq |
| 671 | - priority |
| 672 | - cells |
| 673 | |
Ulf Magnusson | 5bc06e8 | 2019-09-16 19:04:41 +0200 | [diff] [blame] | 674 | The legacy syntax is still supported for backwards compatibility, but generates |
| 675 | deprecation warnings. Support will be dropped in the Zephyr 2.3 release. |
Anas Nashif | 03eada3 | 2019-02-01 10:09:13 -0500 | [diff] [blame] | 676 | |
Erwan Gouriou | 8223cfb | 2019-02-19 09:38:49 +0100 | [diff] [blame] | 677 | Include files generation |
| 678 | ************************ |
| 679 | |
| 680 | At build time, after a board's ``.dts`` file has been processed by the DTC |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 681 | (Devicetree Compiler), a corresponding ``.dts_compiled`` file is generated |
Erwan Gouriou | 8223cfb | 2019-02-19 09:38:49 +0100 | [diff] [blame] | 682 | under the ``zephyr`` directory. |
| 683 | This ``.dts_compiled`` file is processed by the python DTS parsing script |
| 684 | and generates an include file named |
| 685 | ``include/generated/generated_dts_board_unfixed.h`` |
| 686 | that holds all the information extracted from the DTS file with |
| 687 | the 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 Gala | a614a02 | 2019-06-22 10:51:09 -0500 | [diff] [blame] | 695 | #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 Gouriou | 8223cfb | 2019-02-19 09:38:49 +0100 | [diff] [blame] | 698 | #define DT_GPIO_KEYS_BUTTON_0_LABEL "User SW2" |
Kumar Gala | 284bc9d | 2019-06-22 10:57:14 -0500 | [diff] [blame] | 699 | |
| 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 Gouriou | 8223cfb | 2019-02-19 09:38:49 +0100 | [diff] [blame] | 708 | |
| 709 | Additionally, a file named ``generated_dts_board_fixups.h`` is |
| 710 | generated in the same directory concatenating all board-related fixup files. |
| 711 | |
| 712 | The include file ``include/generated_dts_board.h`` includes both these generated |
Marti Bolivar | 85fa523 | 2019-10-04 13:34:15 -0700 | [diff] [blame] | 713 | files, giving Zephyr C source files access to the board's devicetree information. |
Anas Nashif | 03eada3 | 2019-02-01 10:09:13 -0500 | [diff] [blame] | 714 | |
Peter Bigot | 4d97252 | 2019-10-17 16:47:44 -0500 | [diff] [blame] | 715 | GPIO Nexus Nodes |
| 716 | **************** |
| 717 | |
| 718 | Each board has a set of General Purpose Input/Output (GPIO) |
| 719 | peripherals that can be accessed through the :ref:`GPIO<gpio>` module. |
| 720 | Many boards provide headers that allow :ref:`shields<shields>` from |
| 721 | other vendors to be mounted on their boards. Each shield identifies |
| 722 | its hardware in a devicetree overlay. |
| 723 | |
| 724 | GPIOs accessed by the shield peripherals must be identified using the |
| 725 | shield GPIO abstraction, for example from the ``arduino-r3-header`` |
| 726 | compatible. Boards that provide the header must map the header pins |
| 727 | to SOC-specific pins. This is accomplished by including a `nexus |
| 728 | node`_ 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 | |
| 764 | This specifies how Arduino pin references like ``<&arduino_header 11 |
| 765 | 0>`` are converted to SOC gpio pin references like ``<&gpiob 4 0>``. |
| 766 | |
| 767 | In Zephyr GPIO specifiers generally have two parameters (indicated by |
| 768 | ``#gpio-cells = <2>``): the pin number and a set of flags. The low 6 |
| 769 | bits of the flags correspond to features that can be configured in |
| 770 | devicetree. In some cases it's necessary to use a non-zero flag value |
| 771 | to 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 | |
| 777 | After preprocessing this becomes ``<&arduino_header 11 1>``. Normally |
| 778 | the presence of such a flag would cause the map lookup to fail, |
| 779 | because 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 |
| 781 | pin and all but the low 6 bits of the flags are used to identify the |
| 782 | specifier. Then the ``gpio-map-pass-thru`` specifies that the low 6 |
| 783 | bits of the flags are copied over, so the SOC GPIO reference becomes |
| 784 | ``<&gpiob 4 1>`` as intended. |
| 785 | |
| 786 | See `nexus node`_ for more information about this capability. |
| 787 | |
Anas Nashif | 03eada3 | 2019-02-01 10:09:13 -0500 | [diff] [blame] | 788 | .. include:: flash_partitions.inc |