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 pxe
U-Boot command.
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 explained here [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 a PXE configuration file in pxelinux.cfg directory of the TFTP server and parses it.
3.1. PXE configuration file[edit source]
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 LABEL of the menu :
- the LABEL can be any 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 bootarg used to start the kernel is defined via the APPEND option, including the rootfs to use;
For example, for an STM32MP157C-EV1 board, with the rootfs on the 6th partition of the SDCard (/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 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, several options can be added by completing the labels list with other labels and TIMEOUT options (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).
{{ReviewsComments|NSA W939 : below what do you mean by" looks" ?, parse ?} 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 per board.
{{ReviewsComments|NSA W939 : below what do you mean by" share" ?, have ?} Each file of the pxelinux.cfg directory can share the same content (or can be a symbolic link to a default one).
{{ReviewsComments|NSA W939 : below what do you mean by "stm32mp1 " ? STM32MP157C-EV1 e.g.?} 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 <the 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