From: Fiona Klute Date: Mon, 30 Jun 2025 10:53:22 +0000 (+0200) Subject: doc: PXE usage: move environment variables to a separate section X-Git-Tag: v2025.10-rc1~44^2~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=773830f4d95df602ca7e3827373b595d6418a82d;p=thirdparty%2Fu-boot.git doc: PXE usage: move environment variables to a separate section This works better with RST formatting, and avoids duplication. Signed-off-by: Fiona Klute Cc: Tom Rini --- diff --git a/doc/usage/pxe.rst b/doc/usage/pxe.rst index 175938b942a..d23cd453227 100644 --- a/doc/usage/pxe.rst +++ b/doc/usage/pxe.rst @@ -17,33 +17,8 @@ Commands 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 syntax. It requires certain environment variables to be + set, see the Environment section below. **File Paths** @@ -62,54 +37,75 @@ Commands ``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. + depending on conditions, see the Environment section below. + +Environment +----------- + +``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. Required for ``pxe + get``, for ``pxe boot`` if the optional argument + ``pxefile_addr_r`` is not supplied. + +``bootfile`` + Typically set in the DHCP response handler, required for ``pxe + get``. For ``pxe boot``, 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. Required for ``pxe get``. + +``kernel_addr_r``, ``initrd_addr_r`` + Locations in RAM to store the kernel (or FIT image) and + initrd. 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 to store the retrieved fdt blob. 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`` + 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 to temporarily store fdt overlay(s) before + applying them to the fdt blob stored at + ``fdt_addr_r``. Required to use the ``fdtoverlays`` command in + the PXE file. + +``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. + +``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. pxe file format ---------------