PREV_LEC  |  NEXT_LEC

What You Will Learn

• The exact <name>[@<address>] format every device tree node must follow
• When the unit address is required and when it can be left out
• How the reg property and the unit address relate to each other
• What a label is for and why it is optional
• How to write a driver that distinguishes sibling nodes by their address

Prerequisites

• Completed Part 1 of this chapter (device tree concept and data types)
• Comfortable with of_device_id and platform_driver from the earlier platform driver chapter
• A board or QEMU target that boots from device tree, plus the dtc compiler

The Node Name Format

Every device tree node name must follow this pattern:

<name>[@<address>]

<name> is a plain string, at most 31 characters, describing the general class of
device — sensor, i2c, uart, expander. The
@<address> part is optional and only appears when the node represents an
addressable device: something that lives at a specific register offset or bus address
that the kernel needs to know to talk to it.

Two real examples make the pattern concrete:

expander@20 {
    compatible = "microchip,mcp23017";
    reg = <0x20>;
};

i2c@021a0000 {
    compatible = "fsl,imx6q-i2c", "fsl,imx21-i2c";
    reg = <0x021a0000 0x4000>;
};

The unit address after @ should always match the primary address in the node’s
reg property. This is not just a style convention — the device tree compiler and
kernel tooling both expect the two to agree, and mismatches are flagged by dtc
warnings during compilation.

When Can The Address Be Left Out?

If a node does not represent something the kernel needs to address directly — a container node
like aliases, or a purely logical grouping node — it has no @address and
no reg property at all. The rule is simple: no addressable resource, no unit address.

Labels Are Optional, And Different From Names

A label is a separate, optional tag placed before the node, like
ep_sensor: in the snippet below. It has nothing to do with the naming rule above — a
node can be perfectly valid with no label at all. A label only matters when some other node needs
to reference this one (we cover that fully, along with phandles, in the next lecture).

ep_sensor: sensor@53 {
    compatible = "ep,demo-sensor";
    reg = <0x53>;
};

Hands-On: A Driver That Reads Its Own Unit Address

Let’s extend the sensor example from Part 1 to two sibling nodes on the same bus, each with a
different unit address, and write an original driver that tells them apart at probe time by
reading the reg property directly — the same value that appears after the
@ in the node name.

// ep-multi-overlay.dts (fragment)
front_sensor: sensor@53 {
    compatible = "ep,demo-sensor";
    reg = <0x53>;
    label = "front-sensor";
};

rear_sensor: sensor@54 {
    compatible = "ep,demo-sensor";
    reg = <0x54>;
    label = "rear-sensor";
};

// ep_addr_demo.c
#include <linux/module.h>
#include <linux/platform_device.h>
#include <linux/of.h>
#include <linux/of_device.h>

static int ep_addr_demo_probe(struct platform_device *pdev)
{
    struct device *dev = &pdev->dev;
    u32 unit_addr;
    const char *label = "unknown";
    int ret;

    ret = of_property_read_u32(dev->of_node, "reg", &unit_addr);
    if (ret) {
        dev_err(dev, "node %pOF has no reg property\n", dev->of_node);
        return ret;
    }

    of_property_read_string(dev->of_node, "label", &label);

    dev_info(dev, "ep_addr_demo: node=%pOF addr=0x%02x label=%s\n",
             dev->of_node, unit_addr, label);

    return 0;
}

static const struct of_device_id ep_addr_demo_of_match[] = {
    { .compatible = "ep,demo-sensor" },
    { }
};
MODULE_DEVICE_TABLE(of, ep_addr_demo_of_match);

static struct platform_driver ep_addr_demo_driver = {
    .probe = ep_addr_demo_probe,
    .driver = {
        .name           = "ep_addr_demo",
        .of_match_table = ep_addr_demo_of_match,
    },
};
module_platform_driver(ep_addr_demo_driver);

MODULE_LICENSE("GPL");
MODULE_AUTHOR("EmbeddedPathashala");
MODULE_DESCRIPTION("Original device tree unit address demo");

The %pOF printk format specifier prints the full node name including its unit
address, so you get confirmation straight from the kernel that each node was matched
individually — one driver, two independent probe() calls.

$ dtc -@ -I dts -O dtb -o ep-multi.dtbo ep-multi-overlay.dts
$ sudo dtoverlay ep-multi.dtbo
$ sudo insmod ep_addr_demo.ko
$ dmesg | tail -4

Expected output:

[  55.201113] ep_addr_demo sensor@53: ep_addr_demo: node=/sensor@53 addr=0x53 label=front-sensor
[  55.204871] ep_addr_demo sensor@54: ep_addr_demo: node=/sensor@54 addr=0x54 label=rear-sensor

Common Mistakes And Troubleshooting

Best Practices

• Always keep the unit address after @ identical to the first value in reg
• Use generic, class-based names (sensor, uart) rather than vendor-specific names — the compatible string is where vendor identity belongs
• Only add a label when another node will actually reference this one — unused labels add noise
• Run dtc with warnings enabled during development to catch naming mismatches early

Real-World Use Case

This exact naming discipline is what lets a single I2C driver bind to every sensor on a bus,
regardless of how many are present — each gets its own unit address, its own probe() call, and its
own private data, while sharing one driver’s code.

Summary And Key Takeaways

• Node names follow <name>[@<address>], capped at 31 characters
• The unit address is only present for addressable devices and must match reg
• Labels are optional and unrelated to naming — they exist purely for cross-node references
• A single driver can distinguish sibling nodes at runtime by reading reg directly

Conclusion

With naming rules covered, node names should no longer feel arbitrary — every part of
sensor@53 has a defined meaning. Next in this free embedded systems course
chapter, we cover aliases, labels, and phandles: how nodes reference each other across the tree,
plus how to actually compile a .dts file into the .dtb the kernel boots
from.

Frequently Asked Questions

PREV_LEC  |  NEXT_LEC