+SPDX-License-Identifier: GPL-2.0+
/*
* Copyright 2010-2011 Calxeda, Inc.
- *
- * This program is free software; you can redistribute it and/or modify it
- * under the terms of the GNU General Public License as published by the Free
- * Software Foundation; either version 2 of the License, or (at your option)
- * any later version.
- *
- * This program is distributed in the hope it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
- * more details.
- *
- * You should have received a copy of the GNU General Public License along with
- * this program. If not, see <http://www.gnu.org/licenses/>.
*/
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 - the location of a fdt blob. If this is set, it will be passed
- to bootm when booting a kernel.
+ 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 file format
===============
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
-------------------------
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.
+default <label> - the label named here is treated as the default and is
+ the first label 'pxe boot' attempts to boot.
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.
+ 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.
+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.
+ 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.
+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
- 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.
-
-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.
+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.
+
+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.
+
+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.
+
+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.
+ <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/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
+ 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 doesn't recognize initrd options in the append command - you
- must specify initrd files using the initrd 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