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

Pull request efi-2023-04-rc1-3

Documentation:

* Improve the sl-mx8mm documenation
* Clean up README, move some section to HTML
* Man-pages for the mtime and sleep command
* Description of reducible builds
* Document dynamic event handlers

UEFI:

* Support scrolling in eficonfig command

Other:

* fix mtest on 64 bit systems

13 files changed, 327 insertions, 33 deletions

diff --git a/doc/board/kontron/sl-mx8mm.rst b/doc/board/kontron/sl-mx8mm.rst
index f022e0979b..702db60fe3 100644
--- a/doc/board/kontron/sl-mx8mm.rst
+++ b/doc/board/kontron/sl-mx8mm.rst
@@ -9,7 +9,7 @@ with an i.MX8M-Mini SoC, 1/2/4 GB LPDDR4 RAM, SPI NOR, eMMC and PMIC.
 The matching evaluation boards (Board-Line, BL) have two Ethernet ports,
 USB 2.0, HDMI/LVDS, SD card, CAN, RS485, RS232 and much more.
 
-The OSM-S i.MX8MM is compliant to the Open Standard Module (OSM) 1.0
+The OSM-S i.MX8MM is compliant to the Open Standard Module (OSM) 1.1
 specification, size S (https://sget.org/standards/osm).
 
 Quick Start
@@ -20,25 +20,38 @@ Quick Start
 - Build U-Boot
 - Boot
 
+.. note::
+
+   To build on a x86-64 host machine, you need a GNU cross toolchain for the
+   target architecture (aarch64). Check your distros package manager or
+   download and install the necessary tools (``aarch64-linux-gnu-*``) manually.
+
 Get and Build the Trusted Firmware-A (TF-A)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Note: builddir is U-Boot build directory (source directory for in-tree builds)
-
 There are two sources for the TF-A. Mainline and NXP. Get the one you prefer
 (support and features might differ).
 
+.. note::
+
+   If you are using GCC 12 and you get compiler/linker errors, try to add the
+   following arguments to your make command as workaround:
+   ``CFLAGS="-Wno-array-bounds" LDFLAGS="--no-warn-rwx-segments"``
+
 **NXP's imx-atf**
 
-1. Get TF-A from: https://source.codeaurora.org/external/imx/imx-atf, branch: imx_5.4.70_2.3.0
-2. Apply the patch to select the correct UART for the console, otherwise the TF-A will lock up during boot.
-3. Build
+1. Get TF-A from: https://github.com/nxp-imx/imx-atf, branch: lf_v2.6
+2. Build
 
   .. code-block:: bash
 
-     $ make PLAT=imx8mm bl31
+     $ make PLAT=imx8mm CROSS_COMPILE=aarch64-linux-gnu- IMX_BOOT_UART_BASE="0x30880000" bl31
      $ cp build/imx8mm/release/bl31.bin $(builddir)
 
+.. note::
+
+    *builddir* is U-Boot's build directory (source directory for in-tree builds)
+
 **Mainline TF-A**
 
 1. Get TF-A from: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/, tag: v2.4
@@ -54,10 +67,13 @@ Get the DDR firmware
 
 .. code-block:: bash
 
-   $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.9.bin
-   $ chmod +x firmware-imx-8.9.bin
-   $ ./firmware-imx-8.9.bin
-   $ cp firmware-imx-8.9/firmware/ddr/synopsys/lpddr4*.bin $(builddir)
+   $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.18.bin
+   $ chmod +x firmware-imx-8.18.bin
+   $ ./firmware-imx-8.18.bin
+   $ cp firmware-imx-8.18/firmware/ddr/synopsys/lpddr4_pmu_train_1d_imem.bin $(builddir)
+   $ cp firmware-imx-8.18/firmware/ddr/synopsys/lpddr4_pmu_train_1d_dmem.bin $(builddir)
+   $ cp firmware-imx-8.18/firmware/ddr/synopsys/lpddr4_pmu_train_2d_imem.bin $(builddir)
+   $ cp firmware-imx-8.18/firmware/ddr/synopsys/lpddr4_pmu_train_2d_dmem.bin $(builddir)
 
 Build U-Boot
 ^^^^^^^^^^^^
@@ -65,9 +81,9 @@ Build U-Boot
 .. code-block:: bash
 
    $ make kontron-sl-mx8mm_defconfig
-   $ make
+   $ make CROSS_COMPILE=aarch64-linux-gnu-
 
-Burn the flash.bin to SD card at an offset of 33 KiB:
+Copy the flash.bin to SD card at an offset of 33 KiB:
 
 .. code-block:: bash
 
@@ -76,7 +92,39 @@ Burn the flash.bin to SD card at an offset of 33 KiB:
 Boot
 ^^^^
 
-Put the SD card in the slot on the board and apply power.
+Put the SD card in the slot on the board and apply power. Check the serial
+console for output.
+
+Flash the Bootloader to SPI NOR
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Determine and note the exact size of the ``flash.bin`` image in bytes (e.g.
+   by running ``ls -l flash.bin``)
+
+2. On the U-Boot CLI copy the bootloader from SD card to RAM:
+
+   .. code-block::
+
+      mmc dev 1
+      mmc read $loadaddr 0x42 0x1000
+
+3. Erase the SPI NOR flash:
+
+   .. code-block::
+
+      sf probe
+      sf erase 0x0 0x200000
+
+4. Copy the bootloader from RAM to SPI NOR. For the last parameter of the
+   command, use the size determined in step 1 in **hexadecimal notation**:
+
+   .. code-block::
+
+      sf write $loadaddr 0x400 0x13B6F0
+
+.. note::
+
+   To be able to boot from SPI NOR the OTP fuses need to be set accordingly.
 
 Further Information
 -------------------
diff --git a/doc/board/st/stm32mp1.rst b/doc/board/st/stm32mp1.rst
index 3f70634d28..c0b1daa041 100644
--- a/doc/board/st/stm32mp1.rst
+++ b/doc/board/st/stm32mp1.rst
@@ -478,7 +478,8 @@ or:
   +-------+--------+---------+------------------------+------------------------+
 
 And the 4th partition (Rootfs) is marked bootable with a file extlinux.conf
-following the Generic Distribution feature (doc/develop/distro.rst for use).
+following the Generic Distribution feature (see :doc:`../../develop/distro` for
+use).
 
 The size of fip or ssbl partition must be enough for the associated binary file,
 4MB and 2MB are default values.
diff --git a/doc/build/index.rst b/doc/build/index.rst
index dc9cde4001..64e66491bd 100644
--- a/doc/build/index.rst
+++ b/doc/build/index.rst
@@ -9,6 +9,7 @@ Build U-Boot
    source
    gcc
    clang
+   reproducible
    docker
    tools
    buildman
diff --git a/doc/build/reproducible.rst b/doc/build/reproducible.rst
new file mode 100644
index 0000000000..5423080633
--- /dev/null
+++ b/doc/build/reproducible.rst
@@ -0,0 +1,25 @@
+Reproducible builds
+===================
+
+In order to achieve reproducible builds, timestamps used in the U-Boot build
+process have to be set to a fixed value.
+
+This is done using the SOURCE_DATE_EPOCH environment variable which specifies
+the number of seconds since 1970-01-01T00:00:00Z.
+
+Example
+-------
+
+To build the sandbox with 2023-01-01T00:00:00Z as timestamp we can use:
+
+.. code-block:: bash
+
+    make sandbox_defconfig
+    SOURCE_DATE_EPOCH=1672531200 make
+
+This date is shown when we launch U-Boot:
+
+.. code-block:: console
+
+    ./u-boot -T
+    U-Boot 2023.01 (Jan 01 2023 - 00:00:00 +0000)
diff --git a/doc/develop/directories.rst b/doc/develop/directories.rst
new file mode 100644
index 0000000000..112b5655f6
--- /dev/null
+++ b/doc/develop/directories.rst
@@ -0,0 +1,76 @@
+Directory hierarchy
+===================
+
+.. list-table::
+   :header-rows: 1
+
+   * - Directory path
+     - Usage
+   * - /arch
+     - Architecture-specific files
+   * - /arch/arc
+     - Files relating to ARC architecture
+   * - /arch/arm
+     - Files relating to ARM architecture
+   * - /arch/m68k
+     - Files relating to m68k architecture
+   * - /arch/microblaze
+     - Files relating to microblaze architecture
+   * - /arch/mips
+     - Files relating to MIPS architecture
+   * - /arch/nios2
+     - Files relating to Altera NIOS2 architecture
+   * - /arch/powerpc
+     - Files relating to PowerPC architecture
+   * - /arch/riscv
+     - Files relating to RISC-V architecture
+   * - /arch/sandbox
+     - Files relating to HW-independent "sandbox"
+   * - /arch/sh
+     - Files relating to SH architecture
+   * - /arch/x86
+     - Files relating to x86 architecture
+   * - /arch/xtensa
+     - Files relating to Xtensa architecture
+   * - /api
+     - Machine/arch-independent API for external apps
+   * - /board
+     - Board-dependent files
+   * - /boot
+     - Support for images and booting
+   * - /cmd
+     - U-Boot commands functions
+   * - /common
+     - Misc architecture-independent functions
+   * - /configs
+     - Board default configuration files
+   * - /disk
+     - Code for disk drive partition handling
+   * - /doc
+     - Documentation (a mix of ReST and READMEs)
+   * - /drivers
+     - Device drivers
+   * - /dts
+     - Makefile for building internal U-Boot fdt.
+   * - /env
+     - Environment support
+   * - /examples
+     - Example code for standalone applications, etc.
+   * - /fs
+     - Filesystem code (cramfs, ext2, jffs2, etc.)
+   * - /include
+     - Header Files
+   * - /lib
+     - Library routines relating to all architectures
+   * - /Licenses
+     - Various license files
+   * - /net
+     - Networking code
+   * - /post
+     - Power On Self Test
+   * - /scripts
+     - Various build scripts and Makefiles
+   * - /test
+     - Various unit test files
+   * - /tools
+     - Tools to build and sign FIT images, etc.
diff --git a/doc/develop/event.rst b/doc/develop/event.rst
index 6951ec97e7..4ff5934837 100644
--- a/doc/develop/event.rst
+++ b/doc/develop/event.rst
@@ -64,3 +64,26 @@ in an image, use $(CROSS_COMPILE)nm::
 
     nm u-boot |grep evspy |grep list
     00000000002d6300 D _u_boot_list_2_evspy_info_2_EVT_MISC_INIT_F
+
+Logging is also available. Events use category `LOGC_EVENT`, so you can enable
+logging on that, or add `#define LOG_DEBUG` to the top of `common/event.c` to
+see events being sent.
+
+
+Dynamic events
+--------------
+
+Static events provide a way of dealing with events known at build time. In some
+cases we want to attach an event handler at runtime. For example, we may wish
+to be notified when a particular device is probed or removed.
+
+This can be handled by enabling `CONFIG_EVENT_DYNAMIC`. It is then possible to
+call `event_register()` to register a new handler for a particular event.
+
+Dynamic event handlers are called after all the static event spy handlers have
+been processed. Of course, since dynamic event handlers are created at runtime
+it is not possible to use the `event_dump.py` to see them.
+
+At present there is no way to list dynamic event handlers from the command line,
+nor to deregister a dynamic event handler. These features can be added when
+needed.
diff --git a/doc/develop/index.rst b/doc/develop/index.rst
index 79d7736b13..a52ad630d0 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -24,6 +24,7 @@ Implementation
 .. toctree::
    :maxdepth: 1
 
+   directories
    bloblist
    bootstd
    ci_testing
diff --git a/doc/mkeficapsule.1 b/doc/mkeficapsule.1
index 6fb2dd0810..1ca245a10f 100644
--- a/doc/mkeficapsule.1
+++ b/doc/mkeficapsule.1
@@ -11,22 +11,23 @@ mkeficapsule \- Generate EFI capsule file for U-Boot
 .RI [ options ] " " [ image-blob ] " " capsule-file
 
 .SH "DESCRIPTION"
+The
 .B mkeficapsule
-command is used to create an EFI capsule file for use with the U-Boot
-EFI capsule update.
-A capsule file may contain various type of firmware blobs which
-are to be applied to the system and must be placed in the specific
-directory on the UEFI system partition.
-An update will be automatically executed at next reboot.
+command is used to create an EFI capsule file to be used by U-Boot for firmware
+updates.
+A capsule file may contain various types of firmware blobs which are to be
+applied to the system.
+If a capsule file is placed in the /EFI/CapusuleUpdate directory of the EFI
+system partition, U-Boot will try to execute the update at the next reboot.
 
 Optionally, a capsule file can be signed with a given private key.
 In this case, the update will be authenticated by verifying the signature
 before applying.
 
-Additionally, an empty capsule file can be generated for acceptance or
-rejection of firmware images by a governing component like an Operating
-System. The empty capsules do not require an image-blob input file.
-
+Additionally, an empty capsule file can be generated to indicate the acceptance
+or rejection of firmware images by a governing component like an operating
+system.
+Empty capsules do not require an image-blob input file.
 
 .B mkeficapsule
 takes any type of image files when generating non empty capsules, including:
diff --git a/doc/usage/cmd/bdinfo.rst b/doc/usage/cmd/bdinfo.rst
index 6b3cde2ccb..b287d0ff73 100644
--- a/doc/usage/cmd/bdinfo.rst
+++ b/doc/usage/cmd/bdinfo.rst
@@ -17,7 +17,7 @@ Description
 The *bdinfo* command prints information about the board.
 
 Example
-=======
+-------
 
 ::
 
diff --git a/doc/usage/cmd/font.rst b/doc/usage/cmd/font.rst
index 6fb0823270..8ba149d759 100644
--- a/doc/usage/cmd/font.rst
+++ b/doc/usage/cmd/font.rst
@@ -12,33 +12,27 @@ Synopis
     font select <name> [<size>]
     font size <size>
 
-
 Description
 -----------
 
 The *font* command allows selection of the font to use on the video console.
-This is available when the Truetype console is in use. This is the case when
-`CONFIG_CONSOLE_TRUETYPE` is enabled.
-
+This is available when the TrueType console is in use.
 
 font list
 ~~~~~~~~~
 
 This lists the available fonts, using the name of the font file in the build.
 
-
 font select
 ~~~~~~~~~~~
 
 This selects a new font and optionally changes the size.
 
-
 font size
 ~~~~~~~~~
 
 This changes the font size only.
 
-
 Examples
 --------
 
@@ -50,3 +44,14 @@ Examples
     => font size 40
     => font select cantoraone_regular 20
     =>
+
+Configuration
+-------------
+
+The command is only available if CONFIG_CONSOLE_TRUETYPE=y.
+
+Return value
+------------
+
+The return value $? is 0 (true) if the command completes.
+The return value is 1 (false) if the command fails.
diff --git a/doc/usage/cmd/mtest.rst b/doc/usage/cmd/mtest.rst
new file mode 100644
index 0000000000..81d1f8fd1b
--- /dev/null
+++ b/doc/usage/cmd/mtest.rst
@@ -0,0 +1,66 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright 2022, Heinrich Schuchardt <xypron.glpk@gmx.de>
+
+mtest command
+=============
+
+Synopsis
+--------
+
+::
+
+    mtest [start [end [pattern [iterations]]]]
+
+Description
+-----------
+
+The *mtest* command tests the random access memory. It writes long values, reads
+them back and checks for differences. The test can be interrupted with CTRL+C.
+
+The default test uses *pattern* as first value to be written and varies it
+between memory addresses.
+
+An alternative test can be selected with CONFIG_SYS_ALT_MEMTEST=y. It uses
+multiple hard coded bit patterns.
+
+With CONFIGSYS_ALT_MEMTEST_BITFLIP=y a further test is executed. It writes long
+values offset by half the size of long and checks if writing to the one address
+causes bit flips at the other address.
+
+start
+	start address of the memory range tested, defaults to
+	CONFIG_SYS_MEMTEST_START
+
+end
+	end address of the memory range tested, defaults to
+	CONFIG_SYS_MEMTEST_END. If CONFIGSYS_ALT_MEMTEST_BITFLIP=y, a value will
+	be written to this address. Otherwise it is excluded from the range.
+
+pattern
+	pattern to be written to memory. This is a 64bit value on 64bit systems
+	and a 32bit value on 32bit systems. It defaults to 0. The value is
+	ignored if CONFIG_SYS_ALT_MEMTEST=y.
+
+iterations
+	number of test repetitions. If the value is not provided the test will
+	not terminate automatically. Enter CTRL+C instead.
+
+Examples
+--------
+
+::
+
+    => mtest 1000 2000 0x55aa55aa55aa55aa 10
+    Testing 00001000 ... 00002000:
+    Pattern AA55AA55AA55AA55  Writing...  Reading...
+    Tested 16 iteration(s) with 0 errors.
+
+Configuration
+-------------
+
+The mtest command is enabled by CONFIG_CMD_MEMTEST=y.
+
+Return value
+------------
+
+The return value $? is 0 (true) if the command succeeds, 1 (false) otherwise.
diff --git a/doc/usage/cmd/sleep.rst b/doc/usage/cmd/sleep.rst
new file mode 100644
index 0000000000..d19e5b3af8
--- /dev/null
+++ b/doc/usage/cmd/sleep.rst
@@ -0,0 +1,45 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright 2023, Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
+
+sleep command
+=============
+
+Synopsis
+--------
+
+::
+
+    sleep <delay>
+
+Description
+-----------
+
+The *sleep* command waits for *delay* seconds. It can be interrupted by
+CTRL+C.
+
+delay
+   delay in seconds. The value is decimal and can be fractional.
+
+Example
+-------
+
+The current data and time is display before and after sleeping for 3.2
+seconds:
+
+::
+
+    => date; sleep 3.2; date
+    Date: 2023-01-21 (Saturday)    Time: 16:02:41
+    Date: 2023-01-21 (Saturday)    Time: 16:02:44
+    =>
+
+Configuration
+-------------
+
+The command is only available if CONFIG_CMD_SLEEP=y.
+
+Return value
+------------
+
+The return value $? is 0 (true) if the command completes.
+The return value is 1 (false) if the command is interrupted by CTRL+C.
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index 7d4a1cbc10..2c95471f45 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -63,6 +63,7 @@ Shell commands
    cmd/mbr
    cmd/md
    cmd/mmc
+   cmd/mtest
    cmd/part
    cmd/pause
    cmd/pinmux
@@ -76,6 +77,7 @@ Shell commands
    cmd/scp03
    cmd/setexpr
    cmd/size
+   cmd/sleep
    cmd/sound
    cmd/source
    cmd/temperature