README 41 KB

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