/
Using Device-tree Overlay

Using Device-tree Overlay

Owned by Wells Lu
Jan 09, 2025
5 min read

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.

image-20250109-055824.png

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:

image-20250109-034038.png

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

Copying 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: