This application note explains how to install (or update) a bootable Linux image (rootfs.uImage) to the STM32H7 System-On-Module using the Ethernet interface as the download channel.

Hardware Set-Up

The following hardware set-up is required for installation of the software to the STM32H7 SOM:

• STM32H7-SOM Rev 1A soldered onto the STM32H7-BSB Rev 4A baseboard;
• The USB Type C cable connected to the J10 connector on the baseboard (to provide the STM32H7 serial console to the development host);
• The ST-LINK/V2 debugger/programmer connected to the 20-pin P3 ARM JTAG connector on the baseboard (optional);
• The Ethernet cable connected to the J5 connector on the baseboard.

The following picture illustrates the above hardware set-up:

NOTE: The STM32H7-BSB Rev 1A/2A baseboards doesn't have the RJ-45 connector so the Waveshare LAN8720 ETH board should be connected to the P2 header with a special cable. The pin-out is as follows:

The following picture illustrates the hardware set-up for the STM32H7-BSB Rev 1A/2A baseboards:

NOTE: The STM32H7-BSB Rev 1A/2A baseboards are supported by BSP version 2.5.0. The newer versions support the STM32H7-BSB Rev 4A baseboard only.

Installable Linux uImage

The Linux uImage to be installed onto the STM32H7 SOM can be obtained using one of the two approaches, as follows:

1. Build the image from the sources, as documented in Building Linux.
2. Use the prebuilt image provided by Emcraft.

Configuring Network in U-Boot

The Linux image is installed from U-Boot using the Ethernet interface as the download channel.

Step through the following procedure to configure the network parameters in U-Boot:

1. Set the MAC address of the Ethernet interface (you can choose an arbitrary address for development purposes but make sure that it is unique within your LAN):

STM32H7-SOM U-Boot > setenv -f ethaddr
STM32H7-SOM U-Boot > setenv ethaddr 12:34:56:78:9a:bc
STM32H7-SOM U-Boot >

2. Set the IP address of the board to a value that makes sense for your LAN, for example:

STM32H7-SOM U-Boot > setenv ipaddr 192.168.0.166
STM32H7-SOM U-Boot >

3. Set the TFTP server IP address, for example:

STM32H7-SOM U-Boot > setenv serverip 192.168.0.3
STM32H7-SOM U-Boot >

4. Save the network parameters in the QSPI Flash:

STM32H7-SOM U-Boot > saveenv
Saving Environment to UBI... ubi0: detaching mtd2
...
Writing to redundant UBI... done
OK
STM32H7-SOM U-Boot >

5. Try to download a non-existent file from the TFTP server and confirm that the "File not found" error is reported:

STM32H7-SOM U-Boot > tftp dummy
ethernet@40028000 Waiting for PHY auto negotiation to complete. done
Using ethernet@40028000 device
TFTP from server 192.168.0.3; our IP address is 192.168.0.166
Filename 'dummy'.
Load address: 0xd0c00000
Loading: *
TFTP error: 'File not found or No Access' (1)
...

6. Copy the Linux image to the TFTP server and try to download it:

STM32H7-SOM U-Boot > printenv image
image=stm32h7/rootfs.uImage
STM32H7-SOM U-Boot > tftp $image
Using ethernet@40028000 device
TFTP from server 192.168.0.3; our IP address is 192.168.0.166
Filename 'stm32h7/rootfs.uImage'.
Load address: 0xd0c00000
Loading: #################################################################
         #################################################################
         #################################################################
         #################################################################
         #################################################################
         #################################################################
         ############################
         191.4 KiB/s
done
Bytes transferred = 6126586 (5d7bfa hex)
STM32H7-SOM U-Boot >

Installing Linux to QSPI Flash

Step through the following procedure to install the Linux to the QSPI Flash:

1. Copy the Linux image to the TFTP server, adjust the image environment variable, if needed:

STM32H7-SOM U-Boot > printenv image
image=stm32h7/rootfs.uImage
STM32H7-SOM U-Boot >

2. Check the image_vol_size environment variable, which specifies the size of the UBI volume containing the Linux image. Note that this size should correlate with the size of the system MTD partition configured by CONFIG_MTDPARTS_DEFAULT in u-boot/configs/stm32h7_som_nor_defconfig:

STM32H7-SOM U-Boot > prin image_vol_size
image_vol_size=0xc00000
STM32H7-SOM U-Boot >

3. Download the Linux image from the TFTP server and install it to the QSPI Flash:

STM32H7-SOM U-Boot > run reliable_install
Using ethernet@40028000 device
TFTP from server 192.168.0.3; our IP address is 192.168.0.166
Filename 'stm32h7/rootfs.uImage'.
Load address: 0xd0c00000
Loading: #################################################################
         #################################################################
         #################################################################
         #################################################################
         #################################################################
         #################################################################
         ############################
         209 KiB/s
done
Bytes transferred = 6126586 (5d7bfa hex)
Volume rtos1 not found!
Volume rtos2 not found!
Creating dynamic volume rtos1 of size 8388608
Creating dynamic volume rtos2 of size 8388608
6126586 bytes written to volume rtos1
Saving Environment to UBI... ubi0: detaching mtd2
ubi0: mtd2 is detached
ubi0: default fastmap pool size: 8
ubi0: default fastmap WL pool size: 4
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: 4, internal volumes: 1, max. volumes count: 23
ubi0: max/mean erase counter: 2/1, WL threshold: 4096, image sequence 
number: 0
ubi0: available PEBs: 1518, total reserved PEBs: 6418, PEBs reserved for 
bad PEB handling: 0
Read 16384 bytes from volume env1 to d196f520
Read 16384 bytes from volume env2 to d1973540
OK
In:    serial
Out:   serial
Err:   serial
Volume splash not found!
splash_screen_display: ubi_volume_read error=19
Net:   eth0: ethernet@40028000
Hit any key to stop autoboot:  0
Booting Image #1
No size specified -> Using max size (12586496)
Read 12586496 bytes from volume rtos1 to d0c00000
## Booting kernel from Legacy Image at d0c00000 ...
   Image Name:   Linux-6.1.28
   Image Type:   ARM Linux Multi-File Image (uncompressed)
   Data Size:    8982565 Bytes = 8.6 MiB
   Load Address: d0008000
   Entry Point:  d0008001
   Contents:
      Image 0: 8964864 Bytes = 8.5 MiB
      Image 1: 17689 Bytes = 17.3 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 d1975519 ... 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 d1970518 ... 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) #2 PREEMPT Fri May  3 06:01:56 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
[    0.000000] printk: bootconsole [earlycon0] enabled
[    0.000000] printk: debug: ignoring loglevel setting.
[    0.000000] Reserved memory: created DMA memory pool at 0xd1f00000, 
size 1 MiB
[    0.000000] OF: reserved mem: initialized node dmapool, compatible id 
shared-dma-pool
[    0.000000] Zone ranges:
[    0.000000]   Normal   [mem 0x00000000d0000000-0x00000000d1ffffff]
[    0.000000] Movable zone start for each node
[    0.000000] Early memory node ranges
[    0.000000]   node   0: [mem 0x00000000d0000000-0x00000000d1bfffff]
[    0.000000]   node   0: [mem 0x00000000d1c00000-0x00000000d1ffffff]
[    0.000000] Initmem setup node 0 [mem 0x00000000d0000000-
0x00000000d1ffffff]
[    0.000000] pcpu-alloc: s0 r0 d32768 u32768 alloc=1*32768
[    0.000000] pcpu-alloc: [0] 0
[    0.000000] Built 1 zonelists, mobility grouping on.  Total pages: 8128
[    0.000000] Kernel command line: console=ttySTM2,115200 earlyprintk 
consoleblank=0 
panic=3 ignore_loglevel ip=192.168.0.166:192.168.0.3::::eth0:off clk_ignore
_unused
...
[81] Jan 01 00:00:04 Running in background
/ #

Troubleshooting Ethernet

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) configured for the same MAC address.