Add pxe command, which is intended to mimic PXELINUX functionality. 'pxe get' uses tftp to retrieve a file based on UUID, MAC address or IP address. 'pxe boot' interprets the contents of PXELINUX config like file to boot using a specific initrd, kernel and kernel command line. This patch also adds a README.pxe file - see it for more details on the pxe command. Signed-off-by: Jason Hobbs <jason.hobbs@calxeda.com>master
parent
e11938eabc
commit
06283a6401
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,240 @@ |
||||
/* |
||||
* 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 |
||||
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 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. |
||||
|
||||
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. |
||||
|
||||
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 |
||||
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. |
||||
|
||||
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/linux.list---------- |
||||
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 doesn't recognize initrd options in the append command - you |
||||
must specify initrd files using the initrd 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. |
Loading…
Reference in new issue