doc/README.pxe - filogic/uboot - Gitiles

 SPDX-License-Identifier: GPL-2.0+
 /*
  * Copyright 2010-2011 Calxeda, Inc.
  */

 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(or FIT image) 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_r - location in RAM at which 'pxe boot' will store the fdt blob it
      retrieves from tftp. The retrieval is possible if 'fdt' label is defined in
      pxe file and 'fdt_addr_r' is set. If retrieval is possible, 'fdt_addr_r'
      will be passed to bootm command to boot the kernel.

      fdt_addr - the location of a fdt blob. 'fdt_addr' will be passed to bootm
      command if it is set and 'fdt_addr_r' is not passed to bootm command.

      fdtoverlay_addr_r - location in RAM at which 'pxe boot' will temporarily store
      fdt overlay(s) before applying them to the fdt blob stored at 'fdt_addr_r'.

      pxe_label_override - override label to be used, if exists, instead of the
      default label. This will allow consumers to choose a pxe label at
      runtime instead of having to prompt the user. If "pxe_label_override" is set
      but does not exist in the pxe menu, pxe would fallback to the default label if
      given, and no failure is returned but rather a warning message.

 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.

 fallback <label>    - the label named here is treated as a fallback option that
 		      may be attempted should it be detected that booting of
 		      the default has failed to complete, for example via
 		      U-Boot's boot count limit functionality.

 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
 		      (or FIT image) 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.
 		      For FIT image, The configuration specification can be
 		      appended to the file name, with the format:
 		        <path>#<conf>[#<extra-conf[#...]]
 		      It will passed to bootm with that address.
 		      (see: doc/uImage.FIT/command_syntax_extensions.txt)
 		      It useful for overlay selection in pxe file
 		      (see: doc/uImage.FIT/overlay-fdt-boot.txt)

 fdtoverlays <path> [...] - if this label is chosen, use tftp to retrieve the DT
                       overlay(s) at <path>. it will be temporarily stored at the
                       address indicated in the fdtoverlay_addr_r environment variable,
                       and then applied in the load order to the fdt blob stored at the
                       address indicated in the fdt_addr_r environment variable.

 devicetree-overlay <path> [...] - if this label is chosen, use tftp to retrieve the DT
                       overlay(s) at <path>. it will be temporarily stored at the
                       address indicated in the fdtoverlay_addr_r environment variable,
                       and then applied in the load order to the fdt blob stored at the
                       address indicated in the fdt_addr_r environment variable.
                       Alias for fdtoverlays.

 kaslrseed           - set this label to request random number from hwrng as kaslr seed.

 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.
 		      For FIT image, the initrd can be provided with the same value than
 		      kernel, including configuration:
 		        <path>#<conf>[#<extra-conf[#...]]
 		      In this case, kernel_addr_r is passed to bootm.

 fdt <path>	    - if this label is chosen, use tftp to retrieve the fdt blob
 		      at <path>. it will be stored at the address indicated in
 		      the fdt_addr_r environment variable, and that address will
 		      be passed to bootm.
 		      For FIT image, the device tree can be provided with the same value
 		      than kernel, including configuration:
 		        <path>#<conf>[#<extra-conf[#...]]
 		      In this case, kernel_addr_r is passed to bootm.

 devicetree <path>   - if this label is chosen, use tftp to retrieve the fdt blob
 		      at <path>. it will be stored at the address indicated in
 		      the fdt_addr_r environment variable, and that address will
 		      be passed to bootm. Alias for fdt.

 fdtdir <path>	    - if this label is chosen, use tftp to retrieve a fdt blob
 		      relative to <path>. If the fdtfile environment variable
 		      is set, <path>/<fdtfile> is retrieved. Otherwise, the
 		      filename is generated from the soc and board environment
 		      variables, i.e. <path>/<soc>-<board>.dtb is retrieved.
 		      If the fdt command is specified, fdtdir is ignored.

 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/base.menu-----------
 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 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.
	SPDX-License-Identifier: GPL-2.0+
	/*
	* Copyright 2010-2011 Calxeda, Inc.
	*/

	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(or FIT image) 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_r - location in RAM at which 'pxe boot' will store the fdt blob it
	retrieves from tftp. The retrieval is possible if 'fdt' label is defined in
	pxe file and 'fdt_addr_r' is set. If retrieval is possible, 'fdt_addr_r'
	will be passed to bootm command to boot the kernel.

	fdt_addr - the location of a fdt blob. 'fdt_addr' will be passed to bootm
	command if it is set and 'fdt_addr_r' is not passed to bootm command.

	fdtoverlay_addr_r - location in RAM at which 'pxe boot' will temporarily store
	fdt overlay(s) before applying them to the fdt blob stored at 'fdt_addr_r'.

	pxe_label_override - override label to be used, if exists, instead of the
	default label. This will allow consumers to choose a pxe label at
	runtime instead of having to prompt the user. If "pxe_label_override" is set
	but does not exist in the pxe menu, pxe would fallback to the default label if
	given, and no failure is returned but rather a warning message.

	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.

	fallback <label> - the label named here is treated as a fallback option that
	may be attempted should it be detected that booting of
	the default has failed to complete, for example via
	U-Boot's boot count limit functionality.

	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
	(or FIT image) 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.
	For FIT image, The configuration specification can be
	appended to the file name, with the format:
	<path>#<conf>[#<extra-conf[#...]]
	It will passed to bootm with that address.
	(see: doc/uImage.FIT/command_syntax_extensions.txt)
	It useful for overlay selection in pxe file
	(see: doc/uImage.FIT/overlay-fdt-boot.txt)

	fdtoverlays <path> [...] - if this label is chosen, use tftp to retrieve the DT
	overlay(s) at <path>. it will be temporarily stored at the
	address indicated in the fdtoverlay_addr_r environment variable,
	and then applied in the load order to the fdt blob stored at the
	address indicated in the fdt_addr_r environment variable.

	devicetree-overlay <path> [...] - if this label is chosen, use tftp to retrieve the DT
	overlay(s) at <path>. it will be temporarily stored at the
	address indicated in the fdtoverlay_addr_r environment variable,
	and then applied in the load order to the fdt blob stored at the
	address indicated in the fdt_addr_r environment variable.
	Alias for fdtoverlays.

	kaslrseed - set this label to request random number from hwrng as kaslr seed.

	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.
	For FIT image, the initrd can be provided with the same value than
	kernel, including configuration:
	<path>#<conf>[#<extra-conf[#...]]
	In this case, kernel_addr_r is passed to bootm.

	fdt <path> - if this label is chosen, use tftp to retrieve the fdt blob
	at <path>. it will be stored at the address indicated in
	the fdt_addr_r environment variable, and that address will
	be passed to bootm.
	For FIT image, the device tree can be provided with the same value
	than kernel, including configuration:
	<path>#<conf>[#<extra-conf[#...]]
	In this case, kernel_addr_r is passed to bootm.

	devicetree <path> - if this label is chosen, use tftp to retrieve the fdt blob
	at <path>. it will be stored at the address indicated in
	the fdt_addr_r environment variable, and that address will
	be passed to bootm. Alias for fdt.

	fdtdir <path> - if this label is chosen, use tftp to retrieve a fdt blob
	relative to <path>. If the fdtfile environment variable
	is set, <path>/<fdtfile> is retrieved. Otherwise, the
	filename is generated from the soc and board environment
	variables, i.e. <path>/<soc>-<board>.dtb is retrieved.
	If the fdt command is specified, fdtdir is ignored.

	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/base.menu-----------
	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 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.