Using Device-tree Overlay
- Wells Lu
The document describes how to use the device-tree overlay feature in SP7350 platforms. Device-tree overlay feature allow for adding new nodes or modifying properties in the original device-tree without re-compiling the device-tree source of the board. This guide explains enabling the device-tree overlay feature in U-Boot, creating a device-tree overlay for the IMX219 camera, compiling it, and applying it via the uEnv.txt file for an SP7350 board booting from an SD card.
Table of Contents
Enabling Device-tree Overlay Support
To merge the base device-tree blob (DTB) with overlays in U-Boot, we need to enable "FDT library overlay support" in U-Boot. Run the make uconfig command in the project top folder. In the U-Boot menuconfig, navigate to “Library routines” → “Enable the FDT library overlay support” and enable it. Refer to the screenshot below for guidance.
Compile Device-tree with the -@ Switch
Both the base device-tree and overlays must be compiled using the -@ switch with the device-tree compiler (dtc) to include symbol information, enabling successful merging.
Note:
The -@ switch is available in dtc version 1.4.4 or newer.
Linux kernel versions 4.14 or later include a built-in dtc supporting the -@ switch.
Modify build/Makefile to include the -@ switch as shown below:
Device-tree Overlay Example
Device-tree overlays use a distinct syntax compared to standard device-trees. Refer to the Device-Tree Object Documentation for detailed syntax information.
When the device tree overlays were first proposed, their syntax was very special and hard to remember. Since version 1.5, the device tree compiler (dtc) supports a much more natural syntax for writing overlays. Below is an example of a device-tree overlay for the IMX219 camera using the new syntax:
This example shows us what is specific to device-tree overlay source code, compared to the normal device tree syntax:
Before any definition, include the /plugin/; statement.
Use absolute path from the root device (for example, &{/} in below example) if the nodes which you want to modify lack labels.
Use labels, such as &i2c3, &mipicsirx5 and &vin10 in below example, to modify properties, add or remove nodes and properties.
Example: sp7350-imx219.dtso
// SPDX-License-Identifier: (GPL-2.0 OR MIT)
// Install IMX219 at MIPI-RX5 using I2C3
/dts-v1/;
/plugin/;
&{/} {
imx219_vana_2v8: imx219_vana_2v8 {
compatible = "regulator-fixed";
regulator-name = "imx219_vana";
regulator-min-microvolt = <2800000>;
regulator-max-microvolt = <2800000>;
regulator-always-on;
};
imx219_vdig_1v8: imx219_vdig_1v8 {
compatible = "regulator-fixed";
regulator-name = "imx219_vdig";
regulator-min-microvolt = <1500000>;
regulator-max-microvolt = <1500000>;
regulator-always-on;
};
imx219_vddl_1v2: imx219_vddl_1v2 {
compatible = "regulator-fixed";
regulator-name = "imx219_vddl";
regulator-min-microvolt = <1200000>;
regulator-max-microvolt = <1200000>;
regulator-always-on;
};
};
&i2c3 {
status = "okay";
#address-cells = <1>;
#size-cells = <0>;
camera_5: imx219@10 {
compatible = "sony,imx219";
reg = <0x10>;
clocks = <&imx219_clk>;
VANA-supply = <&imx219_vana_2v8>;
VDIG-supply = <&imx219_vdig_1v8>;
VDDL-supply = <&imx219_vddl_1v2>;
//pinctrl-names = "default";
//pinctrl-0 = <&camera_5_pins>;
//power-gpios = <&pctl 21 GPIO_ACTIVE_HIGH>;
//reset-gpios = <&pctl 22 GPIO_ACTIVE_HIGH>;
port {
imx219_5: endpoint {
remote-endpoint = <&csi2_5>;
data-lanes = <1 2>;
clock-noncontinuous;
link-frequencies = /bits/ 64 <456000000>;
};
};
};
};
&mipicsirx5 {
status = "okay";
num_channels = <1>;
ports {
#address-cells = <1>;
#size-cells = <0>;
/* Input port node, sigle endpoint, connected to the CSI-2 transmitter */
port@0 {
reg = <0>;
/* MIPI CSI-2 bus endpoint */
csi2_5: endpoint {
remote-endpoint = <&imx219_5>;
bus-type = <4>;
clock-lanes = <0>;
data-lanes = <1 2>;
};
};
};
};
&vin10 {
status = "okay";
};Compiling Device-tree Overlay with -@ Switch
Compile the overlay using dtc with the -@ switch:
dtc -@ -I dts -O dtb -o sp7350-imx219.dtbo sp7350-imx219.dtsoCopying Device-tree Overlay to the SD card
Copy the resulting file sp7350-imx219.dtbo to the boot partition of your SD card.
Modifying uEnv.txt
Modify the uEnv.txt file to load and apply the device-tree overlay. Below are the changes:
Line 22-23: Load device-tree overlay ‘sp7350-imx219.dtb’ to memory address 1100000.
Line 24-25: Move base fdt to new memory address 1000000 for resizing.
Line 26: Resize the FDT to accommodate the device-tree overlay.
Line 27: Apply the device-tree overlay
Line 30-31: Replace the original sboot_kernel with the modified command to load the dtb at the new memory address.
Modified uEnv.txt:
#
# uEnv.txt for SP7350 (arm64)
#
KERNEL_IMG=uImage
sRpi_args=setenv filesize 0; fatsize $isp_if $isp_dev /cmdline.txt; if test $filesize != 0; then fatload $isp_if $isp_dev $addr_dst_dtb /cmdline.txt; raspb init $fileaddr $filesize; fi;
# bootargs
sbootargs=setenv bootargs console=ttyS0,115200 earlycon root=/dev/mmcblk1p2 rw rootwait $bootargs;
# load kernel
sload_kernel=echo "fatload $isp_if $isp_dev $addr_temp_kernel /$KERNEL_IMG"; fatload $isp_if $isp_dev $addr_temp_kernel /$KERNEL_IMG;
# verify kernel
sverify=echo "verify ${addr_temp_kernel} ${do_secure}"; verify ${addr_temp_kernel} ${do_secure};
# unzip kernel
sunzip_kernel=setexpr addr_temp_kernel ${addr_temp_kernel} + 0x40; setexpr addr_dst_kernel ${addr_dst_kernel} + 0x40; echo "unzip ${addr_temp_kernel} ${addr_dst_kernel}"; unzip ${addr_temp_kernel} ${addr_dst_kernel};
# Load and apply device-tree overlay
sdtoverlay=\
echo "fatload mmc 0 1100000 /sp7350-imx219.dtbo"; \
fatload mmc 0 1100000 /sp7350-imx219.dtbo; \
fdt addr $fdtcontroladdr; \
fdt move $fdtcontroladdr 1000000; \
fdt resize 1000; \
fdt apply 1100000;
# boot cmd
#sboot_kernel=echo "booti ${addr_dst_kernel} - ${fdtcontroladdr}"; booti ${addr_dst_kernel} - ${fdtcontroladdr};
sboot_kernel=run sdtoverlay; echo "booti ${addr_dst_kernel} - 1000000"; booti ${addr_dst_kernel} - 1000000;
# uenvcmd cmd
uenvcmd=run sload_kernel; run sbootargs; run sverify; run sunzip_kernel; run sboot_kernel;
#
# END
#Log of U-Boot
The logs below confirm successful loading and applying of the device-tree overlay:
U-Boot 2024.07-g180bebe6 (Jan 09 2025 - 13:58:52 +0800)
CONFIG_SYS_CACHELINE_SIZE: 64
Model: Sunplus SP7350 MCB
DRAM: 3.8 GiB (effective 4 GiB)
PLLA : 147456000 Hz
PLLC : 1500000000 Hz
PLLL3 : 1200000000 Hz
PLLD : 800000000 Hz
PLLH : 2150000000 Hz
PLLN : 500000000 Hz
PLLS : 2000000000 Hz
reset: reset@f8800004
Core: 331 devices, 20 uclasses, devicetree: separate
SPI: Manufacturer id = 0x00, Device id = 0x0000
MMC: sd: 0
Loading Environment from nowhere... OK
Disp: probe ...
Disp: init 1920x1080 settings
Disp: init lt8912b bridge ic
Disp: probe done
In: usbkbd,serial
Out: vidconsole,serial
Err: vidconsole,serial
Net: Invalid mac address from OTP[22:27] = 00:00:00:00:00:00!
Warning: stmmac@f8103000 (eth0) using random MAC address - a6:93:79:e8:8c:1c
eth0: stmmac@f8103000
starting USB...
Bus usb@f8102100: ehci_sunplus_probe.164, dev_name:usb@f8102100,port_num:0
after write usbruncmd,usbcmd:80b01,retry_times:0
USB EHCI 1.10
Bus usb@f8102080: ohci_sunplus_probe.51, dev_name:usb@f8102080,port_num:1
USB OHCI 1.0
Bus dwc3@f80a1000: Register 2000140 NbrPorts 2
Starting the controller
USB XHCI 1.10
scanning bus usb@f8102100 for devices... 1 USB Device(s) found
scanning bus usb@f8102080 for devices... 1 USB Device(s) found
scanning bus dwc3@f80a1000 for devices... 1 USB Device(s) found
scanning usb for storage devices... 0 Storage Device(s) found
Hit any key to stop autoboot: 0
[scr] bootcmd started
fa218008: 000000fe ....
[scr] Boot from SD Card
sd: 0
run sdcard_boot
1398 bytes read in 34 ms (40 KiB/s)
Loaded environment from uEnv.txt
Running uenvcmd ...
fatload mmc 0 0xFFFFFC0 /uImage
9587666 bytes read in 838 ms (10.9 MiB/s)
verify 0xFFFFFC0 0
unzip 10000000 2000000
Uncompressed size: 23435272 = 0x1659808
fatload mmc 0 1100000 /sp7350-imx219.dtbo
2486 bytes read in 35 ms (69.3 KiB/s)
Working FDT set to eeeef430
Working FDT set to 1000000
booti 2000000 - 1000000
## Flattened Device Tree blob at 01000000
Booting using the fdt blob at 0x1000000
Working FDT set to 1000000
Loading Device Tree to 00000000edecf000, end 00000000edee4fff ... OK
Working FDT set to edecf000
Starting kernel ...