[PATCH v5 17/17] doc:bootmenu: add UEFI boot and distro boot support description

[Masahisa Kojima]

The bootmenu enumerates the UEFI boot options and distro boot
(boot_targets) for boot device selection.

This commit adds the description how the UEFI boot and distro 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>
---
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 | 78 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 77 insertions(+), 1 deletion(-)

diff --git a/doc/usage/cmd/bootmenu.rst b/doc/usage/cmd/bootmenu.rst
index 1016ac8ceb..48f76a82a3 100644
--- a/doc/usage/cmd/bootmenu.rst
+++ b/doc/usage/cmd/bootmenu.rst
@@ -4,7 +4,17 @@
 bootmenu command
 ================
 
-The "bootmenu" command uses U-Boot menu interfaces and provides
+Synopsis
+--------
+
+::
+
+    bootmenu
+
+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
 the items. Current active menu item is highlighted and can be
@@ -79,6 +89,67 @@ 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
+''''''''''''''''''''''''''''''
+
+The bootmenu automatically generates the UEFI boot variable("BOOT####")
+in order of "BootOrder". When the user selects the UEFI boot
+variable entry, bootmenu sets the selected boot variable index
+to "BootNext", then call the uefi boot manager with the command
+"bootefi bootmgr".
+
+The bootmenu automatically enumerates the possible bootable
+media devices supporting EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.
+
+The bootmenu prints the EFI_LOAD_OPTION.Description[] as title
+of the entry together with "UEFI" prefix and BOOT#### variable name.
+
+Example bootmenu is as below::
+
+    *** U-Boot Boot Menu ***
+
+       UEFI BOOT0000 : mmc0:1
+       UEFI BOOT0001 : mmc0:2
+       UEFI BOOT0002 : debian
+       UEFI BOOT0003 : nvme0:1
+       UEFI BOOT0004 : ubuntu
+       UEFI BOOT0005 : nvme0:2
+       UEFI BOOT0006 : usb0:2
+
+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"
+
+distro boot command enumeration
+'''''''''''''''''''''''''''''''
+
+The bootmenu also automatically generates the entries for
+distro boot command. The bootmenu shows the devices in boot_targets
+environment variable.
+When the user selects the distro boot command entry, the bootmenu
+runs the command defined in "bootcmd_xxx" environment variable.
+As an example, if user selects "usb0" entry, bootmenu runs the
+command defined in "bootcmd_usb0".
+
+Example boot_targets::
+
+    usb0, scsi0, nvme0, dhcp
+
+Example bootmenu is as below::
+
+    *** U-Boot Boot Menu ***
+
+       distro_boot   : usb0
+       distro_boot   : scsi0
+       distro_boot   : nvme0
+       distro_boot   : dhcp
+
+Configuration
+-------------
+
 The "bootmenu" cammand is enabled by::
 
     CONFIG_CMD_BOOTMENU=y
@@ -88,3 +159,8 @@ To run the bootmenu at startup add these additional settings::
     CONFIG_AUTOBOOT_KEYED=y
     CONFIG_BOOTDELAY=30
     CONFIG_AUTOBOOT_MENU_SHOW=y
+
+To improve the product security, entering U-Boot console from bootmenu
+can be disabled by::
+
+    CONFIG_CMD_BOOTMENU_ENTER_UBOOT_CONSOLE=n
-- 
2.17.1