Pull request for doc-2023-10-rc4

Documentation:
 
 * Fix documentation for TI boards
 * Describe running on VirtualBox
 * List build dependencies for building documenation
 * Add references to U-Boot talks
 
 Other:
 
 * Fix error handling in the setexpr command (printf_str)
 -----BEGIN PGP SIGNATURE-----
 
 iQIzBAABCAAdFiEEbcT5xx8ppvoGt20zxIHbvCwFGsQFAmTlrkIACgkQxIHbvCwF
 GsQZew/8CBzzL3LzxRh4GZLVfXjgdYT5gQ068G9+ZWBg6UFwM58RruuAdjU+UDc4
 jDM2I2V+4g3Yc8b3+eJzOlbw5DXaSrfwswERTkjq7HRGBr573LFwY7S5eXc2qefj
 /+2dy4lF+7GZjfcH0EKSThye0AT+/xkvjBFjbJGlfmgE6oUP+rCbKVQXwKSwq66T
 x18z6Qi8pM18bGjRSqzR3M14NEHwmnybG+qgziBecc0ruaLbLsW05wEprQzZZNRJ
 Ywr95Bd32R/3iR/BDcsS0Z79S9SmcKrj3nTpJb800dY2hmhVGX3JRTN1wz5YBf4O
 9nMVNEyaYAH5816Wp+cw2/Jr0QmwTjChs4kXMtOfKv/SwJxEd0boMWIjodwGNQpe
 HY13NiKMh3fe9omq+WoN0+zbGA2OtLIfdRiE00STdFrCzHIIQNF9KEwaAMcmSy89
 WiR+WyBdHvpDbNVVaHoWfo6GsxXkqpFbPHSY8Lf0juwA4JMZ6htKTC4wuxLpK/WD
 nYxpsOL7+I0iKmOpiusvbwON1GaiZp0IQgZsHm5e1OVDaJmT2S2CsLj0lP1fHdcT
 FzBbkrCTmAeWGTgg0MyqJCC3+QGv/ES7r76tA5DgKJ/+04+BlIQxc2MS6fRRckGc
 OUXMVdaNAY6WuW0LzUABejOKX8URmaZEEQDUvASFngDEuzks4d0=
 =E6SF
 -----END PGP SIGNATURE-----

Merge tag 'doc-2023-10-rc4' of https://source.denx.de/u-boot/custodians/u-boot-efi

Pull request for doc-2023-10-rc4

Documentation:

* Fix documentation for TI boards
* Describe running on VirtualBox
* List build dependencies for building documenation
* Add references to U-Boot talks

Other:

* Fix error handling in the setexpr command (printf_str)

cmd/printf.c

@@ -144,10 +144,10 @@ static void printf_str(struct print_inf *inf, char *format, ...)
 	i = vsnprintf(inf->str + inf->offset, remaining, format, args);
 	va_end(args);
 
-	if (i >= remaining)
+	if (i < 0)
-		inf->error |= PRINT_TRUNCATED_ERROR;
-	else if (i < 0)
 		inf->error |= PRINT_CONVERSION_ERROR;
+	else if ((unsigned int)i >= remaining)
+		inf->error |= PRINT_TRUNCATED_ERROR;
 	else
 		inf->offset += i;
 }

doc/board/ti/am62x_sk.rst

@@ -47,6 +47,7 @@ Boot Flow:
 Below is the pictorial representation of boot flow:
 
 .. image:: img/boot_diagram_k3_current.svg
+  :alt: Boot flow diagram
 
 - Here TIFS acts as master and provides all the critical services. R5/A53
   requests TIFS to get these services done as shown in the above diagram.
@@ -102,13 +103,13 @@ Set the variables corresponding to this platform:
 
 3. U-Boot:
 
-* 4.1 R5:
+* 3.1 R5:
 
 .. include::  ../ti/k3.rst
     :start-after: .. k3_rst_include_start_build_steps_spl_r5
     :end-before: .. k3_rst_include_end_build_steps_spl_r5
 
-* 4.2 A53:
+* 3.2 A53:
 
 .. include::  ../ti/k3.rst
     :start-after: .. k3_rst_include_start_build_steps_uboot
@@ -141,10 +142,12 @@ Image formats:
 - tiboot3.bin
 
 .. image:: img/multi_cert_tiboot3.bin.svg
+  :alt: tiboot3.bin image format
 
 - tispl.bin
 
 .. image:: img/dm_tispl.bin.svg
+  :alt: tispl.bin image format
 
 A53 SPL DDR Memory Layout
 -------------------------

doc/board/ti/am65x_evm.rst

@@ -46,6 +46,7 @@ applications. This should happen before running Linux.
 instead use Falcon boot flow to reduce boot time.
 
 .. image:: img/boot_diagram_am65.svg
+  :alt: Boot flow diagram
 
 - Here DMSC acts as master and provides all the critical services. R5/A53
   requests DMSC to get these services done as shown in the above diagram.
@@ -102,13 +103,13 @@ Set the variables corresponding to this platform:
 
 3. U-Boot:
 
-* 4.1 R5:
+* 3.1 R5:
 
 .. include::  k3.rst
     :start-after: .. k3_rst_include_start_build_steps_spl_r5
     :end-before: .. k3_rst_include_end_build_steps_spl_r5
 
-* 4.2 A53:
+* 3.2 A53:
 
 .. include::  k3.rst
     :start-after: .. k3_rst_include_start_build_steps_uboot
@@ -122,13 +123,13 @@ Each SoC variant (GP and HS) requires a different source for these files.
 
 - GP
 
-        * tiboot3-am65x_sr2-gp-evm.bin, sysfw-am65x_sr2-gp-evm.itb from step 4.1
+        * tiboot3-am65x_sr2-gp-evm.bin, sysfw-am65x_sr2-gp-evm.itb from step 3.1
-        * tispl.bin_unsigned, u-boot.img_unsigned from step 4.2
+        * tispl.bin_unsigned, u-boot.img_unsigned from step 3.2
 
 - HS
 
-        * tiboot3-am65x_sr2-hs-evm.bin, sysfw-am65x_sr2-hs-evm.itb from step 4.1
+        * tiboot3-am65x_sr2-hs-evm.bin, sysfw-am65x_sr2-hs-evm.itb from step 3.1
-        * tispl.bin, u-boot.img from step 4.2
+        * tispl.bin, u-boot.img from step 3.2
 
 Image formats:
 --------------
@@ -136,14 +137,17 @@ Image formats:
 - tiboot3.bin
 
 .. image:: img/no_multi_cert_tiboot3.bin.svg
+  :alt: tiboot3.bin image format
 
 - tispl.bin
 
 .. image:: img/nodm_tispl.bin.svg
+  :alt: tispl.bin image format
 
 - sysfw.itb
 
 .. image:: img/sysfw.itb.svg
+  :alt: sysfw.itb image format
 
 eMMC:
 -----
@@ -185,6 +189,7 @@ used:
 eMMC layout:
 
 .. image:: img/emmc_am65x_evm_boot0.svg
+  :alt: emmc boot partition layout
 
 Kernel image and DT are expected to be present in the /boot folder of rootfs.
 To boot kernel from eMMC, use the following commands:
@@ -220,6 +225,7 @@ addresses.
 Flash layout for OSPI:
 
 .. image:: img/ospi_sysfw.svg
+  :alt: OSPI flash partition layout
 
 Kernel Image and DT are expected to be present in the /boot folder of UBIFS
 ospi.rootfs just like in SD card case. U-Boot looks for UBI volume named

doc/board/ti/j7200_evm.rst

@@ -35,6 +35,7 @@ Boot Flow:
 Below is the pictorial representation of boot flow:
 
 .. image:: img/boot_diagram_k3_current.svg
+  :alt: Boot flow diagram
 
 - Here DMSC acts as master and provides all the critical services. R5/A72
   requests DMSC to get these services done as shown in the above diagram.
@@ -91,13 +92,13 @@ Set the variables corresponding to this platform:
 
 3. U-Boot:
 
-* 4.1 R5:
+* 3.1 R5:
 
 .. include::  k3.rst
     :start-after: .. k3_rst_include_start_build_steps_spl_r5
     :end-before: .. k3_rst_include_end_build_steps_spl_r5
 
-* 4.2 A72:
+* 3.2 A72:
 
 .. include::  k3.rst
     :start-after: .. k3_rst_include_start_build_steps_uboot
@@ -111,18 +112,18 @@ variant (GP, HS-FS, HS-SE) requires a different source for these files.
 
  - GP
 
-        * tiboot3-j7200-gp-evm.bin from step 4.1
+        * tiboot3-j7200-gp-evm.bin from step 3.1
-        * tispl.bin_unsigned, u-boot.img_unsigned from step 4.2
+        * tispl.bin_unsigned, u-boot.img_unsigned from step 3.2
 
  - HS-FS
 
-        * tiboot3-j7200_sr2-hs-fs-evm.bin from step 4.1
+        * tiboot3-j7200_sr2-hs-fs-evm.bin from step 3.1
-        * tispl.bin, u-boot.img from step 4.2
+        * tispl.bin, u-boot.img from step 3.2
 
  - HS-SE
 
-        * tiboot3-j7200_sr2-hs-evm.bin from step 4.1
+        * tiboot3-j7200_sr2-hs-evm.bin from step 3.1
-        * tispl.bin, u-boot.img from step 4.2
+        * tispl.bin, u-boot.img from step 3.2
 
 Image formats:
 --------------
@@ -130,12 +131,12 @@ Image formats:
 - tiboot3.bin
 
 .. image:: img/j7200_tiboot3.bin.svg
+  :alt: tiboot3.bin image format
 
 - tispl.bin
 
 .. image:: img/dm_tispl.bin.svg
-
+  :alt: tispl.bin image format
-
 
 Switch Setting for Boot Mode
 ----------------------------
@@ -191,6 +192,7 @@ Size of u-boot.img is taken 4MB for refernece,
 But this is subject to change depending upon atf, optee size
 
 .. image:: img/emmc_j7200_evm_boot01.svg
+  :alt: Traditional eMMC boot partition layout
 
 In case of UDA FS mode booting, following is layout.
 
@@ -198,6 +200,7 @@ All boot images tiboot3.bin, tispl and u-boot should be written to
 fat formatted UDA FS as file.
 
 .. image:: img/emmc_j7200_evm_udafs.svg
+  :alt: eMMC UDA boot partition layout
 
 In case of booting from eMMC, write above images into raw or UDA FS.
 and set mmc partconf accordingly.

doc/board/ti/j721e_evm.rst

@@ -40,6 +40,7 @@ Boot flow is similar to that of AM65x SoC and extending it with remoteproc
 support. Below is the pictorial representation of boot flow:
 
 .. image:: img/boot_diagram_j721e.svg
+  :alt: Boot flow diagram
 
 - Here DMSC acts as master and provides all the critical services. R5/A72
   requests DMSC to get these services done as shown in the above diagram.
@@ -96,13 +97,13 @@ Set the variables corresponding to this platform:
 
 3. U-Boot:
 
-* 4.1 R5:
+* 3.1 R5:
 
 .. include::  k3.rst
     :start-after: .. k3_rst_include_start_build_steps_spl_r5
     :end-before: .. k3_rst_include_end_build_steps_spl_r5
 
-* 4.2 A72:
+* 3.2 A72:
 
 .. include::  k3.rst
     :start-after: .. k3_rst_include_start_build_steps_uboot
@@ -117,18 +118,18 @@ files.
 
  - GP
 
-        * tiboot3-j721e-gp-evm.bin, sysfw-j721e-gp-evm.itb from step 4.1
+        * tiboot3-j721e-gp-evm.bin, sysfw-j721e-gp-evm.itb from step 3.1
-        * tispl.bin_unsigned, u-boot.img_unsigned from step 4.2
+        * tispl.bin_unsigned, u-boot.img_unsigned from step 3.2
 
  - HS-FS
 
-        * tiboot3-j721e_sr2-hs-fs-evm.bin, sysfw-j721e_sr2-hs-fs-evm.itb from step 4.1
+        * tiboot3-j721e_sr2-hs-fs-evm.bin, sysfw-j721e_sr2-hs-fs-evm.itb from step 3.1
-        * tispl.bin, u-boot.img from step 4.2
+        * tispl.bin, u-boot.img from step 3.2
 
  - HS-SE
 
-        * tiboot3-j721e_sr2-hs-evm.bin, sysfw-j721e_sr2-hs-evm.itb from step 4.1
+        * tiboot3-j721e_sr2-hs-evm.bin, sysfw-j721e_sr2-hs-evm.itb from step 3.1
-        * tispl.bin, u-boot.img from step 4.2
+        * tispl.bin, u-boot.img from step 3.2
 
 Image formats:
 --------------
@@ -136,14 +137,17 @@ Image formats:
 - tiboot3.bin
 
 .. image:: img/no_multi_cert_tiboot3.bin.svg
+  :alt: tiboot3.bin image format
 
 - tispl.bin
 
 .. image:: img/dm_tispl.bin.svg
+  :alt: tispl.bin image format
 
 - sysfw.itb
 
 .. image:: img/sysfw.itb.svg
+  :alt: sysfw.itb image format
 
 R5 Memory Map:
 --------------
@@ -213,6 +217,7 @@ addresses.
 Flash layout for OSPI:
 
 .. image:: img/ospi_sysfw.svg
+  :alt: OSPI flash partition layout
 
 Firmwares:
 ----------

doc/board/ti/k3.rst

@@ -47,6 +47,7 @@ including a 32bit U-Boot SPL, (called the wakup SPL) that ROM will jump
 to after it has finished loading everything into internal SRAM.
 
 .. image:: img/boot_flow_01.svg
+  :alt: Boot flow up to wakeup domain SPL
 
 The wakeup SPL, running on a wakeup domain core, will initialize DDR and
 any peripherals needed load the larger binaries inside the `tispl.bin`
@@ -56,6 +57,7 @@ starting with Trusted Firmware-A (TF-A), before moving on to start
 OP-TEE and the main domain's U-Boot SPL.
 
 .. image:: img/boot_flow_02.svg
+  :alt: Boot flow up to main domain SPL
 
 The main domain's SPL, running on a 64bit application core, has
 virtually unlimited space (billions of bytes now that DDR is working) to
@@ -64,6 +66,7 @@ which loads more firmware into the micro-controller & wakeup domains and
 finally prepare the main domain to run Linux.
 
 .. image:: img/boot_flow_03.svg
+  :alt: Complete boot flow up to Linux
 
 This is the typical boot flow for all K3 based SoCs, however this flow
 offers quite a lot in the terms of flexibility, especially on High
@@ -120,11 +123,30 @@ online
   | **source:** https://github.com/OP-TEE/optee_os.git
   | **branch:** master
 
-* **TI Firmware (TIFS, DM, DSMC)**
+* **TI Firmware (TIFS, DM, SYSFW)**
 
   | **source:** https://git.ti.com/git/processor-firmware/ti-linux-firmware.git
   | **branch:** ti-linux-firmware
 
+.. note::
+
+  The TI Firmware required for functionality of the system can be
+  one of the following combination (see platform specific boot diagram for
+  further information as to which component runs on which processor):
+
+  * **TIFS** - TI Foundational Security Firmware - Consists of purely firmware
+    meant to run on the security enclave.
+  * **DM** - Device Management firmware also called TI System Control Interface
+    server (TISCI Server) - This component purely plays the role of managing
+    device resources such as power, clock, interrupts, dma etc. This firmware
+    runs on a dedicated or multi-use microcontroller outside the security
+    enclave.
+
+ OR
+
+  * **SYSFW** - System firmware - consists of both TIFS and DM both running on
+    the security enclave.
+
 .. k3_rst_include_end_boot_sources
 
 Build Procedure
@@ -485,6 +507,7 @@ generation device.
 The overall structure of this setup is in the following figure.
 
 .. image:: img/openocd-overview.svg
+  :alt: Overview of OpenOCD setup.
 
 .. note::
 
@@ -577,7 +600,7 @@ correctly to ensure a sane system.
   $ cd openocd
   # Copy the udev rules to the correct system location
   $ sudo cp ./contrib/60-openocd.rules \
-      ./src/JTAG/drivers/libjaylink/contrib/99-libjaylink.rules \
+      ./src/jtag/drivers/libjaylink/contrib/99-libjaylink.rules \
       /etc/udev/rules.d/
   # Get Udev to load the new rules up
   $ sudo udevadm control --reload-rules
@@ -768,7 +791,7 @@ Code modification
   In this example, we will debug ``board_init_f`` inside
   ``arch/arm/mach-k3/{soc}_init.c``. Since some sections of U-Boot
   will be executed multiple times during the bootup process of K3
-  devices, we will need to include either ``CONFIG_CPU_ARM64`` or
+  devices, we will need to include either ``CONFIG_ARM64`` or
   ``CONFIG_CPU_V7R`` to catch the CPU at the desired place during the
   bootup process (Main or Wakeup domains). For example, modify the
   file as follows (depending on need):
@@ -786,7 +809,7 @@ Code modification
       }
       ...
       /* Code to run on the ARMV8 (Main Domain) */
-      if (IS_ENABLED(CONFIG_CPU_ARM64)) {
+      if (IS_ENABLED(CONFIG_ARM64)) {
           volatile int x = 1;
           while(x) {};
       }

doc/build/documentation.rst

@@ -5,6 +5,17 @@ Building documentation
 
 The U-Boot documentation is based on the Sphinx documentation generator.
 
+In addition to the Python packages listed in ``doc/sphinx/requirements.txt``,
+the following dependencies are needed to build the documentation:
+
+* fontconfig
+
+* graphviz
+
+* imagemagick
+
+* texinfo (if building the `Infodoc documentation`_)
+
 HTML documentation
 ------------------
 

doc/develop/uefi/u-boot_on_efi.rst

@@ -254,6 +254,90 @@ This shows running with serial enabled (see `include/configs/efi-x86_app.h`)::
 
    => QEMU: Terminated
 
+Run on VirtualBox (x86_64)
+--------------------------
+
+Enable EFI
+~~~~~~~~~~
+At settings for virtual machine the flag at **System->Motherboard->Enable EFI
+(special OSes only)** has to be enabled.
+
+Installation
+~~~~~~~~~~~~
+Provide the preinstalled Linux system as a Virtual Disk Image (VDI) and assign
+it to a SATA controller (type AHCI) using the settings for the virtual machine
+at menu item **System->Storage->Controller:SATA**.
+
+For the following description three GPT partitions are assumed:
+
+- Partition 1: formatted as FAT file-system and marked as EFI system partition
+  (partition type 0xEF00) used for the U-Boot EFI binary. (If VirtualBox is UEFI
+  compliant, it should recognize the ESP as the boot partition.)
+
+- Partition 2: formatted as **ext4**, used for root file system
+
+Create an extlinux.conf or a boot script
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Following files are assumed to be located at system for boot configuration::
+
+ Partition  File                    Comment
+ 1          EFI/BOOT/BOOTX64.efi    # renamed U-Boot EFI image
+ 1          Image                   # Linux image
+ 1          Initrd                  # Initramfs of Linux
+
+**EFI/BOOT/BOOTX64.efi** is a renamed build result **u-boot-payload.efi**, built with
+**efi-x86_payload64_defconfig** configuration.
+
+Boot script
+~~~~~~~~~~~
+
+The boot script **boot.scr** is assumed to be located at::
+
+ Partition  File        Comment
+ 1          boot.scr    # Boot script, generated with mkimage from template
+
+Content of **boot.scr**:
+
+.. code-block:: bash
+
+  ext4load ${devtype} ${devnum}:${distro_bootpart} ${kernel_addr_r} ${prefix}Image
+  setenv kernel_size ${filesize}
+  ext4load ${devtype} ${devnum}:${distro_bootpart} ${ramdisk_addr_r} ${prefix}Initrd
+  setenv initrd_size ${filesize}
+  zboot  ${kernel_addr_r} ${kernel_size} ${ramdisk_addr_r} ${initrd_size}
+
+Extlinux configuration
+~~~~~~~~~~~~~~~~~~~~~~
+
+Alternatively a configuration **extlinux.conf** can be used. **extlinux.conf**
+is assumed to be located at::
+
+ Partition  File                        Comment
+ 1          extlinux/extlinux.conf      # Extlinux boot configuration
+
+Content of **extlinux.conf**:
+
+.. code-block:: bash
+
+  default l0
+  menu title U-Boot menu
+  prompt 0
+  timeout 50
+
+  label l0
+    menu label Linux
+    linux /Image
+    initrd /Initrd
+
+
+Additionally something like (sda is assumed as disk device):
+
+.. code-block:: bash
+
+	append  root=/dev/sda2 console=tty0 console=ttyS0,115200n8 rootwait rw
+
+
 
 Future work
 -----------

doc/learn/talks.rst

@@ -3,9 +3,18 @@
 U-Boot Talks
 ============
 
-U-Boot is a topic at various conferences each year. These talkes might help you
+U-Boot is a topic at various conferences each year. These talks might help you
-learn a bit about U-Boot.
+learn a bit about U-Boot:
 
-See elinux_talks_ for a list.
+* `Tutorial: Introduction to the Embedded Boot Loader U-boot - Behan Webster,
+  Converse in Code <https://www.youtube.com/watch?v=INWghYZH3hI>`__
+  from Embedded Linux Conference 2020
+  (`slides <https://cm.e-ale.org/2020/ELC2020/intro-to-u-boot/intro-to-u-boot-2020.pdf>`__).
+
+* `Recent Advances in U-Boot - Simon Glass, Google Inc.
+  <https://www.youtube.com/watch?v=YlJBsVZJkDI>`__
+  from Embedded Linux Conference 2023.
+
+See elinux_talks_ for a more comprehensive list.
 
 .. _elinux_talks: https://elinux.org/Boot_Loaders#U-Boot