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:
STM32H7 | Function | BSB | ETH | Name | LAN8720 | Comment |
3V3 | P2.1 | P2.1 | VCC | |||
3V3 | P2.2 | P2.2 | VCC | |||
GND | P2.3 | P2.3 | GND | |||
GND | P2.4 | P2.4 | GND | |||
PC1 | ETH_MDC | P2.5 | P2.5 | MDC | ||
PA2 | ETH_MDIO | P2.6 | P2.6 | MDIO | MDIO | |
PA7 | RMII_CRS_DV | P2.7 | P2.7 | CRS_DV | CRS_DV/MODE2 | |
PA1 | RMII_REF_CLK | P2.8 | P2.8 | R_RXCLK | 50MHz from LAN8720 | |
PC5 | RMII_RXD1 | P2.9 | P2.9 | RXD1 | RXD1/MODE1 | |
PC4 | RMII_RXD0 | P2.10 | P2.10 | RXD0 | RXD0/MODE0 | |
PG13 | RMII_TXD0 | P2.11 | P2.11 | TXD0 | TXD0 | |
PG11 | RMII_TXEN | P2.12 | P2.12 | TX_EN | TXEN | |
PG10 | - | P2.13 | - | - | - | |
PG12 | RMII_TXD1 | P2.14 | P2.14 | TXD1 | TXD1 |
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:
Build the image from the sources, as documented in TBDBuilding Linux.
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:
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 >
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 >
Set the TFTP server IP address, for example:
STM32H7-SOM U-Boot > setenv serverip 192.168.0.3 STM32H7-SOM U-Boot >
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 >
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) ...
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:
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 >
Check the
image_vol_sizeenvironment 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 byCONFIG_MTDPARTS_DEFAULTinu-boot/configs/stm32h7_som_nor_defconfig:STM32H7-SOM U-Boot > prin image_vol_size image_vol_size=0xc00000 STM32H7-SOM U-Boot >
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
ipaddrandserveripcorrectly. Check ethaddr and make sure that you don't have another embedded board (eg. another STM32H7 SOM) configured for the same MAC address.