Devicetree

v2.x.x

In Embedded Systems firmware development, hardware is traditionally described inside header files (.h or .hh). nRF Connect SDK uses a more structured and modular method to describe hardware borrowed from the Zephyr RTOS, which is through a construct called a devicetree.

A devicetree is a hierarchical data structure that describes hardware. The hardware described could be a development kit, SoC, SiP, module, defining everything ranging from the GPIO configurations of the LEDs on a development kit to the memory-mapped locations of peripherals. The devicetree uses a specific format consisting of nodes connected together, where each node contains a set of properties.

The following section is derived from the Zephyr project website.

Devicetree basics

As the name indicates, a devicetree is a tree-like structure. The human-readable text format for this tree is called DTS (for devicetree source).

Here is an example DTS file:

The tree above has three nodes:

  1. A root node: /
  2. A node named a-node, which is a child of the root node
  3. A node named a-sub-node, which is a child of a-node

Nodes can be given labels, which are unique shorthands that can be used to refer to the labeled node elsewhere in the devicetree. Above, a-sub-node has the label subnode_label. A node can have no, one, or multiple node labels.

Devicetree nodes can also have properties. Properties are name/value pairs. Property values can be an array of strings, bytes, numbers, or any mixture of types.

The node a-sub-node has a property named foo, whose value is a cell with value 3. The size and type of foo‘s value are implied by the enclosing angle brackets (< and >) in the DTS. Properties might have an empty value if conveying true-false information. In this case, the presence or absence of the property is sufficiently descriptive.

Devicetree nodes have paths identifying their locations in the tree. Like Unix file system paths, devicetree paths are strings separated by slashes (/), and the root node’s path is a single slash: /. Otherwise, each node’s path is formed by concatenating the node’s ancestors’ names with the node’s own name, separated by slashes. For example, the full path to a-sub-node is /a-node/a-sub-node.

Aliases

It is common to add aliases to the devicetree. The /aliases node contains properties that are aliases, where the name of the property is the name of that alias and the value of the property is a reference to a node in the device tree, see below.

The code snippet above assigns the node a-sub-node, referenced by its label subnode_label to the alias subnode_alias.

Accessing the devicetree

To get information about a particular devicetree node in your source code, you need a node identifier for it. This is just a C macro that refers to the node. There are many ways to get a node identifier.

The two common ones are by the node label through the macro DT_NODELABEL() and by an alias through the macro DT_ALIAS().

For example, to get the node identifier of a-sub-node:

DT_NODELABEL(subnode-label)

To get the value assigned to a certain devicetree property, we can use the macro DT_PROP(). For example, to get the value assigned to the foo property:

DT_PROP(DT_NODELABEL(subnode-label), foo)

Devicetree example

Let’s take an actual example to better understand these concepts. The nRF52833 DK has four user-configurable LEDs (LED1 – LED4) connected to GPIO pins P0.13 – P0.16 as shown in the screenshots below obtained from the schematics (Available in Downloads -> Hardware Files on a development kit page )of the nRF52833 DK.

nRF52833 DK LED location
nRF52833 DK LED pin mapping

DK devicetree file

These hardware details are all described in the devicetree file for the nRF52833 DK. Let’s examine this file, available in <install_path>\zephyr\boards\arm\nrf52833dk_nrf52833\nrf52833dk_nrf52833.dts.

nRF52833 DK devicetree
  1. The devicetree file for the DK includes the devicetree for the specific SoC variant used in the development kit. In the case of the nRF52833 DK, it is the file nrf52833_qiaa.dtsi available in the directory <install_path>\zephyr\dts\arm\nordic. This file is used because this corresponds to the package variant and function variant of the SoC used on the nRF52833 DK. The I in DTSI stands for Include. dtsi files generally contain SoC-level definitions. It also includes the pin mapping, defined in nrf52833dk_nrf52833-pinctrl.dtsi
  2. LED1 on the nRF52833 DK has the node name led_0 and the node label led0. The node label is commonly used to refer to the node, like this &led0.
  3. The led_0 has two properties: gpios and label.
  4. You can see that the property gpios is referencing the node gpio0 through the & symbol. gpio0 is defined in the SoC devicetree, as we will see in the following paragraph. The GPIO pin where LED1 on the kit is connected to the nRF52833 SoC is defined with GPIO 0 as pin 13 (P0.13) and active low.

Important

A node usually has a node label, but it can also have a property with the name label. For instance, the node led_0 has the node label led0 and a property label with the value “Green LED 0“.

The alias node is also defined in the DK devicetree file, see the image below.

nRF52833 DK devicetree
/aliases node

We can see from the /aliases node in the DK devicetree, that node led_0, referenced by its node label as &led0, is given the alias led0.

SoC variant devicetree file

Now, examine the SoC variant devicetree nrf52833_qiaa.dtsi available in the directory install_path>\zephyr\dts\arm\nordic.

nRF52833 QIAA SoC variant devicetree
  1. The SoC variant devicetree includes the base SoC devicetree nrf52833.dtsi, which is available in the same directory.
  2. It contains information related to the SoC variant (version) such as the RAM and flash base addresses and sizes.

Base SoC devicetree file

The SoC devicetree contains SoC-level hardware descriptions for all the peripherals and system blocks. Examine the base SoC devicetree nrf52833.dtsi available in the directory <nRF Connect SDK Installation Path>\zephyr\dts\arm\nordic.

nRF52833 SoC devicetree
  1. The gpio0 node is defined here.
  2. The node specifies which hardware it represents via the compatible property. This is used by the driver to select which nodes it supports.
  3. It also defines the address space for the node.

This should give you a basic overview of how hardware is described and presented using the devicetree. To get more information about the devicetree, you can download the devicetree specification here.

v1.6.0 – v1.9.1

In Embedded Systems firmware development, hardware is traditionally described inside header files (.h or .hh). nRF Connect SDK uses a more structured and modular method to describe hardware borrowed from the Zephyr RTOS, which is through a construct called a devicetree.

A devicetree is a hierarchical data structure that describes hardware. The hardware described could be a development kit, SoC, SiP, module, defining everything ranging from the GPIO configurations of the LEDs on a development kit to the memory-mapped locations of peripherals. The devicetree uses a specific format consisting of nodes connected together, where each node contains a set of properties.

The following section is derived from the Zephyr project website.

Devicetree basics

As the name indicates, a devicetree is a tree-like structure. The human-readable text format for this tree is called DTS (for devicetree source).

Here is an example DTS file:

The tree above has three nodes:

  1. A root node: /
  2. A node named a-node, which is a child of the root node
  3. A node named a-sub-node, which is a child of a-node

Nodes can be given labels, which are unique shorthands that can be used to refer to the labeled node elsewhere in the devicetree. Above, a-sub-node has the label subnode_label. A node can have no, one, or multiple node labels.

Devicetree nodes can also have properties. Properties are name/value pairs. Property values can be an array of strings, bytes, numbers, or any mixture of types.

The node a-sub-node has a property named foo, whose value is a cell with value 3. The size and type of foo‘s value are implied by the enclosing angle brackets (< and >) in the DTS. Properties might have an empty value if conveying true-false information. In this case, the presence or absence of the property is sufficiently descriptive.

Devicetree nodes have paths identifying their locations in the tree. Like Unix file system paths, devicetree paths are strings separated by slashes (/), and the root node’s path is a single slash: /. Otherwise, each node’s path is formed by concatenating the node’s ancestors’ names with the node’s own name, separated by slashes. For example, the full path to a-sub-node is /a-node/a-sub-node.

Devicetree example

Let’s take an actual example to better understand these concepts. The nRF52833 DK has four user-configurable LEDs (LED1LED4) connected to GPIO pins P0.13 – P0.16 as shown in the screenshots below obtained from the schematics of the nRF52833 DK.

nRF52833 DK LED location
nRF52833 DK LED pin mapping

DK devicetree file

These hardware details are all described in the devicetree file for the nRF52833 DK. Let’s examine this file, available in <install_path>\zephyr\boards\arm\nrf52833dk_nrf52833\nrf52833dk_nrf52833.dts.

nRF52833 DK devicetree
  1. The first thing to notice is that it includes the devicetree for the specific SoC variant used in the development kit. In the case of the nRF52833 DK, it is the file nrf52833_qiaa.dtsi available in the directory <nRF Connect SDK Installation Path>\zephyr\dts\arm\nordic. This file is used because this corresponds to the package variant and function variant of the SoC used on the nRF52833 DK. The I in DTSI stands for Include. dtsi files generally contain SoC-level definitions.
  2. LED0 on the nRF52833 DK has the node name led_0 and the node label led0. The node label is commonly used to refer to the node, like this &led0.
  3. The led_0 has two properties: gpios and label.
  4. You can see that the property gpios is referencing the node gpio0 through the & symbol. gpio0 is defined in the SoC devicetree, as we will see in the following paragraph. The GPIO pin, where LED1 on the kit is connected to the nRF52833 SoC, is defined with GPIO 0 as pin 13 (P0.13) and active low.

Note

A node usually has a node label, but it can also have a property with the name label, see 3 in the image above. These are not the same thing.

Aliases

It is common to add aliases to the devicetree. An alias is a property of the aliases node. These are usually added in the devicetree file of the DK. Aliases are added as a way to ensure compatibility across different hardware with all samples.

nRF52833 DK devicetree

The node led_0, referenced here with its node label, as &led0, is given the alias led0.

SoC variant devicetree file

Now, examine the SoC variant devicetree nrf52833_qiaa.dtsi available in the directory <nRF Connect SDK Installation Path>\zephyr\dts\arm\nordic.

nRF52833 QIAA SoC variant devicetree
  1. The SoC variant devicetree includes the base SoC devicetree nrf52833.dtsi, which is available in the same directory.
  2. It contains information related to the SoC variant (version) such as the RAM and flash base addresses and sizes.

Base SoC devicetree file

The SoC devicetree contains SoC-level hardware descriptions for all the peripherals and system blocks. Examine the base SoC devicetree nrf52833.dtsi available in the directory <nRF Connect SDK Installation Path>\zephyr\dts\arm\nordic.

nRF52833 SoC devicetree
  1. The gpio0 node is defined here.
  2. The node specifies which hardware it represents via the compatible property. This is used by the driver to select which nodes it supports.
  3. It also defines the address space for the node.

This should give you a basic overview of how hardware is described and presented using the devicetree. To get more information about the devicetree, you can download the devicetree specification from here.

Register an account
Already have an account? Log in
(All fields are required unless specified optional)

Forgot your password?
Enter your email address, and we will send a link to reset your password.