What You Will Learn

• What a device tree is for and why the kernel can’t hardcode hardware layout instead
• How the dtbs build target finds and compiles device tree source files
• The relationship between .dts, .dtsi, and the compiled .dtb
• How to build device trees for your board and verify the result
• Common device tree build and boot failures, and how to debug them

Prerequisites

• A kernel source tree already configured for your target ARCH (see our kbuild lecture)
• Basic familiarity with how kbuild locates architecture-specific files under arch/$ARCH/
• The device-tree-compiler package installed, or the in-tree dtc that kbuild builds automatically

Why Device Trees Exist

Early embedded ARM support in Linux hardcoded board details directly into C files — one file per board, describing every peripheral address, IRQ number, and GPIO wiring in code. That approach didn’t scale once ARM SoC vendors started shipping dozens of board variants a year. The device tree moved that description out of code and into data: a plain-text source format (.dts) that describes the hardware as a tree of nodes and properties, compiled into a compact binary (.dtb) that the bootloader passes to the kernel at boot time. The same kernel binary can then run on many boards, picking its hardware configuration from whichever .dtb was loaded rather than from board-specific code paths.

A minimal, original example — a fictional board node describing one UART and one LED, written the way you’d find it in a real .dts file:

/dts-v1/;
/ {
    model = "EP Devboard Rev A";
    compatible = "ep,devboard";

    soc {
        uart0: serial@4a000000 {
            compatible = "ep,ep-uart";
            reg = <0x4a000000 0x1000>;
            interrupts = <38>;
            status = "okay";
        };
    };

    leds {
        compatible = "gpio-leds";
        status_led {
            gpios = <&gpio1 5 0>;
            label = "ep:status";
        };
    };
};

None of this needs to change if you swap the SoC’s silicon revision — only the device tree does, and the kernel driver for ep,ep-uart is matched purely through the compatible string.

The dtbs Build Target

Kbuild treats device tree compilation as its own target, separate from the kernel image itself. Running it looks like this:

$ make ARCH=arm64 dtbs

This walks the rules defined in arch/$ARCH/boot/dts/Makefile, which lists which .dts files belong to that architecture (often grouped by vendor subdirectory — arch/arm64/boot/dts/<vendor>/). Each listed source file is run through the device tree compiler, dtc, producing one .dtb per board in the same directory as its source:

$ make ARCH=arm64 dtbs
  DTC     arch/arm64/boot/dts/ep/ep-devboard-a.dtb
  DTC     arch/arm64/boot/dts/ep/ep-devboard-b.dtb
  DTC     arch/arm64/boot/dts/ep/ep-devboard-c.dtb

You can also target a single board directly, which is faster during iterative development than rebuilding every .dtb in the tree:

$ make ARCH=arm64 arch/arm64/boot/dts/ep/ep-devboard-a.dtb

dts, dtsi, And dtb: What Each File Actually Is

A typical SoC vendor’s .dtsi describes everything common to that chip family — CPU cores, memory controller, standard peripheral blocks — and each board’s .dts includes it, then adds or overrides only what’s specific to that board, like which UART is wired to a debug header or which GPIO drives a status LED.

Verifying A Compiled dtb

Because a .dtb is binary, you can’t just read it — but dtc can decompile it back to readable source for inspection, which is useful for confirming what actually got baked into the binary versus what you expected from the source:

$ dtc -I dtb -O dts arch/arm64/boot/dts/ep/ep-devboard-a.dtb | less

This round-trip is one of the fastest ways to catch a mistake like a node accidentally disabled with status = "disabled", or an overlay that didn’t apply the way you expected.

Real-World Use Case: Bringing Up A New Board Revision

Say your team spins a new hardware revision that moves the debug UART to a different pin and adds a second LED. With the device tree model, that change lives entirely in one new .dts file that includes the existing SoC .dtsi and overrides just the two changed nodes — no kernel or driver source changes, no separate kernel build. You add the new file to the vendor’s Makefile list, run make ARCH=arm64 dtbs, flash the new .dtb alongside the existing kernel image, and the same kernel now boots correctly on both revisions.

Common Mistakes And Troubleshooting

Best Practices

• Keep shared SoC details in a .dtsi and board-specific details in the .dts — don’t duplicate common nodes across boards
• Use overlays (.dtbo) for optional add-on hardware instead of maintaining separate full .dts files per configuration
• Decompile your built .dtb after any node change to confirm the compiled result matches your intent
• Give new nodes clear, vendor-prefixed compatible strings to avoid collisions with upstream driver matches

Security Considerations

A device tree is trusted, unauthenticated input to the kernel on most embedded boot chains — if an attacker can substitute the dtb, they can potentially remap memory regions or disable protections a driver relies on. On products where firmware integrity matters, verify the dtb alongside the kernel image using your bootloader’s signature/verification mechanism rather than treating it as inert configuration data.

Summary And Key Takeaways

• Device trees separate hardware description from kernel code, letting one kernel binary support many boards
• make ARCH=$ARCH dtbs compiles every listed .dts into a .dtb using the in-tree dtc compiler
• .dtsi files hold shared SoC-level detail; .dts files hold board-specific detail; .dtb is the compiled result the bootloader hands to the kernel
• Decompiling a built .dtb is the fastest way to confirm what actually got compiled

Conclusion

Between this lecture and the previous one on building kernel images with kbuild, you now have the complete picture of what a bootloader needs to start Linux on an ARM board: a boot-ready kernel image and a matching device tree blob. Understanding both halves — and how kbuild builds each one independently — is one of the more practical, immediately useful skills covered in this free linux device drivers course, especially once you start bringing up your own board revisions.

Frequently Asked Questions