diff options
Diffstat (limited to 'doc/README.pxe')
| -rw-r--r-- | doc/README.pxe | 292 |
1 files changed, 0 insertions, 292 deletions
diff --git a/doc/README.pxe b/doc/README.pxe deleted file mode 100644 index ba189080e8c..00000000000 --- a/doc/README.pxe +++ /dev/null @@ -1,292 +0,0 @@ -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/usage/fit/overlay-fdt-boot.rst). - -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. - -------------/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. |