path: root/doc/README.pxecfg
diff options
Diffstat (limited to 'doc/README.pxecfg')
1 files changed, 239 insertions, 0 deletions
diff --git a/doc/README.pxecfg b/doc/README.pxecfg
new file mode 100644
index 000000000..5c5f8c7f6
--- /dev/null
+++ b/doc/README.pxecfg
@@ -0,0 +1,239 @@
+ * 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 pxecfg 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. To avoid identity confusion with PXELINUX, and because not all behavior is
+identical, we call this feature 'pxecfg'.
+pxecfg get
+ syntax: pxecfg get
+ follows PXELINUX's rules for retrieving configuration files from a tftp
+ server, and supports a subset of PXELINUX's config file syntax.
+ Environment
+ -----------
+ get_pxecfg requires two environment variables to be set:
+ pxecfg_ram - should be set to a location in RAM large enough to hold
+ pxecfg 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.
+ get_pxecfg optionally supports these two environment variables being set:
+ ethaddr - this is the standard MAC address for the ethernet adapter in use.
+ getpxe_cfg 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. get_pxecfg uses
+ it to look for a configuration file based on the system's UUID.
+ File Paths
+ ----------
+ get_pxecfg 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
+pxecfg boot
+ syntax: pxecfg boot [pxecfg_addr]
+ Interprets a pxecfg file stored in memory.
+ pxecfg_addr is an optional argument giving the location of the pxecfg file
+ Environment
+ -----------
+ There are some environment variables that may need to be set, depending on
+ conditions.
+ pxecfg_ram - if the optional argument pxecfg_addr is not supplied, an
+ environment variable named pxecfg_ram must be supplied. This is typically
+ the same value as is used for the get_pxecfg 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 boot_pxecfg will use.
+ 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_ram,initrd_ram - locations in RAM at which boot_pxecfg 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.
+ fdtaddr - the location of a fdt blob. If this is set, it will be passed to
+ bootm when booting a kernel.
+pxecfg file format
+The pxecfg file format is more or less 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
+The size of pxecfg 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 pxecfg files is statically allocated, and its
+location is given by the pxecfg_ram environment variable. the pxecfg code is
+not aware of the size of the pxecfg memory and will outgrow it if pxecfg 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 boot_pxecfg attempts to boot.
+menu title <string> - sets a title for the menu of labels being displayed.
+menu include <path> - use tftp to retrieve the pxecfg 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_ram 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_ram 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.
+Here's a couple of example files to show how this works.
+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
+menu include pxelinux.cfg/menus/base.menu
+timeout 500
+default linux-2.6.38
+When a pxecfg client retrieves and boots the default pxecfg file,
+boot_pxecfg 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 pxecfg and PXELINUX is that since pxecfg
+is part of U-boot and is written entirely in C, it can run on platform
+with network support in U-boot. Here are some of the other differences
+between PXELINUX and pxecfg.
+- pxecfg does not support the PXELINUX DHCP option codes specified in
+ RFC 5071, but could be extended to do so.
+- when pxecfg 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.
+- pxecfg doesn't rely on or provide an UNDI/PXE stack in memory, it only
+ uses U-boot.
+- pxecfg 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. pxecfg could be extended to support
+ a more robust menuing system like that of PXELINUX's.
+- pxecfg expects U-boot uimg's as kernels. anything that would work with
+ the 'bootm' command in U-boot could work with pxecfg.
+- pxecfg doesn't recognize initrd options in the append command - you must
+ specify initrd files using the initrd command
+- pxecfg only recognizes a single file on the initrd command line. it
+ could be extended to support multiple
+- in pxecfg, 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 pxecfg only allows you to choose a label from
+ the menu. if you want to boot something not listed, you can ctrl+c out
+ of pxecfg and use existing U-boot commands to accomplish it.