• Home
Name Date Size #Lines LOC

..--

src/03-May-2024-2,4971,896

tests/03-May-2024-508367

README.mdD03-May-20245.4 KiB221174

README.md

1libufdt `utils` folder
2=====================
3
4This folder contains utilities for device tree overlay.
5
6mkdtimg (DEPRECATED, use mkdtboimg.py instead.)
7-------
8
9If 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.
11You can use `mkdtimg` to pack one or more DTB/DTBO files into an image.
12
13### Image Format
14
15This 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
48You can find the data structure `dt_table_header` and `dt_table_entry`
49in file `src/dt_table.h`
50
51### Build `mkdtimg`
52
53Assume that you are at the root directory of the Android source.
54
551. `source build/envsetup.sh`
562. `lunch`
573. `mmma system/libufdt/util/src`
58
59### Using `mkdtimg`
60
61`mkdtimg` supports several commands, including `create`, `cfg_create`,
62and `dump`.
63
64#### `create` Command
65
66Use 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
75Each 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
77can 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
88Number 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
95For example, `/board/:id`. `mkdtimg` will read the value from the path in
96the DTB/DTBO file and assign into relative property in `dt_table_entry`.
97It should be a 32-bits value.
98
99You can also give a `global_option` as a default option for all entries.
100The default value of `page_size` in `dt_table_header` is `2048`. You can
101use `global_option` `--page_size=<number>` to assign a different value.
102
103Example:
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
140The `cfg_create` command creates an image with a config file in the following
141format:
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
157The `global_options` and `entryX_options` must start with one or more space
158characters (these options are the same as create options, without the `--`
159prefix). Empty lines or lines beginning with `#` are ignored.
160
161Example:
162
163```sh
164[dtboimg.cfg]
165
166# global options
167  id=/:board_id
168  rev=/:board_rev
169  custom0=0xabc
170
171board1.dtbo
172
173board2.dtbo
174  id=0x6800 # override the value of id in global options
175
176board2.dtbo
177```
178
179```sh
180$mkdtimg cfg_create dtbo.img dtboimg.cfg
181```
182
183#### `dump` Command
184
185For `dtb`/`dtbo` images, use the `dump` command to print the information in
186the image. Example:
187
188```sh
189$mkdtimg dump dtbo.img
190dt_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             version = 0
199
200dt_table_entry[0]:
201             dt_size = 380
202           dt_offset = 128
203                  id = 00010000
204                 rev = 00010001
205           custom[0] = 00000abc
206           custom[1] = 00000000
207           custom[2] = 00000000
208           custom[3] = 00000000
209           (FDT)size = 380
210     (FDT)compatible = board_manufacturer,board_model
211...
212```
213
214#### `help` Command
215
216Use `help` command to get more detail options. Example:
217
218```sh
219$mkdtimg help cfg_create
220```
221