This page explains how to boot the Linux kernel from U-Boot through a TFTP[1]server installed on a host PC, based on the U-Boot command pxe.
1. Documentation[edit source]
The documentation is available in the U-Boot source:
2. TFTP server installation on host PC[edit source]
The procedure to install a TFTP server on your PC host is available at this link [2].
3. TFTP server configuration[edit source]
U-Boot follows pxelinux's rules[3] to download from the TFTP server a PXE configuration file located in the pxelinux.cfg directory.
See more details here[4]
U-Boot pxe
command loads and parses a PXE configuration file in pxelinux.cfg directory of the TFTP server.
3.1. PXE configuration file[edit source]
Each PXE configuration file has same format as the extlinux.conf file generated by standard Yocto distribution.
The format of the PXE configuration text file is explained in this chapter. The next chapter explains the name of the file loaded by U-Boot.
For each LABEL of the menu, with KERNEL and FDT option, you define the kernel and the device tree loaded by U-Boot and the Linux bootarg used to start the kernel with the APPEND option, including the rootfs to use; it can be on a device (e•MMC, SDCard, NAND, and so on).
For example , for an STM32MP157C-EV1 board, with the rootfs on the 6th partition of the SDCard (/dev/mmcblk0p6), the 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), you can define the used rootfs
- as ramfs [5] with INITRD tag in configuration file.
The initrd need to be generated [6] - or as nfs mounting point [7] with the bootargs (APPEND: rootfstype=nfs nfsroot=... [8]) and nfs server [9].
In the file, you can add several options by adding other labels and TIMEOUT option (selection needs user action on the U-Boot console);
for example:
menu title Select the boot mode DEFAULT ramfs TIMEOUT 20 LABEL ramfs KERNEL uImage FDT stm32mp157c-ev1.dtb INITRD uInitrd APPEND 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 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
3.2. pxelinux.cfg directory[edit source]
Because more than one board may be booted from the same server, the PXE configuration file name depends on U-boot parameters (hardware address/IP address).
U-Boot looks in the pxelinux.cfg directory for a PXE configuration file name in this order:
- UUID comes from "pxeuuid" variable [10]
- hardware type and address: Ethernet (ARP[11] type "1") with MAC address[12] (ethaddr env variable)
- IP address of the board and each subnet mask
- 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 for your board.
Each file of the pxelinux.cfg directory can share the the same content (or can be a symbolic link to a default one).
For example, for an stm32mp1 target, when:
- UUID is not defined
- ethaddr=00:80:e1:01:2d:6f
- IP =10.48.0.141 (hexa coding=0A30008D)
- ARCH=arm and SOC=stm32mp
U-Boot searches the configuration file is this order:
- "01-00-80-e1-01-2d-6f"
- 0A30008D then subnet 0A30008, 0A3000, 0A300 ...
- 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 fallbackup file)
├── 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 source]
You can execute the DISTRO bootcmd for PXE:
env set serverip <you PC address> run bootcmd_pxe
5. Step by step example[edit source]
- STM32MP157C-EV1 board with mac address: ethaddr=00:80:e1:01:60:da
- 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 source]
- ↑ https://en.wikipedia.org/wiki/Trivial_File_Transfer_Protocol
- ↑ https://importgeek.wordpress.com/2013/09/04/install-configure-and-test-tftp-server-in-ubuntu/
- ↑ https://en.wikipedia.org/wiki/Preboot_Execution_Environment
- ↑ http://syslinux.zytor.com/wiki/index.php/PXELINUX
- ↑ https://en.wikipedia.org/wiki/Initial_ramdisk
- ↑ http://git.yoctoproject.org/cgit.cgi/poky/plain/meta/recipes-core/images/core-image-minimal-initramfs.bb
- ↑ https://en.wikipedia.org/wiki/Network_File_System
- ↑ https://www.kernel.org/doc/Documentation/filesystems/nfs/nfsroot.txt
- ↑ https://elinux.org/TFTP_Boot_and_NFS_Root_Filesystems
- ↑ https://en.wikipedia.org/wiki/Universally_unique_identifier
- ↑ https://en.wikipedia.org/wiki/Address_Resolution_Protocol
- ↑ https://en.wikipedia.org/wiki/MAC_address