Merge tag 'efi-2023-04-rc1-2' of https://source.denx.de/u-boot/custodians/u-boot-efi

Pull request for efi-2023-04-rc1-2

Documentation

* man-pages for source, blkcache, bdinfo
* fix references to distro documentation

UEFI:

* allow clear screen by scrolling
* ensure that file ubootefi.var is created
* fix CapsuleMax variable reporting

Others:

* reduce verbosity of fat_read_file()

4 files changed, 389 insertions, 0 deletions

diff --git a/doc/usage/cmd/bdinfo.rst b/doc/usage/cmd/bdinfo.rst
new file mode 100644
index 0000000000..6b3cde2ccb
--- /dev/null
+++ b/doc/usage/cmd/bdinfo.rst
@@ -0,0 +1,119 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright 2023, Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
+
+bdinfo command
+==============
+
+Synopsis
+--------
+
+::
+
+    bdinfo
+
+Description
+-----------
+
+The *bdinfo* command prints information about the board.
+
+Example
+=======
+
+::
+
+    => bdinfo
+    boot_params = 0x0000000000000000
+    DRAM bank   = 0x0000000000000000
+    -> start    = 0x0000000040000000
+    -> size     = 0x0000000100000000
+    flashstart  = 0x0000000000000000
+    flashsize   = 0x0000000004000000
+    flashoffset = 0x00000000000e87f8
+    baudrate    = 115200 bps
+    relocaddr   = 0x000000013fefb000
+    reloc off   = 0x000000013fefb000
+    Build       = 64-bit
+    current eth = virtio-net#32
+    ethaddr     = 52:52:52:52:52:52
+    IP addr     = 10.0.2.15
+    fdt_blob    = 0x000000013edbadb0
+    new_fdt     = 0x000000013edbadb0
+    fdt_size    = 0x0000000000100000
+    lmb_dump_all:
+     memory.cnt  = 0x1
+     memory[0]      [0x40000000-0x13fffffff], 0x100000000 bytes flags: 0
+     reserved.cnt  = 0x2
+     reserved[0]    [0x13ddb3000-0x13fffffff], 0x0224d000 bytes flags: 0
+     reserved[1]    [0x13edb6930-0x13fffffff], 0x012496d0 bytes flags: 0
+    devicetree  = board
+    arch_number = 0x0000000000000000
+    TLB addr    = 0x000000013fff0000
+    irq_sp      = 0x000000013edbada0
+    sp start    = 0x000000013edbada0
+    Early malloc usage: 3a8 / 2000
+    =>
+
+boot_params
+    address of the memory area for boot parameters
+
+DRAM bank
+    index, start address and end address of a memory bank
+
+baudrate
+    baud rate of the serial console
+
+relocaddr
+    address to which U-Boot has relocated itself
+
+reloc off
+    relocation offset, difference between *relocaddr* and the text base
+
+Build
+    bitness of the system
+
+current eth
+    name of the active network device
+
+IP addr
+    network address, value of the environment variable *ipaddr*
+
+fdt_blob
+    address of U-Boot's own device tree, NULL if none
+
+new_fdt
+    location of the relocated device tree
+
+fdt_size
+    space reserved for relocated device space
+
+lmb_dump_all
+    available memory and memory reservations
+
+devicetree
+    source of the device-tree
+
+arch_number
+    unique id for the board
+
+TLB addr
+    address of the translation lookaside buffer
+
+irq_sp
+    address of the IRQ stack pointer
+
+sp start
+    initial stack pointer address
+
+Early malloc usage
+    amount of memory used in the early malloc memory and its maximum size
+    as defined by CONFIGSYS_MALLOC_F_LEN
+
+Configuration
+-------------
+
+The bdinfo command is available if CONFIG_CMD_BDI=y.
+
+Return code
+-----------
+
+The return code $? is 0 (true).
diff --git a/doc/usage/cmd/blkcache.rst b/doc/usage/cmd/blkcache.rst
new file mode 100644
index 0000000000..d3b2254cfa
--- /dev/null
+++ b/doc/usage/cmd/blkcache.rst
@@ -0,0 +1,74 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright 2023, Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
+
+blkcache command
+================
+
+Synopsis
+--------
+
+::
+
+    blkcache show
+    blkcache configure <blocks> <entries>
+
+Description
+-----------
+
+The *blkcache* command is used to control the size of the block cache and to
+display statistics.
+
+The block cache buffers data read from block devices. This speeds up the access
+to file-systems.
+
+show
+    show and reset statistics
+
+configure
+    set the maximum number of cache entries and the maximum number of blocks per
+    entry
+
+blocks
+    maximum number of blocks per cache entry. The block size is device specific.
+    The initial value is 8.
+
+entries
+    maximum number of entries in the cche. The initial value is 32.
+
+Example
+-------
+
+.. code-block::
+
+    => blkcache show
+    hits: 296
+    misses: 149
+    entries: 7
+    max blocks/entry: 8
+    max cache entries: 32
+    => blkcache show
+    hits: 0
+    misses: 0
+    entries: 7
+    max blocks/entry: 8
+    max cache entries: 32
+    => blkcache configure 16 64
+    changed to max of 64 entries of 16 blocks each
+    => blkcache show
+    hits: 0
+    misses: 0
+    entries: 0
+    max blocks/entry: 16
+    max cache entries: 64
+    =>
+
+Configuration
+-------------
+
+The blkcache command is only available if CONFIG_CMD_BLOCK_CACHE=y.
+
+Return code
+-----------
+
+If the command succeeds, the return code $? is set 0 (true). In case of an
+error the return code is set to 1 (false).
diff --git a/doc/usage/cmd/source.rst b/doc/usage/cmd/source.rst
new file mode 100644
index 0000000000..61a4505909
--- /dev/null
+++ b/doc/usage/cmd/source.rst
@@ -0,0 +1,193 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright 2022, Heinrich Schuchardt <xypron.glpk@gmx.de>
+
+source command
+==============
+
+Synopsis
+--------
+
+::
+
+    source [<addr>][:[<image>]|#[<config>]]
+
+Description
+-----------
+
+The *source* command is used to execute a script file from memory.
+
+Two formats for script files exist:
+
+* legacy U-Boot image format
+* Flat Image Tree (FIT)
+
+The benefit of the FIT images is that they can be signed and verifed as
+decribed in :download:`signature.txt <../../uImage.FIT/signature.txt>`.
+
+Both formats can be created with the mkimage tool.
+
+addr
+    location of the script file in memory, defaults to CONFIG_SYS_LOAD_ADDR.
+
+image
+    name of an image in a FIT file
+
+config
+    name of a configuration in a FIT file. A hash sign following white space
+    starts a comment. Hence, if no *addr* is specified, the hash sign has to be
+    escaped with a backslash or the argument must be quoted.
+
+If both *image* and *config* are omitted, the default configuration is used, or
+if no configuration is defined, the default image.
+
+Examples
+--------
+
+FIT image
+'''''''''
+
+For creating a FIT image an image tree source file (\*.its) is needed. Here is
+an example (source.its).
+
+.. code-block::
+
+    /dts-v1/;
+
+    / {
+        description = "FIT image to test the source command";
+        #address-cells = <1>;
+
+        images {
+            default = "script-1";
+
+            script-1 {
+                data = "echo 1";
+                type = "script";
+                compression = "none";
+            };
+
+            script-2 {
+                data = "echo 2";
+                type = "script";
+                compression = "none";
+            };
+        };
+
+        configurations {
+            default = "conf-2";
+
+            conf-1 {
+                script = "script-1";
+            };
+
+            conf-2 {
+                script = "script-2";
+            };
+        };
+    };
+
+The FIT image file (boot.itb) is created with:
+
+.. code-block:: bash
+
+    mkimage -f source.its boot.itb
+
+In U-Boot the script can be loaded and execute like this
+
+.. code-block::
+
+    => load host 0:1 $loadaddr boot.itb
+    1552 bytes read in 0 ms
+    => source $loadaddr#conf-1
+    ## Executing script at 00000000
+    1
+    => source $loadaddr#conf-2
+    ## Executing script at 00000000
+    2
+    => source $loadaddr:script-1
+    ## Executing script at 00000000
+    1
+    => source $loadaddr:script-2
+    ## Executing script at 00000000
+    2
+    => source $loadaddr
+    ## Executing script at 00000000
+    2
+    => source \#conf-1
+    ## Executing script at 00000000
+    1
+    => source '#conf-1'
+    ## Executing script at 00000000
+    1
+    => source ':script-1'
+    ## Executing script at 00000000
+    1
+    => source
+    ## Executing script at 00000000
+    2
+    =>
+
+Instead of specifying command line instructions directly in the *data* property
+of the image tree source file another file can be included. Here is a minimal
+example which encapsulates the file boot.txt:
+
+.. code-block::
+
+    /dts-v1/;
+    / {
+        description = "";
+        images {
+            script {
+                data = /incbin/("./boot.txt");
+                type = "script";
+            };
+        };
+    };
+
+Legacy U-Boot image
+'''''''''''''''''''
+
+A script file using the legacy U-Boot image file format can be created based on
+a text file. Let's use this example text file (boot.txt):
+
+.. code-block:: bash
+
+    echo Hello from a script
+    echo -------------------
+
+The boot scripts (boot.scr) is created with:
+
+.. code-block:: bash
+
+    mkimage -T script -n 'Test script' -d boot.txt boot.scr
+
+The script can be execute in U-boot like this:
+
+.. code-block::
+
+    => load host 0:1 $loadaddr boot.scr
+    122 bytes read in 0 ms
+    => source $loadaddr
+    ## Executing script at 00000000
+    Hello from a script
+    -------------------
+    => source
+    ## Executing script at 00000000
+    Hello from a script
+    -------------------
+    =>
+
+Configuration
+-------------
+
+The source command is only available if CONFIG_CMD_SOURCE=y.
+The FIT image file format requires CONFIG_FIT=y.#
+The legacy U-Boot image file format requires CONFIG_LEGACY_IMAGE_FORMAT=y.
+On hardened systems support for the legacy U-Boot image format should be
+disabled as these images cannot be signed and verified.
+
+Return value
+------------
+
+If the scripts is executed successfully, the return value $? is 0 (true).
+Otherwise it is 1 (false).
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index cf3666a77d..7d4a1cbc10 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -23,6 +23,8 @@ Shell commands
    cmd/addrmap
    cmd/askenv
    cmd/base
+   cmd/bdinfo
+   cmd/blkcache
    cmd/bootd
    cmd/bootdev
    cmd/bootefi
@@ -75,6 +77,7 @@ Shell commands
    cmd/setexpr
    cmd/size
    cmd/sound
+   cmd/source
    cmd/temperature
    cmd/tftpput
    cmd/true