.DTB File Format – Overlays

Fragments

The root of an overlay holds one or more fragments, nodes conventionally called fragment@0, fragment@1 and so on. A fragment has a target and a child node named __overlay__.

• target: a phandle, the node of the base tree that the content of __overlay__ is merged into. In a compiled overlay it is 0xFFFFFFFF, a value no node has, until a fixup writes the real phandle.
• target-path: a string, the path of the target node, which libfdt reads when a fragment has no target.
• __overlay__: the properties and child nodes to merge into the target.

__fixups__

A node at the root. Each of its properties is named after a label of the base tree that the overlay refers to, and its value is a list of strings, each path:property:offset: the path of a node in the overlay, the property in it, and the byte offset in that property’s value of a phandle that has to be set to the base node’s phandle. The compiler leaves 0xFFFFFFFF there. Example from the dtc document, for a fragment that targets the label ocp:

__fixups__ {
    ocp = "/fragment@0:target:0";
};

__local_fixups__

A phandle inside the overlay that points at another node of the same overlay holds a number the compiler picked; the loader adds its own offset to every such phandle, so that overlays do not clash. __local_fixups__ is a copy of the overlay’s node layout in which each property is named after a property that holds such phandles and its value is a list of u32 byte offsets of them within the value.

__local_fixups__ {
    fragment@1 {
        __overlay__ {
            baz {
                ref-to-res = <0>;
            };
        };
    };
};

__symbols__

Written when the source is compiled with dtc -@. Each property is the name of a label, and its value is the path of the node that carries it. A base tree compiled this way has a __symbols__ node so that overlays can find its labels, and the Pi’s bcm2710-rpi-zero-2-w.dtb has one with 159 labels. Readers that do not apply overlays ignore it.

What the viewer does

A blob with a fragment that has an __overlay__ child, or a __fixups__ or __local_fixups__ node, is shown as an overlay. It gets tables of the fragments (target, and what __overlay__ adds), of the fixups and of the local fixups, and of the symbols. It checks that:

• every fragment has a target or a target-path;
• every __fixups__ string has the form path:property:offset, names a node and a property that exist in the overlay, that the offset leaves room for a 4-byte phandle, and says whether the word there is the placeholder 0xFFFFFFFF;
• every __local_fixups__ property names a property of the same node path in the overlay and that its offsets are inside that value.

It does not apply the overlay to a base tree.