u-boot/doc/README.pxe

2  * Copyright 2010-2011 Calxeda, Inc.
4  * SPDX-License-Identifier:	GPL-2.0+
8 the PXELINUX boot loader. This allows U-Boot based systems to be controlled
9 remotely using the same PXE based techniques that many non U-Boot based servers
16 -------
19      follows PXELINUX's rules for retrieving configuration files from a tftp
23      -----------
26      pxefile_addr_r - should be set to a location in RAM large enough to hold
27      pxe files while they're being processed. Up to 16 config files may be
28      held in memory at once. The exact number and size of the files varies with
32      bootfile,serverip - these two are typically set in the DHCP response
37      ethaddr - this is the standard MAC address for the ethernet adapter in use.
41      pxeuuid - this is a UUID in standard form using lower case hexadecimal
42      digits, for example, 550e8400-e29b-41d4-a716-446655440000. 'pxe get' uses
43      it to look for a configuration file based on the system's UUID.
46      ----------
47      'pxe get' repeatedly tries to download config files until it either
49      contents of paths it tries mirrors exactly that of PXELINUX - you can
55 --------
64      -----------
68      pxefile_addr_r - if the optional argument pxefile_addr_r is not supplied,
72      bootfile - typically set in the DHCP response handler based on the
74      directory that all other paths to files retrieved by 'pxe boot' will use.
75      If no bootfile is specified, paths used in pxe files will be used as is.
77      serverip - typically set in the DHCP response handler, this is the IP
78      address of the tftp server from which other files will be retrieved.
80      kernel_addr_r, initrd_addr_r - locations in RAM at which 'pxe boot' will
85      fdt_addr_r - location in RAM at which 'pxe boot' will store the fdt blob it
90      fdt_addr - the location of a fdt blob. 'fdt_addr' will be passed to bootm
97 commands - global commands, and commands specific to labels. Lines begining
101 The size of pxe files and the number of labels is only limited by the amount
102 of RAM available to U-Boot. Memory for labels is dynamically allocated as
103 they're parsed, and memory for pxe files is statically allocated, and its
105 not aware of the size of the pxefile memory and will outgrow it if pxe files
109 -------------------------
112 default <label>	    - the label named here is treated as the default and is
115 menu title <string> - sets a title for the menu of labels being displayed.
117 menu include <path> - use tftp to retrieve the pxe file at <path>, which
120 		      of include up to 16 files deep is supported.
122 prompt <flag>	    - if 1, always prompt the user to enter a label to boot
125 timeout <num>	    - wait for user input for <num>/10 seconds before
126 		      auto-booting a node.
128 label <name>	    - begin a label definition. labels continue until
133 ------------------------
136 menu default	    - set this label as the default label to boot; this is
140 kernel <path>	    - if this label is chosen, use tftp to retrieve the kernel
145 append <string>	    - use <string> as the kernel command line when booting this
148 initrd <path>	    - if this label is chosen, use tftp to retrieve the initrd
153 fdt <path>	    - if this label is chosen, use tftp to retrieve the fdt blob
158 fdtdir <path>	    - if this label is chosen, use tftp to retrieve a fdt blob
162 		      variables, i.e. <path>/<soc>-<board>.dtb is retrieved.
165 localboot <flag>    - Run the command defined by "localcmd" in the environment.
167 		      PXELINUX config files.
170 -------
171 Here's a couple of example files to show how this works.
173 ------------/tftpboot/pxelinux.cfg/menus/base.menu-----------
184 label linux-2.6.38
185 	kernel kernels/linux-2.6.38.bin
193 -------------------------------------------------------------
195 ------------/tftpboot/pxelinux.cfg/default-------------------
199 default linux-2.6.38
200 -------------------------------------------------------------
204 the linux-2.6.38 label, which will cause /tftpboot/kernels/linux-2.6.38.bin
209 The biggest difference between U-Boot's pxe and PXELINUX is that since
210 U-Boot's pxe support is written entirely in C, it can run on any platform
211 with network support in U-Boot. Here are some other differences between
212 PXELINUX and U-Boot's pxe support.
214 - U-Boot's pxe does not support the PXELINUX DHCP option codes specified
217 - when U-Boot's pxe fails to boot, it will return control to U-Boot,
218   allowing another command to run, other U-Boot command, instead of resetting
221 - U-Boot's pxe doesn't rely on or provide an UNDI/PXE stack in memory, it
222   only uses U-Boot.
224 - U-Boot's pxe doesn't provide the full menu implementation that PXELINUX
225   does, only a simple text based menu using the commands described in
227   menu, submenus, passwords, etc. U-Boot's pxe could be extended to support
230 - U-Boot's pxe expects U-Boot uimg's as kernels.  Anything that would work
231   with the 'bootm' command in U-Boot could work with the 'pxe boot' command.
233 - U-Boot's pxe only recognizes a single file on the initrd command line.  It
236 - in U-Boot's pxe, the localboot command doesn't necessarily cause a local
237   disk boot - it will do whatever is defined in the 'localcmd' env
241 - the interactive prompt in U-Boot's pxe only allows you to choose a label
243   out of 'pxe boot' and use existing U-Boot commands to accomplish it.