How to use non-trivial device tree overlays?

Which system do you use? Android, Ubuntu, OOWOW or others?

Android 11

Which version of system do you use? Please provide the version of the system here:


Please describe your issue below:

The SDK contains a trivial device tree overlay (DTBO_DEVICETREE=android_overlay_dt) that is compiled with device/khadas/common/kernelbuild/ and applied during u-boot (androidboot.dtbo_idx=0)

BUT, modifying the device tree overlay to contain something non-trivial like this:


/ {
    fragment@0 {
        // absolute path
        __overlay__ {

            status_leds {
                compatible = "gpio-leds";
                my_led {
                    //gpios = <&gpio GPIOY_8 GPIO_ACTIVE_LOW>;
                    gpios = <&gpio 0x89 0x01>;
                    default-state = "keep";

results in the following output in the console during boot:

Apply dtbo 1
failed on fdt_overlay_apply(): FDT_ERR_NOTFOUND
base fdt does did not have a /__symbols__ node
make sure you've compiled with -@
   Uncompressing Kernel Image ... OK
   Loading Ramdisk to 3e94a000, end 3f7ff4ea ... OK
libfdt fdt_check_header(): FDT_ERR_BADMAGIC
[rsvmem] fdt addr error.
ERROR: image is not a fdt - must RESET the board to recover.
FDT creation failed! hanging...### ERROR ### Please RESET the board ###

I am assuming the problem is the gpio references into mesont7.dtsi definitions. kvim4.dts and kvim4n.dts base device trees are built by the SDK as default. Decompiling the kvim4.dtb does not show any __symbols__ node. How can this be solved?

Building the Linux kernel with modified DTC_FLAGS, seems to solve the issue, but is there a more correct solution? I didn’t see the same improvement when adding CONFIG_OF_OVERLAY=y to the kernel config

-    ./mk kvim4 -v 5.4 -j$NPROC
+    DTC_FLAGS=-@ ./mk kvim4 -v 5.4 -j$NPROC

Hello @xavier

@william.lin will help you then.

How did you update the dtbo file. Reburning the dtbo image (dtbo.img) or other ?

Yes, I build all (bootloader, kernel, Android) from source and flash with burn-tool.

I have not found a way to build and flash only dtbo.img…

Also, in case C-style #include are used in the device tree overlay, then the overlay needs to be preprocessed before compiled by dtc in

DTCPPTOOL=“${CC} -E -P -nostdinc -I ${ROOT_DIR}/common/include/ -I ${ROOT_DIR}/arch -undef -x assembler-with-cpp”
${DTCPPTOOL} ${src_overlay} -o ${tmp_overlay}
${DTCTOOL} -@ -I dts -O dtb -o ${dst_overlay} ${tmp_overlay}

Currently, the Android code released by khadas does not support this feature.
Our team is evaluating this feature and we may be able to support it in the future version.

I found a related proposed kernel patch+discussion on this issue:

Seems like invoking make with DTC_FLAGS=-@ is the way to go. Also Linux kernel mainline’s scripts/Makefile.lib has not changed with respect to this (as of 6.10-rc6)

So just to be clear (for other readers), the patches above in this thread enable non-trivial device tree overlays to be used.