]>
Commit | Line | Data |
---|---|---|
06283a64 JH |
1 | /* |
2 | * Copyright 2010-2011 Calxeda, Inc. | |
3 | * | |
4 | * This program is free software; you can redistribute it and/or modify it | |
5 | * under the terms of the GNU General Public License as published by the Free | |
6 | * Software Foundation; either version 2 of the License, or (at your option) | |
7 | * any later version. | |
8 | * | |
9 | * This program is distributed in the hope it will be useful, but WITHOUT | |
10 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
11 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for | |
12 | * more details. | |
13 | * | |
14 | * You should have received a copy of the GNU General Public License along with | |
15 | * this program. If not, see <http://www.gnu.org/licenses/>. | |
16 | */ | |
17 | ||
18 | The 'pxe' commands provide a near subset of the functionality provided by | |
19 | the PXELINUX boot loader. This allows U-boot based systems to be controlled | |
20 | remotely using the same PXE based techniques that many non U-boot based servers | |
21 | use. | |
22 | ||
23 | Commands | |
24 | ======== | |
25 | ||
26 | pxe get | |
27 | ------- | |
28 | syntax: pxe get | |
29 | ||
30 | follows PXELINUX's rules for retrieving configuration files from a tftp | |
31 | server, and supports a subset of PXELINUX's config file syntax. | |
32 | ||
33 | Environment | |
34 | ----------- | |
35 | 'pxe get' requires two environment variables to be set: | |
36 | ||
37 | pxefile_addr_r - should be set to a location in RAM large enough to hold | |
38 | pxe files while they're being processed. Up to 16 config files may be | |
39 | held in memory at once. The exact number and size of the files varies with | |
40 | how the system is being used. A typical config file is a few hundred bytes | |
41 | long. | |
42 | ||
43 | bootfile,serverip - these two are typically set in the DHCP response | |
44 | handler, and correspond to fields in the DHCP response. | |
45 | ||
46 | 'pxe get' optionally supports these two environment variables being set: | |
47 | ||
48 | ethaddr - this is the standard MAC address for the ethernet adapter in use. | |
49 | 'pxe get' uses it to look for a configuration file specific to a system's | |
50 | MAC address. | |
51 | ||
52 | pxeuuid - this is a UUID in standard form using lower case hexadecimal | |
53 | digits, for example, 550e8400-e29b-41d4-a716-446655440000. 'pxe get' uses | |
54 | it to look for a configuration file based on the system's UUID. | |
55 | ||
56 | File Paths | |
57 | ---------- | |
58 | 'pxe get' repeatedly tries to download config files until it either | |
59 | successfully downloads one or runs out of paths to try. The order and | |
60 | contents of paths it tries mirrors exactly that of PXELINUX - you can | |
61 | read in more detail about it at: | |
62 | ||
63 | http://syslinux.zytor.com/wiki/index.php/Doc/pxelinux | |
64 | ||
65 | pxe boot | |
66 | -------- | |
67 | syntax: pxe boot [pxefile_addr_r] | |
68 | ||
69 | Interprets a pxe file stored in memory. | |
70 | ||
71 | pxefile_addr_r is an optional argument giving the location of the pxe file. | |
72 | The file must be terminated with a NUL byte. | |
73 | ||
74 | Environment | |
75 | ----------- | |
76 | There are some environment variables that may need to be set, depending | |
77 | on conditions. | |
78 | ||
79 | pxefile_addr_r - if the optional argument pxefile_addr_r is not supplied, | |
80 | an environment variable named pxefile_addr_r must be supplied. This is | |
81 | typically the same value as is used for the 'pxe get' command. | |
82 | ||
83 | bootfile - typically set in the DHCP response handler based on the | |
84 | same field in the DHCP respone, this path is used to generate the base | |
85 | directory that all other paths to files retrieved by 'pxe boot' will use. | |
86 | If no bootfile is specified, paths used in pxe files will be used as is. | |
87 | ||
88 | serverip - typically set in the DHCP response handler, this is the IP | |
89 | address of the tftp server from which other files will be retrieved. | |
90 | ||
91 | kernel_addr_r, initrd_addr_r - locations in RAM at which 'pxe boot' will | |
92 | store the kernel and initrd it retrieves from tftp. These locations will | |
93 | be passed to the bootm command to boot the kernel. These environment | |
94 | variables are required to be set. | |
95 | ||
96 | fdt_addr - the location of a fdt blob. If this is set, it will be passed | |
97 | to bootm when booting a kernel. | |
98 | ||
99 | pxe file format | |
100 | =============== | |
101 | The pxe file format is nearly a subset of the PXELINUX file format; see | |
102 | http://syslinux.zytor.com/wiki/index.php/PXELINUX. It's composed of one line | |
103 | commands - global commands, and commands specific to labels. Lines begining | |
104 | with # are treated as comments. White space between and at the beginning of | |
105 | lines is ignored. | |
106 | ||
107 | The size of pxe files and the number of labels is only limited by the amount | |
108 | of RAM available to U-boot. Memory for labels is dynamically allocated as | |
109 | they're parsed, and memory for pxe files is statically allocated, and its | |
110 | location is given by the pxefile_addr_r environment variable. The pxe code is | |
111 | not aware of the size of the pxefile memory and will outgrow it if pxe files | |
112 | are too large. | |
113 | ||
114 | Supported global commands | |
115 | ------------------------- | |
116 | Unrecognized commands are ignored. | |
117 | ||
6b62b9a3 WD |
118 | default <label> - the label named here is treated as the default and is |
119 | the first label 'pxe boot' attempts to boot. | |
06283a64 JH |
120 | |
121 | menu title <string> - sets a title for the menu of labels being displayed. | |
122 | ||
123 | menu include <path> - use tftp to retrieve the pxe file at <path>, which | |
6b62b9a3 WD |
124 | is then immediately parsed as if the start of its |
125 | contents were the next line in the current file. nesting | |
126 | of include up to 16 files deep is supported. | |
06283a64 | 127 | |
6b62b9a3 WD |
128 | prompt <flag> - if 1, always prompt the user to enter a label to boot |
129 | from. if 0, only prompt the user if timeout expires. | |
06283a64 JH |
130 | |
131 | timeout <num> - wait for user input for <num>/10 seconds before | |
6b62b9a3 | 132 | auto-booting a node. |
06283a64 | 133 | |
6b62b9a3 WD |
134 | label <name> - begin a label definition. labels continue until |
135 | a command not recognized as a label command is seen, | |
136 | or EOF is reached. | |
06283a64 JH |
137 | |
138 | Supported label commands | |
139 | ------------------------ | |
140 | labels end when a command not recognized as a label command is reached, or EOF. | |
141 | ||
6b62b9a3 WD |
142 | menu default - set this label as the default label to boot; this is |
143 | the same behavior as the global default command but | |
144 | specified in a different way | |
06283a64 | 145 | |
6b62b9a3 WD |
146 | kernel <path> - if this label is chosen, use tftp to retrieve the kernel |
147 | at <path>. it will be stored at the address indicated in | |
148 | the kernel_addr_r environment variable, and that address | |
149 | will be passed to bootm to boot this kernel. | |
06283a64 | 150 | |
6b62b9a3 WD |
151 | append <string> - use <string> as the kernel command line when booting this |
152 | label. | |
06283a64 | 153 | |
6b62b9a3 WD |
154 | initrd <path> - if this label is chosen, use tftp to retrieve the initrd |
155 | at <path>. it will be stored at the address indicated in | |
156 | the initrd_addr_r environment variable, and that address | |
157 | will be passed to bootm. | |
06283a64 JH |
158 | |
159 | localboot <flag> - Run the command defined by "localcmd" in the environment. | |
6b62b9a3 WD |
160 | <flag> is ignored and is only here to match the syntax of |
161 | PXELINUX config files. | |
06283a64 JH |
162 | |
163 | Example | |
164 | ------- | |
165 | Here's a couple of example files to show how this works. | |
166 | ||
167 | ------------/tftpboot/pxelinux.cfg/menus/linux.list---------- | |
168 | menu title Linux selections | |
169 | ||
170 | # This is the default label | |
171 | label install | |
172 | menu label Default Install Image | |
173 | kernel kernels/install.bin | |
174 | append console=ttyAMA0,38400 debug earlyprintk | |
175 | initrd initrds/uzInitrdDebInstall | |
176 | ||
177 | # Just another label | |
178 | label linux-2.6.38 | |
179 | kernel kernels/linux-2.6.38.bin | |
180 | append root=/dev/sdb1 | |
181 | ||
182 | # The locally installed kernel | |
183 | label local | |
184 | menu label Locally installed kernel | |
185 | append root=/dev/sdb1 | |
186 | localboot 1 | |
187 | ------------------------------------------------------------- | |
188 | ||
189 | ------------/tftpboot/pxelinux.cfg/default------------------- | |
190 | menu include pxelinux.cfg/menus/base.menu | |
191 | timeout 500 | |
192 | ||
193 | default linux-2.6.38 | |
194 | ------------------------------------------------------------- | |
195 | ||
196 | When a pxe client retrieves and boots the default pxe file, | |
197 | 'pxe boot' will wait for user input for 5 seconds before booting | |
198 | the linux-2.6.38 label, which will cause /tftpboot/kernels/linux-2.6.38.bin | |
199 | to be downloaded, and boot with the command line "root=/dev/sdb1" | |
200 | ||
201 | Differences with PXELINUX | |
202 | ========================= | |
203 | The biggest difference between U-boot's pxe and PXELINUX is that since | |
204 | U-boot's pxe support is written entirely in C, it can run on any platform | |
205 | with network support in U-boot. Here are some other differences between | |
206 | PXELINUX and U-boot's pxe support. | |
207 | ||
208 | - U-boot's pxe does not support the PXELINUX DHCP option codes specified | |
209 | in RFC 5071, but could be extended to do so. | |
210 | ||
211 | - when U-boot's pxe fails to boot, it will return control to U-boot, | |
212 | allowing another command to run, other U-boot command, instead of resetting | |
213 | the machine like PXELINUX. | |
214 | ||
215 | - U-boot's pxe doesn't rely on or provide an UNDI/PXE stack in memory, it | |
216 | only uses U-boot. | |
217 | ||
218 | - U-boot's pxe doesn't provide the full menu implementation that PXELINUX | |
219 | does, only a simple text based menu using the commands described in | |
6b62b9a3 | 220 | this README. With PXELINUX, it's possible to have a graphical boot |
06283a64 JH |
221 | menu, submenus, passwords, etc. U-boot's pxe could be extended to support |
222 | a more robust menuing system like that of PXELINUX's. | |
223 | ||
224 | - U-boot's pxe expects U-boot uimg's as kernels. Anything that would work | |
225 | with the 'bootm' command in U-boot could work with the 'pxe boot' command. | |
226 | ||
06283a64 JH |
227 | - U-boot's pxe only recognizes a single file on the initrd command line. It |
228 | could be extended to support multiple. | |
229 | ||
230 | - in U-boot's pxe, the localboot command doesn't necessarily cause a local | |
231 | disk boot - it will do whatever is defined in the 'localcmd' env | |
232 | variable. And since it doesn't support a full UNDI/PXE stack, the | |
233 | type field is ignored. | |
234 | ||
235 | - the interactive prompt in U-boot's pxe only allows you to choose a label | |
236 | from the menu. If you want to boot something not listed, you can ctrl+c | |
237 | out of 'pxe boot' and use existing U-boot commands to accomplish it. |