1 libufdt `utils` folder 2 ===================== 3 4 This folder contains utilities for device tree overlay. 5 6 mkdtimg 7 ------- 8 9 If your DTB/DTBO is in an unique partition, e.g. `dtb` and `dtbo` partition. 10 `mkdtimg` is a tool for creating the `dtb`/`dtbo` image. 11 You can use `mkdtimg` to pack one or more DTB/DTBO files into an image. 12 13 ### Image Format 14 15 This is the layout for `dtb`/`dtbo` image: 16 17 ```txt 18 +---------------------------+ - - - - 19 | dt_table_header | ^ | v dt_entries_offset | header_size 20 +===========================+ | | - - - 21 | dt_table_entry #0 | | | ^ | dt_entry_size 22 +---------------------------+ | | | - 23 | dt_table_entry #1 | | | | 24 +---------------------------+ | | | 25 | ... | | | | dt_entry_size * dt_entry_count 26 +---------------------------+ | | | 27 | dt_table_entry #N | | | v 28 +===========================+ | | - 29 | +-----------------------+ | | | 30 | | fdt_header #0 | | | | 31 + +-----------------------+ | | | dt_offset 32 | DTBO #0 | | v (dt_entry_entry #1) 33 +===========================+ | _ 34 | +-----------------------+ | | ^ 35 | | fdt_header #1 | | | | 36 + +-----------------------+ | | | dt_size 37 | DTBO #1 | | v (dt_entry_entry #1) 38 +===========================+ | - 39 | ... | | 40 +===========================+ | 41 | +-----------------------+ | | 42 | | fdt_header #N | | | total_size 43 + +-----------------------+ | | 44 | DTBO #N | v 45 +---------------------------+ - 46 ``` 47 48 You can find the data structure `dt_table_header` and `dt_table_entry` 49 in file `src/dt_table.h` 50 51 ### Build `mkdtimg` 52 53 Assume that you are at the root directory of the Android source. 54 55 1. `source build/envsetup.sh` 56 2. `lunch` 57 3. `mmma system/libufdt/util/src` 58 59 ### Using `mkdtimg` 60 61 `mkdtimg` supports several commands, including `create`, `cfg_create`, 62 and `dump`. 63 64 #### `create` Command 65 66 Use the `create` command to create a `dtb`/`dtbo` image: 67 68 ```sh 69 $mkdtimg create <image_filename> (<global-option>...) \ 70 <ftb1_filename> (<entry1_option>...) \ 71 <ftb2_filename> (<entry2_option>...) \ 72 ... 73 ``` 74 75 Each dtb/dtbo `ftbX_filename` will generate a `dt_table_entry` in image. 76 `entryX_options` are the values to assign to `dt_table_entry`. These values 77 can be any of the following: 78 79 ```sh 80 --id=<number|path> 81 --rev=<number|path> 82 --custom0=<number|path> 83 --custom1=<number|path> 84 --custom2=<number|path> 85 --custom3=<number|path> 86 ``` 87 88 Number values can be a 32-bit digit (such as `68000`) or a hex number 89 (such as `0x6800`). Alternatively, you can specify a path using the format: 90 91 ``` 92 <full_node_path>:<property_name> 93 ``` 94 95 For example, `/board/:id`. `mkdtimg` will read the value from the path in 96 the DTB/DTBO file and assign into relative property in `dt_table_entry`. 97 It should be a 32-bits value. 98 99 You can also give a `global_option` as a default option for all entries. 100 The default value of `page_size` in `dt_table_header` is `2048`. You can 101 use `global_option` `--page_size=<number>` to assign a different value. 102 103 Example: 104 105 ```dts 106 [board1.dts] 107 108 /dts-v1/; 109 /plugin/; 110 111 / { 112 compatible = "board_manufacturer,board_model"; 113 board_id = <0x00010000>; 114 board_rev = <0x00010001>; 115 another_hw_information = "some_data"; 116 ... 117 }; 118 119 &device@0 { 120 value = <0x1>; 121 status = "okay"; 122 }; 123 ``` 124 125 ```sh 126 $mkdtimg create dtbo.img --id=/:board_id --rev=/:board_rev --custom0=0xabc \ 127 board1.dtbo \ 128 board2.dtbo --id=0x6800 \ 129 board3.dtbo --id=0x6801 --custom0=0x123 130 ``` 131 132 * First `dt_table_entry` (`board1.dtbo`) `id` is `0x00010000` and `custom[0]` 133 is `0x00000abc.` 134 * Second `id` is `0x00006800` and `custom[0]` is `0x00000abc`. 135 * Third `id` is `0x00006801` and `custom[0]` is `0x00000123`. 136 * All others use the default value (0). 137 138 #### `cfg_create` Command 139 140 The `cfg_create` command creates an image with a config file in the following 141 format: 142 143 ```sh 144 # global options 145 <global_option> 146 ... 147 # entries 148 <ftb1_filename> # comment 149 <entry1_option> # comment 150 ... 151 <ftb2_filename> 152 <entry2_option> 153 ... 154 ... 155 ``` 156 157 The `global_options` and `entryX_options` must start with one or more space 158 characters (these options are the same as create options, without the `--` 159 prefix). Empty lines or lines beginning with `#` are ignored. 160 161 Example: 162 163 ```sh 164 [dtboimg.cfg] 165 166 # global options 167 id=/:board_id 168 rev=/:board_rev 169 custom0=0xabc 170 171 board1.dtbo 172 173 board2.dtbo 174 id=0x6800 # override the value of id in global options 175 176 board2.dtbo 177 ``` 178 179 ```sh 180 $mkdtimg cfg_create dtbo.img dtboimg.cfg 181 ``` 182 183 #### `dump` Command 184 185 For `dtb`/`dtbo` images, use the `dump` command to print the information in 186 the image. Example: 187 188 ```sh 189 $mkdtimg dump dtbo.img 190 dt_table_header: 191 magic = d7b7ab1e 192 total_size = 1300 193 header_size = 32 194 dt_entry_size = 32 195 dt_entry_count = 3 196 dt_entries_offset = 32 197 page_size = 2048 198 reserved[0] = 00000000 199 dt_table_entry[0]: 200 dt_size = 380 201 dt_offset = 128 202 id = 00010000 203 rev = 00010001 204 custom[0] = 00000abc 205 custom[1] = 00000000 206 custom[2] = 00000000 207 custom[3] = 00000000 208 (FDT)size = 380 209 (FDT)compatible = board_manufacturer,board_model 210 ... 211 ``` 212 213 #### `help` Command 214 215 Use `help` command to get more detail options. Example: 216 217 ```sh 218 $mkdtimg help cfg_create 219 ``` 220