phandles

Phandles are unique identifiers used within device tree structures to reference one node from another. In Open Firmware and its descendants, including Flattened Device Tree (FDT) used by Linux and other systems, each node may be assigned a phandle, a 32-bit integer value. A node can obtain a phandle either by declaring a phandle property explicitly or by automatic assignment during device tree compilation.

Phandles enable cross-referencing between nodes through properties that describe hardware resources or relationships, such as clocks, interrupts, resets, or memory regions. In source form (DTS), a node can be given a label, and other nodes reference it using a phandle reference like <&label>. In the compiled binary device tree, these references resolve to the numeric phandles stored in the relevant properties.

The primary purpose of phandles is to provide stable indirection. They allow a node’s resources to be described without hard-coding node paths, which is useful when the tree layout changes. For example, a device can request a clock by referencing the phandle of a clock provider, or a peripheral can cite its interrupt controller by using the corresponding phandle.

Not every node must have a phandle; nodes without a explicit phandle can still be referenced if the tree’s compiler assigns one automatically, though explicit phandles improve readability and maintenance. Incorrect or duplicate phandles can lead to boot or runtime failures, as references may point to the wrong nodes or become unresolved.

In summary, phandles are fundamental to the device tree mechanism, providing stable, compact handles that connect related hardware description nodes in a flexible and scalable way.