Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 1 | .. SPDX-License-Identifier: GPL-2.0+ |
| 2 | .. Copyright (c) 2016 Google, Inc |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 3 | |
| 4 | Introduction |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 5 | ============ |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 6 | |
| 7 | Firmware often consists of several components which must be packaged together. |
| 8 | For example, we may have SPL, U-Boot, a device tree and an environment area |
| 9 | grouped together and placed in MMC flash. When the system starts, it must be |
| 10 | able to find these pieces. |
| 11 | |
Simon Glass | 774b23f | 2021-03-18 20:25:17 +1300 | [diff] [blame] | 12 | Building firmware should be separate from packaging it. Many of the complexities |
| 13 | of modern firmware build systems come from trying to do both at once. With |
| 14 | binman, you build all the pieces that are needed, using whatever assortment of |
| 15 | projects and build systems are needed, then use binman to stitch everything |
| 16 | together. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 17 | |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 18 | |
| 19 | What it does |
| 20 | ------------ |
| 21 | |
| 22 | Binman reads your board's device tree and finds a node which describes the |
Simon Glass | 774b23f | 2021-03-18 20:25:17 +1300 | [diff] [blame] | 23 | required image layout. It uses this to work out what to place where. |
| 24 | |
| 25 | Binman provides a mechanism for building images, from simple SPL + U-Boot |
| 26 | combinations, to more complex arrangements with many parts. It also allows |
| 27 | users to inspect images, extract and replace binaries within them, repacking if |
| 28 | needed. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 29 | |
| 30 | |
| 31 | Features |
| 32 | -------- |
| 33 | |
Simon Glass | 774b23f | 2021-03-18 20:25:17 +1300 | [diff] [blame] | 34 | Apart from basic padding, alignment and positioning features, Binman supports |
| 35 | hierarchical images, compression, hashing and dealing with the binary blobs |
| 36 | which are a sad trend in open-source firmware at present. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 37 | |
Simon Glass | 774b23f | 2021-03-18 20:25:17 +1300 | [diff] [blame] | 38 | Executable binaries can access the location of other binaries in an image by |
| 39 | using special linker symbols (zero-overhead but somewhat limited) or by reading |
| 40 | the devicetree description of the image. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 41 | |
Simon Glass | 774b23f | 2021-03-18 20:25:17 +1300 | [diff] [blame] | 42 | Binman is designed primarily for use with U-Boot and associated binaries such |
| 43 | as ARM Trusted Firmware, but it is suitable for use with other projects, such |
| 44 | as Zephyr. Binman also provides facilities useful in Chromium OS, such as CBFS, |
Simon Glass | 76d71b0 | 2022-08-07 16:33:26 -0600 | [diff] [blame] | 45 | vblocks and the like. |
Simon Glass | 774b23f | 2021-03-18 20:25:17 +1300 | [diff] [blame] | 46 | |
| 47 | Binman provides a way to process binaries before they are included, by adding a |
| 48 | Python plug-in. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 49 | |
| 50 | Binman is intended for use with U-Boot but is designed to be general enough |
| 51 | to be useful in other image-packaging situations. |
| 52 | |
| 53 | |
| 54 | Motivation |
| 55 | ---------- |
| 56 | |
Simon Glass | 774b23f | 2021-03-18 20:25:17 +1300 | [diff] [blame] | 57 | As mentioned above, packaging of firmware is quite a different task from |
| 58 | building the various parts. In many cases the various binaries which go into |
| 59 | the image come from separate build systems. For example, ARM Trusted Firmware |
| 60 | is used on ARMv8 devices but is not built in the U-Boot tree. If a Linux kernel |
| 61 | is included in the firmware image, it is built elsewhere. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 62 | |
| 63 | It is of course possible to add more and more build rules to the U-Boot |
| 64 | build system to cover these cases. It can shell out to other Makefiles and |
| 65 | build scripts. But it seems better to create a clear divide between building |
| 66 | software and packaging it. |
| 67 | |
| 68 | At present this is handled by manual instructions, different for each board, |
| 69 | on how to create images that will boot. By turning these instructions into a |
| 70 | standard format, we can support making valid images for any board without |
| 71 | manual effort, lots of READMEs, etc. |
| 72 | |
| 73 | Benefits: |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 74 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 75 | - Each binary can have its own build system and tool chain without creating |
| 76 | any dependencies between them |
| 77 | - Avoids the need for a single-shot build: individual parts can be updated |
| 78 | and brought in as needed |
| 79 | - Provides for a standard image description available in the build and at |
| 80 | run-time |
| 81 | - SoC-specific image-signing tools can be accommodated |
| 82 | - Avoids cluttering the U-Boot build system with image-building code |
| 83 | - The image description is automatically available at run-time in U-Boot, |
| 84 | SPL. It can be made available to other software also |
| 85 | - The image description is easily readable (it's a text file in device-tree |
| 86 | format) and permits flexible packing of binaries |
| 87 | |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 88 | |
| 89 | Terminology |
| 90 | ----------- |
| 91 | |
| 92 | Binman uses the following terms: |
| 93 | |
| 94 | - image - an output file containing a firmware image |
| 95 | - binary - an input binary that goes into the image |
| 96 | |
| 97 | |
| 98 | Relationship to FIT |
| 99 | ------------------- |
| 100 | |
| 101 | FIT is U-Boot's official image format. It supports multiple binaries with |
| 102 | load / execution addresses, compression. It also supports verification |
| 103 | through hashing and RSA signatures. |
| 104 | |
| 105 | FIT was originally designed to support booting a Linux kernel (with an |
| 106 | optional ramdisk) and device tree chosen from various options in the FIT. |
| 107 | Now that U-Boot supports configuration via device tree, it is possible to |
| 108 | load U-Boot from a FIT, with the device tree chosen by SPL. |
| 109 | |
| 110 | Binman considers FIT to be one of the binaries it can place in the image. |
| 111 | |
| 112 | Where possible it is best to put as much as possible in the FIT, with binman |
| 113 | used to deal with cases not covered by FIT. Examples include initial |
| 114 | execution (since FIT itself does not have an executable header) and dealing |
| 115 | with device boundaries, such as the read-only/read-write separation in SPI |
| 116 | flash. |
| 117 | |
| 118 | For U-Boot, binman should not be used to create ad-hoc images in place of |
| 119 | FIT. |
| 120 | |
Simon Glass | 76d71b0 | 2022-08-07 16:33:26 -0600 | [diff] [blame] | 121 | Note that binman can itself create a FIT. This helps to move mkimage |
| 122 | invocations out of the Makefile and into binman image descriptions. It also |
| 123 | helps by removing the need for ad-hoc tools like `make_fit_atf.py`. |
| 124 | |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 125 | |
| 126 | Relationship to mkimage |
| 127 | ----------------------- |
| 128 | |
| 129 | The mkimage tool provides a means to create a FIT. Traditionally it has |
| 130 | needed an image description file: a device tree, like binman, but in a |
| 131 | different format. More recently it has started to support a '-f auto' mode |
| 132 | which can generate that automatically. |
| 133 | |
| 134 | More relevant to binman, mkimage also permits creation of many SoC-specific |
| 135 | image types. These can be listed by running 'mkimage -T list'. Examples |
| 136 | include 'rksd', the Rockchip SD/MMC boot format. The mkimage tool is often |
| 137 | called from the U-Boot build system for this reason. |
| 138 | |
| 139 | Binman considers the output files created by mkimage to be binary blobs |
| 140 | which it can place in an image. Binman does not replace the mkimage tool or |
Michael Heimpold | 55c822d | 2018-08-22 22:01:24 +0200 | [diff] [blame] | 141 | this purpose. It would be possible in some situations to create a new entry |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 142 | type for the images in mkimage, but this would not add functionality. It |
Michael Heimpold | 55c822d | 2018-08-22 22:01:24 +0200 | [diff] [blame] | 143 | seems better to use the mkimage tool to generate binaries and avoid blurring |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 144 | the boundaries between building input files (mkimage) and packaging then |
| 145 | into a final image (binman). |
| 146 | |
Simon Glass | 76d71b0 | 2022-08-07 16:33:26 -0600 | [diff] [blame] | 147 | Note that binman can itself invoke mkimage. This helps to move mkimage |
| 148 | invocations out of the Makefile and into binman image descriptions. |
| 149 | |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 150 | |
| 151 | Using binman |
| 152 | ============ |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 153 | |
| 154 | Example use of binman in U-Boot |
| 155 | ------------------------------- |
| 156 | |
| 157 | Binman aims to replace some of the ad-hoc image creation in the U-Boot |
| 158 | build system. |
| 159 | |
| 160 | Consider sunxi. It has the following steps: |
| 161 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 162 | #. It uses a custom mksunxiboot tool to build an SPL image called |
| 163 | sunxi-spl.bin. This should probably move into mkimage. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 164 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 165 | #. It uses mkimage to package U-Boot into a legacy image file (so that it can |
| 166 | hold the load and execution address) called u-boot.img. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 167 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 168 | #. It builds a final output image called u-boot-sunxi-with-spl.bin which |
| 169 | consists of sunxi-spl.bin, some padding and u-boot.img. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 170 | |
| 171 | Binman is intended to replace the last step. The U-Boot build system builds |
| 172 | u-boot.bin and sunxi-spl.bin. Binman can then take over creation of |
Simon Glass | 243c2c1 | 2022-02-08 11:49:54 -0700 | [diff] [blame] | 173 | sunxi-spl.bin by calling mksunxiboot or mkimage. In any case, it would then |
| 174 | create the image from the component parts. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 175 | |
| 176 | This simplifies the U-Boot Makefile somewhat, since various pieces of logic |
| 177 | can be replaced by a call to binman. |
| 178 | |
Simon Glass | 76d71b0 | 2022-08-07 16:33:26 -0600 | [diff] [blame] | 179 | |
| 180 | Invoking binman within U-Boot |
| 181 | ----------------------------- |
| 182 | |
| 183 | Within U-Boot, binman is invoked by the build system, i.e. when you type 'make' |
| 184 | or use buildman to build U-Boot. There is no need to run binman independently |
| 185 | during development. Everything happens automatically and is set up for your |
| 186 | SoC or board so that binman produced the right things. |
| 187 | |
| 188 | The general policy is that the Makefile builds all the binaries in INPUTS-y |
| 189 | (the 'inputs' rule), then binman is run to produce the final images (the 'all' |
| 190 | rule). |
| 191 | |
| 192 | There should be only one invocation of binman in Makefile, the very last step |
| 193 | that pulls everything together. At present there are some arch-specific |
| 194 | invocations as well, but these should be dropped when those architectures are |
| 195 | converted to use binman properly. |
| 196 | |
| 197 | As above, the term 'binary' is used for something in INPUTS-y and 'image' is |
| 198 | used for the things that binman creates. So the binaries are inputs to the |
| 199 | image(s) and it is the image that is actually loaded on the board. |
| 200 | |
| 201 | Again, at present, there are a number of things created in Makefile which should |
| 202 | be done by binman (when we get around to it), like `u-boot-ivt.img`, |
| 203 | `lpc32xx-spl.img`, `u-boot-with-nand-spl.imx`, `u-boot-spl-padx4.sfp` and |
| 204 | `u-boot-mtk.bin`, just to pick on a few. When completed this will remove about |
| 205 | 400 lines from `Makefile`. |
| 206 | |
| 207 | Since binman is invoked only once, it must of course create all the images that |
| 208 | are needed, in that one invocation. It does this by working through the image |
| 209 | descriptions one by one, collecting the input binaries, processing them as |
| 210 | needed and producing the final images. |
| 211 | |
| 212 | The same binaries may be used by multiple images. For example binman may be used |
| 213 | to produce an SD-card image and a SPI-flash image. In this case the binaries |
| 214 | going into the process are the same, but binman produces slightly different |
| 215 | images in each case. |
| 216 | |
| 217 | For some SoCs, U-Boot is not the only project that produces the necessary |
| 218 | binaries. For example, ARM Trusted Firmware (ATF) is a project that produces |
| 219 | binaries which must be incorporate, such as `bl31.elf` or `bl31.bin`. For this |
| 220 | to work you must have built ATF before you build U-Boot and you must tell U-Boot |
| 221 | where to find the bl31 image, using the BL31 environment variable. |
| 222 | |
| 223 | How do you know how to incorporate ATF? It is handled by the atf-bl31 entry type |
| 224 | (etype). An etype is an implementation of reading a binary into binman, in this |
| 225 | case the `bl31.bin` file. When you build U-Boot but do not set the BL31 |
| 226 | environment variable, binman provides a help message, which comes from |
| 227 | `missing-blob-help`:: |
| 228 | |
| 229 | See the documentation for your board. You may need to build ARM Trusted |
| 230 | Firmware and build with BL31=/path/to/bl31.bin |
| 231 | |
| 232 | The mechanism by which binman is advised of this is also in the Makefile. See |
| 233 | the `-a atf-bl31-path=${BL31}` piece in `cmd_binman`. This tells binman to |
| 234 | set the EntryArg `atf-bl31-path` to the value of the `BL31` environment |
| 235 | variable. Within binman, this EntryArg is picked up by the `Entry_atf_bl31` |
| 236 | etype. An EntryArg is simply an argument to the entry. The `atf-bl31-path` |
| 237 | name is documented in :ref:`etype_atf_bl31`. |
| 238 | |
Simon Glass | 7d959c5 | 2022-08-18 02:16:45 -0600 | [diff] [blame] | 239 | Taking this a little further, when binman is used to create a FIT, it supports |
| 240 | using an ELF file, e.g. `bl31.elf` and splitting it into separate pieces (with |
| 241 | `fit,operation = "split-elf"`), each with its own load address. |
| 242 | |
Simon Glass | 76d71b0 | 2022-08-07 16:33:26 -0600 | [diff] [blame] | 243 | |
| 244 | Invoking binman outside U-Boot |
| 245 | ------------------------------ |
| 246 | |
| 247 | While binman is invoked from within the U-Boot build system, it is also possible |
| 248 | to invoke it separately. This is typically used in a production build system, |
| 249 | where signing is completed (with real keys) and any missing binaries are |
| 250 | provided. |
| 251 | |
| 252 | For example, for build testing there is no need to provide a real signature, |
| 253 | nor is there any need to provide a real ATF BL31 binary (for example). These can |
| 254 | be added later by invoking binman again, providing all the required inputs |
| 255 | from the first time, plus any that were missing or placeholders. |
| 256 | |
| 257 | So in practice binman is often used twice: |
| 258 | |
| 259 | - once within the U-Boot build system, for development and testing |
| 260 | - again outside U-Boot to assembly and final production images |
| 261 | |
| 262 | While the same input binaries are used in each case, you will of course you will |
| 263 | need to create your own binman command line, similar to that in `cmd_binman` in |
| 264 | the Makefile. You may find the -I and --toolpath options useful. The |
| 265 | device tree file is provided to binman in binary form, so there is no need to |
| 266 | have access to the original `.dts` sources. |
| 267 | |
| 268 | |
| 269 | Assembling the image description |
| 270 | -------------------------------- |
| 271 | |
| 272 | Since binman uses the device tree for its image description, you can use the |
| 273 | same files that describe your board's hardware to describe how the image is |
| 274 | assembled. Typically the images description is in a common file used by all |
| 275 | boards with a particular SoC (e.g. `imx8mp-u-boot.dtsi`). |
| 276 | |
| 277 | Where a particular boards needs to make changes, it can override properties in |
| 278 | the SoC file, just as it would for any other device tree property. It can also |
| 279 | add a image that is specific to the board. |
| 280 | |
| 281 | Another way to control the image description to make use of CONFIG options in |
| 282 | the description. For example, if the start offset of a particular entry varies |
| 283 | by board, you can add a Kconfig for that and reference it in the description:: |
| 284 | |
| 285 | u-boot-spl { |
| 286 | }; |
| 287 | |
| 288 | fit { |
| 289 | offset = <CONFIG_SPL_PAD_TO>; |
| 290 | ... |
| 291 | }; |
| 292 | |
| 293 | The SoC can provide a default value but boards can override that as needed and |
| 294 | binman will take care of it. |
| 295 | |
| 296 | It is even possible to control which entries appear in the image, by using the |
| 297 | C preprocessor:: |
| 298 | |
| 299 | #ifdef CONFIG_HAVE_MRC |
| 300 | intel-mrc { |
Tom Rini | aefad5d | 2022-12-04 10:14:07 -0500 | [diff] [blame] | 301 | offset = <CFG_X86_MRC_ADDR>; |
Simon Glass | 76d71b0 | 2022-08-07 16:33:26 -0600 | [diff] [blame] | 302 | }; |
| 303 | #endif |
| 304 | |
| 305 | Only boards which enable `HAVE_MRC` will include this entry. |
| 306 | |
| 307 | Obviously a similar approach can be used to control which images are produced, |
| 308 | with a Kconfig option to enable a SPI image, for example. However there is |
| 309 | generally no harm in producing an image that is not used. If a board uses MMC |
| 310 | but not SPI, but the SoC supports booting from both, then both images can be |
| 311 | produced, with only on or other being used by particular boards. This can help |
| 312 | reduce the need for having multiple defconfig targets for a board where the |
| 313 | only difference is the boot media, enabling / disabling secure boot, etc. |
| 314 | |
| 315 | Of course you can use the device tree itself to pass any board-specific |
| 316 | information that is needed by U-Boot at runtime (see binman_syms_ for how to |
| 317 | make binman insert these values directly into executables like SPL). |
| 318 | |
| 319 | There is one more way this can be done: with individual .dtsi files for each |
| 320 | image supported by the SoC. Then the board `.dts` file can include the ones it |
| 321 | wants. This is not recommended, since it is likely to be difficult to maintain |
| 322 | and harder to understand the relationship between the different boards. |
| 323 | |
| 324 | |
| 325 | Producing images for multiple boards |
| 326 | ------------------------------------ |
| 327 | |
| 328 | When invoked within U-Boot, binman only builds a single set of images, for |
| 329 | the chosen board. This is set by the `CONFIG_DEFAULT_DEVICE_TREE` option. |
| 330 | |
| 331 | However, U-Boot generally builds all the device tree files associated with an |
| 332 | SoC. These are written to the (e.g. for ARM) `arch/arm/dts` directory. Each of |
| 333 | these contains the full binman description for that board. Often the best |
| 334 | approach is to build a single image that includes all these device tree binaries |
| 335 | and allow SPL to select the correct one on boot. |
| 336 | |
| 337 | However, it is also possible to build separate images for each board, simply by |
| 338 | invoking binman multiple times, once for each device tree file, using a |
| 339 | different output directory. This will produce one set of images for each board. |
| 340 | |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 341 | |
| 342 | Example use of binman for x86 |
| 343 | ----------------------------- |
| 344 | |
| 345 | In most cases x86 images have a lot of binary blobs, 'black-box' code |
| 346 | provided by Intel which must be run for the platform to work. Typically |
| 347 | these blobs are not relocatable and must be placed at fixed areas in the |
Michael Heimpold | 55c822d | 2018-08-22 22:01:24 +0200 | [diff] [blame] | 348 | firmware image. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 349 | |
| 350 | Currently this is handled by ifdtool, which places microcode, FSP, MRC, VGA |
| 351 | BIOS, reference code and Intel ME binaries into a u-boot.rom file. |
| 352 | |
| 353 | Binman is intended to replace all of this, with ifdtool left to handle only |
| 354 | the configuration of the Intel-format descriptor. |
| 355 | |
| 356 | |
Simon Glass | 7a7874f | 2022-01-09 20:13:48 -0700 | [diff] [blame] | 357 | Installing binman |
| 358 | ----------------- |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 359 | |
Simon Glass | 76d71b0 | 2022-08-07 16:33:26 -0600 | [diff] [blame] | 360 | First install prerequisites, e.g: |
| 361 | |
| 362 | .. code-block:: bash |
Simon Glass | 567b682 | 2019-07-08 13:18:35 -0600 | [diff] [blame] | 363 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 364 | sudo apt-get install python-pyelftools python3-pyelftools lzma-alone \ |
| 365 | liblz4-tool |
Simon Glass | 567b682 | 2019-07-08 13:18:35 -0600 | [diff] [blame] | 366 | |
Simon Glass | 7a7874f | 2022-01-09 20:13:48 -0700 | [diff] [blame] | 367 | You can run binman directly if you put it on your PATH. But if you want to |
Simon Glass | 76d71b0 | 2022-08-07 16:33:26 -0600 | [diff] [blame] | 368 | install into your `~/.local` Python directory, use: |
| 369 | |
| 370 | .. code-block:: bash |
Simon Glass | 7a7874f | 2022-01-09 20:13:48 -0700 | [diff] [blame] | 371 | |
| 372 | pip install tools/patman tools/dtoc tools/binman |
| 373 | |
| 374 | Note that binman makes use of libraries from patman and dtoc, which is why these |
| 375 | need to be installed. Also you need `libfdt` and `pylibfdt` which can be |
Simon Glass | 76d71b0 | 2022-08-07 16:33:26 -0600 | [diff] [blame] | 376 | installed like this: |
| 377 | |
| 378 | .. code-block:: bash |
Simon Glass | 7a7874f | 2022-01-09 20:13:48 -0700 | [diff] [blame] | 379 | |
| 380 | git clone git://git.kernel.org/pub/scm/utils/dtc/dtc.git |
| 381 | cd dtc |
| 382 | pip install . |
| 383 | make NO_PYTHON=1 install |
| 384 | |
| 385 | This installs the `libfdt.so` library into `~/lib` so you can use |
| 386 | `LD_LIBRARY_PATH=~/lib` when running binman. If you want to install it in the |
Simon Glass | 76d71b0 | 2022-08-07 16:33:26 -0600 | [diff] [blame] | 387 | system-library directory, replace the last line with: |
| 388 | |
| 389 | .. code-block:: bash |
Simon Glass | 7a7874f | 2022-01-09 20:13:48 -0700 | [diff] [blame] | 390 | |
| 391 | make NO_PYTHON=1 PREFIX=/ install |
| 392 | |
| 393 | Running binman |
| 394 | -------------- |
| 395 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 396 | Type:: |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 397 | |
Simon Glass | 76d71b0 | 2022-08-07 16:33:26 -0600 | [diff] [blame] | 398 | .. code-block: bash |
| 399 | |
| 400 | make NO_PYTHON=1 PREFIX=/ install |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 401 | binman build -b <board_name> |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 402 | |
| 403 | to build an image for a board. The board name is the same name used when |
| 404 | configuring U-Boot (e.g. for sandbox_defconfig the board name is 'sandbox'). |
| 405 | Binman assumes that the input files for the build are in ../b/<board_name>. |
| 406 | |
Simon Glass | 76d71b0 | 2022-08-07 16:33:26 -0600 | [diff] [blame] | 407 | Or you can specify this explicitly: |
| 408 | |
| 409 | .. code-block:: bash |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 410 | |
Simon Glass | 76d71b0 | 2022-08-07 16:33:26 -0600 | [diff] [blame] | 411 | make NO_PYTHON=1 PREFIX=/ install |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 412 | binman build -I <build_path> |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 413 | |
| 414 | where <build_path> is the build directory containing the output of the U-Boot |
| 415 | build. |
| 416 | |
| 417 | (Future work will make this more configurable) |
| 418 | |
| 419 | In either case, binman picks up the device tree file (u-boot.dtb) and looks |
| 420 | for its instructions in the 'binman' node. |
| 421 | |
| 422 | Binman has a few other options which you can see by running 'binman -h'. |
| 423 | |
| 424 | |
Simon Glass | 4b94ac9 | 2017-11-12 21:52:06 -0700 | [diff] [blame] | 425 | Enabling binman for a board |
| 426 | --------------------------- |
| 427 | |
Simon Glass | 774b23f | 2021-03-18 20:25:17 +1300 | [diff] [blame] | 428 | At present binman is invoked from a rule in the main Makefile. You should be |
| 429 | able to enable CONFIG_BINMAN to enable this rule. |
Simon Glass | 4b94ac9 | 2017-11-12 21:52:06 -0700 | [diff] [blame] | 430 | |
Simon Glass | 774b23f | 2021-03-18 20:25:17 +1300 | [diff] [blame] | 431 | The output file is typically named image.bin and is located in the output |
| 432 | directory. If input files are needed to you add these to INPUTS-y either in the |
| 433 | main Makefile or in a config.mk file in your arch subdirectory. |
Simon Glass | 4b94ac9 | 2017-11-12 21:52:06 -0700 | [diff] [blame] | 434 | |
| 435 | Once binman is executed it will pick up its instructions from a device-tree |
| 436 | file, typically <soc>-u-boot.dtsi, where <soc> is your CONFIG_SYS_SOC value. |
| 437 | You can use other, more specific CONFIG options - see 'Automatic .dtsi |
| 438 | inclusion' below. |
| 439 | |
Simon Glass | 76d71b0 | 2022-08-07 16:33:26 -0600 | [diff] [blame] | 440 | .. _binman_syms: |
Simon Glass | 4b94ac9 | 2017-11-12 21:52:06 -0700 | [diff] [blame] | 441 | |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 442 | Access to binman entry offsets at run time (symbols) |
| 443 | ---------------------------------------------------- |
| 444 | |
| 445 | Binman assembles images and determines where each entry is placed in the image. |
| 446 | This information may be useful to U-Boot at run time. For example, in SPL it |
| 447 | is useful to be able to find the location of U-Boot so that it can be executed |
| 448 | when SPL is finished. |
| 449 | |
| 450 | Binman allows you to declare symbols in the SPL image which are filled in |
Simon Glass | 76d71b0 | 2022-08-07 16:33:26 -0600 | [diff] [blame] | 451 | with their correct values during the build. For example: |
| 452 | |
| 453 | .. code-block:: c |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 454 | |
| 455 | binman_sym_declare(ulong, u_boot_any, image_pos); |
| 456 | |
| 457 | declares a ulong value which will be assigned to the image-pos of any U-Boot |
| 458 | image (u-boot.bin, u-boot.img, u-boot-nodtb.bin) that is present in the image. |
Simon Glass | 76d71b0 | 2022-08-07 16:33:26 -0600 | [diff] [blame] | 459 | You can access this value with something like: |
| 460 | |
| 461 | .. code-block:: c |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 462 | |
| 463 | ulong u_boot_offset = binman_sym(ulong, u_boot_any, image_pos); |
| 464 | |
| 465 | Thus u_boot_offset will be set to the image-pos of U-Boot in memory, assuming |
| 466 | that the whole image has been loaded, or is available in flash. You can then |
| 467 | jump to that address to start U-Boot. |
| 468 | |
| 469 | At present this feature is only supported in SPL and TPL. In principle it is |
| 470 | possible to fill in such symbols in U-Boot proper, as well, but a future C |
| 471 | library is planned for this instead, to read from the device tree. |
| 472 | |
| 473 | As well as image-pos, it is possible to read the size of an entry and its |
| 474 | offset (which is the start position of the entry within its parent). |
| 475 | |
| 476 | A small technical note: Binman automatically adds the base address of the image |
| 477 | (i.e. __image_copy_start) to the value of the image-pos symbol, so that when the |
| 478 | image is loaded to its linked address, the value will be correct and actually |
| 479 | point into the image. |
| 480 | |
| 481 | For example, say SPL is at the start of the image and linked to start at address |
| 482 | 80108000. If U-Boot's image-pos is 0x8000 then binman will write an image-pos |
| 483 | for U-Boot of 80110000 into the SPL binary, since it assumes the image is loaded |
| 484 | to 80108000, with SPL at 80108000 and U-Boot at 80110000. |
| 485 | |
| 486 | For x86 devices (with the end-at-4gb property) this base address is not added |
| 487 | since it is assumed that images are XIP and the offsets already include the |
| 488 | address. |
| 489 | |
| 490 | |
| 491 | Access to binman entry offsets at run time (fdt) |
| 492 | ------------------------------------------------ |
| 493 | |
| 494 | Binman can update the U-Boot FDT to include the final position and size of |
| 495 | each entry in the images it processes. The option to enable this is -u and it |
| 496 | causes binman to make sure that the 'offset', 'image-pos' and 'size' properties |
| 497 | are set correctly for every entry. Since it is not necessary to specify these in |
| 498 | the image definition, binman calculates the final values and writes these to |
| 499 | the device tree. These can be used by U-Boot at run-time to find the location |
| 500 | of each entry. |
| 501 | |
| 502 | Alternatively, an FDT map entry can be used to add a special FDT containing |
| 503 | just the information about the image. This is preceded by a magic string so can |
| 504 | be located anywhere in the image. An image header (typically at the start or end |
| 505 | of the image) can be used to point to the FDT map. See fdtmap and image-header |
| 506 | entries for more information. |
| 507 | |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 508 | Map files |
| 509 | --------- |
| 510 | |
| 511 | The -m option causes binman to output a .map file for each image that it |
| 512 | generates. This shows the offset and size of each entry. For example:: |
| 513 | |
| 514 | Offset Size Name |
| 515 | 00000000 00000028 main-section |
| 516 | 00000000 00000010 section@0 |
| 517 | 00000000 00000004 u-boot |
| 518 | 00000010 00000010 section@1 |
| 519 | 00000000 00000004 u-boot |
| 520 | |
| 521 | This shows a hierarchical image with two sections, each with a single entry. The |
| 522 | offsets of the sections are absolute hex byte offsets within the image. The |
| 523 | offsets of the entries are relative to their respective sections. The size of |
| 524 | each entry is also shown, in bytes (hex). The indentation shows the entries |
| 525 | nested inside their sections. |
| 526 | |
| 527 | |
| 528 | Passing command-line arguments to entries |
| 529 | ----------------------------------------- |
| 530 | |
| 531 | Sometimes it is useful to pass binman the value of an entry property from the |
| 532 | command line. For example some entries need access to files and it is not |
| 533 | always convenient to put these filenames in the image definition (device tree). |
| 534 | |
Bin Meng | 1fa2b7c | 2021-05-10 20:23:30 +0800 | [diff] [blame] | 535 | The -a option supports this:: |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 536 | |
Bin Meng | 1fa2b7c | 2021-05-10 20:23:30 +0800 | [diff] [blame] | 537 | -a <prop>=<value> |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 538 | |
| 539 | where:: |
| 540 | |
| 541 | <prop> is the property to set |
| 542 | <value> is the value to set it to |
| 543 | |
| 544 | Not all properties can be provided this way. Only some entries support it, |
| 545 | typically for filenames. |
| 546 | |
| 547 | |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 548 | Image description format |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 549 | ======================== |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 550 | |
| 551 | The binman node is called 'binman'. An example image description is shown |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 552 | below:: |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 553 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 554 | binman { |
| 555 | filename = "u-boot-sunxi-with-spl.bin"; |
| 556 | pad-byte = <0xff>; |
| 557 | blob { |
| 558 | filename = "spl/sunxi-spl.bin"; |
| 559 | }; |
| 560 | u-boot { |
| 561 | offset = <CONFIG_SPL_PAD_TO>; |
| 562 | }; |
| 563 | }; |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 564 | |
| 565 | |
| 566 | This requests binman to create an image file called u-boot-sunxi-with-spl.bin |
| 567 | consisting of a specially formatted SPL (spl/sunxi-spl.bin, built by the |
| 568 | normal U-Boot Makefile), some 0xff padding, and a U-Boot legacy image. The |
| 569 | padding comes from the fact that the second binary is placed at |
| 570 | CONFIG_SPL_PAD_TO. If that line were omitted then the U-Boot binary would |
| 571 | immediately follow the SPL binary. |
| 572 | |
| 573 | The binman node describes an image. The sub-nodes describe entries in the |
| 574 | image. Each entry represents a region within the overall image. The name of |
| 575 | the entry (blob, u-boot) tells binman what to put there. For 'blob' we must |
| 576 | provide a filename. For 'u-boot', binman knows that this means 'u-boot.bin'. |
| 577 | |
| 578 | Entries are normally placed into the image sequentially, one after the other. |
| 579 | The image size is the total size of all entries. As you can see, you can |
Simon Glass | e8561af | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 580 | specify the start offset of an entry using the 'offset' property. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 581 | |
| 582 | Note that due to a device tree requirement, all entries must have a unique |
| 583 | name. If you want to put the same binary in the image multiple times, you can |
| 584 | use any unique name, with the 'type' property providing the type. |
| 585 | |
| 586 | The attributes supported for entries are described below. |
| 587 | |
Simon Glass | e8561af | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 588 | offset: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 589 | This sets the offset of an entry within the image or section containing |
| 590 | it. The first byte of the image is normally at offset 0. If 'offset' is |
| 591 | not provided, binman sets it to the end of the previous region, or the |
| 592 | start of the image's entry area (normally 0) if there is no previous |
| 593 | region. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 594 | |
| 595 | align: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 596 | This sets the alignment of the entry. The entry offset is adjusted |
| 597 | so that the entry starts on an aligned boundary within the containing |
| 598 | section or image. For example 'align = <16>' means that the entry will |
| 599 | start on a 16-byte boundary. This may mean that padding is added before |
| 600 | the entry. The padding is part of the containing section but is not |
| 601 | included in the entry, meaning that an empty space may be created before |
| 602 | the entry starts. Alignment should be a power of 2. If 'align' is not |
| 603 | provided, no alignment is performed. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 604 | |
| 605 | size: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 606 | This sets the size of the entry. The contents will be padded out to |
| 607 | this size. If this is not provided, it will be set to the size of the |
| 608 | contents. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 609 | |
| 610 | pad-before: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 611 | Padding before the contents of the entry. Normally this is 0, meaning |
| 612 | that the contents start at the beginning of the entry. This can be used |
| 613 | to offset the entry contents a little. While this does not affect the |
| 614 | contents of the entry within binman itself (the padding is performed |
| 615 | only when its parent section is assembled), the end result will be that |
| 616 | the entry starts with the padding bytes, so may grow. Defaults to 0. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 617 | |
| 618 | pad-after: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 619 | Padding after the contents of the entry. Normally this is 0, meaning |
| 620 | that the entry ends at the last byte of content (unless adjusted by |
| 621 | other properties). This allows room to be created in the image for |
| 622 | this entry to expand later. While this does not affect the contents of |
| 623 | the entry within binman itself (the padding is performed only when its |
| 624 | parent section is assembled), the end result will be that the entry ends |
| 625 | with the padding bytes, so may grow. Defaults to 0. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 626 | |
| 627 | align-size: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 628 | This sets the alignment of the entry size. For example, to ensure |
| 629 | that the size of an entry is a multiple of 64 bytes, set this to 64. |
| 630 | While this does not affect the contents of the entry within binman |
| 631 | itself (the padding is performed only when its parent section is |
| 632 | assembled), the end result is that the entry ends with the padding |
| 633 | bytes, so may grow. If 'align-size' is not provided, no alignment is |
| 634 | performed. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 635 | |
| 636 | align-end: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 637 | This sets the alignment of the end of an entry with respect to the |
| 638 | containing section. Some entries require that they end on an alignment |
| 639 | boundary, regardless of where they start. This does not move the start |
| 640 | of the entry, so the contents of the entry will still start at the |
| 641 | beginning. But there may be padding at the end. While this does not |
| 642 | affect the contents of the entry within binman itself (the padding is |
| 643 | performed only when its parent section is assembled), the end result |
| 644 | is that the entry ends with the padding bytes, so may grow. |
| 645 | If 'align-end' is not provided, no alignment is performed. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 646 | |
| 647 | filename: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 648 | For 'blob' types this provides the filename containing the binary to |
| 649 | put into the entry. If binman knows about the entry type (like |
| 650 | u-boot-bin), then there is no need to specify this. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 651 | |
| 652 | type: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 653 | Sets the type of an entry. This defaults to the entry name, but it is |
| 654 | possible to use any name, and then add (for example) 'type = "u-boot"' |
| 655 | to specify the type. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 656 | |
Simon Glass | e8561af | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 657 | offset-unset: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 658 | Indicates that the offset of this entry should not be set by placing |
| 659 | it immediately after the entry before. Instead, is set by another |
| 660 | entry which knows where this entry should go. When this boolean |
| 661 | property is present, binman will give an error if another entry does |
| 662 | not set the offset (with the GetOffsets() method). |
Simon Glass | 4ba8d50 | 2018-06-01 09:38:17 -0600 | [diff] [blame] | 663 | |
Simon Glass | 9dcc861 | 2018-08-01 15:22:42 -0600 | [diff] [blame] | 664 | image-pos: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 665 | This cannot be set on entry (or at least it is ignored if it is), but |
| 666 | with the -u option, binman will set it to the absolute image position |
| 667 | for each entry. This makes it easy to find out exactly where the entry |
| 668 | ended up in the image, regardless of parent sections, etc. |
Simon Glass | 9dcc861 | 2018-08-01 15:22:42 -0600 | [diff] [blame] | 669 | |
Simon Glass | dd156a4 | 2022-03-05 20:18:59 -0700 | [diff] [blame] | 670 | extend-size: |
| 671 | Extend the size of this entry to fit available space. This space is only |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 672 | limited by the size of the image/section and the position of the next |
| 673 | entry. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 674 | |
Simon Glass | aa2fcf9 | 2019-07-08 14:25:30 -0600 | [diff] [blame] | 675 | compress: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 676 | Sets the compression algortihm to use (for blobs only). See the entry |
| 677 | documentation for details. |
Simon Glass | aa2fcf9 | 2019-07-08 14:25:30 -0600 | [diff] [blame] | 678 | |
Simon Glass | a820af7 | 2020-09-06 10:39:09 -0600 | [diff] [blame] | 679 | missing-msg: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 680 | Sets the tag of the message to show if this entry is missing. This is |
| 681 | used for external blobs. When they are missing it is helpful to show |
| 682 | information about what needs to be fixed. See missing-blob-help for the |
| 683 | message for each tag. |
Simon Glass | a820af7 | 2020-09-06 10:39:09 -0600 | [diff] [blame] | 684 | |
Simon Glass | 7098b7f | 2021-03-21 18:24:30 +1300 | [diff] [blame] | 685 | no-expanded: |
| 686 | By default binman substitutes entries with expanded versions if available, |
| 687 | so that a `u-boot` entry type turns into `u-boot-expanded`, for example. The |
| 688 | `--no-expanded` command-line option disables this globally. The |
| 689 | `no-expanded` property disables this just for a single entry. Put the |
| 690 | `no-expanded` boolean property in the node to select this behaviour. |
| 691 | |
Simon Glass | 8004581 | 2018-09-14 04:57:30 -0600 | [diff] [blame] | 692 | The attributes supported for images and sections are described below. Several |
| 693 | are similar to those for entries. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 694 | |
| 695 | size: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 696 | Sets the image size in bytes, for example 'size = <0x100000>' for a |
| 697 | 1MB image. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 698 | |
Simon Glass | eb023b3 | 2019-04-25 21:58:39 -0600 | [diff] [blame] | 699 | offset: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 700 | This is similar to 'offset' in entries, setting the offset of a section |
| 701 | within the image or section containing it. The first byte of the section |
| 702 | is normally at offset 0. If 'offset' is not provided, binman sets it to |
| 703 | the end of the previous region, or the start of the image's entry area |
| 704 | (normally 0) if there is no previous region. |
Simon Glass | eb023b3 | 2019-04-25 21:58:39 -0600 | [diff] [blame] | 705 | |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 706 | align-size: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 707 | This sets the alignment of the image size. For example, to ensure |
| 708 | that the image ends on a 512-byte boundary, use 'align-size = <512>'. |
| 709 | If 'align-size' is not provided, no alignment is performed. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 710 | |
| 711 | pad-before: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 712 | This sets the padding before the image entries. The first entry will |
| 713 | be positioned after the padding. This defaults to 0. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 714 | |
| 715 | pad-after: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 716 | This sets the padding after the image entries. The padding will be |
| 717 | placed after the last entry. This defaults to 0. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 718 | |
| 719 | pad-byte: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 720 | This specifies the pad byte to use when padding in the image. It |
| 721 | defaults to 0. To use 0xff, you would add 'pad-byte = <0xff>'. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 722 | |
| 723 | filename: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 724 | This specifies the image filename. It defaults to 'image.bin'. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 725 | |
Simon Glass | e8561af | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 726 | sort-by-offset: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 727 | This causes binman to reorder the entries as needed to make sure they |
| 728 | are in increasing positional order. This can be used when your entry |
| 729 | order may not match the positional order. A common situation is where |
| 730 | the 'offset' properties are set by CONFIG options, so their ordering is |
| 731 | not known a priori. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 732 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 733 | This is a boolean property so needs no value. To enable it, add a |
| 734 | line 'sort-by-offset;' to your description. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 735 | |
| 736 | multiple-images: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 737 | Normally only a single image is generated. To create more than one |
| 738 | image, put this property in the binman node. For example, this will |
| 739 | create image1.bin containing u-boot.bin, and image2.bin containing |
| 740 | both spl/u-boot-spl.bin and u-boot.bin:: |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 741 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 742 | binman { |
| 743 | multiple-images; |
| 744 | image1 { |
| 745 | u-boot { |
| 746 | }; |
| 747 | }; |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 748 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 749 | image2 { |
| 750 | spl { |
| 751 | }; |
| 752 | u-boot { |
| 753 | }; |
| 754 | }; |
| 755 | }; |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 756 | |
| 757 | end-at-4gb: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 758 | For x86 machines the ROM offsets start just before 4GB and extend |
| 759 | up so that the image finished at the 4GB boundary. This boolean |
| 760 | option can be enabled to support this. The image size must be |
| 761 | provided so that binman knows when the image should start. For an |
| 762 | 8MB ROM, the offset of the first entry would be 0xfff80000 with |
| 763 | this option, instead of 0 without this option. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 764 | |
Jagdish Gediya | 0fb978c | 2018-09-03 21:35:07 +0530 | [diff] [blame] | 765 | skip-at-start: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 766 | This property specifies the entry offset of the first entry. |
Jagdish Gediya | 0fb978c | 2018-09-03 21:35:07 +0530 | [diff] [blame] | 767 | |
Simon Glass | 72cc538 | 2022-10-20 18:22:39 -0600 | [diff] [blame] | 768 | For PowerPC mpc85xx based CPU, CONFIG_TEXT_BASE is the entry |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 769 | offset of the first entry. It can be 0xeff40000 or 0xfff40000 for |
| 770 | nor flash boot, 0x201000 for sd boot etc. |
Jagdish Gediya | 0fb978c | 2018-09-03 21:35:07 +0530 | [diff] [blame] | 771 | |
Simon Glass | 72cc538 | 2022-10-20 18:22:39 -0600 | [diff] [blame] | 772 | 'end-at-4gb' property is not applicable where CONFIG_TEXT_BASE + |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 773 | Image size != 4gb. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 774 | |
Simon Glass | f427c5f | 2021-03-21 18:24:33 +1300 | [diff] [blame] | 775 | align-default: |
| 776 | Specifies the default alignment for entries in this section, if they do |
| 777 | not specify an alignment. Note that this only applies to top-level entries |
| 778 | in the section (direct subentries), not any subentries of those entries. |
| 779 | This means that each section must specify its own default alignment, if |
| 780 | required. |
| 781 | |
Neha Malcom Francis | 3eb4be3 | 2022-10-17 16:36:25 +0530 | [diff] [blame] | 782 | symlink: |
| 783 | Adds a symlink to the image with string given in the symlink property. |
| 784 | |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 785 | Examples of the above options can be found in the tests. See the |
| 786 | tools/binman/test directory. |
| 787 | |
Simon Glass | e76a3e6 | 2018-06-01 09:38:11 -0600 | [diff] [blame] | 788 | It is possible to have the same binary appear multiple times in the image, |
| 789 | either by using a unit number suffix (u-boot@0, u-boot@1) or by using a |
| 790 | different name for each and specifying the type with the 'type' attribute. |
| 791 | |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 792 | |
Michael Heimpold | 55c822d | 2018-08-22 22:01:24 +0200 | [diff] [blame] | 793 | Sections and hierachical images |
Simon Glass | a91e115 | 2018-06-01 09:38:16 -0600 | [diff] [blame] | 794 | ------------------------------- |
| 795 | |
| 796 | Sometimes it is convenient to split an image into several pieces, each of which |
| 797 | contains its own set of binaries. An example is a flash device where part of |
| 798 | the image is read-only and part is read-write. We can set up sections for each |
| 799 | of these, and place binaries in them independently. The image is still produced |
| 800 | as a single output file. |
| 801 | |
| 802 | This feature provides a way of creating hierarchical images. For example here |
Simon Glass | 1e32400 | 2018-06-01 09:38:19 -0600 | [diff] [blame] | 803 | is an example image with two copies of U-Boot. One is read-only (ro), intended |
| 804 | to be written only in the factory. Another is read-write (rw), so that it can be |
Simon Glass | a91e115 | 2018-06-01 09:38:16 -0600 | [diff] [blame] | 805 | upgraded in the field. The sizes are fixed so that the ro/rw boundary is known |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 806 | and can be programmed:: |
Simon Glass | a91e115 | 2018-06-01 09:38:16 -0600 | [diff] [blame] | 807 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 808 | binman { |
| 809 | section@0 { |
| 810 | read-only; |
| 811 | name-prefix = "ro-"; |
| 812 | size = <0x100000>; |
| 813 | u-boot { |
| 814 | }; |
| 815 | }; |
| 816 | section@1 { |
| 817 | name-prefix = "rw-"; |
| 818 | size = <0x100000>; |
| 819 | u-boot { |
| 820 | }; |
| 821 | }; |
| 822 | }; |
Simon Glass | a91e115 | 2018-06-01 09:38:16 -0600 | [diff] [blame] | 823 | |
| 824 | This image could be placed into a SPI flash chip, with the protection boundary |
| 825 | set at 1MB. |
| 826 | |
| 827 | A few special properties are provided for sections: |
| 828 | |
| 829 | read-only: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 830 | Indicates that this section is read-only. This has no impact on binman's |
| 831 | operation, but his property can be read at run time. |
Simon Glass | a91e115 | 2018-06-01 09:38:16 -0600 | [diff] [blame] | 832 | |
Simon Glass | 3b78d53 | 2018-06-01 09:38:21 -0600 | [diff] [blame] | 833 | name-prefix: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 834 | This string is prepended to all the names of the binaries in the |
| 835 | section. In the example above, the 'u-boot' binaries which actually be |
| 836 | renamed to 'ro-u-boot' and 'rw-u-boot'. This can be useful to |
| 837 | distinguish binaries with otherwise identical names. |
Simon Glass | 3b78d53 | 2018-06-01 09:38:21 -0600 | [diff] [blame] | 838 | |
Simon Glass | a91e115 | 2018-06-01 09:38:16 -0600 | [diff] [blame] | 839 | |
Simon Glass | fb30e29 | 2019-07-20 12:23:51 -0600 | [diff] [blame] | 840 | Image Properties |
| 841 | ---------------- |
| 842 | |
| 843 | Image nodes act like sections but also have a few extra properties: |
| 844 | |
| 845 | filename: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 846 | Output filename for the image. This defaults to image.bin (or in the |
| 847 | case of multiple images <nodename>.bin where <nodename> is the name of |
| 848 | the image node. |
Simon Glass | fb30e29 | 2019-07-20 12:23:51 -0600 | [diff] [blame] | 849 | |
| 850 | allow-repack: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 851 | Create an image that can be repacked. With this option it is possible |
| 852 | to change anything in the image after it is created, including updating |
| 853 | the position and size of image components. By default this is not |
| 854 | permitted since it is not possibly to know whether this might violate a |
| 855 | constraint in the image description. For example, if a section has to |
| 856 | increase in size to hold a larger binary, that might cause the section |
| 857 | to fall out of its allow region (e.g. read-only portion of flash). |
Simon Glass | fb30e29 | 2019-07-20 12:23:51 -0600 | [diff] [blame] | 858 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 859 | Adding this property causes the original offset and size values in the |
| 860 | image description to be stored in the FDT and fdtmap. |
Simon Glass | fb30e29 | 2019-07-20 12:23:51 -0600 | [diff] [blame] | 861 | |
| 862 | |
Simon Glass | fca3856 | 2022-08-18 02:16:46 -0600 | [diff] [blame] | 863 | Image dependencies |
| 864 | ------------------ |
| 865 | |
| 866 | Binman does not currently support images that depend on each other. For example, |
| 867 | if one image creates `fred.bin` and then the next uses this `fred.bin` to |
| 868 | produce a final `image.bin`, then the behaviour is undefined. It may work, or it |
| 869 | may produce an error about `fred.bin` being missing, or it may use a version of |
| 870 | `fred.bin` from a previous run. |
| 871 | |
| 872 | Often this can be handled by incorporating the dependency into the second |
| 873 | image. For example, instead of:: |
| 874 | |
| 875 | binman { |
| 876 | multiple-images; |
| 877 | |
| 878 | fred { |
| 879 | u-boot { |
| 880 | }; |
| 881 | fill { |
| 882 | size = <0x100>; |
| 883 | }; |
| 884 | }; |
| 885 | |
| 886 | image { |
| 887 | blob { |
| 888 | filename = "fred.bin"; |
| 889 | }; |
| 890 | u-boot-spl { |
| 891 | }; |
| 892 | }; |
| 893 | |
| 894 | you can do this:: |
| 895 | |
| 896 | binman { |
| 897 | image { |
| 898 | fred { |
| 899 | type = "section"; |
| 900 | u-boot { |
| 901 | }; |
| 902 | fill { |
| 903 | size = <0x100>; |
| 904 | }; |
| 905 | }; |
| 906 | u-boot-spl { |
| 907 | }; |
| 908 | }; |
| 909 | |
| 910 | |
| 911 | |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 912 | Hashing Entries |
| 913 | --------------- |
| 914 | |
| 915 | It is possible to ask binman to hash the contents of an entry and write that |
| 916 | value back to the device-tree node. For example:: |
| 917 | |
| 918 | binman { |
| 919 | u-boot { |
| 920 | hash { |
| 921 | algo = "sha256"; |
| 922 | }; |
| 923 | }; |
| 924 | }; |
| 925 | |
| 926 | Here, a new 'value' property will be written to the 'hash' node containing |
| 927 | the hash of the 'u-boot' entry. Only SHA256 is supported at present. Whole |
| 928 | sections can be hased if desired, by adding the 'hash' node to the section. |
| 929 | |
| 930 | The has value can be chcked at runtime by hashing the data actually read and |
| 931 | comparing this has to the value in the device tree. |
| 932 | |
| 933 | |
| 934 | Expanded entries |
| 935 | ---------------- |
| 936 | |
| 937 | Binman automatically replaces 'u-boot' with an expanded version of that, i.e. |
| 938 | 'u-boot-expanded'. This means that when you write:: |
| 939 | |
| 940 | u-boot { |
| 941 | }; |
| 942 | |
| 943 | you actually get:: |
| 944 | |
| 945 | u-boot { |
| 946 | type = "u-boot-expanded'; |
| 947 | }; |
| 948 | |
| 949 | which in turn expands to:: |
| 950 | |
| 951 | u-boot { |
| 952 | type = "section"; |
| 953 | |
| 954 | u-boot-nodtb { |
| 955 | }; |
| 956 | |
| 957 | u-boot-dtb { |
| 958 | }; |
| 959 | }; |
| 960 | |
| 961 | U-Boot's various phase binaries actually comprise two or three pieces. |
| 962 | For example, u-boot.bin has the executable followed by a devicetree. |
| 963 | |
| 964 | With binman we want to be able to update that devicetree with full image |
| 965 | information so that it is accessible to the executable. This is tricky |
| 966 | if it is not clear where the devicetree starts. |
| 967 | |
| 968 | The above feature ensures that the devicetree is clearly separated from the |
| 969 | U-Boot executable and can be updated separately by binman as needed. It can be |
| 970 | disabled with the --no-expanded flag if required. |
| 971 | |
Heiko Thiery | d589456 | 2022-01-24 08:11:01 +0100 | [diff] [blame] | 972 | The same applies for u-boot-spl and u-boot-tpl. In those cases, the expansion |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 973 | includes the BSS padding, so for example:: |
| 974 | |
| 975 | spl { |
| 976 | type = "u-boot-spl" |
| 977 | }; |
| 978 | |
| 979 | you actually get:: |
| 980 | |
| 981 | spl { |
| 982 | type = "u-boot-expanded'; |
| 983 | }; |
| 984 | |
| 985 | which in turn expands to:: |
| 986 | |
| 987 | spl { |
| 988 | type = "section"; |
| 989 | |
| 990 | u-boot-spl-nodtb { |
| 991 | }; |
| 992 | |
| 993 | u-boot-spl-bss-pad { |
| 994 | }; |
| 995 | |
| 996 | u-boot-spl-dtb { |
| 997 | }; |
| 998 | }; |
| 999 | |
| 1000 | Of course we should not expand SPL if it has no devicetree. Also if the BSS |
| 1001 | padding is not needed (because BSS is in RAM as with CONFIG_SPL_SEPARATE_BSS), |
| 1002 | the 'u-boot-spl-bss-pad' subnode should not be created. The use of the expaned |
| 1003 | entry type is controlled by the UseExpanded() method. In the SPL case it checks |
| 1004 | the 'spl-dtb' entry arg, which is 'y' or '1' if SPL has a devicetree. |
| 1005 | |
| 1006 | For the BSS case, a 'spl-bss-pad' entry arg controls whether it is present. All |
| 1007 | entry args are provided by the U-Boot Makefile. |
| 1008 | |
| 1009 | |
| 1010 | Compression |
| 1011 | ----------- |
| 1012 | |
| 1013 | Binman support compression for 'blob' entries (those of type 'blob' and |
| 1014 | derivatives). To enable this for an entry, add a 'compress' property:: |
| 1015 | |
| 1016 | blob { |
| 1017 | filename = "datafile"; |
| 1018 | compress = "lz4"; |
| 1019 | }; |
| 1020 | |
| 1021 | The entry will then contain the compressed data, using the 'lz4' compression |
| 1022 | algorithm. Currently this is the only one that is supported. The uncompressed |
| 1023 | size is written to the node in an 'uncomp-size' property, if -u is used. |
| 1024 | |
| 1025 | Compression is also supported for sections. In that case the entire section is |
| 1026 | compressed in one block, including all its contents. This means that accessing |
| 1027 | an entry from the section required decompressing the entire section. Also, the |
| 1028 | size of a section indicates the space that it consumes in its parent section |
| 1029 | (and typically the image). With compression, the section may contain more data, |
| 1030 | and the uncomp-size property indicates that, as above. The contents of the |
| 1031 | section is compressed first, before any padding is added. This ensures that the |
| 1032 | padding itself is not compressed, which would be a waste of time. |
| 1033 | |
| 1034 | |
| 1035 | Automatic .dtsi inclusion |
| 1036 | ------------------------- |
| 1037 | |
| 1038 | It is sometimes inconvenient to add a 'binman' node to the .dts file for each |
| 1039 | board. This can be done by using #include to bring in a common file. Another |
| 1040 | approach supported by the U-Boot build system is to automatically include |
| 1041 | a common header. You can then put the binman node (and anything else that is |
| 1042 | specific to U-Boot, such as u-boot,dm-pre-reloc properies) in that header |
| 1043 | file. |
| 1044 | |
| 1045 | Binman will search for the following files in arch/<arch>/dts:: |
| 1046 | |
| 1047 | <dts>-u-boot.dtsi where <dts> is the base name of the .dts file |
| 1048 | <CONFIG_SYS_SOC>-u-boot.dtsi |
| 1049 | <CONFIG_SYS_CPU>-u-boot.dtsi |
| 1050 | <CONFIG_SYS_VENDOR>-u-boot.dtsi |
| 1051 | u-boot.dtsi |
| 1052 | |
| 1053 | U-Boot will only use the first one that it finds. If you need to include a |
| 1054 | more general file you can do that from the more specific file using #include. |
Simon Glass | 0a1b3b6 | 2021-12-16 20:59:23 -0700 | [diff] [blame] | 1055 | If you are having trouble figuring out what is going on, you can use |
| 1056 | `DEVICE_TREE_DEBUG=1` with your build:: |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 1057 | |
Simon Glass | 0a1b3b6 | 2021-12-16 20:59:23 -0700 | [diff] [blame] | 1058 | make DEVICE_TREE_DEBUG=1 |
| 1059 | scripts/Makefile.lib:334: Automatic .dtsi inclusion: options: |
| 1060 | arch/arm/dts/juno-r2-u-boot.dtsi arch/arm/dts/-u-boot.dtsi |
| 1061 | arch/arm/dts/armv8-u-boot.dtsi arch/arm/dts/armltd-u-boot.dtsi |
| 1062 | arch/arm/dts/u-boot.dtsi ... found: "arch/arm/dts/juno-r2-u-boot.dtsi" |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 1063 | |
| 1064 | |
Simon Glass | adfb849 | 2021-11-03 21:09:18 -0600 | [diff] [blame] | 1065 | Updating an ELF file |
| 1066 | ==================== |
| 1067 | |
| 1068 | For the EFI app, where U-Boot is loaded from UEFI and runs as an app, there is |
| 1069 | no way to update the devicetree after U-Boot is built. Normally this works by |
| 1070 | creating a new u-boot.dtb.out with he updated devicetree, which is automatically |
| 1071 | built into the output image. With ELF this is not possible since the ELF is |
| 1072 | not part of an image, just a stand-along file. We must create an updated ELF |
| 1073 | file with the new devicetree. |
| 1074 | |
| 1075 | This is handled by the --update-fdt-in-elf option. It takes four arguments, |
| 1076 | separated by comma: |
| 1077 | |
| 1078 | infile - filename of input ELF file, e.g. 'u-boot's |
| 1079 | outfile - filename of output ELF file, e.g. 'u-boot.out' |
| 1080 | begin_sym - symbol at the start of the embedded devicetree, e.g. |
| 1081 | '__dtb_dt_begin' |
| 1082 | end_sym - symbol at the start of the embedded devicetree, e.g. |
| 1083 | '__dtb_dt_end' |
| 1084 | |
| 1085 | When this flag is used, U-Boot does all the normal packaging, but as an |
| 1086 | additional step, it creates a new ELF file with the new devicetree embedded in |
| 1087 | it. |
| 1088 | |
| 1089 | If logging is enabled you will see a message like this:: |
| 1090 | |
| 1091 | Updating file 'u-boot' with data length 0x400a (16394) between symbols |
| 1092 | '__dtb_dt_begin' and '__dtb_dt_end' |
| 1093 | |
| 1094 | There must be enough space for the updated devicetree. If not, an error like |
| 1095 | the following is produced:: |
| 1096 | |
| 1097 | ValueError: Not enough space in 'u-boot' for data length 0x400a (16394); |
| 1098 | size is 0x1744 (5956) |
| 1099 | |
| 1100 | |
Simon Glass | 7a61c6b | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 1101 | Entry Documentation |
Simon Glass | 774b23f | 2021-03-18 20:25:17 +1300 | [diff] [blame] | 1102 | =================== |
Simon Glass | 7a61c6b | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 1103 | |
| 1104 | For details on the various entry types supported by binman and how to use them, |
Simon Glass | 774b23f | 2021-03-18 20:25:17 +1300 | [diff] [blame] | 1105 | see entries.rst which is generated from the source code using: |
| 1106 | |
| 1107 | binman entry-docs >tools/binman/entries.rst |
Simon Glass | 7a61c6b | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 1108 | |
Simon Glass | 774b23f | 2021-03-18 20:25:17 +1300 | [diff] [blame] | 1109 | .. toctree:: |
| 1110 | :maxdepth: 2 |
Simon Glass | 7a61c6b | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 1111 | |
Simon Glass | 774b23f | 2021-03-18 20:25:17 +1300 | [diff] [blame] | 1112 | entries |
| 1113 | |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 1114 | |
| 1115 | Managing images |
| 1116 | =============== |
Simon Glass | 7a61c6b | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 1117 | |
Simon Glass | b2fd11d | 2019-07-08 14:25:48 -0600 | [diff] [blame] | 1118 | Listing images |
| 1119 | -------------- |
| 1120 | |
| 1121 | It is possible to list the entries in an existing firmware image created by |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 1122 | binman, provided that there is an 'fdtmap' entry in the image. For example:: |
Simon Glass | b2fd11d | 2019-07-08 14:25:48 -0600 | [diff] [blame] | 1123 | |
| 1124 | $ binman ls -i image.bin |
| 1125 | Name Image-pos Size Entry-type Offset Uncomp-size |
| 1126 | ---------------------------------------------------------------------- |
| 1127 | main-section c00 section 0 |
| 1128 | u-boot 0 4 u-boot 0 |
| 1129 | section 5fc section 4 |
| 1130 | cbfs 100 400 cbfs 0 |
| 1131 | u-boot 138 4 u-boot 38 |
| 1132 | u-boot-dtb 180 108 u-boot-dtb 80 3b5 |
| 1133 | u-boot-dtb 500 1ff u-boot-dtb 400 3b5 |
| 1134 | fdtmap 6fc 381 fdtmap 6fc |
| 1135 | image-header bf8 8 image-header bf8 |
| 1136 | |
| 1137 | This shows the hierarchy of the image, the position, size and type of each |
| 1138 | entry, the offset of each entry within its parent and the uncompressed size if |
| 1139 | the entry is compressed. |
| 1140 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 1141 | It is also possible to list just some files in an image, e.g.:: |
Simon Glass | b2fd11d | 2019-07-08 14:25:48 -0600 | [diff] [blame] | 1142 | |
| 1143 | $ binman ls -i image.bin section/cbfs |
| 1144 | Name Image-pos Size Entry-type Offset Uncomp-size |
| 1145 | -------------------------------------------------------------------- |
| 1146 | cbfs 100 400 cbfs 0 |
| 1147 | u-boot 138 4 u-boot 38 |
| 1148 | u-boot-dtb 180 108 u-boot-dtb 80 3b5 |
| 1149 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 1150 | or with wildcards:: |
Simon Glass | b2fd11d | 2019-07-08 14:25:48 -0600 | [diff] [blame] | 1151 | |
| 1152 | $ binman ls -i image.bin "*cb*" "*head*" |
| 1153 | Name Image-pos Size Entry-type Offset Uncomp-size |
| 1154 | ---------------------------------------------------------------------- |
| 1155 | cbfs 100 400 cbfs 0 |
| 1156 | u-boot 138 4 u-boot 38 |
| 1157 | u-boot-dtb 180 108 u-boot-dtb 80 3b5 |
| 1158 | image-header bf8 8 image-header bf8 |
| 1159 | |
Simon Glass | b9028bc | 2021-11-23 21:09:49 -0700 | [diff] [blame] | 1160 | If an older version of binman is used to list images created by a newer one, it |
| 1161 | is possible that it will contain entry types that are not supported. These still |
| 1162 | show with the correct type, but binman just sees them as blobs (plain binary |
| 1163 | data). Any special features of that etype are not supported by the old binman. |
| 1164 | |
Simon Glass | b2fd11d | 2019-07-08 14:25:48 -0600 | [diff] [blame] | 1165 | |
Simon Glass | 980a284 | 2019-07-08 14:25:52 -0600 | [diff] [blame] | 1166 | Extracting files from images |
| 1167 | ---------------------------- |
| 1168 | |
| 1169 | You can extract files from an existing firmware image created by binman, |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 1170 | provided that there is an 'fdtmap' entry in the image. For example:: |
Simon Glass | 980a284 | 2019-07-08 14:25:52 -0600 | [diff] [blame] | 1171 | |
| 1172 | $ binman extract -i image.bin section/cbfs/u-boot |
| 1173 | |
| 1174 | which will write the uncompressed contents of that entry to the file 'u-boot' in |
| 1175 | the current directory. You can also extract to a particular file, in this case |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 1176 | u-boot.bin:: |
Simon Glass | 980a284 | 2019-07-08 14:25:52 -0600 | [diff] [blame] | 1177 | |
| 1178 | $ binman extract -i image.bin section/cbfs/u-boot -f u-boot.bin |
| 1179 | |
| 1180 | It is possible to extract all files into a destination directory, which will |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 1181 | put files in subdirectories matching the entry hierarchy:: |
Simon Glass | 980a284 | 2019-07-08 14:25:52 -0600 | [diff] [blame] | 1182 | |
| 1183 | $ binman extract -i image.bin -O outdir |
| 1184 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 1185 | or just a selection:: |
Simon Glass | 980a284 | 2019-07-08 14:25:52 -0600 | [diff] [blame] | 1186 | |
| 1187 | $ binman extract -i image.bin "*u-boot*" -O outdir |
| 1188 | |
Simon Glass | 637958f | 2021-11-23 21:09:50 -0700 | [diff] [blame] | 1189 | Some entry types have alternative formats, for example fdtmap which allows |
| 1190 | extracted just the devicetree binary without the fdtmap header:: |
| 1191 | |
| 1192 | $ binman extract -i /tmp/b/odroid-c4/image.bin -f out.dtb -F fdt fdtmap |
| 1193 | $ fdtdump out.dtb |
| 1194 | /dts-v1/; |
| 1195 | // magic: 0xd00dfeed |
| 1196 | // totalsize: 0x8ab (2219) |
| 1197 | // off_dt_struct: 0x38 |
| 1198 | // off_dt_strings: 0x82c |
| 1199 | // off_mem_rsvmap: 0x28 |
| 1200 | // version: 17 |
| 1201 | // last_comp_version: 2 |
| 1202 | // boot_cpuid_phys: 0x0 |
| 1203 | // size_dt_strings: 0x7f |
| 1204 | // size_dt_struct: 0x7f4 |
| 1205 | |
| 1206 | / { |
| 1207 | image-node = "binman"; |
| 1208 | image-pos = <0x00000000>; |
| 1209 | size = <0x0011162b>; |
| 1210 | ... |
| 1211 | |
| 1212 | Use `-F list` to see what alternative formats are available:: |
| 1213 | |
| 1214 | $ binman extract -i /tmp/b/odroid-c4/image.bin -F list |
| 1215 | Flag (-F) Entry type Description |
| 1216 | fdt fdtmap Extract the devicetree blob from the fdtmap |
| 1217 | |
Simon Glass | 980a284 | 2019-07-08 14:25:52 -0600 | [diff] [blame] | 1218 | |
Simon Glass | 072959a | 2019-07-20 12:23:50 -0600 | [diff] [blame] | 1219 | Replacing files in an image |
| 1220 | --------------------------- |
| 1221 | |
| 1222 | You can replace files in an existing firmware image created by binman, provided |
Simon Glass | 31cce97 | 2021-11-23 21:09:48 -0700 | [diff] [blame] | 1223 | that there is an 'fdtmap' entry in the image. For example:: |
Simon Glass | 072959a | 2019-07-20 12:23:50 -0600 | [diff] [blame] | 1224 | |
| 1225 | $ binman replace -i image.bin section/cbfs/u-boot |
| 1226 | |
| 1227 | which will write the contents of the file 'u-boot' from the current directory |
Simon Glass | 30033c2 | 2019-07-20 12:24:15 -0600 | [diff] [blame] | 1228 | to the that entry, compressing if necessary. If the entry size changes, you must |
| 1229 | add the 'allow-repack' property to the original image before generating it (see |
| 1230 | above), otherwise you will get an error. |
Simon Glass | 072959a | 2019-07-20 12:23:50 -0600 | [diff] [blame] | 1231 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 1232 | You can also use a particular file, in this case u-boot.bin:: |
Simon Glass | 30033c2 | 2019-07-20 12:24:15 -0600 | [diff] [blame] | 1233 | |
| 1234 | $ binman replace -i image.bin section/cbfs/u-boot -f u-boot.bin |
| 1235 | |
| 1236 | It is possible to replace all files from a source directory which uses the same |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 1237 | hierarchy as the entries:: |
Simon Glass | 30033c2 | 2019-07-20 12:24:15 -0600 | [diff] [blame] | 1238 | |
| 1239 | $ binman replace -i image.bin -I indir |
| 1240 | |
| 1241 | Files that are missing will generate a warning. |
| 1242 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 1243 | You can also replace just a selection of entries:: |
Simon Glass | 30033c2 | 2019-07-20 12:24:15 -0600 | [diff] [blame] | 1244 | |
| 1245 | $ binman replace -i image.bin "*u-boot*" -I indir |
| 1246 | |
Simon Glass | 072959a | 2019-07-20 12:23:50 -0600 | [diff] [blame] | 1247 | |
Simon Glass | a922347 | 2022-11-09 19:14:49 -0700 | [diff] [blame] | 1248 | .. _`BinmanLogging`: |
| 1249 | |
Simon Glass | 233a26a9 | 2019-07-08 14:25:49 -0600 | [diff] [blame] | 1250 | Logging |
| 1251 | ------- |
| 1252 | |
| 1253 | Binman normally operates silently unless there is an error, in which case it |
| 1254 | just displays the error. The -D/--debug option can be used to create a full |
Simon Glass | caa5f18 | 2021-02-06 09:57:28 -0700 | [diff] [blame] | 1255 | backtrace when errors occur. You can use BINMAN_DEBUG=1 when building to select |
| 1256 | this. |
Simon Glass | 233a26a9 | 2019-07-08 14:25:49 -0600 | [diff] [blame] | 1257 | |
| 1258 | Internally binman logs some output while it is running. This can be displayed |
| 1259 | by increasing the -v/--verbosity from the default of 1: |
| 1260 | |
| 1261 | 0: silent |
| 1262 | 1: warnings only |
| 1263 | 2: notices (important messages) |
| 1264 | 3: info about major operations |
| 1265 | 4: detailed information about each operation |
| 1266 | 5: debug (all output) |
| 1267 | |
Simon Glass | caa5f18 | 2021-02-06 09:57:28 -0700 | [diff] [blame] | 1268 | You can use BINMAN_VERBOSE=5 (for example) when building to select this. |
Simon Glass | 233a26a9 | 2019-07-08 14:25:49 -0600 | [diff] [blame] | 1269 | |
Simon Glass | 7223245 | 2016-11-25 20:15:53 -0700 | [diff] [blame] | 1270 | |
Simon Glass | 4142486 | 2022-01-09 20:14:12 -0700 | [diff] [blame] | 1271 | Bintools |
| 1272 | ======== |
| 1273 | |
| 1274 | `Bintool` is the name binman gives to a binary tool which it uses to create and |
| 1275 | manipulate binaries that binman cannot handle itself. Bintools are often |
| 1276 | necessary since Binman only supports a subset of the available file formats |
| 1277 | natively. |
| 1278 | |
| 1279 | Many SoC vendors invent ways to load code into their SoC using new file formats, |
| 1280 | sometimes changing the format with successive SoC generations. Sometimes the |
| 1281 | tool is available as Open Source. Sometimes it is a pre-compiled binary that |
| 1282 | must be downloaded from the vendor's website. Sometimes it is available in |
| 1283 | source form but difficult or slow to build. |
| 1284 | |
| 1285 | Even for images that use bintools, binman still assembles the image from its |
| 1286 | image description. It may handle parts of the image natively and part with |
| 1287 | various bintools. |
| 1288 | |
| 1289 | Binman relies on these tools so provides various features to manage them: |
| 1290 | |
| 1291 | - Determining whether the tool is currently installed |
| 1292 | - Downloading or building the tool |
| 1293 | - Determining the version of the tool that is installed |
| 1294 | - Deciding which tools are needed to build an image |
| 1295 | |
| 1296 | The Bintool class is an interface to the tool, a thin level of abstration, using |
| 1297 | Python functions to run the tool for each purpose (e.g. creating a new |
| 1298 | structure, adding a file to an existing structure) rather than just lists of |
| 1299 | string arguments. |
| 1300 | |
| 1301 | As with external blobs, bintools (which are like 'external' tools) can be |
| 1302 | missing. When building an image requires a bintool and it is not installed, |
| 1303 | binman detects this and reports the problem, but continues to build an image. |
| 1304 | This is useful in CI systems which want to check that everything is correct but |
| 1305 | don't have access to the bintools. |
| 1306 | |
| 1307 | To make this work, all calls to bintools (e.g. with Bintool.run_cmd()) must cope |
| 1308 | with the tool being missing, i.e. when None is returned, by: |
| 1309 | |
| 1310 | - Calling self.record_missing_bintool() |
| 1311 | - Setting up some fake contents so binman can continue |
| 1312 | |
| 1313 | Of course the image will not work, but binman reports which bintools are needed |
| 1314 | and also provide a way to fetch them. |
| 1315 | |
| 1316 | To see the available bintools, use:: |
| 1317 | |
| 1318 | binman tool --list |
| 1319 | |
| 1320 | To fetch tools which are missing, use:: |
| 1321 | |
| 1322 | binman tool --fetch missing |
| 1323 | |
| 1324 | You can also use `--fetch all` to fetch all tools or `--fetch <tool>` to fetch |
| 1325 | a particular tool. Some tools are built from source code, in which case you will |
| 1326 | need to have at least the `build-essential` and `git` packages installed. |
| 1327 | |
| 1328 | Bintool Documentation |
| 1329 | ===================== |
| 1330 | |
| 1331 | To provide details on the various bintools supported by binman, bintools.rst is |
| 1332 | generated from the source code using: |
| 1333 | |
| 1334 | binman bintool-docs >tools/binman/bintools.rst |
| 1335 | |
| 1336 | .. toctree:: |
| 1337 | :maxdepth: 2 |
| 1338 | |
| 1339 | bintools |
| 1340 | |
Simon Glass | a20c041 | 2022-11-09 19:14:54 -0700 | [diff] [blame] | 1341 | Binman commands and arguments |
| 1342 | ============================= |
| 1343 | |
| 1344 | Usage:: |
| 1345 | |
| 1346 | binman [-h] [-B BUILD_DIR] [-D] [-H] [--toolpath TOOLPATH] [-T THREADS] |
| 1347 | [--test-section-timeout] [-v VERBOSITY] [-V] |
| 1348 | {build,bintool-docs,entry-docs,ls,extract,replace,test,tool} ... |
| 1349 | |
| 1350 | Binman provides the following commands: |
| 1351 | |
| 1352 | - **build** - build images |
| 1353 | - **bintools-docs** - generate documentation about bintools |
| 1354 | - **entry-docs** - generate documentation about entry types |
| 1355 | - **ls** - list an image |
| 1356 | - **extract** - extract files from an image |
| 1357 | - **replace** - replace one or more entries in an image |
| 1358 | - **test** - run tests |
| 1359 | - **tool** - manage bintools |
| 1360 | |
| 1361 | Options: |
| 1362 | |
| 1363 | -h, --help |
| 1364 | Show help message and exit |
| 1365 | |
| 1366 | -B BUILD_DIR, --build-dir BUILD_DIR |
| 1367 | Directory containing the build output |
| 1368 | |
| 1369 | -D, --debug |
| 1370 | Enabling debugging (provides a full traceback on error) |
| 1371 | |
| 1372 | -H, --full-help |
| 1373 | Display the README file |
| 1374 | |
| 1375 | --toolpath TOOLPATH |
| 1376 | Add a path to the directories containing tools |
| 1377 | |
| 1378 | -T THREADS, --threads THREADS |
| 1379 | Number of threads to use (0=single-thread). Note that -T0 is useful for |
| 1380 | debugging since everything runs in one thread. |
| 1381 | |
| 1382 | -v VERBOSITY, --verbosity VERBOSITY |
| 1383 | Control verbosity: 0=silent, 1=warnings, 2=notices, 3=info, 4=detail, |
| 1384 | 5=debug |
| 1385 | |
| 1386 | -V, --version |
| 1387 | Show the binman version |
| 1388 | |
| 1389 | Test options: |
| 1390 | |
| 1391 | --test-section-timeout |
| 1392 | Use a zero timeout for section multi-threading (for testing) |
| 1393 | |
| 1394 | Commands are described below. |
| 1395 | |
| 1396 | binman build |
| 1397 | ------------ |
| 1398 | |
| 1399 | This builds one or more images using the provided image description. |
| 1400 | |
| 1401 | Usage:: |
| 1402 | |
| 1403 | binman build [-h] [-a ENTRY_ARG] [-b BOARD] [-d DT] [--fake-dtb] |
| 1404 | [--fake-ext-blobs] [--force-missing-bintools FORCE_MISSING_BINTOOLS] |
| 1405 | [-i IMAGE] [-I INDIR] [-m] [-M] [-n] [-O OUTDIR] [-p] [-u] |
| 1406 | [--update-fdt-in-elf UPDATE_FDT_IN_ELF] [-W] |
| 1407 | |
| 1408 | Options: |
| 1409 | |
| 1410 | -h, --help |
| 1411 | Show help message and exit |
| 1412 | |
| 1413 | -a ENTRY_ARG, --entry-arg ENTRY_ARG |
| 1414 | Set argument value `arg=value`. See |
| 1415 | `Passing command-line arguments to entries`_. |
| 1416 | |
| 1417 | -b BOARD, --board BOARD |
| 1418 | Board name to build. This can be used instead of `-d`, in which case the |
| 1419 | file `u-boot.dtb` is used, within the build directory's board subdirectory. |
| 1420 | |
| 1421 | -d DT, --dt DT |
| 1422 | Configuration file (.dtb) to use. This must have a top-level node called |
| 1423 | `binman`. See `Image description format`_. |
| 1424 | |
| 1425 | -i IMAGE, --image IMAGE |
| 1426 | Image filename to build (if not specified, build all) |
| 1427 | |
| 1428 | -I INDIR, --indir INDIR |
| 1429 | Add a path to the list of directories to use for input files. This can be |
| 1430 | specified multiple times to add more than one path. |
| 1431 | |
| 1432 | -m, --map |
| 1433 | Output a map file for each image. See `Map files`_. |
| 1434 | |
| 1435 | -M, --allow-missing |
| 1436 | Allow external blobs and bintools to be missing. See `External blobs`_. |
| 1437 | |
| 1438 | -n, --no-expanded |
| 1439 | Don't use 'expanded' versions of entries where available; normally 'u-boot' |
| 1440 | becomes 'u-boot-expanded', for example. See `Expanded entries`_. |
| 1441 | |
| 1442 | -O OUTDIR, --outdir OUTDIR |
| 1443 | Path to directory to use for intermediate and output files |
| 1444 | |
| 1445 | -p, --preserve |
| 1446 | Preserve temporary output directory even if option -O is not given |
| 1447 | |
| 1448 | -u, --update-fdt |
| 1449 | Update the binman node with offset/size info. See |
| 1450 | `Access to binman entry offsets at run time (fdt)`_. |
| 1451 | |
| 1452 | --update-fdt-in-elf UPDATE_FDT_IN_ELF |
| 1453 | Update an ELF file with the output dtb. The argument is a string consisting |
| 1454 | of four parts, separated by commas. See `Updating an ELF file`_. |
| 1455 | |
| 1456 | -W, --ignore-missing |
| 1457 | Return success even if there are missing blobs/bintools (requires -M) |
| 1458 | |
| 1459 | Options used only for testing: |
| 1460 | |
| 1461 | --fake-dtb |
| 1462 | Use fake device tree contents |
| 1463 | |
| 1464 | --fake-ext-blobs |
| 1465 | Create fake ext blobs with dummy content |
| 1466 | |
| 1467 | --force-missing-bintools FORCE_MISSING_BINTOOLS |
| 1468 | Comma-separated list of bintools to consider missing |
| 1469 | |
| 1470 | binman bintool-docs |
| 1471 | ------------------- |
| 1472 | |
| 1473 | Usage:: |
| 1474 | |
| 1475 | binman bintool-docs [-h] |
| 1476 | |
| 1477 | This outputs documentation for the bintools in rST format. See |
| 1478 | `Bintool Documentation`_. |
| 1479 | |
| 1480 | binman entry-docs |
| 1481 | ----------------- |
| 1482 | |
| 1483 | Usage:: |
| 1484 | |
| 1485 | binman entry-docs [-h] |
| 1486 | |
| 1487 | This outputs documentation for the entry types in rST format. See |
| 1488 | `Entry Documentation`_. |
| 1489 | |
| 1490 | binman ls |
| 1491 | --------- |
| 1492 | |
| 1493 | Usage:: |
| 1494 | |
| 1495 | binman ls [-h] -i IMAGE [paths ...] |
| 1496 | |
| 1497 | Positional arguments: |
| 1498 | |
| 1499 | paths |
| 1500 | Paths within file to list (wildcard) |
| 1501 | |
| 1502 | Pptions: |
| 1503 | |
| 1504 | -h, --help |
| 1505 | show help message and exit |
| 1506 | |
| 1507 | -i IMAGE, --image IMAGE |
| 1508 | Image filename to list |
| 1509 | |
| 1510 | This lists an image, showing its contents. See `Listing images`_. |
| 1511 | |
| 1512 | binman extract |
| 1513 | -------------- |
| 1514 | |
| 1515 | Usage:: |
| 1516 | |
| 1517 | binman extract [-h] [-F FORMAT] -i IMAGE [-f FILENAME] [-O OUTDIR] [-U] |
| 1518 | [paths ...] |
| 1519 | |
| 1520 | Positional arguments: |
| 1521 | |
| 1522 | Paths |
| 1523 | Paths within file to extract (wildcard) |
| 1524 | |
| 1525 | Options: |
| 1526 | |
| 1527 | -h, --help |
| 1528 | show help message and exit |
| 1529 | |
| 1530 | -F FORMAT, --format FORMAT |
| 1531 | Select an alternative format for extracted data |
| 1532 | |
| 1533 | -i IMAGE, --image IMAGE |
| 1534 | Image filename to extract |
| 1535 | |
| 1536 | -f FILENAME, --filename FILENAME |
| 1537 | Output filename to write to |
| 1538 | |
| 1539 | -O OUTDIR, --outdir OUTDIR |
| 1540 | Path to directory to use for output files |
| 1541 | |
| 1542 | -U, --uncompressed |
| 1543 | Output raw uncompressed data for compressed entries |
| 1544 | |
| 1545 | This extracts the contents of entries from an image. See |
| 1546 | `Extracting files from images`_. |
| 1547 | |
| 1548 | binman replace |
| 1549 | -------------- |
| 1550 | |
| 1551 | Usage:: |
| 1552 | |
| 1553 | binman replace [-h] [-C] -i IMAGE [-f FILENAME] [-F] [-I INDIR] [-m] |
| 1554 | [paths ...] |
| 1555 | |
| 1556 | Positional arguments: |
| 1557 | |
| 1558 | paths |
| 1559 | Paths within file to replace (wildcard) |
| 1560 | |
| 1561 | Options: |
| 1562 | |
| 1563 | -h, --help |
| 1564 | show help message and exit |
| 1565 | |
| 1566 | -C, --compressed |
| 1567 | Input data is already compressed if needed for the entry |
| 1568 | |
| 1569 | -i IMAGE, --image IMAGE |
| 1570 | Image filename to update |
| 1571 | |
| 1572 | -f FILENAME, --filename FILENAME |
| 1573 | Input filename to read from |
| 1574 | |
| 1575 | -F, --fix-size |
| 1576 | Don't allow entries to be resized |
| 1577 | |
| 1578 | -I INDIR, --indir INDIR |
| 1579 | Path to directory to use for input files |
| 1580 | |
| 1581 | -m, --map |
| 1582 | Output a map file for the updated image |
| 1583 | |
| 1584 | This replaces one or more entries in an existing image. See |
| 1585 | `Replacing files in an image`_. |
| 1586 | |
| 1587 | binman test |
| 1588 | ----------- |
| 1589 | |
| 1590 | Usage:: |
| 1591 | |
| 1592 | binman test [-h] [-P PROCESSES] [-T] [-X] [tests ...] |
| 1593 | |
| 1594 | Positional arguments: |
| 1595 | |
| 1596 | tests |
| 1597 | Test names to run (omit for all) |
| 1598 | |
| 1599 | Options: |
| 1600 | |
| 1601 | -h, --help |
| 1602 | show help message and exit |
| 1603 | |
| 1604 | -P PROCESSES, --processes PROCESSES |
| 1605 | set number of processes to use for running tests. This defaults to the |
| 1606 | number of CPUs on the machine |
| 1607 | |
| 1608 | -T, --test-coverage |
| 1609 | run tests and check for 100% coverage |
| 1610 | |
| 1611 | -X, --test-preserve-dirs |
| 1612 | Preserve and display test-created input directories; also preserve the |
| 1613 | output directory if a single test is run (pass test name at the end of the |
| 1614 | command line |
| 1615 | |
| 1616 | binman tool |
| 1617 | ----------- |
| 1618 | |
| 1619 | Usage:: |
| 1620 | |
| 1621 | binman tool [-h] [-l] [-f] [bintools ...] |
| 1622 | |
| 1623 | Positional arguments: |
| 1624 | |
| 1625 | bintools |
| 1626 | Bintools to process |
| 1627 | |
| 1628 | Options: |
| 1629 | |
| 1630 | -h, --help |
| 1631 | show help message and exit |
| 1632 | |
| 1633 | -l, --list |
| 1634 | List all known bintools |
| 1635 | |
| 1636 | -f, --fetch |
| 1637 | Fetch a bintool from a known location. Use `all` to fetch all and `missing` |
| 1638 | to fetch any missing tools. |
| 1639 | |
Simon Glass | 4142486 | 2022-01-09 20:14:12 -0700 | [diff] [blame] | 1640 | |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 1641 | Technical details |
| 1642 | ================= |
Simon Glass | 7223245 | 2016-11-25 20:15:53 -0700 | [diff] [blame] | 1643 | |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1644 | Order of image creation |
| 1645 | ----------------------- |
| 1646 | |
| 1647 | Image creation proceeds in the following order, for each entry in the image. |
| 1648 | |
Simon Glass | e22f8fa | 2018-07-06 10:27:41 -0600 | [diff] [blame] | 1649 | 1. AddMissingProperties() - binman can add calculated values to the device |
Simon Glass | e8561af | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 1650 | tree as part of its processing, for example the offset and size of each |
Simon Glass | e22f8fa | 2018-07-06 10:27:41 -0600 | [diff] [blame] | 1651 | entry. This method adds any properties associated with this, expanding the |
| 1652 | device tree as needed. These properties can have placeholder values which are |
| 1653 | set later by SetCalculatedProperties(). By that stage the size of sections |
| 1654 | cannot be changed (since it would cause the images to need to be repacked), |
| 1655 | but the correct values can be inserted. |
| 1656 | |
| 1657 | 2. ProcessFdt() - process the device tree information as required by the |
Simon Glass | 9230773 | 2018-07-06 10:27:40 -0600 | [diff] [blame] | 1658 | particular entry. This may involve adding or deleting properties. If the |
| 1659 | processing is complete, this method should return True. If the processing |
| 1660 | cannot complete because it needs the ProcessFdt() method of another entry to |
| 1661 | run first, this method should return False, in which case it will be called |
| 1662 | again later. |
| 1663 | |
Simon Glass | e22f8fa | 2018-07-06 10:27:41 -0600 | [diff] [blame] | 1664 | 3. GetEntryContents() - the contents of each entry are obtained, normally by |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1665 | reading from a file. This calls the Entry.ObtainContents() to read the |
| 1666 | contents. The default version of Entry.ObtainContents() calls |
| 1667 | Entry.GetDefaultFilename() and then reads that file. So a common mechanism |
| 1668 | to select a file to read is to override that function in the subclass. The |
| 1669 | functions must return True when they have read the contents. Binman will |
| 1670 | retry calling the functions a few times if False is returned, allowing |
| 1671 | dependencies between the contents of different entries. |
| 1672 | |
Simon Glass | e8561af | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 1673 | 4. GetEntryOffsets() - calls Entry.GetOffsets() for each entry. This can |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1674 | return a dict containing entries that need updating. The key should be the |
Simon Glass | e8561af | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 1675 | entry name and the value is a tuple (offset, size). This allows an entry to |
| 1676 | provide the offset and size for other entries. The default implementation |
| 1677 | of GetEntryOffsets() returns {}. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1678 | |
Simon Glass | e8561af | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 1679 | 5. PackEntries() - calls Entry.Pack() which figures out the offset and |
| 1680 | size of an entry. The 'current' image offset is passed in, and the function |
| 1681 | returns the offset immediately after the entry being packed. The default |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1682 | implementation of Pack() is usually sufficient. |
| 1683 | |
Simon Glass | 2d9570d | 2020-10-26 17:40:22 -0600 | [diff] [blame] | 1684 | Note: for sections, this also checks that the entries do not overlap, nor extend |
| 1685 | outside the section. If the section does not have a defined size, the size is |
| 1686 | set large enough to hold all the entries. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1687 | |
Simon Glass | 2d9570d | 2020-10-26 17:40:22 -0600 | [diff] [blame] | 1688 | 6. SetImagePos() - sets the image position of every entry. This is the absolute |
Simon Glass | 4b05b2d | 2019-07-20 12:23:52 -0600 | [diff] [blame] | 1689 | position 'image-pos', as opposed to 'offset' which is relative to the containing |
| 1690 | section. This must be done after all offsets are known, which is why it is quite |
| 1691 | late in the ordering. |
| 1692 | |
Simon Glass | 2d9570d | 2020-10-26 17:40:22 -0600 | [diff] [blame] | 1693 | 7. SetCalculatedProperties() - update any calculated properties in the device |
Simon Glass | e8561af | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 1694 | tree. This sets the correct 'offset' and 'size' vaues, for example. |
Simon Glass | e22f8fa | 2018-07-06 10:27:41 -0600 | [diff] [blame] | 1695 | |
Simon Glass | 2d9570d | 2020-10-26 17:40:22 -0600 | [diff] [blame] | 1696 | 8. ProcessEntryContents() - this calls Entry.ProcessContents() on each entry. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1697 | The default implementatoin does nothing. This can be overriden to adjust the |
| 1698 | contents of an entry in some way. For example, it would be possible to create |
| 1699 | an entry containing a hash of the contents of some other entries. At this |
Simon Glass | e61b6f6 | 2019-07-08 14:25:37 -0600 | [diff] [blame] | 1700 | stage the offset and size of entries should not be adjusted unless absolutely |
| 1701 | necessary, since it requires a repack (going back to PackEntries()). |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1702 | |
Simon Glass | 2d9570d | 2020-10-26 17:40:22 -0600 | [diff] [blame] | 1703 | 9. ResetForPack() - if the ProcessEntryContents() step failed, in that an entry |
Simon Glass | 4b05b2d | 2019-07-20 12:23:52 -0600 | [diff] [blame] | 1704 | has changed its size, then there is no alternative but to go back to step 5 and |
| 1705 | try again, repacking the entries with the updated size. ResetForPack() removes |
| 1706 | the fixed offset/size values added by binman, so that the packing can start from |
| 1707 | scratch. |
| 1708 | |
Simon Glass | 2d9570d | 2020-10-26 17:40:22 -0600 | [diff] [blame] | 1709 | 10. WriteSymbols() - write the value of symbols into the U-Boot SPL binary. |
Simon Glass | e8561af | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 1710 | See 'Access to binman entry offsets at run time' below for a description of |
Simon Glass | 29dae67 | 2018-07-06 10:27:39 -0600 | [diff] [blame] | 1711 | what happens in this stage. |
Simon Glass | be83bc7 | 2017-11-13 18:55:05 -0700 | [diff] [blame] | 1712 | |
Simon Glass | 2d9570d | 2020-10-26 17:40:22 -0600 | [diff] [blame] | 1713 | 11. BuildImage() - builds the image and writes it to a file |
Simon Glass | 4b05b2d | 2019-07-20 12:23:52 -0600 | [diff] [blame] | 1714 | |
Simon Glass | 2d9570d | 2020-10-26 17:40:22 -0600 | [diff] [blame] | 1715 | 12. WriteMap() - writes a text file containing a map of the image. This is the |
Simon Glass | 4b05b2d | 2019-07-20 12:23:52 -0600 | [diff] [blame] | 1716 | final step. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1717 | |
| 1718 | |
Simon Glass | a922347 | 2022-11-09 19:14:49 -0700 | [diff] [blame] | 1719 | .. _`External tools`: |
| 1720 | |
Simon Glass | 6244fa4 | 2019-07-08 13:18:28 -0600 | [diff] [blame] | 1721 | External tools |
| 1722 | -------------- |
| 1723 | |
| 1724 | Binman can make use of external command-line tools to handle processing of |
| 1725 | entry contents or to generate entry contents. These tools are executed using |
| 1726 | the 'tools' module's Run() method. The tools generally must exist on the PATH, |
| 1727 | but the --toolpath option can be used to specify additional search paths to |
| 1728 | use. This option can be specified multiple times to add more than one path. |
| 1729 | |
Alper Nebi Yasak | fb4e538 | 2020-09-06 14:46:07 +0300 | [diff] [blame] | 1730 | For some compile tools binman will use the versions specified by commonly-used |
| 1731 | environment variables like CC and HOSTCC for the C compiler, based on whether |
| 1732 | the tool's output will be used for the target or for the host machine. If those |
| 1733 | aren't given, it will also try to derive target-specific versions from the |
| 1734 | CROSS_COMPILE environment variable during a cross-compilation. |
| 1735 | |
Simon Glass | 31cce97 | 2021-11-23 21:09:48 -0700 | [diff] [blame] | 1736 | If the tool is not available in the path you can use BINMAN_TOOLPATHS to specify |
| 1737 | a space-separated list of paths to search, e.g.:: |
| 1738 | |
| 1739 | BINMAN_TOOLPATHS="/tools/g12a /tools/tegra" binman ... |
| 1740 | |
| 1741 | |
Simon Glass | a922347 | 2022-11-09 19:14:49 -0700 | [diff] [blame] | 1742 | .. _`External blobs`: |
| 1743 | |
Simon Glass | 31cce97 | 2021-11-23 21:09:48 -0700 | [diff] [blame] | 1744 | External blobs |
| 1745 | -------------- |
| 1746 | |
| 1747 | Binary blobs, even if the source code is available, complicate building |
| 1748 | firmware. The instructions can involve multiple steps and the binaries may be |
| 1749 | hard to build or obtain. Binman at least provides a unified description of how |
| 1750 | to build the final image, no matter what steps are needed to get there. |
| 1751 | |
| 1752 | Binman also provides a `blob-ext` entry type that pulls in a binary blob from an |
| 1753 | external file. If the file is missing, binman can optionally complete the build |
| 1754 | and just report a warning. Use the `-M/--allow-missing` option to enble this. |
| 1755 | This is useful in CI systems which want to check that everything is correct but |
| 1756 | don't have access to the blobs. |
| 1757 | |
| 1758 | If the blobs are in a different directory, you can specify this with the `-I` |
| 1759 | option. |
| 1760 | |
| 1761 | For U-Boot, you can use set the BINMAN_INDIRS environment variable to provide a |
| 1762 | space-separated list of directories to search for binary blobs:: |
| 1763 | |
| 1764 | BINMAN_INDIRS="odroid-c4/fip/g12a \ |
| 1765 | odroid-c4/build/board/hardkernel/odroidc4/firmware \ |
| 1766 | odroid-c4/build/scp_task" binman ... |
Simon Glass | 6244fa4 | 2019-07-08 13:18:28 -0600 | [diff] [blame] | 1767 | |
Simon Glass | 6bce5dc | 2022-11-09 19:14:42 -0700 | [diff] [blame] | 1768 | Note that binman fails with exit code 103 when there are missing blobs. If you |
| 1769 | wish binman to continue anyway, you can pass `-W` to binman. |
| 1770 | |
| 1771 | |
Simon Glass | 52debad | 2016-11-25 20:15:59 -0700 | [diff] [blame] | 1772 | Code coverage |
| 1773 | ------------- |
| 1774 | |
| 1775 | Binman is a critical tool and is designed to be very testable. Entry |
Simon Glass | f46732a | 2019-07-08 14:25:29 -0600 | [diff] [blame] | 1776 | implementations target 100% test coverage. Run 'binman test -T' to check this. |
Simon Glass | 52debad | 2016-11-25 20:15:59 -0700 | [diff] [blame] | 1777 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 1778 | To enable Python test coverage on Debian-type distributions (e.g. Ubuntu):: |
Simon Glass | 52debad | 2016-11-25 20:15:59 -0700 | [diff] [blame] | 1779 | |
Simon Glass | a16dd6e | 2019-07-08 13:18:26 -0600 | [diff] [blame] | 1780 | $ sudo apt-get install python-coverage python3-coverage python-pytest |
Simon Glass | 52debad | 2016-11-25 20:15:59 -0700 | [diff] [blame] | 1781 | |
| 1782 | |
Simon Glass | 6bce5dc | 2022-11-09 19:14:42 -0700 | [diff] [blame] | 1783 | Exit status |
| 1784 | ----------- |
| 1785 | |
| 1786 | Binman produces the following exit codes: |
| 1787 | |
| 1788 | 0 |
| 1789 | Success |
| 1790 | |
| 1791 | 1 |
| 1792 | Any sort of failure - see output for more details |
| 1793 | |
| 1794 | 103 |
| 1795 | There are missing external blobs or bintools. This is only returned if |
| 1796 | -M is passed to binman, otherwise missing blobs return an exit status of 1. |
| 1797 | Note, if -W is passed as well as -M, then this is converted into a warning |
| 1798 | and will return an exit status of 0 instead. |
| 1799 | |
| 1800 | |
Simon Glass | a922347 | 2022-11-09 19:14:49 -0700 | [diff] [blame] | 1801 | U-Boot environment variables for binman |
| 1802 | --------------------------------------- |
| 1803 | |
| 1804 | The U-Boot Makefile supports various environment variables to control binman. |
| 1805 | All of these are set within the Makefile and result in passing various |
| 1806 | environment variables (or make flags) to binman: |
| 1807 | |
| 1808 | BINMAN_DEBUG |
| 1809 | Enables backtrace debugging by adding a `-D` argument. See |
| 1810 | :ref:`BinmanLogging`. |
| 1811 | |
| 1812 | BINMAN_INDIRS |
| 1813 | Sets the search path for input files used by binman by adding one or more |
| 1814 | `-I` arguments. See :ref:`External blobs`. |
| 1815 | |
| 1816 | BINMAN_TOOLPATHS |
| 1817 | Sets the search path for external tool used by binman by adding one or more |
| 1818 | `--toolpath` arguments. See :ref:`External tools`. |
| 1819 | |
| 1820 | BINMAN_VERBOSE |
| 1821 | Sets the logging verbosity of binman by adding a `-v` argument. See |
| 1822 | :ref:`BinmanLogging`. |
| 1823 | |
| 1824 | |
Simon Glass | ddd5e1d | 2022-01-23 12:55:46 -0700 | [diff] [blame] | 1825 | Error messages |
| 1826 | -------------- |
| 1827 | |
| 1828 | This section provides some guidance for some of the less obvious error messages |
| 1829 | produced by binman. |
| 1830 | |
| 1831 | |
| 1832 | Expected __bss_size symbol |
| 1833 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1834 | |
| 1835 | Example:: |
| 1836 | |
| 1837 | binman: Node '/binman/u-boot-spl-ddr/u-boot-spl/u-boot-spl-bss-pad': |
| 1838 | Expected __bss_size symbol in spl/u-boot-spl |
| 1839 | |
| 1840 | This indicates that binman needs the `__bss_size` symbol to be defined in the |
| 1841 | SPL binary, where `spl/u-boot-spl` is the ELF file containing the symbols. The |
| 1842 | symbol tells binman the size of the BSS region, in bytes. It needs this to be |
| 1843 | able to pad the image so that the following entries do not overlap the BSS, |
| 1844 | which would cause them to be overwritte by variable access in SPL. |
| 1845 | |
| 1846 | This symbols is normally defined in the linker script, immediately after |
| 1847 | _bss_start and __bss_end are defined, like this:: |
| 1848 | |
| 1849 | __bss_size = __bss_end - __bss_start; |
| 1850 | |
| 1851 | You may need to add it to your linker script if you get this error. |
| 1852 | |
| 1853 | |
Simon Glass | 1aeb751 | 2019-05-17 22:00:52 -0600 | [diff] [blame] | 1854 | Concurrent tests |
| 1855 | ---------------- |
| 1856 | |
| 1857 | Binman tries to run tests concurrently. This means that the tests make use of |
| 1858 | all available CPUs to run. |
| 1859 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 1860 | To enable this:: |
Simon Glass | 1aeb751 | 2019-05-17 22:00:52 -0600 | [diff] [blame] | 1861 | |
| 1862 | $ sudo apt-get install python-subunit python3-subunit |
| 1863 | |
| 1864 | Use '-P 1' to disable this. It is automatically disabled when code coverage is |
| 1865 | being used (-T) since they are incompatible. |
| 1866 | |
| 1867 | |
Simon Glass | 1c420c9 | 2019-07-08 13:18:49 -0600 | [diff] [blame] | 1868 | Debugging tests |
| 1869 | --------------- |
| 1870 | |
| 1871 | Sometimes when debugging tests it is useful to keep the input and output |
| 1872 | directories so they can be examined later. Use -X or --test-preserve-dirs for |
| 1873 | this. |
| 1874 | |
| 1875 | |
Alper Nebi Yasak | fb4e538 | 2020-09-06 14:46:07 +0300 | [diff] [blame] | 1876 | Running tests on non-x86 architectures |
| 1877 | -------------------------------------- |
| 1878 | |
| 1879 | Binman's tests have been written under the assumption that they'll be run on a |
| 1880 | x86-like host and there hasn't been an attempt to make them portable yet. |
| 1881 | However, it's possible to run the tests by cross-compiling to x86. |
| 1882 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 1883 | To install an x86 cross-compiler on Debian-type distributions (e.g. Ubuntu):: |
Alper Nebi Yasak | fb4e538 | 2020-09-06 14:46:07 +0300 | [diff] [blame] | 1884 | |
| 1885 | $ sudo apt-get install gcc-x86-64-linux-gnu |
| 1886 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 1887 | Then, you can run the tests under cross-compilation:: |
Alper Nebi Yasak | fb4e538 | 2020-09-06 14:46:07 +0300 | [diff] [blame] | 1888 | |
| 1889 | $ CROSS_COMPILE=x86_64-linux-gnu- binman test -T |
| 1890 | |
| 1891 | You can also use gcc-i686-linux-gnu similar to the above. |
| 1892 | |
| 1893 | |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 1894 | Writing new entries and debugging |
| 1895 | --------------------------------- |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1896 | |
| 1897 | The behaviour of entries is defined by the Entry class. All other entries are |
| 1898 | a subclass of this. An important subclass is Entry_blob which takes binary |
| 1899 | data from a file and places it in the entry. In fact most entry types are |
| 1900 | subclasses of Entry_blob. |
| 1901 | |
| 1902 | Each entry type is a separate file in the tools/binman/etype directory. Each |
| 1903 | file contains a class called Entry_<type> where <type> is the entry type. |
| 1904 | New entry types can be supported by adding new files in that directory. |
| 1905 | These will automatically be detected by binman when needed. |
| 1906 | |
| 1907 | Entry properties are documented in entry.py. The entry subclasses are free |
| 1908 | to change the values of properties to support special behaviour. For example, |
| 1909 | when Entry_blob loads a file, it sets content_size to the size of the file. |
| 1910 | Entry classes can adjust other entries. For example, an entry that knows |
Simon Glass | e8561af | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 1911 | where other entries should be positioned can set up those entries' offsets |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1912 | so they don't need to be set in the binman decription. It can also adjust |
| 1913 | entry contents. |
| 1914 | |
| 1915 | Most of the time such essoteric behaviour is not needed, but it can be |
| 1916 | essential for complex images. |
| 1917 | |
Simon Glass | ade2ef6 | 2017-12-24 12:12:07 -0700 | [diff] [blame] | 1918 | If you need to specify a particular device-tree compiler to use, you can define |
| 1919 | the DTC environment variable. This can be useful when the system dtc is too |
| 1920 | old. |
| 1921 | |
Simon Glass | e64a092 | 2018-11-06 15:21:31 -0700 | [diff] [blame] | 1922 | To enable a full backtrace and other debugging features in binman, pass |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 1923 | BINMAN_DEBUG=1 to your build:: |
Simon Glass | e64a092 | 2018-11-06 15:21:31 -0700 | [diff] [blame] | 1924 | |
Bin Meng | a089c41 | 2019-10-02 19:07:29 -0700 | [diff] [blame] | 1925 | make qemu-x86_defconfig |
Simon Glass | e64a092 | 2018-11-06 15:21:31 -0700 | [diff] [blame] | 1926 | make BINMAN_DEBUG=1 |
| 1927 | |
Simon Glass | 03b1d8f | 2019-09-25 08:11:11 -0600 | [diff] [blame] | 1928 | To enable verbose logging from binman, base BINMAN_VERBOSE to your build, which |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 1929 | adds a -v<level> option to the call to binman:: |
Simon Glass | 03b1d8f | 2019-09-25 08:11:11 -0600 | [diff] [blame] | 1930 | |
Bin Meng | a089c41 | 2019-10-02 19:07:29 -0700 | [diff] [blame] | 1931 | make qemu-x86_defconfig |
Simon Glass | 03b1d8f | 2019-09-25 08:11:11 -0600 | [diff] [blame] | 1932 | make BINMAN_VERBOSE=5 |
| 1933 | |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1934 | |
Simon Glass | 76f496d | 2021-07-06 10:36:37 -0600 | [diff] [blame] | 1935 | Building sections in parallel |
| 1936 | ----------------------------- |
| 1937 | |
| 1938 | By default binman uses multiprocessing to speed up compilation of large images. |
| 1939 | This works at a section level, with one thread for each entry in the section. |
| 1940 | This can speed things up if the entries are large and use compression. |
| 1941 | |
| 1942 | This feature can be disabled with the '-T' flag, which defaults to a suitable |
| 1943 | value for your machine. This depends on the Python version, e.g on v3.8 it uses |
| 1944 | 12 threads on an 8-core machine. See ConcurrentFutures_ for more details. |
| 1945 | |
| 1946 | The special value -T0 selects single-threaded mode, useful for debugging during |
| 1947 | development, since dealing with exceptions and problems in threads is more |
| 1948 | difficult. This avoids any use of ThreadPoolExecutor. |
| 1949 | |
| 1950 | |
Simon Glass | 6fba35c | 2022-02-08 11:50:00 -0700 | [diff] [blame] | 1951 | Collecting data for an entry type |
| 1952 | --------------------------------- |
| 1953 | |
| 1954 | Some entry types deal with data obtained from others. For example, |
| 1955 | `Entry_mkimage` calls the `mkimage` tool with data from its subnodes:: |
| 1956 | |
| 1957 | mkimage { |
| 1958 | args = "-n test -T script"; |
| 1959 | |
| 1960 | u-boot-spl { |
| 1961 | }; |
| 1962 | |
| 1963 | u-boot { |
| 1964 | }; |
| 1965 | }; |
| 1966 | |
| 1967 | This shows mkimage being passed a file consisting of SPL and U-Boot proper. It |
Simon Glass | 43a98cc | 2022-03-05 20:18:58 -0700 | [diff] [blame] | 1968 | is created by calling `Entry.collect_contents_to_file()`. Note that in this |
| 1969 | case, the data is passed to mkimage for processing but does not appear |
| 1970 | separately in the image. It may not appear at all, depending on what mkimage |
| 1971 | does. The contents of the `mkimage` entry are entirely dependent on the |
| 1972 | processing done by the entry, with the provided subnodes (`u-boot-spl` and |
| 1973 | `u-boot`) simply providing the input data for that processing. |
Simon Glass | 6fba35c | 2022-02-08 11:50:00 -0700 | [diff] [blame] | 1974 | |
| 1975 | Note that `Entry.collect_contents_to_file()` simply concatenates the data from |
| 1976 | the different entries together, with no control over alignment, etc. Another |
| 1977 | approach is to subclass `Entry_section` so that those features become available, |
| 1978 | such as `size` and `pad-byte`. Then the contents of the entry can be obtained by |
Simon Glass | 43a98cc | 2022-03-05 20:18:58 -0700 | [diff] [blame] | 1979 | calling `super().BuildSectionData()` in the entry's BuildSectionData() |
| 1980 | implementation to get the input data, then write it to a file and process it |
| 1981 | however is desired. |
Simon Glass | 6fba35c | 2022-02-08 11:50:00 -0700 | [diff] [blame] | 1982 | |
| 1983 | There are other ways to obtain data also, depending on the situation. If the |
| 1984 | entry type is simply signing data which exists elsewhere in the image, then |
| 1985 | you can use `Entry_collection` as a base class. It lets you use a property |
| 1986 | called `content` which lists the entries containing data to be processed. This |
| 1987 | is used by `Entry_vblock`, for example:: |
| 1988 | |
| 1989 | u_boot: u-boot { |
| 1990 | }; |
Simon Glass | 43a98cc | 2022-03-05 20:18:58 -0700 | [diff] [blame] | 1991 | |
Simon Glass | 6fba35c | 2022-02-08 11:50:00 -0700 | [diff] [blame] | 1992 | vblock { |
| 1993 | content = <&u_boot &dtb>; |
| 1994 | keyblock = "firmware.keyblock"; |
| 1995 | signprivate = "firmware_data_key.vbprivk"; |
| 1996 | version = <1>; |
| 1997 | kernelkey = "kernel_subkey.vbpubk"; |
| 1998 | preamble-flags = <1>; |
| 1999 | }; |
| 2000 | |
| 2001 | dtb: u-boot-dtb { |
| 2002 | }; |
| 2003 | |
| 2004 | which shows an image containing `u-boot` and `u-boot-dtb`, with the `vblock` |
| 2005 | image collecting their contents to produce input for its signing process, |
| 2006 | without affecting those entries, which still appear in the final image |
| 2007 | untouched. |
| 2008 | |
| 2009 | Another example is where an entry type needs several independent pieces of input |
| 2010 | to function. For example, `Entry_fip` allows a number of different binary blobs |
| 2011 | to be placed in their own individual places in a custom data structure in the |
| 2012 | output image. To make that work you can add subnodes for each of them and call |
| 2013 | `Entry.Create()` on each subnode, as `Entry_fip` does. Then the data for each |
| 2014 | blob can come from any suitable place, such as an `Entry_u_boot` or an |
| 2015 | `Entry_blob` or anything else:: |
| 2016 | |
| 2017 | atf-fip { |
| 2018 | fip-hdr-flags = /bits/ 64 <0x123>; |
| 2019 | soc-fw { |
| 2020 | fip-flags = /bits/ 64 <0x123456789abcdef>; |
| 2021 | filename = "bl31.bin"; |
| 2022 | }; |
| 2023 | |
| 2024 | u-boot { |
| 2025 | fip-uuid = [fc 65 13 92 4a 5b 11 ec |
| 2026 | 94 35 ff 2d 1c fc 79 9c]; |
| 2027 | }; |
| 2028 | }; |
| 2029 | |
| 2030 | The `soc-fw` node is a `blob-ext` (i.e. it reads in a named binary file) whereas |
| 2031 | `u-boot` is a normal entry type. This works because `Entry_fip` selects the |
| 2032 | `blob-ext` entry type if the node name (here `soc-fw`) is recognised as being |
| 2033 | a known blob type. |
| 2034 | |
| 2035 | When adding new entry types you are encouraged to use subnodes to provide the |
Simon Glass | 43a98cc | 2022-03-05 20:18:58 -0700 | [diff] [blame] | 2036 | data for processing, unless the `content` approach is more suitable. Consider |
| 2037 | whether the input entries are contained within (or consumed by) the entry, vs |
| 2038 | just being 'referenced' by the entry. In the latter case, the `content` approach |
| 2039 | makes more sense. Ad-hoc properties and other methods of obtaining data are |
| 2040 | discouraged, since it adds to confusion for users. |
Simon Glass | 6fba35c | 2022-02-08 11:50:00 -0700 | [diff] [blame] | 2041 | |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 2042 | History / Credits |
| 2043 | ----------------- |
| 2044 | |
| 2045 | Binman takes a lot of inspiration from a Chrome OS tool called |
| 2046 | 'cros_bundle_firmware', which I wrote some years ago. That tool was based on |
| 2047 | a reasonably simple and sound design but has expanded greatly over the |
| 2048 | years. In particular its handling of x86 images is convoluted. |
| 2049 | |
Simon Glass | 1e32400 | 2018-06-01 09:38:19 -0600 | [diff] [blame] | 2050 | Quite a few lessons have been learned which are hopefully applied here. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 2051 | |
| 2052 | |
| 2053 | Design notes |
| 2054 | ------------ |
| 2055 | |
| 2056 | On the face of it, a tool to create firmware images should be fairly simple: |
| 2057 | just find all the input binaries and place them at the right place in the |
| 2058 | image. The difficulty comes from the wide variety of input types (simple |
| 2059 | flat binaries containing code, packaged data with various headers), packing |
| 2060 | requirments (alignment, spacing, device boundaries) and other required |
| 2061 | features such as hierarchical images. |
| 2062 | |
| 2063 | The design challenge is to make it easy to create simple images, while |
| 2064 | allowing the more complex cases to be supported. For example, for most |
| 2065 | images we don't much care exactly where each binary ends up, so we should |
| 2066 | not have to specify that unnecessarily. |
| 2067 | |
| 2068 | New entry types should aim to provide simple usage where possible. If new |
| 2069 | core features are needed, they can be added in the Entry base class. |
| 2070 | |
| 2071 | |
| 2072 | To do |
| 2073 | ----- |
| 2074 | |
| 2075 | Some ideas: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 2076 | |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 2077 | - Use of-platdata to make the information available to code that is unable |
Simon Glass | 774b23f | 2021-03-18 20:25:17 +1300 | [diff] [blame] | 2078 | to use device tree (such as a very small SPL image). For now, limited info is |
| 2079 | available via linker symbols |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 2080 | - Allow easy building of images by specifying just the board name |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 2081 | - Support building an image for a board (-b) more completely, with a |
| 2082 | configurable build directory |
Simon Glass | 8100a8e | 2019-07-20 12:24:02 -0600 | [diff] [blame] | 2083 | - Detect invalid properties in nodes |
| 2084 | - Sort the fdtmap by offset |
Simon Glass | 01ab229 | 2021-01-06 21:35:12 -0700 | [diff] [blame] | 2085 | - Output temporary files to a different directory |
Simon Glass | e87009da | 2022-02-08 11:49:57 -0700 | [diff] [blame] | 2086 | - Rationalise the fdt, fdt_util and pylibfdt modules which currently have some |
| 2087 | overlapping and confusing functionality |
| 2088 | - Update the fdt library to use a better format for Prop.value (the current one |
| 2089 | is useful for dtoc but not much else) |
| 2090 | - Figure out how to make Fdt support changing the node order, so that |
| 2091 | Node.AddSubnode() can support adding a node before another, existing node. |
| 2092 | Perhaps it should completely regenerate the flat tree? |
Simon Glass | fca3856 | 2022-08-18 02:16:46 -0600 | [diff] [blame] | 2093 | - Support images which depend on each other |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 2094 | |
| 2095 | -- |
| 2096 | Simon Glass <sjg@chromium.org> |
| 2097 | 7/7/2016 |
Simon Glass | 76f496d | 2021-07-06 10:36:37 -0600 | [diff] [blame] | 2098 | |
| 2099 | .. _ConcurrentFutures: https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.ThreadPoolExecutor |