Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 1 | /* |
| 2 | * Copyright 2010-2011 Calxeda, Inc. |
| 3 | * |
Wolfgang Denk | 1a45966 | 2013-07-08 09:37:19 +0200 | [diff] [blame] | 4 | * SPDX-License-Identifier: GPL-2.0+ |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 5 | */ |
| 6 | |
| 7 | The 'pxe' commands provide a near subset of the functionality provided by |
Bin Meng | a187559 | 2016-02-05 19:30:11 -0800 | [diff] [blame] | 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 |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 10 | use. |
| 11 | |
| 12 | Commands |
| 13 | ======== |
| 14 | |
| 15 | pxe get |
| 16 | ------- |
| 17 | syntax: pxe get |
| 18 | |
| 19 | follows PXELINUX's rules for retrieving configuration files from a tftp |
| 20 | server, and supports a subset of PXELINUX's config file syntax. |
| 21 | |
| 22 | Environment |
| 23 | ----------- |
| 24 | 'pxe get' requires two environment variables to be set: |
| 25 | |
| 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 |
| 29 | how the system is being used. A typical config file is a few hundred bytes |
| 30 | long. |
| 31 | |
| 32 | bootfile,serverip - these two are typically set in the DHCP response |
| 33 | handler, and correspond to fields in the DHCP response. |
| 34 | |
| 35 | 'pxe get' optionally supports these two environment variables being set: |
| 36 | |
| 37 | ethaddr - this is the standard MAC address for the ethernet adapter in use. |
| 38 | 'pxe get' uses it to look for a configuration file specific to a system's |
| 39 | MAC address. |
| 40 | |
| 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. |
| 44 | |
| 45 | File Paths |
| 46 | ---------- |
| 47 | 'pxe get' repeatedly tries to download config files until it either |
| 48 | successfully downloads one or runs out of paths to try. The order and |
| 49 | contents of paths it tries mirrors exactly that of PXELINUX - you can |
| 50 | read in more detail about it at: |
| 51 | |
| 52 | http://syslinux.zytor.com/wiki/index.php/Doc/pxelinux |
| 53 | |
| 54 | pxe boot |
| 55 | -------- |
| 56 | syntax: pxe boot [pxefile_addr_r] |
| 57 | |
| 58 | Interprets a pxe file stored in memory. |
| 59 | |
| 60 | pxefile_addr_r is an optional argument giving the location of the pxe file. |
| 61 | The file must be terminated with a NUL byte. |
| 62 | |
| 63 | Environment |
| 64 | ----------- |
| 65 | There are some environment variables that may need to be set, depending |
| 66 | on conditions. |
| 67 | |
| 68 | pxefile_addr_r - if the optional argument pxefile_addr_r is not supplied, |
| 69 | an environment variable named pxefile_addr_r must be supplied. This is |
| 70 | typically the same value as is used for the 'pxe get' command. |
| 71 | |
| 72 | bootfile - typically set in the DHCP response handler based on the |
| 73 | same field in the DHCP respone, this path is used to generate the base |
| 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. |
| 76 | |
| 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. |
| 79 | |
| 80 | kernel_addr_r, initrd_addr_r - locations in RAM at which 'pxe boot' will |
| 81 | store the kernel and initrd it retrieves from tftp. These locations will |
| 82 | be passed to the bootm command to boot the kernel. These environment |
| 83 | variables are required to be set. |
| 84 | |
Chander Kashyap | a655938 | 2012-09-06 19:36:31 +0000 | [diff] [blame] | 85 | fdt_addr_r - location in RAM at which 'pxe boot' will store the fdt blob it |
| 86 | retrieves from tftp. The retrieval is possible if 'fdt' label is defined in |
| 87 | pxe file and 'fdt_addr_r' is set. If retrieval is possible, 'fdt_addr_r' |
| 88 | will be passed to bootm command to boot the kernel. |
| 89 | |
| 90 | fdt_addr - the location of a fdt blob. 'fdt_addr' will be passed to bootm |
| 91 | command if it is set and 'fdt_addr_r' is not passed to bootm command. |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 92 | |
| 93 | pxe file format |
| 94 | =============== |
| 95 | The pxe file format is nearly a subset of the PXELINUX file format; see |
| 96 | http://syslinux.zytor.com/wiki/index.php/PXELINUX. It's composed of one line |
| 97 | commands - global commands, and commands specific to labels. Lines begining |
| 98 | with # are treated as comments. White space between and at the beginning of |
| 99 | lines is ignored. |
| 100 | |
| 101 | The size of pxe files and the number of labels is only limited by the amount |
Bin Meng | a187559 | 2016-02-05 19:30:11 -0800 | [diff] [blame] | 102 | of RAM available to U-Boot. Memory for labels is dynamically allocated as |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 103 | they're parsed, and memory for pxe files is statically allocated, and its |
| 104 | location is given by the pxefile_addr_r environment variable. The pxe code is |
| 105 | not aware of the size of the pxefile memory and will outgrow it if pxe files |
| 106 | are too large. |
| 107 | |
| 108 | Supported global commands |
| 109 | ------------------------- |
| 110 | Unrecognized commands are ignored. |
| 111 | |
Wolfgang Denk | 6b62b9a | 2011-12-19 12:03:40 +0100 | [diff] [blame] | 112 | default <label> - the label named here is treated as the default and is |
| 113 | the first label 'pxe boot' attempts to boot. |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 114 | |
| 115 | menu title <string> - sets a title for the menu of labels being displayed. |
| 116 | |
| 117 | menu include <path> - use tftp to retrieve the pxe file at <path>, which |
Wolfgang Denk | 6b62b9a | 2011-12-19 12:03:40 +0100 | [diff] [blame] | 118 | is then immediately parsed as if the start of its |
| 119 | contents were the next line in the current file. nesting |
| 120 | of include up to 16 files deep is supported. |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 121 | |
Wolfgang Denk | 6b62b9a | 2011-12-19 12:03:40 +0100 | [diff] [blame] | 122 | prompt <flag> - if 1, always prompt the user to enter a label to boot |
| 123 | from. if 0, only prompt the user if timeout expires. |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 124 | |
| 125 | timeout <num> - wait for user input for <num>/10 seconds before |
Wolfgang Denk | 6b62b9a | 2011-12-19 12:03:40 +0100 | [diff] [blame] | 126 | auto-booting a node. |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 127 | |
Wolfgang Denk | 6b62b9a | 2011-12-19 12:03:40 +0100 | [diff] [blame] | 128 | label <name> - begin a label definition. labels continue until |
| 129 | a command not recognized as a label command is seen, |
| 130 | or EOF is reached. |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 131 | |
| 132 | Supported label commands |
| 133 | ------------------------ |
| 134 | labels end when a command not recognized as a label command is reached, or EOF. |
| 135 | |
Wolfgang Denk | 6b62b9a | 2011-12-19 12:03:40 +0100 | [diff] [blame] | 136 | menu default - set this label as the default label to boot; this is |
| 137 | the same behavior as the global default command but |
| 138 | specified in a different way |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 139 | |
Wolfgang Denk | 6b62b9a | 2011-12-19 12:03:40 +0100 | [diff] [blame] | 140 | kernel <path> - if this label is chosen, use tftp to retrieve the kernel |
| 141 | at <path>. it will be stored at the address indicated in |
| 142 | the kernel_addr_r environment variable, and that address |
| 143 | will be passed to bootm to boot this kernel. |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 144 | |
Wolfgang Denk | 6b62b9a | 2011-12-19 12:03:40 +0100 | [diff] [blame] | 145 | append <string> - use <string> as the kernel command line when booting this |
| 146 | label. |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 147 | |
Wolfgang Denk | 6b62b9a | 2011-12-19 12:03:40 +0100 | [diff] [blame] | 148 | initrd <path> - if this label is chosen, use tftp to retrieve the initrd |
| 149 | at <path>. it will be stored at the address indicated in |
| 150 | the initrd_addr_r environment variable, and that address |
| 151 | will be passed to bootm. |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 152 | |
Chander Kashyap | a655938 | 2012-09-06 19:36:31 +0000 | [diff] [blame] | 153 | fdt <path> - if this label is chosen, use tftp to retrieve the fdt blob |
| 154 | at <path>. it will be stored at the address indicated in |
| 155 | the fdt_addr_r environment variable, and that address will |
| 156 | be passed to bootm. |
| 157 | |
Stefan Brüns | 6015f8f | 2015-08-30 19:10:58 +0200 | [diff] [blame] | 158 | fdtdir <path> - if this label is chosen, use tftp to retrieve a fdt blob |
| 159 | relative to <path>. If the fdtfile environment variable |
| 160 | is set, <path>/<fdtfile> is retrieved. Otherwise, the |
| 161 | filename is generated from the soc and board environment |
| 162 | variables, i.e. <path>/<soc>-<board>.dtb is retrieved. |
| 163 | If the fdt command is specified, fdtdir is ignored. |
| 164 | |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 165 | localboot <flag> - Run the command defined by "localcmd" in the environment. |
Wolfgang Denk | 6b62b9a | 2011-12-19 12:03:40 +0100 | [diff] [blame] | 166 | <flag> is ignored and is only here to match the syntax of |
| 167 | PXELINUX config files. |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 168 | |
| 169 | Example |
| 170 | ------- |
| 171 | Here's a couple of example files to show how this works. |
| 172 | |
Stefan Brüns | 695c132 | 2015-08-30 19:10:59 +0200 | [diff] [blame] | 173 | ------------/tftpboot/pxelinux.cfg/menus/base.menu----------- |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 174 | menu title Linux selections |
| 175 | |
| 176 | # This is the default label |
| 177 | label install |
| 178 | menu label Default Install Image |
| 179 | kernel kernels/install.bin |
| 180 | append console=ttyAMA0,38400 debug earlyprintk |
| 181 | initrd initrds/uzInitrdDebInstall |
| 182 | |
| 183 | # Just another label |
| 184 | label linux-2.6.38 |
| 185 | kernel kernels/linux-2.6.38.bin |
| 186 | append root=/dev/sdb1 |
| 187 | |
| 188 | # The locally installed kernel |
| 189 | label local |
| 190 | menu label Locally installed kernel |
| 191 | append root=/dev/sdb1 |
| 192 | localboot 1 |
| 193 | ------------------------------------------------------------- |
| 194 | |
| 195 | ------------/tftpboot/pxelinux.cfg/default------------------- |
| 196 | menu include pxelinux.cfg/menus/base.menu |
| 197 | timeout 500 |
| 198 | |
| 199 | default linux-2.6.38 |
| 200 | ------------------------------------------------------------- |
| 201 | |
| 202 | When a pxe client retrieves and boots the default pxe file, |
| 203 | 'pxe boot' will wait for user input for 5 seconds before booting |
| 204 | the linux-2.6.38 label, which will cause /tftpboot/kernels/linux-2.6.38.bin |
| 205 | to be downloaded, and boot with the command line "root=/dev/sdb1" |
| 206 | |
| 207 | Differences with PXELINUX |
| 208 | ========================= |
Bin Meng | a187559 | 2016-02-05 19:30:11 -0800 | [diff] [blame] | 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. |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 213 | |
Bin Meng | a187559 | 2016-02-05 19:30:11 -0800 | [diff] [blame] | 214 | - U-Boot's pxe does not support the PXELINUX DHCP option codes specified |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 215 | in RFC 5071, but could be extended to do so. |
| 216 | |
Bin Meng | a187559 | 2016-02-05 19:30:11 -0800 | [diff] [blame] | 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 |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 219 | the machine like PXELINUX. |
| 220 | |
Bin Meng | a187559 | 2016-02-05 19:30:11 -0800 | [diff] [blame] | 221 | - U-Boot's pxe doesn't rely on or provide an UNDI/PXE stack in memory, it |
| 222 | only uses U-Boot. |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 223 | |
Bin Meng | a187559 | 2016-02-05 19:30:11 -0800 | [diff] [blame] | 224 | - U-Boot's pxe doesn't provide the full menu implementation that PXELINUX |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 225 | does, only a simple text based menu using the commands described in |
Wolfgang Denk | 6b62b9a | 2011-12-19 12:03:40 +0100 | [diff] [blame] | 226 | this README. With PXELINUX, it's possible to have a graphical boot |
Bin Meng | a187559 | 2016-02-05 19:30:11 -0800 | [diff] [blame] | 227 | menu, submenus, passwords, etc. U-Boot's pxe could be extended to support |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 228 | a more robust menuing system like that of PXELINUX's. |
| 229 | |
Bin Meng | a187559 | 2016-02-05 19:30:11 -0800 | [diff] [blame] | 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. |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 232 | |
Bin Meng | a187559 | 2016-02-05 19:30:11 -0800 | [diff] [blame] | 233 | - U-Boot's pxe only recognizes a single file on the initrd command line. It |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 234 | could be extended to support multiple. |
| 235 | |
Bin Meng | a187559 | 2016-02-05 19:30:11 -0800 | [diff] [blame] | 236 | - in U-Boot's pxe, the localboot command doesn't necessarily cause a local |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 237 | disk boot - it will do whatever is defined in the 'localcmd' env |
| 238 | variable. And since it doesn't support a full UNDI/PXE stack, the |
| 239 | type field is ignored. |
| 240 | |
Bin Meng | a187559 | 2016-02-05 19:30:11 -0800 | [diff] [blame] | 241 | - the interactive prompt in U-Boot's pxe only allows you to choose a label |
Jason Hobbs | 06283a6 | 2011-08-31 10:37:30 -0500 | [diff] [blame] | 242 | from the menu. If you want to boot something not listed, you can ctrl+c |
Bin Meng | a187559 | 2016-02-05 19:30:11 -0800 | [diff] [blame] | 243 | out of 'pxe boot' and use existing U-Boot commands to accomplish it. |