Skip to main content

Device Tree

1. Introduction to Device Tree​

The Device Tree is a mechanism used in the Linux kernel to describe board-level hardware information. It is written in text format, typically using the .dts (Device Tree Source) or .dtsi (Device Tree Source Include) file extensions. The .dts file defines specific hardware device information, while the .dtsi file is used to extract common device or platform configurations that are referenced by .dts files.

For Luckfox Pico, the device tree files are located in the following directory of the SDK: luckfox-pico SDK/sysdrv/source/kernel/arch/arm/boot/dts

During the build process, .dts and .dtsi files are compiled into binary .dtb (Device Tree Blob) files. At system startup, U-Boot loads the .dtb file into memory. The kernel then parses this file during boot to initialize hardware, load drivers, and register device nodes based on the hardware information it contains.

It is important to note that starting from Linux kernel 4.4, a Dynamic Device Tree mechanism was introduced. This allows parts of the .dtb configuration to be modified or overridden at runtime. Kernel drivers can adapt dynamically to the new configuration instead of relying solely on the statically loaded .dtb during boot.

2. Device Tree Configuration Overview​

During the image build phase for Luckfox Pico, you must first select the appropriate board support file:

./build.sh lunch

  • The board support file information is symbolically linked to <luckfox-pico SDK>/.BoardConfig.mk.

  • The board support file defines the .dts file corresponding to the specific Luckfox Pico model. For models with common hardware designs, their .dts files may include a shared .dtsi file to simplify centralized configuration management.

  • The .dts and .dtsi files corresponding to different models are listed below:

    型号.dts.dtsi
    Luckfox Picorv1103g-luckfox-pico.dtsrv1103-luckfox-pico-ipc.dtsi
    Luckfox Pico mini arv1103g-luckfox-pico-mini-a.dtsrv1103-luckfox-pico-ipc.dtsi
    Luckfox Pico mini brv1103g-luckfox-pico-mini-b.dtsrv1103-luckfox-pico-ipc.dtsi
    Luckfox Pico plusrv1103g-luckfox-pico-plus.dtsrv1103-luckfox-pico-ipc.dtsi
    Luckfox Pico pro/maxrv1106g-luckfox-pico-pro-max.dtsrv1106-luckfox-pico-pro-max-ipc.dtsi
    Luckfox Pico ultrarv1106g-luckfox-pico-ultra.dtsrv1106-luckfox-pico-ultra-ipc.dtsi
    Luckfox Pico ultra Wrv1106g-luckfox-pico-ultra-w.dtsrv1106-luckfox-pico-ultra-ipc.dtsi
    Luckfox Pico Pi A/Brv1106g-luckfox-pico-pi.dtsrv1106-luckfox-pico-pi-ipc.dtsi
    Luckfox Pico Pico Pi A/B Wrv1106g-luckfox-pico-pi-w.dtsrv1106-luckfox-pico-pi-ipc.dtsi
    Luckfox-Pico-86-Panel-0208/0408rv1106g-luckfox-pico-86panel.dtsrv1106-luckfox-pico-86panel-ipc.dtsi
    Luckfox-Pico-86-Panel-1208/1408rv1106g-luckfox-pico-86panel-w.dtsrv1106-luckfox-pico-86panel-ipc.dtsi

3. Device Tree Configuration​

3.1 Device Tree File Structure​

For Luckfox Pico, the basic device tree configurations related to the RV1103 / RV1106 chips—such as rv1106.dtsi, rv1106-pinctrl.dtsi, etc.—are provided by Rockchip. Based on the hardware resources available on the Luckfox Pico, the default configurations are set in .dtsi files, while model-specific hardware information is defined in .dts files.

  • The configurations in .dts files have the highest priority and can override settings in the .dtsi files. You can reference nodes from .dtsi and either modify their properties or recreate them entirely.
  • For easier editing, the .dts file corresponding to the selected board support package is symlinked to <luckfox-pico SDK>/config/dts_config after running ./build.sh. Normally, you only need to edit the .dts file to configure hardware features—.dtsi files should not be modified.

3.2 常用配置​

3.2.1 GPIO Configuration​

Pins are configured as GPIO by default. The high or low output levels can be set using sysfs, but default pull-up or pull-down configurations must be done through the device tree or by writing to registers. To configure gpio1 pc7 as a pull-up by default, add the following to <luckfox-pico SDK>/config/dts_config:

/{
    /*-------------------------------------------------------*/
    /*----------------------other data-----------------------*/
    /*-------------------------------------------------------*/

    gpio1pc7:gpio1pc7 {
        compatible = "regulator-fixed";
        pinctrl-names = "default";
        pinctrl-0 = <&gpio1_pc7>;
        regulator-name = "gpio1_pc7";
        regulator-always-on;
    };  
};

&pinctrl {
    gpio1-pc7 {
        gpio1_pc7:gpio1-pc7 {
            rockchip,pins = <1 RK_PC7 RK_FUNC_GPIO &pcfg_pull_up>;
        };
    };
};
  • gpio1pc7 represents the newly created node, which must be placed under the existing root node; a new root node cannot be created independently.
  • other data represents the default configuration for Luckfox Pico's model and compatible properties.
  • pcfg_pull_up represents the default pull-up, pcfg_pull_down represents the default pull-down, and pcfg_pull_none represents no pull-up or pull-down.

3.2.2 PWM Configuration​

PWM functionality can only be used by one pin at a time. For example, the pins corresponding to PWM1M0 and PWM1_M1 cannot be used simultaneously. The pin usage is controlled through the pinctrl attribute. To enable PWM1M0, add the following to <Luckfox-pico SDK>/config/dts_config:

&pwm1 {
    status = "okay";
    pinctrl-0 = <&pwm1m0_pins>;
};
  • &pwm1 refers to the node, based on rv1106.dtsi.
  • &pwm1m0_pins refers to the pinctrl node containing the pin and multiplex mode information, based on rv1106-pinctrl.dtsi.
  • Since PWM's frequency and duty cycle can be set using sysfs, the device tree configuration for PWM only enables the feature.

3.2.3 UART Configuration​

UART functionality can only be used by one set of pins at a time. For example, the pin sets for UART1M0 and UART1M1 cannot be used together, and the pins within the set cannot be split. Pin usage is controlled through the pinctrl attribute. To enable UART1M0, add the following to <Luckfox-pico SDK>/config/dts_config:

&uart1 {
    status = "okay";
    pinctrl-0 = <&uart1m0_xfer>;
};
  • &uart1 refers to the node, based on rv1106.dtsi.
  • &uart1m0_xfer refers to the pinctrl node containing pin and multiplex mode information, based on rv1106-pinctrl.dtsi.
  • If flow control is needed, ensure the corresponding UART group has flow control pins, and add the necessary ctsn and rtsn pin information to the pinctrl-0 attribute.

3.2.4 I2C Configuration​

I2C functionality can only be used by one set of pins at a time. For example, I2C0M0 and I2C0M1 cannot be used simultaneously, and the pins within the set cannot be split. Pin usage is controlled through the pinctrl attribute. To enable I2C0M0, add the following to <Luckfox-pico SDK>/config/dts_config:

&i2c0 {
    status = "okay";
    pinctrl-0 = <&i2c0m0_xfer>;
    clock-frequency = <100000>;
};
  • &i2c0 refers to the node, based on rv1106.dtsi.
  • &i2c0m0_xfer refers to the pinctrl node containing pin and multiplex mode information, based on rv1106-pinctrl.dtsi.
  • The clock-frequency attribute sets the I2C clock frequency in Hz. You can adjust this according to actual needs, with the default I2C frequency set to 100000 (100kHz) in standard mode.

3.2.5 SPI Configuration​

SPI functionality can only be used by one set of pins at a time. For example, SPI0M0 and SPI0M1 cannot be used together, and the pins within the set cannot be split. However, not all pins within the same SPI group must be used (e.g., only enabling CLK and MISO). Pin usage is controlled through the pinctrl attribute. If only the CLK and MOSI pins are to be enabled for SPI0M0, add the following to <Luckfox-pico SDK>/config/dts_config:

&spi0 {
    status = "okay";
    pinctrl-0 = <&spi0m0_clk &spi0m0_mosi>;
    spidev@0 {
        status = "okay";
        compatible = "rockchip,spidev";
        spi-max-frequency = <50000000>;
        reg = <0>;
    };
    fbtft@0 {
        status = "disabled";
    };
};

  • &spi0 refers to the node, based on rv1106.dtsi.

  • pinctrl-0 refers to the node in the corresponding Luckfox Pico model's .dtsi file. The distinction from rv1106-pinctrl.dtsi is that the pins are separated for easier configuration.

  • The spi-max-frequency attribute sets the SPI clock frequency in Hz. You can adjust this according to actual needs, with the default SPI frequency set to 50 MHz.

  • spidev@0 refers to a child node in .dtsi used for SPI communication with the main device.

  • fbtft@0 refers to an FB device node in .dtsi, which should not be enabled together with spidev@0. If the fbtft@0 node does not exist in the corresponding .dtsi, this configuration will have no effect.

  • The pinctrl/spi0 node configures the pins spi0m0_clk, spi0m0_mosi, spi0m0_miso, and spi0m0_cs0, but only spi0m0_clk and spi0m0_mosi are used. Unused pins will not be enabled for SPI functionality.

    /* This pinctrl node has already been defined in the .dtsi file and does not need to be added in the .dts file */
    &pinctrl {
        spi0 {
            spi0m0_clk: spi0m0-clk {
                rockchip,pins = <1 RK_PC1 4 &pcfg_pull_none>;
            };
            spi0m0_mosi: spi0m0-mosi {
                rockchip,pins = <1 RK_PC2 6 &pcfg_pull_none>;
            };
            spi0m0_miso: spi0m0-miso {
                rockchip,pins = <1 RK_PC3 6 &pcfg_pull_none>;
            };
            spi0m0_cs0: spi0m0-cs0 {
                rockchip,pins = <1 RK_PC0 4 &pcfg_pull_none>;
            };
        };
    };

3.2.6 RGB Configuration​

Luckfox Pico Ultra / Ultra W supports driving an RGB interface LCD screen, which requires multiple pins. Ensure that all the required pins are not configured for other functions before enabling the RGB interface. To configure the Luckfox Pico Ultra to drive the LF40-720720-ARK screen, add the following to <Luckfox-pico SDK>/config/dts_config:

&rgb{
    status = "okay";
    pinctrl-0 = <&lcd_pins>;
};

&panel{
    display-timings {
        timing0:timing0 {
            clock-frequency = <30000000>； 
            hactive = <720>;
            vactive = <720>;
            hback-porch = <44>;
            hfront-porch = <46>;
            vback-porch = <18>;
            vfront-porch = <16>;
            hsync-len = <2>;
            vsync-len = <2>;
            hsync-active = <0>;
            vsync-active = <0>;
            de-active = <0>;
            pixelclk-active = <1>;
        };
    };
};

  • &rgb refers to the referenced node, with the default attribute configuration found in the corresponding Luckfox Pico model's .dtsi and rv1106.dtsi. If the RGB interface is not needed, change the status attribute to disabled.
  • &timing0 refers to the timing information of the screen, which should be configured according to the screen's specifications.
  • For more configuration details, refer to the RGB section.

3.2.7 TouchScreen Configuration​

Luckfox Pico Ultra / Luckfox Pico Ultra W support controlling the touchscreen via the I2C interface. A sub-node needs to be added to the I2C3 node to configure the touchscreen. For example, to configure the Luckfox Pico Ultra using I2C3 to drive the GT911 touchscreen chip on the LF40-720720-ARK screen, add the following to <Luckfox-pico SDK>/config/dts_config:

&i2c3 {
    status = "okay";
    pinctrl-0 = <&i2c3m2_xfer &tp_rst &tp_irq>;
    clock-frequency = <100000>;
    GT911:touchscreen {
      compatible = "goodix,gt911";
      reg = <0x14>;

      interrupt-parent = <&gpio0>;
      interrupts = <RK_PA3 IRQ_TYPE_EDGE_FALLING>;

      reset-gpios = <&gpio0 RK_PA4 GPIO_ACTIVE_LOW>;
      pinctrl-names = "default";
    };
};

  • GT911:touchscreen represents the created touchscreen sub-node. The related attribute configurations should be set according to the touchscreen specifications and the matching Goodix driver.

  • pinctrl-0 configures the I2C pins needed for the touchscreen, as well as the reset pin (tp_rst) and touch interrupt pin (tp_irq). The referenced nodes are configured in the corresponding Luckfox Pico model's .dtsi file.

  • reg configures the touchscreen's I2C device address.

  • pinctrl/touchscreen configures the tp_rst and tp_irq pins. Ensure these pins are not reused for other functions or occupied by other drivers.

```c++
/* The pinctrl node creation has already been implemented in the dtsi file, so it is not needed in the dts */
 &pinctrl {
    touchscreen {
        tp_rst:tp-rst {
            rockchip,pins = <0 RK_PA4 RK_FUNC_GPIO &pcfg_pull_up>;
        };
 
        tp_irq:tp-irq {
            rockchip,pins = <0 RK_PA3 RK_FUNC_GPIO &pcfg_pull_none>;
        };
    };    
 };
```
  • For more configuration details, refer to the RGB section.

3.2.8 USB Configuration​

Luckfox Pico's USB is set to peripheral mode by default, allowing the USB to act as a device for ADB terminal access and as an RNDIS device for LAN access on the computer. When in peripheral mode, plugging in devices like a USB flash drive or keyboard will not have any effect. To configure the USB as host mode for recognizing attached peripherals, add the following to <Luckfox-pico SDK>/config/dts_config:

&usbdrd_dwc3 {
    status = "okay";
    dr_mode = "host";
};
  • &usbdrd_dwc3 refers to the node that configures the USB mode. Other dependent USB nodes are enabled by default, with the source and default configuration found in rv1106.dtsi and the corresponding Luckfox Pico model's .dtsi file.
  • The dr_mode attribute configures the USB mode. host represents host mode, and peripheral represents device mode.

3.2.9 CSI Configuration​

Luckfox Pico's CSI is enabled by default. On Luckfox Pico / Mini / Plus / Pro / Max, you can control the CSI camera by simply inserting the CSI camera. On Luckfox Pico Ultra / Ultra W, since I2C4 also brings out other pin groups besides CSI, you need to modify the pinctrl-0 attribute of I2C4 to ensure the CSI interface works properly. To enable the CSI interface on Luckfox Pico Ultra, add the following to <Luckfox-pico SDK>/config/dts_config:

&csi2_dphy_hw {
    status = "okay";
};

&i2c4 {
    status = "okay";
    clock-frequency = <400000>;
    pinctrl-0 = <&i2c4m2_xfer>;
};
  • &csi2_dphy_hw refers to the CSI2 D-PHY node, which is the underlying node for the CSI interface. If this node is not enabled, the property settings of other nodes will be ineffective.
  • &i2c4 refers to the I2C4 node. The sub-nodes related to the sensor are enabled in the corresponding .dtsi file, with support for the SC3336 sensor enabled by default.
  • pinctrl-0 is configured by default as <&i2c4m0_xfer &i2c4m1_xfer &i2c4m2_xfer> on Luckfox Pico Ultra to ensure complete device tree information in the final compiled DTB. This configuration in the .dts file will override the configuration in the .dtsi file to ensure the CSI is enabled correctly.

3.2.10 SDMMC Configuration​

Luckfox Pico / Mini / Plus / Pro / Max have TF card slots with SDMMC enabled by default. If the system uses an SD card as the storage medium, disabling SDMMC could prevent the system from booting. Only Luckfox Pico Plus has the SDMMC pins exposed, and when Luckfox Pico Plus uses SPI-NAND as the storage medium, SDMMC can be disabled and the pins can be repurposed for other functions. The SDMMC configuration is already added by default in <Luckfox-pico SDK>/config/dts_config:

&sdmmc {
    max-frequency = <50000000>;
    no-sdio;
    no-mmc;
    bus-width = <4>;
    cap-mmc-highspeed;
    cap-sd-highspeed;
    disable-wp;
    pinctrl-names = "default";
    pinctrl-0 = <&sdmmc0_clk &sdmmc0_cmd &sdmmc0_det &sdmmc0_bus4>;
    status = "okay";
};
  • To disable SDMMC, simply change the status attribute to disabled.