Merge tag 'efi-2021-04-rc3' of https://gitlab.denx.de/u-boot/custodians/u-boot-efi

Pull request for efi-2021-04-rc3

Bug fixes:

* Let EFI simple file protocol access last block of partition
* Correct conversion of multi-part device paths in
  EFI_DEVICE_PATH_TO_TEXT_PROTOCOL.ConvertDevicePathToText()

Documentation:

* booti and qfw man-pages

5 files changed, 222 insertions, 15 deletions

diff --git a/doc/README.distro b/doc/README.distro
index cc1c41ecb3..c4f041ca71 100644
--- a/doc/README.distro
+++ b/doc/README.distro
@@ -259,10 +259,10 @@ kernel_addr_r:
 
 kernel_comp_addr_r:
   Optional. This is only required if user wants to boot Linux from a compressed
-  Image(.gz, .bz2, .lzma, .lzo) using booti command. It represents the location
-  in RAM where the compressed Image will be decompressed temporarily. Once the
-  decompression is complete, decompressed data will be moved kernel_addr_r for
-  booting.
+  Image(.gz, .bz2, .lzma, .lzo) using the booti command. It represents the
+  location in RAM where the compressed Image will be decompressed temporarily.
+  Once the decompression is complete, the decompressed data will be moved to
+  kernel_addr_r for booting.
 
 kernel_comp_size:
   Optional. This is only required if user wants to boot Linux from a compressed
diff --git a/doc/conf.py b/doc/conf.py
index 3f456a18f5..eb74b86aef 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -147,9 +147,9 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = 'The Linux Kernel'
-copyright = 'The kernel development community'
-author = 'The kernel development community'
+project = 'Das U-Boot'
+copyright = 'The U-Boot development community'
+author = 'The U-Boot development community'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -260,7 +260,7 @@ except ImportError:
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+html_logo = '../tools/logos/u-boot_logo.svg'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -340,7 +340,7 @@ html_use_smartypants = False
 #html_search_scorer = 'scorer.js'
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'TheLinuxKerneldoc'
+htmlhelp_basename = 'TheUBootdoc'
 
 # -- Options for LaTeX output ---------------------------------------------
 
@@ -470,6 +470,8 @@ if major == 1 and minor < 6:
 #  author, documentclass [howto, manual, or own class]).
 # Sorted in alphabetical order
 latex_documents = [
+    ('index', 'u-boot-hacker-manual.tex', 'U-Boot Hacker Manual',
+     'The U-Boot development community', 'manual'),
 ]
 
 # Add all other index files from Documentation/ subdirectories
@@ -483,8 +485,8 @@ for fn in os.listdir('.'):
                 break
         if not has:
             latex_documents.append((doc, fn + '.tex',
-                                    'Linux %s Documentation' % fn.capitalize(),
-                                    'The kernel development community',
+                                    'U-Boot %s Documentation' % fn.capitalize(),
+                                    'The U-Boot development community',
                                     'manual'))
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -513,7 +515,7 @@ for fn in os.listdir('.'):
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'thelinuxkernel', 'The Linux Kernel Documentation',
+    (master_doc, 'dasuboot', 'The U-Boot Documentation',
      [author], 1)
 ]
 
@@ -527,8 +529,8 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'TheLinuxKernel', 'The Linux Kernel Documentation',
-     author, 'TheLinuxKernel', 'One line description of project.',
+    (master_doc, 'DasUBoot', 'The U-Boot Documentation',
+     author, 'DasUBoot', 'One line description of project.',
      'Miscellaneous'),
 ]
 
@@ -626,7 +628,7 @@ epub_exclude_files = ['search.html']
 # multiple PDF files here actually tries to get the cross-referencing right
 # *between* PDF files.
 pdf_documents = [
-    ('kernel-documentation', u'Kernel', u'Kernel', u'J. Random Bozo'),
+    ('uboot-documentation', u'U-Boot', u'U-Boot', u'J. Random Bozo'),
 ]
 
 # kernel-doc extension configuration for running Sphinx directly (e.g. by Read
diff --git a/doc/usage/booti.rst b/doc/usage/booti.rst
new file mode 100644
index 0000000000..d631fb571d
--- /dev/null
+++ b/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/doc/usage/index.rst b/doc/usage/index.rst
index 5754958d7e..a8842bf9fb 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -15,6 +15,7 @@ Shell commands
 
    base
    bootefi
+   booti
    bootmenu
    button
    conitrace
@@ -27,5 +28,6 @@ Shell commands
    loady
    mbr
    pstore
+   qfw
    sbi
    true
diff --git a/doc/usage/qfw.rst b/doc/usage/qfw.rst
new file mode 100644
index 0000000000..87463e1e5b
--- /dev/null
+++ b/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.