u-boot/doc/uImage.FIT
Alexandru Gagniuc 4afc4f37c7 doc: FIT image: Clarify format and simplify syntax
** Introduction

There are currently four ways to load an OS image with u-boot
  1. SPL -> u-boot -> bootm
  2. SPL blue falcon mode
  3. "Basic" FIT image (CONFIG_LOAD_FIT)
  4. "Full-featured" FIT image (CONFIG_LOAD_FIT_FULL)

These four code paths were developed independently, and share very
little code. (3) and (4), behave very differently, are littered with
special cases. They even have different DTS syntax and properties.

The cause of this divergence is that the FIT format specification
leaves a number of things open to interpretation. The purpose of this
change is to enable the reduction of code size, duplication, and
complexity by updating and streamlining the FIT format.

We are only marginally concerned with backwards compatibility, because
we don't have inter-compatibility. For example, CONFIG_LOAD_FIT is
able to load images that CONFIG_LOAD_FIT_FULL won't. This is a direct
result of the incompatible syntax between the two implementations.

Ideally, these changes would enable "simple" FIT to be a subset of the
"full" fit implementation, and share most code. These changes should
also eliminate the need for falcon mode (although we are not
advocating for the removal of falcon mode at this time).

** Description of changes

 * The "configurations" node is now mandatory

Guessing how to load components based on their "os" and "type" invites
confusion and superfluous heuristics. Instead, require each FIT image
to be explicit on how components should be loaded.

 * Eliminate "ramdisk", "setup", "standalone", and "fpga" properties

Having too many special purpose properties requires special-casing
FIT loading code. When a special property can be handled by another
property, it is redundant.
 - A "ramdisk" is identical to a loadable. Thus ramdisk images should
   be placed under "loadables".
 - A "setup" node can be achieved by using a "kernel" or "firmware"
   property instead.
 - "standalone" is used for u-boot nodes. The correct property to use
   in this case is "firmware".
 - "fpga" is a loadable

 * Prioritize control between "firmware" and "kernel"

"firmware" and "kernel" are special nodes in that control is passed
to the "entry-point" of the image. Both can be present, for example,
an OP-TEE firmware with a linux kernel. When both are present,
control is passed to the "firmware" image.

** Further generalizations (not included herein)

The "firmware" and "kernel" properties could be generalized as a
"next-boot-stage", or similar name. This "next" stage would be special
in that it is both executable, and is the stage that is passed
control. For example, "next-stage" could be an op-tee image, with
linux as a loadable, or a u-boot image.

Signed-off-by: Alexandru Gagniuc <mr.nuke.me@gmail.com>
2021-01-22 16:17:33 -05:00
..
beaglebone_vboot.txt arm: ti: Remove ARCH= references from documentation 2020-06-02 17:27:04 -04:00
command_syntax_extensions.txt doc: FIT image: fix incorrect description of DT node unit address 2018-01-15 18:29:21 -07:00
howto.txt spl: Use standard FIT entries 2020-10-27 08:13:32 +01:00
kernel.its doc: FIT image: fix incorrect examples of DT node unit address 2018-01-15 18:29:21 -07:00
kernel_fdt.its doc: FIT image: fix incorrect examples of DT node unit address 2018-01-15 18:29:21 -07:00
kernel_fdts_compressed.its fit: Support compat string property in configuration node 2019-07-29 09:32:08 -04:00
multi-with-fpga.its doc: FIT image: fix incorrect examples of DT node unit address 2018-01-15 18:29:21 -07:00
multi-with-loadables.its doc: FIT image: fix incorrect examples of DT node unit address 2018-01-15 18:29:21 -07:00
multi.its doc: FIT image: fix incorrect examples of DT node unit address 2018-01-15 18:29:21 -07:00
multi_spl.its doc: FIT image: fix incorrect examples of DT node unit address 2018-01-15 18:29:21 -07:00
overlay-fdt-boot.txt doc: FIT image: fix incorrect description of DT node unit address 2018-01-15 18:29:21 -07:00
sec_firmware_ppa.its armv8: sec_firmware: Add support for multiple loadables 2018-05-09 09:17:51 -05:00
sign-configs.its doc: FIT image: fix incorrect examples of DT node unit address 2018-01-15 18:29:21 -07:00
sign-images.its doc: FIT image: fix incorrect examples of DT node unit address 2018-01-15 18:29:21 -07:00
signature.txt doc: verified-boot: add required-mode information 2020-10-12 21:30:37 -04:00
source_file_format.txt doc: FIT image: Clarify format and simplify syntax 2021-01-22 16:17:33 -05:00
uefi.its doc: Add sample uefi.its image description file 2020-01-07 18:08:21 +01:00
update3.its doc: FIT image: fix incorrect examples of DT node unit address 2018-01-15 18:29:21 -07:00
update_uboot.its doc: fit: Write hex address as hex instead of int 2020-07-17 10:47:19 -04:00
verified-boot.txt doc: verified-boot: fix typos 2017-08-26 14:56:14 -04:00
x86-fit-boot.txt doc: FIT image: fix incorrect description of DT node unit address 2018-01-15 18:29:21 -07:00