+SPDX-License-Identifier: GPL-2.0+
/*
* Copyright 2010-2011 Calxeda, Inc.
- *
- * SPDX-License-Identifier: GPL-2.0+
*/
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
+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
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 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.
+ 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
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
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
+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
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
specified in a different way
kernel <path> - if this label is chosen, use tftp to retrieve the kernel
- 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.
+ (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.
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
-------
Here's a couple of example files to show how this works.
-------------/tftpboot/pxelinux.cfg/menus/linux.list----------
+------------/tftpboot/pxelinux.cfg/menus/base.menu-----------
menu title Linux selections
# This is the default label
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.
+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
+- 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
+- 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 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
+- 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
+ 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 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
+- 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
+- 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
+- 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.
+ out of 'pxe boot' and use existing U-Boot commands to accomplish it.
projects / J-u-boot.git / blobdiff