tools/binman/bintools.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2
   3 Binman bintool Documentation
   4 ============================
   5
   6 This file describes the bintools (binary tools) supported by binman. Bintools
   7 are binman's name for external executables that it runs to generate or process
   8 binaries. It is fairly easy to create new bintools. Just add a new file to the
   9 'btool' directory. You can use existing bintools as examples.
  10
  11
  12
  13 Bintool: bzip2: Compression/decompression using the bzip2 algorithm
  14 -------------------------------------------------------------------
  15
  16 This bintool supports running `bzip2` to compress and decompress data, as
  17 used by binman.
  18
  19 It is also possible to fetch the tool, which uses `apt` to install it.
  20
  21 Documentation is available via::
  22
  23     man bzip2
  24
  25
  26
  27 Bintool: cbfstool: Coreboot filesystem (CBFS) tool
  28 --------------------------------------------------
  29
  30 This bintool supports creating new CBFS images and adding files to an
  31 existing image, i.e. the features needed by binman.
  32
  33 It also supports fetching a binary cbfstool, since building it from source
  34 is fairly slow.
  35
  36 Documentation about CBFS is at https://www.coreboot.org/CBFS
  37
  38
  39
  40 Bintool: fiptool: Image generation for ARM Trusted Firmware
  41 -----------------------------------------------------------
  42
  43 This bintool supports running `fiptool` with some basic parameters as
  44 neeed by binman.
  45
  46 It also supports build fiptool from source.
  47
  48 fiptool provides a way to package firmware in an ARM Trusted Firmware
  49 Firmware Image Package (ATF FIP) format. It is used with Trusted Firmware A,
  50 for example.
  51
  52 See `TF-A FIP tool documentation`_ for more information.
  53
  54 .. _`TF-A FIP tool documentation`:
  55     https://trustedfirmware-a.readthedocs.io/en/latest/getting_started/tools-build.html?highlight=fiptool#building-and-using-the-fip-tool
  56
  57
  58
  59 Bintool: futility: Handles the 'futility' tool
  60 ----------------------------------------------
  61
  62 futility (flash utility) is a tool for working with Chromium OS flash
  63 images. This Bintool implements just the features used by Binman, related to
  64 GBB creation and firmware signing.
  65
  66 A binary version of the tool can be fetched.
  67
  68 See `Chromium OS vboot documentation`_ for more information.
  69
  70 .. _`Chromium OS vboot documentation`:
  71     https://chromium.googlesource.com/chromiumos/platform/vboot/+/refs/heads/main/_vboot_reference/README
  72
  73
  74
  75 Bintool: gzip: Compression/decompression using the gzip algorithm
  76 -----------------------------------------------------------------
  77
  78 This bintool supports running `gzip` to compress and decompress data, as
  79 used by binman.
  80
  81 It is also possible to fetch the tool, which uses `apt` to install it.
  82
  83 Documentation is available via::
  84
  85     man gzip
  86
  87
  88
  89 Bintool: ifwitool: Handles the 'ifwitool' tool
  90 ----------------------------------------------
  91
  92 This bintool supports running `ifwitool` with some basic parameters as
  93 neeed by binman. It includes creating a file from a FIT as well as adding,
  94 replacing, deleting and extracting subparts.
  95
  96 The tool is built as part of U-Boot, but a binary version can be fetched if
  97 required.
  98
  99 ifwitool provides a way to package firmware in an Intel Firmware Image
 100 (IFWI) file on some Intel SoCs, e.g. Apolo Lake.
 101
 102
 103
 104 Bintool: lz4: Compression/decompression using the LZ4 algorithm
 105 ---------------------------------------------------------------
 106
 107 This bintool supports running `lz4` to compress and decompress data, as
 108 used by binman.
 109
 110 It is also possible to fetch the tool, which uses `apt` to install it.
 111
 112 Documentation is available via::
 113
 114     man lz4
 115
 116
 117
 118 Bintool: lzma_alone: Compression/decompression using the LZMA algorithm
 119 -----------------------------------------------------------------------
 120
 121 This bintool supports running `lzma_alone` to compress and decompress data,
 122 as used by binman.
 123
 124 It is also possible to fetch the tool, which uses `apt` to install it.
 125
 126 Documentation is available via::
 127
 128     man lzma_alone
 129
 130
 131
 132 Bintool: lzop: Compression/decompression using the lzop algorithm
 133 -----------------------------------------------------------------
 134
 135 This bintool supports running `lzop` to compress and decompress data, as
 136 used by binman.
 137
 138 It is also possible to fetch the tool, which uses `apt` to install it.
 139
 140 Documentation is available via::
 141
 142     man lzop
 143
 144
 145
 146 Bintool: mkimage: Image generation for U-Boot
 147 ---------------------------------------------
 148
 149 This bintool supports running `mkimage` with some basic parameters as
 150 neeed by binman.
 151
 152 Normally binman uses the mkimage built by U-Boot. But when run outside the
 153 U-Boot build system, binman can use the version installed in your system.
 154 Support is provided for fetching this on Debian-like systems, using apt.
 155
 156
 157
 158 Bintool: openssl: openssl tool
 159 ------------------------------
 160
 161 This bintool supports creating new openssl certificates.
 162
 163 It also supports fetching a binary openssl
 164
 165 Documentation about openssl is at https://www.openssl.org/
 166
 167
 168
 169 Bintool: xz: Compression/decompression using the xz algorithm
 170 -------------------------------------------------------------
 171
 172 This bintool supports running `xz` to compress and decompress data, as
 173 used by binman.
 174
 175 It is also possible to fetch the tool, which uses `apt` to install it.
 176
 177 Documentation is available via::
 178
 179     man xz
 180
 181
 182
 183 Bintool: zstd: Compression/decompression using the zstd algorithm
 184 -----------------------------------------------------------------
 185
 186 This bintool supports running `zstd` to compress and decompress data, as
 187 used by binman.
 188
 189 It is also possible to fetch the tool, which uses `apt` to install it.
 190
 191 Documentation is available via::
 192
 193     man zstd
 194
 195
 196
 197 Bintool: fdt_add_pubkey: Add public key to device tree
 198 ------------------------------------------------------
 199
 200 This bintool supports running `fdt_add_pubkey` in order to add a public
 201 key coming from a certificate to a device-tree.
 202
 203 Normally signing is done using `mkimage` in context of `binman sign`. However,
 204 in this process the public key is not added to the stage before u-boot proper.
 205 Using `fdt_add_pubkey` the key can be injected to the SPL independent of
 206 `mkimage`
 207
 208
 209
 210 Bintool: bootgen: Sign ZynqMP FSBL image
 211 ----------------------------------------
 212
 213 This bintool supports running `bootgen` in order to sign a SPL for ZynqMP
 214 devices.
 215
 216 The bintool automatically creates an appropriate input image file (.bif) for
 217 bootgen based on the passed arguments. The output is a bootable,
 218 authenticated `boot.bin` file.