u-boot-brain/doc
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
..
android doc: android/boot-image: invalid C declaration 2021-01-04 09:10:16 -05:00
api linker_lists: Fix alignment issue 2020-12-18 20:32:21 -07:00
arch smbios: Add documentation and devicetree binding 2020-11-06 10:18:20 +08:00
board doc: board: freescale: advise to use newer atf and firmware 2021-01-18 15:23:06 -05:00
build doc/build/gcc.rst: required packages for SUSE 2020-12-15 09:30:51 +01:00
chromium
develop doc: move README.trace to HTML documentation 2020-12-15 09:37:24 +01:00
device-tree-bindings video: seps525: Add dt binding description 2021-01-05 11:54:53 +01:00
driver-model MAINTAINERS: Update STi and STM32 maintainers emails in remaining files 2021-01-13 09:52:58 +01:00
imx dm: treewide: Rename auto_alloc_size members to be shorter 2020-12-13 08:00:25 -07:00
media
mvebu
sphinx doc: Sphinx.override_domain() deprecated 2020-10-14 11:16:34 -04:00
sphinx-static
SPI
SPL
uefi efi_loader: setting boot device 2021-01-13 02:38:00 +01:00
uImage.FIT doc: FIT image: Clarify format and simplify syntax 2021-01-22 16:17:33 -05:00
usage Pull request for documentation tag doc-2021-04-rc1 2021-01-18 08:04:05 -05:00
.gitignore
bounces
conf.py doc: allow building htmldoc with Sphinx 3+ 2020-12-15 09:31:39 +01:00
feature-removal-schedule.txt
git-mailrc MAINTAINERS, git-mailrc: Update sunxi maintainers 2020-10-29 09:57:13 -04:00
I2C_Edge_Conditions
index.rst doc: move pstore.rst to usage/pstore.rst 2020-12-15 09:35:04 +01:00
kwboot.1
Makefile
mkimage.1 mkimage: Allow updating the FIT timestamp 2020-07-25 14:46:57 -06:00
README.440-DDR-performance
README.AMCC-eval-boards-cleanup
README.arm-caches
README.arm-relocation treewide: convert bd_t to struct bd_info manually 2020-07-17 10:46:44 -04:00
README.armada-secureboot
README.asn1
README.atmel_mci treewide: convert bd_t to struct bd_info manually 2020-07-17 10:46:44 -04:00
README.atmel_pmecc
README.autoboot
README.bcm7xxx
README.bcmns3 doc: add README doc for bcmns3 platform 2020-07-29 10:37:11 -04:00
README.bedbug
README.bitbangMII
README.bloblist
README.bootcount
README.boston
README.bus_vcxk
README.cfi
README.chromium cros: Add information about booting Chrome OS on x86 2020-09-25 11:27:11 +08:00
README.chromium-chainload
README.commands.itest
README.commands.spl
README.console treewide: convert bd_t to struct bd_info manually 2020-07-17 10:46:44 -04:00
README.davinci README: davinci: Clarify when SPL is used and the target devices. 2020-07-13 20:58:34 +05:30
README.davinci.nand_spl
README.dfu doc: dfu: fix typo in README.dfu 2020-10-22 11:26:14 -04:00
README.dfutftp cmd: drop fitupd command 2020-07-16 12:37:01 +02:00
README.displaying-bmps
README.distro
README.dns
README.enetaddr
README.esbc_validate
README.ext4
README.falcon
README.fdt-control
README.fec_mxc
README.fsl_iim
README.fsl-clk
README.fsl-ddr
README.fsl-dpaa
README.fsl-esdhc Move eSDHC adapter card identification to board files 2020-07-27 14:16:28 +05:30
README.fsl-hwconfig
README.fsl-trustzone-components
README.fuse
README.generic_usb_ohci
README.generic-board treewide: convert bd_t to struct bd_info manually 2020-07-17 10:46:44 -04:00
README.gpio
README.gpt doc/README.gpt: reflow partition type GUID table 2021-01-16 14:49:09 -05:00
README.Heterogeneous-SoCs
README.hwconfig
README.i2c
README.iomux
README.JFFS2
README.JFFS2_NAND
README.kconfig
README.kwbimage
README.LED
README.link-local
README.lynxkdi
README.m54418twr
README.malta
README.marvell Revert "arm64: dts: a3720: add support for espressobin with populated emmc" 2020-12-07 07:11:37 +01:00
README.mediatek
README.memory-test
README.menu
README.mpc74xx Initial revision 2002-11-02 23:30:20 +00:00
README.mpc83xx.ddrecc
README.mpc83xxads
README.mpc85xx
README.mpc85xx-sd-spi-boot
README.mpc85xx-spin-table
README.mpc85xxcds
README.multi-dtb-fit doc: multi-dtb-fit: Remove double underscores 2020-07-17 10:47:19 -04:00
README.mxc_ocotp
README.nand
README.nand-boot-ppc440
README.ne2000
README.nokia_rx51 Nokia RX-51: Add link for u-boot-gen-combined script to README file 2020-06-13 23:12:17 +05:30
README.nvme
README.odroid
README.OFT
README.omap3 logicpd: Drop omap3 zoom1 2020-07-09 20:58:05 +05:30
README.omap-ulpi-viewport
README.pblimage
README.pcap
README.plan9
README.POST treewide: convert bd_t to struct bd_info manually 2020-07-17 10:46:44 -04:00
README.power-framework
README.pxe
README.ramboot-ppc85xx
README.rmobile
README.rockchip
README.rockusb
README.s5p4418 arm: add (default) config for nanopi2 board 2020-07-29 08:43:40 -04:00
README.s5pc1xx
README.sata
README.sched
README.scrapyard scrapyard: Delete this file and script 2019-09-19 12:54:29 -04:00
README.semihosting
README.serial_multi
README.sha1
README.silent Convert CONFIG_SYS_DEVICE_NULLDEV to Kconfig 2020-08-23 13:43:10 -04:00
README.SNTP
README.socfpga arm: socfpga: arria10: Add qts-filter for Arria10 socfpga 2020-10-09 17:53:14 +08:00
README.spear
README.SPL
README.splashprepare
README.srio-pcie-boot-corenet
README.standalone
README.t1040-l2switch
README.tee
README.ti-secure
README.TPL
README.ubi
README.ubispl
README.ublimage
README.udp net: add a generic udp protocol 2020-09-30 16:55:03 -04:00
README.unaligned-memory-access.txt
README.uniphier
README.update cmd: drop fitupd command 2020-07-16 12:37:01 +02:00
README.usb
README.vf610
README.video
README.virtio
README.VLAN
README.VSC3316-3308
README.vxworks
README.watchdog
README.zfs

This patch series adds support for ZFS listing and load to u-boot.

To Enable zfs ls and load commands, modify the board specific config file with
#define CONFIG_CMD_ZFS

Steps to test:

1. After applying the patch, zfs specific commands can be seen
   in the boot loader prompt using
	UBOOT #help

	zfsload- load binary file from a ZFS file system
	zfsls  - list files in a directory (default /)

2. To list the files in zfs pool, device or partition, execute
	zfsls <interface> <dev[:part]> [POOL/@/dir/file]
	For example:
	UBOOT #zfsls mmc 0:5 /rpool/@/usr/bin/

3. To read and load a file from an ZFS formatted partition to RAM, execute
	zfsload <interface> <dev[:part]> [addr] [filename] [bytes]
	For example:
	UBOOT #zfsload mmc 2:2 0x30007fc0 /rpool/@/boot/uImage

References :
	-- ZFS GRUB sources from Solaris GRUB-0.97
	-- GRUB Bazaar repository

Jorgen Lundman <lundman at lundman.net> 2012.