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 bindings (YAML files)

Devicetree bindings define the compatible property. It declares requirements on the contents of devicetree nodes, and provides semantic information about the contents of valid nodes. Zephyr’s devicetree bindings are defined as YAML files. Every devicetree node must have a compatible property. A devicetree node is matched using the compatible property with its definition in the devicetree binding.

Below is an example of a devicetree binding file (.yaml) that defines the compatible property named nordic,nrf-sample with one required property named num-sample of type integer.

compatible: "nordic,nrf-sample"
properties:
  num-sample:
    type: int
    required: true

Below is a sample DTS file (.dts) with the node node0 that is set to the compatible nordic,nrf-sample. This means the node0 node must have the required property num-sample and that property must be assigned an integer value. Otherwise, the build will fail.

node0 {
     compatible = "nordic,nrf-sample";
     num-sample = <3>;
};

The devicetree bindings are shipped with the SDK in <install_path>\zephyr\dts\bindings . The devicetree bindings for Nordic Semiconductor devices are listed here as well.

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.

/ {
        aliases {
                subnode_alias = &subnode_label;
        };
};

The code snippet above assigns the node a-sub-node, referenced by its label subnode_label to the alias subnode_alias. The purpose here is that your C/C++ application code (Ex: main.c) will use the alias. The definition of fixed aliases (Ex: led0 for the first LED on a board ) in boards’ dts files can make the application code more portable, as it can avoid hard-coding varying device node names and make the application code more flexible to changes in the board used.

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 understand these concepts better. 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.

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

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

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. This might sound redundant; however, it is here to make sure that all boards with LEDs nodes will have a constant alias for their LEDs(Ex: led0 for the first LED) so that the application code (Ex: main.c )will compile on different boards, without the need for you to manually inspect the DTS files and figure out the node label used for the LEDs on different boards.

If we take a look at some of the other peripheral nodes, you will notice various pinctrl properties (defined in <install_path>\zephyr\dts\bindings\pinctrl\pinctrl-device.yaml). For example, &uart0, the node describing the UART0 peripheral has the properties pinctrl-0, pinctrl-1 and pinctrl-names.

This is based on Zephyr’s pin control and assigns specific pin configurations to the devicetree nodes through the &pinctrl node that is defined in the pin control devicetree file.

Pin control devicetree file

The devicetree file relies on the pin control devicetree file for the pin mappings of the various nodes (except for LEDs and buttons). As seen in the image above, the &uart0 node has references to the nodes &uart0_default and &uart0_sleep, which are defined in this file. The pin control devicetree file is found in <install_path>\zephyr\boards\arm\nrf52833dk_nrf52833\nrf52833dk_nrf52833-pinctrl.dtsi.

1. The &pinctrl node (defined in <install_path>\zephyr\dts\bindings\pinctrl\nordic,nrf-pinctrl.yaml) includes all device pin configurations in its sub-nodes.
2. The node uart0_default encodes the pin configurations for the default state of the UART0 peripheral. The pin control API lets you assign different pins to the peripherals based on states; the two standard states are default and sleep.
3. Pin configurations are organized in groups within each sub-node, where each group specifies a list of pin function selections in the psels property. The group1 node is one of these groups, specifying the pin configurations for UART_TX and UART_RTS.
4. A group can also specify shared pin properties common to all specified pins. The group2 node is specifying the pin configurations for UART_RX and UART_CTS, and setting the bias-pull-up property for both of them.

SoC variant devicetree file

Now, examine the SoC variant devicetree nrf52833_qiaa.dtsi available in the directory <install_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 <install_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 here.