doc: Remove FIT documentation that is elsewhere

Before 9d0750064e (doc: Move external FIT docs into the main body), the
FIT property data-size was not a mandatory property and still it is not
expected to be set alongside the data property.

Move the data-size property to the "Conditionally mandatory property"
section, where it actually belongs.

Signed-off-by: Sam Povilus <sam.povilus@amd.com>
Reviewed-by: Simon Glass <sjg@chromium.org>

2 files changed, 6 insertions, 682 deletions

diff --git a/doc/usage/fit/index.rst b/doc/usage/fit/index.rst
index bd25bd3..68231e9 100644
--- a/doc/usage/fit/index.rst
+++ b/doc/usage/fit/index.rst
@@ -4,8 +4,8 @@ Flat Image Tree (FIT)
 =====================
 
 U-Boot uses Flat Image Tree (FIT) as a standard file format for packaging
-images that it it reads and boots. Documentation about FIT is available at
-doc/uImage.FIT
+images that it reads and boots. Documentation about FIT is available in
+`the Flattened Image Tree project <https://fitspec.osfw.foundation/>`_.
 
 .. toctree::
     :maxdepth: 1
diff --git a/doc/usage/fit/source_file_format.rst b/doc/usage/fit/source_file_format.rst
index 15990e3..2bd8e79 100644
--- a/doc/usage/fit/source_file_format.rst
+++ b/doc/usage/fit/source_file_format.rst
@@ -1,684 +1,8 @@
-.. SPDX-License-Identifier: GPL-2.0+
+.. SPDX-License-Identifier: GPL-2.0-or-later
 
 Flattened Image Tree (FIT) Format
 =================================
 
-Introduction
-------------
-
-The number of elements playing a role in the kernel booting process has
-increased over time and now typically includes the devicetree, kernel image and
-possibly a ramdisk image. Generally, all must be placed in the system memory and
-booted together.
-
-For firmware images a similar process has taken place, with various binaries
-loaded at different addresses, such as ARM's ATF, OpenSBI, FPGA and U-Boot
-itself.
-
-FIT provides a flexible and extensible format to deal with this complexity. It
-provides support for multiple components. It also supports multiple
-configurations, so that the same FIT can be used to boot multiple boards, with
-some components in common (e.g. kernel) and some specific to that board (e.g.
-devicetree).
-
-Terminology
-~~~~~~~~~~~
-
-This document defines FIT by providing FDT (Flat Device Tree) bindings. These
-describe the final form of the FIT at the moment when it is used. The user
-perspective may be simpler, as some of the properties (like timestamps and
-hashes) are filled in automatically by the U-Boot mkimage tool.
-
-To avoid confusion with the kernel FDT the following naming convention is used:
-
-FIT
-    Flattened Image Tree
-
-FIT is formally a flattened devicetree (in the libfdt meaning), which conforms
-to bindings defined in this document.
-
-.its
-    image tree source
-
-.itb
-    flattened image tree blob
-
-Image-building procedure
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following picture shows how the FIT is prepared. Input consists of
-image source file (.its) and a set of data files. Image is created with the
-help of standard U-Boot mkimage tool which in turn uses dtc (device tree
-compiler) to produce image tree blob (.itb). The resulting .itb file is the
-actual binary of a new FIT::
-
-    tqm5200.its
-    +
-    vmlinux.bin.gz     mkimage + dtc               xfer to target
-    eldk-4.2-ramdisk  --------------> tqm5200.itb --------------> boot
-    tqm5200.dtb                          /|\
-                                          |
-                                     'new FIT'
-
-Steps:
-
-#. Create .its file, automatically filled-in properties are omitted
-
-#. Call mkimage tool on a .its file
-
-#. mkimage calls dtc to create .itb image and assures that
-   missing properties are added
-
-#. .itb (new FIT) is uploaded onto the target and used therein
-
-
-Unique identifiers
-~~~~~~~~~~~~~~~~~~
-
-To identify FIT sub-nodes representing images, hashes, configurations (which
-are defined in the following sections), the "unit name" of the given sub-node
-is used as it's identifier as it assures uniqueness without additional
-checking required.
-
-
-External data
-~~~~~~~~~~~~~
-
-FIT is normally built initially with image data in the 'data' property of each
-image node. It is also possible for this data to reside outside the FIT itself.
-This allows the 'FDT' part of the FIT to be quite small, so that it can be
-loaded and scanned without loading a large amount of data. Then when an image is
-needed it can be loaded from an external source.
-
-External FITs use 'data-offset' or 'data-position' instead of 'data'.
-
-The mkimage tool can convert a FIT to use external data using the `-E` argument,
-optionally using `-p` to specific a fixed position.
-
-It is often desirable to align each image to a block size or cache-line size
-(e.g. 512 bytes), so that there is no need to copy it to an aligned address when
-reading the image data. The mkimage tool provides a `-B` argument to support
-this.
-
-Root-node properties
---------------------
-
-The root node of the FIT should have the following layout::
-
-    / o image-tree
-        |- description = "image description"
-        |- timestamp = <12399321>
-        |- #address-cells = <1>
-        |
-        o images
-        | |
-        | o image-1 {...}
-        | o image-2 {...}
-        | ...
-        |
-        o configurations
-          |- default = "conf-1"
-          |
-          o conf-1 {...}
-          o conf-2 {...}
-          ...
-
-Optional property
-~~~~~~~~~~~~~~~~~
-
-description
-    Textual description of the FIT
-
-Mandatory property
-~~~~~~~~~~~~~~~~~~
-
-timestamp
-    Last image modification time being counted in seconds since
-    1970-01-01 00:00:00 - to be automatically calculated by mkimage tool.
-
-Conditionally mandatory property
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-#address-cells
-    Number of 32bit cells required to represent entry and
-    load addresses supplied within sub-image nodes. May be omitted when no
-    entry or load addresses are used.
-
-Mandatory nodes
-~~~~~~~~~~~~~~~
-
-images
-    This node contains a set of sub-nodes, each of them representing
-    single component sub-image (like kernel, ramdisk, etc.). At least one
-    sub-image is required.
-
-configurations
-    Contains a set of available configuration nodes and
-    defines a default configuration.
-
-
-'/images' node
---------------
-
-This node is a container node for component sub-image nodes. Each sub-node of
-the '/images' node should have the following layout::
-
-    o image-1
-        |- description = "component sub-image description"
-        |- data = /incbin/("path/to/data/file.bin")
-        |- type = "sub-image type name"
-        |- arch = "ARCH name"
-        |- os = "OS name"
-        |- compression = "compression name"
-        |- load = <00000000>
-        |- entry = <00000000>
-        |
-        o hash-1 {...}
-        o hash-2 {...}
-        ...
-
-Mandatory properties
-~~~~~~~~~~~~~~~~~~~~
-
-description
-    Textual description of the component sub-image
-
-type
-    Name of component sub-image type. Supported types are:
-
-    ====================  ==================
-    Sub-image type        Meaning
-    ====================  ==================
-    invalid               Invalid Image
-    aisimage              Davinci AIS image
-    atmelimage            ATMEL ROM-Boot Image
-    copro                 Coprocessor Image
-    fdt_legacy            legacy Image with Flat Device Tree
-    filesystem            Filesystem Image
-    firmware              Firmware
-    firmware_ivt          Firmware with HABv4 IVT
-    flat_dt               Flat Device Tree
-    fpga                  FPGA Device Image (bitstream file, vendor specific)
-    gpimage               TI Keystone SPL Image
-    imx8image             NXP i.MX8 Boot Image
-    imx8mimage            NXP i.MX8M Boot Image
-    imximage              Freescale i.MX Boot Image
-    kernel                Kernel Image
-    kernel_noload         Kernel Image (no loading done)
-    kwbimage              Kirkwood Boot Image
-    lpc32xximage          LPC32XX Boot Image
-    mtk_image             MediaTek BootROM loadable Image
-    multi                 Multi-File Image
-    mxsimage              Freescale MXS Boot Image
-    omapimage             TI OMAP SPL With GP CH
-    pblimage              Freescale PBL Boot Image
-    pmmc                  TI Power Management Micro-Controller Firmware
-    ramdisk               RAMDisk Image
-    rkimage               Rockchip Boot Image
-    rksd                  Rockchip SD Boot Image
-    rkspi                 Rockchip SPI Boot Image
-    script                Script
-    socfpgaimage          Altera SoCFPGA CV/AV preloader
-    socfpgaimage_v1       Altera SoCFPGA A10 preloader
-    spkgimage             Renesas SPKG Image
-    standalone            Standalone Program
-    stm32image            STMicroelectronics STM32 Image
-    sunxi_egon            Allwinner eGON Boot Image
-    sunxi_toc0            Allwinner TOC0 Boot Image
-    tee                   Trusted Execution Environment Image
-    ublimage              Davinci UBL image
-    vybridimage           Vybrid Boot Image
-    x86_setup             x86 setup.bin
-    zynqimage             Xilinx Zynq Boot Image
-    zynqmpbif             Xilinx ZynqMP Boot Image (bif)
-    zynqmpimage           Xilinx ZynqMP Boot Image
-    ====================  ==================
-
-compression
-    Compression used by included data. If no compression is used, the
-    compression property should be set to "none". If the data is compressed but
-    it should not be uncompressed by the loader (e.g. compressed ramdisk), this
-    should also be set to "none".
-
-    Supported compression types are:
-
-    ====================  ==================
-    Compression type      Meaning
-    ====================  ==================
-    none                  uncompressed
-    bzip2                 bzip2 compressed
-    gzip                  gzip compressed
-    lz4                   lz4 compressed
-    lzma                  lzma compressed
-    lzo                   lzo compressed
-    zstd                  zstd compressed
-    ====================  ==================
-
-
-Conditionally mandatory property
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-data
-    Path to the external file which contains this node's binary data. Within
-    the FIT this is the contents of the file. This is mandatory unless
-    external data is used.
-
-data-offset
-    Offset of the data in a separate image store. The image store is placed
-    immediately after the last byte of the device tree binary, aligned to a
-    4-byte boundary. This is mandatory if external data is used, with an offset.
-
-data-position
-    Machine address at which the data is to be found. This is a fixed address
-    not relative to the loading of the FIT. This is mandatory if external data
-    used with a fixed address.
-
-data-size
-    Size of the data in bytes. This is mandatory if external data is used.
-
-os
-    OS name, mandatory for types "kernel". Valid OS names are:
-
-    ====================  ==================
-    OS name               Meaning
-    ====================  ==================
-    invalid               Invalid OS
-    4_4bsd                4_4BSD
-    arm-trusted-firmware  ARM Trusted Firmware
-    dell                  Dell
-    efi                   EFI Firmware
-    esix                  Esix
-    freebsd               FreeBSD
-    integrity             INTEGRITY
-    irix                  Irix
-    linux                 Linux
-    ncr                   NCR
-    netbsd                NetBSD
-    openbsd               OpenBSD
-    openrtos              OpenRTOS
-    opensbi               RISC-V OpenSBI
-    ose                   Enea OSE
-    plan9                 Plan 9
-    psos                  pSOS
-    qnx                   QNX
-    rtems                 RTEMS
-    sco                   SCO
-    solaris               Solaris
-    svr4                  SVR4
-    tee                   Trusted Execution Environment
-    u-boot                U-Boot
-    vxworks               VxWorks
-    ====================  ==================
-
-arch
-    Architecture name, mandatory for types: "standalone", "kernel",
-    "firmware", "ramdisk" and "fdt". Valid architecture names are:
-
-    ====================  ==================
-    Architecture type     Meaning
-    ====================  ==================
-    invalid               Invalid ARCH
-    alpha                 Alpha
-    arc                   ARC
-    arm64                 AArch64
-    arm                   ARM
-    avr32                 AVR32
-    blackfin              Blackfin
-    ia64                  IA64
-    m68k                  M68K
-    microblaze            MicroBlaze
-    mips64                MIPS 64 Bit
-    mips                  MIPS
-    nds32                 NDS32
-    nios2                 NIOS II
-    or1k                  OpenRISC 1000
-    powerpc               PowerPC
-    ppc                   PowerPC
-    riscv                 RISC-V
-    s390                  IBM S390
-    sandbox               Sandbox
-    sh                    SuperH
-    sparc64               SPARC 64 Bit
-    sparc                 SPARC
-    x86_64                AMD x86_64
-    x86                   Intel x86
-    xtensa                Xtensa
-    ====================  ==================
-
-entry
-    entry point address, address size is determined by
-    '#address-cells' property of the root node.
-    Mandatory for types: "firmware", and "kernel".
-
-load
-    load address, address size is determined by '#address-cells'
-    property of the root node.
-    Mandatory for types: "firmware", and "kernel".
-
-compatible
-    compatible method for loading image.
-    Mandatory for types: "fpga", and images that do not specify a load address.
-    Supported compatible methods:
-
-    ==========================  =========================================
-    Compatible string           Meaning
-    ==========================  =========================================
-    u-boot,fpga-legacy          Generic fpga loading routine.
-    u-boot,zynqmp-fpga-ddrauth  Signed non-encrypted FPGA bitstream for
-                                Xilinx Zynq UltraScale+ (ZymqMP) device.
-    u-boot,zynqmp-fpga-enc      Encrypted FPGA bitstream for Xilinx Zynq
-                                UltraScale+ (ZynqMP) device.
-    ==========================  =========================================
-
-phase
-    U-Boot phase for which the image is intended.
-
-    "spl"
-        image is an SPL image
-
-    "u-boot"
-        image is a U-Boot image
-
-Optional nodes:
-
-hash-1
-    Each hash sub-node represents separate hash or checksum
-    calculated for node's data according to specified algorithm.
-
-signature-1
-    Each signature sub-node represents separate signature
-    calculated for node's data according to specified algorithm.
-
-
-Hash nodes
-----------
-
-::
-
-    o hash-1
-        |- algo = "hash or checksum algorithm name"
-        |- value = [hash or checksum value]
-
-Mandatory properties
-~~~~~~~~~~~~~~~~~~~~
-
-algo
-    Algorithm name. Supported algoriths and their value sizes are:
-
-    ==================== ============ =========================================
-    Sub-image type       Size (bytes) Meaning
-    ==================== ============ =========================================
-    crc16-ccitt          2            Cyclic Redundancy Check 16-bit
-                                      (Consultative Committee for International
-                                      Telegraphy and Telephony)
-    crc32                4            Cyclic Redundancy Check 32-bit
-    md5                  16           Message Digest 5 (MD5)
-    sha1                 20           Secure Hash Algorithm 1 (SHA1)
-    sha256               32           Secure Hash Algorithm 2 (SHA256)
-    sha384               48           Secure Hash Algorithm 2 (SHA384)
-    sha512               64           Secure Hash Algorithm 2 (SHA512)
-    ==================== ============ =========================================
-
-value
-    Actual checksum or hash value.
-
-Image-signature nodes
----------------------
-
-::
-
-    o signature-1
-        |- algo = "algorithm name"
-        |- key-name-hint = "key name"
-        |- value = [hash or checksum value]
-
-
-Mandatory properties
-~~~~~~~~~~~~~~~~~~~~
-
-_`FIT Algorithm`:
-
-algo
-    Algorithm name. Supported algoriths and their value sizes are shown below.
-    Note that the hash is specified separately from the signing algorithm, so
-    it is possible to mix and match any SHA algorithm with any signing
-    algorithm. The size of the signature relates to the signing algorithm, not
-    the hash, since it is the hash that is signed.
-
-    ==================== ============ =========================================
-    Sub-image type       Size (bytes) Meaning
-    ==================== ============ =========================================
-    sha1,rsa2048         256          SHA1 hash signed with 2048-bit
-                                      Rivest–Shamir–Adleman algorithm
-    sha1,rsa3072         384          SHA1 hash signed with 2048-bit RSA
-    sha1,rsa4096         512          SHA1 hash signed with 2048-bit RSA
-    sha1,ecdsa256        32           SHA1 hash signed with 256-bit  Elliptic
-                                      Curve Digital Signature Algorithm
-    sha256,...
-    sha384,...
-    sha512,...
-    ==================== ============ =========================================
-
-key-name-hint
-    Name of key to use for signing. The keys will normally be in
-    a single directory (parameter -k to mkimage). For a given key <name>, its
-    private key is stored in <name>.key and the certificate is stored in
-    <name>.crt.
-
-sign-images
-    A list of images to sign, each being a property of the conf
-    node that contains then. The default is "kernel,fdt" which means that these
-    two images will be looked up in the config and signed if present. This is
-    used by mkimage to determine which images to sign.
-
-The following properies are added as part of signing, and are mandatory:
-
-value
-    Actual signature value. This is added by mkimage.
-
-hashed-nodes
-    A list of nodes which were hashed by the signer. Each is
-    a string - the full path to node. A typical value might be::
-
-	hashed-nodes = "/", "/configurations/conf-1", "/images/kernel",
-	    "/images/kernel/hash-1", "/images/fdt-1",
-	    "/images/fdt-1/hash-1";
-
-hashed-strings
-    The start and size of the string region of the FIT that was hashed. The
-    start is normally 0, indicating the first byte of the string table. The size
-    indicates the number of bytes hashed as part of signing.
-
-The following properies are added as part of signing, and are optional:
-
-timestamp
-    Time when image was signed (standard Unix time_t format)
-
-signer-name
-    Name of the signer (e.g. "mkimage")
-
-signer-version
-    Version string of the signer (e.g. "2013.01")
-
-comment
-    Additional information about the signer or image
-
-padding
-    The padding algorithm, it may be pkcs-1.5 or pss,
-    if no value is provided we assume pkcs-1.5
-
-
-'/configurations' node
-----------------------
-
-The 'configurations' node creates convenient, labeled boot configurations,
-which combine together kernel images with their ramdisks and fdt blobs.
-
-The 'configurations' node has the following structure::
-
-    o configurations
-        |- default = "default configuration sub-node unit name"
-        |
-        o config-1 {...}
-        o config-2 {...}
-        ...
-
-
-Optional property
-~~~~~~~~~~~~~~~~~
-
-default
-    Selects one of the configuration sub-nodes as a default configuration.
-
-Mandatory nodes
-~~~~~~~~~~~~~~~
-
-configuration-sub-node-unit-name
-    At least one of the configuration sub-nodes is required.
-
-Optional nodes
-~~~~~~~~~~~~~~
-
-signature-1
-    Each signature sub-node represents separate signature
-    calculated for the configuration according to specified algorithm.
-
-
-Configuration nodes
--------------------
-
-Each configuration has the following structure::
-
-    o config-1
-        |- description = "configuration description"
-        |- kernel = "kernel sub-node unit name"
-        |- fdt = "fdt sub-node unit-name" [, "fdt overlay sub-node unit-name", ...]
-        |- loadables = "loadables sub-node unit-name"
-        |- script = "
-        |- compatible = "vendor,board-style device tree compatible string"
-        o signature-1 {...}
-
-Mandatory properties
-~~~~~~~~~~~~~~~~~~~~
-
-description
-    Textual configuration description.
-
-kernel or firmware
-    Unit name of the corresponding kernel or firmware
-    (u-boot, op-tee, etc) image. If both "kernel" and "firmware" are specified,
-    control is passed to the firmware image.
-
-Optional properties
-~~~~~~~~~~~~~~~~~~~
-
-fdt
-    Unit name of the corresponding fdt blob (component image node of a
-    "fdt type"). Additional fdt overlay nodes can be supplied which signify
-    that the resulting device tree blob is generated by the first base fdt
-    blob with all subsequent overlays applied.
-
-fpga
-    Unit name of the corresponding fpga bitstream blob
-    (component image node of a "fpga type").
-
-loadables
-    Unit name containing a list of additional binaries to be
-    loaded at their given locations.  "loadables" is a comma-separated list
-    of strings. U-Boot will load each binary at its given start-address and
-    may optionally invoke additional post-processing steps on this binary based
-    on its component image node type.
-
-script
-    The image to use when loading a U-Boot script (for use with the
-    source command).
-
-compatible
-    The root compatible string of the U-Boot device tree that
-    this configuration shall automatically match when CONFIG_FIT_BEST_MATCH is
-    enabled. If this property is not provided, the compatible string will be
-    extracted from the fdt blob instead. This is only possible if the fdt is
-    not compressed, so images with compressed fdts that want to use compatible
-    string matching must always provide this property.
-
-The FDT blob is required to properly boot FDT based kernel, so the minimal
-configuration for 2.6 FDT kernel is (kernel, fdt) pair.
-
-Older, 2.4 kernel and 2.6 non-FDT kernel do not use FDT blob, in such cases
-'struct bd_info' must be passed instead of FDT blob, thus fdt property *must
-not* be specified in a configuration node.
-
-Configuration-signature nodes
------------------------------
-
-::
-
-    o signature-1
-        |- algo = "algorithm name"
-        |- key-name-hint = "key name"
-        |- sign-images = "path1", "path2";
-        |- value = [hash or checksum value]
-        |- hashed-strings = <0 len>
-
-
-Mandatory properties
-~~~~~~~~~~~~~~~~~~~~
-
-algo
-    See `FIT Algorithm`_.
-
-key-name-hint
-    Name of key to use for signing. The keys will normally be in
-    a single directory (parameter -k to mkimage). For a given key <name>, its
-    private key is stored in <name>.key and the certificate is stored in
-    <name>.crt.
-
-The following properies are added as part of signing, and are mandatory:
-
-value
-    Actual signature value. This is added by mkimage.
-
-The following properies are added as part of signing, and are optional:
-
-timestamp
-    Time when image was signed (standard Unix time_t format)
-
-signer-name
-    Name of the signer (e.g. "mkimage")
-
-signer-version
-    Version string of the signer (e.g. "2013.01")
-
-comment
-    Additional information about the signer or image
-
-padding
-    The padding algorithm, it may be pkcs-1.5 or pss,
-    if no value is provided we assume pkcs-1.5
-
-
-
-Examples
---------
-
-Some example files are available here, showing various scenarios
-
-.. toctree::
-    :maxdepth: 1
-
-    kernel
-    kernel_fdt
-    kernel_fdts_compressed
-    multi
-    multi_spl
-    multi-with-fpga
-    multi-with-loadables
-    sec_firmware_ppa
-    sign-configs
-    sign-images
-    uefi
-    update3
-    update_uboot
-
-.. sectionauthor:: Marian Balakowicz <m8@semihalf.com>
-.. sectionauthor:: External data additions, 25/1/16 Simon Glass <sjg@chromium.org>
+FIT format documentation has been moved to
+`a separate project <https://fitspec.osfw.foundation/>`_. Updates to the
+format/specification should be submitted there.