diff options
Diffstat (limited to 'doc/usage')
| -rw-r--r-- | doc/usage/bootefi.rst | 135 | ||||
| -rw-r--r-- | doc/usage/bootmenu.rst | 95 | ||||
| -rw-r--r-- | doc/usage/button.rst | 64 | ||||
| -rw-r--r-- | doc/usage/index.rst | 17 | ||||
| -rw-r--r-- | doc/usage/netconsole.rst | 109 | ||||
| -rw-r--r-- | doc/usage/pstore.rst | 84 |
6 files changed, 504 insertions, 0 deletions
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@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/bootmenu.rst b/doc/usage/bootmenu.rst new file mode 100644 index 0000000000..1f094ad6ed --- /dev/null +++ b/doc/usage/bootmenu.rst @@ -0,0 +1,95 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. (C) Copyright 2011-2012 Pali Rohár <pali@kernel.org> + +bootmenu command +================ + +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 +selected using the "Enter" key. The selection of the highlighted +menu entry invokes an U-Boot command (or a list of commands) +associated with this menu entry. + +The "bootmenu" command interprets ANSI escape sequencies, so +an ANSI terminal is required for proper menu rendering and item +selection. + +The assembling of the menu is done via a set of environment variables +"bootmenu_<num>" and "bootmenu_delay", i.e.:: + + bootmenu_delay=<delay> + bootmenu_<num>="<title>=<commands>" + +<delay> + is the autoboot delay in seconds, after which the first + menu entry will be selected automatically + +<num> + is the boot menu entry number, starting from zero + +<title> + is the text of the menu entry shown on the console + or on the boot screen + +<commands> + are commands which will be executed when a menu + entry is selected + +Title and commands are separated by the first appearance of a '=' +character in the value of the environment variable. + +The first (optional) argument of the "bootmenu" command is a delay specifier +and it overrides the delay value defined by "bootmenu_delay" environment +variable. If the environment variable "bootmenu_delay" is not set or if +the argument of the "bootmenu" command is not specified, the default delay +will be CONFIG_BOOTDELAY. If delay is 0, no menu entries will be shown on +the console (or on the screen) and the command of the first menu entry will +be called immediately. If delay is less then 0, bootmenu will be shown and +autoboot will be disabled. + +Bootmenu always adds menu entry "U-Boot console" at the end of all menu +entries specified by environment variables. When selecting this entry +the bootmenu terminates and the usual U-Boot command prompt is presented +to the user. + +Example environment:: + + setenv bootmenu_0 Boot 1. kernel=bootm 0x82000000 # Set first menu entry + setenv bootmenu_1 Boot 2. kernel=bootm 0x83000000 # Set second menu entry + setenv bootmenu_2 Reset board=reset # Set third menu entry + setenv bootmenu_3 U-Boot boot order=boot # Set fourth menu entry + bootmenu 20 # Run bootmenu with autoboot delay 20s + + +The above example will be rendered as below:: + + *** U-Boot Boot Menu *** + + Boot 1. kernel + Boot 2. kernel + Reset board + U-Boot boot order + U-Boot console + + Hit any key to stop autoboot: 20 + Press UP/DOWN to move, ENTER to select + +The selected menu entry will be highlighted - it will have inverted +background and text colors. + +The "bootmenu" cammand is enabled by:: + + CONFIG_CMD_BOOTMENU=y + +To run the bootmenu at startup add these additional settings:: + + CONFIG_AUTOBOOT_KEYED=y + CONFIG_BOOTDELAY=30 + CONFIG_AUTOBOOT_MENU_SHOW=y + +When you intend to use the bootmenu on a color frame buffer console, +make sure to additionally define:: + + CONFIG_CFB_CONSOLE_ANSI=y diff --git a/doc/usage/button.rst b/doc/usage/button.rst new file mode 100644 index 0000000000..ea41762757 --- /dev/null +++ b/doc/usage/button.rst @@ -0,0 +1,64 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +button command +============== + +Synopsis +-------- + +:: + + button list + button <name> + +Description +----------- + +The button command is used to retrieve the status of a button. To show the +status of a button with name 'button1' you would issue the command + +:: + + button button1 + +The status of the button is both written to the console as *ON* or *OFF* and +set in the return value variable *$?* as 0 (true) or 1 (false). To retrieve +the status of a button with name *button1* and to write it to environment +variable *status1* you would execute the commands + +:: + + button button1 + setenv status1 $? + +A list of all available buttons and their status can be displayed using + +:: + + button list + +If a button device has not been probed yet, its status will be shown as +*<inactive>* in the list. + +Configuration +------------- + +To use the button command you must specify CONFIG_CMD_BUTTON=y and enable a +button driver. The available buttons are defined in the device-tree. + +Return value +------------ + +The variable *$?* takes the following values + ++---+-----------------------------+ +| 0 | ON, the button is pressed | ++---+-----------------------------+ +| 1 | OFF, the button is released | ++---+-----------------------------+ +| 0 | button list was shown | ++---+-----------------------------+ +| 1 | button not found | ++---+-----------------------------+ +| 1 | invalid arguments | ++---+-----------------------------+ diff --git a/doc/usage/index.rst b/doc/usage/index.rst new file mode 100644 index 0000000000..fbb2c0481c --- /dev/null +++ b/doc/usage/index.rst @@ -0,0 +1,17 @@ +Use U-Boot +========== + +.. toctree:: + + netconsole + +Shell commands +-------------- + +.. toctree:: + :maxdepth: 1 + + bootefi + bootmenu + button + pstore diff --git a/doc/usage/netconsole.rst b/doc/usage/netconsole.rst new file mode 100644 index 0000000000..0156f0212d --- /dev/null +++ b/doc/usage/netconsole.rst @@ -0,0 +1,109 @@ +Network console +=============== + +In U-Boot, we implemented the networked console via the standard +"devices" mechanism, which means that you can switch between the +serial and network input/output devices by adjusting the 'stdin' and +'stdout' environment variables. To switch to the networked console, +set either of these variables to "nc". Input and output can be +switched independently. + +The default buffer size can be overridden by setting +CONFIG_NETCONSOLE_BUFFER_SIZE. + +We use an environment variable 'ncip' to set the IP address and the +port of the destination. The format is <ip_addr>:<port>. If <port> is +omitted, the value of 6666 is used. If the env var doesn't exist, the +broadcast address and port 6666 are used. If it is set to an IP +address of 0 (or 0.0.0.0) then no messages are sent to the network. +The source / listening port can be configured separately by setting +the 'ncinport' environment variable and the destination port can be +configured by setting the 'ncoutport' environment variable. + +For example, if your server IP is 192.168.1.1, you could use:: + + => setenv nc 'setenv stdout nc;setenv stdin nc' + => setenv ncip 192.168.1.1 + => saveenv + => run nc + +On the host side, please use this script to access the console + +.. code-block:: bash + + tools/netconsole <ip> [port] + +The script uses netcat to talk to the board over UDP. It requires you to +specify the target IP address (or host name, assuming DNS is working). The +script can be interrupted by pressing ^T (CTRL-T). + +Be aware that in some distributives (Fedora Core 5 at least) +usage of nc has been changed and -l and -p options are considered +as mutually exclusive. If nc complains about options provided, +you can just remove the -p option from the script. + +It turns out that 'netcat' cannot be used to listen to broadcast +packets. We developed our own tool 'ncb' (see tools directory) that +listens to broadcast packets on a given port and dumps them to the +standard output. It will be built when compiling for a board which +has CONFIG_NETCONSOLE defined. If the netconsole script can find it +in PATH or in the same directory, it will be used instead. + +For Linux, the network-based console needs special configuration. +Minimally, the host IP address needs to be specified. This can be +done either via the kernel command line, or by passing parameters +while loading the netconsole.o module (when used in a loadable module +configuration). Please refer to Documentation/networking/logging.txt +file for the original Ingo Molnar's documentation on how to pass +parameters to the loadable module. + +The format of the kernel command line parameter (for the static +configuration) is as follows + +.. code-block:: bash + + netconsole=[src-port]@[src-ip]/[<dev>],[tgt-port]@<tgt-ip>/[tgt-macaddr] + +where + +src-port + source for UDP packets (defaults to 6665) + +src-ip + source IP to use (defaults to the interface's address) + +dev + network interface (defaults to eth0) + +tgt-port + port for logging agent (defaults to 6666) + +tgt-ip + IP address for logging agent (this is the required parameter) + +tgt-macaddr + ethernet MAC address for logging agent (defaults to broadcast) + +Examples + +.. code-block:: bash + + netconsole=4444@10.0.0.1/eth1,9353@10.0.0.2/12:34:56:78:9a:bc + netconsole=@/,@192.168.3.1/ + +Please note that for the Linux networked console to work, the +ethernet interface has to be up by the time the netconsole driver is +initialized. This means that in case of static kernel configuration, +the respective Ethernet interface has to be brought up using the "IP +Autoconfiguration" kernel feature, which is usually done by defaults +in the ELDK-NFS-based environment. + +To browse the Linux network console output, use the 'netcat' tool invoked +as follows: + +.. code-block:: bash + + nc -u -l -p 6666 + +Note that unlike the U-Boot implementation the Linux netconsole is +unidirectional, i. e. you have console output only in Linux. diff --git a/doc/usage/pstore.rst b/doc/usage/pstore.rst new file mode 100644 index 0000000000..8c4e5274aa --- /dev/null +++ b/doc/usage/pstore.rst @@ -0,0 +1,84 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +PStore command +============== + +Design +------ + +Linux PStore and Ramoops modules (Linux config options PSTORE and PSTORE_RAM) +allow to use memory to pass data from the dying breath of a crashing kernel to +its successor. This command allows to read those records from U-Boot command +line. + +Ramoops is an oops/panic logger that writes its logs to RAM before the system +crashes. It works by logging oopses and panics in a circular buffer. Ramoops +needs a system with persistent RAM so that the content of that area can survive +after a restart. + +Ramoops uses a predefined memory area to store the dump. + +Ramoops parameters can be passed as kernel parameters or through Device Tree, +i.e.:: + + ramoops.mem_address=0x30000000 ramoops.mem_size=0x100000 ramoops.record_size=0x2000 ramoops.console_size=0x2000 memmap=0x100000$0x30000000 + +The same values should be set in U-Boot to be able to retrieve the records. +This values can be set at build time in U-Boot configuration file, or at runtime. +U-Boot automatically patches the Device Tree to pass the Ramoops parameters to +the kernel. + +The PStore configuration parameters are: + +======================= ========== + Name Default +======================= ========== +CMD_PSTORE_MEM_ADDR +CMD_PSTORE_MEM_SIZE 0x10000 +CMD_PSTORE_RECORD_SIZE 0x1000 +CMD_PSTORE_CONSOLE_SIZE 0x1000 +CMD_PSTORE_FTRACE_SIZE 0x1000 +CMD_PSTORE_PMSG_SIZE 0x1000 +CMD_PSTORE_ECC_SIZE 0 +======================= ========== + +Records sizes should be a power of 2. +The memory size and the record/console size must be non-zero. + +Multiple 'dump' records can be stored in the memory reserved for PStore. +The memory size has to be larger than the sum of the record sizes, i.e.:: + + MEM_SIZE >= RECORD_SIZE * n + CONSOLE_SIZE + FTRACE_SIZE + PMSG_SIZE + +Usage +----- + +Generate kernel crash +~~~~~~~~~~~~~~~~~~~~~ + +For test purpose, you can generate a kernel crash by setting reboot timeout to +10 seconds and trigger a panic + +.. code-block:: console + + $ sudo sh -c "echo 1 > /proc/sys/kernel/sysrq" + $ sudo sh -c "echo 10 > /proc/sys/kernel/panic" + $ sudo sh -c "echo c > /proc/sysrq-trigger" + +Retrieve logs in U-Boot +~~~~~~~~~~~~~~~~~~~~~~~ + +First of all, unless PStore parameters as been set during U-Boot configuration +and match kernel ramoops parameters, it needs to be set using 'pstore set', e.g.:: + + => pstore set 0x30000000 0x100000 0x2000 0x2000 + +Then all available dumps can be displayed +using:: + + => pstore display + +Or saved to an existing directory in an Ext2 or Ext4 partition, e.g. on root +directory of 1st partition of the 2nd MMC:: + + => pstore save mmc 1:1 / |