u-boot.git/doc/uImage.FIT/source_file_format.txt, branch v2022.01

doc: FIT image: Introduce "u-boot, fpga-legacy" property

2021-04-14T19:23:01+00:00

Commit 4afc4f37c70e ("doc: FIT image: Clarify format and simplify
syntax") introduced a "compatible" property for loadable images.
It did not define its contents. Use "u-boot,fpga-legacy" compatible
string to specify that fpga_load() should be used to load the image.

Signed-off-by: Alexandru Gagniuc

doc: FIT image: Clarify format and simplify syntax

2021-01-22T21:17:33+00:00

** 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

doc: Fix typo in FIT documentation

2020-12-18T10:46:36+00:00

u_boot should be u-boot

Signed-off-by: Sean Anderson 
Reviewed-by: Bin Meng 
Reviewed-by: Jagan Teki

mkimage: fit_image: Add option to make fit header align

2020-04-24T14:10:01+00:00

The image is usually stored in block device like emmc, SD card, make the
offset of image data aligned to block(512 byte) can avoid data copy
during boot process.
eg. SPL boot from FIT image with external data:
- SPL read the first block of FIT image, and then parse the header;
- SPL read image data separately;
- The first image offset is the base_offset which is the header size;
- The second image offset is just after the first image;
- If the offset of imge does not aligned, SPL will do memcpy;
The header size is a ramdon number, which is very possible not aligned, so
add '-B size'to specify the align size in hex for better performance.

example usage:
  ./tools/mkimage -E -f u-boot.its -B 0x200 u-boot.itb

Signed-off-by: Kever Yang 
Reviewed-by: Punit Agrawal 
Reviewed-by: Tom Rini

cosmetic: Fix spelling and whitespace errors

2019-12-03T13:43:23+00:00

Signed-off-by: Thomas Hebb

fit: Support compat string property in configuration node

2019-07-29T13:32:08+00:00

This patch adds support for an optional optimization to compatible
string matching where the compatible string property from the root node
of the kernel FDT can be copied into the configuration node of the FIT
image. This is most useful when using compressed FDTs or when using FDT
overlays, where the traditional extraction of the compatible string from
the kernel FDT itself is not easily possible.

Signed-off-by: Julius Werner 
Reviewed-by: Simon Glass

doc: FIT image: clarify usage of "compression" property

2018-08-10T17:45:33+00:00

Compressed images should have their compression property
set to "none" if U-Boot should leave them compressed.

This is especially the case for compressed ramdisks that
should be uncompressed by the kernel only.

Signed-off-by: Simon Goldschmidt

doc: FIT image: fix incorrect description of DT node unit address

2018-01-16T01:29:21+00:00

The DT spec demands a unit-address in a node name to match the "reg"
property in that node. Newer dtc versions will throw warnings if this is
not the case.
Fix all occurences in the FIT image documentation files where this was not
observed, to not give bad examples to the reader.

Signed-off-by: Andre Przywara

SPL: Add FIT data-position property support

2017-12-13T02:33:38+00:00

For external data, FIT has a optional property "data-position" which
can set the external data to a fixed offset to FIT beginning.
Add the support for this property in SPL FIT.

Signed-off-by: Ye Li 
Signed-off-by: Peng Fan 
Reviewed-by: Simon Glass 
Reviewed-by: Tomas Melin 
Cc: Pantelis Antoniou 
Cc: "Andrew F. Davis" 
Cc: Igor Grinberg 
Cc: "tomas.melin@vaisala.com" 
Cc: Kever Yang 
Cc: Andre Przywara 
Cc: York Sun 
Cc: Lokesh Vutla 
Cc: "Cooper Jr., Franklin" 
Cc: George McCollister 
Cc: Tuomas Tynkkynen 
Cc: Jean-Jacques Hiblot 
Cc: Rick Altherr 
Cc: Tom Rini 
Reviewed-by: Lokesh Vutla 
Reviewed-by: York Sun

fit: fdt overlays doc

2017-09-15T11:27:49+00:00

Signed-off-by: Pantelis Antoniou 
Reviewed-by: Łukasz Majewski
Acked-by: Simon Glass