--- title: "Devicetree" canonical_url: https://developer.repebble.com/pebbleos/docs/development/build_system/devicetree/ last_updated: 2026-11-13 sdk_version: 4.44 --- # Devicetree Source: https://developer.repebble.com/pebbleos/docs/development/build_system/devicetree/ A board’s hardware is described by a devicetree: what is on it, where, and how it is wired. The tree follows the Linux devicetree bindings and conventions, so the same description could boot Linux on that SoC. It only exists at build time: nothing of it is stored or parsed by the firmware. Each device it describes becomes a static, read-only instance, as if it had been written by hand. The devicetree decides two things: - **Which drivers are built.** A driver is enabled by default when the tree has an enabled node it binds to, through a `DT_HAS__ENABLED` symbol in Kconfig. - **Which devices exist, and how they are connected.** Each enabled node whose driver is enabled becomes a call to that driver’s instance macro. The native boards, such as `native_emery`, run on the host and have no hardware to describe: their drivers define their devices in C, and their roles name them; see [Roles](#devicetree-roles). The QEMU boards run on emulated hardware, which a tree describes like any other: `dts/qemu/pebble.dtsi` for the machine, a board tree for each. ## Trees | File | Contents | | --- | --- | | `dts//.dtsi` | The SoC, as `dts/sifli/sf32lb52.dtsi`: CPU, interrupt controller, peripherals, mostly `status = "disabled"` | | `dts/qemu/pebble.dtsi` | The QEMU Pebble machines, whose peripherals are QEMU devices (`qemu,pebble-*`) | | `boards//.dtsi` | What the revisions of a board share | | `boards//-pinctrl.dtsi` | The pin control states of the board, on SoCs with a pin controller | | `boards//_.dts` | A revision, e.g. `obelix_pvt.dts`, or `.dts` for boards with one | | `include/dt-bindings/` | Constants the trees use, such as clock IDs and GPIO flags | | `dts/bindings/` | Bindings that upstream does not have | A board tree includes its SoC tree, enables the peripherals it uses, and adds what is on the board: sensors on a bus, the flash on its controller, the panel, supplies switched by GPIOs. ``` &i2c2 {pinctrl-0 = \<&i2c2\_default\>;pinctrl-names = "default";clock-frequency = \<400000\>;dmas = \<&dmac1 5 23 2\>;dma-names = "rx";status = "okay";lsm6dso: imu@6a {compatible = "st,lsm6dso";reg = \<0x6a\>;interrupt-parent = \<&gpio1\>;interrupts = \<38 IRQ\_TYPE\_EDGE\_RISING\>;mount-matrix = "-1", "0", "0","0", "1", "0","0", "0", "1";};}; ``` ## From tree to instances ``` flowchart TD dts["boards/<board>/*.dts
dts/*/*.dtsi
application overlays"] dtc["dtmap.py: C preprocessor, dtc"] dtb["board.dtb"] kdt["Kconfig.dt
DT_HAS_*_ENABLED"] kconfig["Kconfig"] cfg[".config"] dtmap["dtmap.py"] specs["*.dtmap.yaml, *.class.yaml, *.regs.yaml"] roles["roles.yml"] out["devicetree/devices.h
devicetree/partitions.h
devicetree/regs.h
devicetree/instances/*.inc
devicetree/roles.c"] drv["drivers"] dts --> dtc --> dtb --> kdt --> kconfig --> cfg --> dtmap dtb --> dtmap specs --> dtmap --> out --> drv roles --> dtmap classDef app fill:#fa4a36,stroke:#fa4a36,color:#ffffff classDef system fill:#fd8a7c,stroke:#fd8a7c,color:#171717 classDef base fill:#525252,stroke:#525252,color:#ffffff class dts,roles,out app class dtc,kconfig,dtmap system class dtb,kdt,cfg,specs,drv base ``` 1. **Compile.** When the build directory is configured, `tools/cmake/kconfig.py` has `tools/devicetree/dtmap.py` compile the board’s tree before Kconfig runs, followed by the overlays of the application, if any; see [Overlays](#devicetree-overlays). The C preprocessor runs first, with `boards/`, `dts/` and `include/` on the include path, then `dtc`, into `devicetree/board.dtb` in the build. `dtc`’s default checks apply, with `unique_unit_address_if_enabled` in place of `unique_unit_address`; a warning fails the build. 2. **Kconfig.** In the same step, `dtmap.py` writes `devicetree/Kconfig.dt`, with one `DT_HAS__ENABLED` symbol for every compatible a driver binds to, set when the tree has an enabled node of that compatible. The root `Kconfig` sources it, and drivers default to it. 3. **Generate.** At build time, `dtmap.py` reads the compiled tree, the resolved `.config` and the specs of the drivers, and writes, under `generated/include/devicetree/`: `dtc` is needed to configure a board with a tree; see [Getting started guide](https://developer.repebble.com/pebbleos/docs/getting_started.md). ## Writing trees The trees follow Linux, so that what is learned there applies here and the other way around: - **Bindings.** A node follows the upstream binding of its compatible when there is one, property for property. A binding of our own goes in `dts/bindings/`, written the way upstream would accept it. - **Compatibles.** A compatible names the part, e.g. `jdi,lpm015m135a`, never a family or a board. A peripheral that a whole SoC series shares lists the part it is on first and the first part that had it last, as `"nordic,nrf52840-twim", "nordic,nrf52832-twim"`: the driver names the last one in its spec, so one driver serves the series. - **Hardware only.** A node is a piece of hardware: one node per hardware block, with generic node names (`i2c@`, `serial@`, `spi@`, `pwm@`, `display-controller@`). Software constructs, configuration and policy are not nodes. - **Functions of a block.** A block that works as one of several peripherals, all through the same registers, has a node per function, siblings at the block’s address, each with its own compatible and label. Only one of them may be enabled, which `dtc` checks. A function that a block offers on top of its own, as a timer driving a PWM output, is a child node of the block: - **Abstract IDs.** When a specifier identifies something inside the device it points to, such as one of the clocks of a clock controller, one of its resets or a request line of a DMA controller, the number is an ID that the binding defines in a header under `include/dt-bindings/`, never a register bit or the index a driver happens to use. The tree then only depends on the binding, as upstream requires, and a driver can number things as it likes: the `ids` key of its spec maps each ID to the driver’s number when the instances are generated, and an ID the driver does not know fails the build. - **Pins.** On SoCs with a pin controller, pins are pin control states, with the generic pin configuration properties (`input-enable`, `bias-pull-up`, `drive-strength`, `output-low`). Peripherals that select their own pins, as on the nRF52, take them as GPIO properties named after the signal (`scl-gpios`, `sck-gpios`, `tx-gpios`). - **References.** A device that uses another one points to it, with the standard property for what it uses; see [References between devices](#devicetree-references). ### References between devices Most of what a node describes is how it is wired to other devices: the regulator that powers it, the clock it runs from, the GPIO that enables it, the PWM that drives one of its inputs. The node of the device that uses something (the consumer) points to the node of the device that provides it (the provider), with a phandle and, when the provider has several of them, cells saying which one: ``` sensor@48 {compatible = "vendor,sensor";reg = \<0x48\>;vdd-supply = \<&ldo1\>;/\* a regulator \*/enable-gpios = \<&gpio0 5 GPIO\_ACTIVE\_HIGH\>; /\* pin 5 of a GPIO controller \*/interrupt-parent = \<&gpio0\>;interrupts = \<6 IRQ\_TYPE\_EDGE\_RISING\>;/\* an interrupt, here from a pin \*/clocks = \<&rcc RCC\_CLK\_SENSOR\>;/\* one of the clocks of the RCC \*/pwms = \<&timer1\_pwm 0 16666666 0\>;/\* a PWM channel, period, flags \*/}; ``` The properties are the standard ones of the upstream bindings: `-supply` for regulators, `-gpios`, `interrupts` or `interrupts-extended`, `clocks`, `resets`, `dmas`, `pwms` and `mboxes`, with `-names` properties to pick an entry by name. A rail switched by a GPIO is a `regulator-fixed` node, so that its consumers refer to it as to any other regulator. Devices along a data path, such as a display controller and its panel, are connected by a graph: a `port` in each node, with an `endpoint` pointing at the other. The generator turns each reference into C in two steps. The consumer’s spec says which reference fills which argument of its instance macro (`supply: vdd`, `gpio: enable`, `pwm: 0`); see [Specs](#devicetree-specs). The provider’s class, or its spec, gives the C of a reference to one of its devices from the cells (`provides`); see [Classes](#devicetree-classes). A reference to a node that is disabled, or whose driver is not enabled, fails the build, and the provider is initialized before the consumer; see [Initialization order](#devicetree-init-order). ### Roles Which device code uses for a purpose is not in the tree: which UART is the console, which flash holds the filesystem, which sensor is the accelerometer. These are roles. Each class lists the roles of its devices, with the Kconfig symbol that needs them, if any: ``` class: audiotype: struct pbl\_audioinclude: pbl/drivers/audio.hroles:mic: MICspeaker: SPEAKER ``` A role is reached from C as its name in capitals, a pointer declared by the class header, as `SPEAKER`: | Role | Class | Needed by | | --- | --- | --- | | `console_uart` | `uart` | | | `qemu_uart` | `uart` | | | `bt_hci_uart` | `uart` | `BT_HCI_UART` | | `display` | `display` | `DISPLAY` | | `backlight` | `backlight` | `BACKLIGHT` | | `flash` | `flash` | `FLASH` | | `accel` | `accel` | `ACCEL` | | `mag` | `mag` | `MAG` | | `als` | `als` | `ALS` | | `touch` | `touch` | `TOUCH` | | `vibe` | `vibe` | `VIBE` | | `mic` | `audio` | `MIC` | | `speaker` | `audio` | `SPEAKER` | | `die_temp` | `temp` | `TEMP` | | `rtc` | `rtc` | `RTC` | | `battery` | `battery` | | A board gives each role it has a device in `boards//roles.yml`, and a revision changes them in `roles..yml`. A device is the label of a node, or a symbol for a device defined in C, with the header declaring it: ``` console\_uart: uart2flash: flash0accel:symbol: SIM\_ACCELinclude: pbl/drivers/imu/sim.h ``` An application changes them in its `roles.yml`, then in `boards/.roles.yml`: a role there replaces the board’s, and `null` removes it. A class object of the node is taken, so a node implementing several classes, as a display with its backlight, can have several roles. `dtmap.py` writes `devicetree/roles.c`, defining each role whose symbol is enabled: ``` const struct pbl\_accel \*const ACCEL = &dt\_lsm6dso; ``` An enabled symbol whose role has no device, or a device with no driver, fails the build. A role no symbol needs is left out when its device has no driver. ### Overlays An application changes the board’s tree with overlays, applied after it in this order: `app.overlay`, for every board, then `boards/.overlay`. An overlay changes nodes by their label, and can add new ones: ``` &lsm6dso {status = "disabled";};&i2c2 {status = "okay";}; ``` They take the include path and preprocessor of the board’s tree. A board without a tree has nothing to overlay, which fails the build. ### Validating `tools/devicetree/validate.py` checks our bindings and the board trees with dtschema, against the upstream bindings and ours. The upstream bindings and their headers come from the `third_party/devicetree/devicetree-rebasing` submodule, pinned to a release, and dtschema is in `requirements.txt`: ``` python3 tools/devicetree/validate.py \--bindings dts/bindings//,.yaml \--all-trees ``` `--bindings` checks bindings as upstream checks its own: against the meta-schema, and their examples against the bindings. `--all-trees` compiles every board tree and checks it; compiled trees, such as `build/devicetree/board.dtb`, can be given instead. CI checks the bindings a pull request adds or changes, and every tree. ## Connecting a driver A driver takes part through three things: a class file for its class, a spec next to the driver, and the generated instances it includes. Classes and specs are found under `drivers/`, `kernel/` and `soc/`, and anywhere in the application’s directory, so an application can bring drivers of its own. ### Classes A class is the software model of a kind of device, unknown to the tree and to the bindings. `.class.yaml`, next to the class, gives its type, its header, and how other devices refer to one of its devices: ``` class: gpiotype: struct pbl\_gpio\_portinclude: pbl/drivers/gpio.hprovides:# Cells are \gpio: "PBL\_GPIO(&{sym}, {0}, PBL\_GPIO\_DT\_FLAGS({1}))" ``` A `provides` template turns a reference from another node into C: `{sym}` is the symbol of the referenced device, and `{0}`, `{1}`, … the cells of the specifier. Instance files include only class headers, so drivers do not need to know each other. The objects of a class hold their `struct pbl_device` as `dev`. A class that differs says so with `device`: a template such as `"&{sym}"` for a class whose type is the device itself, or `false` for objects that are not devices, as pin states. ### Specs `.dtmap.yaml`, next to the driver, says which compatible the driver binds to, which class it implements, and where each argument of its instance macro comes from: ``` compatible: vendor,soc-i2cconfig: I2C\_SOCclass: i2cdefine: PBL\_I2C\_SOC\_DEFINEargs:- name: true- reg: 0- irq: 0- clock: 0- prop: clock-frequencydefault: 100000- pinctrl: default ``` | Key | Meaning | | --- | --- | | `compatible` | The compatible the driver binds to. A node gets the drivers of the first compatible of its list that has an enabled one | | `config` | The driver’s Kconfig symbol | | `class` | The class it implements, or a list for a node giving several class objects | | `define` | Its instance macro | | `args` | The macro arguments after the symbol, in order | | `symbol` | The symbol of each class object, when it is not `dt_