El Device Tree: describir el hardware que no se descubre

Si el hardware embebido es mudo y su descripción tiene que vivir en algún sitio, la pregunta es dónde. La respuesta que ganó no es el código, son los datos: el device tree, un árbol de nodos y propiedades que describe la topología del hardware de una placa sin una sola línea ejecutable. Nació de una crisis concreta —el caos de miles de board files de ARM— y se convirtió en el lenguaje con el que hoy se describe casi todo SoC. Un archivo .dts no es un programa: es un mapa del silicio que el kernel lee al arrancar.

Por qué existe: la rebelión contra los board files

Hacia 2011 el árbol de ARM en el kernel era un vertedero. Cada placa —y había miles— aportaba un archivo .c en arch/arm/mach-*/ con sus direcciones, sus IRQ y su cableado, todo compilado dentro del binario. Añadir una placa era añadir código; cambiar una dirección era recompilar el kernel. Linus Torvalds estalló públicamente contra aquel diluvio de placas, y la comunidad adoptó una idea que ya usaban PowerPC y SPARC: describir el hardware en un archivo de datos externo, no en código. Ese formato es el device tree, heredado de Open Firmware.

La consecuencia es un cambio de naturaleza. La descripción del hardware deja de ser lógica compilada y pasa a ser un dato que el kernel interpreta en tiempo de arranque. Un mismo binario del kernel sirve para decenas de placas distintas; lo que cambia entre ellas es el blob de device tree que se le entrega. La descripción se separó del código.

Anatomía de un .dts

Un device tree es un árbol. Tiene un nodo raíz, y de él cuelgan nodos hijos que representan buses y dispositivos, cada uno con propiedades de tipo clave y valor. Este es un fragmento realista de la descripción de un SoC:

/dts-v1/;

/ {
	compatible = "acme,board-evk", "acme,soc-8";
	#address-cells = <1>;
	#size-cells = <1>;

	soc {
		compatible = "simple-bus";
		#address-cells = <1>;
		#size-cells = <1>;
		ranges;

		uart0: serial@50000000 {
			compatible = "acme,uart-9000";
			reg = <0x50000000 0x1000>;
			interrupts = <0 42 4>;
			clocks = <&clk_uart>;
			status = "okay";
		};
	};
};

Léelo despacio, porque cada pieza tiene un papel:

• El nombre de nodo y su dirección de unidad. serial@50000000 es un nombre genérico (serial) seguido de arroba y la dirección donde vive. Esa dirección de unidad debe coincidir con la primera celda de reg.
• compatible. La propiedad más importante: una lista de cadenas fabricante,modelo que identifica el hardware. Es la clave con la que el kernel encontrará el driver (nivel 29.4). Se lee de la más específica a la más genérica.
• reg. El rango de registros: aquí 0x50000000 de base y 0x1000 de tamaño. Cuántas celdas ocupa la base y cuántas el tamaño lo fijan #address-cells y #size-cells del nodo padre.
• interrupts. La descripción de la línea de interrupción, en el formato que imponga el controlador de interrupciones padre (aquí tres celdas: tipo, número y flags).
• status. okay habilita el nodo; disabled hace que el kernel lo ignore, útil para apagar un periférico en una variante de placa.

La etiqueta uart0: es un rótulo (label) que permite referenciar el nodo desde otro sitio con &uart0, el mecanismo de los phandle que conecta un dispositivo con su reloj, su GPIO o su controlador de interrupciones.

Phandles y celdas: cómo se enlazan los nodos

Un árbol de nodos sueltos no describiría hardware real, donde una UART necesita un reloj y un controlador de interrupciones que viven en otros nodos. El device tree los conecta con phandles: una referencia a otro nodo a través de su rótulo. Y para saber cuántos números acompañan a cada referencia usa las propiedades #*-cells, que cada proveedor declara.

clk_uart: clock@40000000 {
	compatible = "fixed-clock";
	#clock-cells = <0>;               /* al referenciarme no hace falta indice */
	clock-frequency = <24000000>;
};

intc: interrupt-controller@48000000 {
	compatible = "acme,intc";
	interrupt-controller;
	#interrupt-cells = <3>;           /* cada interrupts lleva 3 celdas */
	reg = <0x48000000 0x1000>;
};

uart0: serial@50000000 {
	compatible = "acme,uart-9100";
	reg = <0x50000000 0x1000>;
	interrupt-parent = <&intc>;       /* de quien cuelga mi interrupcion */
	interrupts = <0 42 4>;
	clocks = <&clk_uart>;             /* mi reloj, por phandle */
};

Aquí clocks = <&clk_uart> es un phandle al nodo del reloj; como este declara #clock-cells = <0>, la referencia no lleva más números. La propiedad interrupt-parent apunta al controlador que interpreta mi línea, y como declara #interrupt-cells = <3>, mi interrupts lleva exactamente tres celdas. Esta gramática de celdas es lo que permite que el kernel resuelva, en el arranque, qué reloj alimenta qué dispositivo y qué controlador atiende qué interrupción, sin saber nada de esta placa en particular.

Del .dts al .dtb: fuente, blob y kernel

El .dts es texto para humanos; el kernel consume un binario compacto llamado FDT (Flattened Device Tree) o .dtb. El compilador es dtc, y vive en el propio árbol del kernel:

# compilar la fuente legible a un blob binario que el kernel entiende
dtc -I dts -O dtb -o acme-board.dtb acme-board.dts

# el proceso inverso: descompilar un blob para inspeccionarlo
dtc -I dtb -O dts acme-board.dtb

En el arranque, el bootloader (U-Boot, o UEFI en ARM64) carga ese .dtb en memoria y le pasa al kernel un puntero a él. El kernel lo desdobla muy temprano, antes incluso de tener memoria dinámica completa, y a partir del árbol crea un struct platform_device por cada nodo describible, rellenando sus recursos con lo que dicen reg e interrupts. Después, ya en marcha, expone el árbol vivo en el sistema de archivos:

/proc/device-tree/                       el arbol tal como lo ve el kernel
/sys/firmware/devicetree/base/           la misma vista, en sysfs
/sys/firmware/fdt                         el blob crudo que recibio del bootloader

flowchart LR
DTS[archivo dts legible] -->|dtc| DTB[blob dtb binario]
DTB -->|el bootloader lo carga y lo pasa| KERNEL[Kernel arranca]
KERNEL -->|desdobla el FDT| NODOS[Un platform_device por nodo]
NODOS -->|reg e interrupts| REC[Recursos MEM e IRQ]