Skip to content

mohitmishra786/low-level-dev-skills / skills/kernel-dev/device-tree

device-tree

Verified

Device tree skill for Linux hardware description. Use when writing DTS/DTSI, bindings, overlays, phandles, or debugging OF platform probe failures. Activates on queries about device tree, DTS syntax, phandle, devicetree bindings, DT overlay, or OF graph.

FileKindSize
SKILL.mdskill md3.4 KB
---
name: device-tree
description: Device tree skill for Linux hardware description. Use when writing DTS/DTSI, bindings, overlays, phandles, or debugging OF platform probe failures. Activates on queries about device tree, DTS syntax, phandle, devicetree bindings, DT overlay, or OF graph.
---

# Device Tree (Devicetree)

## Purpose

Guide agents through Linux device tree source (DTS): syntax, bindings, phandles, overlays, and how the kernel OF (Open Firmware) layer parses hardware description into `platform_device` instances.

## Triggers

- Platform driver not probing — DT mismatch
- Adding a new board `.dts` or fragment overlay
- Understanding `compatible`, `reg`, `interrupts`, `clocks` properties
- Cross-checking hardware with `skills/kernel-dev/platform-device-model`

## Workflow

### 1. DTS structure

```dts
/dts-v1/;
#include "soc.dtsi"

/ {
    model = "My Board";
    compatible = "vendor,my-board", "vendor,soc-family";

    soc {
        uart0: serial@40011000 {
            compatible = "vendor,uart";
            reg = <0x40011000 0x400>;
            interrupts = <GIC_SPI 38 IRQ_TYPE_LEVEL_HIGH>;
            clocks = <&clk_uart0>;
            status = "okay";
        };
    };
};
```

### 2. Key properties

| Property | Meaning |
|----------|---------|
| `compatible` | Driver match string (most specific first) |
| `reg` | MMIO address + length ( `#address-cells`, `#size-cells` ) |
| `interrupts` | IRQ specifier (interrupt parent defines cells) |
| `clocks` / `clock-names` | phandle to clock provider |
| `status` | `"disabled"` skips probe |

### 3. Phandles

```dts
clk_uart0: clock-uart {
    compatible = "vendor,clk";
    #clock-cells = <0>;
};

serial@... {
    clocks = <&clk_uart0>;  /* phandle reference */
};
```

### 4. Kernel parsing

```text
OF core reads DTB at boot
├── of_platform_populate() creates platform_devices
└── driver `.of_match_table` matches `compatible`
```

```c
static const struct of_device_id my_of_match[] = {
    { .compatible = "vendor,uart" },
    { }
};
MODULE_DEVICE_TABLE(of, my_of_match);
```

### 5. Compile and inspect

```bash
dtc -I dts -O dtb -o board.dtb board.dts
dtc -I fs -O dts /proc/device-tree 2>/dev/null | less
ls /sys/firmware/devicetree/base/
```

Bindings live at [devicetree.org](https://www.devicetree.org/) — always cite binding name in commits.

### 6. Overlays (configfs)

```bash
# Runtime overlay apply (when CONFIG_OF_OVERLAY)
mkdir -p /config/device-tree/overlays/my-overlay
cat my-overlay.dtbo > /config/device-tree/overlays/my-overlay/dtbo
```

### 7. Agent usage

```text
/device-tree Write DTS fragment for I2C sensor on i2c1 with interrupt on GPIO5
```

## Common Problems

| Symptom | Cause | Fix |
|---------|-------|-----|
| Driver not bound | `compatible` typo | Match driver's `of_match_table` |
| Wrong MMIO | `#address-cells` mismatch | Follow SoC `.dtsi` |
| IRQ not firing | Wrong interrupt parent/cells | Copy from working board DTS |
| Probe defer loop | Clock/regulator missing | `-EPROBE_DEFER` supplier in DT |
| Overlay fails | Symbol unresolved | `__fixups__` / label exports |

## Related skills

- `skills/kernel-dev/platform-device-model` — probe and sysfs
- `skills/kernel/device-drivers` — `devm_of_iomap`
- `skills/baremetal/datasheet-and-refmanual-reading` — HW to DT mapping
- `skills/embedded/zephyr` — Zephyr devicetree (different tooling)
- `skills/kernel-dev/bus-drivers-i2c-spi` — bus node children
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall