[RESEND v9 8/9] doc:bootmenu: add description for UEFI boot support

[Ilias Apalodimas]

Hi Kojima-san

On Fri, 15 Jul 2022 at 17:45, Masahisa Kojima
<masahisa.kojima at linaro.org> wrote:
>
> The bootmenu enumerates the UEFI boot options
> for boot device selection.
> This commit adds the description how the UEFI boot work
> in bootmenu. This commit also adds "Synopsis", "Description"
> and "Configuration" sections to follow the U-Boot command
> documentation format.
>
> Signed-off-by: Masahisa Kojima <masahisa.kojima at linaro.org>
> ---
> No change since v7
>
> Changes in v7:
> - update the description what bootmenu do for uefi-related boot menu
> - add default behavior when user exits from bootmenu
>
> Changes in v6:
> - remove distro boot related contents because the distro boot
> support in bootmenu is dropped
> - update uefi entry example
> - add [delay] argument of bootmenu command
> - add description to enable uefi boot entry
>
> Changes in v5:
> - follow the cmd documentation format same as other command, add "Synopsis",
>   "Description" add "Configuration" sections
>
> Newly created in v4
>
>  doc/usage/cmd/bootmenu.rst | 74 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 74 insertions(+)
>
> diff --git a/doc/usage/cmd/bootmenu.rst b/doc/usage/cmd/bootmenu.rst
> index 9430f8c9aa..69435090a2 100644
> --- a/doc/usage/cmd/bootmenu.rst
> +++ b/doc/usage/cmd/bootmenu.rst
> @@ -4,6 +4,15 @@
>  bootmenu command
>  ================
>
> +Synopsis
> +--------
> +::
> +
> +    bootmenu [delay]
> +
> +Description
> +-----------
> +
>  The "bootmenu" command uses U-Boot menu interfaces and provides
>  a simple mechanism for creating menus with different boot items.
>  The cursor keys "Up" and "Down" are used for navigation through
> @@ -79,6 +88,55 @@ The above example will be rendered as below::
>  The selected menu entry will be highlighted - it will have inverted
>  background and text colors.
>
> +UEFI boot variable enumeration
> +''''''''''''''''''''''''''''''
> +If enabled, the bootmenu command will automatically generate and add
> +UEFI-related boot menu entries for the following items.
> +
> + * possible bootable media with default file names
> + * user-defined UEFI boot options
> +
> +The bootmenu automatically enumerates the possible bootable
> +media devices supporting EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.
> +This auto generated entry is named as "<interface> <devnum>:<part>" format.
> +(e.g. "usb 0:1")
> +
> +The bootmenu displays the UEFI-related menu entries in order of "BootOrder".
> +When the user selects the UEFI boot menu entry, the bootmenu sets
> +the selected boot variable index to "BootNext" without non-volatile attribute,
> +then call the uefi boot manager with the command "bootefi bootmgr".
> +
> +Example bootmenu is as below::
> +
> +    *** U-Boot Boot Menu ***
> +
> +       mmc 0:1
> +       mmc 0:2
> +       debian
> +       nvme 0:1
> +       ubuntu
> +       nvme 0:2
> +       usb 0:2
> +       U-Boot console
> +
> +Default behavior when user exits from the bootmenu
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +User can exit from bootmenu by selecting the last entry
> +"U-Boot console"/"Quit" or ESC/CTRL+C key.
> +
> +When the CONFIG_BOOTMENU_DISABLE_UBOOT_CONSOLE is disabled,
> +user exits from the bootmenu and returns to the U-Boot console.
> +
> +When the CONFIG_BOOTMENU_DISABLE_UBOOT_CONSOLE is enabled, user can not
> +enter the U-Boot console. When the user exits from the bootmenu,
> +the bootmenu invokes the following default behabior.

Behavior

> +
> + * if CONFIG_CMD_BOOTEFI_BOOTMGR is enabled, execute "bootefi bootmgr" command
> + * "bootefi bootmgr" fails or is not enabled, then execute "run bootcmt" command.

"run bootcmd"

> +
> +Configuration
> +-------------
> +
>  The "bootmenu" command is enabled by::
>
>      CONFIG_CMD_BOOTMENU=y
> @@ -88,3 +146,19 @@ To run the bootmenu at startup add these additional settings::
>      CONFIG_AUTOBOOT_KEYED=y
>      CONFIG_BOOTDELAY=30
>      CONFIG_AUTOBOOT_MENU_SHOW=y
> +
> +UEFI boot variable enumeration is enabled by::
> +
> +    CONFIG_CMD_BOOTEFI_BOOTMGR=y
> +
> +To improve the product security, entering U-Boot console from bootmenu
> +can be disabled by::
> +
> +    CONFIG_BOOTMENU_DISABLE_UBOOT_CONSOLE=y
> +
> +To scan the discoverable devices connected to the buses such as
> +USB and PCIe prior to bootmenu showing up, CONFIG_PREBOOT can be
> +used to run the command before showing the bootmenu, i.e.::
> +
> +    CONFIG_USE_PREBOOT=y
> +    CONFIG_PREBOOT="pci enum; usb start; scsi scan; nvme scan; virtio scan"
> --
> 2.17.1
>

With these changes

Reviewed-by: Ilias Apalodimas <ilias.apalodimas at linaro.org>