Re: [U-Boot] [PATCH v3 2/2] efi_loader: provide new doc/README.uefi

2018-03-02 Thread Leif Lindholm 
On Fri, Mar 02, 2018 at 07:58:50PM +0100, Heinrich Schuchardt wrote:
> Provides information about
> 
> - usage of the bootefi command
> - overview of UEFI
> - interaction between U-Boot and EFI drivers
> 
> Signed-off-by: Heinrich Schuchardt 

Well, from my point of view:
Reviewed-by: Leif Lindholm 
or
Acked-by: Leif Lindholm 
(whichever makes more sense).

Many thanks!

/
Leif

> ---
> v3
>   rename README.efi to README.uefi
>   use UEFI instead of EFI where applicable
> v2
>   split the patch in two: one deleteing all old lines, the other
>   adding the new ones
>   update README contents
> ---
>  MAINTAINERS |   2 +-
>  doc/README.efi  |   0
>  doc/README.uefi | 332 
> 
>  3 files changed, 333 insertions(+), 1 deletion(-)
>  delete mode 100644 doc/README.efi
>  create mode 100644 doc/README.uefi
> 
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 077828cf1d4..da799b551d9 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -290,7 +290,7 @@ EFI PAYLOAD
>  M:   Alexander Graf 
>  S:   Maintained
>  T:   git git://github.com/agraf/u-boot.git
> -F:   doc/README.efi
> +F:   doc/README.uefi
>  F:   doc/README.iscsi
>  F:   include/efi*
>  F:   include/pe.h
> diff --git a/doc/README.efi b/doc/README.efi
> deleted file mode 100644
> index e69de29bb2d..000
> diff --git a/doc/README.uefi b/doc/README.uefi
> new file mode 100644
> index 000..7403be36146
> --- /dev/null
> +++ b/doc/README.uefi
> @@ -0,0 +1,332 @@
> +
> +
> +# UEFI on U-Boot
> +
> +The Unified Extensible Firmware Interface Specification (UEFI) [1] has become
> +the default for booting on AArch64 and x86 systems. It provides a stable API 
> for
> +the interaction of drivers and applications with the firmware. The API 
> comprises
> +access to block storage, network, and console to name a few. The Linux kernel
> +and boot loaders like GRUB or the FreeBSD loader can be executed.
> +
> +## Building for UEFI
> +
> +The UEFI standard supports only little endian systems. The UEFI support can 
> be
> +activated for ARM and x86 by specifying
> +
> +CONFIG_CMD_BOOTEFI=y
> +CONFIG_EFI_LOADER=y
> +
> +in the .config file.
> +
> +Support for attaching virtual block devices, e.g. iSCSI drives connected by 
> the
> +loaded UEFI application [3], requires
> +
> +CONFIG_BLK=y
> +CONFIG_PARTITIONS=y
> +
> +### Executing a UEFI binary
> +
> +The bootefi command is used to start UEFI applications or to install UEFI
> +drivers. It takes two parameters
> +
> +bootefi  [fdt address]
> +
> +* image address - the memory address of the UEFI binary
> +* fdt address - the memory address of the flattened device tree
> +
> +Below you find the output of an example session starting GRUB.
> +
> +=> load mmc 0:2 ${fdt_addr_r} boot/dtb
> +29830 bytes read in 14 ms (2 MiB/s)
> +=> load mmc 0:1 ${kernel_addr_r} efi/debian/grubaa64.efi
> +reading efi/debian/grubaa64.efi
> +120832 bytes read in 7 ms (16.5 MiB/s)
> +=> bootefi ${kernel_addr_r} ${fdt_addr_r}
> +
> +The environment variable 'bootargs' is passed as load options in the UEFI 
> system
> +table. The Linux kernel EFI stub uses the load options as command line
> +arguments.
> +
> +### Executing the boot manager
> +
> +The UEFI specfication foresees to define boot entries and boot sequence via 
> UEFI
> +variables. Booting according to these variables is possible via
> +
> +bootefi bootmgr [fdt address]
> +
> +As of U-Boot v2018.03 UEFI variables are not persisted and cannot be set at
> +runtime.
> +
> +### Executing the built in hello world application
> +
> +A hello world UEFI application can be built with
> +
> +CONFIG_CMD_BOOTEFI_HELLO_COMPILE=y
> +
> +It can be embedded into the U-Boot binary with
> +
> +CONFIG_CMD_BOOTEFI_HELLO=y
> +
> +The bootefi command is used to start the embedded hello world application.
> +
> +bootefi hello [fdt address]
> +
> +Below you find the output of an example session.
> +
> +=> bootefi hello ${fdtcontroladdr}
> +## Starting EFI application at 0100 ...
> +WARNING: using memory device/image path, this may confuse some payloads!
> +Hello, world!
> +Running on UEFI 2.7
> +Have SMBIOS table
> +Have device tree
> +Load options: root=/dev/sdb3 init=/sbin/init rootwait ro
> +## Application terminated, r = 0
> +
> +The environment variable fdtcontroladdr points to U-Boot's internal device 
> tree
> +(if available).
> +
> +### Executing the built-in selftest
> +
> +An UEFI selftest suite can be embedded in U-Boot by building with
> +
> +CONFIG_CMD_BOOTEFI_SELFTEST=y
> +
> +For testing the UEFI implementation the bootefi command can be used to start 
> the
> +selftest.
> +
> +bootefi selftest [fdt address]
> +
> +The environment variable 'efi_selftest' can be used to select a single test. 
> If
> +it is not provided

[U-Boot] [PATCH v3 2/2] efi_loader: provide new doc/README.uefi

2018-03-02 Thread Heinrich Schuchardt 
Provides information about

- usage of the bootefi command
- overview of UEFI
- interaction between U-Boot and EFI drivers

Signed-off-by: Heinrich Schuchardt 
---
v3
rename README.efi to README.uefi
use UEFI instead of EFI where applicable
v2
split the patch in two: one deleteing all old lines, the other
adding the new ones
update README contents
---
 MAINTAINERS |   2 +-
 doc/README.efi  |   0
 doc/README.uefi | 332 
 3 files changed, 333 insertions(+), 1 deletion(-)
 delete mode 100644 doc/README.efi
 create mode 100644 doc/README.uefi

diff --git a/MAINTAINERS b/MAINTAINERS
index 077828cf1d4..da799b551d9 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -290,7 +290,7 @@ EFI PAYLOAD
 M: Alexander Graf 
 S: Maintained
 T: git git://github.com/agraf/u-boot.git
-F: doc/README.efi
+F: doc/README.uefi
 F: doc/README.iscsi
 F: include/efi*
 F: include/pe.h
diff --git a/doc/README.efi b/doc/README.efi
deleted file mode 100644
index e69de29bb2d..000
diff --git a/doc/README.uefi b/doc/README.uefi
new file mode 100644
index 000..7403be36146
--- /dev/null
+++ b/doc/README.uefi
@@ -0,0 +1,332 @@
+
+
+# UEFI on U-Boot
+
+The Unified Extensible Firmware Interface Specification (UEFI) [1] has become
+the default for booting on AArch64 and x86 systems. It provides a stable API 
for
+the interaction of drivers and applications with the firmware. The API 
comprises
+access to block storage, network, and console to name a few. The Linux kernel
+and boot loaders like GRUB or the FreeBSD loader can be executed.
+
+## Building for UEFI
+
+The UEFI standard supports only little endian systems. The UEFI support can be
+activated for ARM and x86 by specifying
+
+CONFIG_CMD_BOOTEFI=y
+CONFIG_EFI_LOADER=y
+
+in the .config file.
+
+Support for attaching virtual block devices, e.g. iSCSI drives connected by the
+loaded UEFI application [3], requires
+
+CONFIG_BLK=y
+CONFIG_PARTITIONS=y
+
+### Executing a UEFI binary
+
+The bootefi command is used to start UEFI applications or to install UEFI
+drivers. It takes two parameters
+
+bootefi  [fdt address]
+
+* image address - the memory address of the UEFI binary
+* fdt address - the memory address of the flattened device tree
+
+Below you find the output of an example session starting GRUB.
+
+=> load mmc 0:2 ${fdt_addr_r} boot/dtb
+29830 bytes read in 14 ms (2 MiB/s)
+=> load mmc 0:1 ${kernel_addr_r} efi/debian/grubaa64.efi
+reading efi/debian/grubaa64.efi
+120832 bytes read in 7 ms (16.5 MiB/s)
+=> bootefi ${kernel_addr_r} ${fdt_addr_r}
+
+The environment variable 'bootargs' is passed as load options in the UEFI 
system
+table. The Linux kernel EFI stub uses the load options as command line
+arguments.
+
+### Executing the boot manager
+
+The UEFI specfication foresees to define boot entries and boot sequence via 
UEFI
+variables. Booting according to these variables is possible via
+
+bootefi bootmgr [fdt address]
+
+As of U-Boot v2018.03 UEFI variables are not persisted and cannot be set at
+runtime.
+
+### Executing the built in hello world application
+
+A hello world UEFI application can be built with
+
+CONFIG_CMD_BOOTEFI_HELLO_COMPILE=y
+
+It can be embedded into the U-Boot binary with
+
+CONFIG_CMD_BOOTEFI_HELLO=y
+
+The bootefi command is used to start the embedded hello world application.
+
+bootefi hello [fdt address]
+
+Below you find the output of an example session.
+
+=> bootefi hello ${fdtcontroladdr}
+## Starting EFI application at 0100 ...
+WARNING: using memory device/image path, this may confuse some payloads!
+Hello, world!
+Running on UEFI 2.7
+Have SMBIOS table
+Have device tree
+Load options: root=/dev/sdb3 init=/sbin/init rootwait ro
+## Application terminated, r = 0
+
+The environment variable fdtcontroladdr points to U-Boot's internal device tree
+(if available).
+
+### Executing the built-in selftest
+
+An UEFI selftest suite can be embedded in U-Boot by building with
+
+CONFIG_CMD_BOOTEFI_SELFTEST=y
+
+For testing the UEFI implementation the bootefi command can be used to start 
the
+selftest.
+
+bootefi selftest [fdt address]
+
+The environment variable 'efi_selftest' can be used to select a single test. If
+it is not provided all tests are executed except those marked as 'on request'.
+If the environment variable is set to 'list' a list of all tests is shown.
+
+Below you can find the output of an example session.
+
+=> setenv efi_selftest simple network protocol
+=> bootefi selftest
+Testing EFI API implementation
+Selected test: 'simple network protocol'
+Setting up 'simple network protocol'
+Setting up 'simple network protocol' succeeded
+Executing 'simple network protocol'
+DHCP Discover
+DHCP reply received from 192.168.76.2