Add submodule dependency filesHEAD master

Change-Id: Iaf8d18082d3991dec7c0ebbea540f092188eb4ec
author: Angelos Mouzakitis <a.mouzakitis@virtualopensystems.com> 2023-10-10 14:33:42 +0000
committer: Angelos Mouzakitis <a.mouzakitis@virtualopensystems.com> 2023-10-10 14:33:42 +0000
commit: af1a266670d040d2f4083ff309d732d648afba2a (patch)
tree: 2fc46203448ddcc6f81546d379abfaeb323575e9 /roms/u-boot/doc/usage
parent: e02cda008591317b1625707ff8e115a4841aa889 (diff)
36 files changed, 2913 insertions, 0 deletions
diff --git a/roms/u-boot/doc/usage/addrmap.rst b/roms/u-boot/doc/usage/addrmap.rst
new file mode 100644
index 000000000..472fd547f
--- /dev/null
+++ b/roms/u-boot/doc/usage/addrmap.rst
@@ -0,0 +1,41 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+addrmap command
+===============
+
+Synopsis
+--------
+
+::
+
+    addrmap
+
+Description
+-----------
+
+The addrmap command is used to display non-identity virtual-physical memory
+mappings for 32-bit CPUs.
+
+The output may look like:
+
+::
+
+    => addrmap
+               vaddr            paddr             size
+    ================ ================ ================
+            e0000000        fe0000000         00100000
+            00000000         00000000         04000000
+            04000000         04000000         04000000
+            80000000        c00000000         10000000
+            90000000        c10000000         10000000
+            a0000000        fe1000000         00010000
+
+The first column indicates the virtual address.
+The second column indicates the physical address.
+The third column indicates the mapped size.
+
+Configuration
+-------------
+
+To use the addrmap command you must specify CONFIG_CMD_ADDRMAP=y.
+It is automatically turned on when CONFIG_ADDR_MAP is set.
diff --git a/roms/u-boot/doc/usage/askenv.rst b/roms/u-boot/doc/usage/askenv.rst
new file mode 100644
index 000000000..5c4ca35d4
--- /dev/null
+++ b/roms/u-boot/doc/usage/askenv.rst
@@ -0,0 +1,87 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+askenv command
+===============
+
+Synopsis
+--------
+
+::
+
+    askenv name [message] [size]
+
+Description
+-----------
+
+Display message and get environment variable name of max size characters
+from stdin.
+
+name
+    name of the environment variable
+
+message
+    message is displayed while the command waits for the  value to be
+    entered from stdin.if no message is specified,a default message
+    "Please enter name:" will be displayed.
+
+size
+    maximum number of characters that will be stored in environment
+    variable name.this is in decimal number format (unlike in
+    other commands where size values are in hexa-decimal). Default
+    value of size is 1023 (CONFIG_SYS_CBSIZE - 1).
+
+Example
+-------
+
+Value of a environment variable env1 without message and size parameters:
+
+::
+
+    => askenv env1;echo $?
+    Please enter 'env1': val1
+    0
+    => printenv env1
+    env1=val1
+
+Value of a environment variable env2 with message and size parameters:
+
+::
+
+    => askenv env2 Please type-in a value for env2: 10;echo $?
+    Please type-in a value for env2: 1234567890123
+    0
+    => printenv env2
+    env2=1234567890
+
+Value of a environment variable env3 with size parameter only:
+
+::
+
+    => askenv env3 10;echo $?
+    Please enter 'env3': val3
+    0
+    => printenv env3
+    env3=val3
+
+Return Value of askenv command, when used without any other arguments:
+
+::
+
+    => askenv;echo $?
+    askenv - get environment variables from stdin
+
+    Usage:
+    askenv name [message] [size]
+        - display 'message' and get environment variable 'name' from stdin (max 'size' chars)
+    1
+
+Configuration
+-------------
+
+The askenv command is only available if CMD_ASKENV=y
+
+Return value
+------------
+
+The return value $? is set to 0 (true).
+If no other arguments are specified (along with askenv), it is set to 1 (false).
diff --git a/roms/u-boot/doc/usage/base.rst b/roms/u-boot/doc/usage/base.rst
new file mode 100644
index 000000000..db9cd4d97
--- /dev/null
+++ b/roms/u-boot/doc/usage/base.rst
@@ -0,0 +1,23 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+base command
+============
+
+Synopsis
+--------
+
+::
+
+    base [address]
+
+Description
+-----------
+
+The *base* command sets or displays the address offset used by the memory
+commands *cmp, cp, md, mdc, mm, ms, mw, mwc*.
+
+All other commands ignore the address defined by *base*.
+
+address
+    new base address as hexadecimal number. If no value is provided, the current
+    value is displayed.
diff --git a/roms/u-boot/doc/usage/bootefi.rst b/roms/u-boot/doc/usage/bootefi.rst
new file mode 100644
index 000000000..282f22aac
--- /dev/null
+++ b/roms/u-boot/doc/usage/bootefi.rst
@@ -0,0 +1,135 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright 2020, Heinrich Schuchardt <xypron.glpk@gmx.de>
+
+bootefi command
+===============
+
+Synopsis
+--------
+
+::
+
+    bootefi [image_addr] [fdt_addr]
+    bootefi bootmgr [fdt_addr]
+    bootefi hello [fdt_addr]
+    bootefi selftest [fdt_addr]
+
+Description
+-----------
+
+The *bootefi* command is used to launch a UEFI binary which can be either of
+
+* UEFI application
+* UEFI boot services driver
+* UEFI run-time services driver
+
+An operating system requires a hardware description which can either be
+presented as ACPI table (CONFIG\_GENERATE\_ACPI\_TABLE=y) or as device-tree
+The load address of the device-tree may be provided as parameter *fdt\_addr*. If
+this address is not specified, the bootefi command will try to fall back in
+sequence to:
+
+* the device-tree specified by environment variable *fdt\_addr*
+* the device-tree specified by environment variable *fdtcontroladdr*
+
+The load address of the binary is specified by parameter *image_address*. A
+command sequence to run a UEFI application might look like
+
+::
+
+    load mmc 0:2 $fdt_addr_r dtb
+    load mmc 0:1 $kernel_addr_r /EFI/grub/grubaa64.efi
+    bootefi $kernel_addr_r $fdt_addr_r
+
+The last file loaded defines the image file path in the loaded image protocol.
+Hence the executable should always be loaded last.
+
+The value of the environment variable *bootargs* is converted from UTF-8 to
+UTF-16 and passed as load options in the loaded image protocol to the UEFI
+binary.
+
+Note
+    UEFI binaries that are contained in FIT images are launched via the
+    *bootm* command.
+
+UEFI boot manager
+'''''''''''''''''
+
+The UEFI boot manager is invoked by the *bootefi bootmgr* sub-command.
+Here boot options are defined by UEFI variables with a name consisting of the
+letters *Boot* followed by a four digit hexadecimal number, e.g. *Boot0001* or
+*BootA03E*. The boot variable defines a label, the device path of the binary to
+execute as well as the load options passed in the loaded image protocol.
+
+If the UEFI variable *BootNext* is defined, it specifies the number of the boot
+option to execute next. If no binary can be loaded via *BootNext* the variable
+*BootOrder* specifies in which sequence boot options shalled be tried.
+
+The values of these variables can be managed using the U-Boot command
+*efidebug*.
+
+UEFI hello world application
+''''''''''''''''''''''''''''
+
+U-Boot can be compiled with a hello world application that can be launched using
+the *bootefi hello* sub-command. A session might look like
+
+::
+
+    => setenv bootargs 'Greetings to the world'
+    => bootefi hello
+    Booting /MemoryMapped(0x0,0x10001000,0x1000)
+    Hello, world!
+    Running on UEFI 2.8
+    Have SMBIOS table
+    Have device tree
+    Load options: Greetings to the world
+
+UEFI selftest
+'''''''''''''
+
+U-Boot can be compiled with UEFI unit tests. These unit tests are invoked using
+the *bootefi selftest* sub-command.
+
+Which unit test is executed is controlled by the environment variable
+*efi\_selftest*. If this variable is not set, all unit tests that are not marked
+as 'on request' are executed.
+
+To show a list of the available unit tests the value *list* can be used
+
+::
+
+    => setenv efi_selftest list
+    => bootefi selftest
+
+    Available tests:
+    'block image transfer' - on request
+    'block device'
+    'configuration tables'
+    ...
+
+A single test is selected for execution by setting the *efi\_selftest*
+environment variable to match one of the listed identifiers
+
+::
+
+    => setenv efi_selftest 'block image transfer'
+    => bootefi selftest
+
+Some of the tests execute the ExitBootServices() UEFI boot service and will not
+return to the command line but require a board reset.
+
+Configuration
+-------------
+
+To use the *bootefi* command you must specify CONFIG\_CMD\_BOOTEFI=y.
+The *bootefi hello* sub-command requries CMD\_BOOTEFI\_HELLO=y.
+The *bootefi selftest* sub-command depends on CMD\_BOOTEFI\_SELFTEST=y.
+
+See also
+--------
+
+* *bootm* for launching UEFI binaries packed in FIT images
+* *booti*, *bootm*, *bootz* for launching a Linux kernel without using the
+  UEFI sub-system
+* *efidebug* for setting UEFI boot variables
diff --git a/roms/u-boot/doc/usage/booti.rst b/roms/u-boot/doc/usage/booti.rst
new file mode 100644
index 000000000..d631fb571
--- /dev/null
+++ b/roms/u-boot/doc/usage/booti.rst
@@ -0,0 +1,114 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+booti command
+=============
+
+Synopsis
+--------
+
+::
+
+    booti [<addr> [<initrd>[:<size>]] [<fdt>]]
+
+Description
+-----------
+
+The booti command is used to boot a Linux kernel in flat or compressed
+'Image' format. Which compressed formats are supported is configurable.
+
+addr
+    address of kernel image, defaults to CONFIG_SYS_LOAD_ADDR.
+
+initrd
+    address of the initial RAM disk. Use '-' to boot a kernel with a device
+    tree but without an initial RAM disk.
+
+size
+    size of the initial RAM disk. This parameter must be specified for raw
+    initial RAM disks.
+
+fdt
+    address of the device tree.
+
+To support compressed Image files the following environment variables must be
+set:
+
+kernel_comp_addr_r
+    start of memory area used for decompression
+
+kernel_comp_size
+    size of the compressed file. The value has to be at least the size of
+    loaded image for decompression to succeed. For the booti command the
+    maximum decompressed size is 10 times this value.
+
+Example
+-------
+
+This is the boot log of an Odroid C2 board:
+
+::
+
+    => load mmc 0:1 $fdt_addr_r dtb-5.10.0-3-arm64
+    27530 bytes read in 7 ms (3.7 MiB/s)
+    => load mmc 0:1 $kernel_addr_r vmlinuz-5.10.0-3-arm64
+    26990448 bytes read in 1175 ms (21.9 MiB/s)
+    => load mmc 0:1 $ramdisk_addr_r initrd.img-5.10.0-3-arm64
+    27421776 bytes read in 1209 ms (21.6 MiB/s)
+    => booti $kernel_addr_r $ramdisk_addr_r:$filesize $fdt_addr_r
+    Moving Image from 0x8080000 to 0x8200000, end=9c60000
+    ## Flattened Device Tree blob at 08008000
+       Booting using the fdt blob at 0x8008000
+       Loading Ramdisk to 7a52a000, end 7bf50c50 ... OK
+       Loading Device Tree to 000000007a520000, end 000000007a529b89 ... OK
+
+    Starting kernel ...
+
+The kernel can be compressed with gzip:
+
+.. code-block:: bash
+
+    cd /boot
+    gzip -k vmlinuz-5.10.0-3-arm64
+
+Here is the boot log for the compressed kernel:
+
+::
+
+    => setenv kernel_comp_addr_r 0x50000000
+    => setenv kernel_comp_size 0x04000000
+    => load mmc 0:1 $fdt_addr_r dtb-5.10.0-3-arm64
+    27530 bytes read in 6 ms (4.4 MiB/s)
+    => load mmc 0:1 $kernel_addr_r vmlinuz-5.10.0-3-arm64.gz
+    9267730 bytes read in 402 ms (22 MiB/s)
+    => load mmc 0:1 $ramdisk_addr_r initrd.img-5.10.0-3-arm64
+    27421776 bytes read in 1181 ms (22.1 MiB/s)
+    => booti $kernel_addr_r $ramdisk_addr_r:$filesize $fdt_addr_r
+       Uncompressing Kernel Image
+    Moving Image from 0x8080000 to 0x8200000, end=9c60000
+    ## Flattened Device Tree blob at 08008000
+       Booting using the fdt blob at 0x8008000
+       Loading Ramdisk to 7a52a000, end 7bf50c50 ... OK
+       Loading Device Tree to 000000007a520000, end 000000007a529b89 ... OK
+
+    Starting kernel ...
+
+Configuration
+-------------
+
+The booti command is only available if CONFIG_CMD_BOOTI=y.
+
+Which compression types are supported depends on:
+
+* CONFIG_BZIP2
+* CONFIG_GZIP
+* CONFIG_LZ4
+* CONFIG_LZMA
+* CONFIG_LZO
+* CONFIG_ZSTD
+
+Return value
+------------
+
+Normally this command does not return. If an error occurs, the return value $?
+is set to 1 (false). If the operating system returns to U-Boot, the system is
+reset.
diff --git a/roms/u-boot/doc/usage/bootmenu.rst b/roms/u-boot/doc/usage/bootmenu.rst
new file mode 100644
index 000000000..1f094ad6e
--- /dev/null
+++ b/roms/u-boot/doc/usage/bootmenu.rst
@@ -0,0 +1,95 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. (C) Copyright 2011-2012 Pali Rohár <pali@kernel.org>
+
+bootmenu command
+================
+
+The "bootmenu" command uses U-Boot menu interfaces and provides
+a simple mechanism for creating menus with different boot items.
+The cursor keys "Up" and "Down" are used for navigation through
+the items. Current active menu item is highlighted and can be
+selected using the "Enter" key. The selection of the highlighted
+menu entry invokes an U-Boot command (or a list of commands)
+associated with this menu entry.
+
+The "bootmenu" command interprets ANSI escape sequencies, so
+an ANSI terminal is required for proper menu rendering and item
+selection.
+
+The assembling of the menu is done via a set of environment variables
+"bootmenu_<num>" and "bootmenu_delay", i.e.::
+
+    bootmenu_delay=<delay>
+    bootmenu_<num>="<title>=<commands>"
+
+<delay>
+    is the autoboot delay in seconds, after which the first
+    menu entry will be selected automatically
+
+<num>
+    is the boot menu entry number, starting from zero
+
+<title>
+    is the text of the menu entry shown on the console
+    or on the boot screen
+
+<commands>
+    are commands which will be executed when a menu
+    entry is selected
+
+Title and commands are separated by the first appearance of a '='
+character in the value of the environment variable.
+
+The first (optional) argument of the "bootmenu" command is a delay specifier
+and it overrides the delay value defined by "bootmenu_delay" environment
+variable. If the environment variable "bootmenu_delay" is not set or if
+the argument of the "bootmenu" command is not specified, the default delay
+will be CONFIG_BOOTDELAY. If delay is 0, no menu entries will be shown on
+the console (or on the screen) and the command of the first menu entry will
+be called immediately. If delay is less then 0, bootmenu will be shown and
+autoboot will be disabled.
+
+Bootmenu always adds menu entry "U-Boot console" at the end of all menu
+entries specified by environment variables. When selecting this entry
+the bootmenu terminates and the usual U-Boot command prompt is presented
+to the user.
+
+Example environment::
+
+    setenv bootmenu_0 Boot 1. kernel=bootm 0x82000000  # Set first menu entry
+    setenv bootmenu_1 Boot 2. kernel=bootm 0x83000000  # Set second menu entry
+    setenv bootmenu_2 Reset board=reset                # Set third menu entry
+    setenv bootmenu_3 U-Boot boot order=boot           # Set fourth menu entry
+    bootmenu 20        # Run bootmenu with autoboot delay 20s
+
+
+The above example will be rendered as below::
+
+    *** U-Boot Boot Menu ***
+
+       Boot 1. kernel
+       Boot 2. kernel
+       Reset board
+       U-Boot boot order
+       U-Boot console
+
+    Hit any key to stop autoboot: 20
+    Press UP/DOWN to move, ENTER to select
+
+The selected menu entry will be highlighted - it will have inverted
+background and text colors.
+
+The "bootmenu" cammand is enabled by::
+
+    CONFIG_CMD_BOOTMENU=y
+
+To run the bootmenu at startup add these additional settings::
+
+    CONFIG_AUTOBOOT_KEYED=y
+    CONFIG_BOOTDELAY=30
+    CONFIG_AUTOBOOT_MENU_SHOW=y
+
+When you intend to use the bootmenu on a color frame buffer console,
+make sure to additionally define::
+
+    CONFIG_CFB_CONSOLE_ANSI=y
diff --git a/roms/u-boot/doc/usage/button.rst b/roms/u-boot/doc/usage/button.rst
new file mode 100644
index 000000000..ea4176275
--- /dev/null
+++ b/roms/u-boot/doc/usage/button.rst
@@ -0,0 +1,64 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+button command
+==============
+
+Synopsis
+--------
+
+::
+
+    button list
+    button <name>
+
+Description
+-----------
+
+The button command is used to retrieve the status of a button. To show the
+status of a button with name 'button1' you would issue the command
+
+::
+
+    button button1
+
+The status of the button is both written to the console as *ON* or *OFF* and
+set in the return value variable *$?* as 0 (true) or 1 (false). To retrieve
+the status of a button with name *button1* and to write it to environment
+variable *status1* you would execute the commands
+
+::
+
+    button button1
+    setenv status1 $?
+
+A list of all available buttons and their status can be displayed using
+
+::
+
+    button list
+
+If a button device has not been probed yet, its status will be shown as
+*<inactive>* in the list.
+
+Configuration
+-------------
+
+To use the button command you must specify CONFIG_CMD_BUTTON=y and enable a
+button driver. The available buttons are defined in the device-tree.
+
+Return value
+------------
+
+The variable *$?* takes the following values
+
++---+-----------------------------+
+| 0 | ON, the button is pressed   |
++---+-----------------------------+
+| 1 | OFF, the button is released |
++---+-----------------------------+
+| 0 | button list was shown       |
++---+-----------------------------+
+| 1 | button not found            |
++---+-----------------------------+
+| 1 | invalid arguments           |
++---+-----------------------------+
diff --git a/roms/u-boot/doc/usage/conitrace.rst b/roms/u-boot/doc/usage/conitrace.rst
new file mode 100644
index 000000000..d9916c865
--- /dev/null
+++ b/roms/u-boot/doc/usage/conitrace.rst
@@ -0,0 +1,54 @@
+conitrace command
+=================
+
+Synopsis
+--------
+
+::
+
+    conitrace
+
+Description
+-----------
+
+The conitrace command is used to test the correct function of the console input
+driver. It is especially valuable for checking the support for special keys like
+<F1> or <POS1>.
+
+To display escape sequences on a single line the output only advances to the
+next line after detecting a pause of a few milliseconds.
+
+The output is hexadecimal.
+
+Examples
+--------
+
+Entering keys <B><SHIFT-B><CTRL-B><X>
+
+::
+
+    => conitrace
+    Waiting for your input
+    To terminate type 'x'
+    62
+    42
+    02
+    =>
+
+Entering keys <F1><POS1><DEL><BACKSPACE><X>
+
+::
+
+    => conitrace
+    Waiting for your input
+    To terminate type 'x'
+    1b 4f 50
+    1b 5b 48
+    1b 5b 33 7e
+    7f
+    =>
+
+Configuration
+-------------
+
+The conitrace command is only available if CONFIG_CMD_CONITRACE=y.
diff --git a/roms/u-boot/doc/usage/dfu.rst b/roms/u-boot/doc/usage/dfu.rst
new file mode 100644
index 000000000..11c88072b
--- /dev/null
+++ b/roms/u-boot/doc/usage/dfu.rst
@@ -0,0 +1,404 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Device Firmware Upgrade (DFU)
+=============================
+
+Overview
+--------
+
+The Device Firmware Upgrade (DFU) allows to download and upload firmware
+to/from U-Boot connected over USB.
+
+U-boot follows the Universal Serial Bus Device Class Specification for
+Device Firmware Upgrade Version 1.1 the USB forum (DFU v1.1 in www.usb.org).
+
+U-Boot implements this DFU capability (CONFIG_DFU) with the command dfu
+(cmd/dfu.c / CONFIG_CMD_DFU) based on:
+
+- the DFU stack (common/dfu.c and common/spl/spl_dfu.c), based on the
+  USB DFU download gadget (drivers/usb/gadget/f_dfu.c)
+- The access to mediums is done in DFU backends (driver/dfu)
+
+Today the supported DFU backends are:
+
+- MMC (RAW or FAT / EXT2 / EXT3 / EXT4 file system / SKIP / SCRIPT)
+- NAND
+- RAM
+- SF (serial flash)
+- MTD (all MTD device: NAND, SPI-NOR, SPI-NAND,...)
+- virtual
+
+These DFU backends are also used by
+
+- the dfutftp (see README.dfutftp)
+- the thordown command (cmd/thordown.c and gadget/f_thor.c)
+
+The "virtual" backend is a generic DFU backend to support a board specific
+target (for example OTP), only based on the weak functions:
+
+- dfu_write_medium_virt
+- dfu_get_medium_size_virt
+- dfu_read_medium_virt
+
+Configuration Options
+---------------------
+
+The following configuration option are relevant for device firmware upgrade:
+
+* CONFIG_DFU
+* CONFIG_DFU_OVER_USB
+* CONFIG_DFU_MMC
+* CONFIG_DFU_MTD
+* CONFIG_DFU_NAND
+* CONFIG_DFU_RAM
+* CONFIG_DFU_SF
+* CONFIG_DFU_SF_PART
+* CONFIG_DFU_TIMEOUT
+* CONFIG_DFU_VIRTUAL
+* CONFIG_CMD_DFU
+
+Environment variables
+---------------------
+
+The dfu command uses 3 environments variables:
+
+dfu_alt_info
+    The DFU setting for the USB download gadget with a semicolon separated
+    string of information on each alternate::
+
+        dfu_alt_info="<alt1>;<alt2>;....;<altN>"
+
+    When several devices are used, the format is:
+
+    - <interface> <dev>'='alternate list (';' separated)
+    - each interface is separated by '&'::
+
+        dfu_alt_info=\
+            "<interface1> <dev1>=<alt1>;....;<altN>&"\
+            "<interface2> <dev2>=<altN+1>;....;<altM>&"\
+            ...\
+            "<interfaceI> <devI>=<altY+1>;....;<altZ>&"
+
+dfu_bufsiz
+    size of the DFU buffer, when absent, defaults to
+    CONFIG_SYS_DFU_DATA_BUF_SIZE (8 MiB by default)
+
+dfu_hash_algo
+    name of the hash algorithm to use
+
+Commands
+--------
+
+dfu <USB_controller> [<interface> <dev>] list
+    list the alternate device defined in *dfu_alt_info*
+
+dfu <USB_controller> [<interface> <dev>] [<timeout>]
+    start the dfu stack on the USB instance with the selected medium
+    backend and use the *dfu_alt_info* variable to configure the
+    alternate setting and link each one with the medium
+    The dfu command continue until receive a ^C in console or
+    a DFU detach transaction from HOST. If CONFIG_DFU_TIMEOUT option
+    is enabled and <timeout> parameter is present in the command line,
+    the DFU operation will be aborted automatically after <timeout>
+    seconds of waiting remote to initiate DFU session.
+
+The possible values of <interface> are (with <USB controller> = 0 in the dfu
+command example)
+
+mmc
+    for eMMC and SD card::
+
+        dfu 0 mmc <dev>
+
+    each element in *dfu_alt_info* being
+
+    * <name> raw <offset> <size> [mmcpart <num>]   raw access to mmc device
+    * <name> part <dev> <part_id> [mmcpart <num>]  raw access to partition
+    * <name> fat <dev> <part_id> [mmcpart <num>]   file in FAT partition
+    * <name> ext4 <dev> <part_id> [mmcpart <num>]  file in EXT4 partition
+    * <name> skip 0 0                              ignore flashed data
+    * <name> script 0 0                            execute commands in shell
+
+    with
+
+    partid
+        being the GPT or DOS partition index,
+    num
+         being the eMMC hardware partition number.
+
+    A value of environment variable *dfu_alt_info* for eMMC could be::
+
+        u-boot raw 0x3e 0x800 mmcpart 1;bl2 raw 0x1e 0x1d mmcpart 1
+
+    A value of environment variable *dfu_alt_info* for SD card could be::
+
+        u-boot raw 0x80 0x800;uImage ext4 0 2
+
+    If don't want to flash given image file to storage, use "skip" type
+    entity.
+
+    - It can be used to protect flashing wrong image for the specific board.
+    - Especailly, this layout will be useful when thor protocol is used,
+      which performs flashing in batch mode, where more than one file is
+      processed.
+
+    For example, if one makes a single tar file with support for the two
+    boards with u-boot-<board1>.bin and u-boot-<board2>.bin files, one
+    can use it to flash a proper u-boot image on both without a failure::
+
+        u-boot-<board1>.bin raw 0x80 0x800; u-boot-<board2>.bin skip 0 0
+
+    When flashing new system image requires do some more complex things
+    than just writing data to the storage medium, one can use 'script'
+    type. Data written to such entity will be executed as a command list
+    in the u-boot's shell. This for example allows to re-create partition
+    layout and even set new *dfu_alt_info* for the newly created paritions.
+    Such script would look like::
+
+        setenv dfu_alt_info ...
+        setenv mbr_parts ...
+        mbr write ...
+
+    Please note that this means that user will be able to execute any
+    arbitrary commands just like in the u-boot's shell.
+
+nand
+    raw slc nand device::
+
+         dfu 0 nand <dev>
+
+    each element in *dfu_alt_info* being either of
+
+    * <name> raw <offset> <size>   raw access to mmc device
+    * <name> part <dev> <part_id>  raw acces to partition
+    * <name> partubi <dev> <part_id>  raw acces to ubi partition
+
+    with
+
+    partid
+        is the MTD partition index
+
+ram
+    raw access to ram::
+
+         dfu 0 ram <dev>
+
+    dev
+        is not used for RAM target
+
+    each element in *dfu_alt_info* being::
+
+      <name> ram <offset> <size>  raw access to ram
+
+sf
+    serial flash : NOR::
+
+        cmd: dfu 0 sf <dev>
+
+    each element in *dfu_alt_info* being either of:
+
+    * <name> raw <offset> <size>  raw access to sf device
+    * <name> part <dev> <part_id>  raw acces to partition
+    * <name> partubi <dev> <part_id>  raw acces to ubi partition
+
+    with
+
+    partid
+        is the MTD partition index
+
+mtd
+    all MTD device: NAND, SPI-NOR, SPI-NAND,...::
+
+        cmd: dfu 0 mtd <dev>
+
+    with
+
+    dev
+        the mtd identifier as defined in mtd command
+        (nand0, nor0, spi-nand0,...)
+
+    each element in *dfu_alt_info* being either of:
+
+    * <name> raw <offset> <size> forraw access to mtd device
+    * <name> part <dev> <part_id> for raw acces to partition
+    * <name> partubi <dev> <part_id> for raw acces to ubi partition
+
+    with
+
+    partid
+        is the MTD partition index
+
+virt
+    virtual flash back end for DFU
+
+    ::
+
+        cmd: dfu 0 virt <dev>
+
+    each element in *dfu_alt_info* being:
+
+    * <name>
+
+<interface> and <dev> are absent, the dfu command to use multiple devices::
+
+    cmd: dfu 0 list
+    cmd: dfu 0
+
+*dfu_alt_info* variable provides the list of <interface> <dev> with
+alternate list separated by '&' with the same format for each <alt>::
+
+    mmc <dev>=<alt1>;....;<altN>
+    nand <dev>=<alt1>;....;<altN>
+    ram <dev>=<alt1>;....;<altN>
+    sf <dev>=<alt1>;....;<altN>
+    mtd <dev>=<alt1>;....;<altN>
+    virt <dev>=<alt1>;....;<altN>
+
+Callbacks
+---------
+
+The weak callback functions can be implemented to manage specific behavior
+
+dfu_initiated_callback
+   called when the DFU transaction is started, used to initiase the device
+
+dfu_flush_callback
+    called at the end of the DFU write after DFU manifestation, used to manage
+    the device when DFU transaction is closed
+
+Host tools
+----------
+
+When U-Boot runs the dfu stack, the DFU host tools can be used
+to send/receive firmwares on each configurated alternate.
+
+For example dfu-util is a host side implementation of the DFU 1.1
+specifications(http://dfu-util.sourceforge.net/) which works with U-Boot.
+
+Usage
+-----
+
+Example 1: firmware located in eMMC or SD card, with:
+
+- alternate 1 (alt=1) for SPL partition (GPT partition 1)
+- alternate 2 (alt=2) for U-Boot partition (GPT partition 2)
+
+The U-Boot configuration is::
+
+  U-Boot> env set dfu_alt_info "spl part 0 1;u-boot part 0 2"
+
+  U-Boot> dfu 0 mmc 0 list
+  DFU alt settings list:
+  dev: eMMC alt: 0 name: spl layout: RAW_ADDR
+  dev: eMMC alt: 1 name: u-boot layout: RAW_ADDR
+
+  Boot> dfu 0 mmc 0
+
+On the Host side:
+
+list the available alternate setting::
+
+  $> dfu-util -l
+  dfu-util 0.9
+
+  Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
+  Copyright 2010-2016 Tormod Volden and Stefan Schmidt
+  This program is Free Software and has ABSOLUTELY NO WARRANTY
+  Please report bugs to http://sourceforge.net/p/dfu-util/tickets/
+
+  Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \
+     alt=1, name="u-boot", serial="003A00203438510D36383238"
+  Found DFU: [0483:5720] ver=0200, devnum=45, cfg=1, intf=0, path="3-1.3.1", \
+     alt=0, name="spl", serial="003A00203438510D36383238"
+
+  To download to U-Boot, use -D option
+
+  $> dfu-util -a 0 -D u-boot-spl.bin
+  $> dfu-util -a 1 -D u-boot.bin
+
+  To upload from U-Boot, use -U option
+
+  $> dfu-util -a 0 -U u-boot-spl.bin
+  $> dfu-util -a 1 -U u-boot.bin
+
+  To request a DFU detach and reset the USB connection:
+  $> dfu-util -a 0 -e  -R
+
+
+Example 2: firmware located in NOR (sf) and NAND, with:
+
+- alternate 1 (alt=1) for SPL partition (NOR GPT partition 1)
+- alternate 2 (alt=2) for U-Boot partition (NOR GPT partition 2)
+- alternate 3 (alt=3) for U-Boot-env partition (NOR GPT partition 3)
+- alternate 4 (alt=4) for UBI partition (NAND GPT partition 1)
+
+::
+
+  U-Boot> env set dfu_alt_info \
+  "sf 0:0:10000000:0=spl part 0 1;u-boot part 0 2; \
+  u-boot-env part 0 3&nand 0=UBI partubi 0,1"
+
+  U-Boot> dfu 0 list
+
+  DFU alt settings list:
+  dev: SF alt: 0 name: spl layout: RAW_ADDR
+  dev: SF alt: 1 name: ssbl layout: RAW_ADDR
+  dev: SF alt: 2 name: u-boot-env layout: RAW_ADDR
+  dev: NAND alt: 3 name: UBI layout: RAW_ADDR
+
+  U-Boot> dfu 0
+
+::
+
+  $> dfu-util -l
+  Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
+     intf=0, alt=3, name="UBI", serial="002700333338511934383330"
+  Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
+     intf=0, alt=2, name="u-boot-env", serial="002700333338511934383330"
+  Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
+     intf=0, alt=1, name="u-boot", serial="002700333338511934383330"
+  Found DFU: [0483:5720] ver=9999, devnum=96, cfg=1,\
+     intf=0, alt=0, name="spl", serial="002700333338511934383330"
+
+Same example with MTD backend
+
+::
+
+  U-Boot> env set dfu_alt_info \
+     "mtd nor0=spl part 1;u-boot part 2;u-boot-env part 3&"\
+     "mtd nand0=UBI partubi 1"
+
+  U-Boot> dfu 0 list
+  using id 'nor0,0'
+  using id 'nor0,1'
+  using id 'nor0,2'
+  using id 'nand0,0'
+  DFU alt settings list:
+  dev: MTD alt: 0 name: spl layout: RAW_ADDR
+  dev: MTD alt: 1 name: u-boot layout: RAW_ADDR
+  dev: MTD alt: 2 name: u-boot-env layout: RAW_ADDR
+  dev: MTD alt: 3 name: UBI layout: RAW_ADDR
+
+Example 3
+
+firmware located in SD Card (mmc) and virtual partition on OTP and PMIC not
+volatile memory
+
+- alternate 1 (alt=1) for scard
+- alternate 2 (alt=2) for OTP (virtual)
+- alternate 3 (alt=3) for PMIC NVM (virtual)
+
+::
+
+   U-Boot> env set dfu_alt_info \
+      "mmc 0=sdcard raw 0 0x100000&"\
+      "virt 0=otp" \
+      "virt 1=pmic"
+
+::
+
+   U-Boot> dfu 0 list
+   DFU alt settings list:
+   dev: eMMC alt: 0 name: sdcard layout: RAW_ADDR
+   dev: VIRT alt: 1 name: otp layout: RAW_ADDR
+   dev: VIRT alt: 2 name: pmic layout: RAW_ADDR
diff --git a/roms/u-boot/doc/usage/echo.rst b/roms/u-boot/doc/usage/echo.rst
new file mode 100644
index 000000000..861abdfd1
--- /dev/null
+++ b/roms/u-boot/doc/usage/echo.rst
@@ -0,0 +1,65 @@
+echo command
+============
+
+Synopsis
+--------
+
+::
+
+    echo [-n] [args ...]
+
+Description
+-----------
+
+The echo command prints its arguments to the console separated by spaces.
+
+-n
+    Do not print a line feed after the last argument.
+
+args
+    Arguments to be printed. The arguments are evaluated before being passed to
+    the command.
+
+Examples
+--------
+
+Strings are parsed before the arguments are passed to the echo command:
+
+::
+
+    => echo "a" 'b' c
+    a b c
+    =>
+
+Observe how variables included in strings are handled:
+
+::
+
+    => setenv var X; echo "a)" ${var} 'b)' '${var}' c) ${var}
+    a) X b) ${var} c) X
+    =>
+
+
+-n suppresses the line feed:
+
+::
+
+    => echo -n 1 2 3; echo a b c
+    1 2 3a b c
+    => echo -n 1 2 3
+    1 2 3=>
+
+A more complex example:
+
+::
+
+    => for i in a b c; do for j in 1 2 3; do echo -n "${i}${j}, "; done; echo; done;
+    a1, a2, a3,
+    b1, b2, b3,
+    c1, c2, c3,
+    =>
+
+Return value
+------------
+
+The return value $? is always set to 0 (true).
diff --git a/roms/u-boot/doc/usage/exception.rst b/roms/u-boot/doc/usage/exception.rst
new file mode 100644
index 000000000..27df88bd5
--- /dev/null
+++ b/roms/u-boot/doc/usage/exception.rst
@@ -0,0 +1,66 @@
+exception command
+=================
+
+Synopsis
+--------
+
+::
+
+    exception <type>
+
+Description
+-----------
+
+The exception command is used to test the handling of exceptions like undefined
+instructions, segmentation faults or alignment faults.
+
+type
+  type of exception to be generated. The available types are architecture
+  dependent. Use 'help exception' to determine which are available.
+
+  **ARM:**
+
+  breakpoint
+    prefetch abort
+
+  unaligned
+    data abort
+
+  undefined
+    undefined instruction
+
+  **RISC-V:**
+
+  ebreak
+    breakpoint exception
+
+  unaligned
+    load address misaligned
+
+  undefined
+    undefined instruction
+
+  **Sandbox:**
+
+  sigsegv
+    illegal memory access
+
+  undefined
+    undefined instruction
+
+  **x86:**
+
+  undefined
+    undefined instruction
+
+Examples
+--------
+
+::
+
+    => exception undefined
+
+    Illegal instruction
+    pc = 0x56076dd1a0f9, pc_reloc = 0x540f9
+
+    resetting ...
diff --git a/roms/u-boot/doc/usage/exit.rst b/roms/u-boot/doc/usage/exit.rst
new file mode 100644
index 000000000..769223c47
--- /dev/null
+++ b/roms/u-boot/doc/usage/exit.rst
@@ -0,0 +1,40 @@
+exit command
+============
+
+Synopsis
+--------
+
+::
+
+    exit
+
+Description
+-----------
+
+The exit command terminates a script started via the run or source command.
+If scripts are nested, only the innermost script is left.
+
+::
+
+    => setenv inner 'echo entry inner; exit; echo inner done'
+    => setenv outer 'echo entry outer; run inner; echo outer done'
+    => run outer
+    entry outer
+    entry inner
+    outer done
+    =>
+
+When executed outside a script a warning is written. Following commands are not
+executed.
+
+::
+
+    => echo first; exit; echo last
+    first
+    exit not allowed from main input shell.
+    =>
+
+Return value
+------------
+
+$? is always set to 0 (true).
diff --git a/roms/u-boot/doc/usage/extension.rst b/roms/u-boot/doc/usage/extension.rst
new file mode 100644
index 000000000..2b88398b1
--- /dev/null
+++ b/roms/u-boot/doc/usage/extension.rst
@@ -0,0 +1,111 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright 2021, Kory Maincent <kory.maincent@bootlin.com>
+
+U-Boot extension board usage (CONFIG_EXTENSION)
+===============================================
+
+Synopsis
+--------
+
+::
+
+    extension scan
+    extension list
+    extension apply <extension number|all>
+
+Description
+-----------
+
+The "extension" command proposes a generic U-Boot mechanism to detect
+extension boards connected to the HW platform, and apply the appropriate
+Device Tree overlays depending on the detected extension boards.
+
+The "extension" command comes with three sub-commands:
+
+ - "extension scan" makes the generic code call the board-specific
+   extension_board_scan() function to retrieve the list of detected
+   extension boards.
+
+ - "extension list" allows to list the detected extension boards.
+
+ - "extension apply <number>|all" allows to apply the Device Tree
+   overlay(s) corresponding to one, or all, extension boards
+
+The latter requires two environment variables to exist:
+
+ - extension_overlay_addr: the RAM address where to load the Device
+   Tree overlays
+
+ - extension_overlay_cmd: the U-Boot command to load one overlay.
+   Indeed, the location and mechanism to load DT overlays is very setup
+   specific.
+
+In order to enable this mechanism, board-specific code must implement
+the extension_board_scan() function that fills in a linked list of
+"struct extension", each describing one extension board. In addition,
+the board-specific code must select the SUPPORT_EXTENSION_SCAN Kconfig
+boolean.
+
+Usage example
+-------------
+
+1. Make sure your devicetree is loaded and set as the working fdt tree.
+
+::
+
+    => run loadfdt
+    => fdt addr $fdtaddr
+
+2. Prepare the environment variables
+
+::
+
+    => setenv extension_overlay_addr 0x88080000
+    => setenv extension_overlay_cmd 'load mmc 0:1 ${extension_overlay_addr} /boot/${extension_overlay_name}'
+
+3. Detect the plugged extension board
+
+::
+
+    => extension scan
+
+4. List the plugged extension board information and the devicetree
+   overlay name
+
+::
+
+    => extension list
+
+5. Apply the appropriate devicetree overlay
+
+For apply the selected overlay:
+
+::
+
+    => extension apply 0
+
+For apply all the overlays:
+
+::
+
+    => extension apply all
+
+Simple extension_board_scan function example
+--------------------------------------------
+
+.. code-block:: c
+
+    int extension_board_scan(struct list_head *extension_list)
+    {
+        struct extension *extension;
+
+        extension = calloc(1, sizeof(struct extension));
+        snprintf(extension->overlay, sizeof(extension->overlay), "overlay.dtbo");
+        snprintf(extension->name, sizeof(extension->name), "extension board");
+        snprintf(extension->owner, sizeof(extension->owner), "sandbox");
+        snprintf(extension->version, sizeof(extension->version), "1.1");
+        snprintf(extension->other, sizeof(extension->other), "Extension board information");
+        list_add_tail(&extension->list, extension_list);
+
+        return 1;
+    }
diff --git a/roms/u-boot/doc/usage/false.rst b/roms/u-boot/doc/usage/false.rst
new file mode 100644
index 000000000..a17fe8602
--- /dev/null
+++ b/roms/u-boot/doc/usage/false.rst
@@ -0,0 +1,28 @@
+false command
+=============
+
+Synopsis
+--------
+
+::
+
+    false
+
+Description
+-----------
+
+The false command sets the return value $? to 1 (false).
+
+Example
+-------
+
+::
+
+    => false; echo $?
+    1
+    =>
+
+Configuration
+-------------
+
+The false command is only available if CONFIG_HUSH_PARSER=y.
diff --git a/roms/u-boot/doc/usage/fatinfo.rst b/roms/u-boot/doc/usage/fatinfo.rst
new file mode 100644
index 000000000..af2eba434
--- /dev/null
+++ b/roms/u-boot/doc/usage/fatinfo.rst
@@ -0,0 +1,51 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+fatinfo command
+===============
+
+Synopsis
+--------
+
+::
+
+    fatinfo <interface> <dev[:part]>
+
+Description
+-----------
+
+The fatinfo command displays information about a FAT partition.
+
+interface
+    interface for accessing the block device (mmc, sata, scsi, usb, ....)
+
+dev
+    device number
+
+part
+    partition number, defaults to 1
+
+Example
+-------
+
+Here is the output for a partition on a 32 GB SD-Card:
+
+::
+
+    => fatinfo mmc 0:1
+    Interface:  MMC
+      Device 0: Vendor: Man 00001b Snr 97560602 Rev: 13.8 Prod: EB1QT0
+                Type: Removable Hard Disk
+                Capacity: 30528.0 MB = 29.8 GB (62521344 x 512)
+    Filesystem: FAT32 "MYDISK     "
+    =>
+
+Configuration
+-------------
+
+The fatinfo command is only available if CONFIG_CMD_FAT=y.
+
+Return value
+------------
+
+The return value $? is set to 0 (true) if the partition is a FAT partition.
+Otherwise it is set to 1 (false).
diff --git a/roms/u-boot/doc/usage/fdt_overlays.rst b/roms/u-boot/doc/usage/fdt_overlays.rst
new file mode 100644
index 000000000..ea3971343
--- /dev/null
+++ b/roms/u-boot/doc/usage/fdt_overlays.rst
@@ -0,0 +1,134 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright (c) 2017, Pantelis Antoniou <pantelis.antoniou@konsulko.com>
+
+Device Tree Overlays
+====================
+
+Overlay Syntax
+--------------
+
+Device-tree overlays require a slightly different syntax compared to traditional
+device-trees. Please refer to dt-object-internal.txt in the device-tree compiler
+sources for information regarding the internal format of overlays:
+https://git.kernel.org/pub/scm/utils/dtc/dtc.git/tree/Documentation/dt-object-internal.txt
+
+Building Overlays
+-----------------
+
+In a nutshell overlays provides a means to manipulate a symbol a previous
+device-tree or device-tree overlay has defined. It requires both the base
+device-tree and all the overlays to be compiled with the *-@* command line
+switch of the device-tree compiler so that symbol information is included.
+
+Note
+    Support for *-@* option can only be found in dtc version 1.4.4 or newer.
+    Only version 4.14 or higher of the Linux kernel includes a built in version
+    of dtc that meets this requirement.
+
+Building a binary device-tree overlay follows the same process as building a
+traditional binary device-tree. For example:
+
+**base.dts**
+
+::
+
+	/dts-v1/;
+	/ {
+		foo: foonode {
+			foo-property;
+		};
+	};
+
+.. code-block:: console
+
+	$ dtc -@ -I dts -O dtb -o base.dtb base.dts
+
+**overlay.dts**
+
+::
+
+	/dts-v1/;
+	/plugin/;
+	/ {
+		fragment@1 {
+			target = <&foo>;
+			__overlay__ {
+				overlay-1-property;
+				bar: barnode {
+					bar-property;
+				};
+			};
+		};
+	};
+
+.. code-block:: console
+
+	$ dtc -@ -I dts -O dtb -o overlay.dtbo overlay.dts
+
+Ways to Utilize Overlays in U-Boot
+----------------------------------
+
+There are two ways to apply overlays in U-Boot.
+
+* Include and define overlays within a FIT image and have overlays
+  automatically applied.
+
+* Manually load and apply overlays
+
+The remainder of this document will discuss using overlays via the manual
+approach. For information on using overlays as part of a FIT image please see:
+doc/uImage.FIT/overlay-fdt-boot.txt
+
+Manually Loading and Applying Overlays
+--------------------------------------
+
+1. Figure out where to place both the base device tree blob and the
+   overlay. Make sure you have enough space to grow the base tree without
+   overlapping anything.
+
+::
+
+    => setenv fdtaddr 0x87f00000
+    => setenv fdtovaddr 0x87fc0000
+
+2. Load the base binary device-tree and the binary device-tree overlay.
+
+::
+
+    => load ${devtype} ${bootpart} ${fdtaddr} ${bootdir}/base.dtb
+    => load ${devtype} ${bootpart} ${fdtovaddr} ${bootdir}/overlay.dtbo
+
+3. Set the base binary device-tree as the working fdt tree.
+
+::
+
+    => fdtaddr $fdtaddr
+
+4. Grow it enough so it can encompass all applied overlays
+
+::
+
+    => fdt resize 8192
+
+5. You are now ready to apply the overlay.
+
+::
+
+    => fdt apply $fdtovaddr
+
+6. Boot system like you would do with a traditional dtb.
+
+For bootm:
+
+::
+
+    => bootm ${kerneladdr} - ${fdtaddr}
+
+For bootz:
+
+::
+
+    => bootz ${kerneladdr} - ${fdtaddr}
+
+Please note that in case of an error, both the base and overlays are going
+to be invalidated, so keep copies to avoid reloading.
diff --git a/roms/u-boot/doc/usage/fit.rst b/roms/u-boot/doc/usage/fit.rst
new file mode 100644
index 000000000..703743405
--- /dev/null
+++ b/roms/u-boot/doc/usage/fit.rst
@@ -0,0 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+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
diff --git a/roms/u-boot/doc/usage/for.rst b/roms/u-boot/doc/usage/for.rst
new file mode 100644
index 000000000..f9e504979
--- /dev/null
+++ b/roms/u-boot/doc/usage/for.rst
@@ -0,0 +1,65 @@
+for command
+===========
+
+Synopis
+-------
+
+::
+
+    for <variable> in <items>; do <commands>; done
+
+Description
+-----------
+
+The for command is used to loop over a list of values and execute a series of
+commands for each of these.
+
+The counter variable of the loop is a shell variable. Please, keep in mind that
+an environment variable takes precedence over a shell variable of the same name.
+
+variable
+    name of the counter variable
+
+items
+    space separated item list
+
+commands
+    commands to execute
+
+Example
+-------
+
+::
+
+    => setenv c
+    => for c in 1 2 3; do echo item ${c}; done
+    item 1
+    item 2
+    item 3
+    => echo ${c}
+    3
+    => setenv c x
+    => for c in 1 2 3; do echo item ${c}; done
+    item x
+    item x
+    item x
+    =>
+
+The first line ensures that there is no environment variable *c*. Hence in the
+first loop the shell variable *c* is printed.
+
+After defining an environment variable of name *c* it takes precedence over the
+shell variable and the environment variable is printed.
+
+Return value
+------------
+
+The return value $? after the done statement is the return value of the last
+statement executed in the loop.
+
+::
+
+    => for i in true false; do ${i}; done; echo $?
+    1
+    => for i in false true; do ${i}; done; echo $?
+    0
diff --git a/roms/u-boot/doc/usage/index.rst b/roms/u-boot/doc/usage/index.rst
new file mode 100644
index 000000000..40b796a3a
--- /dev/null
+++ b/roms/u-boot/doc/usage/index.rst
@@ -0,0 +1,48 @@
+Use U-Boot
+==========
+
+.. toctree::
+   :maxdepth: 1
+
+   dfu
+   fdt_overlays
+   fit
+   netconsole
+   partitions
+
+Shell commands
+--------------
+
+.. toctree::
+   :maxdepth: 1
+
+   addrmap
+   askenv
+   base
+   bootefi
+   booti
+   bootmenu
+   button
+   x86/cbsysinfo
+   conitrace
+   echo
+   exception
+   extension
+   exit
+   false
+   fatinfo
+   for
+   load
+   loady
+   mbr
+   md
+   mmc
+   pinmux
+   pstore
+   qfw
+   reset
+   sbi
+   scp03
+   size
+   true
+   ums
diff --git a/roms/u-boot/doc/usage/load.rst b/roms/u-boot/doc/usage/load.rst
new file mode 100644
index 000000000..1efee7731
--- /dev/null
+++ b/roms/u-boot/doc/usage/load.rst
@@ -0,0 +1,74 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+load command
+============
+
+Synopsis
+--------
+
+::
+
+    load <interface> [<dev[:part]> [<addr> [<filename> [bytes [pos]]]]]
+
+Description
+-----------
+
+The load command is used to read a file from a filesystem into memory.
+
+The number of transferred bytes is saved in the environment variable filesize.
+The load address is saved in the environment variable fileaddr.
+
+interface
+    interface for accessing the block device (mmc, sata, scsi, usb, ....)
+
+dev
+    device number
+
+part
+    partition number, defaults to 0 (whole device)
+
+addr
+    load address, defaults to environment variable loadaddr or if loadaddr is
+    not set to configuration variable CONFIG_SYS_LOAD_ADDR
+
+filename
+    path to file, defaults to environment variable bootfile
+
+bytes
+    maximum number of bytes to load
+
+pos
+    number of bytes to skip
+
+addr, bytes, pos are hexadecimal numbers.
+
+Example
+-------
+
+::
+
+    => load mmc 0:1 ${kernel_addr_r} snp.efi
+    149280 bytes read in 11 ms (12.9 MiB/s)
+    =>
+    => load mmc 0:1 ${kernel_addr_r} snp.efi 1000000
+    149280 bytes read in 9 ms (15.8 MiB/s)
+    =>
+    => load mmc 0:1 ${kernel_addr_r} snp.efi 1000000 100
+    149024 bytes read in 10 ms (14.2 MiB/s)
+    =>
+    => load mmc 0:1 ${kernel_addr_r} snp.efi 10
+    16 bytes read in 1 ms (15.6 KiB/s)
+    =>
+
+Configuration
+-------------
+
+The load command is only available if CONFIG_CMD_FS_GENERIC=y.
+
+Return value
+------------
+
+The return value $? is set to 0 (true) if the file was successfully loaded
+even if the number of bytes is less then the specified length.
+
+If an error occurs, the return value $? is set to 1 (false).
diff --git a/roms/u-boot/doc/usage/loady.rst b/roms/u-boot/doc/usage/loady.rst
new file mode 100644
index 000000000..2819cc72a
--- /dev/null
+++ b/roms/u-boot/doc/usage/loady.rst
@@ -0,0 +1,67 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+loady command
+=============
+
+Synopsis
+--------
+
+::
+
+    loady [addr [baud]]
+
+Description
+-----------
+
+The loady command is used to transfer a file to the device via the serial line
+using the YMODEM protocol.
+
+The number of transferred bytes is saved in environment variable filesize.
+
+addr
+    load address, defaults to environment variable loadaddr or if loadaddr is
+    not set to configuration variable CONFIG_SYS_LOAD_ADDR
+
+baud
+    baud rate for the ymodem transmission. After the transmission the baud
+    rate is reset to the original value.
+
+Example
+-------
+
+In the example below the terminal emulation program picocom was used to
+transfer a file to the device.
+
+After entering the loady command the key sequence <CTRL-A><CTRL-S> is used to
+let picocom prompt for the file name. Picocom invokes the program sz for the
+file transfer.
+
+::
+
+    => loady 80064000 115200
+    ## Ready for binary (ymodem) download to 0x80064000 at 115200 bps...
+    C
+    *** file: BOOTRISCV64.EFI
+    $ sz -b -vv BOOTRISCV64.EFI
+    Sending: BOOTRISCV64.EFI
+    Bytes Sent: 398976   BPS:7883
+    Sending:
+    Ymodem sectors/kbytes sent:   0/ 0k
+    Transfer complete
+
+    *** exit status: 0 ***
+    /1(CAN) packets, 4 retries
+    ## Total Size      = 0x0006165f = 398943 Bytes
+    => echo ${filesize}
+    6165f
+    =>
+
+Configuration
+-------------
+
+The command is only available if CONFIG_CMD_LOADB=y.
+
+Return value
+------------
+
+The return value $? is always 0 (true).
diff --git a/roms/u-boot/doc/usage/mbr.rst b/roms/u-boot/doc/usage/mbr.rst
new file mode 100644
index 000000000..bddf2f612
--- /dev/null
+++ b/roms/u-boot/doc/usage/mbr.rst
@@ -0,0 +1,94 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+mbr command
+===========
+
+Synopsis
+--------
+
+::
+
+    mbr verify [interface] [device no] [partition list]
+    mbr write [interface] [device no] [partition list]
+
+Description
+-----------
+
+The mbr command lets users create or verify the MBR (Master Boot Record)
+partition layout based on the provided text description. The partition
+layout is alternatively read from the 'mbr_parts' environment variable.
+This can be used in scripts to help system image flashing tools to ensure
+proper partition layout.
+
+The syntax of the text description of the partition list is similar to
+the one used by the 'gpt' command.
+
+Supported partition parameters are:
+
+* name (currently ignored)
+* start (partition start offset in bytes)
+* size (in bytes or '-' to expand it to the whole free area)
+* bootable (boolean flag)
+* id (MBR partition type)
+
+If one wants to create more than 4 partitions, an 'Extended' primary
+partition (with 0x05 ID) has to be explicitly provided as a one of the
+first 4 entries.
+
+Here is an example how to create a 6 partitions (3 on the 'extended
+volume'), some of the predefined sizes:
+
+::
+
+    => setenv mbr_parts 'name=boot,start=4M,size=128M,bootable,id=0x0e;
+        name=rootfs,size=3072M,id=0x83;
+        name=system-data,size=512M,id=0x83;
+        name=[ext],size=-,id=0x05;
+        name=user,size=-,id=0x83;
+        name=modules,size=100M,id=0x83;
+        name=ramdisk,size=8M,id=0x83'
+    => mbr write mmc 0
+
+To check if the layout on the MMC #0 storage device matches the provided
+text description one has to issue following command (assuming that
+mbr_parts environment variable is set):
+
+::
+
+    => mbr verify mmc 0
+
+The verify sub-command is especially useful in the system update scripts:
+
+::
+
+    => if mbr verify mmc 0; then
+         echo MBR layout needs to be updated
+         ...
+       fi
+
+The 'mbr write' command returns 0 on success write or 1 on failure.
+
+The 'mbr verify' returns 0 if the layout matches the one on the storage
+device or 1 if not.
+
+Configuration
+-------------
+
+To use the mbr command you must specify CONFIG_CMD_MBR=y.
+
+Return value
+------------
+
+The variable *$?* takes the following values
+
++---+------------------------------+
+| 0 | mbr write was succesful      |
++---+------------------------------+
+| 1 | mbr write failed             |
++---+------------------------------+
+| 0 | mbr verify was succesful     |
++---+------------------------------+
+| 1 | mbr verify was not succesful |
++---+------------------------------+
+|-1 | invalid arguments            |
++---+------------------------------+
diff --git a/roms/u-boot/doc/usage/md.rst b/roms/u-boot/doc/usage/md.rst
new file mode 100644
index 000000000..4c1073ea3
--- /dev/null
+++ b/roms/u-boot/doc/usage/md.rst
@@ -0,0 +1,106 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+md command
+==========
+
+Synopis
+-------
+
+::
+
+    md <address>[<data_size>] [<length>]
+
+Description
+-----------
+
+The md command is used to dump the contents of memory. It uses a standard
+format that includes the address, hex data and ASCII display. It supports
+various data sizes and uses the endianness of the target.
+
+The specified data_size and length become the defaults for future memory
+commands commands.
+
+address
+    start address to display
+
+data_size
+    size of each value to display (defaults to .l):
+
+    =========  ===================
+    data_size  Output size
+    =========  ===================
+    .b         byte
+    .w         word (16 bits)
+    .l         long (32 bits)
+    .q         quadword (64 bits)
+    =========  ===================
+
+length
+    number of values to dump. Defaults to 40 (0d64). Note that this is not
+    the same as the number of bytes, unless .b is used.
+
+Note that the format of 'md.b' can be emulated from linux with::
+
+    # This works but requires using sed to get the extra spaces
+    # <addr> is the address, <f> is the filename
+    xxd -o <addr> -g1 <f> |sed 's/  /    /' >bad
+
+    # This uses a single tool but the offset always starts at 0
+    # <f> is the filename
+    hexdump -v -e '"%08.8_ax: " 16/1 "%02x " "    "' -e '16/1 "%_p" "\n" ' <f>
+
+
+Example
+-------
+
+::
+
+    => md 10000
+    00010000: 00010000 00000000 f0f30f00 00005596    .............U..
+    00010010: 10011010 00000000 10011010 00000000    ................
+    00010020: 10011050 00000000 b96d4cd8 00007fff    P........Lm.....
+    00010030: 00000000 00000000 f0f30f18 00005596    .............U..
+    00010040: 10011040 00000000 10011040 00000000    @.......@.......
+    00010050: b96d4cd8 00007fff 10011020 00000000    .Lm..... .......
+    00010060: 00000003 000000c3 00000000 00000000    ................
+    00010070: 00000000 00000000 f0e892f3 00005596    .............U..
+    00010080: 00000000 000000a1 00000000 00000000    ................
+    00010090: 00000000 00000000 f0e38aa6 00005596    .............U..
+    000100a0: 00000000 000000a6 00000022 00000000    ........".......
+    000100b0: 00000001 00000000 f0e38aa1 00005596    .............U..
+    000100c0: 00000000 000000be 00000000 00000000    ................
+    000100d0: 00000000 00000000 00000000 00000000    ................
+    000100e0: 00000000 00000000 00000000 00000000    ................
+    000100f0: 00000000 00000000 00000000 00000000    ................
+    => md.b 10000
+    00010000: 00 00 01 00 00 00 00 00 00 0f f3 f0 96 55 00 00    .............U..
+    00010010: 10 10 01 10 00 00 00 00 10 10 01 10 00 00 00 00    ................
+    00010020: 50 10 01 10 00 00 00 00 d8 4c 6d b9 ff 7f 00 00    P........Lm.....
+    00010030: 00 00 00 00 00 00 00 00 18 0f f3 f0 96 55 00 00    .............U..
+    => md.b 10000 10
+    00010000: 00 00 01 00 00 00 00 00 00 0f f3 f0 96 55 00 00    .............U..
+    =>
+    00010010: 10 10 01 10 00 00 00 00 10 10 01 10 00 00 00 00    ................
+    =>
+    00010020: 50 10 01 10 00 00 00 00 d8 4c 6d b9 ff 7f 00 00    P........Lm.....
+    =>
+    => md.q 10000
+    00010000: 0000000000010000 00005596f0f30f00    .............U..
+    00010010: 0000000010011010 0000000010011010    ................
+    00010020: 0000000010011050 00007fffb96d4cd8    P........Lm.....
+    00010030: 0000000000000000 00005596f0f30f18    .............U..
+    00010040: 0000000010011040 0000000010011040    @.......@.......
+    00010050: 00007fffb96d4cd8 0000000010011020    .Lm..... .......
+    00010060: 000000c300000003 0000000000000000    ................
+    00010070: 0000000000000000 00005596f0e892f3    .............U..
+
+The empty commands cause a 'repeat', so that md shows the next available data
+in the same format as before.
+
+
+Return value
+------------
+
+The return value $? is always 0 (true).
+
+
diff --git a/roms/u-boot/doc/usage/mmc.rst b/roms/u-boot/doc/usage/mmc.rst
new file mode 100644
index 000000000..f20efe3d7
--- /dev/null
+++ b/roms/u-boot/doc/usage/mmc.rst
@@ -0,0 +1,215 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+mmc command
+============
+
+Synopsis
+--------
+
+::
+
+    mmc info
+    mmc read addr blk# cnt
+    mmc write addr blk# cnt
+    mmc erase blk# cnt
+    mmc rescan
+    mmc part
+    mmc dev [dev] [part]
+    mmc list
+    mmc wp
+    mmc bootbus <dev> <boot_bus_width> <reset_boot_bus_width> <boot_mode>
+    mmc bootpart-resize <dev> <dev part size MB> <RPMB part size MB>
+    mmc partconf <dev> [[varname] | [<boot_ack> <boot_partition> <partition_access>]]
+    mmc rst-function <dev> <value>
+
+Description
+-----------
+
+The mmc command is used to control MMC(eMMC/SD) device.
+
+The 'mmc info' command displays information (Manufacturer ID, OEM, Name, Bus Speed, Mode, ...) of MMC device.
+
+The 'mmc read' command reads raw data to memory address from MMC device with block offset and count.
+
+The 'mmc write' command writes raw data to MMC device from memory address with block offset and count.
+
+    addr
+        memory address
+    blk#
+        start block offset
+    cnt
+        block count
+
+The 'mmc erase' command erases *cnt* blocks on the MMC device starting at block *blk#*.
+
+    blk#
+        start block offset
+    cnt
+        block count
+
+The 'mmc rescan' command scans the available MMC device.
+
+The 'mmc part' command displays the list available partition on current mmc device.
+
+The 'mmc dev' command shows or set current mmc device.
+
+    dev
+        device number to change
+    part
+        partition number to change
+
+The 'mmc list' command displays the list available devices.
+
+The 'mmc wp' command enables "power on write protect" function for boot partitions.
+
+The 'mmc bootbus' command sets the BOOT_BUS_WIDTH field. (*Refer to eMMC specification*)
+
+    boot_bus_width
+        0x0
+            x1 (sdr) or x4(ddr) buswidth in boot operation mode (default)
+        0x1
+            x4 (sdr/ddr) buswidth in boot operation mode
+        0x2
+            x8 (sdr/ddr) buswidth in boot operation mode
+        0x3
+            Reserved
+
+    reset_boot_bus_width
+        0x0
+            Reset buswidth to x1, Single data reate and backward compatible timing after boot operation (default)
+        0x1
+            Retain BOOT_BUS_WIDTH and BOOT_MODE value after boot operation. This is relevant to Push-pull mode operation only
+
+    boot_mode
+        0x0
+            Use single data rate + backward compatible timing in boot operation (default)
+        0x1
+            Use single data rate + High Speed timing in boot operation mode
+        0x2
+            Use dual data rate in boot operation
+        0x3
+            Reserved
+
+The 'mmc partconf' command shows or changes PARTITION_CONFIG field.
+
+    varname
+        When showing the PARTITION_CONFIG, an optional environment variable to store the current boot_partition value into.
+    boot_ack
+        boot acknowledge value
+    boot_partition
+        boot partition to enable for boot
+            0x0
+                Device not boot enabled(default)
+            0x1
+                Boot partition1 enabled for boot
+            0x2
+                Boot partition2 enabled for boot
+            0x7
+                User area enabled for boot
+            others
+                Reserved
+    partition_access
+        partitions to access
+
+The 'mmc bootpart-resize' command changes sizes of boot and RPMB partitions.
+
+    dev
+        device number
+    boot part size MB
+        target size of boot partition
+    RPMB part size MB
+        target size of RPMB partition
+
+The 'mmc rst-function' command changes the RST_n_FUNCTION field.
+**WARNING** : This is a write-once field. (*Refer to eMMC specification*)
+
+    value
+        0x0
+            RST_n signal is temporarily disabled (default)
+        0x1
+            RST_n signal is permanently enabled
+        0x2
+            RST_n signal is permanently disabled
+        0x3
+            Reserved
+
+
+Examples
+--------
+
+The 'mmc info' command displays device's capabilities:
+::
+
+    => mmc info
+    Device: EXYNOS DWMMC
+    Manufacturer ID: 45
+    OEM: 100
+    Name: SDW16
+    Bus Speed: 52000000
+    Mode: MMC DDR52 (52MHz)
+    Rd Block Len: 512
+    MMC version 5.0
+    High Capacity: Yes
+    Capacity: 14.7 GiB
+    Bus Width: 8-bit DDR
+    Erase Group Size: 512 KiB
+    HC WP Group Size: 8 MiB
+    User Capacity: 14.7 GiB WRREL
+    Boot Capacity: 4 MiB ENH
+    RPMB Capacity: 4 MiB ENH
+    Boot area 0 is not write protected
+    Boot area 1 is not write protected
+
+The raw data can be read/written via 'mmc read/write' command:
+::
+
+    => mmc read 0x40000000 0x5000 0x100
+    MMC read: dev # 0, block # 20480, count 256 ... 256 blocks read: OK
+
+    => mmc write 0x40000000 0x5000 0x10
+    MMC write: dev # 0, block # 20480, count 256 ... 256 blocks written: OK
+
+The partition list can be shown via 'mmc part' command:
+::
+
+    => mmc part
+    Partition Map for MMC device 0  --   Partition Type: DOS
+
+    Part    Start Sector    Num Sectors     UUID            Type
+      1     8192            131072          dff8751a-01     0e Boot
+      2     139264          6291456         dff8751a-02     83
+      3     6430720         1048576         dff8751a-03     83
+      4     7479296         23298048        dff8751a-04     05 Extd
+      5     7481344         307200          dff8751a-05     83
+      6     7790592         65536           dff8751a-06     83
+      7     7858176         16384           dff8751a-07     83
+      8     7876608         22900736        dff8751a-08     83
+
+The current device can be shown or set via 'mmc dev' command:
+::
+
+    => mmc dev
+    switch to partitions #0, OK
+    mmc0(part0) is current device
+    => mmc dev 2 0
+    switch to partitions #0, OK
+    mmc2 is current device
+
+The list of available devices can be shown via 'mmc list' command:
+::
+
+    => mmc list
+    mmc list
+    EXYNOS DWMMC: 0 (eMMC)
+    EXYNOS DWMMC: 2 (SD)
+
+Configuration
+-------------
+
+The mmc command is only available if CONFIG_CMD_MMC=y.
+Some commands need to enable more configuration.
+
+write, erase
+    CONFIG_MMC_WRITE
+bootbus, bootpart-resize, partconf, rst-function
+    CONFIG_SUPPORT_EMMC_BOOT=y
diff --git a/roms/u-boot/doc/usage/netconsole.rst b/roms/u-boot/doc/usage/netconsole.rst
new file mode 100644
index 000000000..0156f0212
--- /dev/null
+++ b/roms/u-boot/doc/usage/netconsole.rst
@@ -0,0 +1,109 @@
+Network console
+===============
+
+In U-Boot, we implemented the networked console via the standard
+"devices" mechanism, which means that you can switch between the
+serial and network input/output devices by adjusting the 'stdin' and
+'stdout' environment variables. To switch to the networked console,
+set either of these variables to "nc". Input and output can be
+switched independently.
+
+The default buffer size can be overridden by setting
+CONFIG_NETCONSOLE_BUFFER_SIZE.
+
+We use an environment variable 'ncip' to set the IP address and the
+port of the destination. The format is <ip_addr>:<port>. If <port> is
+omitted, the value of 6666 is used. If the env var doesn't exist, the
+broadcast address and port 6666 are used. If it is set to an IP
+address of 0 (or 0.0.0.0) then no messages are sent to the network.
+The source / listening port can be configured separately by setting
+the 'ncinport' environment variable and the destination port can be
+configured by setting the 'ncoutport' environment variable.
+
+For example, if your server IP is 192.168.1.1, you could use::
+
+	=> setenv nc 'setenv stdout nc;setenv stdin nc'
+	=> setenv ncip 192.168.1.1
+	=> saveenv
+	=> run nc
+
+On the host side, please use this script to access the console
+
+.. code-block:: bash
+
+	tools/netconsole <ip> [port]
+
+The script uses netcat to talk to the board over UDP.  It requires you to
+specify the target IP address (or host name, assuming DNS is working). The
+script can be interrupted by pressing ^T (CTRL-T).
+
+Be aware that in some distributives (Fedora Core 5 at least)
+usage of nc has been changed and -l and -p options are considered
+as mutually exclusive. If nc complains about options provided,
+you can just remove the -p option from the script.
+
+It turns out that 'netcat' cannot be used to listen to broadcast
+packets. We developed our own tool 'ncb' (see tools directory) that
+listens to broadcast packets on a given port and dumps them to the
+standard output.  It will be built when compiling for a board which
+has CONFIG_NETCONSOLE defined.  If the netconsole script can find it
+in PATH or in the same directory, it will be used instead.
+
+For Linux, the network-based console needs special configuration.
+Minimally, the host IP address needs to be specified. This can be
+done either via the kernel command line, or by passing parameters
+while loading the netconsole.o module (when used in a loadable module
+configuration). Please refer to Documentation/networking/logging.txt
+file for the original Ingo Molnar's documentation on how to pass
+parameters to the loadable module.
+
+The format of the kernel command line parameter (for the static
+configuration) is as follows
+
+.. code-block:: bash
+
+    netconsole=[src-port]@[src-ip]/[<dev>],[tgt-port]@<tgt-ip>/[tgt-macaddr]
+
+where
+
+src-port
+    source for UDP packets (defaults to 6665)
+
+src-ip
+    source IP to use (defaults to the interface's address)
+
+dev
+    network interface (defaults to eth0)
+
+tgt-port
+  port for logging agent (defaults to 6666)
+
+tgt-ip
+  IP address for logging agent (this is the required parameter)
+
+tgt-macaddr
+    ethernet MAC address for logging agent (defaults to broadcast)
+
+Examples
+
+.. code-block:: bash
+
+  netconsole=4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc
+  netconsole=@/,@192.168.3.1/
+
+Please note that for the Linux networked console to work, the
+ethernet interface has to be up by the time the netconsole driver is
+initialized. This means that in case of static kernel configuration,
+the respective Ethernet interface has to be brought up using the "IP
+Autoconfiguration" kernel feature, which is usually done by defaults
+in the ELDK-NFS-based environment.
+
+To browse the Linux network console output, use the 'netcat' tool invoked
+as follows:
+
+.. code-block:: bash
+
+	nc -u -l -p 6666
+
+Note that unlike the U-Boot implementation the Linux netconsole is
+unidirectional, i. e. you have console output only in Linux.
diff --git a/roms/u-boot/doc/usage/partitions.rst b/roms/u-boot/doc/usage/partitions.rst
new file mode 100644
index 000000000..2c1a12b6b
--- /dev/null
+++ b/roms/u-boot/doc/usage/partitions.rst
@@ -0,0 +1,80 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. _partitions:
+
+Partitions
+==========
+
+Synopsis
+--------
+
+::
+
+    <command> <interface> [devnum][.hwpartnum][:partnum|#partname]
+
+Description
+-----------
+
+Many U-Boot commands allow specifying partitions (or whole disks) using a
+generic syntax.
+
+interface
+        The interface used to access the partition's device, like ``mmc`` or
+        ``scsi``. For a full list of supported interfaces, consult the
+        ``if_typename_str`` array in ``drivers/block/blk-uclass.c``
+
+devnum
+        The device number. This defaults to 0.
+
+hwpartnum
+        The hardware partition number. All devices have at least one hardware
+        partition. On most devices, hardware partition 0 specifies the whole
+        device. On eMMC devices, hardware partition 0 is the user partition,
+        hardware partitions 1 and 2 are the boot partitions, hardware partition
+        3 is the RPMB partition, and further partitions are general-purpose
+        user-created partitions. The default hardware partition number is 0.
+
+partnum
+        The partition number, starting from 1. The partition number 0 specifies
+        that the whole device is to be used as one "partition."
+
+partname
+        The partition name. This is the partition label for GPT partitions. For
+        MBR partitions, the following syntax is used::
+
+                <devtype><devletter><partnum>
+
+        devtype
+                A device type like ``mmcsd`` or ``hd``. See the
+                ``part_set_generic_name`` function in ``disk/part.c`` for a
+                complete list.
+
+        devletter
+                The device number as an offset from ``a``. For example, device
+                number 2 would have a device letter of ``c``.
+
+        partnum
+                The partition number. This is the same as above.
+
+If neither ``partname`` nor ``partnum`` is specified and there is a partition
+table, then partition 1 is used. If there is no partition table, then the whole
+device is used as one "partition." If none of ``devnum``, ``hwpartnum``,
+``partnum``, or ``partname`` is specified, or only ``-`` is specified, then
+``devnum`` defaults to the value of the ``bootdevice`` environmental variable.
+
+Examples
+--------
+
+List the root directory contents on MMC device 2, hardware partition 1,
+and partition number 3::
+
+        ls mmc 2.1:3 /
+
+Load ``/kernel.itb`` to address ``0x80000000`` from SCSI device 0, hardware partition
+0, and the partition labeled ``boot``::
+
+        load scsi #boot 0x80000000 /kernel.itb
+
+Print the partition UUID of the SATA device ``$bootdevice``, hardware partition
+0, and partition number 0::
+
+        part uuid sata -
diff --git a/roms/u-boot/doc/usage/pinmux.rst b/roms/u-boot/doc/usage/pinmux.rst
new file mode 100644
index 000000000..9f4392cd0
--- /dev/null
+++ b/roms/u-boot/doc/usage/pinmux.rst
@@ -0,0 +1,95 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+pinmux command
+==============
+
+Synopsis
+--------
+
+::
+
+    pinmux list
+    pinmux dev [pincontroller-name]
+    pinmux status [-a | pin-name]
+
+Description
+-----------
+
+The pinmux command is used to show the pin-controller muxing.
+
+The 'pinmux list' command diplays the available pin-controller.
+
+The 'pinmux dev' command selects the pin-controller for next commands.
+
+    pincontroller-name
+        name of the pin-controller to select
+
+The 'pinmux status' command displays the pin muxing information.
+
+    \-a
+        display pin muxing of all pin-controllers.
+    pin-name
+        name of the pin to display
+
+Example
+-------
+
+::
+
+    => pinmux list
+    | Device                        | Driver                        | Parent
+    | pinctrl-gpio                  | sandbox_pinctrl_gpio          | root_driver
+    | pinctrl                       | sandbox_pinctrl               | root_driver
+    =>
+    => pinmux dev pinctrl
+    dev: pinctrl
+    =>
+    => pinmux status
+    P0        : UART TX.
+    P1        : UART RX.
+    P2        : I2S SCK.
+    P3        : I2S SD.
+    P4        : I2S WS.
+    P5        : GPIO0 bias-pull-up input-disable.
+    P6        : GPIO1 drive-open-drain.
+    P7        : GPIO2 bias-pull-down input-enable.
+    P8        : GPIO3 bias-disable.
+    =>
+    => pinmux status P0
+    P0        : UART TX.
+    =>
+    => pinmux status -a
+    --------------------------
+    pinctrl-gpio:
+    a0        : gpio input .
+    a1        : gpio input .
+    a2        : gpio input .
+    a3        : gpio input .
+    a4        : gpio input .
+    a5        : gpio output .
+    a6        : gpio output .
+    a7        : gpio input .
+    a8        : gpio input .
+    a9        : gpio input .
+    --------------------------
+    pinctrl:
+    P0        : UART TX.
+    P1        : UART RX.
+    P2        : I2S SCK.
+    P3        : I2S SD.
+    P4        : I2S WS.
+    P5        : GPIO0 bias-pull-up input-disable.
+    P6        : GPIO1 drive-open-drain.
+    P7        : GPIO2 bias-pull-down input-enable.
+    P8        : GPIO3 bias-disable.
+
+Configuration
+-------------
+
+The pinmux command is only available if CONFIG_CMD_PINMUX=y.
+
+Return value
+------------
+
+The return value $? is set to 0 (true) if the command succeded and to 1 (false)
+otherwise.
diff --git a/roms/u-boot/doc/usage/pstore.rst b/roms/u-boot/doc/usage/pstore.rst
new file mode 100644
index 000000000..1c8374513
--- /dev/null
+++ b/roms/u-boot/doc/usage/pstore.rst
@@ -0,0 +1,93 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+pstore command
+==============
+
+Synopsis
+--------
+
+::
+
+    pstore set <addr> <len> [record-size] [console-size] [ftrace-size] [pmsg_size] [ecc-size]
+    pstore display [record-type] [nb]
+    pstore save <interface> <dev[:part]> <directory-path>
+
+Design
+------
+
+Linux PStore and Ramoops modules (Linux config options PSTORE and PSTORE_RAM)
+allow to use memory to pass data from the dying breath of a crashing kernel to
+its successor. This command allows to read those records from U-Boot command
+line.
+
+Ramoops is an oops/panic logger that writes its logs to RAM before the system
+crashes. It works by logging oopses and panics in a circular buffer. Ramoops
+needs a system with persistent RAM so that the content of that area can survive
+after a restart.
+
+Ramoops uses a predefined memory area to store the dump.
+
+Ramoops parameters can be passed as kernel parameters or through Device Tree,
+i.e.::
+
+    ramoops.mem_address=0x30000000 ramoops.mem_size=0x100000 ramoops.record_size=0x2000 ramoops.console_size=0x2000 memmap=0x100000$0x30000000
+
+The same values should be set in U-Boot to be able to retrieve the records.
+This values can be set at build time in U-Boot configuration file, or at runtime.
+U-Boot automatically patches the Device Tree to pass the Ramoops parameters to
+the kernel.
+
+The PStore configuration parameters are:
+
+======================= ==========
+ Name                   Default
+======================= ==========
+CMD_PSTORE_MEM_ADDR
+CMD_PSTORE_MEM_SIZE     0x10000
+CMD_PSTORE_RECORD_SIZE  0x1000
+CMD_PSTORE_CONSOLE_SIZE 0x1000
+CMD_PSTORE_FTRACE_SIZE  0x1000
+CMD_PSTORE_PMSG_SIZE    0x1000
+CMD_PSTORE_ECC_SIZE     0
+======================= ==========
+
+Records sizes should be a power of 2.
+The memory size and the record/console size must be non-zero.
+
+Multiple 'dump' records can be stored in the memory reserved for PStore.
+The memory size has to be larger than the sum of the record sizes, i.e.::
+
+    MEM_SIZE >= RECORD_SIZE * n + CONSOLE_SIZE + FTRACE_SIZE + PMSG_SIZE
+
+Usage
+-----
+
+Generate kernel crash
+~~~~~~~~~~~~~~~~~~~~~
+
+For test purpose, you can generate a kernel crash by setting reboot timeout to
+10 seconds and trigger a panic
+
+.. code-block:: console
+
+    $ sudo sh -c "echo 1 > /proc/sys/kernel/sysrq"
+    $ sudo sh -c "echo 10 > /proc/sys/kernel/panic"
+    $ sudo sh -c "echo c > /proc/sysrq-trigger"
+
+Retrieve logs in U-Boot
+~~~~~~~~~~~~~~~~~~~~~~~
+
+First of all, unless PStore parameters as been set during U-Boot configuration
+and match kernel ramoops parameters, it needs to be set using 'pstore set', e.g.::
+
+    => pstore set 0x30000000 0x100000 0x2000 0x2000
+
+Then all available dumps can be displayed
+using::
+
+    => pstore display
+
+Or saved to an existing directory in an Ext2 or Ext4 partition, e.g. on root
+directory of 1st partition of the 2nd MMC::
+
+    => pstore save mmc 1:1 /
diff --git a/roms/u-boot/doc/usage/qfw.rst b/roms/u-boot/doc/usage/qfw.rst
new file mode 100644
index 000000000..87463e1e5
--- /dev/null
+++ b/roms/u-boot/doc/usage/qfw.rst
@@ -0,0 +1,89 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+qfw command
+===========
+
+Synopsis
+--------
+
+::
+
+    qfw list
+    qfw cpus
+    qfw load [kernel_addr [initrd_addr]]
+
+Description
+-----------
+
+The *qfw* command is used to retrieve information form the QEMU firmware.
+
+The *qfw list* sub-command displays the QEMU firmware files.
+
+The *qfw cpus* sub-command displays the available CPUs.
+
+The *qfw load* command is used to load a kernel and an initial RAM disk.
+
+kernel_addr
+    address to which the file specified by the -kernel parameter of QEMU shall
+    be loaded. Defaults to environment variable *loadaddr* and further to
+    the value of *CONFIG_LOADADDR*.
+
+initrd_addr
+    address to which the file specified by the -initrd parameter of QEMU shall
+    be loaded. Defaults to environment variable *ramdiskaddr* and further to
+    the value of *CONFIG_RAMDISK_ADDR*.
+
+Examples
+--------
+
+QEMU firmware files are listed via the *qfw list* command:
+
+::
+
+    => qfw list
+    etc/boot-fail-wait
+    etc/smbios/smbios-tables
+    etc/smbios/smbios-anchor
+    etc/e820
+    genroms/kvmvapic.bin
+    genroms/linuxboot.bin
+    etc/system-states
+    etc/acpi/tables
+    etc/table-loader
+    etc/tpm/log
+    etc/acpi/rsdp
+    bootorder
+
+The available CPUs can be shown via the *qfw cpus* command:
+
+::
+
+    => qfw cpu
+    2 cpu(s) online
+
+The *-kernel* and *-initrd* parameters allow to specify a kernel and an
+initial RAM disk for QEMU:
+
+.. code-block:: bash
+
+   $ qemu-system-x86_64 -machine pc-i440fx-2.5 -bios u-boot.rom -m 1G \
+       -nographic -kernel vmlinuz -initrd initrd
+
+Now the kernel and the initial RAM disk can be loaded to the U-Boot memory via
+the *qfw load* command and booted thereafter.
+
+::
+
+    => qfw load ${kernel_addr_r} ${ramdisk_addr_r}
+    loading kernel to address 0000000001000000 size 5048f0 initrd 0000000004000000 size 3c94891
+    => zboot 1000000 5048f0 4000000 3c94891
+    Valid Boot Flag
+    Magic signature found
+    Linux kernel version 4.19.0-14-amd64 (debian-kernel@lists.debian.org) #1 SMP Debian 4.19.171-2 (2021-01-30)
+    Building boot_params at 0x00090000
+    Loading bzImage at address 100000 (5260160 bytes)
+
+Configuration
+-------------
+
+The qfw command is only available if CONFIG_CMD_QFW=y.
diff --git a/roms/u-boot/doc/usage/reset.rst b/roms/u-boot/doc/usage/reset.rst
new file mode 100644
index 000000000..384d5d60f
--- /dev/null
+++ b/roms/u-boot/doc/usage/reset.rst
@@ -0,0 +1,26 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+reset command
+=============
+
+Synopsis
+--------
+
+::
+
+    reset [-w]
+
+Description
+-----------
+
+Perform reset of the CPU. By default does COLD reset, which resets CPU,
+DDR and peripherals, on some boards also resets external PMIC.
+
+-w
+    Do warm WARM, reset CPU but keep peripheral/DDR/PMIC active.
+
+
+Return value
+------------
+
+The return value $? is always set to 0 (true).
diff --git a/roms/u-boot/doc/usage/sbi.rst b/roms/u-boot/doc/usage/sbi.rst
new file mode 100644
index 000000000..96d886105
--- /dev/null
+++ b/roms/u-boot/doc/usage/sbi.rst
@@ -0,0 +1,49 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+sbi command
+===========
+
+Synopsis
+--------
+
+::
+
+    sbi
+
+Description
+-----------
+
+The sbi command is used to display information about the SBI (Supervisor Binary
+Interface) implementation on RISC-V systems.
+
+The output may look like:
+
+::
+
+    => sbi
+    SBI 0.2
+    OpenSBI
+    Extensions:
+      sbi_set_timer
+      sbi_console_putchar
+      sbi_console_getchar
+      sbi_clear_ipi
+      sbi_send_ipi
+      sbi_remote_fence_i
+      sbi_remote_sfence_vma
+      sbi_remote_sfence_vma_asid
+      sbi_shutdown
+      SBI Base Functionality
+      Timer Extension
+      IPI Extension
+      RFENCE Extension
+      Hart State Management Extension
+
+The first line indicates the version of the RISC-V SBI specification.
+The second line indicates the implementation.
+The further lines enumerate the implemented extensions.
+
+Configuration
+-------------
+
+To use the sbi command you must specify CONFIG_CMD_SBI=y.
diff --git a/roms/u-boot/doc/usage/scp03.rst b/roms/u-boot/doc/usage/scp03.rst
new file mode 100644
index 000000000..7ff87ed85
--- /dev/null
+++ b/roms/u-boot/doc/usage/scp03.rst
@@ -0,0 +1,33 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+scp03 command
+=============
+
+Synopsis
+--------
+
+::
+
+    scp03 enable
+    scp03 provision
+
+Description
+-----------
+
+The *scp03* command calls into a Trusted Application executing in a
+Trusted Execution Environment to enable (if present) the Secure
+Channel Protocol 03 stablished between the processor and the secure
+element.
+
+This protocol encrypts all the communication between the processor and
+the secure element using a set of pre-defined keys. These keys can be
+rotated (provisioned) using the *provision* request.
+
+See also
+--------
+
+For some information on the internals implemented in the TEE, please
+check the GlobalPlatform documentation on `Secure Channel Protocol '03'`_
+
+.. _Secure Channel Protocol '03':
+   https://globalplatform.org/wp-content/uploads/2014/07/GPC_2.3_D_SCP03_v1.1.2_PublicRelease.pdf
diff --git a/roms/u-boot/doc/usage/size.rst b/roms/u-boot/doc/usage/size.rst
new file mode 100644
index 000000000..f0c35e482
--- /dev/null
+++ b/roms/u-boot/doc/usage/size.rst
@@ -0,0 +1,40 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+size command
+============
+
+Synopsis
+--------
+
+::
+
+    size <interface> <dev[:part]> <filename>
+
+Description
+-----------
+
+The size command determines the size of a file and sets the environment variable
+filesize to this value. If filename points to a directory, the value is set to
+zero.
+
+If the command fails, the filesize environment variable is not changed.
+
+dev
+    device number
+
+part
+    partition number, defaults to 1
+
+filename
+    path to file
+
+Configuration
+-------------
+
+The size command is only available if CONFIG_CMD_FS_GENERIC=y.
+
+Return value
+------------
+
+The return value $? is set to 0 (true) if the command succeded and to 1 (false)
+otherwise.
diff --git a/roms/u-boot/doc/usage/true.rst b/roms/u-boot/doc/usage/true.rst
new file mode 100644
index 000000000..f9ef71b2d
--- /dev/null
+++ b/roms/u-boot/doc/usage/true.rst
@@ -0,0 +1,28 @@
+true command
+============
+
+Synopsis
+--------
+
+::
+
+    true
+
+Description
+-----------
+
+The true command sets the return value $? to 0 (true).
+
+Example
+-------
+
+::
+
+    => true; echo $?
+    0
+    =>
+
+Configuration
+-------------
+
+The true command is only available if CONFIG_HUSH_PARSER=y.
diff --git a/roms/u-boot/doc/usage/ums.rst b/roms/u-boot/doc/usage/ums.rst
new file mode 100644
index 000000000..3cde5fa1f
--- /dev/null
+++ b/roms/u-boot/doc/usage/ums.rst
@@ -0,0 +1,57 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+ums command
+===========
+
+Synopsis
+--------
+
+::
+
+    ums <dev> [<interface>] <devnum[:partnum]>
+
+Description
+-----------
+
+Use the USB Mass Storage class (also known as UMS) to make accessible an U-Boot
+block device (fully or with :ref:`U-Boot's partition syntax <partitions>`)
+to a USB host and to enable file transfers. U-Boot, the USB device, acts as a
+simple external hard drive plugged on the host USB port.
+
+This command "ums" stays in the USB's treatment loop until user enters Ctrl-C.
+
+dev
+    USB gadget device number
+
+interface
+    interface for accessing the block device (mmc, sata, scsi, usb, ....)
+    defaults is "mmc"
+
+devnum
+    device number for selected interface
+
+partnum
+    partition number or 0 to expose all partitions, defaults to 0
+
+Example
+-------
+
+::
+
+    => ums 0 mmc 0
+    => ums 0 usb 1:2
+
+Configuration
+-------------
+
+The ums command is only available if CONFIG_CMD_USB_MASS_STORAGE=y
+and depends on CONFIG_USB_USB_GADGET and CONFIG_BLK.
+
+Return value
+------------
+
+The return value $? is set to 0 (true) when the USB stack was successfully
+started and interrupted, with Ctrl-C or after USB cable issue (detection
+timeout or cable removal).
+
+If an error occurs, the return value $? is set to 1 (false).
diff --git a/roms/u-boot/doc/usage/x86/cbsysinfo.rst b/roms/u-boot/doc/usage/x86/cbsysinfo.rst
new file mode 100644
index 000000000..8c03a8516
--- /dev/null
+++ b/roms/u-boot/doc/usage/x86/cbsysinfo.rst
@@ -0,0 +1,25 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+cbsysinfo
+=========
+
+Synopis
+-------
+
+::
+
+    cbsysinfo
+
+
+Description
+-----------
+
+This displays information obtained from the coreboot sysinfo table. It is only
+useful when booting U-Boot from coreboot.
+
+Example
+-------
+
+::
+
+    => cbsysinfo
author	Angelos Mouzakitis <a.mouzakitis@virtualopensystems.com>	2023-10-10 14:33:42 +0000
committer	Angelos Mouzakitis <a.mouzakitis@virtualopensystems.com>	2023-10-10 14:33:42 +0000
commit	af1a266670d040d2f4083ff309d732d648afba2a (patch)
tree	2fc46203448ddcc6f81546d379abfaeb323575e9 /roms/u-boot/doc/usage
parent	e02cda008591317b1625707ff8e115a4841aa889 (diff)