[TOC]

Tools

The development tool paths related to this chapter (taking the U-Boot root directory as the reference point):

./scripts/mkbootimg
./scripts/unpack_bootimg
./scripts/repack-bootimg
./scripts/unpack_resource.sh
./scripts/stacktrace.sh
./tools/patman/patman
./tools/buildman/buildman

../rkbin/tools/resource_tool
../rkbin/tools/loaderimage
../rkbin/tools/trust_merger
../rkbin/tools/boot_merger

trust_merger

Function: Packages bl30, bl31, bl32 bin files for 64-bit platforms according to the ini configuration file, generating trust.img.

ini file:

Taking RK3368TRUST.ini as an example:

[VERSION]
MAJOR=0                     ----Major version number
MINOR=1                     ----Minor version number
[BL30_OPTION]               ----bl30, currently set as mcu bin
SEC=1                       ----BL30 bin exists
PATH=tools/rk_tools/bin/rk33/rk3368bl30_v2.00.bin	----Specify bin path
ADDR=0xff8c0000             ----Firmware load and run address in DDR
[BL31_OPTION]               ----bl31, currently set as bin for multi-core and power management
SEC=1                       ----BL31 bin exists
PATH=tools/rk_tools/bin/rk33/rk3368bl31-20150401-v0.1.bin----Specify bin path
ADDR=0x00008000             ----Firmware load and run address in DDR
[BL32_OPTION]
SEC=0                       ----BL32 bin does not exist
[BL33_OPTION]
SEC=0                       ----BL33 bin does not exist
[OUTPUT]
PATH=trust.img [OUTPUT]     ----Output firmware name

Pack command:

/*
 * @<sha>: Optional. sha related, refer to make.sh
 * @<rsa>: Optional. rsa related, refer to make.sh
 * @<size>: Optional, format: --size [KB] [count]. Output file size; default is 2M single copy, 2 copies packed
 * @[ini file]: Required. ini file
 */

./tools/trust_merger <sha> <rsa> <size> [ini file]

Example:

./tools/trust_merger --rsa 3 --sha 2 ./ RKTRUST/RK3399TRUST.ini
out:trust.img
merge success(trust.img)

Unpack command:

// @[input image]: Required. Firmware to unpack, usually trust.img

./tools/trust_merger --unpack [input image]

Example:

./tools/trust_merger --unpack trust.img

File Size = 4194304
Header Tag:BL3X
Header version:256
Header flag:35
SrcFileNum:4
SignOffset:992
Component 0:
ComponentID:BL31
StorageAddr:0x4
ImageSize:0x1c0
LoadAddr:0x10000
Component 1:
ComponentID:BL31
StorageAddr:0x1c4
ImageSize:0x10
LoadAddr:0xff8c0000
Component 2:
ComponentID:BL31
StorageAddr:0x1d4
ImageSize:0x48
LoadAddr:0xff8c2000
Component 3:
ComponentID:BL32
StorageAddr:0x21c
ImageSize:0x2e0
LoadAddr:0x8400000
unpack success

boot_merger

Function: Packages miniloader + ddr + usb plug according to the ini configuration file, generating loader firmware.

ini file:

Taking the RK3288MINIALL.ini file as an example:

[CHIP_NAME]
NAME=RK320A                 ----Chip name: "RK" plus the 4B chip model agreed with maskrom
[VERSION]
MAJOR=2                     ----Major version number
MINOR=36                    ----Minor version number
[CODE471_OPTION]            ----code471, currently set as ddr bin
NUM=1
Path1=tools/rk_tools/bin/rk32/rk3288_ddr_400MHz_v1.06.bin
[CODE472_OPTION]            ----code472, currently set as usbplug bin
NUM=1
Path1=tools/rk_tools/bin/rk32/rk3288_usbplug_v2.36.bin
[LOADER_OPTION]
NUM=2
LOADER1=FlashData           ----flash data, currently set as ddr bin
LOADER2=FlashBoot           ----flash boot, currently set as miniloader bin
FlashData=tools/rk_tools/bin/rk32/rk3288_ddr_400MHz_v1.06.bin
FlashBoot=tools/rk_tools/bin/rk32/rk3288_miniloader_v2.36.bin
[OUTPUT]                    ----Output file name
PATH=rk3288_loader_v1.06.236.bin

Pack command:

// @[ini file]: Required. ini file

./tools/boot_merger [ini file]

Example:

./tools/boot_merger ./RKBOOT/RK3399MINIALL.ini
out:rk3399_loader_v1.17.115.bin
fix opt:rk3399_loader_v1.17.115.bin
merge success(rk3399_loader_v1.17.115.bin)

Unpack command:

// @[input image]: Required. Firmware to unpack, usually a loader file

./tools/boot_merger --unpack [input image]

Example:

./tools/boot_merger --unpack rk3399_loader_v1.17.115.bin
unpack entry(rk3399_ddr_800MHz_v1.17)
unpack entry(rk3399_usbplug_v1.15)
unpack entry(FlashData)
unpack entry(FlashBoot)
unpack success

loaderimage

Function:

Pack u-boot.bin to generate uboot.img
Pack 32-bit platform tee bin to generate trust.img

Pack u-boot:

/*
 * @[input bin]: Required. Source bin file
 * @[output image]: Required. Output file
 * @[load_addr]: Required. Load address
 * @<size>: Optional, format: --size [KB] [count]. Output file size; default is 1M single copy, 4 copies packed
 */

./tools/loaderimage --pack --uboot [input bin] [output image] [load_addr] <size>

Example:

./tools/loaderimage --pack --uboot ./u-boot.bin uboot.img 0x60000000 --size 1024 2

 load addr is 0x60000000!
pack input u-boot.bin
pack file size: 701981
crc = 0xc595eb85
uboot version: U-Boot 2017.09-02593-gb6e59d9 (Feb 18 2019 - 13:58:53)
pack uboot.img success!

Unpack u-boot:

/*
 * @[input image]: Required. Source file to unpack
 * @[output bin]: Required. Unpack output file, any name is acceptable
 */

./tools/loaderimage --unpack --uboot [input image] [output bin]

Example:

./tools/loaderimage --unpack --uboot uboot.img uboot.bin
unpack input uboot.img
unpack uboot.bin success!

Pack trust:

/*
 * @[input bin]: Required. bin file
 * @[output image]: Required. Output file
 * @[load_addr]: Required. Load address
 * @<size>: Optional. Format: --size [KB] [count], output file size; default is 1M single copy, 4 copies packed
 */

./tools/loaderimage --pack --trustos [input bin] [output image] [load_addr] <size>

Example:

./tools/loaderimage --pack --trustos ./bin/rk32/rk322x_tee_v2.00.bin trust.img \
                       0x80000000  --size 1024 2

 load addr is 0x80000000!
pack input bin/rk32/rk322x_tee_v2.00.bin
pack file size: 333896
crc = 0x2de93b46
pack trust.img success!

Unpack trust:

/*
 * @[input image]: Required. Source file to unpack
 * @[output bin]: Required. Unpack output file, any name is acceptable
 */

./tools/loaderimage --unpack --trustos [input image] [output bin]

Example:

./tools/loaderimage --unpack --trustos trust.img tee.bin
unpack input trust.img
unpack tee.bin success!

resource_tool

Function: Used for packing arbitrary resource files to generate resource.img.

Pack command:

./tools/resource_tool [--pack] [--image=<resource.img>] <file list>

Example:

./scripts/resource_tool ./arch/arm/boot/dts/rk3126-evb.dtb logo.bmp logo_kernel.bmp
Pack to resource.img successed!

Unpack command:

./tools/resource_tool --unpack --image=<resource.img> [output dir]

Example:

./tools/resource_tool --unpack --image=resource.img ./out/

Dump header:
partition version:0.0
header size:1
index tbl:
        offset:1        entry size:1    entry num:3
Dump Index table:
entry(0):
        path:rk-kernel.dtb
        offset:4        size:33728
entry(1):
        path:logo.bmp
        offset:70       size:170326
entry(2):
        path:logo_kernel.bmp
        offset:403      size:19160
Unack resource.img to ./out successed!

mkimage

Function: Generates the Loader firmware in SPL mode.

For example, generating the IDBLOCK format required by Rockchip's bootrom. This command also modifies the first 4 bytes of u-boot-tpl.bin to the ID required for Bootrom verification:

./tools/mkimage -n rk3328 -T rksd -d tpl/u-boot-tpl.bin idbloader.img

Detailed reference:

./doc/mkimage.1

stacktrace.sh

Function: Parse call stack information. Please refer to the RK Architecture chapter.

mkbootimg

Function: Pack firmware to generate boot and recovery.img. Source files come from the Android project.

Example:

./scripts/mkbootimg --kernel zImage --second resource.img --ramdisk ramdisk.img --out boot.img

unpack_bootimg

Function: Used for unpacking boot and recovery.img. Source files come from the Android project.

Example:

./scripts/unpack_bootimg --boot_img boot.img --out out/

repack-bootimg

Function: Replace firmware in boot and recovery.img.

Example:

// Example: replace only kernel
./scripts/repack-bootimg --boot_img boot.img --kernel zImage -o boot_repack.img

// Example: replace only resource
./scripts/repack-bootimg --boot_img boot.img --second resource.img -o boot_repack.img

pack_resource.sh

Function: Pack charging images from the ./tools/images/ directory into resource.img.

Example:

./scripts/pack_resource.sh resource.img

Pack ./tools/images/ & resource.img to resource.img ...
Unpacking old image(resource.img):
rk-kernel.dtb 1
Pack to resource.img successed!
Packed resources:
rk-kernel.dtb battery_1.bmp battery_2.bmp battery_3.bmp battery_4.bmp battery_5.bmp battery_fail.bmp battery_0.bmp 8

resource.img is packed ready

buildman

Function: Batch compile code, very suitable for verifying whether a commit on the current platform affects other platforms. Detailed reference:

./tools/buildman/README

Using buildman requires setting up the toolchain path in advance. Edit the '~/.buildman' file:

[toolchain]
arm: ~/prebuilts/gcc/linux-x86/arm/gcc-linaro-6.3.1-2017.05-x86_64_arm-linux-gnueabihf/
aarch64: ~/prebuilts/gcc/linux-x86/aarch64/gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu/

Typical use case, such as compiling U-Boot code for all Rockchip platforms:

./tools/buildman/buildman rockchip

Ideal result:

$ ./tools/buildman/buildman rockchip
boards.cfg is up to date. Nothing to do.
Building current source for 34 boards (4 threads, 1 job per thread)
   34    0    0 /34     evb-rk3326

In the displayed result, the first number is the count of fully passing platforms (green), the second is platforms with warning output (yellow), and the third is platforms with errors that cannot compile (red). If there are warnings or errors during compilation, they will be displayed on the terminal.

patman

Function: A Python tool that checks and submits patches by calling other tools. It is a very useful tool for patch Upstream (U-Boot, Kernel). Main features:

Automatically format patches based on parameters;
Call checkpatch for checking;
Extract and convert commit information into Cover-letter, patch version, version changes, etc., required by the upstream mailing list;
Automatically remove change-id from commits;
Automatically extract the recipients for each patch based on Maintainer and file submission information;
Send all patches based on the '~/.gitconfig' or './.gitconfig' configuration.

Detailed reference:

./tools/patman/README

Use the '-h' option to view all command options:

$ patman -h
Usage: patman [options]

Create patches from commits in a branch, check them and email them as
specified by tags you place in the commits. Use -n to do a dry run first.

Options:
  -h, --help            show this help message and exit
  -H, --full-help       Display the README file
  -c COUNT, --count=COUNT
                        Automatically create patches from top n commits
  -i, --ignore-errors   Send patches email even if patch errors are found
  -m, --no-maintainers  Don't cc the file maintainers automatically
  -n, --dry-run         Do a dry run (create but don't email patches)
  -p PROJECT, --project=PROJECT
                        Project name; affects default option values and
                        aliases [default: u-boot]
  -r IN_REPLY_TO, --in-reply-to=IN_REPLY_TO
                        Message ID that this series is in reply to
  -s START, --start=START
                        Commit to start creating patches from (0 = HEAD)
  -t, --ignore-bad-tags
                        Ignore bad tags / aliases
  --test                run tests
  -v, --verbose         Verbose output of errors and warnings
  --cc-cmd=CC_CMD       Output cc list for patch file (used by git)
  --no-check            Don't check for patch compliance
  --no-tags             Don't process subject tags as aliaes
  -T, --thread          Create patches as a single thread

Typical use case: Submit the latest 3 patches

patman -t -c3

After running the command, if checkpatch has errors or warnings, it will automatically abort. You need to fix the patch and rerun.

Other common options

'-t' Everything before ":" in the title is treated as a TAG. Most cannot be recognized by patman, so the '-t' option is needed;
'-i' If some warnings (e.g., exceeding 80 characters) are deemed unnecessary to fix, you can directly add the '-i' option to submit the patch;
'-s' If the patch to be submitted is not at the top of the current tree, you can use '-s' to skip the top N patches;
'-n' If you do not intend to submit a patch but just want to verify whether the latest patch passes checkpatch, you can use the '-n' option;

patman works with keywords in the commit message to generate the information required by the upstream mailing list. Typical commit:

commit 72aa9e3085e64e785680c3fa50a28651a8961feb
Author: Kever Yang <kever.yang@rock-chips.com>
Date:   Wed Sep 6 09:22:42 2017 +0800

    spl: add support to booting with OP-TEE

    OP-TEE is an open source trusted OS, in armv7, its loading and
    running are like this:
    loading:
    - SPL load both OP-TEE and U-Boot
    running:
    - SPL run into OP-TEE in secure mode;
    - OP-TEE run into U-Boot in non-secure mode;

    More detail:
    <https://github.com/OP-TEE/optee_os>
    and search for 'boot arguments' for detail entry parameter in:
    core/arch/arm/kernel/generic_entry_a32.S

    Cover-letter:
    rockchip: add tpl and OPTEE support for rk3229

    Add some generic options for TPL support for arm 32bit, and then
    and TPL support for rk3229(cortex-A7), and then add OPTEE support
    in SPL.

    Tested on latest u-boot-rockchip master.

    END

    Series-version: 4
    Series-changes: 4
    - use NULL instead of '0'
    - add fdt_addr as arg2 of entry

    Series-changes: 2
    - Using new image type for op-tee

    Change-Id: I3fd2b8305ba8fa9ea687ab7f3fd1ffd2fac9ece6
    Signed-off-by: Kever Yang <kever.yang@rock-chips.com>

When this patch is sent using the patman command, a Cover-letter is generated:

[PATCH v4 00/11] rockchip: add tpl and OPTEE support for rk3229

The corresponding patch title is as follows, including version information and the current patch's position in the entire series:

[PATCH v4,07/11] spl: add support to booting with OP-TEE

The commit message of the patch has been processed: change-id is removed, Cover-letter is removed, and version-changes information is converted to non-body text:

OP-TEE is an open source trusted OS, in armv7, its loading and
running are like this:
loading:
- SPL load both OP-TEE and U-Boot
running:
- SPL run into OP-TEE in secure mode;
- OP-TEE run into U-Boot in non-secure mode;

More detail:
<https://github.com/OP-TEE/optee_os>
and search for 'boot arguments' for detail entry parameter in:
core/arch/arm/kernel/generic_entry_a32.S

Signed-off-by: Kever Yang <kever.yang@rock-chips.com>
---

Changes in v4:
- use NULL instead of '0'
- add fdt_addr as arg2 of entry

Changes in v3: None
Changes in v2:
- Using new image type for op-tee

 common/spl/Kconfig     |  7 +++++++
 common/spl/Makefile    |  1 +
 common/spl/spl.c       |  9 +++++++++
 common/spl/spl_optee.S | 13 +++++++++++++
 include/spl.h          | 13 +++++++++++++
 5 files changed, 43 insertions(+)
 create mode 100644 common/spl/spl_optee.S

For more keyword usage, such as "Series-prefix", "Series-cc", etc., please refer to the README.

trust_merger​

boot_merger​

loaderimage​

resource_tool​

mkimage​

stacktrace.sh​

mkbootimg​

unpack_bootimg​

repack-bootimg​

pack_resource.sh​

buildman​

patman​

trust_merger

boot_merger

loaderimage

resource_tool

mkimage

stacktrace.sh

mkbootimg

unpack_bootimg

repack-bootimg

pack_resource.sh

buildman

patman