random-mirrors/smaeul-u-boot
1
0
Fork 0
mirror of https://github.com/smaeul/u-boot.git synced 2025-10-25 10:08:21 +01:00
Code Issues Packages Projects Releases Wiki Activity
smaeul-u-boot/doc/README.pxe
Martyn Welch d2faad3ff3 boot: pxe_utils: Add fallback support 
When configured correctly, we can detect when boot fails after the boot
process has been handed over to the kernel through the use of U-Boot's
bootcount support. In some instances, such as when we are performing
atomic updates via a system such as OSTree, it is desirable to provide a
fallback option so that we can return to a previous (hopefully working)
state.

Add a "fallback" option to the supported extlinux configuration options
that points to a label like "default" so that we can utilise this in
later commits.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>
Reviewed-by: Simon Glass <sjg@chromium.org>
2024-10-15 10:24:27 -06:00

292 lines
12 KiB
Plaintext
Raw Blame History

SPDX-License-Identifier: GPL-2.0+
/*
* Copyright 2010-2011 Calxeda, Inc.
*/
The 'pxe' commands provide a near subset of the functionality provided by
the PXELINUX boot loader. This allows U-Boot based systems to be controlled
remotely using the same PXE based techniques that many non U-Boot based servers
use.
Commands
========
pxe get
-------
syntax: pxe get
follows PXELINUX's rules for retrieving configuration files from a tftp
server, and supports a subset of PXELINUX's config file syntax.
Environment
-----------
'pxe get' requires two environment variables to be set:
pxefile_addr_r - should be set to a location in RAM large enough to hold
pxe files while they're being processed. Up to 16 config files may be
held in memory at once. The exact number and size of the files varies with
how the system is being used. A typical config file is a few hundred bytes
long.
bootfile,serverip - these two are typically set in the DHCP response
handler, and correspond to fields in the DHCP response.
'pxe get' optionally supports these two environment variables being set:
ethaddr - this is the standard MAC address for the ethernet adapter in use.
'pxe get' uses it to look for a configuration file specific to a system's
MAC address.
pxeuuid - this is a UUID in standard form using lower case hexadecimal
digits, for example, 550e8400-e29b-41d4-a716-446655440000. 'pxe get' uses
it to look for a configuration file based on the system's UUID.
File Paths
----------
'pxe get' repeatedly tries to download config files until it either
successfully downloads one or runs out of paths to try. The order and
contents of paths it tries mirrors exactly that of PXELINUX - you can
read in more detail about it at:
http://syslinux.zytor.com/wiki/index.php/Doc/pxelinux
pxe boot
--------
syntax: pxe boot [pxefile_addr_r]
Interprets a pxe file stored in memory.
pxefile_addr_r is an optional argument giving the location of the pxe file.
The file must be terminated with a NUL byte.
Environment
-----------
There are some environment variables that may need to be set, depending
on conditions.
pxefile_addr_r - if the optional argument pxefile_addr_r is not supplied,
an environment variable named pxefile_addr_r must be supplied. This is
typically the same value as is used for the 'pxe get' command.
bootfile - typically set in the DHCP response handler based on the
same field in the DHCP respone, this path is used to generate the base
directory that all other paths to files retrieved by 'pxe boot' will use.
If no bootfile is specified, paths used in pxe files will be used as is.
serverip - typically set in the DHCP response handler, this is the IP
address of the tftp server from which other files will be retrieved.
kernel_addr_r, initrd_addr_r - locations in RAM at which 'pxe boot' will
store the kernel(or FIT image) and initrd it retrieves from tftp. These
locations will be passed to the bootm command to boot the kernel. These
environment variables are required to be set.
fdt_addr_r - location in RAM at which 'pxe boot' will store the fdt blob it
retrieves from tftp. The retrieval is possible if 'fdt' label is defined in
pxe file and 'fdt_addr_r' is set. If retrieval is possible, 'fdt_addr_r'
will be passed to bootm command to boot the kernel.
fdt_addr - the location of a fdt blob. 'fdt_addr' will be passed to bootm
command if it is set and 'fdt_addr_r' is not passed to bootm command.
fdtoverlay_addr_r - location in RAM at which 'pxe boot' will temporarily store
fdt overlay(s) before applying them to the fdt blob stored at 'fdt_addr_r'.
pxe_label_override - override label to be used, if exists, instead of the
default label. This will allow consumers to choose a pxe label at
runtime instead of having to prompt the user. If "pxe_label_override" is set
but does not exist in the pxe menu, pxe would fallback to the default label if
given, and no failure is returned but rather a warning message.
pxe file format
===============
The pxe file format is nearly a subset of the PXELINUX file format; see
http://syslinux.zytor.com/wiki/index.php/PXELINUX. It's composed of one line
commands - global commands, and commands specific to labels. Lines begining
with # are treated as comments. White space between and at the beginning of
lines is ignored.
The size of pxe files and the number of labels is only limited by the amount
of RAM available to U-Boot. Memory for labels is dynamically allocated as
they're parsed, and memory for pxe files is statically allocated, and its
location is given by the pxefile_addr_r environment variable. The pxe code is
not aware of the size of the pxefile memory and will outgrow it if pxe files
are too large.
Supported global commands
-------------------------
Unrecognized commands are ignored.
default <label> - the label named here is treated as the default and is
the first label 'pxe boot' attempts to boot.
fallback <label> - the label named here is treated as a fallback option that
may be attempted should it be detected that booting of
the default has failed to complete, for example via
U-Boot's boot count limit functionality.
menu title <string> - sets a title for the menu of labels being displayed.
menu include <path> - use tftp to retrieve the pxe file at <path>, which
is then immediately parsed as if the start of its
contents were the next line in the current file. nesting
of include up to 16 files deep is supported.
prompt <flag> - if 1, always prompt the user to enter a label to boot
from. if 0, only prompt the user if timeout expires.
timeout <num> - wait for user input for <num>/10 seconds before
auto-booting a node.
label <name> - begin a label definition. labels continue until
a command not recognized as a label command is seen,
or EOF is reached.
Supported label commands
------------------------
labels end when a command not recognized as a label command is reached, or EOF.
menu default - set this label as the default label to boot; this is
the same behavior as the global default command but
specified in a different way
kernel <path> - if this label is chosen, use tftp to retrieve the kernel
(or FIT image) at <path>. it will be stored at the address
indicated in the kernel_addr_r environment variable, and
that address will be passed to bootm to boot this kernel.
For FIT image, The configuration specification can be
appended to the file name, with the format:
<path>#<conf>[#<extra-conf[#...]]
It will passed to bootm with that address.
(see: doc/uImage.FIT/command_syntax_extensions.txt)
It useful for overlay selection in pxe file
(see: doc/uImage.FIT/overlay-fdt-boot.txt)
fdtoverlays <path> [...] - if this label is chosen, use tftp to retrieve the DT
overlay(s) at <path>. it will be temporarily stored at the
address indicated in the fdtoverlay_addr_r environment variable,
and then applied in the load order to the fdt blob stored at the
address indicated in the fdt_addr_r environment variable.
devicetree-overlay <path> [...] - if this label is chosen, use tftp to retrieve the DT
overlay(s) at <path>. it will be temporarily stored at the
address indicated in the fdtoverlay_addr_r environment variable,
and then applied in the load order to the fdt blob stored at the
address indicated in the fdt_addr_r environment variable.
Alias for fdtoverlays.
kaslrseed - set this label to request random number from hwrng as kaslr seed.
append <string> - use <string> as the kernel command line when booting this
label.
initrd <path> - if this label is chosen, use tftp to retrieve the initrd
at <path>. it will be stored at the address indicated in
the initrd_addr_r environment variable, and that address
will be passed to bootm.
For FIT image, the initrd can be provided with the same value than
kernel, including configuration:
<path>#<conf>[#<extra-conf[#...]]
In this case, kernel_addr_r is passed to bootm.
fdt <path> - if this label is chosen, use tftp to retrieve the fdt blob
at <path>. it will be stored at the address indicated in
the fdt_addr_r environment variable, and that address will
be passed to bootm.
For FIT image, the device tree can be provided with the same value
than kernel, including configuration:
<path>#<conf>[#<extra-conf[#...]]
In this case, kernel_addr_r is passed to bootm.
devicetree <path> - if this label is chosen, use tftp to retrieve the fdt blob
at <path>. it will be stored at the address indicated in
the fdt_addr_r environment variable, and that address will
be passed to bootm. Alias for fdt.
fdtdir <path> - if this label is chosen, use tftp to retrieve a fdt blob
relative to <path>. If the fdtfile environment variable
is set, <path>/<fdtfile> is retrieved. Otherwise, the
filename is generated from the soc and board environment
variables, i.e. <path>/<soc>-<board>.dtb is retrieved.
If the fdt command is specified, fdtdir is ignored.
localboot <flag> - Run the command defined by "localcmd" in the environment.
<flag> is ignored and is only here to match the syntax of
PXELINUX config files.
Example
-------
Here's a couple of example files to show how this works.
------------/tftpboot/pxelinux.cfg/menus/base.menu-----------
menu title Linux selections
# This is the default label
label install
menu label Default Install Image
kernel kernels/install.bin
append console=ttyAMA0,38400 debug earlyprintk
initrd initrds/uzInitrdDebInstall
# Just another label
label linux-2.6.38
kernel kernels/linux-2.6.38.bin
append root=/dev/sdb1
# The locally installed kernel
label local
menu label Locally installed kernel
append root=/dev/sdb1
localboot 1
-------------------------------------------------------------
------------/tftpboot/pxelinux.cfg/default-------------------
menu include pxelinux.cfg/menus/base.menu
timeout 500
default linux-2.6.38
-------------------------------------------------------------
When a pxe client retrieves and boots the default pxe file,
'pxe boot' will wait for user input for 5 seconds before booting
the linux-2.6.38 label, which will cause /tftpboot/kernels/linux-2.6.38.bin
to be downloaded, and boot with the command line "root=/dev/sdb1"
Differences with PXELINUX
=========================
The biggest difference between U-Boot's pxe and PXELINUX is that since
U-Boot's pxe support is written entirely in C, it can run on any platform
with network support in U-Boot. Here are some other differences between
PXELINUX and U-Boot's pxe support.
- U-Boot's pxe does not support the PXELINUX DHCP option codes specified
in RFC 5071, but could be extended to do so.
- when U-Boot's pxe fails to boot, it will return control to U-Boot,
allowing another command to run, other U-Boot command, instead of resetting
the machine like PXELINUX.
- U-Boot's pxe doesn't rely on or provide an UNDI/PXE stack in memory, it
only uses U-Boot.
- U-Boot's pxe doesn't provide the full menu implementation that PXELINUX
does, only a simple text based menu using the commands described in
this README. With PXELINUX, it's possible to have a graphical boot
menu, submenus, passwords, etc. U-Boot's pxe could be extended to support
a more robust menuing system like that of PXELINUX's.
- U-Boot's pxe expects U-Boot uimg's as kernels. Anything that would work
with the 'bootm' command in U-Boot could work with the 'pxe boot' command.
- U-Boot's pxe only recognizes a single file on the initrd command line. It
could be extended to support multiple.
- in U-Boot's pxe, the localboot command doesn't necessarily cause a local
disk boot - it will do whatever is defined in the 'localcmd' env
variable. And since it doesn't support a full UNDI/PXE stack, the
type field is ignored.
- the interactive prompt in U-Boot's pxe only allows you to choose a label
from the menu. If you want to boot something not listed, you can ctrl+c
out of 'pxe boot' and use existing U-Boot commands to accomplish it.
Reference in New Issue View Git Blame Copy Permalink