diff options
Diffstat (limited to 'doc/usage/pxe.rst')
| -rw-r--r-- | doc/usage/pxe.rst | 346 |
1 files changed, 346 insertions, 0 deletions
diff --git a/doc/usage/pxe.rst b/doc/usage/pxe.rst new file mode 100644 index 00000000000..c2dc11f218d --- /dev/null +++ b/doc/usage/pxe.rst @@ -0,0 +1,346 @@ +.. SPDX-License-Identifier: GPL-2.0+ + Copyright 2010-2011 Calxeda, Inc. + +PXE Boot and extlinux.conf +========================== + +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. + +The ``sysboot`` command and Extlinux boot method use the same file +format as PXE boot for ``extlinux.conf``. + +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. It requires certain environment variables to be + set, see the Environment section below. + + **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. + + There are some environment variables that may need to be set, + depending on conditions, see the Environment section below. + +``sysboot`` + **Syntax:** ``sysboot [-p] <interface> <dev[:part]> <ext2|fat|any> [addr] [filename]`` + + Load and boot an ``extlinux.conf`` file from a local + filesystem. Paths in the ``extlinux.conf`` file (kernel, + initrd, FDT and overlays) will be interpreted within that + filesystem. + + Example: + + ``sysboot mmc 0.0:2 any ${pxefile_addr_r} /boot/extlinux.conf`` + +Environment +----------- + +``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. Required for ``pxe + get``, for ``pxe boot`` if the optional argument + ``pxefile_addr_r`` is not supplied. + +``bootfile`` + Typically set in the DHCP response handler, required for ``pxe + get``. For ``pxe boot``, 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. Required for ``pxe get``. + +``kernel_addr_r``, ``initrd_addr_r`` + Locations in RAM to store the kernel (or FIT image) and + initrd. 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 to store the retrieved fdt blob. 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`` + 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 to temporarily store fdt overlay(s) before + applying them to the fdt blob stored at + ``fdt_addr_r``. Required to use the ``fdtoverlays`` command in + the PXE file. + +``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. + +``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. + +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 beginning 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 be passed to bootm with that address (see: + doc/uImage.FIT/command_syntax_extensions.txt). It is useful + for overlay selection in pxe file (see + :doc:`./fit/overlay-fdt-boot`). + +``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. Environment variable references like ``${var}`` are + substituted before boot. + +``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. + +.. code-block:: + :caption: /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 + +.. code-block:: + :caption: /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. |