This note explains how to load images to the target via Ethernet. With an Ethernet connection available, U-Boot can load images from a TFTP host quickly and easily. This is the development and software manufacturing option that is preferable with U-Boot and Linux.
The download procedure is based on the tftpboot command provided by the U-Boot command interface. tftboot implements a download capability over Ethernet using the TFTP protocol and has the following synopsis:
tftpboot <file> [<load_addr>]
If you do not specify a load address, then the value will be taken from the loadaddr environment variable. On the STM32H7 SOM board, loadaddr is set as follows, placing the download buffer into the on-module SDRAM:
STM32H7-SOM U-Boot > print loadaddr
loadaddr=0xD0C00000
The MAC address of the Ethernet interface is defined by the ethaddr environment variable.The IP address of the board is defined by the ipaddr U-Boot environment variable. The TFTP server IP address is defined by the serverip U-Boot environment variable. Make sure you define these environment variables to values that make sense for your LAN and save them into the QSPI Flash:
STM32H7-SOM U-Boot > env default -a
## Resetting to default environment
STM32H7-SOM U-Boot > setenv ethaddr 12:34:56:78:9a:bc
STM32H7-SOM U-Boot > setenv ipaddr 172.17.0.66
STM32H7-SOM U-Boot > setenv serverip 172.17.0.1
STM32H7-SOM U-Boot > saveenv
Saving Environment to UBI... ubi0: detaching mtd2
ubi0: mtd2 is detached
ubi0: default fastmap pool size: 256
ubi0: default fastmap WL pool size: 128
ubi0: attaching mtd2
ubi0: scanning is finished
ubi0: attached mtd2 (name "system", size 31 MiB)
ubi0: PEB size: 4096 bytes (4 KiB), LEB size: 3968 bytes
ubi0: min./max. I/O unit sizes: 1/256, sub-page size 1
ubi0: VID header offset: 64 (aligned 64), data offset: 128
ubi0: good PEBs: 7936, bad PEBs: 0, corrupted PEBs: 0
ubi0: user volume: 5, internal volumes: 1, max. volumes count: 23
ubi0: max/mean erase counter: 2/1, WL threshold: 4096, image sequence number: 0
ubi0: available PEBs: 989, total reserved PEBs: 6947, PEBs reserved for
bad PEB handling: 0
Writing to redundant UBI... done
OK
Once the transmission using tftpboot finishes, the file will be in memory at the specified load address. The loadaddr environment variable will automatically be set to the address the tftpboot command used. The filesize environment variable will automatically be set to the number of bytes transferred during the load operation.
Then you are free to do whatever you like with the loaded image. You can boot Linux from the image (assuming it is a Linux uImage file), display the memory, etc.
One typical command sequence involving tftpboot is defined in the netboot environment variable, which by default is set in U-Boot as follows:
STM32H7-SOM U-Boot > pri netboot
netboot=tftp ${image} && run addip addclk && bootm
STM32H7-SOM U-Boot >
What netboot does is load from tftpdir in a TFTP host a file defined by image (the tftp command), then add the TCP/IP related parameters to the kernel command string (addip), and finally boot Linux from the just loaded image (bootm).
Let's use netboot to boot Linux via TFTP from the sample Linux image (rootfs.uImage) included in the Emcraft software distribution. Copy rootfs.uImage to the appropriate (tftpdir) TFTP directory on the host and then from U-Boot on the target set the image environment variable to point to the image:
STM32H7-SOM U-Boot > setenv image stm32h7/rootfs.uImage
STM32H7-SOM U-Boot > saveenv
Saving Environment to UBI... ubi0: detaching mtd2
ubi0: mtd2 is detached
ubi0: default fastmap pool size: 256
ubi0: default fastmap WL pool size: 128
ubi0: attaching mtd2
ubi0: scanning is finished
ubi0: attached mtd2 (name "system", size 31 MiB)
ubi0: PEB size: 4096 bytes (4 KiB), LEB size: 3968 bytes
ubi0: min./max. I/O unit sizes: 1/256, sub-page size 1
ubi0: VID header offset: 64 (aligned 64), data offset: 128
ubi0: good PEBs: 7936, bad PEBs: 0, corrupted PEBs: 0
ubi0: user volume: 5, internal volumes: 1, max. volumes count: 23
ubi0: max/mean erase counter: 2/1, WL threshold: 4096, image sequence number: 0
ubi0: available PEBs: 989, total reserved PEBs: 6947, PEBs reserved for
bad PEB handling: 0
Writing to UBI... done
OK
STM32H7-SOM U-Boot > run netboot
ethernet@40028000 Waiting for PHY auto negotiation to complete. done
Using ethernet@40028000 device
TFTP from server 172.17.0.1; our IP address is 172.17.0.66
Filename 'stm32h7/rootfs.uImage'.
Load address: 0xd0c00000
Loading: #################################################################
#################################################################
#################################################################
#################################################################
#################################################################
#################################################################
#################################################################
#################################################################
#################################################################
###########################
2.7 MiB/s
done
Bytes transferred = 8982513 (890ff1 hex)
## Booting kernel from Legacy Image at d0c00000 ...
Image Name: Linux-6.1.28
Image Type: ARM Linux Multi-File Image (uncompressed)
Data Size: 8982449 Bytes = 8.6 MiB
Load Address: d0008000
Entry Point: d0008001
Contents:
Image 0: 8964864 Bytes = 8.5 MiB
Image 1: 17573 Bytes = 17.2 KiB
Verifying Checksum ... OK
## Loading init Ramdisk from multi component Legacy Image at d0c00000 ...
## Flattened Device Tree from multi component Image at D0C00000
Booting using the fdt at 0xd148cb4c
Loading Multi-File Image ... OK
Loading Ramdisk to d1971000, end d19754a5 ... OK
ERROR: reserving fdt memory region failed (addr=d1c00000 size=300000)
ERROR: reserving fdt memory region failed (addr=d1f00000 size=100000)
Loading Device Tree to d1969000, end d19704a4 ... OK
Starting kernel ...
[ 0.000000] Booting Linux on physical CPU 0x0
[ 0.000000] Linux version 6.1.28 (sasha@workbench.emcraft.com)
(arm-none-eabi-gcc (GNU Arm Embedded Toolchain 10.3-2021.10)
10.3.1 20210824 (release), GNU ld (GNU Arm Embedded Toolchain
10.3-2021.10) 2.36.1.20210621) #4 PREEMPT Thu Apr 25 13:48:32 UTC 2024
[ 0.000000] CPU: ARMv7-M [411fc271] revision 1 (ARMv7M), cr=00000000
[ 0.000000] CPU: PIPT / VIPT nonaliasing data cache, PIPT instruction cache
[ 0.000000] OF: fdt: Machine model: STM32H7 SOM Starter Kit
...
[ 7.405307] stm32-dwmac 40028000.ethernet eth0: No Safety Features
support found
[ 7.411929] stm32-dwmac 40028000.ethernet eth0: IEEE 1588-2008 Advanced
Timestamp supported
[ 7.422503] stm32-dwmac 40028000.ethernet eth0: registered PTP clock
[ 7.433559] stm32-dwmac 40028000.ethernet eth0: configuring for phy/rmii
link mode
[ 10.540095] stm32-dwmac 40028000.ethernet eth0: Link is Up - 100Mbps/
Full - flow control rx/tx
[ 10.548086] IPv6: ADDRCONF(NETDEV_CHANGE): eth0: link becomes ready
[ 182.570092] random: crng init done
/ # ps
PID USER VSZ STAT COMMAND
1 root 872 S init
2 root 0 SW [kthreadd]
3 root 0 IW< [rcu_gp]
4 root 0 IW< [rcu_par_gp]
5 root 0 IW< [slub_flushwq]
7 root 0 IW< [kworker/0:0H-ev]
8 root 0 IW [kworker/u2:0-ev]
9 root 0 IW< [mm_percpu_wq]
10 root 0 SW [ksoftirqd/0]
11 root 0 IW [rcu_preempt]
12 root 0 SW [kdevtmpfs]
13 root 0 IW< [inet_frag_wq]
15 root 0 IW< [writeback]
16 root 0 IW< [kblockd]
17 root 0 SW [watchdogd]
18 root 0 IW< [kworker/0:1H]
19 root 0 IW< [rpciod]
20 root 0 IW< [xprtiod]
21 root 0 IW< [cfg80211]
22 root 0 IW [kworker/u2:1-ev]
23 root 0 SW [kswapd0]
24 root 0 IW< [nfsiod]
25 root 0 SW [irq/36-40013400]
26 root 0 SW [spi0]
27 root 0 IW< [stmmac_wq]
31 root 0 SW [irq/38-40005400]
32 root 0 SW [irq/39-40005400]
33 root 0 SW [irq/40-58001c00]
34 root 0 SW [irq/41-58001c00]
35 root 0 SW [irq/42-mmci-pl1]
36 root 0 SW [irq/43-52007000]
37 root 0 SW [irq/44-mmci-pl1]
38 root 0 IW [kworker/0:2-eve]
39 root 0 IW< [mld]
40 root 0 IW< [ipv6_addrconf]
79 root 728 S dropbear -R
81 root 884 S -/bin/hush
106 root 0 IW [kworker/0:1-eve]
107 root 0 IW [kworker/0:0-eve]
108 root 880 R ps
/ #
Here are some troubleshooting tips, in case tftpboot does not work for you from U-Boot:
- As trivial as it sounds make sure that the board is connected to the LAN with an Ethernet cable.
- Suppose you are still not getting your file from the TFTP server. It is possible that the problem is on the host side - you must set up a TFTP server correctly. Just google for "how to set up a tftp server" and follow the advice from some top articles.
- Make sure you have copied a file you are trying to download to the TFTP server directory on the host.
- Disable the firewall on the host since get enabled, it will block TFTP requests from the target.
- On the target, make sure that you have set ipaddr and serverip correctly. Check ethaddr and make sure that you don't have another embedded board (eg. another STM32H7 SOM board) configured for the same MAC address.
