Getting Started With Zephyr: DTS vs DTSI vs Overlays

• RTOS
• Software Development
• C Programming

• "Why do I have to fiddle with a Devicetree and not just write code?"
• "What are the different Devicetree files and where are they located?"
• "When do I create a Deviceteree and when should I use an overlay?"

I like to keep the following picture in mind when thinking about Devicetrees in Zephyr with an NXP FRDM MCXN947 development board as reference (https://www.nxp.com/part/FRDM-MCXN947):

Devicetrees: The Bridge Between Hardware and Software

The picture above illustrates the brilliance of a Devicetree and how it mirrors the underlying hardware. If we imagine a board, from both a hardware and an embedded software point of view, we can make the following statements:

• A board consists of :
  • An SoC
  • Peripherals "external" to the SoC, but "internal" to the board
  • A pin definition for the SoC that are specific to the board 
• The SoC consists of:
  • N CPUs (N >= 1)
  • Peripherals that are "external" to the CPU, but "internal" to the SoC
• As embedded softawre application developers, we can also:
  
  • Modify the pins of our board, depending on our application

If we didn't have Devicetrees, we would need to write source code for each permutation of SoC and board combination, and then potentially write more code if we wanted to make changes depending on our application. Granted, some vendors have developed the infrastructure with the source code that corresponds to the boards, and they have GUIs that allow you to make pin changes for your application.

The challenge is that we must design our embedded software to decouple the underlying hardware from our business logic preemptively. This can be difficult. Some vendor GUIs place a significant portion of the hardware configuration source code in "main.c", and we must actively separate it into a separate file. 

Devicetrees, on the other hand, force you to abstract away the underlying hardware in your source code. For example, coupled with Zephyr's layered architecture, your source code only knows that at most there is a set of GPIOs that should be present in the Devicetree that perform some action.

In my opinion, the most significant advantage of Zephyr and Devicetrees is that it's easy to switch across hardware. We can keep the source code and corresponding business logic the same and only need to change which board we are targeting.

Devicetrees: Layering Hardware

Zephyr's Devicetree organization can be daunting, but once you understand that it mirrors the underlying hardware, it becomes easier to navigate. In the picture above, our top-level board is represented by the "frdm_mcxn947_mcxn947_cpu0.dts" file (a file ending with the .dts extension is always the "top-level" board Devicetree"). This file is located under boards/nxp/frdm_mcxn947 directory in the Zephyr v4.1.0 repository.

The structure of the filename itself also mirrors the overall hardware. "frdm_mcxn947" represents the board and "mcxn947" corresponds to the SoC and "cpu0" corresponds to one of the CPUs inside the SoC. 

If we open this file, we can see that it's bare, which is usually the case for top-level Devicetree files:

/*
 * Copyright 2024 NXP
 *
 * SPDX-License-Identifier: Apache-2.0
 */

/dts-v1/;

#include "frdm_mcxn947_mcxn947_cpu0.dtsi"

/ {
        model = "NXP FRDM_N94 board";
        compatible = "nxp,mcxn947", "nxp,mcx";
}

We can see that this file only references the "frdm_mcxn947_mcxn947_cpu0.dtsi" file, which is referred to as an "inclusion" file and is located in the same directory. This file performs the following:

• It references the "generic" board Devicetree inclusion file, not specific to CPU0.
• It removes references to CPU1, since it's not relevant to CPU0.
• It ties the underlying hardware to common Zephyr interfaces.
• It enables peripherals that are disabled by default.

We can also see that this file also references "nxp/nxp_mcxn94x.dtsi" file, which is the inclusion file corresponding to the SoC. This file is located under dts/arm/nxp/. This fiile also follows the same general design of the board Devicetree file. It references inclusion files that correspond to commonalities shared across similar SoCs, which are outlined in the "nxp_mcxn94x_common.dtsi" which is also in the same directory. This inclusion file eventually references the "armv8-m.dtsi" file, which is the core that the SoC uses.

Thus, the organization of the Devicetree files corresponds very closely to the hardware design.

Devicetree vs Overlay?

One of the common questions I encounter when using Zephyr is whether to create a Devicetree or to use an overlay. I typically ask myself the following questions when deciding to choose which route to use:

• How much does the custom PCB deviate from a similar development board that Zephyr supports? If there is a significant deviation, I usually create a separate board with its own Devicetree. If not, I use the existing board Devicetree and make an overlay.
• How often will I need to support the board for future applications? If it's for a one-off project that will likely have no use in the near future, I will most likely use an overlay. If the client wants to use this board for future projects and applications, I will create a new board. 

Conclusion

I attempted to alleviate some fears and frustrations associated with using Devicetrees in Zephyr in this blog post. I will also be hosting a bootcamp at the inaugural Embedded Systems Summit on October 14. We will delve into more detail about Devicetrees and Overlays using real hardware at the boot camp. I encourage you to sign up if you'd like to learn more: https://www.embeddedsummit.com/register.php

Sign in