This application note explains how to build and run FreeRTOS run-time image for the Emcraft STM32H7 SOM and Starter Kit using STM32CubeIDE.

1. FreeRTOS Demo Project

Emcraft maintains the FreeRTOS sources for the STM32H7 SOM and Starter Kit in the following repository:

• https://gitlab.com/emcraft/STM32H7/STM32CubeH7 .

The emcraft-projects branch contains a project configuration compatible with the ST's STM32CubeIDE build and development framework.

This configuration installs the FreeRTOS executable binaries in to the STM32H7 SOM Flash, utilising both the STM32H7 internal Flash and the external QSPI Flash. This configuration is not compatible with the boot workflow where the U-Boot boot loader is used as the primary boot firmware.

The demo project for the STM32H7 SOM is freertos_stm32h7_som.

The project is configured to boot from the STM32H7 internal Flash. Limited size of the internal Flash does not allow to store the entire executable binary. The basic drivers fit into the internal Flash, however enabling additional FreeRTOS features and middleware may require additional storage. Due to the limited size of the internal Flash, some parts of the executable code are linked to the external SDRAM available on the STM32H7 SOM. Those parts are compiled to a separate binary and are stored in the QSPI Flash of the STM32H7 SOM. As a summary, when built, the project consists of 2 binary files - first one is freertos_stm32h7_som_intflash.bin, which contains the boot code and the HAL drivers is to be installed to the internal Flash, and second one is freertos_stm32h7_som_qspiflash.bin, which contains the FreeRTOS application code and middleware is to be installed to the QSPI Flash.

The standard ST tools support writing to the internal STM32H7 Flash memory, however to program the QSPI Flash an external loader program is required. This program is provided in a separate STM32CubeIDE project mt25ql512abb_stm32h7_som. This project is available at the same git repo on the emcraft-projects branch as the main demo project. The project mt25ql512abb_stm32h7_som must be built in the STM32CubeIDE and then the resultant binary MT25QL512A_STM32H7-SOM.stldr must be added to the STM32CubeIDE or STM32CubeProgrammer, in order to operate with the QSPI Flash of the STM32H7 SOM.

2. Software Set-Up

The STM32CubeIDE needs to be installed on the development host in order to build and debug FreeRTOS.

Go to https://www.st.com/en/development-tools/stm32cubeide.html and select the latest version of the IDE. The Emcraft configuration has been tested with STM32CubeIDE Version 1.15.1, using Ubuntu 22.04 as the development host.

3. Hardware Set-Up

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

• STM32H7-SOM Rev 2A soldered onto the STM32H7-BSB Rev 3A baseboard.

• The USB type-C cable connected to the J10 connector on the baseboard (to provide power supply to the board and 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.

The following picture illustrates the above hardware set-up:

4. Adding the FreeRTOS Project to STM32CubeIDE

Run the following step-wise procedure to import the FreeRTOS project to the STM32CubeIDE:

1. Create a separate directory and clone the FreeRTOS repository:

   $ mkdir stm32h7-som
   $ cd stm32h7-som
   $ git clone https://gitlab.com/emcraft/STM32H7/STM32CubeH7.git -b emcraft-projects
   

2. Start the STM32CubeIDE and select a workspace directory. The workspace directory is an arbitrary directory, different from the directory where your source file is located.

3. Click File->Open Projects from File System:
   

   

4. Select <STM32CubeH7 path>/freertos_stm32h7_som path and click Finish.

5. Building the Project

1. In Project Explorer double click to the freertos_stm32h750_som.ioc file to activate the Device Configuration Tool:

   

2. Click Project->Generate Code or press Alt-K to generate C-files from the .ioc file.

3. Click Project->Build Project or press Ctrl-B to start building.

4. Select the Console tab and check the output:

   

5. If needed, find the executable binaries in the Debug subfolder of the FreeRTOS project directory.

6. Running the Project

1. In order to program the application part of the freertos_stm32h7_som project to the QSPI Flash, use the external loader. The following procedure builds the mt25ql512abb_stm32h7_som external loader from the STM32CubeIDE in the same workspace, where the main demo project resides:

   1. Click File->Open Projects from File System:
      

      

   2. Select <STM32CubeH7 path>/mt25ql512abb_stm32h7_som path and click Finish.

   3. In Project Explorer double click to the mt25ql512abb_stm32h7_som.ioc file to activate the Device Configuration Tool:

      

   4. Click Project->Generate Code or press Alt-K to generate C-files from the .ioc file.

   5. Click Project->Build Project or press Ctrl-B to start building.

2. In Project Explorer select the freertos_stm32h7_som project. Then click Run->Run Configurations...:

   

3. Select STM32 C/C++ Application -> freertos_stm32h7_som Debug. Select the Debugger tab, scroll down and click Add... in the External loaders group:

   

4. Click Workspace... and select MT25QL512A_STM32H7-SOM.stldr file:

   

5. Apply changes and clone the Run Configurations... window.

6. Click the Run button at the top panel to install the application to the target board and run it:

   

7. The following prompt shall appear on the serial console:

   STM32H7 SOM FreeRTOS CLI, www.emcraft.com
   Type help to view a list of available commands.
   CLI>
   

7. Debugging the Project

Its is assumed that the MT25QL512A_STM32H7-SOM.stldr external loader is already added to the project's Run Configurations as per items 7.1 .. 7.5.

To support all debug features, the Watchdog timer (WDT) must be disabled in the project.

1. The dedicated option SKIP_WDT_TASK is defined in main.h in order to quickly enable/disable WDT in the project. To disable WDT set this option to 1 and rebuild the project:

   

2. Click the Debug button at the top panel to start debugging:

   

3. Select Remember my decision and switch to the Debug Perspective if prompted:

   

4. Wait for the STM32CubeIDE to write the firmware image to the target via ST-Link and stop at the main() function:

   

At this point SDRAM is not initialized yet. Only the code that is located in the internal Flash or internal RAM is available for setting breakpoints. If there were breakpoints set by a previous debug session which refer to SDRAM, they need to be deactivated. The breakpoints in SDRAM can be re-activated later, when the initialization code has been performed.

• Set a breakpoint after the MX_QUADSPI_Init() function is done:

  

• Proceed to execute the program.

• When the program stops at the breakpoint set in the 2 steps above, the QUADSPI interface is initialized and the application code is copied to SDRAM, so you can use breakpoints in the application code. Let's set a breakpoint at the prvHelpCommand() function in the CLI driver:

  

• Proceed to execute the program.

• Switch to the terminal with the serial console and type the help command:

  STM32H7 SOM FreeRTOS CLI, www.emcraft.com
  Type help to view a list of available commands.
  CLI> help
  

• Switch back to the debug session in the STM32CubeIDE. Make sure the execution is stopped at the breakpoint in the prvHelpCommand() function. Use the Step Over button to proceed the execution in a step-wise fashion:

  

• Proceed to execute the program in a step-wise fashion, set up breakpoints, examine variables and so on.

8. Known Problems and Limitations

This section lists known problems and limitations:

1. LCD is not supported.

2. The U-Boot environment and reliable upgrade are not available because the this configuration boots FreeRTOS with no reliance on U-Boot as the primary firmware.