This application note explains how to build and 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 USD 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.

Building Linux

Linux images are built on the cross-development host. Make sure that you activate the cross development environment as described in Installing and Activating Cross Development Environment.

In the Emcraft software distribution, Linux images are built from project directories. A project defines a concrete Linux configuration ready for installation to the target. Each project is defined by the following files:

• ${MCU}_defconfig - kernel configuration for the project;
• <project>.busybox - busybox configuration for the project;
• <project>.initrams - spec file for the project root filesystem (initramfs).

When you run make from the project directory (for instance, from projects/rootfs), the build system builds project-specific versions of the Linux kernel and busybox, then creates an initramfs filesystem containing the newly built busybox binary as well as other target files defined by the initramfs filesystem specification file, and finally wraps it all up into a single Linux image (rootfs.uImage) ready for download to the target.

Step through the following procedure to build a Linux project:

1. Activate the cross development environment:

$ . ./ACTIVATE.sh

2. Change to the project directory, for instance:

$ cd projects/rootfs

3. Run make to create the project rootfs.uImage ready for load to the target:

$ make

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=0x800000
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 23 MiB)
ubi0: PEB size: 131072 bytes (128 KiB), LEB size: 126976 bytes
ubi0: min./max. I/O unit sizes: 2048/2048, sub-page size 2048
ubi0: VID header offset: 2048 (aligned 2048), data offset: 4096
ubi0: good PEBs: 184, bad PEBs: 0, corrupted PEBs: 0
ubi0: user volume: 4, internal volumes: 1, max. volumes count: 128
ubi0: max/mean erase counter: 2/1, WL threshold: 4096, image sequence number:
 0
ubi0: available PEBs: 22, total reserved PEBs: 162, PEBs reserved for bad 
PEB handling: 20
Writing to UBI... done
OK
STM32H7-SOM U-Boot >

4. Verify that the Linux has been successfully installed. Reset the SOM by pressing the S3 button on the carrier board and confirm that the following output appears on the serial UART console:

U-Boot SPL 2019.04-gec287f63c5 (Jun 16 2023 - 14:31:30 +0000)
Hit 's' key to enter spl shell:
Trying to boot from SPI


U-Boot 2019.04-gec287f63c5 (Jun 16 2023 - 14:31:30 +0000)

Model: STMicroelectronics STM32H7 SOM
DRAM:  28 MiB
Flash: 128 KiB
MMC:   STM32 SDMMC2: 0
Loading Environment from UBI... 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 23 MiB)
ubi0: PEB size: 131072 bytes (128 KiB), LEB size: 126976 bytes
ubi0: min./max. I/O unit sizes: 2048/2048, sub-page size 2048
ubi0: VID header offset: 2048 (aligned 2048), data offset: 4096
ubi0: good PEBs: 184, bad PEBs: 0, corrupted PEBs: 0
ubi0: user volume: 4, internal volumes: 1, max. volumes count: 128
ubi0: max/mean erase counter: 2/1, WL threshold: 4096, image sequence 
number: 0
ubi0: available PEBs: 22, total reserved PEBs: 162, PEBs reserved for bad 
PEB ha ndling: 20
Read 16384 bytes from volume env1 to d1e6d6e0
Read 16384 bytes from volume env2 to d1e71700
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 (8507392)
Read 8507392 bytes from volume rtos1 to d0c00000
## Booting kernel from Legacy Image at d0c00000 ...
   Image Name:   Linux-5.15.67-00009-g75b7979d4ab
   Image Type:   ARM Linux Multi-File Image (uncompressed)
   Data Size:    6126522 Bytes = 5.8 MiB
   Load Address: d0408000
   Entry Point:  d0408001
   Contents:
      Image 0: 6111552 Bytes = 5.8 MiB
      Image 1: 14958 Bytes = 14.6 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 0xd11d418c
   Loading Multi-File Image ... OK
   Loading Ramdisk to d1e70000, end d1e73a6e ... OK
   Loading Device Tree to d1e69000, end d1e6fa6d ... OK

Starting kernel ...

[    0.000000] Booting Linux on physical CPU 0x0
[    0.000000] Linux version 5.15.67-00009-g75b7979d4ab2 
(sasha_d@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) #371 
PREEMPT Fri Jun 16 18:54:05 UTC 2023
[    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 0xd0300000, 
size 1 MiB
[    0.000000] OF: reserved mem: initialized node dmapool@d0300000, 
compatible id 
shared-dma-pool
[    0.000000] Zone ranges:
[    0.000000]   Normal   [mem 0x00000000d0400000-0x0000000
0d1ffffff]
[    0.000000] Movable zone start for each node
[    0.000000] Early memory node ranges
[    0.000000]   node   0: [mem 0x00000000d0400000-0x00000000d1ffffff]
[    0.000000] Initmem setup node 0 [mem 0x00000000d0400000-0x0
0000000d1ffffff]
[    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: 7112
[    0.000000] Kernel command line: console=ttySTM0,115200 earlyprintk 
consoleblank=0 
panic=3 ignore_loglevel
...
init started: BusyBox v1.24.2 (2023-05-19 20:14:28)
mount: mounting devpts on /dev/pts failed: No such device
/ #

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.