.DTB File Format

Introduction

A devicetree describes the hardware of a board to the software that runs on it: which processors there are, how much memory, which devices sit at which addresses, which interrupts they raise and which devices a console is on. It is written as a text source (.dts), compiled by the dtc tool into a flattened devicetree blob (.dtb), and read by a boot program and by the operating system. Linux and U-Boot read it. The blob is the same on every architecture, ARM, ARM64, RISC-V, PowerPC and others.

On a Raspberry Pi the boot partition holds one .dtb for each board, for example bcm2711-rpi-4-b.dtb or bcm2710-rpi-zero-2-w.dtb. The firmware reads the file for the board it is running on, applies the overlays that config.txt names, and passes the result to the kernel. A .dtbo is such an overlay: a small blob with the same layout that changes or adds nodes in a base tree.

Structure

All numbers are big-endian, on every machine. The blob is a header and three blocks. The header gives each block’s offset and size. The structure block is the tree itself, a stream of tokens that open and close nodes and give them properties. The names of properties are not in the stream: they are in the strings block and the stream points at them. The Devicetree Specification (chapter 5) puts the blocks in this order, with free space allowed between them for alignment.

The values of properties are bytes. What they mean depends on the property’s name: a compatible is a list of strings, a reg is a list of addresses and sizes whose width comes from the parent node. The standard properties page lists the names the Specification defines and what type each has. A property with any other name carries no type in the file.

In the explorer

Drop a .dtb or .dtbo on the explorer to see the blob as a map of its bytes and as a tree: the header words, the memory reservations, every node with its properties under it, and the strings. Each property is shown by what its name says it is: a string list, a cell count taken from the parent, a phandle that names the node it points to, an interrupt specifier cut by the interrupt parent’s #interrupt-cells. The viewer does not guess a type from the bytes. A property whose name is not in the table shows its string, cell and byte readings side by side, and the options bar can ask for one of them for all such properties. The offsets, alignment, sizes and version rules are checked, and anything that does not hold is listed as a problem and the file is still shown as far as it can be read. A FIT image (.itb) is a devicetree too and also gets its images, hashes and configurations as tables. An overlay also gets its fragments, __fixups__ and __local_fixups__ as tables, checked against the properties they point into.

Not described

Known, not yet covered

• Reference: the property names defined by the Linux and U-Boot bindings (clocks, resets, gpios, pinctrl-*, dmas and thousands more) and the nexus properties that take a phandle and a number of cells from the target node. They are documented in the kernel’s binding files; the standard properties page covers only what the Devicetree Specification defines.
• Viewer: such properties show their bytes with the string, cell and byte readings side by side, not a typed value. Unit addresses in node names are not checked against reg. A blob is not checked against the schema of its bindings.
• Viewer: versions older than 16 are read with the rules libfdt applies (values of 8 bytes or more on an 8-byte boundary, full paths as names). The viewer was checked on version 3 and 16 blobs written by dtc, not on real files of those versions.
• Viewer: an overlay is checked for consistency but not applied to a base tree.

Unknown

• Reference: the Raspberry Pi firmware’s own additions to overlays and to the base tree (the __overrides__ node of the Pi overlays, parameters on config.txt lines) are not described in a public specification we could read for these pages.

Links