[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["缺少我需要的資訊","missingTheInformationINeed","thumb-down"],["過於複雜/步驟過多","tooComplicatedTooManySteps","thumb-down"],["過時","outOfDate","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["示例/程式碼問題","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間：2025-07-27 (世界標準時間)。"],[],[],null,["# Compile and verify\n\nYou can use device tree compiler (DTC) to compile the device tree source (DTS)\nfiles. However, before applying the overlay device tree (DT) on the target main DT, you\nshould also verify the result by simulating the behavior of the device tree overlay (DTO).\n\nCompile with DTC\n----------------\n\nWhen using `dtc` to compile `.dts`, you must add\noption `-@` to add a `__symbols__` node in the\nresulting `.dtbo`. The `__symbols__` node contains a\nlist of all nodes that are marked with a label, which the DTO library can use\nfor references.\n\nSample command to build main DT `.dts`: \n\n```\ndtc -@ -O dtb -o my_main_dt.dtb my_main_dt.dts\n```\n\nSample command to build the overlay DT `.dts`: \n\n```\ndtc -@ -O dtb -o my_overlay_dt.dtbo my_overlay_dt.dts\n```\n| **Note:** If you encounter the DTC build error: `invalid option --'@'`, you might need to update your DTC version. Upstream of AOSP, the official DTC supports DTO as of [version\n| 1.4.4](https://github.com/dgibson/dtc/tree/v1.4.4) and most patches are merged after December 2016. For DTO support, we recommend using the [external/dtc](https://android.googlesource.com/platform/external/dtc/) in AOSP, which is synced with the latest DTC (with DTO patches merged as needed).\n\nVerify DTO results on the host\n------------------------------\n\nVerification can help you identify errors that might occur when placing\nthe overlay DT on the main DT. Before updating the target, you can verify the\nresult of overlaying DT on the host by simulating the behavior of DTO using\n`/include/` in `.dts`.\n| **Note:** `/include/` does NOT support the use of `__overlay__` in overlay DT sources.\n\n**Figure 1.** Use syntax /include/ to simulate DTO on the host.\n\n1. Create a copy of the overlay `.dts`. In the copy, remove the first line header. Example: \n\n ```\n /dts-v1/;\n /plugin/;\n ```\n Save the file as `my_overlay_dt_wo_header.dts` (or any filename you want).\n2. 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: \n\n ```\n /include/ \"my_overlay_dt_wo_header.dts\"\n ```\n Save the file as `my_main_dt_with_include.dts` (or any filename you want).\n3. 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: \n\n ```\n dtc -@ -O dtb -o my_merged_dt.dtb my_main_dt_with_include.dts\n ```\n4. Use `dtc` to dump `my_merged_dt.dto`. \n\n ```\n dtc -O dts -o my_merged_dt.dts my_merged_dt.dtb\n ```\n\nVerify DTO in Android 9\n-----------------------\n\nAndroid 9 requires a device tree blob overlay\n(DTBO) partition. To add nodes or make changes to the properties in the SoC\nDT, the bootloader must dynamically overlay a device specific DT over\nthe SoC DT.\n\n### Indicate applied overlays\n\nTo enable the [Vendor Test Suite (VTS)](/docs/core/tests/vts) to assess the correctness of overlay\napp, vendors must add a new kernel command line parameter\n`androidboot.dtbo_idx` that indicates the overlays selected from\nthe DTBO partition. In Android 12 using kernel version\n5.10 or greater, this parameter passes through bootconfig.\nFor example, the parameter `androidboot.dtbo_idx=x,y,z` reports\n`x`, `y` and `z` as the zero-based indices of\nthe DTOs from the DTBO partition applied (in that order)\nby the bootloader to the base DT.\n\nOverlays can apply to nodes from the main DT or add new nodes,\nbut **can't** refer to a node added in a previous overlay. This\nrestriction is necessary because the overlay app doesn't merge the\noverlay symbol table with the main DT symbol table (not merging avoids\nconflicts in symbol names and complication of dependencies between\noverlays).\n\n#### Example: Invalid overlays\n\nIn this example, `overlay_2.dts` refers to node\n**`e`** , which was added by\n`overlay_1.dts`. After `overlay_1` is applied to the\nmain DT, if an attempt is made to apply `overlay_2` to the\nresultant DT, the overlay app fails with an error that the symbol\n**`e`** isn't present in the symbol table for the\nbase DT.\n\n| main.dts | overlay_1.dts | overlay_2.dts |\n|----------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|\n| ``` [main.dts] /dts-v1/; / { a: a {}; b: b {}; c: c {}; }; ``` | ``` [overlay_1.dts] /dts-v1/; /plugin/; &b { ref1 = \u003c&a\u003e; e: e { prop = \u003c0x0a\u003e; phandle = \u003c0x04\u003e; }; }; ``` | ``` [overlay_2.dts] /dts-v1/; /plugin/; /* invalid! */ &e { prop = \u003c0x0b\u003e; }; ``` |\n\n#### Example: Valid overlays\n\nIn this example, `overlay_2.dts` refers only to node\n**`b`** from the main DTS. When\n`overlay_1` is applied to the base DT, then followed by the\napp of `overlay_2`, the value of property\n**`prop`** in node **`e`**\n(set by `overlay_1.dts`) is overwritten by the value set by\n`overlay_2.dts`.\n\n| main.dts | overlay_1.dts | overlay_2.dts |\n|-----------------------------------------------------------------|-----------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|\n| ``` [final.dts] /dts-v1/; / { a: a {}; b: b {}; c: c {}; }; ``` | ``` [overlay_1.dts] /dts-v1/; /plugin/; &b { ref1 = \u003c&a\u003e; e { prop = \u003c0x0c\u003e; }; }; ``` | ``` [overlay_2.dts] /dts-v1/; /plugin/; /* valid */ &b { ref1 = \u003c&c\u003e; e { prop = \u003c0x0d\u003e; }; }; ``` |\n\n### Implement the DTBO partition\n\nTo implement the required DTBO partition, ensure the bootloader can do the\nfollowing:\n\n1. Identify the board it is running on and select the corresponding overlays to be applied.\n2. Append the `androidboot.dtbo_idx` parameter to the kernel command line.\n - 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).\n - The indices must refer to the position of the overlay in the DTBO partition.\n\nFor details on the structure of the DTBO partition, refer to [Device tree overlays](/devices/architecture/dto).\n\n### Validate the DTBO partition\n\nYou can use VTS to verify the following:\n\n- 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).\n- Validity of the `ro.boot.dtbo_idx` system property (by checking that the property specifies at least one valid DTBO image index).\n- Validity of the DTBO partition (also verifies the overlays in the DTBO partition that are applied to the base DT).\n- Additional nodes or property changes in the resulting DT are presented to the Linux kernel.\n\nFor example, in the following overlays and final DT, adding\n`androidboot.dtbo_idx=5,3` to the kernel command line passes\nvalidation but adding `androidboot.dtbo_idx=3,5` to the kernel\ncommand line doesn't pass validation.\n\n| Overlay DT at index 3 | Overlay DT at index 5 |\n|--------------------------------------------------------------------|--------------------------------------------------------------------|\n| ``` [overlay_1.dts] /dts-v1/; /plugin/; &c { prop = \u003c0xfe\u003e; }; ``` | ``` [overlay_2.dts] /dts-v1/; /plugin/; &c { prop = \u003c0xff\u003e; }; ``` |\n\n| Final DT |\n|----------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| ``` /dts-v1/; / { a { phandle = \u003c0x1\u003e; }; b { phandle = \u003c0x2\u003e; }; c { phandle = \u003c0x3\u003e; prop = \u003c0xfe\u003e; }; __symbols__ { a = \"/a\"; b = \"/b\"; c = \"/c\"; }; }; ``` |"]]
