Am 19. November 2024 23:28:35 MEZ schrieb Lothar Rubusch <[email protected]>: >Fix some typos and duplicate words in binman.rst. > >Signed-off-by: Lothar Rubusch <[email protected]> >--- > tools/binman/binman.rst | 238 ++++++++++++++++++++-------------------- > 1 file changed, 119 insertions(+), 119 deletions(-) > >diff --git a/tools/binman/binman.rst b/tools/binman/binman.rst >index 381e55686f..620b5fa048 100644 >--- a/tools/binman/binman.rst >+++ b/tools/binman/binman.rst >@@ -5,7 +5,7 @@ Introduction > ============ > > Firmware often consists of several components which must be packaged together. >-For example, we may have SPL, U-Boot, a device tree and an environment area >+For example, we may have SPL, U-Boot, a device-tree and an environment area
Both devicetree and device tree are common spelling variants. See for instance https://www.devicetree.org/. > grouped together and placed in MMC flash. When the system starts, it must be > able to find these pieces. > >@@ -19,7 +19,7 @@ together. > What it does > ------------ > >-Binman reads your board's device tree and finds a node which describes the >+Binman reads your board's device-tree and finds a node which describes the > required image layout. It uses this to work out what to place where. > > Binman provides a mechanism for building images, from simple SPL + U-Boot >@@ -31,13 +31,13 @@ needed. > Features > -------- > >-Apart from basic padding, alignment and positioning features, Binman supports >+Apart from basic padding, alignment, and positioning features, Binman supports > hierarchical images, compression, hashing and dealing with the binary blobs >-which are a sad trend in open-source firmware at present. >+which is a sad trend in open-source firmware at present. It is not Binmans support (singular) that is a sad trend. It is binary blobs (plural) that are a sad trend. Best regards Heinrich > > Executable binaries can access the location of other binaries in an image by >-using special linker symbols (zero-overhead but somewhat limited) or by >reading >-the devicetree description of the image. >+using special linker symbols (zero-overhead but limited) or by reading >+the device-tree description of the image. > > Binman is designed primarily for use with U-Boot and associated binaries such > as ARM Trusted Firmware, but it is suitable for use with other projects, such >@@ -55,14 +55,14 @@ Motivation > ---------- > > As mentioned above, packaging of firmware is quite a different task from >-building the various parts. In many cases the various binaries which go into >-the image come from separate build systems. For example, ARM Trusted Firmware >+building the various parts. In many cases the various binaries which go into >image >+come from separate build systems. For example, ARM Trusted Firmware > is used on ARMv8 devices but is not built in the U-Boot tree. If a Linux > kernel > is included in the firmware image, it is built elsewhere. > >-It is of course possible to add more and more build rules to the U-Boot >+It is of course possible to add further build rules to the U-Boot > build system to cover these cases. It can shell out to other Makefiles and >-build scripts. But it seems better to create a clear divide between building >+build scripts. But it seems preferable to create a clear divide between >building > software and packaging it. > > At present this is handled by manual instructions, different for each board, >@@ -82,7 +82,7 @@ Benefits: > - Avoids cluttering the U-Boot build system with image-building code > - The image description is automatically available at run-time in U-Boot, > SPL. It can be made available to other software also >- - The image description is easily readable (it's a text file in device-tree >+ - The image description is easily readable (a text file in device-tree > format) and permits flexible packing of binaries > > >@@ -102,7 +102,7 @@ You can install binman using:: > > pip install binary-manager > >-The name is chosen since binman conflicts with an existing package. >+The name was chosen since binman conflicts with an existing package. > > If you are using binman within the U-Boot tree, it may be easiest to add a > symlink from your local `~/.bin` directory to `/path/to/tools/binman/binman`. >@@ -116,9 +116,9 @@ load / execution addresses, compression. It also supports >verification > through hashing and RSA signatures. > > FIT was originally designed to support booting a Linux kernel (with an >-optional ramdisk) and device tree chosen from various options in the FIT. >-Now that U-Boot supports configuration via device tree, it is possible to >-load U-Boot from a FIT, with the device tree chosen by SPL. >+optional ramdisk) and device-tree chosen from assorted options in the FIT. >+Now that U-Boot supports configuration via device-tree, it is possible to >+load U-Boot from a FIT, with the device-tree chosen by SPL. > > Binman considers FIT to be one of the binaries it can place in the image. > >@@ -140,7 +140,7 @@ Relationship to mkimage > ----------------------- > > The mkimage tool provides a means to create a FIT. Traditionally it has >-needed an image description file: a device tree, like binman, but in a >+needed an image description file: a device-tree, like binman, but in a > different format. More recently it has started to support a '-f auto' mode > which can generate that automatically. > >@@ -173,7 +173,7 @@ build system. > Consider sunxi. It has the following steps: > > #. It uses a custom mksunxiboot tool to build an SPL image called >- sunxi-spl.bin. This should probably move into mkimage. >+ sunxi-spl.bin. This should better go into mkimage. > > #. It uses mkimage to package U-Boot into a legacy image file (so that it > can > hold the load and execution address) called u-boot.img. >@@ -193,7 +193,7 @@ can be replaced by a call to binman. > Invoking binman within U-Boot > ----------------------------- > >-Within U-Boot, binman is invoked by the build system, i.e. when you type >'make' >+Within U-Boot, binman is invoked by the build system, i.e., when you type >'make' > or use buildman to build U-Boot. There is no need to run binman independently > during development. Everything happens automatically and is set up for your > SoC or board so that binman produced the right things. >@@ -208,10 +208,10 @@ invocations as well, but these should be dropped when >those architectures are > converted to use binman properly. > > As above, the term 'binary' is used for something in INPUTS-y and 'image' is >-used for the things that binman creates. So the binaries are inputs to the >-image(s) and it is the image that is actually loaded on the board. >+used for the things that binman creates. Hence, the binaries are inputs to the >+ image(s), and it is the image that is actually loaded on the board. > >-Again, at present, there are a number of things created in Makefile which >should >+Again, at present, there are a few things created in Makefile which should > be done by binman (when we get around to it), like `u-boot-ivt.img`, > `lpc32xx-spl.img`, `u-boot-with-nand-spl.imx`, `u-boot-spl-padx4.sfp` and > `u-boot-mtk.bin`, just to pick on a few. When completed this will remove about >@@ -222,15 +222,15 @@ are needed, in that one invocation. It does this by >working through the image > descriptions one by one, collecting the input binaries, processing them as > needed and producing the final images. > >-The same binaries may be used by multiple images. For example binman may be >used >+The same binaries may be used for multiple images. For example, binman may be >used > to produce an SD-card image and a SPI-flash image. In this case the binaries > going into the process are the same, but binman produces slightly different > images in each case. > > For some SoCs, U-Boot is not the only project that produces the necessary > binaries. For example, ARM Trusted Firmware (ATF) is a project that produces >-binaries which must be incorporate, such as `bl31.elf` or `bl31.bin`. For this >-to work you must have built ATF before you build U-Boot and you must tell >U-Boot >+binaries which must be incorporated, such as `bl31.elf` or `bl31.bin`. For >this >+to work you must have built ATF before you build U-Boot, and you must tell >U-Boot > where to find the bl31 image, using the BL31 environment variable. > > How do you know how to incorporate ATF? It is handled by the atf-bl31 entry > type >@@ -267,29 +267,29 @@ nor is there any need to provide a real ATF BL31 binary >(for example). These can > be added later by invoking binman again, providing all the required inputs > from the first time, plus any that were missing or placeholders. > >-So in practice binman is often used twice: >+Then, in practice binman is often used twice: > >-- once within the U-Boot build system, for development and testing >-- again outside U-Boot to assembly and final production images >+- Once within the U-Boot build system, for development and testing >+- Again, outside U-Boot to assembly and final production images > > While the same input binaries are used in each case, you will of course you > will >-need to create your own binman command line, similar to that in `cmd_binman` >in >+need to create your own binman command line, like that in `cmd_binman` in > the Makefile. You may find the -I and --toolpath options useful. The >-device tree file is provided to binman in binary form, so there is no need to >+Device-tree file is provided to binman in binary form, so there is no need to > have access to the original `.dts` sources. > > > Assembling the image description > -------------------------------- > >-Since binman uses the device tree for its image description, you can use the >+Since binman uses the device-tree for its image description, you can use the > same files that describe your board's hardware to describe how the image is >-assembled. Typically the images description is in a common file used by all >+assembled. Typically, the images description is in a common file used by all > boards with a particular SoC (e.g. `imx8mp-u-boot.dtsi`). > >-Where a particular boards needs to make changes, it can override properties in >-the SoC file, just as it would for any other device tree property. It can also >-add a image that is specific to the board. >+Where a particular board needs to make changes, it can override properties in >+the SoC file, just as it would for any other device-tree property. It can also >+add an image that is specific to the board. > > Another way to control the image description to make use of CONFIG options in > the description. For example, if the start offset of a particular entry varies >@@ -303,7 +303,7 @@ by board, you can add a Kconfig for that and reference it >in the description:: > ... > }; > >-The SoC can provide a default value but boards can override that as needed and >+The SoC can provide a default value, but boards can override that as needed >and > binman will take care of it. > > It is even possible to control which entries appear in the image, by using the >@@ -317,15 +317,15 @@ C preprocessor:: > > Only boards which enable `HAVE_MRC` will include this entry. > >-Obviously a similar approach can be used to control which images are produced, >-with a Kconfig option to enable a SPI image, for example. However there is >-generally no harm in producing an image that is not used. If a board uses MMC >+Obviously, a similar approach can be used to control which images are >produced, >+with a Kconfig option to enable a SPI image, for example. However, there is >+no general harm in producing an image that is not used. If a board uses MMC > but not SPI, but the SoC supports booting from both, then both images can be >-produced, with only on or other being used by particular boards. This can help >-reduce the need for having multiple defconfig targets for a board where the >+produced, with only one or other being used by a particular board. This can >help >+reduce the need for having multiple defconfig targets, for boards where the > only difference is the boot media, enabling / disabling secure boot, etc. > >-Of course you can use the device tree itself to pass any board-specific >+Of course, you can use the device-tree itself to pass any board-specific > information that is needed by U-Boot at runtime (see binman_syms_ for how to > make binman insert these values directly into executables like SPL). > >@@ -341,14 +341,14 @@ Producing images for multiple boards > When invoked within U-Boot, binman only builds a single set of images, for > the chosen board. This is set by the `CONFIG_DEFAULT_DEVICE_TREE` option. > >-However, U-Boot generally builds all the device tree files associated with an >-SoC. These are written to the (e.g. for ARM) `arch/arm/dts` directory. Each of >+However, U-Boot builds all the device-tree files associated with an >+SoC. These are written in the (e.g. for ARM) `arch/arm/dts` directory. Each of > these contains the full binman description for that board. Often the best >-approach is to build a single image that includes all these device tree >binaries >+approach is to build a single image that includes all these device-tree >binaries > and allow SPL to select the correct one on boot. > > However, it is also possible to build separate images for each board, simply > by >-invoking binman multiple times, once for each device tree file, using a >+invoking binman multiple times, once for each device-tree file, using a > different output directory. This will produce one set of images for each > board. > > >@@ -429,7 +429,7 @@ build. > > (Future work will make this more configurable) > >-In either case, binman picks up the device tree file (u-boot.dtb) and looks >+In either case, binman picks up the device-tree file (u-boot.dtb) and looks > for its instructions in the 'binman' node. > > Binman has a few other options which you can see by running 'binman -h'. >@@ -441,7 +441,7 @@ Enabling binman for a board > At present binman is invoked from a rule in the main Makefile. You should be > able to enable CONFIG_BINMAN to enable this rule. > >-The output file is typically named image.bin and is located in the output >+The output file is typically named image.bin and is in the output > directory. If input files are needed to you add these to INPUTS-y either in > the > main Makefile or in a config.mk file in your arch subdirectory. > >@@ -476,19 +476,19 @@ You can access this value with something like: > ulong u_boot_offset = binman_sym(ulong, u_boot_any, image_pos); > > Thus u_boot_offset will be set to the image-pos of U-Boot in memory, assuming >-that the whole image has been loaded, or is available in flash. You can then >+that the whole image has been loaded or is available in flash. You can then > jump to that address to start U-Boot. > > At present this feature is only supported in SPL and TPL. In principle it is > possible to fill in such symbols in U-Boot proper, as well, but a future C >-library is planned for this instead, to read from the device tree. >+library is planned for this instead, to read from the device-tree. > > As well as image-pos, it is possible to read the size of an entry and its > offset (which is the start position of the entry within its parent). > > A small technical note: Binman automatically adds the base address of the > image > (i.e. __image_copy_start) to the value of the image-pos symbol, so that when > the >-image is loaded to its linked address, the value will be correct and actually >+image is loaded to its linked address; the value will be correct and actually > point into the image. > > For example, say SPL is at the start of the image and linked to start at > address >@@ -523,7 +523,7 @@ each entry in the images it processes. The option to >enable this is -u and it > causes binman to make sure that the 'offset', 'image-pos' and 'size' > properties > are set correctly for every entry. Since it is not necessary to specify these > in > the image definition, binman calculates the final values and writes these to >-the device tree. These can be used by U-Boot at run-time to find the location >+the device-tree. These can be used by U-Boot at run-time to find the location > of each entry. > > Alternatively, an FDT map entry can be used to add a special FDT containing >@@ -556,8 +556,8 @@ Passing command-line arguments to entries > ----------------------------------------- > > Sometimes it is useful to pass binman the value of an entry property from the >-command line. For example some entries need access to files and it is not >-always convenient to put these filenames in the image definition (device >tree). >+command line. For example, some entries need access to files, and it is not >+always convenient to put these filenames in the image definition >(device-tree). > > The -a option supports this:: > >@@ -594,7 +594,7 @@ This requests binman to create an image file called >u-boot-sunxi-with-spl.bin > consisting of a specially formatted SPL (spl/sunxi-spl.bin, built by the > normal U-Boot Makefile), some 0xff padding, and a U-Boot legacy image. The > padding comes from the fact that the second binary is placed at >-CONFIG_SPL_PAD_TO. If that line were omitted then the U-Boot binary would >+CONFIG_SPL_PAD_TO. If that line were omitted, then the U-Boot binary would > immediately follow the SPL binary. > > The binman node describes an image. The sub-nodes describe entries in the >@@ -606,7 +606,7 @@ Entries are normally placed into the image sequentially, >one after the other. > The image size is the total size of all entries. As you can see, you can > specify the start offset of an entry using the 'offset' property. > >-Note that due to a device tree requirement, all entries must have a unique >+Note that due to a device-tree requirement, all entries must have a unique > name. If you want to put the same binary in the image multiple times, you can > use any unique name, with the 'type' property providing the type. > >@@ -622,7 +622,7 @@ offset: > align: > This sets the alignment of the entry. The entry offset is adjusted > so that the entry starts on an aligned boundary within the containing >- section or image. For example 'align = <16>' means that the entry will >+ section or image. For example, 'align = <16>' means that the entry will > start on a 16-byte boundary. This may mean that padding is added before > the entry. The padding is part of the containing section but is not > included in the entry, meaning that an empty space may be created before >@@ -639,7 +639,7 @@ min-size: > ('pad-before' and 'pad-after'), but not padding added to meet alignment > requirements. While this does not affect the contents of the entry within > binman itself (the padding is performed only when its parent section is >- assembled), the end result will be that the entry ends with the padding >+ assembled), the result will be that the entry ends with the padding > bytes, so may grow. Defaults to 0. > > pad-before: >@@ -647,8 +647,8 @@ pad-before: > that the contents start at the beginning of the entry. This can be used > to offset the entry contents a little. While this does not affect the > contents of the entry within binman itself (the padding is performed >- only when its parent section is assembled), the end result will be that >- the entry starts with the padding bytes, so may grow. Defaults to 0. >+ only when its parent section is assembled), the result will be that >+ the entry starts with the padding bytes, so it may grow. Defaults to 0. > > pad-after: > Padding after the contents of the entry. Normally this is 0, meaning >@@ -656,7 +656,7 @@ pad-after: > other properties). This allows room to be created in the image for > this entry to expand later. While this does not affect the contents of > the entry within binman itself (the padding is performed only when its >- parent section is assembled), the end result will be that the entry ends >+ parent section is assembled), the result will be that the entry ends > with the padding bytes, so may grow. Defaults to 0. > > align-size: >@@ -664,7 +664,7 @@ align-size: > that the size of an entry is a multiple of 64 bytes, set this to 64. > While this does not affect the contents of the entry within binman > itself (the padding is performed only when its parent section is >- assembled), the end result is that the entry ends with the padding >+ assembled), the result is that the entry ends with the padding > bytes, so may grow. If 'align-size' is not provided, no alignment is > performed. > >@@ -675,7 +675,7 @@ align-end: > of the entry, so the contents of the entry will still start at the > beginning. But there may be padding at the end. While this does not > affect the contents of the entry within binman itself (the padding is >- performed only when its parent section is assembled), the end result >+ performed only when its parent section is assembled), the result > is that the entry ends with the padding bytes, so may grow. > If 'align-end' is not provided, no alignment is performed. > >@@ -708,7 +708,7 @@ extend-size: > entry. > > compress: >- Sets the compression algortihm to use (for blobs only). See the entry >+ Sets the compression algorithm to use (for blobs only). See the entry > documentation for details. > > missing-msg: >@@ -725,23 +725,23 @@ assume-size: > size if requested. > > no-expanded: >- By default binman substitutes entries with expanded versions if available, >+ By default, binman substitutes entries with expanded versions if >available, > so that a `u-boot` entry type turns into `u-boot-expanded`, for example. > The > `--no-expanded` command-line option disables this globally. The > `no-expanded` property disables this just for a single entry. Put the >- `no-expanded` boolean property in the node to select this behaviour. >+ `no-expanded` boolean property in the node to select this behavior. > > optional: > External blobs are normally required to be present for the image to be > built (but see `External blobs`_). This properly allows an entry to be >- optional, so that when it is cannot be found, this problem is ignored and >+ optional, so that when it cannot be found, this problem is ignored and > an empty file is used for this blob. This should be used only when the > blob > is entirely optional and is not needed for correct operation of the image. > Note that missing, optional blobs do not produce a non-zero exit code from > binman, although it does show a warning about the missing external blob. > > insert-template: >- This is not strictly speaking an entry property, since it is processed >early >+ This is not an entry property, since it is processed early > in Binman before the entries are read. It is a list of phandles of nodes > to > include in the current (target) node. For each node, its subnodes and > their > properties are brought into the target node. See Templates_ below for >@@ -751,7 +751,7 @@ symbols-base: > When writing symbols into a binary, the value of that symbol is assumed to > be relative to the base address of the binary. This allow the binary to be > loaded in memory at its base address, so that symbols point into the > binary >- correctly. In some cases the binary is in fact not yet in memory, but must >+ correctly. In some cases, the binary is in fact not yet in memory, but >must > be read from storage. In this case there is no base address for the > symbols. > This property can be set to 0 to indicate this. Other values for > symbols-base are allowed, but care must be taken that the code which uses >@@ -759,14 +759,14 @@ symbols-base: > address is used. > > The attributes supported for images and sections are described below. Several >-are similar to those for entries. >+of them are like the attributes for entries. > > size: > Sets the image size in bytes, for example 'size = <0x100000>' for a > 1MB image. > > offset: >- This is similar to 'offset' in entries, setting the offset of a section >+ This is like 'offset' in entries, setting the offset of a section > within the image or section containing it. The first byte of the section > is normally at offset 0. If 'offset' is not provided, binman sets it to > the end of the previous region, or the start of the image's entry area >@@ -799,7 +799,7 @@ sort-by-offset: > the 'offset' properties are set by CONFIG options, so their ordering is > not known a priori. > >- This is a boolean property so needs no value. To enable it, add a >+ This is a boolean property, so it needs no value. To enable it, add a > line 'sort-by-offset;' to your description. > > multiple-images: >@@ -842,7 +842,7 @@ skip-at-start: > Image size != 4gb. > > align-default: >- Specifies the default alignment for entries in this section, if they do >+ Specifies the default alignment for entries in this section if they do > not specify an alignment. Note that this only applies to top-level entries > in the section (direct subentries), not any subentries of those entries. > This means that each section must specify its own default alignment, if >@@ -883,7 +883,7 @@ elf-base-sym: > be read correctly. See binman_syms_ for more information. > > offset-from-elf: >- Sets the offset of an entry based on a symbol value in an another entry. >+ Sets the offset of an entry based on a symbol value in another entry. > The format is <&phandle>, "sym_name", <offset> where phandle is the entry > containing the blob (with associated ELF file providing symbols), > <sym_name> > is the symbol to lookup (relative to elf-base-sym) and <offset> is an > offset >@@ -894,7 +894,7 @@ preserve: > flag should be checked by the updater when it is deciding which entries to > update. This flag is normally attached to sections but can be attached to > a single entry in a section if the updater supports it. Not that binman >- itself has no control over the updater's behaviour, so this is just a >+ itself has no control over the updater's behavior, so this is just a > signal. It is not enforced by binman. > > Examples of the above options can be found in the tests. See the >@@ -905,16 +905,16 @@ either by using a unit number suffix (u-boot@0, >u-boot@1) or by using a > different name for each and specifying the type with the 'type' attribute. > > >-Sections and hierachical images >+Sections and hierarchical images > ------------------------------- > > Sometimes it is convenient to split an image into several pieces, each of > which > contains its own set of binaries. An example is a flash device where part of >-the image is read-only and part is read-write. We can set up sections for each >+the image is read-only, and part is read-write. We can set up sections for >each > of these, and place binaries in them independently. The image is still > produced > as a single output file. > >-This feature provides a way of creating hierarchical images. For example here >+This feature provides a way of creating hierarchical images. For example, here > is an example image with two copies of U-Boot. One is read-only (ro), intended > to be written only in the factory. Another is read-write (rw), so that it can > be > upgraded in the field. The sizes are fixed so that the ro/rw boundary is known >@@ -947,7 +947,7 @@ read-only: > > name-prefix: > This string is prepended to all the names of the binaries in the >- section. In the example above, the 'u-boot' binaries which actually be >+ section. In the example above, the 'u-boot' binaries which be > renamed to 'ro-u-boot' and 'rw-u-boot'. This can be useful to > distinguish binaries with otherwise identical names. > >@@ -955,7 +955,7 @@ filename: > This allows the contents of the section to be written to a file in the > output directory. This can sometimes be useful to use the data in one > section in different image, since there is currently no way to share data >- beteen images other than through files. >+ between images other than through files. > > Image Properties > ---------------- >@@ -970,11 +970,11 @@ filename: > allow-repack: > Create an image that can be repacked. With this option it is possible > to change anything in the image after it is created, including updating >- the position and size of image components. By default this is not >- permitted since it is not possibly to know whether this might violate a >- constraint in the image description. For example, if a section has to >+ the position and size of image components. By default, this is not >+ permitted since it is not possible to know whether this might violate a >+ constraint in the image description. For example, if a section must > increase in size to hold a larger binary, that might cause the section >- to fall out of its allow region (e.g. read-only portion of flash). >+ to fall out of its allow-region (e.g. read-only portion of flash). > > Adding this property causes the original offset and size values in the > image description to be stored in the FDT and fdtmap. >@@ -985,7 +985,7 @@ Image dependencies > > Binman does not currently support images that depend on each other. For > example, > if one image creates `fred.bin` and then the next uses this `fred.bin` to >-produce a final `image.bin`, then the behaviour is undefined. It may work, or >it >+produce a final `image.bin`, then the behavior is undefined. It may work, or >it > may produce an error about `fred.bin` being missing, or it may use a version > of > `fred.bin` from a previous run. > >@@ -1045,10 +1045,10 @@ value back to the device-tree node. For example:: > > Here, a new 'value' property will be written to the 'hash' node containing > the hash of the 'u-boot' entry. Only SHA256 is supported at present. Whole >-sections can be hased if desired, by adding the 'hash' node to the section. >+sections can be hashed if desired, by adding the 'hash' node to the section. > >-The has value can be chcked at runtime by hashing the data actually read and >-comparing this has to the value in the device tree. >+The hash value can be checked at runtime by hashing the data read and >+comparing this hash to the value in the device-tree. > > > Expanded entries >@@ -1078,14 +1078,14 @@ which in turn expands to:: > }; > }; > >-U-Boot's various phase binaries actually comprise two or three pieces. >-For example, u-boot.bin has the executable followed by a devicetree. >+U-Boot's phase binaries comprise two or three pieces. For example, u-boot.bin >+has the executable followed by a device-tree. > >-With binman we want to be able to update that devicetree with full image >+With binman we want to be able to update that device-tree with full image > information so that it is accessible to the executable. This is tricky >-if it is not clear where the devicetree starts. >+if it is not clear where the device-tree starts. > >-The above feature ensures that the devicetree is clearly separated from the >+The above feature ensures that the device-tree is clearly separated from the > U-Boot executable and can be updated separately by binman as needed. It can be > disabled with the --no-expanded flag if required. > >@@ -1117,11 +1117,11 @@ which in turn expands to:: > }; > }; > >-Of course we should not expand SPL if it has no devicetree. Also if the BSS >+Of course, we should not expand SPL if it has no device-tree. Also, if the BSS > padding is not needed (because BSS is in RAM as with CONFIG_SPL_SEPARATE_BSS), >-the 'u-boot-spl-bss-pad' subnode should not be created. The use of the expaned >+the 'u-boot-spl-bss-pad' subnode should not be created. The use of the >expanded > entry type is controlled by the UseExpanded() method. In the SPL case it > checks >-the 'spl-dtb' entry arg, which is 'y' or '1' if SPL has a devicetree. >+the 'spl-dtb' entry arg, which is 'y' or '1' if SPL has a device-tree. > > For the BSS case, a 'spl-bss-pad' entry arg controls whether it is present. > All > entry args are provided by the U-Boot Makefile. >@@ -1749,7 +1749,7 @@ Options: > Options used only for testing: > > --fake-dtb >- Use fake device tree contents >+ Use fake device-tree contents > > --fake-ext-blobs > Create fake ext blobs with dummy content >@@ -1789,7 +1789,7 @@ Positional arguments: > paths > Paths within file to list (wildcard) > >-Pptions: >+Options: > > -h, --help > show help message and exit >@@ -1899,7 +1899,7 @@ Options: > > -P PROCESSES, --processes PROCESSES > set number of processes to use for running tests. This defaults to the >- number of CPUs on the machine >+ numbering the CPUs on the machine > > -T, --test-coverage > run tests and check for 100% coverage >@@ -1974,13 +1974,13 @@ Image creation proceeds in the following order, for >each entry in the image. > 1. AddMissingProperties() - binman can add calculated values to the device > tree as part of its processing, for example the offset and size of each > entry. This method adds any properties associated with this, expanding the >-device tree as needed. These properties can have placeholder values which are >-set later by SetCalculatedProperties(). By that stage the size of sections >+device-tree as needed. These properties can have placeholder values which are >+set later by SetCalculatedProperties(). By that stage, the size of sections > cannot be changed (since it would cause the images to need to be repacked), > but the correct values can be inserted. > >-2. ProcessFdt() - process the device tree information as required by the >-particular entry. This may involve adding or deleting properties. If the >+2. ProcessFdt() - process the device-tree information as required by the >+entry. This may involve adding or deleting properties. If the > processing is complete, this method should return True. If the processing > cannot complete because it needs the ProcessFdt() method of another entry to > run first, this method should return False, in which case it will be called >@@ -1989,7 +1989,7 @@ again later. > 3. GetEntryContents() - the contents of each entry are obtained, normally by > reading from a file. This calls the Entry.ObtainContents() to read the > contents. The default version of Entry.ObtainContents() calls >-Entry.GetDefaultFilename() and then reads that file. So a common mechanism >+Entry.GetDefaultFilename() and then reads that file. Thus, a common mechanism > to select a file to read is to override that function in the subclass. The > functions must return True when they have read the contents. Binman will > retry calling the functions a few times if False is returned, allowing >@@ -2039,7 +2039,7 @@ what happens in this stage. > 11. BuildImage() - builds the image and writes it to a file > > 12. WriteMap() - writes a text file containing a map of the image. This is the >-final step. >+last step. > > > .. _`External tools`: >@@ -2049,14 +2049,14 @@ External tools > > Binman can make use of external command-line tools to handle processing of > entry contents or to generate entry contents. These tools are executed using >-the 'tools' module's Run() method. The tools generally must exist on the PATH, >+the 'tools' module's Run() method. The tools must exist on the PATH, > but the --toolpath option can be used to specify additional search paths to > use. This option can be specified multiple times to add more than one path. > >-For some compile tools binman will use the versions specified by commonly-used >+For some compile tools binman will use the versions specified by commonly used > environment variables like CC and HOSTCC for the C compiler, based on whether > the tool's output will be used for the target or for the host machine. If > those >-aren't given, it will also try to derive target-specific versions from the >+are not given, it will also try to derive target-specific versions from the > CROSS_COMPILE environment variable during a cross-compilation. > > If the tool is not available in the path you can use BINMAN_TOOLPATHS to > specify >@@ -2077,7 +2077,7 @@ to build the final image, no matter what steps are >needed to get there. > > Binman also provides a `blob-ext` entry type that pulls in a binary blob from > an > external file. If the file is missing, binman can optionally complete the > build >-and just report a warning. Use the `-M/--allow-missing` option to enble this. >+and just report a warning. Use the `-M/--allow-missing` option to enable this. > This is useful in CI systems which want to check that everything is correct > but > don't have access to the blobs. > >@@ -2172,7 +2172,7 @@ symbol tells binman the size of the BSS region, in >bytes. It needs this to be > able to pad the image so that the following entries do not overlap the BSS, > which would cause them to be overwritte by variable access in SPL. > >-This symbols is normally defined in the linker script, immediately after >+These symbols are normally defined in the linker script, immediately after > _bss_start and __bss_end are defined, like this:: > > __bss_size = __bss_end - __bss_start; >@@ -2186,7 +2186,7 @@ Concurrent tests > Binman tries to run tests concurrently. This means that the tests make use of > all available CPUs to run. > >- To enable this:: >+ Enable this:: > > $ sudo apt-get install python-subunit python3-subunit > >@@ -2202,7 +2202,7 @@ See :doc:`../binman_tests`. > Debugging tests > --------------- > >-Sometimes when debugging tests it is useful to keep the input and output >+Sometimes when debugging tests, it is useful to keep the input and output > directories so they can be examined later. Use -X or --test-preserve-dirs for > this. > >@@ -2363,10 +2363,10 @@ blob can come from any suitable place, such as an >`Entry_u_boot` or an > > The `soc-fw` node is a `blob-ext` (i.e. it reads in a named binary file) > whereas > `u-boot` is a normal entry type. This works because `Entry_fip` selects the >-`blob-ext` entry type if the node name (here `soc-fw`) is recognised as being >+`blob-ext` entry type if the node name (here `soc-fw`) is recognized as being > a known blob type. > >-When adding new entry types you are encouraged to use subnodes to provide the >+When adding new entry types, you are encouraged to use subnodes to provide the > data for processing, unless the `content` approach is more suitable. Consider > whether the input entries are contained within (or consumed by) the entry, vs > just being 'referenced' by the entry. In the latter case, the `content` > approach >@@ -2378,8 +2378,8 @@ History / Credits > > Binman takes a lot of inspiration from a Chrome OS tool called > 'cros_bundle_firmware', which I wrote some years ago. That tool was based on >-a reasonably simple and sound design but has expanded greatly over the >-years. In particular its handling of x86 images is convoluted. >+a simple and sound design but has expanded over the >+years. In particular, its handling of x86 images is convoluted. > > Quite a few lessons have been learned which are hopefully applied here. > >@@ -2387,11 +2387,11 @@ Quite a few lessons have been learned which are >hopefully applied here. > Design notes > ------------ > >-On the face of it, a tool to create firmware images should be fairly simple: >+On the face of it, a tool to create firmware images should be simple: > just find all the input binaries and place them at the right place in the > image. The difficulty comes from the wide variety of input types (simple > flat binaries containing code, packaged data with various headers), packing >-requirments (alignment, spacing, device boundaries) and other required >+requirements (alignment, spacing, device boundaries) and other required > features such as hierarchical images. > > The design challenge is to make it easy to create simple images, while >@@ -2409,7 +2409,7 @@ To do > Some ideas: > > - Use of-platdata to make the information available to code that is unable >- to use device tree (such as a very small SPL image). For now, limited info >is >+ to use device-tree (such as a small SPL image). For now, limited info is > available via linker symbols > - Allow easy building of images by specifying just the board name > - Support building an image for a board (-b) more completely, with a >@@ -2417,7 +2417,7 @@ Some ideas: > - Detect invalid properties in nodes > - Sort the fdtmap by offset > - Output temporary files to a different directory >-- Rationalise the fdt, fdt_util and pylibfdt modules which currently have some >+- Rationalize the fdt, fdt_util and pylibfdt modules which currently have some > overlapping and confusing functionality > - Update the fdt library to use a better format for Prop.value (the current > one > is useful for dtoc but not much else)
