One SoC file, one board file, and what happens where they meet

composition

Who includes whom

Four source files, one flattened tree, and a second device tree entirely — U-Boot’s — that runs first and leaves the pin multiplexer in a state the kernel simply inherits. Our board file is a third sibling of the two reference boards, not a modification of either.

census

What the SoC file declares, by status

Fifty-six hand-written nodes: forty-seven at the top level plus the nine children of sysctl and security. The interesting split is by status — nineteen sit disabled waiting for a board to claim them, twenty-five are switched on unconditionally, and twelve carry no status at all, which in device-tree semantics means enabled.

After a board file has had its say the flattened tree is 234 nodes: 184 okay, 11 still disabled. Those eleven are uart1, uart2, uart4, i2c0–i2c2, all three SPI controllers and mipi1/mipi2: everything nobody claimed. Anything this board needs from that list is a node we would have to enable ourselves, and the charger, the fuel gauge and the LoRa radio are all in it.

• status = "okay" in k230.dtsi
• no status property — enabled by default
• status = "disabled" — a board must opt in
• opted in by the board file

mechanism

How an override actually resolves

A board file does not copy a node. It writes &label { … }, which the compiler resolves to whichever node carries that label anywhere in the included tree, then merges the properties in: later assignment wins, everything unmentioned survives.

taxonomy

Seven things a board file does

Read against the two reference boards and our own, every edit falls into one of these seven. There is no eighth kind, which is a useful thing to know before writing a board file.

&uart0 {
    status = "okay";
};

&mmc_sd0 {
    status = "okay";
    no-1-8-v;
    rx_delay_line = <0x0d>;
    tx_delay_line = <0xc0>;
};

&i2c3 {
    status = "okay";
    touchscreen@5d {
        compatible = "goodix,gt9895";
        reg = <0x5d>;
        reset-gpios = <&gpio0_ports 24 GPIO_ACTIVE_LOW>;
        interrupt-parent = <&gpio0_ports>;
        interrupts = <23 IRQ_TYPE_EDGE_FALLING>;
    };
};

&mipi0 {
    // set to csi2
    id = <2>;
    reg = <0x0 0x9000a800 0x0 0x800>;
    interrupts = <121 IRQ_TYPE_LEVEL_HIGH>;
    resets = <&sysctl_reset K230_RESET_CSI2_…>,
             <&sysctl_reset K230_RESET_M2_…>;
};

&dsi {
    ports {
        port@1 {
            reg = <1>;
            dsi_out_rm69a10: endpoint {
                remote-endpoint = <&rm69a10_in>;
            };
        };
    };
};

/ {
    model = "LILYGO T-Display-K230";
    compatible = "lilygo,t-display-k230",
                 "canaan,canmv-k230",
                 "canaan,kendryte-k230";
    aliases { serial3 = &uart3; mmc0 = &mmc_sd0;
              mmc1 = &mmc_sd1; i2c0 = &i2c4; i2c1 = &i2c3; };
    chosen { stdout-path = "serial0:115200n8"; };
    ddr: memory@0 {
        device_type = "memory";
        reg = <0x0 0x0 0x0 0x40000000>;   // 1 GiB
    };
    sound { compatible = "canaan,k230-audio-inno"; … };
};

#include "k230.dtsi"
#include "display-rm69a10-568x1232.dtsi"

// …and later, supply the pins the fragment
// declared but deliberately left off the panel node:
&lcd {
    dsi_reset-gpios      = <&gpio0_ports 22 GPIO_ACTIVE_HIGH>;
    backlight_gpio-gpios = <&gpio0_ports 25 GPIO_ACTIVE_HIGH>;
};

the real thing

The board file we actually wrote

An earlier version of this note carried a sketch of what a T-Display board file might look like, with a Wi-Fi power sequence and a bus-width override in it, and a footnote saying it had never been compiled. The file below is the one in the repository. It compiles against the real k230.dtsi, every node was verified present in the output rather than assumed, and the two guessed-at Wi-Fi edits are not in it.

// nix/dts/k230-tdisplay.dts — compiles, and booted Linux on
// 2026-09-20. The panel it describes has still never lit.

/dts-v1/;

#include "k230.dtsi"
#include "display-rm69a10-568x1232.dtsi"          // ours

/ {
    model = "LILYGO T-Display-K230";
    compatible = "lilygo,t-display-k230", "canaan,canmv-k230",
                 "canaan,kendryte-k230";

    aliases {
        serial3 = &uart3;
        mmc0 = &mmc_sd0;   // the RTL8189FTV, over SDIO
        mmc1 = &mmc_sd1;   // the TF card, and the boot device
        i2c0 = &i2c4; i2c1 = &i2c3;
    };

    chosen { stdout-path = "serial0:115200n8"; };   // ttyS0, not ttyS1
    ddr: memory@0 { device_type = "memory"; reg = <0x0 0x0 0x0 0x40000000>; };
    sound { compatible = "canaan,k230-audio-inno"; … };
};

&uart0 { status = "okay"; };                        // CH342 ch0 — console
&uart3 { status = "okay"; };                        // CH342 ch1
&usb0  { status = "okay"; };
&usb1  { status = "okay"; };

&mmc_sd1 { status = "okay"; no-1-8-v; cap-sd-highspeed; mshc_ctrl_r = <0x00>; };

&mmc_sd0 {                                          // carried over verbatim
    status = "okay"; no-1-8-v;
    rx_delay_line = <0x0d>; tx_delay_line = <0xc0>;
};
// NOT WRITTEN — no mmc-pwrseq and no regulator, so nothing asserts IO45
//   and the radio stays unpowered under Linux exactly as it does under
//   RT-Smart. A known gap, left visible rather than guessed at.

&i2c3 {
    status = "okay";
    touchscreen@5d {                              // the reference has ft5306@38
        compatible = "goodix,gt9895";              // no driver matches this, anywhere
        reg = <0x5d>;
        reset-gpios = <&gpio0_ports 24 GPIO_ACTIVE_LOW>;
        interrupt-parent = <&gpio0_ports>;
        interrupts = <23 IRQ_TYPE_EDGE_FALLING>;
    };
};
&i2c4 { status = "okay"; };

&mipi0 { /* re-pointed to CSI-2, exactly as the reference does */ };

// NOT WRITTEN — no LT9611 node. The non-LCD reference gives it
//   gpio0_ports 24 and 23, which on this board are the touch controller's.
// NOT WRITTEN — BQ25896, BQ27220, SX1262/LR2021: bus and chip-select unread.

&lcd {                                              // the label on our panel node
    dsi_reset-gpios      = <&gpio0_ports 22 GPIO_ACTIVE_HIGH>;
    backlight_gpio-gpios = <&gpio0_ports 25 GPIO_ACTIVE_HIGH>;
};