Am 19. November 2024 23:28:35 MEZ schrieb Lothar Rubusch l.rubusch@gmail.com:

Fix some typos and duplicate words in binman.rst.

Signed-off-by: Lothar Rubusch l.rubusch@gmail.com

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)

Hi, thank you all! This is outstanding, such a fast feedback! As I also just ran a tool over the texts, adjusted formatting and reverted/accepted some changes manually to my knowledge (I'm not a native speaker).

On Tue, Nov 19, 2024 at 11:48 PM Heinrich Schuchardt xypron.glpk@gmx.de wrote:

Am 19. November 2024 23:28:36 MEZ schrieb Lothar Rubusch l.rubusch@gmail.com:

...

Fix some typos and duplicate words in gdb.rst.

[...]

...

CONFIG_CC_OPTIMIZE_FOR_DEBUG=y

@@ -24,8 +24,8 @@ Otherwise build, install, and run U-Boot as usual. Using OpenOCD as GDB server

---

-`OpenOCD https://openocd.org/`_ is an open source tool supporting hardware -debug probes, and providing a GDB server. It is readily available in major Linux +`OpenOCD https://openocd.org/`_ is an open-source tool supporting hardware +debug probes and provide a GDB server. It is readily available in major Linux

Thanks for the patch.

'tool' is singular. You cannot use 'provide' here.

Ok.

...

distributions or you can build it from source.

Here is example of starting OpenOCD on Debian using a J-Link adapter and a @@ -124,7 +124,7 @@ with the command *bdinfo*: Early malloc usage: cd8 / 2000

Look out for the line starting with *relocaddr* which has the address -you need, ``0x27f7a000`` in this case. +You need, ``0x27f7a000`` in this case.

You is only capitalized at the start of sentences.

Ok.

...

On most architectures (not sandbox, x86, Xtensa) the global data pointer is stored in a fixed register: @@ -144,7 +144,7 @@ riscv gp sh r13 ============ ========

-On these architecture the relocation address cat be determined by +On this architecture the relocation address can be determined by

On these architectures ...

Ok.

Hi, thank you all! This is outstanding, such a fast feedback! As I also just ran a tool over the texts, adjusted formatting and reverted/accepted some changes manually to my knowledge (I'm not a native speaker). Please, could you clarify the following?

On Wed, Nov 20, 2024 at 8:15 AM Alexander Dahl ada@thorsis.com wrote:

Hello Lothar,

Am Tue, Nov 19, 2024 at 10:28:36PM +0000 schrieb Lothar Rubusch:

...

Fix some typos and duplicate words in gdb.rst.

Signed-off-by: Lothar Rubusch l.rubusch@gmail.com

doc/develop/gdb.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/doc/develop/gdb.rst b/doc/develop/gdb.rst index 4e359c7f22..dc38435227 100644 --- a/doc/develop/gdb.rst +++ b/doc/develop/gdb.rst @@ -8,12 +8,12 @@ Using a JTAG adapter it is possible to debug a running U-Boot with GDB. A common way is to connect a debug adapter to the JTAG connector of your board, run a GDB server, connect GDB to the GDB server, and use GDB as usual.

-Similarly QEMU can provide a GDB server. +Similarly, QEMU can provide a GDB server.

Preparing build

-Building U-Boot with with reduced optimization (-Og) and without link time +Building U-Boot with reduced optimization (-Og) and without link time

ack

...

optimization is recommended for easier debugging::

 CONFIG_CC_OPTIMIZE_FOR_DEBUG=y

@@ -24,8 +24,8 @@ Otherwise build, install, and run U-Boot as usual. Using OpenOCD as GDB server

---

-`OpenOCD https://openocd.org/`_ is an open source tool supporting hardware -debug probes, and providing a GDB server. It is readily available in major Linux +`OpenOCD https://openocd.org/`_ is an open-source tool supporting hardware +debug probes and provide a GDB server. It is readily available in major Linux

NACK. It would read "OpenOCD is a tool supporting x and provide y" now. This is most probably wrong?

I'm not sure if I got the point. If you can't find the time to answer, I'll simply revert this entire change and leave it as is, no prob. So, change 1) is "open source" to "open-source"; change 2) is a removal of the comma; and change 3) "providing" -> "provide". Do I understand you correctly, change 1) could be ok, where change 2) is to be left as is, and also change 3) has to be as is?

...

distributions or you can build it from source.

Here is example of starting OpenOCD on Debian using a J-Link adapter and a @@ -124,7 +124,7 @@ with the command *bdinfo*: Early malloc usage: cd8 / 2000

Look out for the line starting with *relocaddr* which has the address -you need, ``0x27f7a000`` in this case. +You need, ``0x27f7a000`` in this case.

NACK. These are not two sentences but one, containing "the address you need". Splitting that makes no sense.

Agree. This was already meantioned.

On Wed, Nov 20, 2024 at 11:26 AM Alexander Dahl ada@thorsis.com wrote:

Hello Lothar,

Am Wed, Nov 20, 2024 at 11:11:23AM +0100 schrieb Lothar Rubusch:

...

Hi, thank you all! This is outstanding, such a fast feedback! As I also just ran a tool over the texts, adjusted formatting and reverted/accepted some changes manually to my knowledge (I'm not a native speaker). Please, could you clarify the following?

What about mentioning the tool in the commit message then?

...

On Wed, Nov 20, 2024 at 8:15 AM Alexander Dahl ada@thorsis.com wrote:

...

Hello Lothar,

Am Tue, Nov 19, 2024 at 10:28:36PM +0000 schrieb Lothar Rubusch:

...

Fix some typos and duplicate words in gdb.rst.

Signed-off-by: Lothar Rubusch l.rubusch@gmail.com

doc/develop/gdb.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/doc/develop/gdb.rst b/doc/develop/gdb.rst index 4e359c7f22..dc38435227 100644 --- a/doc/develop/gdb.rst +++ b/doc/develop/gdb.rst @@ -8,12 +8,12 @@ Using a JTAG adapter it is possible to debug a running U-Boot with GDB. A common way is to connect a debug adapter to the JTAG connector of your board, run a GDB server, connect GDB to the GDB server, and use GDB as usual.

-Similarly QEMU can provide a GDB server. +Similarly, QEMU can provide a GDB server.

Preparing build

-Building U-Boot with with reduced optimization (-Og) and without link time +Building U-Boot with reduced optimization (-Og) and without link time

ack

...

optimization is recommended for easier debugging::

 CONFIG_CC_OPTIMIZE_FOR_DEBUG=y

@@ -24,8 +24,8 @@ Otherwise build, install, and run U-Boot as usual. Using OpenOCD as GDB server

---

-`OpenOCD https://openocd.org/`_ is an open source tool supporting hardware -debug probes, and providing a GDB server. It is readily available in major Linux +`OpenOCD https://openocd.org/`_ is an open-source tool supporting hardware +debug probes and provide a GDB server. It is readily available in major Linux

NACK. It would read "OpenOCD is a tool supporting x and provide y" now. This is most probably wrong?

I'm not sure if I got the point. If you can't find the time to answer, I'll simply revert this entire change and leave it as is, no prob. So, change 1) is "open source" to "open-source"; change 2) is a removal of the comma; and change 3) "providing" -> "provide". Do I understand you correctly, change 1) could be ok, where change 2) is to be left as is, and also change 3) has to be as is?

I have no strong opinion on 1). I'm not sure about the comma in 2).

Let me explain 3) although I'm no native speaker as well.

You could split the previous sentence in two like this:

OpenOCD is an open source tool supporting hardware debug probes. OpenOCD is an open source tool providing a GDB server.

After your change the first part stays the same, the second part becomes:

OpenOCD is an open source tool provide a GDB server.

or

OpenOCD provide a GDB server.

It depends on how you interpret what parts the "and" connects (or which redundant part can be omitted), but both variants sound just wrong. So if you can not convince us this is a real style improvement in correct language, leave it as is.

Thank you so much. I understand. My question was actually just about confirmation, and more about keeping 1) or not. Since 2) and 3) are pretty clear. Sorry, I was not clear.

Personally I think automated tools can help detecting language issues, but the patch author should review changes carefully before sending them to other developers. ;-)

Agree.

Best, L

Am 19. November 2024 23:28:37 MEZ schrieb Lothar Rubusch l.rubusch@gmail.com:

Fix some typos and wording in binman/entries.rst.

Signed-off-by: Lothar Rubusch l.rubusch@gmail.com

tools/binman/entries.rst | 104 +++++++++++++++++++-------------------- 1 file changed, 52 insertions(+), 52 deletions(-)

diff --git a/tools/binman/entries.rst b/tools/binman/entries.rst index e918162fb4..abec03bb3c 100644 --- a/tools/binman/entries.rst +++ b/tools/binman/entries.rst @@ -7,18 +7,18 @@ fairly easy to create new entry types. Just add a new file to the 'etype' directory. You can use the existing entries as examples.

Note that some entries are subclasses of others, using and extending their -features to produce new behaviours. +features to produce new behaviors.

The project once used to prefer British English.

.. _etype_alternates_fdt:

-Entry: alternates-fdt: Entry that generates alternative sections for each devicetree provided +Entry: alternates-fdt: Entry that generates alternative sections for each device-tree provided

'Devicetree' is a frequently used spelling variant, cf. https://www.devicetree.org/ .

---

When creating an image designed to boot on multiple models, each model -requires its own devicetree. This entry deals with selecting the correct -devicetree from a directory containing them. Each one is read in turn, then +requires its own device-tree. This entry deals with selecting the correct +device-tree from a directory containing them. Each one is read in turn, then used to produce section contents which are written to a file. This results in a number of images, one for each model.

@@ -48,8 +48,8 @@ of each of the alternates is the same as the 'default' one, so they can in principle be 'slotted in' to the appropriate place in the main image.

The optional `fdt-phase` property indicates the phase to build. In this -case, it etype runs fdtgrep to obtain the devicetree subset for that phase, -respecting the `bootph-xxx` tags in the devicetree. +case, it etype runs fdtgrep to obtain the device-tree subset for that phase, +respecting the `bootph-xxx` tags in the device-tree.

@@ -214,7 +214,7 @@ icons, for example. For verified boot it could be used for each part of the image (e.g. separate FIPs for A and B) but cannot describe the whole firmware image. As with FMAP there is no hierarchy defined, although FMAP works around this by having 'section' areas which encompass others. A -similar workaround would be possible with FIP but is not currently defined. +similar workaround would be possible with FIP but it is not currently defined.

Both versions seem to be correct English.

Best regards

Heinrich

It is recommended to always add an fdtmap to every image, as well as any FIPs so that binman and other tools can access the entire image correctly. @@ -240,7 +240,7 @@ Properties / Entry arguments: lz4: Use lz4 compression (via 'lz4' command-line utility)

This entry reads data from a file and places it in the entry. The -default filename is often specified specified by the subclass. See for +default filename is often specified by the subclass. See for example the 'u-boot' entry which provides the filename 'u-boot.bin'.

If compression is enabled, an extra 'uncomp-size' property is written to @@ -283,10 +283,10 @@ See 'blob' for Properties / Entry arguments. Entry: blob-ext-list: List of externally built binary blobs

---

-This is like blob-ext except that a number of blobs can be provided, -typically with some sort of relationship, e.g. all are DDC parameters. +This is like blob-ext except that a few blobs can be provided, +typically, with some sort of relationship, e.g. all are DDC parameters.

-If any of the external files needed by this llist is missing, binman can +If any of the external files needed by this list is missing, binman can optionally ignore it and produce a broken image with a warning.

Args: @@ -335,7 +335,7 @@ structure and allows the position of individual files to be set, since it is designed to support execute-in-place in an x86 SPI-flash device. Where XIP is not used, it supports compression and storing ELF files.

-CBFS is used by coreboot as its way of orgnanising SPI-flash contents. +CBFS is used by coreboot as its way of organizing SPI-flash contents.

The contents of the CBFS are defined by subnodes of the cbfs entry, e.g.::

@@ -351,8 +351,8 @@ The contents of the CBFS are defined by subnodes of the cbfs entry, e.g.::

This creates a CBFS 1MB in size two files in it: u-boot.bin and u-boot.dtb. Note that the size is required since binman does not support calculating it. -The contents of each entry is just what binman would normally provide if it -were not a CBFS node. A blob type can be used to import arbitrary files as +The contents of each entry are just what binman would normally provide if it +was not a CBFS node. A blob type can be used to import arbitrary files as with the second subnode below::

cbfs {

@@ -431,7 +431,7 @@ cbfs-offset: specify where the file should be placed in cases where a fixed position is needed. Typical uses are for code which is not relocatable and must execute in-place from a particular address. This works because SPI flash

• is generally mapped into memory on x86 devices. The file header is

• is mapped into memory on x86 devices. The file header is placed before this offset so that the data start lines up exactly with the chosen offset. If this property is not provided, then the file is placed in the next available spot.

@@ -439,9 +439,9 @@ cbfs-offset: The current implementation supports only a subset of CBFS features. It does not support other file types (e.g. payload), adding multiple files (like the 'files' entry with a pattern supported by binman), putting files at a -particular offset in the CBFS and a few other things. +offset in the CBFS and a few other things.

-Of course binman can create images containing multiple CBFSs, simply by +Of course, binman can create images containing multiple CBFSs, simply by defining these in the binman config::

@@ -475,7 +475,7 @@ defining these in the binman config:: };

This creates an 8MB image with two CBFSs, one at offset 1MB, one at 7MB, -both of size 1MB. +both sizes 1MB.

@@ -745,11 +745,11 @@ Example output for a simple image with U-Boot and an FDT map:: }; };

-If allow-repack is used then 'orig-offset' and 'orig-size' properties are +If allow-repack is used, then 'orig-offset' and 'orig-size' properties are added as necessary. See the binman README.

When extracting files, an alternative 'fdt' format is available for fdtmaps. -Use `binman extract -F fdt ...` to use this. It will export a devicetree, +Use `binman extract -F fdt ...` to use this. It will export a device-tree, without the fdtmap header, so it can be viewed with `fdtdump`.

@@ -766,8 +766,8 @@ Properties / Entry arguments: lz4: Use lz4 compression (via 'lz4' command-line utility) - files-align: Align each file to the given alignment

-This entry reads a number of files and places each in a separate sub-entry -within this entry. To access these you need to enable device-tree updates +The entry reads a few files and places each in a separate sub-entry +within this entry. To access it you need to enable device-tree updates at run-time so you can obtain the file positions.

@@ -883,7 +883,7 @@ NAME Name of the dtb as provided (i.e. without adding '.dtb')

The `default` property, if present, will be automatically set to the name -if of configuration whose devicetree matches the `default-dt` entry +if of configuration whose device-tree matches the `default-dt` entry argument, e.g. with `-a default-dt=sun50i-a64-pine64-lts`.

Available substitutions for property values in these nodes are: @@ -919,7 +919,7 @@ U-Boot supports creating fdt and config nodes automatically. To do this, pass an `of-list` property (e.g. `-a of-list=file1 file2`). This tells binman that you want to generates nodes for two files: `file1.dtb` and `file2.dtb`. The `fit,fdt-list` property (see above) indicates that -`of-list` should be used. If the property is missing you will get an error. +`of-list` should be used. If the property is missing, you get an error.

Then add a 'generator node', a node with a name starting with '@'::

@@ -953,20 +953,20 @@ You can create config nodes in a similar way:: This tells binman to create nodes `config-1` and `config-2`, i.e. a config for each of your two files.

-Note that if no devicetree files are provided (with '-a of-list' as above) +Note that if no device-tree files are provided (with '-a of-list' as above) then no nodes will be generated.

The 'fit,compatible' property (if present) is replaced with the compatible -string from the root node of the devicetree, so that things work correctly -with FIT's configuration-matching algortihm. +string from the root node of the device-tree, so that things work correctly +with FIT's configuration-matching algorithm.

Dealing with phases

FIT can be used to load firmware. In this case it may be necessary to run
-the devicetree for each model through fdtgrep to remove unwanted properties.
+the device-tree for each model through fdtgrep to remove unwanted properties.
The 'fit,fdt-phase' property can be provided to indicate the phase for which
-the devicetree is intended.
+the device-tree is intended.

For example this indicates that the FDT should be processed for VPL::

@@ -1164,7 +1164,7 @@ Properties / Entry arguments:

FMAP is a simple format used by flashrom, an open-source utility for
reading and writing the SPI flash, typically on x86 CPUs. The format
-provides flashrom with a list of areas, so it knows what it in the flash.
+provides flashrom with a list of areas, that it knows what is in the flash.
It can then read or write just a single area, instead of the whole flash.

The format is defined by the flashrom project, in the file lib/fmap.h -
@@ -1214,7 +1214,7 @@ Entry: image-header: An entry which contains a pointer to the FDT map

Properties / Entry arguments:
    location: Location of header ("start" or "end" of image). This is
-        optional. If omitted then the entry must have an offset property.
+        optional. If omitted, then the entry must have an offset property.

This adds an 8-byte entry to the start or end of the image, pointing to the
location of the FDT map. The format is a magic number followed by an offset
@@ -1223,7 +1223,7 @@ from the start or end of the image, in twos-compliment format.
This entry must be in the top-level part of the image.

NOTE: If the location is at the start/end, you will probably need to specify
-sort-by-offset for the image, unless you actually put the image header
+sort-by-offset for the image, unless you put the image header
first/last in the entry list.


@@ -1338,7 +1338,7 @@ Properties / Entry arguments:
This file contains a binary blob which is used on some devices to set up
the silicon. U-Boot executes this code in U-Boot proper after SDRAM is
running, so that it can make full use of memory. Documentation is typically
-not available in sufficient detail to allow U-Boot do this this itself.
+not available in sufficient detail to allow U-Boot do this itself.

An example filename is 'fsp_s.bin'

@@ -1411,7 +1411,7 @@ Properties / Entry arguments:
This file contains code used by the SoC that is required to make it work.
The Management Engine is like a background task that runs things that are
not clearly documented, but may include keyboard, display and network
-access. For platform that use ME it is not possible to disable it. U-Boot
+access. For platforms using ME, it is not possible to disable it. U-Boot
does not directly execute code in the ME binary.

A typical filename is 'me.bin'.
@@ -1664,7 +1664,7 @@ placed at offset 'RESET_VECTOR_ADDRESS - 0xffc'.

.. _etype_pre_load:

-Entry: pre-load: Pre load image header
+Entry: pre-load: Pre-load image header
--------------------------------------

Properties / Entry arguments:
@@ -2216,14 +2216,14 @@ Properties / Entry arguments:
Entry: u-boot-expanded: U-Boot flat binary broken out into its component parts
------------------------------------------------------------------------------

-This is a section containing the U-Boot binary and a devicetree. Using this
+This is a section containing the U-Boot binary and a device-tree. Using this
entry type automatically creates this section, with the following entries
in it:

   u-boot-nodtb
   u-boot-dtb

-Having the devicetree separate allows binman to update it in the final
+Having the device-tree separate allows binman to update it in the final
image, so that the entries positions are provided to the running U-Boot.


@@ -2303,8 +2303,8 @@ to avoid the data overlapping with U-Boot variables. This entry is useful in
that case. It automatically pads out the entry size to cover both the code,
data and BSS.

-The contents of this entry will a certain number of zero bytes, determined
-by __bss_size
+The contents of this entry will be filled up with a number of zero bytes,
+determined by __bss_size

The ELF file 'spl/u-boot-spl' must also be available for this to work, since
binman uses that to look up the BSS address.
@@ -2348,14 +2348,14 @@ Properties / Entry arguments:
        select)

This is a section containing the U-Boot binary, BSS padding if needed and a
-devicetree. Using this entry type automatically creates this section, with
+device-tree. Using this entry type automatically creates this section, with
the following entries in it:

   u-boot-spl-nodtb
   u-boot-spl-bss-pad
   u-boot-dtb

-Having the devicetree separate allows binman to update it in the final
+Having the device-tree separate allows binman to update it in the final
image, so that the entries positions are provided to the running U-Boot.

This entry is selected based on the value of the 'spl-dtb' entryarg. If
@@ -2479,8 +2479,8 @@ to avoid the data overlapping with U-Boot variables. This entry is useful in
that case. It automatically pads out the entry size to cover both the code,
data and BSS.

-The contents of this entry will a certain number of zero bytes, determined
-by __bss_size
+The contents of this entry will be filled up with a number of zero bytes,
+determined by __bss_size

The ELF file 'tpl/u-boot-tpl' must also be available for this to work, since
binman uses that to look up the BSS address.
@@ -2536,14 +2536,14 @@ Properties / Entry arguments:
        select)

This is a section containing the U-Boot binary, BSS padding if needed and a
-devicetree. Using this entry type automatically creates this section, with
+device-tree. Using this entry type automatically creates this section, with
the following entries in it:

   u-boot-tpl-nodtb
   u-boot-tpl-bss-pad
   u-boot-dtb

-Having the devicetree separate allows binman to update it in the final
+Having the device-tree separate allows binman to update it in the final
image, so that the entries positions are provided to the running U-Boot.

This entry is selected based on the value of the 'tpl-dtb' entryarg. If
@@ -2678,8 +2678,8 @@ to avoid the data overlapping with U-Boot variables. This entry is useful in
that case. It automatically pads out the entry size to cover both the code,
data and BSS.

-The contents of this entry will a certain number of zero bytes, determined
-by __bss_size
+The contents of this entry will be filled up with a number of zero bytes,
+determined by __bss_size

The ELF file 'vpl/u-boot-vpl' must also be available for this to work, since
binman uses that to look up the BSS address.
@@ -2723,14 +2723,14 @@ Properties / Entry arguments:
        select)

This is a section containing the U-Boot binary, BSS padding if needed and a
-devicetree. Using this entry type automatically creates this section, with
+device-tree. Using this entry type automatically creates this section, with
the following entries in it:

   u-boot-vpl-nodtb
   u-boot-vpl-bss-pad
   u-boot-dtb

-Having the devicetree separate allows binman to update it in the final
+Having the device-tree separate allows binman to update it in the final
image, so that the entries positions are provided to the running U-Boot.

This entry is selected based on the value of the 'vpl-dtb' entryarg. If
@@ -2774,7 +2774,7 @@ Properties / Entry arguments:
See Entry_u_boot_ucode for full details of the three entries involved in
this process. This entry updates U-Boot with the offset and size of the
microcode, to allow early x86 boot code to find it without doing anything
-complicated. Otherwise it is the same as the u-boot entry.
+complicated. Otherwise, it is the same as the u-boot entry.



@@ -2947,8 +2947,8 @@ Properties / Entry arguments:
    - keysrc-enc: (Optional) Key source when using decryption engine
    - pmufw-filename: Filename of PMU firmware. Default: pmu-firmware.elf
    - psk-key-name-hint: Name of primary secret key to use for signing the
-                         secondardy public key. Format: .pem file
-    - ssk-key-name-hint: Name of secondardy secret key to use for signing
+                         secondary public key. Format: .pem file
+    - ssk-key-name-hint: Name of secondary secret key to use for signing
                         the boot image. Format: .pem file

The etype is used to create a boot image for Xilinx ZynqMP