Compile and verify

You can use device tree compiler (DTC) to compile the device tree source (DTS) files. However, before applying the overlay device tree (DT) on the target main DT, you should also verify the result by simulating the behavior of the device tree overlay (DTO).

Compile with DTC

When using dtc to compile .dts, you must add option -@ to add a __symbols__ node in the resulting .dtbo. The __symbols__ node contains a list of all nodes that are marked with a label, which the DTO library can use for references.

Sample command to build main DT .dts:

dtc -@ -O dtb -o my_main_dt.dtb my_main_dt.dts

Sample command to build the overlay DT .dts:

dtc -@ -O dtb -o my_overlay_dt.dtbo my_overlay_dt.dts

Verify DTO results on the host

Verification can help you identify errors that might occur when placing the overlay DT on the main DT. Before updating the target, you can verify the result of overlaying DT on the host by simulating the behavior of DTO using /include/ in .dts.

Figure 1. Use syntax /include/ to simulate DTO on the host.

  1. Create a copy of the overlay .dts. In the copy, remove the first line header. Example: 
    /dts-v1/;
/plugin/;
    Save the file as my_overlay_dt_wo_header.dts (or any filename you want).
  2. Create a copy of the main .dts. In the copy, after the last line, append the include syntax for the file you created in step 1. For example: 
    /include/ "my_overlay_dt_wo_header.dts"
    Save the file as my_main_dt_with_include.dts (or any filename you want).
  3. Use dtc to compile my_main_dt_with_include.dts to get the merged DT, which should be the same result as DTO. For example: 
    dtc -@ -O dtb -o my_merged_dt.dtb my_main_dt_with_include.dts
  4. Use dtc to dump my_merged_dt.dto. 
    dtc -O dts -o my_merged_dt.dts my_merged_dt.dtb

Verify DTO in Android 9

Android 9 requires a device tree blob overlay (DTBO) partition. To add nodes or make changes to the properties in the SoC DT, the bootloader must dynamically overlay a device specific DT over the SoC DT.

Indicate applied overlays

To enable the Vendor Test Suite (VTS) to assess the correctness of overlay app, vendors must add a new kernel command line parameter androidboot.dtbo_idx that indicates the overlays selected from the DTBO partition. In Android 12 using kernel version 5.10 or greater, this parameter passes through bootconfig. For example, the parameter androidboot.dtbo_idx=x,y,z reports x, y and z as the zero-based indices of the DTOs from the DTBO partition applied (in that order) by the bootloader to the base DT.

Overlays can apply to nodes from the main DT or add new nodes, but can't refer to a node added in a previous overlay. This restriction is necessary because the overlay app doesn't merge the overlay symbol table with the main DT symbol table (not merging avoids conflicts in symbol names and complication of dependencies between overlays).

Example: Invalid overlays

In this example, overlay_2.dts refers to node e , which was added by overlay_1.dts. After overlay_1 is applied to the main DT, if an attempt is made to apply overlay_2 to the resultant DT, the overlay app fails with an error that the symbol e isn't present in the symbol table for the base DT.

main.dts overlay_1.dts overlay_2.dts 
[main.dts]

/dts-v1/;

/ {
  a: a {};
  b: b {};
  c: c {};
};

[overlay_1.dts]

/dts-v1/;
/plugin/;

&b { ref1 =  <&a>;
    e: e {
        prop = <0x0a>;
        phandle = <0x04>;
    };
};

[overlay_2.dts]

/dts-v1/;
/plugin/;

/* invalid! */
&e {
    prop = <0x0b>;
};

Example: Valid overlays

In this example, overlay_2.dts refers only to node b from the main DTS. When overlay_1 is applied to the base DT, then followed by the app of overlay_2, the value of property prop in node e (set by overlay_1.dts) is overwritten by the value set by overlay_2.dts.

main.dts overlay_1.dts overlay_2.dts 
[final.dts]

/dts-v1/;

/ {
  a: a {};
  b: b {};
  c: c {};
};

[overlay_1.dts]

/dts-v1/;
/plugin/;


&b { ref1 =  <&a>;
     e {
          prop = <0x0c>;
      };
};

[overlay_2.dts]

/dts-v1/;
/plugin/;

/* valid */
&b { ref1 =  <&c>;
     e {
          prop = <0x0d>;
      };
};

Implement the DTBO partition

To implement the required DTBO partition, ensure the bootloader can do the following:

  1. Identify the board it is running on and select the corresponding overlays to be applied.
  2. Append the androidboot.dtbo_idx parameter to the kernel command line.
    • The parameter must indicate, the zero-based indices of the DTOs from the DTBO partition image it applied to the base DT (in the same order).
    • The indices must refer to the position of the overlay in the DTBO partition.

For details on the structure of the DTBO partition, refer to Device tree overlays.

Validate the DTBO partition

You can use VTS to verify the following:

  • Existence of the kernel command line parameter androidboot.dtbo_idx (by checking that Init has automatically set up the corresponding ro.boot.dtbo_idx system property).
  • Validity of the ro.boot.dtbo_idx system property (by checking that the property specifies at least one valid DTBO image index).
  • Validity of the DTBO partition (also verifies the overlays in the DTBO partition that are applied to the base DT).
  • Additional nodes or property changes in the resulting DT are presented to the Linux kernel.

For example, in the following overlays and final DT, adding androidboot.dtbo_idx=5,3 to the kernel command line passes validation but adding androidboot.dtbo_idx=3,5 to the kernel command line doesn't pass validation.

Overlay DT at index 3 Overlay DT at index 5 
[overlay_1.dts]

/dts-v1/;
/plugin/;

&c { prop = <0xfe>; };

[overlay_2.dts]

/dts-v1/;
/plugin/;

&c { prop = <0xff>; };
Final DT 
/dts-v1/;
/ {

	a {
		phandle = <0x1>;
	};

	b {
		phandle = <0x2>;
	};

	c {
		phandle = <0x3>;
		prop = <0xfe>;
	};

	__symbols__ {
		a = "/a";
		b = "/b";
		c = "/c";
	};
};