[PATCH v2 1/1] doc: man-page for bootefi command

[Heinrich Schuchardt]

Provide a description of the bootefi command.

Signed-off-by: Heinrich Schuchardt <xypron.glpk at gmx.de>
---
v2:
	Replace ".. code-block::" by "::" as the build-system on Gitlab
	does not like code-block without language. The problem did not
	occur locally.
---
 MAINTAINERS           |   1 +
 doc/usage/bootefi.rst | 135 ++++++++++++++++++++++++++++++++++++++++++
 doc/usage/index.rst   |   1 +
 3 files changed, 137 insertions(+)
 create mode 100644 doc/usage/bootefi.rst

diff --git a/MAINTAINERS b/MAINTAINERS
index 127e30c0a5..8675965fe5 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -679,6 +679,7 @@ S:	Maintained
 T:	git https://gitlab.denx.de/u-boot/custodians/u-boot-efi.git
 F:	doc/api/efi.rst
 F:	doc/uefi/*
+F:	doc/usage/bootefi.rst
 F:	drivers/rtc/emul_rtc.c
 F:	include/capitalization.h
 F:	include/charset.h
diff --git a/doc/usage/bootefi.rst b/doc/usage/bootefi.rst
new file mode 100644
index 0000000000..282f22aac9
--- /dev/null
+++ b/doc/usage/bootefi.rst
@@ -0,0 +1,135 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. Copyright 2020, Heinrich Schuchardt <xypron.glpk at 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/doc/usage/index.rst b/doc/usage/index.rst
index 6c4b5b9240..fbb2c0481c 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -11,6 +11,7 @@ Shell commands
 .. toctree::
    :maxdepth: 1

+   bootefi
    bootmenu
    button
    pstore
--
2.29.2