aosp12/system/libufdt/utils

libufdt utils folder

This folder contains utilities for device tree overlay.

mkdtimg (DEPRECATED, use mkdtboimg.py instead.)

If your DTB/DTBO is in an unique partition, e.g. dtb and dtbo partition. mkdtimg is a tool for creating the dtb/dtbo image. You can use mkdtimg to pack one or more DTB/DTBO files into an image.

Image Format

This is the layout for dtb/dtbo image:

  +---------------------------+  - -   -                    -
  |      dt_table_header      |  ^ |   v dt_entries_offset  | header_size
  +===========================+  | | - -                    -
  |      dt_table_entry #0    |  | | ^ | dt_entry_size
  +---------------------------+  | | | -
  |      dt_table_entry #1    |  | | |
  +---------------------------+  | | |
  |            ...            |  | | | dt_entry_size * dt_entry_count
  +---------------------------+  | | |
  |      dt_table_entry #N    |  | | v
  +===========================+  | | -
  | +-----------------------+ |  | |
  | |    fdt_header     #0  | |  | |
  + +-----------------------+ |  | |  dt_offset
  |      DTBO           #0    |  | v (dt_entry_entry #1)
  +===========================+  | _
  | +-----------------------+ |  | ^
  | |    fdt_header     #1  | |  | |
  + +-----------------------+ |  | |  dt_size
  |      DTBO           #1    |  | v (dt_entry_entry #1)
  +===========================+  | -
  |            ...            |  |
  +===========================+  |
  | +-----------------------+ |  |
  | |    fdt_header     #N  | |  | total_size
  + +-----------------------+ |  |
  |      DTBO           #N    |  v
  +---------------------------+  -

You can find the data structure dt_table_header and dt_table_entry in file src/dt_table.h

Build mkdtimg

Assume that you are at the root directory of the Android source.

1. source build/envsetup.sh
2. lunch
3. mmma system/libufdt/util/src

Using mkdtimg

mkdtimg supports several commands, including create, cfg_create, and dump.

create Command

Use the create command to create a dtb/dtbo image:

$mkdtimg create <image_filename> (<global-option>...) \
  <ftb1_filename> (<entry1_option>...) \
  <ftb2_filename> (<entry2_option>...) \
  ...

Each dtb/dtbo ftbX_filename will generate a dt_table_entry in image. entryX_options are the values to assign to dt_table_entry. These values can be any of the following:

  --id=<number|path>
  --rev=<number|path>
  --custom0=<number|path>
  --custom1=<number|path>
  --custom2=<number|path>
  --custom3=<number|path>

Number values can be a 32-bit digit (such as 68000) or a hex number (such as 0x6800). Alternatively, you can specify a path using the format:

<full_node_path>:<property_name>

For example, /board/:id. mkdtimg will read the value from the path in the DTB/DTBO file and assign into relative property in dt_table_entry. It should be a 32-bits value.

You can also give a global_option as a default option for all entries. The default value of page_size in dt_table_header is 2048. You can use global_option --page_size=<number> to assign a different value.

Example:

[board1.dts]

/dts-v1/;
/plugin/;

/ {
  compatible = "board_manufacturer,board_model";
  board_id = <0x00010000>;
  board_rev = <0x00010001>;
  another_hw_information = "some_data";
  ...
};

&device@0 {
  value = <0x1>;
  status = "okay";
};

$mkdtimg create dtbo.img --id=/:board_id --rev=/:board_rev --custom0=0xabc \
  board1.dtbo \
  board2.dtbo --id=0x6800 \
  board3.dtbo --id=0x6801 --custom0=0x123

• First dt_table_entry (board1.dtbo) id is 0x00010000 and custom[0] is 0x00000abc.
• Second id is 0x00006800 and custom[0] is 0x00000abc.
• Third id is 0x00006801 and custom[0] is 0x00000123.
• All others use the default value (0).

cfg_create Command

The cfg_create command creates an image with a config file in the following format:

# global options
  <global_option>
  ...
# entries
<ftb1_filename>     # comment
  <entry1_option>   # comment
  ...
<ftb2_filename>
  <entry2_option>
  ...
...

The global_options and entryX_options must start with one or more space characters (these options are the same as create options, without the -- prefix). Empty lines or lines beginning with # are ignored.

Example:

[dtboimg.cfg]

# global options
  id=/:board_id
  rev=/:board_rev
  custom0=0xabc

board1.dtbo

board2.dtbo
  id=0x6800 # override the value of id in global options

board2.dtbo

$mkdtimg cfg_create dtbo.img dtboimg.cfg

dump Command

For dtb/dtbo images, use the dump command to print the information in the image. Example:

$mkdtimg dump dtbo.img
dt_table_header:
               magic = d7b7ab1e
          total_size = 1300
         header_size = 32
       dt_entry_size = 32
      dt_entry_count = 3
   dt_entries_offset = 32
           page_size = 2048
             version = 0

dt_table_entry[0]:
             dt_size = 380
           dt_offset = 128
                  id = 00010000
                 rev = 00010001
           custom[0] = 00000abc
           custom[1] = 00000000
           custom[2] = 00000000
           custom[3] = 00000000
           (FDT)size = 380
     (FDT)compatible = board_manufacturer,board_model
...

help Command

Use help command to get more detail options. Example:

$mkdtimg help cfg_create