You are currently not logged in and your progress will not be saved. Register or Log in

Devicetree

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:

/dts-v1/;
/ {
        a-node {
                subnode_label: a-sub-node {
                        foo = <3>;
                };
        };
};

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 (LED1 – LED4 ) 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. 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.

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.