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, |
| 45 | vblocks and and the like. |
| 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 | |
| 121 | |
| 122 | Relationship to mkimage |
| 123 | ----------------------- |
| 124 | |
| 125 | The mkimage tool provides a means to create a FIT. Traditionally it has |
| 126 | needed an image description file: a device tree, like binman, but in a |
| 127 | different format. More recently it has started to support a '-f auto' mode |
| 128 | which can generate that automatically. |
| 129 | |
| 130 | More relevant to binman, mkimage also permits creation of many SoC-specific |
| 131 | image types. These can be listed by running 'mkimage -T list'. Examples |
| 132 | include 'rksd', the Rockchip SD/MMC boot format. The mkimage tool is often |
| 133 | called from the U-Boot build system for this reason. |
| 134 | |
| 135 | Binman considers the output files created by mkimage to be binary blobs |
| 136 | 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] | 137 | 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] | 138 | 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] | 139 | 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] | 140 | the boundaries between building input files (mkimage) and packaging then |
| 141 | into a final image (binman). |
| 142 | |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 143 | |
| 144 | Using binman |
| 145 | ============ |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 146 | |
| 147 | Example use of binman in U-Boot |
| 148 | ------------------------------- |
| 149 | |
| 150 | Binman aims to replace some of the ad-hoc image creation in the U-Boot |
| 151 | build system. |
| 152 | |
| 153 | Consider sunxi. It has the following steps: |
| 154 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 155 | #. It uses a custom mksunxiboot tool to build an SPL image called |
| 156 | sunxi-spl.bin. This should probably move into mkimage. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 157 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 158 | #. It uses mkimage to package U-Boot into a legacy image file (so that it can |
| 159 | hold the load and execution address) called u-boot.img. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 160 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 161 | #. It builds a final output image called u-boot-sunxi-with-spl.bin which |
| 162 | consists of sunxi-spl.bin, some padding and u-boot.img. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 163 | |
| 164 | Binman is intended to replace the last step. The U-Boot build system builds |
| 165 | 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] | 166 | sunxi-spl.bin by calling mksunxiboot or mkimage. In any case, it would then |
| 167 | create the image from the component parts. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 168 | |
| 169 | This simplifies the U-Boot Makefile somewhat, since various pieces of logic |
| 170 | can be replaced by a call to binman. |
| 171 | |
| 172 | |
| 173 | Example use of binman for x86 |
| 174 | ----------------------------- |
| 175 | |
| 176 | In most cases x86 images have a lot of binary blobs, 'black-box' code |
| 177 | provided by Intel which must be run for the platform to work. Typically |
| 178 | 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] | 179 | firmware image. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 180 | |
| 181 | Currently this is handled by ifdtool, which places microcode, FSP, MRC, VGA |
| 182 | BIOS, reference code and Intel ME binaries into a u-boot.rom file. |
| 183 | |
| 184 | Binman is intended to replace all of this, with ifdtool left to handle only |
| 185 | the configuration of the Intel-format descriptor. |
| 186 | |
| 187 | |
Simon Glass | 7a7874f | 2022-01-09 20:13:48 -0700 | [diff] [blame] | 188 | Installing binman |
| 189 | ----------------- |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 190 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 191 | First install prerequisites, e.g:: |
Simon Glass | 567b682 | 2019-07-08 13:18:35 -0600 | [diff] [blame] | 192 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 193 | sudo apt-get install python-pyelftools python3-pyelftools lzma-alone \ |
| 194 | liblz4-tool |
Simon Glass | 567b682 | 2019-07-08 13:18:35 -0600 | [diff] [blame] | 195 | |
Simon Glass | 7a7874f | 2022-01-09 20:13:48 -0700 | [diff] [blame] | 196 | You can run binman directly if you put it on your PATH. But if you want to |
| 197 | install into your `~/.local` Python directory, use:: |
| 198 | |
| 199 | pip install tools/patman tools/dtoc tools/binman |
| 200 | |
| 201 | Note that binman makes use of libraries from patman and dtoc, which is why these |
| 202 | need to be installed. Also you need `libfdt` and `pylibfdt` which can be |
| 203 | installed like this:: |
| 204 | |
| 205 | git clone git://git.kernel.org/pub/scm/utils/dtc/dtc.git |
| 206 | cd dtc |
| 207 | pip install . |
| 208 | make NO_PYTHON=1 install |
| 209 | |
| 210 | This installs the `libfdt.so` library into `~/lib` so you can use |
| 211 | `LD_LIBRARY_PATH=~/lib` when running binman. If you want to install it in the |
| 212 | system-library directory, replace the last line with:: |
| 213 | |
| 214 | make NO_PYTHON=1 PREFIX=/ install |
| 215 | |
| 216 | Running binman |
| 217 | -------------- |
| 218 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 219 | Type:: |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 220 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 221 | binman build -b <board_name> |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 222 | |
| 223 | to build an image for a board. The board name is the same name used when |
| 224 | configuring U-Boot (e.g. for sandbox_defconfig the board name is 'sandbox'). |
| 225 | Binman assumes that the input files for the build are in ../b/<board_name>. |
| 226 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 227 | Or you can specify this explicitly:: |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 228 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 229 | binman build -I <build_path> |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 230 | |
| 231 | where <build_path> is the build directory containing the output of the U-Boot |
| 232 | build. |
| 233 | |
| 234 | (Future work will make this more configurable) |
| 235 | |
| 236 | In either case, binman picks up the device tree file (u-boot.dtb) and looks |
| 237 | for its instructions in the 'binman' node. |
| 238 | |
| 239 | Binman has a few other options which you can see by running 'binman -h'. |
| 240 | |
| 241 | |
Simon Glass | 4b94ac9 | 2017-11-12 21:52:06 -0700 | [diff] [blame] | 242 | Enabling binman for a board |
| 243 | --------------------------- |
| 244 | |
Simon Glass | 774b23f | 2021-03-18 20:25:17 +1300 | [diff] [blame] | 245 | At present binman is invoked from a rule in the main Makefile. You should be |
| 246 | able to enable CONFIG_BINMAN to enable this rule. |
Simon Glass | 4b94ac9 | 2017-11-12 21:52:06 -0700 | [diff] [blame] | 247 | |
Simon Glass | 774b23f | 2021-03-18 20:25:17 +1300 | [diff] [blame] | 248 | The output file is typically named image.bin and is located in the output |
| 249 | directory. If input files are needed to you add these to INPUTS-y either in the |
| 250 | main Makefile or in a config.mk file in your arch subdirectory. |
Simon Glass | 4b94ac9 | 2017-11-12 21:52:06 -0700 | [diff] [blame] | 251 | |
| 252 | Once binman is executed it will pick up its instructions from a device-tree |
| 253 | file, typically <soc>-u-boot.dtsi, where <soc> is your CONFIG_SYS_SOC value. |
| 254 | You can use other, more specific CONFIG options - see 'Automatic .dtsi |
| 255 | inclusion' below. |
| 256 | |
| 257 | |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 258 | Access to binman entry offsets at run time (symbols) |
| 259 | ---------------------------------------------------- |
| 260 | |
| 261 | Binman assembles images and determines where each entry is placed in the image. |
| 262 | This information may be useful to U-Boot at run time. For example, in SPL it |
| 263 | is useful to be able to find the location of U-Boot so that it can be executed |
| 264 | when SPL is finished. |
| 265 | |
| 266 | Binman allows you to declare symbols in the SPL image which are filled in |
| 267 | with their correct values during the build. For example:: |
| 268 | |
| 269 | binman_sym_declare(ulong, u_boot_any, image_pos); |
| 270 | |
| 271 | declares a ulong value which will be assigned to the image-pos of any U-Boot |
| 272 | image (u-boot.bin, u-boot.img, u-boot-nodtb.bin) that is present in the image. |
| 273 | You can access this value with something like:: |
| 274 | |
| 275 | ulong u_boot_offset = binman_sym(ulong, u_boot_any, image_pos); |
| 276 | |
| 277 | Thus u_boot_offset will be set to the image-pos of U-Boot in memory, assuming |
| 278 | that the whole image has been loaded, or is available in flash. You can then |
| 279 | jump to that address to start U-Boot. |
| 280 | |
| 281 | At present this feature is only supported in SPL and TPL. In principle it is |
| 282 | possible to fill in such symbols in U-Boot proper, as well, but a future C |
| 283 | library is planned for this instead, to read from the device tree. |
| 284 | |
| 285 | As well as image-pos, it is possible to read the size of an entry and its |
| 286 | offset (which is the start position of the entry within its parent). |
| 287 | |
| 288 | A small technical note: Binman automatically adds the base address of the image |
| 289 | (i.e. __image_copy_start) to the value of the image-pos symbol, so that when the |
| 290 | image is loaded to its linked address, the value will be correct and actually |
| 291 | point into the image. |
| 292 | |
| 293 | For example, say SPL is at the start of the image and linked to start at address |
| 294 | 80108000. If U-Boot's image-pos is 0x8000 then binman will write an image-pos |
| 295 | for U-Boot of 80110000 into the SPL binary, since it assumes the image is loaded |
| 296 | to 80108000, with SPL at 80108000 and U-Boot at 80110000. |
| 297 | |
| 298 | For x86 devices (with the end-at-4gb property) this base address is not added |
| 299 | since it is assumed that images are XIP and the offsets already include the |
| 300 | address. |
| 301 | |
| 302 | |
| 303 | Access to binman entry offsets at run time (fdt) |
| 304 | ------------------------------------------------ |
| 305 | |
| 306 | Binman can update the U-Boot FDT to include the final position and size of |
| 307 | each entry in the images it processes. The option to enable this is -u and it |
| 308 | causes binman to make sure that the 'offset', 'image-pos' and 'size' properties |
| 309 | are set correctly for every entry. Since it is not necessary to specify these in |
| 310 | the image definition, binman calculates the final values and writes these to |
| 311 | the device tree. These can be used by U-Boot at run-time to find the location |
| 312 | of each entry. |
| 313 | |
| 314 | Alternatively, an FDT map entry can be used to add a special FDT containing |
| 315 | just the information about the image. This is preceded by a magic string so can |
| 316 | be located anywhere in the image. An image header (typically at the start or end |
| 317 | of the image) can be used to point to the FDT map. See fdtmap and image-header |
| 318 | entries for more information. |
| 319 | |
| 320 | |
| 321 | Map files |
| 322 | --------- |
| 323 | |
| 324 | The -m option causes binman to output a .map file for each image that it |
| 325 | generates. This shows the offset and size of each entry. For example:: |
| 326 | |
| 327 | Offset Size Name |
| 328 | 00000000 00000028 main-section |
| 329 | 00000000 00000010 section@0 |
| 330 | 00000000 00000004 u-boot |
| 331 | 00000010 00000010 section@1 |
| 332 | 00000000 00000004 u-boot |
| 333 | |
| 334 | This shows a hierarchical image with two sections, each with a single entry. The |
| 335 | offsets of the sections are absolute hex byte offsets within the image. The |
| 336 | offsets of the entries are relative to their respective sections. The size of |
| 337 | each entry is also shown, in bytes (hex). The indentation shows the entries |
| 338 | nested inside their sections. |
| 339 | |
| 340 | |
| 341 | Passing command-line arguments to entries |
| 342 | ----------------------------------------- |
| 343 | |
| 344 | Sometimes it is useful to pass binman the value of an entry property from the |
| 345 | command line. For example some entries need access to files and it is not |
| 346 | always convenient to put these filenames in the image definition (device tree). |
| 347 | |
Bin Meng | 1fa2b7c | 2021-05-10 20:23:30 +0800 | [diff] [blame] | 348 | The -a option supports this:: |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 349 | |
Bin Meng | 1fa2b7c | 2021-05-10 20:23:30 +0800 | [diff] [blame] | 350 | -a <prop>=<value> |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 351 | |
| 352 | where:: |
| 353 | |
| 354 | <prop> is the property to set |
| 355 | <value> is the value to set it to |
| 356 | |
| 357 | Not all properties can be provided this way. Only some entries support it, |
| 358 | typically for filenames. |
| 359 | |
| 360 | |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 361 | Image description format |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 362 | ======================== |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 363 | |
| 364 | The binman node is called 'binman'. An example image description is shown |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 365 | below:: |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 366 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 367 | binman { |
| 368 | filename = "u-boot-sunxi-with-spl.bin"; |
| 369 | pad-byte = <0xff>; |
| 370 | blob { |
| 371 | filename = "spl/sunxi-spl.bin"; |
| 372 | }; |
| 373 | u-boot { |
| 374 | offset = <CONFIG_SPL_PAD_TO>; |
| 375 | }; |
| 376 | }; |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 377 | |
| 378 | |
| 379 | This requests binman to create an image file called u-boot-sunxi-with-spl.bin |
| 380 | consisting of a specially formatted SPL (spl/sunxi-spl.bin, built by the |
| 381 | normal U-Boot Makefile), some 0xff padding, and a U-Boot legacy image. The |
| 382 | padding comes from the fact that the second binary is placed at |
| 383 | CONFIG_SPL_PAD_TO. If that line were omitted then the U-Boot binary would |
| 384 | immediately follow the SPL binary. |
| 385 | |
| 386 | The binman node describes an image. The sub-nodes describe entries in the |
| 387 | image. Each entry represents a region within the overall image. The name of |
| 388 | the entry (blob, u-boot) tells binman what to put there. For 'blob' we must |
| 389 | provide a filename. For 'u-boot', binman knows that this means 'u-boot.bin'. |
| 390 | |
| 391 | Entries are normally placed into the image sequentially, one after the other. |
| 392 | 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] | 393 | specify the start offset of an entry using the 'offset' property. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 394 | |
| 395 | Note that due to a device tree requirement, all entries must have a unique |
| 396 | name. If you want to put the same binary in the image multiple times, you can |
| 397 | use any unique name, with the 'type' property providing the type. |
| 398 | |
| 399 | The attributes supported for entries are described below. |
| 400 | |
Simon Glass | e8561af | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 401 | offset: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 402 | This sets the offset of an entry within the image or section containing |
| 403 | it. The first byte of the image is normally at offset 0. If 'offset' is |
| 404 | not provided, binman sets it to the end of the previous region, or the |
| 405 | start of the image's entry area (normally 0) if there is no previous |
| 406 | region. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 407 | |
| 408 | align: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 409 | This sets the alignment of the entry. The entry offset is adjusted |
| 410 | so that the entry starts on an aligned boundary within the containing |
| 411 | section or image. For example 'align = <16>' means that the entry will |
| 412 | start on a 16-byte boundary. This may mean that padding is added before |
| 413 | the entry. The padding is part of the containing section but is not |
| 414 | included in the entry, meaning that an empty space may be created before |
| 415 | the entry starts. Alignment should be a power of 2. If 'align' is not |
| 416 | provided, no alignment is performed. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 417 | |
| 418 | size: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 419 | This sets the size of the entry. The contents will be padded out to |
| 420 | this size. If this is not provided, it will be set to the size of the |
| 421 | contents. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 422 | |
| 423 | pad-before: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 424 | Padding before the contents of the entry. Normally this is 0, meaning |
| 425 | that the contents start at the beginning of the entry. This can be used |
| 426 | to offset the entry contents a little. While this does not affect the |
| 427 | contents of the entry within binman itself (the padding is performed |
| 428 | only when its parent section is assembled), the end result will be that |
| 429 | 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] | 430 | |
| 431 | pad-after: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 432 | Padding after the contents of the entry. Normally this is 0, meaning |
| 433 | that the entry ends at the last byte of content (unless adjusted by |
| 434 | other properties). This allows room to be created in the image for |
| 435 | this entry to expand later. While this does not affect the contents of |
| 436 | the entry within binman itself (the padding is performed only when its |
| 437 | parent section is assembled), the end result will be that the entry ends |
| 438 | with the padding bytes, so may grow. Defaults to 0. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 439 | |
| 440 | align-size: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 441 | This sets the alignment of the entry size. For example, to ensure |
| 442 | that the size of an entry is a multiple of 64 bytes, set this to 64. |
| 443 | While this does not affect the contents of the entry within binman |
| 444 | itself (the padding is performed only when its parent section is |
| 445 | assembled), the end result is that the entry ends with the padding |
| 446 | bytes, so may grow. If 'align-size' is not provided, no alignment is |
| 447 | performed. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 448 | |
| 449 | align-end: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 450 | This sets the alignment of the end of an entry with respect to the |
| 451 | containing section. Some entries require that they end on an alignment |
| 452 | boundary, regardless of where they start. This does not move the start |
| 453 | of the entry, so the contents of the entry will still start at the |
| 454 | beginning. But there may be padding at the end. While this does not |
| 455 | affect the contents of the entry within binman itself (the padding is |
| 456 | performed only when its parent section is assembled), the end result |
| 457 | is that the entry ends with the padding bytes, so may grow. |
| 458 | If 'align-end' is not provided, no alignment is performed. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 459 | |
| 460 | filename: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 461 | For 'blob' types this provides the filename containing the binary to |
| 462 | put into the entry. If binman knows about the entry type (like |
| 463 | u-boot-bin), then there is no need to specify this. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 464 | |
| 465 | type: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 466 | Sets the type of an entry. This defaults to the entry name, but it is |
| 467 | possible to use any name, and then add (for example) 'type = "u-boot"' |
| 468 | to specify the type. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 469 | |
Simon Glass | e8561af | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 470 | offset-unset: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 471 | Indicates that the offset of this entry should not be set by placing |
| 472 | it immediately after the entry before. Instead, is set by another |
| 473 | entry which knows where this entry should go. When this boolean |
| 474 | property is present, binman will give an error if another entry does |
| 475 | not set the offset (with the GetOffsets() method). |
Simon Glass | 4ba8d50 | 2018-06-01 09:38:17 -0600 | [diff] [blame] | 476 | |
Simon Glass | 9dcc861 | 2018-08-01 15:22:42 -0600 | [diff] [blame] | 477 | image-pos: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 478 | This cannot be set on entry (or at least it is ignored if it is), but |
| 479 | with the -u option, binman will set it to the absolute image position |
| 480 | for each entry. This makes it easy to find out exactly where the entry |
| 481 | ended up in the image, regardless of parent sections, etc. |
Simon Glass | 9dcc861 | 2018-08-01 15:22:42 -0600 | [diff] [blame] | 482 | |
Simon Glass | fa79a81 | 2018-09-14 04:57:29 -0600 | [diff] [blame] | 483 | expand-size: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 484 | Expand the size of this entry to fit available space. This space is only |
| 485 | limited by the size of the image/section and the position of the next |
| 486 | entry. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 487 | |
Simon Glass | aa2fcf9 | 2019-07-08 14:25:30 -0600 | [diff] [blame] | 488 | compress: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 489 | Sets the compression algortihm to use (for blobs only). See the entry |
| 490 | documentation for details. |
Simon Glass | aa2fcf9 | 2019-07-08 14:25:30 -0600 | [diff] [blame] | 491 | |
Simon Glass | a820af7 | 2020-09-06 10:39:09 -0600 | [diff] [blame] | 492 | missing-msg: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 493 | Sets the tag of the message to show if this entry is missing. This is |
| 494 | used for external blobs. When they are missing it is helpful to show |
| 495 | information about what needs to be fixed. See missing-blob-help for the |
| 496 | message for each tag. |
Simon Glass | a820af7 | 2020-09-06 10:39:09 -0600 | [diff] [blame] | 497 | |
Simon Glass | 7098b7f | 2021-03-21 18:24:30 +1300 | [diff] [blame] | 498 | no-expanded: |
| 499 | By default binman substitutes entries with expanded versions if available, |
| 500 | so that a `u-boot` entry type turns into `u-boot-expanded`, for example. The |
| 501 | `--no-expanded` command-line option disables this globally. The |
| 502 | `no-expanded` property disables this just for a single entry. Put the |
| 503 | `no-expanded` boolean property in the node to select this behaviour. |
| 504 | |
Simon Glass | 8004581 | 2018-09-14 04:57:30 -0600 | [diff] [blame] | 505 | The attributes supported for images and sections are described below. Several |
| 506 | are similar to those for entries. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 507 | |
| 508 | size: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 509 | Sets the image size in bytes, for example 'size = <0x100000>' for a |
| 510 | 1MB image. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 511 | |
Simon Glass | eb023b3 | 2019-04-25 21:58:39 -0600 | [diff] [blame] | 512 | offset: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 513 | This is similar to 'offset' in entries, setting the offset of a section |
| 514 | within the image or section containing it. The first byte of the section |
| 515 | is normally at offset 0. If 'offset' is not provided, binman sets it to |
| 516 | the end of the previous region, or the start of the image's entry area |
| 517 | (normally 0) if there is no previous region. |
Simon Glass | eb023b3 | 2019-04-25 21:58:39 -0600 | [diff] [blame] | 518 | |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 519 | align-size: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 520 | This sets the alignment of the image size. For example, to ensure |
| 521 | that the image ends on a 512-byte boundary, use 'align-size = <512>'. |
| 522 | If 'align-size' is not provided, no alignment is performed. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 523 | |
| 524 | pad-before: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 525 | This sets the padding before the image entries. The first entry will |
| 526 | be positioned after the padding. This defaults to 0. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 527 | |
| 528 | pad-after: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 529 | This sets the padding after the image entries. The padding will be |
| 530 | placed after the last entry. This defaults to 0. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 531 | |
| 532 | pad-byte: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 533 | This specifies the pad byte to use when padding in the image. It |
| 534 | defaults to 0. To use 0xff, you would add 'pad-byte = <0xff>'. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 535 | |
| 536 | filename: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 537 | This specifies the image filename. It defaults to 'image.bin'. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 538 | |
Simon Glass | e8561af | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 539 | sort-by-offset: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 540 | This causes binman to reorder the entries as needed to make sure they |
| 541 | are in increasing positional order. This can be used when your entry |
| 542 | order may not match the positional order. A common situation is where |
| 543 | the 'offset' properties are set by CONFIG options, so their ordering is |
| 544 | not known a priori. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 545 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 546 | This is a boolean property so needs no value. To enable it, add a |
| 547 | line 'sort-by-offset;' to your description. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 548 | |
| 549 | multiple-images: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 550 | Normally only a single image is generated. To create more than one |
| 551 | image, put this property in the binman node. For example, this will |
| 552 | create image1.bin containing u-boot.bin, and image2.bin containing |
| 553 | both spl/u-boot-spl.bin and u-boot.bin:: |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 554 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 555 | binman { |
| 556 | multiple-images; |
| 557 | image1 { |
| 558 | u-boot { |
| 559 | }; |
| 560 | }; |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 561 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 562 | image2 { |
| 563 | spl { |
| 564 | }; |
| 565 | u-boot { |
| 566 | }; |
| 567 | }; |
| 568 | }; |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 569 | |
| 570 | end-at-4gb: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 571 | For x86 machines the ROM offsets start just before 4GB and extend |
| 572 | up so that the image finished at the 4GB boundary. This boolean |
| 573 | option can be enabled to support this. The image size must be |
| 574 | provided so that binman knows when the image should start. For an |
| 575 | 8MB ROM, the offset of the first entry would be 0xfff80000 with |
| 576 | this option, instead of 0 without this option. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 577 | |
Jagdish Gediya | 0fb978c | 2018-09-03 21:35:07 +0530 | [diff] [blame] | 578 | skip-at-start: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 579 | This property specifies the entry offset of the first entry. |
Jagdish Gediya | 0fb978c | 2018-09-03 21:35:07 +0530 | [diff] [blame] | 580 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 581 | For PowerPC mpc85xx based CPU, CONFIG_SYS_TEXT_BASE is the entry |
| 582 | offset of the first entry. It can be 0xeff40000 or 0xfff40000 for |
| 583 | nor flash boot, 0x201000 for sd boot etc. |
Jagdish Gediya | 0fb978c | 2018-09-03 21:35:07 +0530 | [diff] [blame] | 584 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 585 | 'end-at-4gb' property is not applicable where CONFIG_SYS_TEXT_BASE + |
| 586 | Image size != 4gb. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 587 | |
Simon Glass | f427c5f | 2021-03-21 18:24:33 +1300 | [diff] [blame] | 588 | align-default: |
| 589 | Specifies the default alignment for entries in this section, if they do |
| 590 | not specify an alignment. Note that this only applies to top-level entries |
| 591 | in the section (direct subentries), not any subentries of those entries. |
| 592 | This means that each section must specify its own default alignment, if |
| 593 | required. |
| 594 | |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 595 | Examples of the above options can be found in the tests. See the |
| 596 | tools/binman/test directory. |
| 597 | |
Simon Glass | e76a3e6 | 2018-06-01 09:38:11 -0600 | [diff] [blame] | 598 | It is possible to have the same binary appear multiple times in the image, |
| 599 | either by using a unit number suffix (u-boot@0, u-boot@1) or by using a |
| 600 | different name for each and specifying the type with the 'type' attribute. |
| 601 | |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 602 | |
Michael Heimpold | 55c822d | 2018-08-22 22:01:24 +0200 | [diff] [blame] | 603 | Sections and hierachical images |
Simon Glass | a91e115 | 2018-06-01 09:38:16 -0600 | [diff] [blame] | 604 | ------------------------------- |
| 605 | |
| 606 | Sometimes it is convenient to split an image into several pieces, each of which |
| 607 | contains its own set of binaries. An example is a flash device where part of |
| 608 | the image is read-only and part is read-write. We can set up sections for each |
| 609 | of these, and place binaries in them independently. The image is still produced |
| 610 | as a single output file. |
| 611 | |
| 612 | This feature provides a way of creating hierarchical images. For example here |
Simon Glass | 1e32400 | 2018-06-01 09:38:19 -0600 | [diff] [blame] | 613 | is an example image with two copies of U-Boot. One is read-only (ro), intended |
| 614 | 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] | 615 | 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] | 616 | and can be programmed:: |
Simon Glass | a91e115 | 2018-06-01 09:38:16 -0600 | [diff] [blame] | 617 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 618 | binman { |
| 619 | section@0 { |
| 620 | read-only; |
| 621 | name-prefix = "ro-"; |
| 622 | size = <0x100000>; |
| 623 | u-boot { |
| 624 | }; |
| 625 | }; |
| 626 | section@1 { |
| 627 | name-prefix = "rw-"; |
| 628 | size = <0x100000>; |
| 629 | u-boot { |
| 630 | }; |
| 631 | }; |
| 632 | }; |
Simon Glass | a91e115 | 2018-06-01 09:38:16 -0600 | [diff] [blame] | 633 | |
| 634 | This image could be placed into a SPI flash chip, with the protection boundary |
| 635 | set at 1MB. |
| 636 | |
| 637 | A few special properties are provided for sections: |
| 638 | |
| 639 | read-only: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 640 | Indicates that this section is read-only. This has no impact on binman's |
| 641 | operation, but his property can be read at run time. |
Simon Glass | a91e115 | 2018-06-01 09:38:16 -0600 | [diff] [blame] | 642 | |
Simon Glass | 3b78d53 | 2018-06-01 09:38:21 -0600 | [diff] [blame] | 643 | name-prefix: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 644 | This string is prepended to all the names of the binaries in the |
| 645 | section. In the example above, the 'u-boot' binaries which actually be |
| 646 | renamed to 'ro-u-boot' and 'rw-u-boot'. This can be useful to |
| 647 | distinguish binaries with otherwise identical names. |
Simon Glass | 3b78d53 | 2018-06-01 09:38:21 -0600 | [diff] [blame] | 648 | |
Simon Glass | a91e115 | 2018-06-01 09:38:16 -0600 | [diff] [blame] | 649 | |
Simon Glass | fb30e29 | 2019-07-20 12:23:51 -0600 | [diff] [blame] | 650 | Image Properties |
| 651 | ---------------- |
| 652 | |
| 653 | Image nodes act like sections but also have a few extra properties: |
| 654 | |
| 655 | filename: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 656 | Output filename for the image. This defaults to image.bin (or in the |
| 657 | case of multiple images <nodename>.bin where <nodename> is the name of |
| 658 | the image node. |
Simon Glass | fb30e29 | 2019-07-20 12:23:51 -0600 | [diff] [blame] | 659 | |
| 660 | allow-repack: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 661 | Create an image that can be repacked. With this option it is possible |
| 662 | to change anything in the image after it is created, including updating |
| 663 | the position and size of image components. By default this is not |
| 664 | permitted since it is not possibly to know whether this might violate a |
| 665 | constraint in the image description. For example, if a section has to |
| 666 | increase in size to hold a larger binary, that might cause the section |
| 667 | 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] | 668 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 669 | Adding this property causes the original offset and size values in the |
| 670 | image description to be stored in the FDT and fdtmap. |
Simon Glass | fb30e29 | 2019-07-20 12:23:51 -0600 | [diff] [blame] | 671 | |
| 672 | |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 673 | Hashing Entries |
| 674 | --------------- |
| 675 | |
| 676 | It is possible to ask binman to hash the contents of an entry and write that |
| 677 | value back to the device-tree node. For example:: |
| 678 | |
| 679 | binman { |
| 680 | u-boot { |
| 681 | hash { |
| 682 | algo = "sha256"; |
| 683 | }; |
| 684 | }; |
| 685 | }; |
| 686 | |
| 687 | Here, a new 'value' property will be written to the 'hash' node containing |
| 688 | the hash of the 'u-boot' entry. Only SHA256 is supported at present. Whole |
| 689 | sections can be hased if desired, by adding the 'hash' node to the section. |
| 690 | |
| 691 | The has value can be chcked at runtime by hashing the data actually read and |
| 692 | comparing this has to the value in the device tree. |
| 693 | |
| 694 | |
| 695 | Expanded entries |
| 696 | ---------------- |
| 697 | |
| 698 | Binman automatically replaces 'u-boot' with an expanded version of that, i.e. |
| 699 | 'u-boot-expanded'. This means that when you write:: |
| 700 | |
| 701 | u-boot { |
| 702 | }; |
| 703 | |
| 704 | you actually get:: |
| 705 | |
| 706 | u-boot { |
| 707 | type = "u-boot-expanded'; |
| 708 | }; |
| 709 | |
| 710 | which in turn expands to:: |
| 711 | |
| 712 | u-boot { |
| 713 | type = "section"; |
| 714 | |
| 715 | u-boot-nodtb { |
| 716 | }; |
| 717 | |
| 718 | u-boot-dtb { |
| 719 | }; |
| 720 | }; |
| 721 | |
| 722 | U-Boot's various phase binaries actually comprise two or three pieces. |
| 723 | For example, u-boot.bin has the executable followed by a devicetree. |
| 724 | |
| 725 | With binman we want to be able to update that devicetree with full image |
| 726 | information so that it is accessible to the executable. This is tricky |
| 727 | if it is not clear where the devicetree starts. |
| 728 | |
| 729 | The above feature ensures that the devicetree is clearly separated from the |
| 730 | U-Boot executable and can be updated separately by binman as needed. It can be |
| 731 | disabled with the --no-expanded flag if required. |
| 732 | |
Heiko Thiery | d589456 | 2022-01-24 08:11:01 +0100 | [diff] [blame] | 733 | 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] | 734 | includes the BSS padding, so for example:: |
| 735 | |
| 736 | spl { |
| 737 | type = "u-boot-spl" |
| 738 | }; |
| 739 | |
| 740 | you actually get:: |
| 741 | |
| 742 | spl { |
| 743 | type = "u-boot-expanded'; |
| 744 | }; |
| 745 | |
| 746 | which in turn expands to:: |
| 747 | |
| 748 | spl { |
| 749 | type = "section"; |
| 750 | |
| 751 | u-boot-spl-nodtb { |
| 752 | }; |
| 753 | |
| 754 | u-boot-spl-bss-pad { |
| 755 | }; |
| 756 | |
| 757 | u-boot-spl-dtb { |
| 758 | }; |
| 759 | }; |
| 760 | |
| 761 | Of course we should not expand SPL if it has no devicetree. Also if the BSS |
| 762 | padding is not needed (because BSS is in RAM as with CONFIG_SPL_SEPARATE_BSS), |
| 763 | the 'u-boot-spl-bss-pad' subnode should not be created. The use of the expaned |
| 764 | entry type is controlled by the UseExpanded() method. In the SPL case it checks |
| 765 | the 'spl-dtb' entry arg, which is 'y' or '1' if SPL has a devicetree. |
| 766 | |
| 767 | For the BSS case, a 'spl-bss-pad' entry arg controls whether it is present. All |
| 768 | entry args are provided by the U-Boot Makefile. |
| 769 | |
| 770 | |
| 771 | Compression |
| 772 | ----------- |
| 773 | |
| 774 | Binman support compression for 'blob' entries (those of type 'blob' and |
| 775 | derivatives). To enable this for an entry, add a 'compress' property:: |
| 776 | |
| 777 | blob { |
| 778 | filename = "datafile"; |
| 779 | compress = "lz4"; |
| 780 | }; |
| 781 | |
| 782 | The entry will then contain the compressed data, using the 'lz4' compression |
| 783 | algorithm. Currently this is the only one that is supported. The uncompressed |
| 784 | size is written to the node in an 'uncomp-size' property, if -u is used. |
| 785 | |
| 786 | Compression is also supported for sections. In that case the entire section is |
| 787 | compressed in one block, including all its contents. This means that accessing |
| 788 | an entry from the section required decompressing the entire section. Also, the |
| 789 | size of a section indicates the space that it consumes in its parent section |
| 790 | (and typically the image). With compression, the section may contain more data, |
| 791 | and the uncomp-size property indicates that, as above. The contents of the |
| 792 | section is compressed first, before any padding is added. This ensures that the |
| 793 | padding itself is not compressed, which would be a waste of time. |
| 794 | |
| 795 | |
| 796 | Automatic .dtsi inclusion |
| 797 | ------------------------- |
| 798 | |
| 799 | It is sometimes inconvenient to add a 'binman' node to the .dts file for each |
| 800 | board. This can be done by using #include to bring in a common file. Another |
| 801 | approach supported by the U-Boot build system is to automatically include |
| 802 | a common header. You can then put the binman node (and anything else that is |
| 803 | specific to U-Boot, such as u-boot,dm-pre-reloc properies) in that header |
| 804 | file. |
| 805 | |
| 806 | Binman will search for the following files in arch/<arch>/dts:: |
| 807 | |
| 808 | <dts>-u-boot.dtsi where <dts> is the base name of the .dts file |
| 809 | <CONFIG_SYS_SOC>-u-boot.dtsi |
| 810 | <CONFIG_SYS_CPU>-u-boot.dtsi |
| 811 | <CONFIG_SYS_VENDOR>-u-boot.dtsi |
| 812 | u-boot.dtsi |
| 813 | |
| 814 | U-Boot will only use the first one that it finds. If you need to include a |
| 815 | 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] | 816 | If you are having trouble figuring out what is going on, you can use |
| 817 | `DEVICE_TREE_DEBUG=1` with your build:: |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 818 | |
Simon Glass | 0a1b3b6 | 2021-12-16 20:59:23 -0700 | [diff] [blame] | 819 | make DEVICE_TREE_DEBUG=1 |
| 820 | scripts/Makefile.lib:334: Automatic .dtsi inclusion: options: |
| 821 | arch/arm/dts/juno-r2-u-boot.dtsi arch/arm/dts/-u-boot.dtsi |
| 822 | arch/arm/dts/armv8-u-boot.dtsi arch/arm/dts/armltd-u-boot.dtsi |
| 823 | 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] | 824 | |
| 825 | |
Simon Glass | adfb849 | 2021-11-03 21:09:18 -0600 | [diff] [blame] | 826 | Updating an ELF file |
| 827 | ==================== |
| 828 | |
| 829 | For the EFI app, where U-Boot is loaded from UEFI and runs as an app, there is |
| 830 | no way to update the devicetree after U-Boot is built. Normally this works by |
| 831 | creating a new u-boot.dtb.out with he updated devicetree, which is automatically |
| 832 | built into the output image. With ELF this is not possible since the ELF is |
| 833 | not part of an image, just a stand-along file. We must create an updated ELF |
| 834 | file with the new devicetree. |
| 835 | |
| 836 | This is handled by the --update-fdt-in-elf option. It takes four arguments, |
| 837 | separated by comma: |
| 838 | |
| 839 | infile - filename of input ELF file, e.g. 'u-boot's |
| 840 | outfile - filename of output ELF file, e.g. 'u-boot.out' |
| 841 | begin_sym - symbol at the start of the embedded devicetree, e.g. |
| 842 | '__dtb_dt_begin' |
| 843 | end_sym - symbol at the start of the embedded devicetree, e.g. |
| 844 | '__dtb_dt_end' |
| 845 | |
| 846 | When this flag is used, U-Boot does all the normal packaging, but as an |
| 847 | additional step, it creates a new ELF file with the new devicetree embedded in |
| 848 | it. |
| 849 | |
| 850 | If logging is enabled you will see a message like this:: |
| 851 | |
| 852 | Updating file 'u-boot' with data length 0x400a (16394) between symbols |
| 853 | '__dtb_dt_begin' and '__dtb_dt_end' |
| 854 | |
| 855 | There must be enough space for the updated devicetree. If not, an error like |
| 856 | the following is produced:: |
| 857 | |
| 858 | ValueError: Not enough space in 'u-boot' for data length 0x400a (16394); |
| 859 | size is 0x1744 (5956) |
| 860 | |
| 861 | |
Simon Glass | 7a61c6b | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 862 | Entry Documentation |
Simon Glass | 774b23f | 2021-03-18 20:25:17 +1300 | [diff] [blame] | 863 | =================== |
Simon Glass | 7a61c6b | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 864 | |
| 865 | 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] | 866 | see entries.rst which is generated from the source code using: |
| 867 | |
| 868 | binman entry-docs >tools/binman/entries.rst |
Simon Glass | 7a61c6b | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 869 | |
Simon Glass | 774b23f | 2021-03-18 20:25:17 +1300 | [diff] [blame] | 870 | .. toctree:: |
| 871 | :maxdepth: 2 |
Simon Glass | 7a61c6b | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 872 | |
Simon Glass | 774b23f | 2021-03-18 20:25:17 +1300 | [diff] [blame] | 873 | entries |
| 874 | |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 875 | |
| 876 | Managing images |
| 877 | =============== |
Simon Glass | 7a61c6b | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 878 | |
Simon Glass | b2fd11d | 2019-07-08 14:25:48 -0600 | [diff] [blame] | 879 | Listing images |
| 880 | -------------- |
| 881 | |
| 882 | 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] | 883 | 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] | 884 | |
| 885 | $ binman ls -i image.bin |
| 886 | Name Image-pos Size Entry-type Offset Uncomp-size |
| 887 | ---------------------------------------------------------------------- |
| 888 | main-section c00 section 0 |
| 889 | u-boot 0 4 u-boot 0 |
| 890 | section 5fc section 4 |
| 891 | cbfs 100 400 cbfs 0 |
| 892 | u-boot 138 4 u-boot 38 |
| 893 | u-boot-dtb 180 108 u-boot-dtb 80 3b5 |
| 894 | u-boot-dtb 500 1ff u-boot-dtb 400 3b5 |
| 895 | fdtmap 6fc 381 fdtmap 6fc |
| 896 | image-header bf8 8 image-header bf8 |
| 897 | |
| 898 | This shows the hierarchy of the image, the position, size and type of each |
| 899 | entry, the offset of each entry within its parent and the uncompressed size if |
| 900 | the entry is compressed. |
| 901 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 902 | 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] | 903 | |
| 904 | $ binman ls -i image.bin section/cbfs |
| 905 | Name Image-pos Size Entry-type Offset Uncomp-size |
| 906 | -------------------------------------------------------------------- |
| 907 | cbfs 100 400 cbfs 0 |
| 908 | u-boot 138 4 u-boot 38 |
| 909 | u-boot-dtb 180 108 u-boot-dtb 80 3b5 |
| 910 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 911 | or with wildcards:: |
Simon Glass | b2fd11d | 2019-07-08 14:25:48 -0600 | [diff] [blame] | 912 | |
| 913 | $ binman ls -i image.bin "*cb*" "*head*" |
| 914 | Name Image-pos Size Entry-type Offset Uncomp-size |
| 915 | ---------------------------------------------------------------------- |
| 916 | cbfs 100 400 cbfs 0 |
| 917 | u-boot 138 4 u-boot 38 |
| 918 | u-boot-dtb 180 108 u-boot-dtb 80 3b5 |
| 919 | image-header bf8 8 image-header bf8 |
| 920 | |
Simon Glass | b9028bc | 2021-11-23 21:09:49 -0700 | [diff] [blame] | 921 | If an older version of binman is used to list images created by a newer one, it |
| 922 | is possible that it will contain entry types that are not supported. These still |
| 923 | show with the correct type, but binman just sees them as blobs (plain binary |
| 924 | data). Any special features of that etype are not supported by the old binman. |
| 925 | |
Simon Glass | b2fd11d | 2019-07-08 14:25:48 -0600 | [diff] [blame] | 926 | |
Simon Glass | 980a284 | 2019-07-08 14:25:52 -0600 | [diff] [blame] | 927 | Extracting files from images |
| 928 | ---------------------------- |
| 929 | |
| 930 | You can extract files from an existing firmware image created by binman, |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 931 | provided that there is an 'fdtmap' entry in the image. For example:: |
Simon Glass | 980a284 | 2019-07-08 14:25:52 -0600 | [diff] [blame] | 932 | |
| 933 | $ binman extract -i image.bin section/cbfs/u-boot |
| 934 | |
| 935 | which will write the uncompressed contents of that entry to the file 'u-boot' in |
| 936 | 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] | 937 | u-boot.bin:: |
Simon Glass | 980a284 | 2019-07-08 14:25:52 -0600 | [diff] [blame] | 938 | |
| 939 | $ binman extract -i image.bin section/cbfs/u-boot -f u-boot.bin |
| 940 | |
| 941 | 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] | 942 | put files in subdirectories matching the entry hierarchy:: |
Simon Glass | 980a284 | 2019-07-08 14:25:52 -0600 | [diff] [blame] | 943 | |
| 944 | $ binman extract -i image.bin -O outdir |
| 945 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 946 | or just a selection:: |
Simon Glass | 980a284 | 2019-07-08 14:25:52 -0600 | [diff] [blame] | 947 | |
| 948 | $ binman extract -i image.bin "*u-boot*" -O outdir |
| 949 | |
Simon Glass | 637958f | 2021-11-23 21:09:50 -0700 | [diff] [blame] | 950 | Some entry types have alternative formats, for example fdtmap which allows |
| 951 | extracted just the devicetree binary without the fdtmap header:: |
| 952 | |
| 953 | $ binman extract -i /tmp/b/odroid-c4/image.bin -f out.dtb -F fdt fdtmap |
| 954 | $ fdtdump out.dtb |
| 955 | /dts-v1/; |
| 956 | // magic: 0xd00dfeed |
| 957 | // totalsize: 0x8ab (2219) |
| 958 | // off_dt_struct: 0x38 |
| 959 | // off_dt_strings: 0x82c |
| 960 | // off_mem_rsvmap: 0x28 |
| 961 | // version: 17 |
| 962 | // last_comp_version: 2 |
| 963 | // boot_cpuid_phys: 0x0 |
| 964 | // size_dt_strings: 0x7f |
| 965 | // size_dt_struct: 0x7f4 |
| 966 | |
| 967 | / { |
| 968 | image-node = "binman"; |
| 969 | image-pos = <0x00000000>; |
| 970 | size = <0x0011162b>; |
| 971 | ... |
| 972 | |
| 973 | Use `-F list` to see what alternative formats are available:: |
| 974 | |
| 975 | $ binman extract -i /tmp/b/odroid-c4/image.bin -F list |
| 976 | Flag (-F) Entry type Description |
| 977 | fdt fdtmap Extract the devicetree blob from the fdtmap |
| 978 | |
Simon Glass | 980a284 | 2019-07-08 14:25:52 -0600 | [diff] [blame] | 979 | |
Simon Glass | 072959a | 2019-07-20 12:23:50 -0600 | [diff] [blame] | 980 | Replacing files in an image |
| 981 | --------------------------- |
| 982 | |
| 983 | 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] | 984 | that there is an 'fdtmap' entry in the image. For example:: |
Simon Glass | 072959a | 2019-07-20 12:23:50 -0600 | [diff] [blame] | 985 | |
| 986 | $ binman replace -i image.bin section/cbfs/u-boot |
| 987 | |
| 988 | 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] | 989 | to the that entry, compressing if necessary. If the entry size changes, you must |
| 990 | add the 'allow-repack' property to the original image before generating it (see |
| 991 | above), otherwise you will get an error. |
Simon Glass | 072959a | 2019-07-20 12:23:50 -0600 | [diff] [blame] | 992 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 993 | 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] | 994 | |
| 995 | $ binman replace -i image.bin section/cbfs/u-boot -f u-boot.bin |
| 996 | |
| 997 | 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] | 998 | hierarchy as the entries:: |
Simon Glass | 30033c2 | 2019-07-20 12:24:15 -0600 | [diff] [blame] | 999 | |
| 1000 | $ binman replace -i image.bin -I indir |
| 1001 | |
| 1002 | Files that are missing will generate a warning. |
| 1003 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 1004 | You can also replace just a selection of entries:: |
Simon Glass | 30033c2 | 2019-07-20 12:24:15 -0600 | [diff] [blame] | 1005 | |
| 1006 | $ binman replace -i image.bin "*u-boot*" -I indir |
| 1007 | |
Simon Glass | 072959a | 2019-07-20 12:23:50 -0600 | [diff] [blame] | 1008 | |
Simon Glass | 233a26a9 | 2019-07-08 14:25:49 -0600 | [diff] [blame] | 1009 | Logging |
| 1010 | ------- |
| 1011 | |
| 1012 | Binman normally operates silently unless there is an error, in which case it |
| 1013 | 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] | 1014 | backtrace when errors occur. You can use BINMAN_DEBUG=1 when building to select |
| 1015 | this. |
Simon Glass | 233a26a9 | 2019-07-08 14:25:49 -0600 | [diff] [blame] | 1016 | |
| 1017 | Internally binman logs some output while it is running. This can be displayed |
| 1018 | by increasing the -v/--verbosity from the default of 1: |
| 1019 | |
| 1020 | 0: silent |
| 1021 | 1: warnings only |
| 1022 | 2: notices (important messages) |
| 1023 | 3: info about major operations |
| 1024 | 4: detailed information about each operation |
| 1025 | 5: debug (all output) |
| 1026 | |
Simon Glass | caa5f18 | 2021-02-06 09:57:28 -0700 | [diff] [blame] | 1027 | 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] | 1028 | |
Simon Glass | 7223245 | 2016-11-25 20:15:53 -0700 | [diff] [blame] | 1029 | |
Simon Glass | 4142486 | 2022-01-09 20:14:12 -0700 | [diff] [blame] | 1030 | Bintools |
| 1031 | ======== |
| 1032 | |
| 1033 | `Bintool` is the name binman gives to a binary tool which it uses to create and |
| 1034 | manipulate binaries that binman cannot handle itself. Bintools are often |
| 1035 | necessary since Binman only supports a subset of the available file formats |
| 1036 | natively. |
| 1037 | |
| 1038 | Many SoC vendors invent ways to load code into their SoC using new file formats, |
| 1039 | sometimes changing the format with successive SoC generations. Sometimes the |
| 1040 | tool is available as Open Source. Sometimes it is a pre-compiled binary that |
| 1041 | must be downloaded from the vendor's website. Sometimes it is available in |
| 1042 | source form but difficult or slow to build. |
| 1043 | |
| 1044 | Even for images that use bintools, binman still assembles the image from its |
| 1045 | image description. It may handle parts of the image natively and part with |
| 1046 | various bintools. |
| 1047 | |
| 1048 | Binman relies on these tools so provides various features to manage them: |
| 1049 | |
| 1050 | - Determining whether the tool is currently installed |
| 1051 | - Downloading or building the tool |
| 1052 | - Determining the version of the tool that is installed |
| 1053 | - Deciding which tools are needed to build an image |
| 1054 | |
| 1055 | The Bintool class is an interface to the tool, a thin level of abstration, using |
| 1056 | Python functions to run the tool for each purpose (e.g. creating a new |
| 1057 | structure, adding a file to an existing structure) rather than just lists of |
| 1058 | string arguments. |
| 1059 | |
| 1060 | As with external blobs, bintools (which are like 'external' tools) can be |
| 1061 | missing. When building an image requires a bintool and it is not installed, |
| 1062 | binman detects this and reports the problem, but continues to build an image. |
| 1063 | This is useful in CI systems which want to check that everything is correct but |
| 1064 | don't have access to the bintools. |
| 1065 | |
| 1066 | To make this work, all calls to bintools (e.g. with Bintool.run_cmd()) must cope |
| 1067 | with the tool being missing, i.e. when None is returned, by: |
| 1068 | |
| 1069 | - Calling self.record_missing_bintool() |
| 1070 | - Setting up some fake contents so binman can continue |
| 1071 | |
| 1072 | Of course the image will not work, but binman reports which bintools are needed |
| 1073 | and also provide a way to fetch them. |
| 1074 | |
| 1075 | To see the available bintools, use:: |
| 1076 | |
| 1077 | binman tool --list |
| 1078 | |
| 1079 | To fetch tools which are missing, use:: |
| 1080 | |
| 1081 | binman tool --fetch missing |
| 1082 | |
| 1083 | You can also use `--fetch all` to fetch all tools or `--fetch <tool>` to fetch |
| 1084 | a particular tool. Some tools are built from source code, in which case you will |
| 1085 | need to have at least the `build-essential` and `git` packages installed. |
| 1086 | |
| 1087 | Bintool Documentation |
| 1088 | ===================== |
| 1089 | |
| 1090 | To provide details on the various bintools supported by binman, bintools.rst is |
| 1091 | generated from the source code using: |
| 1092 | |
| 1093 | binman bintool-docs >tools/binman/bintools.rst |
| 1094 | |
| 1095 | .. toctree:: |
| 1096 | :maxdepth: 2 |
| 1097 | |
| 1098 | bintools |
| 1099 | |
| 1100 | |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 1101 | Technical details |
| 1102 | ================= |
Simon Glass | 7223245 | 2016-11-25 20:15:53 -0700 | [diff] [blame] | 1103 | |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1104 | Order of image creation |
| 1105 | ----------------------- |
| 1106 | |
| 1107 | Image creation proceeds in the following order, for each entry in the image. |
| 1108 | |
Simon Glass | e22f8fa | 2018-07-06 10:27:41 -0600 | [diff] [blame] | 1109 | 1. AddMissingProperties() - binman can add calculated values to the device |
Simon Glass | e8561af | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 1110 | 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] | 1111 | entry. This method adds any properties associated with this, expanding the |
| 1112 | device tree as needed. These properties can have placeholder values which are |
| 1113 | set later by SetCalculatedProperties(). By that stage the size of sections |
| 1114 | cannot be changed (since it would cause the images to need to be repacked), |
| 1115 | but the correct values can be inserted. |
| 1116 | |
| 1117 | 2. ProcessFdt() - process the device tree information as required by the |
Simon Glass | 9230773 | 2018-07-06 10:27:40 -0600 | [diff] [blame] | 1118 | particular entry. This may involve adding or deleting properties. If the |
| 1119 | processing is complete, this method should return True. If the processing |
| 1120 | cannot complete because it needs the ProcessFdt() method of another entry to |
| 1121 | run first, this method should return False, in which case it will be called |
| 1122 | again later. |
| 1123 | |
Simon Glass | e22f8fa | 2018-07-06 10:27:41 -0600 | [diff] [blame] | 1124 | 3. GetEntryContents() - the contents of each entry are obtained, normally by |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1125 | reading from a file. This calls the Entry.ObtainContents() to read the |
| 1126 | contents. The default version of Entry.ObtainContents() calls |
| 1127 | Entry.GetDefaultFilename() and then reads that file. So a common mechanism |
| 1128 | to select a file to read is to override that function in the subclass. The |
| 1129 | functions must return True when they have read the contents. Binman will |
| 1130 | retry calling the functions a few times if False is returned, allowing |
| 1131 | dependencies between the contents of different entries. |
| 1132 | |
Simon Glass | e8561af | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 1133 | 4. GetEntryOffsets() - calls Entry.GetOffsets() for each entry. This can |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1134 | 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] | 1135 | entry name and the value is a tuple (offset, size). This allows an entry to |
| 1136 | provide the offset and size for other entries. The default implementation |
| 1137 | of GetEntryOffsets() returns {}. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1138 | |
Simon Glass | e8561af | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 1139 | 5. PackEntries() - calls Entry.Pack() which figures out the offset and |
| 1140 | size of an entry. The 'current' image offset is passed in, and the function |
| 1141 | returns the offset immediately after the entry being packed. The default |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1142 | implementation of Pack() is usually sufficient. |
| 1143 | |
Simon Glass | 2d9570d | 2020-10-26 17:40:22 -0600 | [diff] [blame] | 1144 | Note: for sections, this also checks that the entries do not overlap, nor extend |
| 1145 | outside the section. If the section does not have a defined size, the size is |
| 1146 | set large enough to hold all the entries. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1147 | |
Simon Glass | 2d9570d | 2020-10-26 17:40:22 -0600 | [diff] [blame] | 1148 | 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] | 1149 | position 'image-pos', as opposed to 'offset' which is relative to the containing |
| 1150 | section. This must be done after all offsets are known, which is why it is quite |
| 1151 | late in the ordering. |
| 1152 | |
Simon Glass | 2d9570d | 2020-10-26 17:40:22 -0600 | [diff] [blame] | 1153 | 7. SetCalculatedProperties() - update any calculated properties in the device |
Simon Glass | e8561af | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 1154 | tree. This sets the correct 'offset' and 'size' vaues, for example. |
Simon Glass | e22f8fa | 2018-07-06 10:27:41 -0600 | [diff] [blame] | 1155 | |
Simon Glass | 2d9570d | 2020-10-26 17:40:22 -0600 | [diff] [blame] | 1156 | 8. ProcessEntryContents() - this calls Entry.ProcessContents() on each entry. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1157 | The default implementatoin does nothing. This can be overriden to adjust the |
| 1158 | contents of an entry in some way. For example, it would be possible to create |
| 1159 | 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] | 1160 | stage the offset and size of entries should not be adjusted unless absolutely |
| 1161 | necessary, since it requires a repack (going back to PackEntries()). |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1162 | |
Simon Glass | 2d9570d | 2020-10-26 17:40:22 -0600 | [diff] [blame] | 1163 | 9. ResetForPack() - if the ProcessEntryContents() step failed, in that an entry |
Simon Glass | 4b05b2d | 2019-07-20 12:23:52 -0600 | [diff] [blame] | 1164 | has changed its size, then there is no alternative but to go back to step 5 and |
| 1165 | try again, repacking the entries with the updated size. ResetForPack() removes |
| 1166 | the fixed offset/size values added by binman, so that the packing can start from |
| 1167 | scratch. |
| 1168 | |
Simon Glass | 2d9570d | 2020-10-26 17:40:22 -0600 | [diff] [blame] | 1169 | 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] | 1170 | 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] | 1171 | what happens in this stage. |
Simon Glass | be83bc7 | 2017-11-13 18:55:05 -0700 | [diff] [blame] | 1172 | |
Simon Glass | 2d9570d | 2020-10-26 17:40:22 -0600 | [diff] [blame] | 1173 | 11. BuildImage() - builds the image and writes it to a file |
Simon Glass | 4b05b2d | 2019-07-20 12:23:52 -0600 | [diff] [blame] | 1174 | |
Simon Glass | 2d9570d | 2020-10-26 17:40:22 -0600 | [diff] [blame] | 1175 | 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] | 1176 | final step. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1177 | |
| 1178 | |
Simon Glass | 6244fa4 | 2019-07-08 13:18:28 -0600 | [diff] [blame] | 1179 | External tools |
| 1180 | -------------- |
| 1181 | |
| 1182 | Binman can make use of external command-line tools to handle processing of |
| 1183 | entry contents or to generate entry contents. These tools are executed using |
| 1184 | the 'tools' module's Run() method. The tools generally must exist on the PATH, |
| 1185 | but the --toolpath option can be used to specify additional search paths to |
| 1186 | use. This option can be specified multiple times to add more than one path. |
| 1187 | |
Alper Nebi Yasak | fb4e538 | 2020-09-06 14:46:07 +0300 | [diff] [blame] | 1188 | For some compile tools binman will use the versions specified by commonly-used |
| 1189 | environment variables like CC and HOSTCC for the C compiler, based on whether |
| 1190 | the tool's output will be used for the target or for the host machine. If those |
| 1191 | aren't given, it will also try to derive target-specific versions from the |
| 1192 | CROSS_COMPILE environment variable during a cross-compilation. |
| 1193 | |
Simon Glass | 31cce97 | 2021-11-23 21:09:48 -0700 | [diff] [blame] | 1194 | If the tool is not available in the path you can use BINMAN_TOOLPATHS to specify |
| 1195 | a space-separated list of paths to search, e.g.:: |
| 1196 | |
| 1197 | BINMAN_TOOLPATHS="/tools/g12a /tools/tegra" binman ... |
| 1198 | |
| 1199 | |
| 1200 | External blobs |
| 1201 | -------------- |
| 1202 | |
| 1203 | Binary blobs, even if the source code is available, complicate building |
| 1204 | firmware. The instructions can involve multiple steps and the binaries may be |
| 1205 | hard to build or obtain. Binman at least provides a unified description of how |
| 1206 | to build the final image, no matter what steps are needed to get there. |
| 1207 | |
| 1208 | Binman also provides a `blob-ext` entry type that pulls in a binary blob from an |
| 1209 | external file. If the file is missing, binman can optionally complete the build |
| 1210 | and just report a warning. Use the `-M/--allow-missing` option to enble this. |
| 1211 | This is useful in CI systems which want to check that everything is correct but |
| 1212 | don't have access to the blobs. |
| 1213 | |
| 1214 | If the blobs are in a different directory, you can specify this with the `-I` |
| 1215 | option. |
| 1216 | |
| 1217 | For U-Boot, you can use set the BINMAN_INDIRS environment variable to provide a |
| 1218 | space-separated list of directories to search for binary blobs:: |
| 1219 | |
| 1220 | BINMAN_INDIRS="odroid-c4/fip/g12a \ |
| 1221 | odroid-c4/build/board/hardkernel/odroidc4/firmware \ |
| 1222 | odroid-c4/build/scp_task" binman ... |
Simon Glass | 6244fa4 | 2019-07-08 13:18:28 -0600 | [diff] [blame] | 1223 | |
Simon Glass | 52debad | 2016-11-25 20:15:59 -0700 | [diff] [blame] | 1224 | Code coverage |
| 1225 | ------------- |
| 1226 | |
| 1227 | 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] | 1228 | implementations target 100% test coverage. Run 'binman test -T' to check this. |
Simon Glass | 52debad | 2016-11-25 20:15:59 -0700 | [diff] [blame] | 1229 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 1230 | To enable Python test coverage on Debian-type distributions (e.g. Ubuntu):: |
Simon Glass | 52debad | 2016-11-25 20:15:59 -0700 | [diff] [blame] | 1231 | |
Simon Glass | a16dd6e | 2019-07-08 13:18:26 -0600 | [diff] [blame] | 1232 | $ sudo apt-get install python-coverage python3-coverage python-pytest |
Simon Glass | 52debad | 2016-11-25 20:15:59 -0700 | [diff] [blame] | 1233 | |
| 1234 | |
Simon Glass | ddd5e1d | 2022-01-23 12:55:46 -0700 | [diff] [blame] | 1235 | Error messages |
| 1236 | -------------- |
| 1237 | |
| 1238 | This section provides some guidance for some of the less obvious error messages |
| 1239 | produced by binman. |
| 1240 | |
| 1241 | |
| 1242 | Expected __bss_size symbol |
| 1243 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 1244 | |
| 1245 | Example:: |
| 1246 | |
| 1247 | binman: Node '/binman/u-boot-spl-ddr/u-boot-spl/u-boot-spl-bss-pad': |
| 1248 | Expected __bss_size symbol in spl/u-boot-spl |
| 1249 | |
| 1250 | This indicates that binman needs the `__bss_size` symbol to be defined in the |
| 1251 | SPL binary, where `spl/u-boot-spl` is the ELF file containing the symbols. The |
| 1252 | symbol tells binman the size of the BSS region, in bytes. It needs this to be |
| 1253 | able to pad the image so that the following entries do not overlap the BSS, |
| 1254 | which would cause them to be overwritte by variable access in SPL. |
| 1255 | |
| 1256 | This symbols is normally defined in the linker script, immediately after |
| 1257 | _bss_start and __bss_end are defined, like this:: |
| 1258 | |
| 1259 | __bss_size = __bss_end - __bss_start; |
| 1260 | |
| 1261 | You may need to add it to your linker script if you get this error. |
| 1262 | |
| 1263 | |
Simon Glass | 1aeb751 | 2019-05-17 22:00:52 -0600 | [diff] [blame] | 1264 | Concurrent tests |
| 1265 | ---------------- |
| 1266 | |
| 1267 | Binman tries to run tests concurrently. This means that the tests make use of |
| 1268 | all available CPUs to run. |
| 1269 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 1270 | To enable this:: |
Simon Glass | 1aeb751 | 2019-05-17 22:00:52 -0600 | [diff] [blame] | 1271 | |
| 1272 | $ sudo apt-get install python-subunit python3-subunit |
| 1273 | |
| 1274 | Use '-P 1' to disable this. It is automatically disabled when code coverage is |
| 1275 | being used (-T) since they are incompatible. |
| 1276 | |
| 1277 | |
Simon Glass | 1c420c9 | 2019-07-08 13:18:49 -0600 | [diff] [blame] | 1278 | Debugging tests |
| 1279 | --------------- |
| 1280 | |
| 1281 | Sometimes when debugging tests it is useful to keep the input and output |
| 1282 | directories so they can be examined later. Use -X or --test-preserve-dirs for |
| 1283 | this. |
| 1284 | |
| 1285 | |
Alper Nebi Yasak | fb4e538 | 2020-09-06 14:46:07 +0300 | [diff] [blame] | 1286 | Running tests on non-x86 architectures |
| 1287 | -------------------------------------- |
| 1288 | |
| 1289 | Binman's tests have been written under the assumption that they'll be run on a |
| 1290 | x86-like host and there hasn't been an attempt to make them portable yet. |
| 1291 | However, it's possible to run the tests by cross-compiling to x86. |
| 1292 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 1293 | 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] | 1294 | |
| 1295 | $ sudo apt-get install gcc-x86-64-linux-gnu |
| 1296 | |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 1297 | Then, you can run the tests under cross-compilation:: |
Alper Nebi Yasak | fb4e538 | 2020-09-06 14:46:07 +0300 | [diff] [blame] | 1298 | |
| 1299 | $ CROSS_COMPILE=x86_64-linux-gnu- binman test -T |
| 1300 | |
| 1301 | You can also use gcc-i686-linux-gnu similar to the above. |
| 1302 | |
| 1303 | |
Simon Glass | fa88828 | 2021-03-18 20:25:14 +1300 | [diff] [blame] | 1304 | Writing new entries and debugging |
| 1305 | --------------------------------- |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1306 | |
| 1307 | The behaviour of entries is defined by the Entry class. All other entries are |
| 1308 | a subclass of this. An important subclass is Entry_blob which takes binary |
| 1309 | data from a file and places it in the entry. In fact most entry types are |
| 1310 | subclasses of Entry_blob. |
| 1311 | |
| 1312 | Each entry type is a separate file in the tools/binman/etype directory. Each |
| 1313 | file contains a class called Entry_<type> where <type> is the entry type. |
| 1314 | New entry types can be supported by adding new files in that directory. |
| 1315 | These will automatically be detected by binman when needed. |
| 1316 | |
| 1317 | Entry properties are documented in entry.py. The entry subclasses are free |
| 1318 | to change the values of properties to support special behaviour. For example, |
| 1319 | when Entry_blob loads a file, it sets content_size to the size of the file. |
| 1320 | Entry classes can adjust other entries. For example, an entry that knows |
Simon Glass | e8561af | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 1321 | where other entries should be positioned can set up those entries' offsets |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1322 | so they don't need to be set in the binman decription. It can also adjust |
| 1323 | entry contents. |
| 1324 | |
| 1325 | Most of the time such essoteric behaviour is not needed, but it can be |
| 1326 | essential for complex images. |
| 1327 | |
Simon Glass | ade2ef6 | 2017-12-24 12:12:07 -0700 | [diff] [blame] | 1328 | If you need to specify a particular device-tree compiler to use, you can define |
| 1329 | the DTC environment variable. This can be useful when the system dtc is too |
| 1330 | old. |
| 1331 | |
Simon Glass | e64a092 | 2018-11-06 15:21:31 -0700 | [diff] [blame] | 1332 | To enable a full backtrace and other debugging features in binman, pass |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 1333 | BINMAN_DEBUG=1 to your build:: |
Simon Glass | e64a092 | 2018-11-06 15:21:31 -0700 | [diff] [blame] | 1334 | |
Bin Meng | a089c41 | 2019-10-02 19:07:29 -0700 | [diff] [blame] | 1335 | make qemu-x86_defconfig |
Simon Glass | e64a092 | 2018-11-06 15:21:31 -0700 | [diff] [blame] | 1336 | make BINMAN_DEBUG=1 |
| 1337 | |
Simon Glass | 03b1d8f | 2019-09-25 08:11:11 -0600 | [diff] [blame] | 1338 | 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] | 1339 | adds a -v<level> option to the call to binman:: |
Simon Glass | 03b1d8f | 2019-09-25 08:11:11 -0600 | [diff] [blame] | 1340 | |
Bin Meng | a089c41 | 2019-10-02 19:07:29 -0700 | [diff] [blame] | 1341 | make qemu-x86_defconfig |
Simon Glass | 03b1d8f | 2019-09-25 08:11:11 -0600 | [diff] [blame] | 1342 | make BINMAN_VERBOSE=5 |
| 1343 | |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1344 | |
Simon Glass | 76f496d | 2021-07-06 10:36:37 -0600 | [diff] [blame] | 1345 | Building sections in parallel |
| 1346 | ----------------------------- |
| 1347 | |
| 1348 | By default binman uses multiprocessing to speed up compilation of large images. |
| 1349 | This works at a section level, with one thread for each entry in the section. |
| 1350 | This can speed things up if the entries are large and use compression. |
| 1351 | |
| 1352 | This feature can be disabled with the '-T' flag, which defaults to a suitable |
| 1353 | value for your machine. This depends on the Python version, e.g on v3.8 it uses |
| 1354 | 12 threads on an 8-core machine. See ConcurrentFutures_ for more details. |
| 1355 | |
| 1356 | The special value -T0 selects single-threaded mode, useful for debugging during |
| 1357 | development, since dealing with exceptions and problems in threads is more |
| 1358 | difficult. This avoids any use of ThreadPoolExecutor. |
| 1359 | |
| 1360 | |
Simon Glass | 6fba35c | 2022-02-08 11:50:00 -0700 | [diff] [blame] | 1361 | Collecting data for an entry type |
| 1362 | --------------------------------- |
| 1363 | |
| 1364 | Some entry types deal with data obtained from others. For example, |
| 1365 | `Entry_mkimage` calls the `mkimage` tool with data from its subnodes:: |
| 1366 | |
| 1367 | mkimage { |
| 1368 | args = "-n test -T script"; |
| 1369 | |
| 1370 | u-boot-spl { |
| 1371 | }; |
| 1372 | |
| 1373 | u-boot { |
| 1374 | }; |
| 1375 | }; |
| 1376 | |
| 1377 | This shows mkimage being passed a file consisting of SPL and U-Boot proper. It |
| 1378 | is create by calling `Entry.collect_contents_to_file()`. Note that in this case, |
| 1379 | the data is passed to mkimage for processing but does not appear separately in |
| 1380 | the image. It may not appear at all, depending on what mkimage does. The |
| 1381 | contents of the `mkimage` entry are entirely dependent on the processing done |
| 1382 | by the entry, with the provided subnodes (`u-boot-spl` and `u-boot`) simply |
| 1383 | providing the input data for that processing. |
| 1384 | |
| 1385 | Note that `Entry.collect_contents_to_file()` simply concatenates the data from |
| 1386 | the different entries together, with no control over alignment, etc. Another |
| 1387 | approach is to subclass `Entry_section` so that those features become available, |
| 1388 | such as `size` and `pad-byte`. Then the contents of the entry can be obtained by |
| 1389 | calling `BuildSectionData()`. |
| 1390 | |
| 1391 | There are other ways to obtain data also, depending on the situation. If the |
| 1392 | entry type is simply signing data which exists elsewhere in the image, then |
| 1393 | you can use `Entry_collection` as a base class. It lets you use a property |
| 1394 | called `content` which lists the entries containing data to be processed. This |
| 1395 | is used by `Entry_vblock`, for example:: |
| 1396 | |
| 1397 | u_boot: u-boot { |
| 1398 | }; |
| 1399 | vblock { |
| 1400 | content = <&u_boot &dtb>; |
| 1401 | keyblock = "firmware.keyblock"; |
| 1402 | signprivate = "firmware_data_key.vbprivk"; |
| 1403 | version = <1>; |
| 1404 | kernelkey = "kernel_subkey.vbpubk"; |
| 1405 | preamble-flags = <1>; |
| 1406 | }; |
| 1407 | |
| 1408 | dtb: u-boot-dtb { |
| 1409 | }; |
| 1410 | |
| 1411 | which shows an image containing `u-boot` and `u-boot-dtb`, with the `vblock` |
| 1412 | image collecting their contents to produce input for its signing process, |
| 1413 | without affecting those entries, which still appear in the final image |
| 1414 | untouched. |
| 1415 | |
| 1416 | Another example is where an entry type needs several independent pieces of input |
| 1417 | to function. For example, `Entry_fip` allows a number of different binary blobs |
| 1418 | to be placed in their own individual places in a custom data structure in the |
| 1419 | output image. To make that work you can add subnodes for each of them and call |
| 1420 | `Entry.Create()` on each subnode, as `Entry_fip` does. Then the data for each |
| 1421 | blob can come from any suitable place, such as an `Entry_u_boot` or an |
| 1422 | `Entry_blob` or anything else:: |
| 1423 | |
| 1424 | atf-fip { |
| 1425 | fip-hdr-flags = /bits/ 64 <0x123>; |
| 1426 | soc-fw { |
| 1427 | fip-flags = /bits/ 64 <0x123456789abcdef>; |
| 1428 | filename = "bl31.bin"; |
| 1429 | }; |
| 1430 | |
| 1431 | u-boot { |
| 1432 | fip-uuid = [fc 65 13 92 4a 5b 11 ec |
| 1433 | 94 35 ff 2d 1c fc 79 9c]; |
| 1434 | }; |
| 1435 | }; |
| 1436 | |
| 1437 | The `soc-fw` node is a `blob-ext` (i.e. it reads in a named binary file) whereas |
| 1438 | `u-boot` is a normal entry type. This works because `Entry_fip` selects the |
| 1439 | `blob-ext` entry type if the node name (here `soc-fw`) is recognised as being |
| 1440 | a known blob type. |
| 1441 | |
| 1442 | When adding new entry types you are encouraged to use subnodes to provide the |
| 1443 | data for processing, unless the `content` approach is more suitable. Ad-hoc |
| 1444 | properties and other methods of obtaining data are discouraged, since it adds to |
| 1445 | confusion for users. |
| 1446 | |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1447 | History / Credits |
| 1448 | ----------------- |
| 1449 | |
| 1450 | Binman takes a lot of inspiration from a Chrome OS tool called |
| 1451 | 'cros_bundle_firmware', which I wrote some years ago. That tool was based on |
| 1452 | a reasonably simple and sound design but has expanded greatly over the |
| 1453 | years. In particular its handling of x86 images is convoluted. |
| 1454 | |
Simon Glass | 1e32400 | 2018-06-01 09:38:19 -0600 | [diff] [blame] | 1455 | Quite a few lessons have been learned which are hopefully applied here. |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1456 | |
| 1457 | |
| 1458 | Design notes |
| 1459 | ------------ |
| 1460 | |
| 1461 | On the face of it, a tool to create firmware images should be fairly simple: |
| 1462 | just find all the input binaries and place them at the right place in the |
| 1463 | image. The difficulty comes from the wide variety of input types (simple |
| 1464 | flat binaries containing code, packaged data with various headers), packing |
| 1465 | requirments (alignment, spacing, device boundaries) and other required |
| 1466 | features such as hierarchical images. |
| 1467 | |
| 1468 | The design challenge is to make it easy to create simple images, while |
| 1469 | allowing the more complex cases to be supported. For example, for most |
| 1470 | images we don't much care exactly where each binary ends up, so we should |
| 1471 | not have to specify that unnecessarily. |
| 1472 | |
| 1473 | New entry types should aim to provide simple usage where possible. If new |
| 1474 | core features are needed, they can be added in the Entry base class. |
| 1475 | |
| 1476 | |
| 1477 | To do |
| 1478 | ----- |
| 1479 | |
| 1480 | Some ideas: |
Simon Glass | 75ead66 | 2021-03-18 20:25:13 +1300 | [diff] [blame] | 1481 | |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1482 | - 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] | 1483 | to use device tree (such as a very small SPL image). For now, limited info is |
| 1484 | available via linker symbols |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1485 | - Allow easy building of images by specifying just the board name |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1486 | - Support building an image for a board (-b) more completely, with a |
| 1487 | configurable build directory |
Simon Glass | 8100a8e | 2019-07-20 12:24:02 -0600 | [diff] [blame] | 1488 | - Detect invalid properties in nodes |
| 1489 | - Sort the fdtmap by offset |
Simon Glass | 01ab229 | 2021-01-06 21:35:12 -0700 | [diff] [blame] | 1490 | - Output temporary files to a different directory |
Simon Glass | e87009da | 2022-02-08 11:49:57 -0700 | [diff] [blame] | 1491 | - Rationalise the fdt, fdt_util and pylibfdt modules which currently have some |
| 1492 | overlapping and confusing functionality |
| 1493 | - Update the fdt library to use a better format for Prop.value (the current one |
| 1494 | is useful for dtoc but not much else) |
| 1495 | - Figure out how to make Fdt support changing the node order, so that |
| 1496 | Node.AddSubnode() can support adding a node before another, existing node. |
| 1497 | Perhaps it should completely regenerate the flat tree? |
| 1498 | |
Simon Glass | 2574ef6 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1499 | |
| 1500 | -- |
| 1501 | Simon Glass <sjg@chromium.org> |
| 1502 | 7/7/2016 |
Simon Glass | 76f496d | 2021-07-06 10:36:37 -0600 | [diff] [blame] | 1503 | |
| 1504 | .. _ConcurrentFutures: https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.ThreadPoolExecutor |