Understanding phandle in Device Tree: Definition, Examples & Best Practices

0 8 8 minutes read

If you are working with embedded Linux, device trees or writing drivers, you may have come across the term phandle. At first glance it looks like another obscure piece of kernel or devicetree jargon—but once you understand it, it becomes a powerful tool for structuring hardware descriptions, linking components and writing clean drivers.
In this article I will explain what a phandle is, why it matters, how you can use it (and misuse it), and I’ll walk you through examples and best practices based on real devicetree work. I’ll speak in plain English so that even if you’re just beginning with device trees, you’ll feel comfortable.
Let’s dive in.

Definition of phandle

So, what exactly is a phandle?
In the context of the device tree (DTS/DTB) for embedded systems, a phandle is a property that holds a number—an unsigned 32-bit integer (u32) in many cases—that references another node in the device tree. In other words, you can think of a phandle as a pointer or link from one node in the tree to another.
Consider this analogy: in C programming you might use a pointer to reference a structure. In devicetree syntax, phandles serve a similar role: they let you reference “this node” from “that node”. For example, an interrupt controller node might define phandle = <1>;, and another node that uses this controller might list interrupt-parent = <1>;.
Why is this useful? Because hardware is often described in pieces: you might have a clock node, a GPIO node, and a peripheral node. The peripheral might say: “I use that clock” by referencing the clock node’s phandle. This keeps things modular and clean.

Why phandle matters in embedded systems

You might wonder: okay, it’s a number referencing another node—but why is that important? Here are a few reasons from my own device tree and driver-writing work:

Clear relationships: Hardware components often depend on other components—for example a device might need a clock, a reset line controller, interrupts, or GPIOs. By using phandles, the devicetree explicitly captures these relations, not just in comments but in machine-readable form.
Driver integration: In the Linux kernel (and other embedded OSes) drivers often parse the device tree to find the resources they need. Using a phandle, a driver can ask the OS: “which clock node does this device reference?” and get back a handle or pointer. For example, there’s a function of_parse_phandle() (or variants) in the kernel.
This makes drivers flexible: the same driver can work with different hardware trees as long as the phandle references are correct.
Hardware abstraction and reuse: Suppose you’re building many boards with slightly different configurations. If each board’s devicetree uses phandles, you can reuse nodes—only the referencing changes. This saves time and avoids duplication.
Validation and tooling: Because phandles are standardised in the devicetree specification, tools (like compilers, linters, devicetree checkers) can validate them. They can check “does this phandle actually point to a valid node?” rather than leaving references informal.

In short: phandles are a small piece of syntax but they unlock good architecture when you describe hardware.

Representation and usage

Let’s get into the details of how phandles work, how they are represented in device tree syntax, and some key variants.

Basic phandle property

According to the devicetree specification, a node that can be referenced defines a phandle property which holds a unique u32 value.
For example:

Here the node pic@10000000 declares phandle = <1>;. If another node wants to reference this controller, it can write:

The 1 is the phandle value—not an address, not a pointer in memory, just the identifier in the compiled devicetree.

phandle vs phandle-array

Often you need to reference multiple nodes, or reference nodes with additional data (specifier cells). The spec describes types:

phandle: one node reference
phandles: zero or more node references
phandle-array: zero or more node references plus specifier cells (extra data)

Here’s an example of a phandle-array:

In this example:

&foo is a phandle to the node labelled foo, followed by specifiers 1 2.
&bar is a phandle followed by 3.
&baz is a phandle followed by 4 5.

From a driver’s perspective, the specifier cells give extra metadata—maybe an index, maybe flags.

phandle with arguments

Sometimes you see a phandle property with an argument. For example:

Here the &bar is the phandle to bar, and the 2 is an argument (specifier). In the driver’s code you might see something like of_parse_phandle_with_fixed_args(...) to extract both the node pointer and the argument.
This allows richer hardware descriptions: “this device uses bar, at index 2”.

Deprecated “linux,phandle”

In older devicetree usage you might see linux,phandle instead of phandle. The meaning is identical but it’s considered deprecated. The spec explains the preferred property is now phandle.
When writing new DTS files, it’s best to use phandle.

Real-world examples from device tree files

Let me walk you through a couple of examples to make this concrete.

Example 1: Simple phandle usage

Suppose we have a clock node:

Then we have another node:

Here the clocks = <&clk_rc32k_ck>, <&clkdiv32k_ick>; uses phandles to reference two clock nodes.
In this way the wdt1_fck node says “my parent clocks are these two nodes”.

Example 2: Phandle array usage

In a pin control scenario:

Here multiple nodes are referenced inside one property, each specified as &label. This corresponds to the phandles type.
If specifier cells followed each phandle, it would be a phandle-array.

Example 3: Driver side parsing

From the kernel blog:

This code shows how a driver might parse a phandle property like "bar = <&bar 2>": the function retrieves the device_node and the specifier arguments.
This underlines how phandles become meaningful at runtime.

How to use phandle in your project

Based on my experience working with devicetrees and drivers, here’s a step-by-step guide to using phandles nicely:

Label your nodes in your DTS file. Choosing meaningful labels helps both you and anyone else who reads the code. For example:

gpio-controller: gpio@12340000 { compatible = "vendor,gpio"; #gpio-cells = <2>; phandle = <10>; … };

Here gpio-controller is the label; phandle = <10>; gives the node identifier.
Reference that label from other nodes. For example:

my_device@0 { compatible = "vendor,my_device"; gpios = <&gpio-controller 5 0>; … };

Here &gpio-controller is the phandle reference, and 5 0 might be specifiers (pin number, flags).
Match the specifier cell count. If your binding says #gpio-cells = <2>, the specifier must have exactly two cells (e.g., “5 0”). If you mismatch, you’ll face compile-time or runtime issues.
Driver side parsing. In your driver’s probe() function (or equivalent) you might do:

ret = of_parse_phandle_with_fixed_args(np, "gpios", 2, 0, &args); if (ret) { dev_err(dev, "failed to parse gpios\n"); return ret; } gpio = args.args[0]; flags = args.args[1];

This gets you the node referenced by the phandle and the specifier. Use the APIs provided by the kernel or your OS.
Validate your tree. When building your device tree, compile it (dtc) and run any lint tools to ensure phandles point to valid nodes. Errors like “invalid phandle reference” or “specifier cell count mismatch” are common catches.
Keep it readable. Although the devicetree is machine-readable, it’s also read by humans. Use consistent naming, meaningful labels, comments when necessary. I like to add comments like:

/* Reference to the main clock controller */ main_clk: clock@... { phandle = <20>; }; … hci0: bluetooth@… { clocks = <&main_clk>; … };

That helps future you or your teammates.
Avoid magic numbers. Don’t just put <5> as a phandle value without context—use labels and keep the tree self-documented.

Common pitfalls and best practices

Even when you know phandles exist, people still make mistakes. I’ve been there. Here are pitfalls to watch and practices I recommend:

Mistaking a regular integer for a phandle: Often you’ll see something like property = <0x6 0x8 …>. But is 0x6 a value or a phandle? As one devicetree forum user put it:

“Phandle is a ID number of node in dts file. But if there is other integer number ‘0x6’ elsewhere … how to know if it is an actual value or a phandle?”

The rule of thumb: look at the property’s binding and type. If the binding says type <phandle> or <phandles> or <phandle-array> then you know those integers correspond to phandles or phandles + specifiers.
Ignoring specifier cell counts: If the provider node declares #cells = <1>, but the referencing node supplies 2 specifiers, you’ll likely trigger a compile or runtime error.
Label mismatch or missing labels: If you omit labels and use numeric phandle values manually, it becomes very brittle. Labels help keep things stable if you reorder nodes.
Using deprecated linux,phandle property: Although supported for compatibility, it’s better to use phandle.
No runtime check in driver: On the driver side, always check return values when parsing phandles. Don’t assume the node exists or has expected properties.
Poor documentation: Because phandles connect nodes, lack of comments or self-explanatory names risks future maintainers not understanding the relations.

Best practices summary:

Use meaningful labels.
Match specifier cell counts.
Reference nodes via &label, not hard numbers.
Validate your tree with tools.
In driver code, handle errors gracefully.
Prefer phandle over linux,phandle.
Document the relationships in comments.

Conclusion

To wrap up: phandles are a core part of devicetree architecture. They let nodes reference each other in a clean, structured way. While the concept is simple—a number pointing to a node—the proper use of phandles unlocks modular, maintainable hardware descriptions and drivers.
In my experience when phandles are used well, you get a devicetree that is easier to read, easier to adapt, and less error-prone. When they’re not used well—for example via hardcoded numeric values, missing labels or specifier mismatch—you’ll spend hours tracking weird errors.
So if you’re building or maintaining embedded Linux systems, invest the time to get phandles right: label nodes clearly, reference properly, validate, and document. Your future self (and anyone else who touches the code) will thank you.

FAQ

Q: What is a phandle?
A: It is a property in a devicetree node that holds a unique identifier (u32) referencing another node. It is used to establish relationships between nodes. devicetree-specification.readthedocs.io+1

Q: How is phandle different from phandle-array?
A: A simple phandle references a single node. A phandle-array can reference multiple nodes and include specifier cells (extra data) after each phandle. docs.zephyrproject.org+1

Q: Can phandle have arguments?
A: Yes. In the phandle-array case (or sometimes even simple phandle with specifier), you can include extra values after the node reference, which drivers interpret. bootlin.com

Q: What if I use the wrong phandle value?
A: You’ll likely see compile-time errors from dtc or runtime bugs—your driver may not find the referenced node, leading to crashes or mis-behaviour.

Q: Where can I find phandle examples?
A: Look into Linux kernel source under Documentation/devicetree/bindings/, or blogs like the Bootlin post. The example in the DTS files for your SoC often show phandle usage too.

Understanding phandle in Device Tree: Definition, Examples & Best Practices

Definition of phandle

Why phandle matters in embedded systems