Tom Rini | 83d290c | 2018-05-06 17:58:06 -0400 | [diff] [blame] | 1 | # SPDX-License-Identifier: GPL-2.0+ |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 2 | # Copyright (c) 2016 Google, Inc |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 3 | |
| 4 | Introduction |
| 5 | ------------ |
| 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 | |
| 12 | So far U-Boot has not provided a way to handle creating such images in a |
| 13 | general way. Each SoC does what it needs to build an image, often packing or |
| 14 | concatenating images in the U-Boot build system. |
| 15 | |
| 16 | Binman aims to provide a mechanism for building images, from simple |
| 17 | SPL + U-Boot combinations, to more complex arrangements with many parts. |
| 18 | |
| 19 | |
| 20 | What it does |
| 21 | ------------ |
| 22 | |
| 23 | Binman reads your board's device tree and finds a node which describes the |
| 24 | required image layout. It uses this to work out what to place where. The |
| 25 | output file normally contains the device tree, so it is in principle possible |
| 26 | to read an image and extract its constituent parts. |
| 27 | |
| 28 | |
| 29 | Features |
| 30 | -------- |
| 31 | |
| 32 | So far binman is pretty simple. It supports binary blobs, such as 'u-boot', |
| 33 | 'spl' and 'fdt'. It supports empty entries (such as setting to 0xff). It can |
| 34 | place entries at a fixed location in the image, or fit them together with |
| 35 | suitable padding and alignment. It provides a way to process binaries before |
| 36 | they are included, by adding a Python plug-in. The device tree is available |
| 37 | to U-Boot at run-time so that the images can be interpreted. |
| 38 | |
Simon Glass | 5746018 | 2019-07-08 14:25:25 -0600 | [diff] [blame] | 39 | Binman can update the device tree with the final location of everything when it |
| 40 | is done. Entry positions can be provided to U-Boot SPL as run-time symbols, |
| 41 | avoiding device-tree code overhead. |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 42 | |
| 43 | Binman can also support incorporating filesystems in the image if required. |
| 44 | For example x86 platforms may use CBFS in some cases. |
| 45 | |
| 46 | Binman is intended for use with U-Boot but is designed to be general enough |
| 47 | to be useful in other image-packaging situations. |
| 48 | |
| 49 | |
| 50 | Motivation |
| 51 | ---------- |
| 52 | |
| 53 | Packaging of firmware is quite a different task from building the various |
| 54 | parts. In many cases the various binaries which go into the image come from |
| 55 | separate build systems. For example, ARM Trusted Firmware is used on ARMv8 |
| 56 | devices but is not built in the U-Boot tree. If a Linux kernel is included |
| 57 | in the firmware image, it is built elsewhere. |
| 58 | |
| 59 | It is of course possible to add more and more build rules to the U-Boot |
| 60 | build system to cover these cases. It can shell out to other Makefiles and |
| 61 | build scripts. But it seems better to create a clear divide between building |
| 62 | software and packaging it. |
| 63 | |
| 64 | At present this is handled by manual instructions, different for each board, |
| 65 | on how to create images that will boot. By turning these instructions into a |
| 66 | standard format, we can support making valid images for any board without |
| 67 | manual effort, lots of READMEs, etc. |
| 68 | |
| 69 | Benefits: |
| 70 | - Each binary can have its own build system and tool chain without creating |
| 71 | any dependencies between them |
| 72 | - Avoids the need for a single-shot build: individual parts can be updated |
| 73 | and brought in as needed |
| 74 | - Provides for a standard image description available in the build and at |
| 75 | run-time |
Thomas Hebb | 32f2ca2 | 2019-11-13 18:18:03 -0800 | [diff] [blame] | 76 | - SoC-specific image-signing tools can be accommodated |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 77 | - Avoids cluttering the U-Boot build system with image-building code |
| 78 | - The image description is automatically available at run-time in U-Boot, |
| 79 | SPL. It can be made available to other software also |
| 80 | - The image description is easily readable (it's a text file in device-tree |
| 81 | format) and permits flexible packing of binaries |
| 82 | |
| 83 | |
| 84 | Terminology |
| 85 | ----------- |
| 86 | |
| 87 | Binman uses the following terms: |
| 88 | |
| 89 | - image - an output file containing a firmware image |
| 90 | - binary - an input binary that goes into the image |
| 91 | |
| 92 | |
| 93 | Relationship to FIT |
| 94 | ------------------- |
| 95 | |
| 96 | FIT is U-Boot's official image format. It supports multiple binaries with |
| 97 | load / execution addresses, compression. It also supports verification |
| 98 | through hashing and RSA signatures. |
| 99 | |
| 100 | FIT was originally designed to support booting a Linux kernel (with an |
| 101 | optional ramdisk) and device tree chosen from various options in the FIT. |
| 102 | Now that U-Boot supports configuration via device tree, it is possible to |
| 103 | load U-Boot from a FIT, with the device tree chosen by SPL. |
| 104 | |
| 105 | Binman considers FIT to be one of the binaries it can place in the image. |
| 106 | |
| 107 | Where possible it is best to put as much as possible in the FIT, with binman |
| 108 | used to deal with cases not covered by FIT. Examples include initial |
| 109 | execution (since FIT itself does not have an executable header) and dealing |
| 110 | with device boundaries, such as the read-only/read-write separation in SPI |
| 111 | flash. |
| 112 | |
| 113 | For U-Boot, binman should not be used to create ad-hoc images in place of |
| 114 | FIT. |
| 115 | |
| 116 | |
| 117 | Relationship to mkimage |
| 118 | ----------------------- |
| 119 | |
| 120 | The mkimage tool provides a means to create a FIT. Traditionally it has |
| 121 | needed an image description file: a device tree, like binman, but in a |
| 122 | different format. More recently it has started to support a '-f auto' mode |
| 123 | which can generate that automatically. |
| 124 | |
| 125 | More relevant to binman, mkimage also permits creation of many SoC-specific |
| 126 | image types. These can be listed by running 'mkimage -T list'. Examples |
| 127 | include 'rksd', the Rockchip SD/MMC boot format. The mkimage tool is often |
| 128 | called from the U-Boot build system for this reason. |
| 129 | |
| 130 | Binman considers the output files created by mkimage to be binary blobs |
| 131 | which it can place in an image. Binman does not replace the mkimage tool or |
Michael Heimpold | 383d256 | 2018-08-22 22:01:24 +0200 | [diff] [blame] | 132 | this purpose. It would be possible in some situations to create a new entry |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 133 | type for the images in mkimage, but this would not add functionality. It |
Michael Heimpold | 383d256 | 2018-08-22 22:01:24 +0200 | [diff] [blame] | 134 | seems better to use the mkimage tool to generate binaries and avoid blurring |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 135 | the boundaries between building input files (mkimage) and packaging then |
| 136 | into a final image (binman). |
| 137 | |
| 138 | |
| 139 | Example use of binman in U-Boot |
| 140 | ------------------------------- |
| 141 | |
| 142 | Binman aims to replace some of the ad-hoc image creation in the U-Boot |
| 143 | build system. |
| 144 | |
| 145 | Consider sunxi. It has the following steps: |
| 146 | |
| 147 | 1. It uses a custom mksunxiboot tool to build an SPL image called |
| 148 | sunxi-spl.bin. This should probably move into mkimage. |
| 149 | |
| 150 | 2. It uses mkimage to package U-Boot into a legacy image file (so that it can |
| 151 | hold the load and execution address) called u-boot.img. |
| 152 | |
| 153 | 3. It builds a final output image called u-boot-sunxi-with-spl.bin which |
| 154 | consists of sunxi-spl.bin, some padding and u-boot.img. |
| 155 | |
| 156 | Binman is intended to replace the last step. The U-Boot build system builds |
| 157 | u-boot.bin and sunxi-spl.bin. Binman can then take over creation of |
| 158 | sunxi-spl.bin (by calling mksunxiboot, or hopefully one day mkimage). In any |
| 159 | case, it would then create the image from the component parts. |
| 160 | |
| 161 | This simplifies the U-Boot Makefile somewhat, since various pieces of logic |
| 162 | can be replaced by a call to binman. |
| 163 | |
| 164 | |
| 165 | Example use of binman for x86 |
| 166 | ----------------------------- |
| 167 | |
| 168 | In most cases x86 images have a lot of binary blobs, 'black-box' code |
| 169 | provided by Intel which must be run for the platform to work. Typically |
| 170 | these blobs are not relocatable and must be placed at fixed areas in the |
Michael Heimpold | 383d256 | 2018-08-22 22:01:24 +0200 | [diff] [blame] | 171 | firmware image. |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 172 | |
| 173 | Currently this is handled by ifdtool, which places microcode, FSP, MRC, VGA |
| 174 | BIOS, reference code and Intel ME binaries into a u-boot.rom file. |
| 175 | |
| 176 | Binman is intended to replace all of this, with ifdtool left to handle only |
| 177 | the configuration of the Intel-format descriptor. |
| 178 | |
| 179 | |
| 180 | Running binman |
| 181 | -------------- |
| 182 | |
Simon Glass | d8d4074 | 2019-07-08 13:18:35 -0600 | [diff] [blame] | 183 | First install prerequisites, e.g. |
| 184 | |
Simon Glass | 07d9e70 | 2019-07-08 13:18:41 -0600 | [diff] [blame] | 185 | sudo apt-get install python-pyelftools python3-pyelftools lzma-alone \ |
| 186 | liblz4-tool |
Simon Glass | d8d4074 | 2019-07-08 13:18:35 -0600 | [diff] [blame] | 187 | |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 188 | Type: |
| 189 | |
Simon Glass | 53cd5d9 | 2019-07-08 14:25:29 -0600 | [diff] [blame] | 190 | binman build -b <board_name> |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 191 | |
| 192 | to build an image for a board. The board name is the same name used when |
| 193 | configuring U-Boot (e.g. for sandbox_defconfig the board name is 'sandbox'). |
| 194 | Binman assumes that the input files for the build are in ../b/<board_name>. |
| 195 | |
| 196 | Or you can specify this explicitly: |
| 197 | |
Simon Glass | 53cd5d9 | 2019-07-08 14:25:29 -0600 | [diff] [blame] | 198 | binman build -I <build_path> |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 199 | |
| 200 | where <build_path> is the build directory containing the output of the U-Boot |
| 201 | build. |
| 202 | |
| 203 | (Future work will make this more configurable) |
| 204 | |
| 205 | In either case, binman picks up the device tree file (u-boot.dtb) and looks |
| 206 | for its instructions in the 'binman' node. |
| 207 | |
| 208 | Binman has a few other options which you can see by running 'binman -h'. |
| 209 | |
| 210 | |
Simon Glass | 9c0a8b1 | 2017-11-12 21:52:06 -0700 | [diff] [blame] | 211 | Enabling binman for a board |
| 212 | --------------------------- |
| 213 | |
| 214 | At present binman is invoked from a rule in the main Makefile. Typically you |
| 215 | will have a rule like: |
| 216 | |
| 217 | ifneq ($(CONFIG_ARCH_<something>),) |
| 218 | u-boot-<your_suffix>.bin: <input_file_1> <input_file_2> checkbinman FORCE |
| 219 | $(call if_changed,binman) |
| 220 | endif |
| 221 | |
| 222 | This assumes that u-boot-<your_suffix>.bin is a target, and is the final file |
| 223 | that you need to produce. You can make it a target by adding it to ALL-y |
| 224 | either in the main Makefile or in a config.mk file in your arch subdirectory. |
| 225 | |
| 226 | Once binman is executed it will pick up its instructions from a device-tree |
| 227 | file, typically <soc>-u-boot.dtsi, where <soc> is your CONFIG_SYS_SOC value. |
| 228 | You can use other, more specific CONFIG options - see 'Automatic .dtsi |
| 229 | inclusion' below. |
| 230 | |
| 231 | |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 232 | Image description format |
| 233 | ------------------------ |
| 234 | |
| 235 | The binman node is called 'binman'. An example image description is shown |
| 236 | below: |
| 237 | |
| 238 | binman { |
| 239 | filename = "u-boot-sunxi-with-spl.bin"; |
| 240 | pad-byte = <0xff>; |
| 241 | blob { |
| 242 | filename = "spl/sunxi-spl.bin"; |
| 243 | }; |
| 244 | u-boot { |
Simon Glass | 3ab9598 | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 245 | offset = <CONFIG_SPL_PAD_TO>; |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 246 | }; |
| 247 | }; |
| 248 | |
| 249 | |
| 250 | This requests binman to create an image file called u-boot-sunxi-with-spl.bin |
| 251 | consisting of a specially formatted SPL (spl/sunxi-spl.bin, built by the |
| 252 | normal U-Boot Makefile), some 0xff padding, and a U-Boot legacy image. The |
| 253 | padding comes from the fact that the second binary is placed at |
| 254 | CONFIG_SPL_PAD_TO. If that line were omitted then the U-Boot binary would |
| 255 | immediately follow the SPL binary. |
| 256 | |
| 257 | The binman node describes an image. The sub-nodes describe entries in the |
| 258 | image. Each entry represents a region within the overall image. The name of |
| 259 | the entry (blob, u-boot) tells binman what to put there. For 'blob' we must |
| 260 | provide a filename. For 'u-boot', binman knows that this means 'u-boot.bin'. |
| 261 | |
| 262 | Entries are normally placed into the image sequentially, one after the other. |
| 263 | The image size is the total size of all entries. As you can see, you can |
Simon Glass | 3ab9598 | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 264 | specify the start offset of an entry using the 'offset' property. |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 265 | |
| 266 | Note that due to a device tree requirement, all entries must have a unique |
| 267 | name. If you want to put the same binary in the image multiple times, you can |
| 268 | use any unique name, with the 'type' property providing the type. |
| 269 | |
| 270 | The attributes supported for entries are described below. |
| 271 | |
Simon Glass | 3ab9598 | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 272 | offset: |
| 273 | This sets the offset of an entry within the image or section containing |
| 274 | it. The first byte of the image is normally at offset 0. If 'offset' is |
| 275 | not provided, binman sets it to the end of the previous region, or the |
| 276 | start of the image's entry area (normally 0) if there is no previous |
| 277 | region. |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 278 | |
| 279 | align: |
Simon Glass | 3ab9598 | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 280 | This sets the alignment of the entry. The entry offset is adjusted |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 281 | so that the entry starts on an aligned boundary within the image. For |
| 282 | example 'align = <16>' means that the entry will start on a 16-byte |
| 283 | boundary. Alignment shold be a power of 2. If 'align' is not |
| 284 | provided, no alignment is performed. |
| 285 | |
| 286 | size: |
| 287 | This sets the size of the entry. The contents will be padded out to |
| 288 | this size. If this is not provided, it will be set to the size of the |
| 289 | contents. |
| 290 | |
| 291 | pad-before: |
| 292 | Padding before the contents of the entry. Normally this is 0, meaning |
| 293 | that the contents start at the beginning of the entry. This can be |
| 294 | offset the entry contents a little. Defaults to 0. |
| 295 | |
| 296 | pad-after: |
| 297 | Padding after the contents of the entry. Normally this is 0, meaning |
| 298 | that the entry ends at the last byte of content (unless adjusted by |
| 299 | other properties). This allows room to be created in the image for |
| 300 | this entry to expand later. Defaults to 0. |
| 301 | |
| 302 | align-size: |
| 303 | This sets the alignment of the entry size. For example, to ensure |
| 304 | that the size of an entry is a multiple of 64 bytes, set this to 64. |
| 305 | If 'align-size' is not provided, no alignment is performed. |
| 306 | |
| 307 | align-end: |
| 308 | This sets the alignment of the end of an entry. Some entries require |
| 309 | that they end on an alignment boundary, regardless of where they |
Simon Glass | 844e5b2 | 2018-06-01 09:38:22 -0600 | [diff] [blame] | 310 | start. This does not move the start of the entry, so the contents of |
| 311 | the entry will still start at the beginning. But there may be padding |
| 312 | at the end. If 'align-end' is not provided, no alignment is performed. |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 313 | |
| 314 | filename: |
| 315 | For 'blob' types this provides the filename containing the binary to |
| 316 | put into the entry. If binman knows about the entry type (like |
| 317 | u-boot-bin), then there is no need to specify this. |
| 318 | |
| 319 | type: |
| 320 | Sets the type of an entry. This defaults to the entry name, but it is |
| 321 | possible to use any name, and then add (for example) 'type = "u-boot"' |
| 322 | to specify the type. |
| 323 | |
Simon Glass | 3ab9598 | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 324 | offset-unset: |
| 325 | Indicates that the offset of this entry should not be set by placing |
Simon Glass | 258fb0e | 2018-06-01 09:38:17 -0600 | [diff] [blame] | 326 | it immediately after the entry before. Instead, is set by another |
| 327 | entry which knows where this entry should go. When this boolean |
| 328 | property is present, binman will give an error if another entry does |
Simon Glass | 3ab9598 | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 329 | not set the offset (with the GetOffsets() method). |
Simon Glass | 258fb0e | 2018-06-01 09:38:17 -0600 | [diff] [blame] | 330 | |
Simon Glass | dbf6be9 | 2018-08-01 15:22:42 -0600 | [diff] [blame] | 331 | image-pos: |
| 332 | This cannot be set on entry (or at least it is ignored if it is), but |
| 333 | with the -u option, binman will set it to the absolute image position |
| 334 | for each entry. This makes it easy to find out exactly where the entry |
| 335 | ended up in the image, regardless of parent sections, etc. |
| 336 | |
Simon Glass | ba64a0b | 2018-09-14 04:57:29 -0600 | [diff] [blame] | 337 | expand-size: |
| 338 | Expand the size of this entry to fit available space. This space is only |
| 339 | limited by the size of the image/section and the position of the next |
| 340 | entry. |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 341 | |
Simon Glass | 8287ee8 | 2019-07-08 14:25:30 -0600 | [diff] [blame] | 342 | compress: |
| 343 | Sets the compression algortihm to use (for blobs only). See the entry |
| 344 | documentation for details. |
| 345 | |
Simon Glass | 9c888cc | 2018-09-14 04:57:30 -0600 | [diff] [blame] | 346 | The attributes supported for images and sections are described below. Several |
| 347 | are similar to those for entries. |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 348 | |
| 349 | size: |
| 350 | Sets the image size in bytes, for example 'size = <0x100000>' for a |
| 351 | 1MB image. |
| 352 | |
Simon Glass | 9481c80 | 2019-04-25 21:58:39 -0600 | [diff] [blame] | 353 | offset: |
| 354 | This is similar to 'offset' in entries, setting the offset of a section |
| 355 | within the image or section containing it. The first byte of the section |
| 356 | is normally at offset 0. If 'offset' is not provided, binman sets it to |
| 357 | the end of the previous region, or the start of the image's entry area |
| 358 | (normally 0) if there is no previous region. |
| 359 | |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 360 | align-size: |
| 361 | This sets the alignment of the image size. For example, to ensure |
| 362 | that the image ends on a 512-byte boundary, use 'align-size = <512>'. |
| 363 | If 'align-size' is not provided, no alignment is performed. |
| 364 | |
| 365 | pad-before: |
| 366 | This sets the padding before the image entries. The first entry will |
Simon Glass | 3ab9598 | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 367 | be positioned after the padding. This defaults to 0. |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 368 | |
| 369 | pad-after: |
| 370 | This sets the padding after the image entries. The padding will be |
| 371 | placed after the last entry. This defaults to 0. |
| 372 | |
| 373 | pad-byte: |
| 374 | This specifies the pad byte to use when padding in the image. It |
| 375 | defaults to 0. To use 0xff, you would add 'pad-byte = <0xff>'. |
| 376 | |
| 377 | filename: |
| 378 | This specifies the image filename. It defaults to 'image.bin'. |
| 379 | |
Simon Glass | 3ab9598 | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 380 | sort-by-offset: |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 381 | This causes binman to reorder the entries as needed to make sure they |
| 382 | are in increasing positional order. This can be used when your entry |
| 383 | order may not match the positional order. A common situation is where |
Simon Glass | 3ab9598 | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 384 | the 'offset' properties are set by CONFIG options, so their ordering is |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 385 | not known a priori. |
| 386 | |
| 387 | This is a boolean property so needs no value. To enable it, add a |
Simon Glass | 3ab9598 | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 388 | line 'sort-by-offset;' to your description. |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 389 | |
| 390 | multiple-images: |
| 391 | Normally only a single image is generated. To create more than one |
| 392 | image, put this property in the binman node. For example, this will |
| 393 | create image1.bin containing u-boot.bin, and image2.bin containing |
| 394 | both spl/u-boot-spl.bin and u-boot.bin: |
| 395 | |
| 396 | binman { |
| 397 | multiple-images; |
| 398 | image1 { |
| 399 | u-boot { |
| 400 | }; |
| 401 | }; |
| 402 | |
| 403 | image2 { |
| 404 | spl { |
| 405 | }; |
| 406 | u-boot { |
| 407 | }; |
| 408 | }; |
| 409 | }; |
| 410 | |
| 411 | end-at-4gb: |
Simon Glass | 3ab9598 | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 412 | For x86 machines the ROM offsets start just before 4GB and extend |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 413 | up so that the image finished at the 4GB boundary. This boolean |
| 414 | option can be enabled to support this. The image size must be |
| 415 | provided so that binman knows when the image should start. For an |
Simon Glass | 3ab9598 | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 416 | 8MB ROM, the offset of the first entry would be 0xfff80000 with |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 417 | this option, instead of 0 without this option. |
| 418 | |
Jagdish Gediya | 94b57db | 2018-09-03 21:35:07 +0530 | [diff] [blame] | 419 | skip-at-start: |
| 420 | This property specifies the entry offset of the first entry. |
| 421 | |
| 422 | For PowerPC mpc85xx based CPU, CONFIG_SYS_TEXT_BASE is the entry |
| 423 | offset of the first entry. It can be 0xeff40000 or 0xfff40000 for |
| 424 | nor flash boot, 0x201000 for sd boot etc. |
| 425 | |
| 426 | 'end-at-4gb' property is not applicable where CONFIG_SYS_TEXT_BASE + |
| 427 | Image size != 4gb. |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 428 | |
| 429 | Examples of the above options can be found in the tests. See the |
| 430 | tools/binman/test directory. |
| 431 | |
Simon Glass | dd57c13 | 2018-06-01 09:38:11 -0600 | [diff] [blame] | 432 | It is possible to have the same binary appear multiple times in the image, |
| 433 | either by using a unit number suffix (u-boot@0, u-boot@1) or by using a |
| 434 | different name for each and specifying the type with the 'type' attribute. |
| 435 | |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 436 | |
Michael Heimpold | 383d256 | 2018-08-22 22:01:24 +0200 | [diff] [blame] | 437 | Sections and hierachical images |
Simon Glass | 1854695 | 2018-06-01 09:38:16 -0600 | [diff] [blame] | 438 | ------------------------------- |
| 439 | |
| 440 | Sometimes it is convenient to split an image into several pieces, each of which |
| 441 | contains its own set of binaries. An example is a flash device where part of |
| 442 | the image is read-only and part is read-write. We can set up sections for each |
| 443 | of these, and place binaries in them independently. The image is still produced |
| 444 | as a single output file. |
| 445 | |
| 446 | This feature provides a way of creating hierarchical images. For example here |
Simon Glass | 7ae5f31 | 2018-06-01 09:38:19 -0600 | [diff] [blame] | 447 | is an example image with two copies of U-Boot. One is read-only (ro), intended |
| 448 | to be written only in the factory. Another is read-write (rw), so that it can be |
Simon Glass | 1854695 | 2018-06-01 09:38:16 -0600 | [diff] [blame] | 449 | upgraded in the field. The sizes are fixed so that the ro/rw boundary is known |
| 450 | and can be programmed: |
| 451 | |
| 452 | binman { |
| 453 | section@0 { |
| 454 | read-only; |
Simon Glass | c8d48ef | 2018-06-01 09:38:21 -0600 | [diff] [blame] | 455 | name-prefix = "ro-"; |
Simon Glass | 1854695 | 2018-06-01 09:38:16 -0600 | [diff] [blame] | 456 | size = <0x100000>; |
| 457 | u-boot { |
| 458 | }; |
| 459 | }; |
| 460 | section@1 { |
Simon Glass | c8d48ef | 2018-06-01 09:38:21 -0600 | [diff] [blame] | 461 | name-prefix = "rw-"; |
Simon Glass | 1854695 | 2018-06-01 09:38:16 -0600 | [diff] [blame] | 462 | size = <0x100000>; |
| 463 | u-boot { |
| 464 | }; |
| 465 | }; |
| 466 | }; |
| 467 | |
| 468 | This image could be placed into a SPI flash chip, with the protection boundary |
| 469 | set at 1MB. |
| 470 | |
| 471 | A few special properties are provided for sections: |
| 472 | |
| 473 | read-only: |
| 474 | Indicates that this section is read-only. This has no impact on binman's |
| 475 | operation, but his property can be read at run time. |
| 476 | |
Simon Glass | c8d48ef | 2018-06-01 09:38:21 -0600 | [diff] [blame] | 477 | name-prefix: |
| 478 | This string is prepended to all the names of the binaries in the |
| 479 | section. In the example above, the 'u-boot' binaries which actually be |
| 480 | renamed to 'ro-u-boot' and 'rw-u-boot'. This can be useful to |
| 481 | distinguish binaries with otherwise identical names. |
| 482 | |
Simon Glass | 1854695 | 2018-06-01 09:38:16 -0600 | [diff] [blame] | 483 | |
Simon Glass | 12bb1a9 | 2019-07-20 12:23:51 -0600 | [diff] [blame] | 484 | Image Properties |
| 485 | ---------------- |
| 486 | |
| 487 | Image nodes act like sections but also have a few extra properties: |
| 488 | |
| 489 | filename: |
| 490 | Output filename for the image. This defaults to image.bin (or in the |
| 491 | case of multiple images <nodename>.bin where <nodename> is the name of |
| 492 | the image node. |
| 493 | |
| 494 | allow-repack: |
| 495 | Create an image that can be repacked. With this option it is possible |
| 496 | to change anything in the image after it is created, including updating |
| 497 | the position and size of image components. By default this is not |
| 498 | permitted since it is not possibly to know whether this might violate a |
| 499 | constraint in the image description. For example, if a section has to |
| 500 | increase in size to hold a larger binary, that might cause the section |
| 501 | to fall out of its allow region (e.g. read-only portion of flash). |
| 502 | |
| 503 | Adding this property causes the original offset and size values in the |
| 504 | image description to be stored in the FDT and fdtmap. |
| 505 | |
| 506 | |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 507 | Entry Documentation |
| 508 | ------------------- |
| 509 | |
| 510 | For details on the various entry types supported by binman and how to use them, |
| 511 | see README.entries. This is generated from the source code using: |
| 512 | |
Simon Glass | 53cd5d9 | 2019-07-08 14:25:29 -0600 | [diff] [blame] | 513 | binman entry-docs >tools/binman/README.entries |
Simon Glass | 5a5da7c | 2018-07-17 13:25:37 -0600 | [diff] [blame] | 514 | |
| 515 | |
Simon Glass | 61f564d | 2019-07-08 14:25:48 -0600 | [diff] [blame] | 516 | Listing images |
| 517 | -------------- |
| 518 | |
| 519 | It is possible to list the entries in an existing firmware image created by |
| 520 | binman, provided that there is an 'fdtmap' entry in the image. For example: |
| 521 | |
| 522 | $ binman ls -i image.bin |
| 523 | Name Image-pos Size Entry-type Offset Uncomp-size |
| 524 | ---------------------------------------------------------------------- |
| 525 | main-section c00 section 0 |
| 526 | u-boot 0 4 u-boot 0 |
| 527 | section 5fc section 4 |
| 528 | cbfs 100 400 cbfs 0 |
| 529 | u-boot 138 4 u-boot 38 |
| 530 | u-boot-dtb 180 108 u-boot-dtb 80 3b5 |
| 531 | u-boot-dtb 500 1ff u-boot-dtb 400 3b5 |
| 532 | fdtmap 6fc 381 fdtmap 6fc |
| 533 | image-header bf8 8 image-header bf8 |
| 534 | |
| 535 | This shows the hierarchy of the image, the position, size and type of each |
| 536 | entry, the offset of each entry within its parent and the uncompressed size if |
| 537 | the entry is compressed. |
| 538 | |
| 539 | It is also possible to list just some files in an image, e.g. |
| 540 | |
| 541 | $ binman ls -i image.bin section/cbfs |
| 542 | Name Image-pos Size Entry-type Offset Uncomp-size |
| 543 | -------------------------------------------------------------------- |
| 544 | cbfs 100 400 cbfs 0 |
| 545 | u-boot 138 4 u-boot 38 |
| 546 | u-boot-dtb 180 108 u-boot-dtb 80 3b5 |
| 547 | |
| 548 | or with wildcards: |
| 549 | |
| 550 | $ binman ls -i image.bin "*cb*" "*head*" |
| 551 | Name Image-pos Size Entry-type Offset Uncomp-size |
| 552 | ---------------------------------------------------------------------- |
| 553 | cbfs 100 400 cbfs 0 |
| 554 | u-boot 138 4 u-boot 38 |
| 555 | u-boot-dtb 180 108 u-boot-dtb 80 3b5 |
| 556 | image-header bf8 8 image-header bf8 |
| 557 | |
| 558 | |
Simon Glass | 71ce0ba | 2019-07-08 14:25:52 -0600 | [diff] [blame] | 559 | Extracting files from images |
| 560 | ---------------------------- |
| 561 | |
| 562 | You can extract files from an existing firmware image created by binman, |
| 563 | provided that there is an 'fdtmap' entry in the image. For example: |
| 564 | |
| 565 | $ binman extract -i image.bin section/cbfs/u-boot |
| 566 | |
| 567 | which will write the uncompressed contents of that entry to the file 'u-boot' in |
| 568 | the current directory. You can also extract to a particular file, in this case |
| 569 | u-boot.bin: |
| 570 | |
| 571 | $ binman extract -i image.bin section/cbfs/u-boot -f u-boot.bin |
| 572 | |
| 573 | It is possible to extract all files into a destination directory, which will |
| 574 | put files in subdirectories matching the entry hierarchy: |
| 575 | |
| 576 | $ binman extract -i image.bin -O outdir |
| 577 | |
| 578 | or just a selection: |
| 579 | |
| 580 | $ binman extract -i image.bin "*u-boot*" -O outdir |
| 581 | |
| 582 | |
Simon Glass | 10f9d00 | 2019-07-20 12:23:50 -0600 | [diff] [blame] | 583 | Replacing files in an image |
| 584 | --------------------------- |
| 585 | |
| 586 | You can replace files in an existing firmware image created by binman, provided |
| 587 | that there is an 'fdtmap' entry in the image. For example: |
| 588 | |
| 589 | $ binman replace -i image.bin section/cbfs/u-boot |
| 590 | |
| 591 | which will write the contents of the file 'u-boot' from the current directory |
Simon Glass | a6cb995 | 2019-07-20 12:24:15 -0600 | [diff] [blame] | 592 | to the that entry, compressing if necessary. If the entry size changes, you must |
| 593 | add the 'allow-repack' property to the original image before generating it (see |
| 594 | above), otherwise you will get an error. |
| 595 | |
| 596 | You can also use a particular file, in this case u-boot.bin: |
| 597 | |
| 598 | $ binman replace -i image.bin section/cbfs/u-boot -f u-boot.bin |
| 599 | |
| 600 | It is possible to replace all files from a source directory which uses the same |
| 601 | hierarchy as the entries: |
| 602 | |
| 603 | $ binman replace -i image.bin -I indir |
| 604 | |
| 605 | Files that are missing will generate a warning. |
| 606 | |
| 607 | You can also replace just a selection of entries: |
| 608 | |
| 609 | $ binman replace -i image.bin "*u-boot*" -I indir |
Simon Glass | 10f9d00 | 2019-07-20 12:23:50 -0600 | [diff] [blame] | 610 | |
| 611 | |
Simon Glass | eea264e | 2019-07-08 14:25:49 -0600 | [diff] [blame] | 612 | Logging |
| 613 | ------- |
| 614 | |
| 615 | Binman normally operates silently unless there is an error, in which case it |
| 616 | just displays the error. The -D/--debug option can be used to create a full |
| 617 | backtrace when errors occur. |
| 618 | |
| 619 | Internally binman logs some output while it is running. This can be displayed |
| 620 | by increasing the -v/--verbosity from the default of 1: |
| 621 | |
| 622 | 0: silent |
| 623 | 1: warnings only |
| 624 | 2: notices (important messages) |
| 625 | 3: info about major operations |
| 626 | 4: detailed information about each operation |
| 627 | 5: debug (all output) |
| 628 | |
| 629 | |
Simon Glass | e0e5df9 | 2018-09-14 04:57:31 -0600 | [diff] [blame] | 630 | Hashing Entries |
| 631 | --------------- |
Simon Glass | e0ff855 | 2016-11-25 20:15:53 -0700 | [diff] [blame] | 632 | |
Simon Glass | e0e5df9 | 2018-09-14 04:57:31 -0600 | [diff] [blame] | 633 | It is possible to ask binman to hash the contents of an entry and write that |
| 634 | value back to the device-tree node. For example: |
Simon Glass | e0ff855 | 2016-11-25 20:15:53 -0700 | [diff] [blame] | 635 | |
Simon Glass | e0e5df9 | 2018-09-14 04:57:31 -0600 | [diff] [blame] | 636 | binman { |
| 637 | u-boot { |
| 638 | hash { |
| 639 | algo = "sha256"; |
| 640 | }; |
| 641 | }; |
| 642 | }; |
| 643 | |
| 644 | Here, a new 'value' property will be written to the 'hash' node containing |
| 645 | the hash of the 'u-boot' entry. Only SHA256 is supported at present. Whole |
| 646 | sections can be hased if desired, by adding the 'hash' node to the section. |
| 647 | |
| 648 | The has value can be chcked at runtime by hashing the data actually read and |
| 649 | comparing this has to the value in the device tree. |
Simon Glass | e0ff855 | 2016-11-25 20:15:53 -0700 | [diff] [blame] | 650 | |
| 651 | |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 652 | Order of image creation |
| 653 | ----------------------- |
| 654 | |
| 655 | Image creation proceeds in the following order, for each entry in the image. |
| 656 | |
Simon Glass | 078ab1a | 2018-07-06 10:27:41 -0600 | [diff] [blame] | 657 | 1. AddMissingProperties() - binman can add calculated values to the device |
Simon Glass | 3ab9598 | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 658 | tree as part of its processing, for example the offset and size of each |
Simon Glass | 078ab1a | 2018-07-06 10:27:41 -0600 | [diff] [blame] | 659 | entry. This method adds any properties associated with this, expanding the |
| 660 | device tree as needed. These properties can have placeholder values which are |
| 661 | set later by SetCalculatedProperties(). By that stage the size of sections |
| 662 | cannot be changed (since it would cause the images to need to be repacked), |
| 663 | but the correct values can be inserted. |
| 664 | |
| 665 | 2. ProcessFdt() - process the device tree information as required by the |
Simon Glass | ecab897 | 2018-07-06 10:27:40 -0600 | [diff] [blame] | 666 | particular entry. This may involve adding or deleting properties. If the |
| 667 | processing is complete, this method should return True. If the processing |
| 668 | cannot complete because it needs the ProcessFdt() method of another entry to |
| 669 | run first, this method should return False, in which case it will be called |
| 670 | again later. |
| 671 | |
Simon Glass | 078ab1a | 2018-07-06 10:27:41 -0600 | [diff] [blame] | 672 | 3. GetEntryContents() - the contents of each entry are obtained, normally by |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 673 | reading from a file. This calls the Entry.ObtainContents() to read the |
| 674 | contents. The default version of Entry.ObtainContents() calls |
| 675 | Entry.GetDefaultFilename() and then reads that file. So a common mechanism |
| 676 | to select a file to read is to override that function in the subclass. The |
| 677 | functions must return True when they have read the contents. Binman will |
| 678 | retry calling the functions a few times if False is returned, allowing |
| 679 | dependencies between the contents of different entries. |
| 680 | |
Simon Glass | 3ab9598 | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 681 | 4. GetEntryOffsets() - calls Entry.GetOffsets() for each entry. This can |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 682 | return a dict containing entries that need updating. The key should be the |
Simon Glass | 3ab9598 | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 683 | entry name and the value is a tuple (offset, size). This allows an entry to |
| 684 | provide the offset and size for other entries. The default implementation |
| 685 | of GetEntryOffsets() returns {}. |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 686 | |
Simon Glass | 3ab9598 | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 687 | 5. PackEntries() - calls Entry.Pack() which figures out the offset and |
| 688 | size of an entry. The 'current' image offset is passed in, and the function |
| 689 | returns the offset immediately after the entry being packed. The default |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 690 | implementation of Pack() is usually sufficient. |
| 691 | |
Simon Glass | 078ab1a | 2018-07-06 10:27:41 -0600 | [diff] [blame] | 692 | 6. CheckSize() - checks that the contents of all the entries fits within |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 693 | the image size. If the image does not have a defined size, the size is set |
| 694 | large enough to hold all the entries. |
| 695 | |
Simon Glass | 078ab1a | 2018-07-06 10:27:41 -0600 | [diff] [blame] | 696 | 7. CheckEntries() - checks that the entries do not overlap, nor extend |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 697 | outside the image. |
| 698 | |
Simon Glass | 4ab88b6 | 2019-07-20 12:23:52 -0600 | [diff] [blame] | 699 | 8. SetImagePos() - sets the image position of every entry. This is the absolute |
| 700 | position 'image-pos', as opposed to 'offset' which is relative to the containing |
| 701 | section. This must be done after all offsets are known, which is why it is quite |
| 702 | late in the ordering. |
| 703 | |
| 704 | 9. SetCalculatedProperties() - update any calculated properties in the device |
Simon Glass | 3ab9598 | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 705 | tree. This sets the correct 'offset' and 'size' vaues, for example. |
Simon Glass | 078ab1a | 2018-07-06 10:27:41 -0600 | [diff] [blame] | 706 | |
Simon Glass | 4ab88b6 | 2019-07-20 12:23:52 -0600 | [diff] [blame] | 707 | 10. ProcessEntryContents() - this calls Entry.ProcessContents() on each entry. |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 708 | The default implementatoin does nothing. This can be overriden to adjust the |
| 709 | contents of an entry in some way. For example, it would be possible to create |
| 710 | an entry containing a hash of the contents of some other entries. At this |
Simon Glass | c52c9e7 | 2019-07-08 14:25:37 -0600 | [diff] [blame] | 711 | stage the offset and size of entries should not be adjusted unless absolutely |
| 712 | necessary, since it requires a repack (going back to PackEntries()). |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 713 | |
Simon Glass | 4ab88b6 | 2019-07-20 12:23:52 -0600 | [diff] [blame] | 714 | 11. ResetForPack() - if the ProcessEntryContents() step failed, in that an entry |
| 715 | has changed its size, then there is no alternative but to go back to step 5 and |
| 716 | try again, repacking the entries with the updated size. ResetForPack() removes |
| 717 | the fixed offset/size values added by binman, so that the packing can start from |
| 718 | scratch. |
| 719 | |
| 720 | 12. WriteSymbols() - write the value of symbols into the U-Boot SPL binary. |
Simon Glass | 3ab9598 | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 721 | See 'Access to binman entry offsets at run time' below for a description of |
Simon Glass | 0a4357c | 2018-07-06 10:27:39 -0600 | [diff] [blame] | 722 | what happens in this stage. |
Simon Glass | 39c1502 | 2017-11-13 18:55:05 -0700 | [diff] [blame] | 723 | |
Simon Glass | 4ab88b6 | 2019-07-20 12:23:52 -0600 | [diff] [blame] | 724 | 13. BuildImage() - builds the image and writes it to a file |
| 725 | |
| 726 | 14. WriteMap() - writes a text file containing a map of the image. This is the |
| 727 | final step. |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 728 | |
| 729 | |
Simon Glass | 6d427c6 | 2016-11-25 20:15:59 -0700 | [diff] [blame] | 730 | Automatic .dtsi inclusion |
| 731 | ------------------------- |
| 732 | |
| 733 | It is sometimes inconvenient to add a 'binman' node to the .dts file for each |
| 734 | board. This can be done by using #include to bring in a common file. Another |
| 735 | approach supported by the U-Boot build system is to automatically include |
| 736 | a common header. You can then put the binman node (and anything else that is |
| 737 | specific to U-Boot, such as u-boot,dm-pre-reloc properies) in that header |
| 738 | file. |
| 739 | |
| 740 | Binman will search for the following files in arch/<arch>/dts: |
| 741 | |
| 742 | <dts>-u-boot.dtsi where <dts> is the base name of the .dts file |
| 743 | <CONFIG_SYS_SOC>-u-boot.dtsi |
| 744 | <CONFIG_SYS_CPU>-u-boot.dtsi |
| 745 | <CONFIG_SYS_VENDOR>-u-boot.dtsi |
| 746 | u-boot.dtsi |
| 747 | |
| 748 | U-Boot will only use the first one that it finds. If you need to include a |
| 749 | more general file you can do that from the more specific file using #include. |
| 750 | If you are having trouble figuring out what is going on, you can uncomment |
| 751 | the 'warning' line in scripts/Makefile.lib to see what it has found: |
| 752 | |
| 753 | # Uncomment for debugging |
Simon Glass | 511fd0b | 2017-11-12 21:52:05 -0700 | [diff] [blame] | 754 | # This shows all the files that were considered and the one that we chose. |
| 755 | # u_boot_dtsi_options_debug = $(u_boot_dtsi_options_raw) |
Simon Glass | 6d427c6 | 2016-11-25 20:15:59 -0700 | [diff] [blame] | 756 | |
| 757 | |
Simon Glass | dbf6be9 | 2018-08-01 15:22:42 -0600 | [diff] [blame] | 758 | Access to binman entry offsets at run time (symbols) |
| 759 | ---------------------------------------------------- |
Simon Glass | 39c1502 | 2017-11-13 18:55:05 -0700 | [diff] [blame] | 760 | |
| 761 | Binman assembles images and determines where each entry is placed in the image. |
| 762 | This information may be useful to U-Boot at run time. For example, in SPL it |
| 763 | is useful to be able to find the location of U-Boot so that it can be executed |
| 764 | when SPL is finished. |
| 765 | |
| 766 | Binman allows you to declare symbols in the SPL image which are filled in |
| 767 | with their correct values during the build. For example: |
| 768 | |
Simon Glass | 7c15013 | 2019-11-06 17:22:44 -0700 | [diff] [blame] | 769 | binman_sym_declare(ulong, u_boot_any, image_pos); |
Simon Glass | 39c1502 | 2017-11-13 18:55:05 -0700 | [diff] [blame] | 770 | |
Simon Glass | 7c15013 | 2019-11-06 17:22:44 -0700 | [diff] [blame] | 771 | declares a ulong value which will be assigned to the image-pos of any U-Boot |
Simon Glass | 39c1502 | 2017-11-13 18:55:05 -0700 | [diff] [blame] | 772 | image (u-boot.bin, u-boot.img, u-boot-nodtb.bin) that is present in the image. |
| 773 | You can access this value with something like: |
| 774 | |
Simon Glass | 7c15013 | 2019-11-06 17:22:44 -0700 | [diff] [blame] | 775 | ulong u_boot_offset = binman_sym(ulong, u_boot_any, image_pos); |
Simon Glass | 39c1502 | 2017-11-13 18:55:05 -0700 | [diff] [blame] | 776 | |
Simon Glass | 7c15013 | 2019-11-06 17:22:44 -0700 | [diff] [blame] | 777 | Thus u_boot_offset will be set to the image-pos of U-Boot in memory, assuming |
| 778 | that the whole image has been loaded, or is available in flash. You can then |
| 779 | jump to that address to start U-Boot. |
Simon Glass | 39c1502 | 2017-11-13 18:55:05 -0700 | [diff] [blame] | 780 | |
Simon Glass | 7c15013 | 2019-11-06 17:22:44 -0700 | [diff] [blame] | 781 | At present this feature is only supported in SPL and TPL. In principle it is |
| 782 | possible to fill in such symbols in U-Boot proper, as well, but a future C |
| 783 | library is planned for this instead, to read from the device tree. |
| 784 | |
| 785 | As well as image-pos, it is possible to read the size of an entry and its |
| 786 | offset (which is the start position of the entry within its parent). |
| 787 | |
| 788 | A small technical note: Binman automatically adds the base address of the image |
| 789 | (i.e. __image_copy_start) to the value of the image-pos symbol, so that when the |
| 790 | image is loaded to its linked address, the value will be correct and actually |
| 791 | point into the image. |
| 792 | |
| 793 | For example, say SPL is at the start of the image and linked to start at address |
| 794 | 80108000. If U-Boot's image-pos is 0x8000 then binman will write an image-pos |
| 795 | for U-Boot of 80110000 into the SPL binary, since it assumes the image is loaded |
| 796 | to 80108000, with SPL at 80108000 and U-Boot at 80110000. |
| 797 | |
| 798 | For x86 devices (with the end-at-4gb property) this base address is not added |
| 799 | since it is assumed that images are XIP and the offsets already include the |
| 800 | address. |
Simon Glass | 39c1502 | 2017-11-13 18:55:05 -0700 | [diff] [blame] | 801 | |
| 802 | |
Simon Glass | dbf6be9 | 2018-08-01 15:22:42 -0600 | [diff] [blame] | 803 | Access to binman entry offsets at run time (fdt) |
| 804 | ------------------------------------------------ |
| 805 | |
| 806 | Binman can update the U-Boot FDT to include the final position and size of |
| 807 | each entry in the images it processes. The option to enable this is -u and it |
| 808 | causes binman to make sure that the 'offset', 'image-pos' and 'size' properties |
| 809 | are set correctly for every entry. Since it is not necessary to specify these in |
| 810 | the image definition, binman calculates the final values and writes these to |
| 811 | the device tree. These can be used by U-Boot at run-time to find the location |
| 812 | of each entry. |
| 813 | |
Simon Glass | 086cec9 | 2019-07-08 14:25:27 -0600 | [diff] [blame] | 814 | Alternatively, an FDT map entry can be used to add a special FDT containing |
| 815 | just the information about the image. This is preceded by a magic string so can |
Simon Glass | cf22894 | 2019-07-08 14:25:28 -0600 | [diff] [blame] | 816 | be located anywhere in the image. An image header (typically at the start or end |
| 817 | of the image) can be used to point to the FDT map. See fdtmap and image-header |
| 818 | entries for more information. |
Simon Glass | 086cec9 | 2019-07-08 14:25:27 -0600 | [diff] [blame] | 819 | |
Simon Glass | dbf6be9 | 2018-08-01 15:22:42 -0600 | [diff] [blame] | 820 | |
Simon Glass | 83d73c2 | 2018-09-14 04:57:26 -0600 | [diff] [blame] | 821 | Compression |
| 822 | ----------- |
| 823 | |
| 824 | Binman support compression for 'blob' entries (those of type 'blob' and |
Simon Glass | 8287ee8 | 2019-07-08 14:25:30 -0600 | [diff] [blame] | 825 | derivatives). To enable this for an entry, add a 'compress' property: |
Simon Glass | 83d73c2 | 2018-09-14 04:57:26 -0600 | [diff] [blame] | 826 | |
| 827 | blob { |
| 828 | filename = "datafile"; |
Simon Glass | 8287ee8 | 2019-07-08 14:25:30 -0600 | [diff] [blame] | 829 | compress = "lz4"; |
Simon Glass | 83d73c2 | 2018-09-14 04:57:26 -0600 | [diff] [blame] | 830 | }; |
| 831 | |
| 832 | The entry will then contain the compressed data, using the 'lz4' compression |
Simon Glass | 8287ee8 | 2019-07-08 14:25:30 -0600 | [diff] [blame] | 833 | algorithm. Currently this is the only one that is supported. The uncompressed |
| 834 | size is written to the node in an 'uncomp-size' property, if -u is used. |
Simon Glass | 83d73c2 | 2018-09-14 04:57:26 -0600 | [diff] [blame] | 835 | |
| 836 | |
| 837 | |
Simon Glass | 3b0c382 | 2018-06-01 09:38:20 -0600 | [diff] [blame] | 838 | Map files |
| 839 | --------- |
| 840 | |
| 841 | The -m option causes binman to output a .map file for each image that it |
Simon Glass | 3ab9598 | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 842 | generates. This shows the offset and size of each entry. For example: |
Simon Glass | 3b0c382 | 2018-06-01 09:38:20 -0600 | [diff] [blame] | 843 | |
Simon Glass | 3ab9598 | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 844 | Offset Size Name |
Simon Glass | 8122f39 | 2018-07-17 13:25:28 -0600 | [diff] [blame] | 845 | 00000000 00000028 main-section |
| 846 | 00000000 00000010 section@0 |
| 847 | 00000000 00000004 u-boot |
| 848 | 00000010 00000010 section@1 |
| 849 | 00000000 00000004 u-boot |
Simon Glass | 3b0c382 | 2018-06-01 09:38:20 -0600 | [diff] [blame] | 850 | |
| 851 | This shows a hierarchical image with two sections, each with a single entry. The |
Simon Glass | 3ab9598 | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 852 | offsets of the sections are absolute hex byte offsets within the image. The |
| 853 | offsets of the entries are relative to their respective sections. The size of |
Simon Glass | 3b0c382 | 2018-06-01 09:38:20 -0600 | [diff] [blame] | 854 | each entry is also shown, in bytes (hex). The indentation shows the entries |
| 855 | nested inside their sections. |
| 856 | |
| 857 | |
Simon Glass | 53af22a | 2018-07-17 13:25:32 -0600 | [diff] [blame] | 858 | Passing command-line arguments to entries |
| 859 | ----------------------------------------- |
| 860 | |
| 861 | Sometimes it is useful to pass binman the value of an entry property from the |
| 862 | command line. For example some entries need access to files and it is not |
| 863 | always convenient to put these filenames in the image definition (device tree). |
| 864 | |
| 865 | The-a option supports this: |
| 866 | |
| 867 | -a<prop>=<value> |
| 868 | |
| 869 | where |
| 870 | |
| 871 | <prop> is the property to set |
| 872 | <value> is the value to set it to |
| 873 | |
| 874 | Not all properties can be provided this way. Only some entries support it, |
| 875 | typically for filenames. |
| 876 | |
| 877 | |
Simon Glass | c7d8035 | 2019-07-08 13:18:28 -0600 | [diff] [blame] | 878 | External tools |
| 879 | -------------- |
| 880 | |
| 881 | Binman can make use of external command-line tools to handle processing of |
| 882 | entry contents or to generate entry contents. These tools are executed using |
| 883 | the 'tools' module's Run() method. The tools generally must exist on the PATH, |
| 884 | but the --toolpath option can be used to specify additional search paths to |
| 885 | use. This option can be specified multiple times to add more than one path. |
| 886 | |
| 887 | |
Simon Glass | 6d427c6 | 2016-11-25 20:15:59 -0700 | [diff] [blame] | 888 | Code coverage |
| 889 | ------------- |
| 890 | |
| 891 | Binman is a critical tool and is designed to be very testable. Entry |
Simon Glass | 53cd5d9 | 2019-07-08 14:25:29 -0600 | [diff] [blame] | 892 | implementations target 100% test coverage. Run 'binman test -T' to check this. |
Simon Glass | 6d427c6 | 2016-11-25 20:15:59 -0700 | [diff] [blame] | 893 | |
| 894 | To enable Python test coverage on Debian-type distributions (e.g. Ubuntu): |
| 895 | |
Simon Glass | 45f449b | 2019-07-08 13:18:26 -0600 | [diff] [blame] | 896 | $ sudo apt-get install python-coverage python3-coverage python-pytest |
Simon Glass | 6d427c6 | 2016-11-25 20:15:59 -0700 | [diff] [blame] | 897 | |
| 898 | |
Simon Glass | 55660d0 | 2019-05-17 22:00:52 -0600 | [diff] [blame] | 899 | Concurrent tests |
| 900 | ---------------- |
| 901 | |
| 902 | Binman tries to run tests concurrently. This means that the tests make use of |
| 903 | all available CPUs to run. |
| 904 | |
| 905 | To enable this: |
| 906 | |
| 907 | $ sudo apt-get install python-subunit python3-subunit |
| 908 | |
| 909 | Use '-P 1' to disable this. It is automatically disabled when code coverage is |
| 910 | being used (-T) since they are incompatible. |
| 911 | |
| 912 | |
Simon Glass | d5164a7 | 2019-07-08 13:18:49 -0600 | [diff] [blame] | 913 | Debugging tests |
| 914 | --------------- |
| 915 | |
| 916 | Sometimes when debugging tests it is useful to keep the input and output |
| 917 | directories so they can be examined later. Use -X or --test-preserve-dirs for |
| 918 | this. |
| 919 | |
| 920 | |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 921 | Advanced Features / Technical docs |
| 922 | ---------------------------------- |
| 923 | |
| 924 | The behaviour of entries is defined by the Entry class. All other entries are |
| 925 | a subclass of this. An important subclass is Entry_blob which takes binary |
| 926 | data from a file and places it in the entry. In fact most entry types are |
| 927 | subclasses of Entry_blob. |
| 928 | |
| 929 | Each entry type is a separate file in the tools/binman/etype directory. Each |
| 930 | file contains a class called Entry_<type> where <type> is the entry type. |
| 931 | New entry types can be supported by adding new files in that directory. |
| 932 | These will automatically be detected by binman when needed. |
| 933 | |
| 934 | Entry properties are documented in entry.py. The entry subclasses are free |
| 935 | to change the values of properties to support special behaviour. For example, |
| 936 | when Entry_blob loads a file, it sets content_size to the size of the file. |
| 937 | Entry classes can adjust other entries. For example, an entry that knows |
Simon Glass | 3ab9598 | 2018-08-01 15:22:37 -0600 | [diff] [blame] | 938 | where other entries should be positioned can set up those entries' offsets |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 939 | so they don't need to be set in the binman decription. It can also adjust |
| 940 | entry contents. |
| 941 | |
| 942 | Most of the time such essoteric behaviour is not needed, but it can be |
| 943 | essential for complex images. |
| 944 | |
Simon Glass | 3ed0de3 | 2017-12-24 12:12:07 -0700 | [diff] [blame] | 945 | If you need to specify a particular device-tree compiler to use, you can define |
| 946 | the DTC environment variable. This can be useful when the system dtc is too |
| 947 | old. |
| 948 | |
Simon Glass | a3c0055 | 2018-11-06 15:21:31 -0700 | [diff] [blame] | 949 | To enable a full backtrace and other debugging features in binman, pass |
| 950 | BINMAN_DEBUG=1 to your build: |
| 951 | |
Bin Meng | c443f56 | 2019-10-02 19:07:29 -0700 | [diff] [blame] | 952 | make qemu-x86_defconfig |
Simon Glass | a3c0055 | 2018-11-06 15:21:31 -0700 | [diff] [blame] | 953 | make BINMAN_DEBUG=1 |
| 954 | |
Simon Glass | 1f338e0 | 2019-09-25 08:11:11 -0600 | [diff] [blame] | 955 | To enable verbose logging from binman, base BINMAN_VERBOSE to your build, which |
| 956 | adds a -v<level> option to the call to binman: |
| 957 | |
Bin Meng | c443f56 | 2019-10-02 19:07:29 -0700 | [diff] [blame] | 958 | make qemu-x86_defconfig |
Simon Glass | 1f338e0 | 2019-09-25 08:11:11 -0600 | [diff] [blame] | 959 | make BINMAN_VERBOSE=5 |
| 960 | |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 961 | |
| 962 | History / Credits |
| 963 | ----------------- |
| 964 | |
| 965 | Binman takes a lot of inspiration from a Chrome OS tool called |
| 966 | 'cros_bundle_firmware', which I wrote some years ago. That tool was based on |
| 967 | a reasonably simple and sound design but has expanded greatly over the |
| 968 | years. In particular its handling of x86 images is convoluted. |
| 969 | |
Simon Glass | 7ae5f31 | 2018-06-01 09:38:19 -0600 | [diff] [blame] | 970 | Quite a few lessons have been learned which are hopefully applied here. |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 971 | |
| 972 | |
| 973 | Design notes |
| 974 | ------------ |
| 975 | |
| 976 | On the face of it, a tool to create firmware images should be fairly simple: |
| 977 | just find all the input binaries and place them at the right place in the |
| 978 | image. The difficulty comes from the wide variety of input types (simple |
| 979 | flat binaries containing code, packaged data with various headers), packing |
| 980 | requirments (alignment, spacing, device boundaries) and other required |
| 981 | features such as hierarchical images. |
| 982 | |
| 983 | The design challenge is to make it easy to create simple images, while |
| 984 | allowing the more complex cases to be supported. For example, for most |
| 985 | images we don't much care exactly where each binary ends up, so we should |
| 986 | not have to specify that unnecessarily. |
| 987 | |
| 988 | New entry types should aim to provide simple usage where possible. If new |
| 989 | core features are needed, they can be added in the Entry base class. |
| 990 | |
| 991 | |
| 992 | To do |
| 993 | ----- |
| 994 | |
| 995 | Some ideas: |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 996 | - Use of-platdata to make the information available to code that is unable |
| 997 | to use device tree (such as a very small SPL image) |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 998 | - Allow easy building of images by specifying just the board name |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 999 | - Support building an image for a board (-b) more completely, with a |
| 1000 | configurable build directory |
Simon Glass | 488b225 | 2019-07-08 14:25:24 -0600 | [diff] [blame] | 1001 | - Support adding FITs to an image |
| 1002 | - Support for ARM Trusted Firmware (ATF) |
Simon Glass | 513c53e | 2019-07-20 12:24:02 -0600 | [diff] [blame] | 1003 | - Detect invalid properties in nodes |
| 1004 | - Sort the fdtmap by offset |
Simon Glass | bf7fd50 | 2016-11-25 20:15:51 -0700 | [diff] [blame] | 1005 | |
| 1006 | -- |
| 1007 | Simon Glass <sjg@chromium.org> |
| 1008 | 7/7/2016 |