nRF Connect SDK Fundamentals – [Lesson 2] – Devicetree – v1.9.1-v1.6.0

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 Devicetree documentation.

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.

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.

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.

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.

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.

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.

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.