How to boot the kernel via TFTP from U-Boot

This page explains how to boot the Linux® kernel from U-Boot through a TFTP server installed on a host PC, based on the pxe U-Boot command.

1 Documentation[edit]

The documentation is available in the U-Boot source:

2 TFTP server installation on host PC[edit]

The procedure, to install a TFTP server on your PC host, is explained here [1].

3 TFTP server configuration[edit]

U-Boot follows pxelinux's rules to download from the TFTP server a PXE configuration file located in the pxelinux.cfg directory.
See more details here[2]

U-Boot pxe command loads a PXE configuration file in pxelinux.cfg directory of the TFTP server and parses it.

3.1 PXE configuration file[edit]

Each PXE configuration file has same format as the extlinux.conf file, generated by a standard Yocto distribution.

The format of the PXE configuration text file is explained in this chapter. More explanations on the name of the file loaded by U-Boot are given in next chapter.

For each element of the menu :

  • the LABEL is a string, for example the boot device such as an e•MMC, SD card, NAND, and so on.
  • the kernel and the device tree loaded by U-Boot are defined via KERNEL and FDT options.
  • the Linux® kernel boot arguments are defined via the APPEND option, including the rootfs to use;

For example, for STM32MP157C-EV1 Evaluation board More info.png, with the rootfs on the 6th partition of the SD card (/dev/mmcblk0p6), the PXE configuration file is:

 menu title Select the boot mode
 DEFAULT sdcard
 LABEL sdcard
 	KERNEL uImage
 	FDT stm32mp157c-ev1.dtb
 	APPEND root=/dev/mmcblk0p6 rootwait rw earlyprintk console=ttySTM0,115200

To fully boot on a network (kernel and rootfs), the rootfs to use can be defined :

  • as initramfs with INITRD command in configuration file.
    The file uInitrd need to be generated, for example with yocto command:
PC $> bitbake core-image-minimal-initramfs
  • or as NFS mounting point with Linux® kernel boot arguments nfsroot[3] added in APPEND command (root=/dev/nfs nfsroot=... ) and NFS server running on the PC[4].

In the configuration file, the menu can have several options (see LABEL, DEFAULT and TIMEOUT commands in README.pxe for details).

For example

 menu title Select the boot mode
 DEFAULT initramfs
 TIMEOUT 20
 LABEL initramfs
 	KERNEL uImage
 	FDT stm32mp157c-ev1.dtb
 	INITRD uInitrd
 	APPEND rootwait rw earlyprintk console=ttySTM0,115200
 LABEL nfs
 	KERNEL uImage
 	FDT stm32mp157c-ev1.dtb
 	APPEND root=/dev/nfs nfsroot=192.168.1.1:/nfsroot ip=dhcp rootwait rw earlyprintk console=ttySTM0,115200
 LABEL sdcard
 	KERNEL uImage
 	FDT stm32mp157c-ev1.dtb
 	APPEND root=/dev/mmcblk0p6 rootwait rw earlyprintk console=ttySTM0,115200
 LABEL eMMC
 	KERNEL uImage
 	FDT stm32mp157c-ev1.dtb
 	APPEND root=/dev/mmcblk1p6 rootwait rw earlyprintk console=ttySTM0,115200

3.2 pxelinux.cfg directory[edit]

Because more than one board may be booted from the same server, the "PXE configuration file" name depends on U-boot parameters (hardware address of the board/IP address).

U-Boot searches for a PXE configuration file in the pxelinux.cfg directory in this order:

  1. UUID comes from "pxeuuid" variable
  2. hardware type and address: ARP type "1" for Ethernet and MAC address
  3. IP address of the board and each subnet mask
  4. at the end, the file named "default-$CONFIG_SYS_ARCH-$CONFIG_SYS_SOC"

You need to provide at least one configuration file on the TFTP server per board.

Each file of the pxelinux.cfg directory can have the same content (or can be a symbolic link to a default one).

For example with STM32MP1 Series, when:

  • UUID is not defined
  • ethaddr=00:80:e1:01:2d:6f
  • IP =10.48.0.141 (hexa coding=0A30008D)
  • CONFIG_SYS_ARCH=arm and CONFIG_SYS_SOC="stm32mp"

U-Boot searches the configuration file is this order:

  1. "01-00-80-e1-01-2d-6f"
  2. 0A30008D then subnet 0A30008, 0A3000, 0A300 ...
  3. default-arm-stm32mp


With ethaddr=00:80:e1:01:2d:6f, the tftp directory (for example /tftpboot) may look like:

 ├── pxelinux.cfg                   directory
 │   ├── 01-00-80-e1-01-2d-6f       configuration file for MAC address 00:80:e1:01:2d:6f
 ├── stm32mp157c-ev1.dtb            device tree
 ├── uImage                         kernel

An other example with

  • different boards (identified by a MAC address)
    each pxe file selects a different device tree (ed1, ev1, dk1, dk2) or kernel file
  • fallback with the IP address submask (symbolic link to default-arm-stm32mp)
  • default-arm-stm32mp (final fallback file, name based on CONFIG_SYS_SOC)
 ├── pxelinux.cfg
 │   ├── 01-00-80-e1-01-2d-6f            configuration file for MAC address 00:80:e1:01:2d:6f
 │   ├── 01-00-80-e1-42-42-8c            configuration file for MAC address 00:80:e1:42:42:8c
 │   ├── 01-00-80-e1-42-42-cd            configuration file for MAC address 00:80:e1:42:42:cd
 │   ├── 01-00-80-e1-42-46-76            configuration file for MAC address 00:80:e1:42:46:6f
 │   ├── 0A300 -> default-arm-stm32mp    configuration file for IP address 10.48.0*.**
 │   ├── 0A30001 -> default-arm-stm32mp  configuration file for IP address 10.48.00.1*
 │   ├── 0A30004 -> default-arm-stm32mp  configuration file for IP address 10.48.00.4*
 │   ├── 0A30008 -> default-arm-stm32mp  configuration file for IP address 10.48.00.8*
 │   └── default-arm-stm32mp             default configuration file
 ├── stm32mp157c-ed1.dtb
 ├── stm32mp157c-ev1.dtb
 ├── stm32mp157a-dk1.dtb
 ├── stm32mp157c-dk2.dtb
 ├── uImage
 ├── uInitrd

4 Board command in U-boot console[edit]

You can execute the DISTRO bootcmd for PXE:

 Board $> env set serverip <the PC address>
 Board $> run bootcmd_pxe

5 Step by step example[edit]

  1. STM32MP157C-EV1 board with MAC address: ethaddr=00:80:e1:01:60:da
  2. Install and configure a TFTP server:
    • IP address is 10.201.21.107
    • directory is :
 ├── pxelinux.cfg
 │   ├── 01-00-80-e1-01-60-da
 ├── stm32mp157c-ev1.dtb 
 ├── uImage

With the text file 01-00-80-e1-01-60-da ( #PXE configuration file in #pxelinux.cfg directory) :

menu title Select the boot mode
DEFAULT sdcard
LABEL sdcard
	KERNEL uImage
	FDT stm32mp157c-ev1.dtb
	APPEND root=/dev/mmcblk0p6 rootwait rw earlyprintk console=ttySTM0,115200

In the U-Boot console:

 STM32MP> env set serverip 10.201.21.107                              set the server address
 STM32MP> run bootcmd_pxe                                            execute the DISTRO command
 BOOTP broadcast 1
 DHCP client bound to address 10.48.1.229 (19 ms)
 missing environment variable: pxeuuid
 missing environment variable: bootfile
 Retrieving file: pxelinux.cfg/01-00-80-e1-01-60-da
 Using ethernet@5800a000 device
 TFTP from server 10.201.21.107; our IP address is 10.48.1.229; sending through gateway 10.48.3.254
 Filename 'pxelinux.cfg/01-00-80-e1-01-60-da'.                       load configuration file
 Load address: 0xc4200000
 Loading: #
 	 105.5 KiB/s
 done
 Bytes transferred = 435 (1b3 hex)
 Config file found
 Select the boot mode                                                display menu
 1:	sdcard
 Enter choice: 1:	sdcard                                       timeout: default choice
 missing environment variable: bootfile
 Retrieving file: uImage                                             load kernel
 Using ethernet@5800a000 device
 TFTP from server 10.201.21.107; our IP address is 10.48.1.229; sending through gateway 10.48.3.254
 Filename 'uImage'.
 Load address: 0xc2000000
 Loading: #################################################################
 	 #################################################################
 	 #################################################################
 	 #################################################################
 	 #################################################################
 	 #################################################################
 	 #################################################################
 	 #################################################################
 	 #################################################################
 	 #################################################################
 	 #################################################################
 	 #################################################################
 	 #################################################################
 	 #################################################################
 	 #################################################################
 	 #################################################################
 	 #################################################################
 	 ################
 	 785.2 KiB/s
 done
 Bytes transferred = 5734976 (578240 hex)
 append: root=/dev/mmcblk0p6 rootwait rw earlyprintk console=ttySTM0,115200
 missing environment variable: bootfile
 Retrieving file: stm32mp157c-ev1.dtb                                  load device tree
 Using ethernet@5800a000 device
 TFTP from server 10.201.21.107; our IP address is 10.48.1.229; sending through gateway 10.48.3.254
 Filename 'stm32mp157c-ev1.dtb'.
 Load address: 0xc4000000
 Loading: ############################
 	 646.5 KiB/s
 done
 Bytes transferred = 138450 (21cd2 hex)
 ## Booting kernel from Legacy Image at c2000000 ...                    booting
    Image Name:   Linux-4.19.49
    Created:      2019-09-04  11:20:19 UTC
    Image Type:   ARM Linux Kernel Image (uncompressed)
    Data Size:    5734912 Bytes = 5.5 MiB
    Load Address: c2000040
    Entry Point:  c2000040
    Verifying Checksum ... OK
 ## Flattened Device Tree blob at c4000000
    Booting using the fdt blob at 0xc4000000
    XIP Kernel Image ... OK
    Using Device Tree in place at c4000000, end c4024cd1
 SF: Detected mx66l51235l with page size 256 Bytes, erase size 64 KiB, total 64 MiB
 
 Starting kernel ...                                                    starting kernel
 
 [    0.000000] Booting Linux on physical CPU 0x0
 ....
 [    0.000000] Kernel command line: root=/dev/mmcblk0p6 rootwait rw earlyprintk console=ttySTM0,115200
 ....

6 References[edit]


MultimediaCard

SD memory card (https://www.sdcard.org) - NEW

former spelling for e•MMC ('e' in italic)

universally unique identifier (https://en.wikipedia.org/wiki/Universally_unique_identifier) - NEW

Protocol used by the Internet Protocol, specifically IPv4, to map IP network addresses to the hardware addresses used by a data link protocol (https://en.wikipedia.org/wiki/Address_Resolution_Protocol)

media access control address (https://en.wikipedia.org/wiki/MAC_address) - NEW

Execute In Place. Method of executing programs directly from long term storage rather than copying it into RAM (linked to NOR Flash).

Central processing unit

Attachments

Discussions