[PATCH v2 1/2] doc: develop: Fix typos and wording in binman/binman.rst

[Heinrich Schuchardt]

On 11/20/24 19:57, Lothar Rubusch wrote:
> Fix some typos and duplicate words in binman.rst.
>
> Signed-off-by: Lothar Rubusch <l.rubusch at gmail.com>
> ---
>   tools/binman/binman.rst | 232 ++++++++++++++++++++--------------------
>   1 file changed, 116 insertions(+), 116 deletions(-)
>
> diff --git a/tools/binman/binman.rst b/tools/binman/binman.rst
> index 381e55686f..434006e932 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 devicetree and an environment area
>   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 devicetree 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,12 +31,12 @@ needed.
>   Features
>   --------
>
> -Apart from basic padding, alignment and positioning features, Binman supports
> -hierarchical images, compression, hashing and dealing with the binary blobs
> +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.
>
>   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
> +using special linker symbols (zero-overhead but limited) or by reading
>   the devicetree description of the image.
>
>   Binman is designed primarily for use with U-Boot and associated binaries 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 devicetree
>       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 devicetree chosen from assorted options in the FIT.
> +Now that U-Boot supports configuration via devicetree, it is possible to
> +load U-Boot from a FIT, with the devicetree 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 devicetree, 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.

This does not build. You can run 'make htmldocs' to check your submission.

doc/develop/package/binman.rst:212:Unexpected indentation.

>
> -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
> +devicetree 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 devicetree 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 devicetree 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 devicetree 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 devicetree 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 devicetree 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 devicetree 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 devicetree 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,11 +441,11 @@ 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.
>
> -Once binman is executed it will pick up its instructions from a device-tree
> +Once binman is executed it will pick up its instructions from a devicetree
>   file, typically <soc>-u-boot.dtsi, where <soc> is your CONFIG_SYS_SOC value.
>   You can use other, more specific CONFIG options - see 'Automatic .dtsi
>   inclusion' below.
> @@ -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 devicetree.
>
>   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 devicetree. 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 (devicetree).
>
>   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 devicetree 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 at 0, u-boot at 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

"which be renamed" in syntactically wrong.

How about "will be renamed"?



>       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).

If the size is increased and the start address stays the same, the
section cannot fall out of its allowed region.

%s/fall out of/exceed/

%s/read-only/the read-only/

Best regards

Heinrich

>
>       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.
>
> @@ -1033,7 +1033,7 @@ Hashing Entries
>   ---------------
>
>   It is possible to ask binman to hash the contents of an entry and write that
> -value back to the device-tree node. For example::
> +value back to the devicetree node. For example::
>
>       binman {
>           u-boot {
> @@ -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 devicetree.
>
>
>   Expanded entries
> @@ -1078,8 +1078,8 @@ 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 devicetree.
>
>   With binman we want to be able to update that devicetree with full image
>   information so that it is accessible to the executable. This is tricky
> @@ -1117,9 +1117,9 @@ 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 devicetree. 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.
>
> @@ -1749,7 +1749,7 @@ Options:
>   Options used only for testing:
>
>   --fake-dtb
> -    Use fake device tree contents
> +    Use fake devicetree 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
> +devicetree 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 devicetree 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.
>
> @@ -2249,7 +2249,7 @@ entry contents.
>   Most of the time such essoteric behaviour is not needed, but it can be
>   essential for complex images.
>
> -If you need to specify a particular device-tree compiler to use, you can define
> +If you need to specify a particular devicetree compiler to use, you can define
>   the DTC environment variable. This can be useful when the system dtc is too
>   old.
>
> @@ -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 devicetree (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