Devicetree

Trees

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/&lt;board&gt;/*.dts<br/>dts/*/*.dtsi<br/>application overlays"]
  dtc["dtmap.py: C preprocessor, dtc"]
  dtb["board.dtb"]
  kdt["Kconfig.dt<br/>DT_HAS_*_ENABLED"]
  kconfig["Kconfig"]
  cfg[".config"]
  dtmap["dtmap.py"]
  specs["*.dtmap.yaml, *.class.yaml, *.regs.yaml"]
  roles["roles.yml"]
  out["devicetree/devices.h<br/>devicetree/partitions.h<br/>devicetree/regs.h<br/>devicetree/instances/*.inc<br/>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. 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_<compatible>_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/:

   • instances/<compatible>.inc for every driver with a spec: one call to its instance macro per enabled node it binds to, followed by the devices it needs; see Initialization order. The file exists, empty, on boards without such a node or without a tree;

   • devices.h, declaring dt_<label> for every labelled device with a driver, with the type of its class, and listing in a comment the enabled nodes with no driver in this configuration. A device with several labels is defined under the first in alphabetical order, and the others are macros for it;

   • partitions.h, the flash partitions; see Flash partitions;

   • regs.h, the registers of the blocks code reaches before there are devices; see Registers before devices;

   • roles.c, the device of each role; see Roles.

dtc is needed to configure a board with a tree; see Getting started guide.

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:

  /* The same registers, as an I2C or as a SPI controller: enable one */
  i2c0: i2c@40003000 {
  	compatible = "vendor,soc-i2c";
  	reg = <0x40003000 0x1000>;
  	status = "disabled";
  };
  
  spi0: spi@40003000 {
  	compatible = "vendor,soc-spi";
  	reg = <0x40003000 0x1000>;
  	status = "disabled";
  };
  
  /* A timer, and the PWM output it can drive */
  timer1: timer@40010000 {
  	compatible = "vendor,soc-timer";
  	reg = <0x40010000 0x1000>;
  
  	timer1_pwm: pwm {
  		compatible = "vendor,soc-timer-pwm";
  		#pwm-cells = <3>;
  	};
  };
  

• 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.

  #include <dt-bindings/clock/vendor,soc-rcc.h>
  
  &i2c0 {
  	clocks = <&rcc RCC_CLK_I2C0>;
  };
  

• 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.

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 */
};

class: audio
type: struct pbl_audio
include: pbl/drivers/audio.h
roles:
  mic: MIC
  speaker: SPEAKER

console_uart: uart2
flash: flash0
accel:
  symbol: SIM_ACCEL
  include: pbl/drivers/imu/sim.h

const struct pbl_accel *const ACCEL = &dt_lsm6dso;

&lsm6dso {
	status = "disabled";
};

&i2c2 {
	status = "okay";
};

python3 tools/devicetree/validate.py \
    --bindings dts/bindings/<dir>/<vendor>,<part>.yaml \
    --all-trees

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.

class: gpio
type: struct pbl_gpio_port
include: pbl/drivers/gpio.h
provides:
  # Cells are <pin flags>
  gpio: "PBL_GPIO(&{sym}, {0}, PBL_GPIO_DT_FLAGS({1}))"

compatible: vendor,soc-i2c
config: I2C_SOC
class: i2c
define: PBL_I2C_SOC_DEFINE
args:
  - name: true
  - reg: 0
  - irq: 0
  - clock: 0
  - prop: clock-frequency
    default: 100000
  - pinctrl: default

ids:
  clock:
    cell: 0                                 # which cell of the specifier
    header: dt-bindings/clock/vendor,soc-rcc.h
    prefix: RCC_CLK_
    values:
      header: pbl/drivers/clk/soc.h
      prefix: SOC_CLK_

#define PBL_I2C_SOC_DEFINE(sym, _name, _base, _irq, _clock, _clock_hz, _pinctrl) \
  PBL_I2C_BUS_STATE_DEFINE(sym);                                                \
  static struct pbl_i2c_soc_state sym##_soc_state;                              \
  PBL_DEVICE_INSTANCE(sym, struct pbl_i2c_soc, struct pbl_i2c_bus, bus){        \
    .bus = PBL_I2C_BUS_INIT(sym, _name, &pbl_i2c_soc_ops, nullptr),             \
    ...                                                                         \
  };                                                                            \
  PBL_IRQ_CONNECT_NUM(_irq, CONFIG_I2C_SOC_IRQ_PRIO, pbl_i2c_soc_irq_handler, &sym##_inst, 0)

#include PBL_DT_INSTANCES(vendor_soc_i2c)

config I2C_SOC
    bool "Vendor SoC I2C controller"
    default DT_HAS_VENDOR_SOC_I2C_ENABLED

PBL_SENSOR_VENDOR_DEFINE(dt_sensor, ...);
PBL_DEVICE_DEPENDS(dt_sensor, &dt_sensor.dev, &dt_ldo1.dev, &dt_gpio0.dev, &dt_rcc.dev,
                   &dt_timer1_pwm.dev);

Using devices

Code reaches a labelled device as dt_<label>, declared in devicetree/devices.h with the type of its class:

#include <devicetree/devices.h>

pbl_display_clear(&dt_lcdc0);

Unlabelled devices can only be reached through other nodes, such as a sensor through its bus. Code that needs a kind of device rather than a particular one uses its role, such as DISPLAY; see Roles.

Flash partitions

The partitions of the board’s flash are a fixed-partitions node under the flash, as in Linux, each with a label:

partitions {
	compatible = "fixed-partitions";
	#address-cells = <1>;
	#size-cells = <1>;

	partition@20000 {
		label = "firmware-slot-0";
		reg = <0x20000 0x300000>;
	};
};

They become devicetree/partitions.h, with PART_<LABEL>_OFFSET, PART_<LABEL>_SIZE and PART_<LABEL> for each, as the C layouts of include/pbl/board/ give them for boards without a tree. CONFIG_BOARD_PARTITIONS_DT selects them, and pbl reads the generated file to find a partition.

Registers before devices

Code that runs before any device is up, as the SoC’s early init, its reset path or the kernel timer, takes the registers of the blocks it touches from the tree too. A *.regs.yaml next to it names their labels, and the Kconfig symbol of that code:

config: SOC_SF32LB52
labels: [hpsys_rcc, pmuc]

When the symbol is set, devicetree/regs.h has PBL_DT_REG_<LABEL> and PBL_DT_SIZE_<LABEL> for the first reg entry of each, translated through the ranges above as for instances. The node may be disabled, as its registers are there all the same. Only the labels listed get a constant: everything else reaches the tree through its instance.

Tests

The generator has unit tests, run on the host:

python3 -m pytest tools/devicetree/tests