4.1.0
ST Edge AI Core for STM32 series


ST Edge AI Core

ST Edge AI Core for STM32 series


for STM32 target, based on ST Edge AI Core Technology 4.1.0



r1.3

Overview

This article describes the STM32-specific command-line options supported by ST Edge AI Core.

Supported STM32 series

The STM32 family consists of 32-bit microcontrollers based on Arm Cortex®-M processors.

supported series description
stm32f4/stm32g4/stm32f3/stm32wb All STM32F4xx, STM32G4xx, STM32F3xx, and STM32WBxx devices with an Arm® Cortex®-M4 core and single-precision FPU support.
stm32l4/stm32l4+ All STM32L4xx and STM32L4Rxx devices with an Arm® Cortex®-M4 core and single-precision FPU support.
stm32n6 All STM32N6xx devices with an Arm® Cortex®-M55 core, with or without the Neural-ART accelerator™.
stm32l5/stm32u5/stm32h5/stm32c5/stm32u3 All STM32L5xx, STM32U5xx, STM32H5xx, STM32C5xx, and STM32U3xx devices with an Arm® Cortex®-M33 core and single-precision FPU support. For the STM32U3 series with the Hardware Signal Processing (HSP) unit, use --hsp.
stm32f7 All STM32F7xx devices with an Arm® Cortex®-M7 core and single-precision FPU support.
stm32h7 All STM32H7xx devices with an Arm® Cortex®-M7 core and double-precision FPU support, with or without the Neural-ART accelerator™.
stm32v8 All STM32V8xx devices with an Arm® Cortex®-M85 core.
stm32l0/stm32g0/stm32c0 All STM32L0xx, STM32G0xx, and STM32C0xx devices with an Arm® Cortex®-M0+ core, without FPU or DSP extension support.
stm32f0 All STM32F0xx devices with an Arm® Cortex®-M0+ core, without FPU or DSP extension support.
stm32wl All STM32WLxx devices with an Arm® Cortex®-M4 core, without FPU support and with DSP extension support.

Warning

All provided inference runtime libraries for the STM32 series, except STM32WL, are compiled with FPU support enabled and the hard floating-point EABI option for performance.

STM32N6 series supporting the Neural-ART accelerator™

  • An STM32N6 device without Neural-ART is supported like a conventional STM32xx device, using optimized AI runtime libraries for Arm® Cortex® M55 core. It is implemented to use the M-Profile Vector Extension (MVE). Consequently, the generated C file cannot be executed on the host machine, and Validation on host is not supported.
  • A dedicated Neural-ART Compiler generates specialized C files for an STM32N6 device with Neural-ART. No simulator or emulator is provided, so the Validation on host workflow is not supported.

STM32U3 series supporting the Hardware Signal Processing (HSP) unit

  • An STM32U3 device without the HSP unit is supported like a conventional STM32U3 device, using optimized AI runtime libraries for Arm® Cortex® M33 core.
  • For an STM32U3 device with the HSP unit, using the --hsp option enables the stedgeai command-line interface (CLI) to select the most appropriate implementation: HSP-optimized functions or an STM32 software implementation when preferable. The CLI also manages memory allocation and layer connections. Individual layers of a convolutional neural network (CNN) can be accelerated through HSP middleware CNN direct commands. Only 8-bit quantized pointwise (PW), depthwise (DW), dense (fully connected), Conv2D, and 2D pooling (average or max) layers are supported (refer to the application note: “AN6400 - How to use the HSP for executing DSP and CNN operations on STM32 MCUs”). Note that no simulator or emulator is provided, so the Validation on host workflow is not supported.

The analyze command identifies operators accelerated by the HSP unit. These operators are marked with the "(hspX)" type extension in the output.

 Number of operations per c-layer
 ------- ------ ------------------------------ ----------- ------------
 c_id    m_id   name (type)                            #op         type
 ------- ------ ------------------------------ ----------- ------------
 0       0      conv2d_0 (Conv2D)  (hsp2)          320,064   smul_s8_s8
 1       1      conv2d_1 (Conv2D_DW)  (hsp2)        72,064   smul_s8_s8
 2       2      conv2d_2 (Conv2D_PW)  (hsp2)       512,064   smul_s8_s8
 3       3      conv2d_3 (Conv2D_DW)  (hsp2)        72,064   smul_s8_s8
 4       4      conv2d_4 (Conv2D_PW)  (hsp2)       512,064   smul_s8_s8
 5       5      conv2d_5 (Conv2D_DW)  (hsp2)        72,064   smul_s8_s8
 6       6      conv2d_6 (Conv2D_PW)  (hsp2)       512,064   smul_s8_s8
 7       7      conv2d_7 (Conv2D_DW)  (hsp2)        72,064   smul_s8_s8
 8       8      conv2d_8 (Conv2D_PW)  (hsp2)       512,064   smul_s8_s8
 9       9      pool_9 (Pool_Avg)  (hsp1)            8,000   smul_s8_s8
 10      11     gemm_11 (Dense)                        780   smul_s8_s8
 11      12     nl_12 (Nonlinearity)                   180     op_s8_s8
 ------- ------ ------------------------------ ----------- ------------
 total                                           2,665,536

Comparison with the STM32Cube AI Studio features

The stedgeai application is the back end used by STM32Cube AI Studio. Compared with STM32Cube AI Studio, the command-line interface (CLI) does not provide several high-level features:

  • Complete IDE project generation: The CLI cannot create a complete IDE project containing the optimized inference runtime library, AI header files, and hardware-specific C files. It generates specialized neural-network (NN) C files and can update existing STM32CubeMX-based or proprietary IDE projects (see the update an IOC-based project section).
  • Memory-layout verification: The CLI reports system-level metrics such as ROM, RAM, and multiply-accumulate (MACC) operations through analyze, but it does not perform a detailed memory-fit check for a specific STM32 device. See the Evaluation report and metrics article for more information.
  • Built-in validation firmware generation: STM32Cube AI Studio provides the ready-to-use firmware project required for validation on target. The project can later be updated with the CLI (see the update an IOC-based project section). Host validation is fully supported by the CLI.
  • C-graph visualization: The CLI provides a textual, tabular representation of the generated C graph, including tensor and operator descriptions, through analyze. Graphical visualization and detailed RAM-usage insights are available in the STM32Cube AI Studio UI.

Generate command extension

Specific options

--hsp <integer>

When specified, this option enables optimization passes that use the Hardware Signal Processing (HSP) unit to accelerate supported kernels. The integer argument (default: 4096, the maximum value) specifies the amount of BRAM reserved for this purpose in 32-bit words. Therefore, the default value of 4096 corresponds to 16 KB.

--hsp-config <integer>

This option selects the HSP implementation for each supported layer type. The integer is interpreted as a hexadecimal value composed of six nibbles. From least significant to most significant, the nibbles map to:

Nibble (from least significant) Layer type
0 FullyConnected
1 Pointwise (PW)
2 Depthwise (DW)
3 Conv2D
4 AveragePool2D
5 MaxPool2D

Each nibble selects a mode independently:

Value FullyConnected AveragePool2D and MaxPool2D PW, DW, and Conv2D
0xF Automatic selection, as if the --hsp-config option had not been specified Automatic selection, as if the --hsp-config option had not been specified Automatic selection, as if the --hsp-config option had not been specified
0x0 STM32 fallback implementation STM32 fallback implementation STM32 fallback implementation
0x1 HSP0 HSP0 HSP1
0x2 HSP1 HSP1 HSP2
0x3 Not specified Not specified HSP3

The CLI expects a decimal integer argument. In Bash, use arithmetic expansion to convert a hexadecimal value to decimal before passing it to the CLI. For example, --hsp-config $((0xFFFFFF)) leaves all six layer types in automatic mode.

The value --hsp-config $((0xF21010)) sets FullyConnected to the STM32 fallback (0x0), PW to HSP1 (0x1), DW to the STM32 fallback (0x0), Conv2D to HSP1 (0x1), AveragePool2D to HSP1 (0x2), and MaxPool2D to automatic mode (0xF).

--dll

Optional flag that instructs the code generator to produce only a host shared library (DLL). This shared library is intended for use by the ai_runner module to perform advanced validation of the model on the host machine. - Optional

This feature is not supported for STM32 targets based on Arm® Cortex®-M processors with Arm® Helium™ technology, nor on STM32 devices that include AI accelerators such as the Hardware Signal Processing (HSP) unit and/or the Neural-ART.

--relocatable

Short syntax: -r/--reloc

Enables generation of a runtime-loadable model (also called a relocatable model). The model can then be loaded and relocated at runtime instead of being fixed at compile or link time. This option is optional.

The generation and management of the runtime-loadable model depend on the underlying runtime and hardware.

STM32 series Refer to the article for detailed guidance
SW only solution “STM32 Arm® Cortex® M - Relocatable binary (or runtime loadable) model support”
Hardware-assisted solution “Neural-ART - Runtime loadable model support”

--address/--copy-weights-at

Only supported with the Legacy API (see the –c-api option).

  • With the --binary flag, these helper options specify the address where the weights are located or/and the destination address where the weights will be copied during initialization. This is achieved using a specific generated '<name>_data.c' file (refer to the “Particular network data c-file” section).

  • With the --relocatable option, the --address argument instructs the code generator to produce an Intel Hexadecimal Object File Format from on the generated runtime loadable model based on the provided address.

This feature is not supported for STM32 targets that use the Neural-ART unit. Weight and parameter management is specific to Neural-ART (see the article “Neural-ART - How to deploy/manage the NPU memory initializers”).

--binary

This option is supported only with the Legacy API (see the –c-api option).

This optional flag instructs the code generator to produce a binary file named '<name>_data.bin' containing only the raw data of the weights and bias tensors. Metadata such as scale factors, zero points, and other parameters is always included in the <name>.c/.h files. The '<name>_data.c' and '<name>_data.h' files are generated regardless of the '--binary' flag (see the “Particular network data C file” section).

This feature is not supported for STM32 targets that use the Neural-ART unit. Weight and parameter management is specific to Neural-ART (see the article “Neural-ART - How to deploy/manage the NPU memory initializers”).

Example

  • Generate only the network NN C-file, weights/bias parameters are provided as a binary file/object.

    $ stedgeai generate -m <model_file_path>  --target stm32 -o <output-directory-path> -n <name> --binary
    ...
    Generated files (8)
    -----------------------------------------------------------
     <output-directory-path>\<name>_config.h
     <output-directory-path>\<name>.h
     <output-directory-path>\<name>.c
     <output-directory-path>\<name>_data.bin
     <output-directory-path>\<name>_data.h
     <output-directory-path>\<name>_data.c
     <output-directory-path>\<name>_data_params.h
     <output-directory-path>\<name>_data_params.c
    
    Creating report file <output-directory-path>\<name>_generate_report.txt
    ...
  • Generate a full relocatable binary file for a STM32H7 series (refer to “Relocatable binary model support” article).

    $ stedgeai generate -m <model_file_path> --target stm32h7 -o <output-directory-path> --relocatable
    ...
    Generated files (10)
    -----------------------------------------------------------
     <output-directory-path>\<name>_config.h
     <output-directory-path>\<name>.h
     <output-directory-path>\<name>.c
     <output-directory-path>\<name>_data.h
     <output-directory-path>\<name>_data.c
     <output-directory-path>\<name>_data_params.h
     <output-directory-path>\<name>_data_params.c
     <output-directory-path>\<name>_rel.bin
     <output-directory-path>\<name>_img_rel.c
     <output-directory-path>\<name>_img_rel.h
    
    Creating report file <output-directory-path>\network_generate_report.txt
    ...
  • Generate a relocatable binary file w/o the weights for a STM32F4 series. Weights/bias data are generated in a separated binary file (refer to “Relocatable binary model support” article)

    $ stedgeai generate -m <model_file_path> --target stm32h7 -o <output-directory-path> -n <name> --relocatable --binary
    ...
    Generated files (11)
    -----------------------------------------------------------
     <output-directory-path>\<name>_config.h
     <output-directory-path>\<name>.h
     <output-directory-path>\<name>.c
     <output-directory-path>\<name>_data.h
     <output-directory-path>\<name>_data.c
     <output-directory-path>\<name>_data_params.h
     <output-directory-path>\<name>_data_params.c
     <output-directory-path>\<name>_data.bin
     <output-directory-path>\<name>_rel.bin
     <output-directory-path>\<name>_img_rel.c
     <output-directory-path>\<name>_img_rel.h
    
    Creating report file <output-directory-path>\<name>_generate_report.txt
    ...

Particular network data c-file

The helper '--address' and '--copy-weights-at' options generate a specialized ai_network_data_weights_get() function. The returned address is passed to ai_<network>_init() through the ai_network_params structure (refer to [[API]][X_CUBE_AI_API]). The application can also manage this behavior, including the copy operation, directly.

If --binary or --relocatable is passed without '--address' or '--copy-weights-at', the following network_data.c file is generated:

#include "network_data.h"

ai_handle ai_network_data_weights_get(void)
{
  return AI_HANDLE_NULL;
}

Example of generated network_data.c file with the --binary and --address 0x810000 options.

#include "network_data.h"

#define AI_NETWORK_DATA_ADDR 0x810000

ai_handle ai_network_data_weights_get(void)
{
  return AI_HANDLE_PTR(AI_NETWORK_DATA_ADDR);
}

Example of generated network_data.c file with the --binary, --address 0x810000 and --copy-weights-at 0xD0000000 options.

#include <string.h>
#include "network_data.h"

#define AI_NETWORK_DATA_ADDR 0x81000
#define AI_NETWORK_DATA_DST_ADDR 0xD0000000

ai_handle ai_network_data_weights_get(void)
{
  memcpy((void *)AI_NETWORK_DATA_DST_ADDR, (const void *)AI_NETWORK_DATA_ADDR,
                                            AI_NETWORK_DATA_WEIGHTS_SIZE);
  return AI_HANDLE_PTR(AI_NETWORK_DATA_DST_ADDR);
}

Update an ioc-based project

For a STM32CubeMX project (ioc-based), the user has the possibility to update only the generated NN C-files. In this case, the '--output' option is used to indicate the root directory of the IDE project, that is, location of the '.ioc' file. The destination of the previous NN c-files is automatically discovered in the source tree else the output directory is used.

$ stedgeai generate -m <model_path> --target stm32 -n <name> -c low -o <root_project_folder>
...
IOC file found in the output directory
...
Generated files (5)
-----------------------------------------------------------
 <root_project_folder>\inc\<name>_details.h
 <root_project_folder>\inc\<name>.h
 <root_project_folder>\src\<name>.c
 <root_project_folder>\inc\<name>_data.h
 <root_project_folder>\src\<name>_data.c

Creating report file <root_project_folder>\<name>_generate_report.txt

or 

$ stedgeai generate -m <model_path> --target stm32 -n <name> --c-api legacy -o <root_project_folder>
...
IOC file found in the output directory
...
Generated files (7)
-----------------------------------------------------------
 <root_project_folder>\Inc\<name>_config.h
 <root_project_folder>\Inc\<name>.h
 <root_project_folder>\Src\<name>.c
 <root_project_folder>\Inc\<name>_data_params.h
 <root_project_folder>\Src\<name>_data_params.c
 <root_project_folder>\Inc\<name>_data.h
 <root_project_folder>\Src\<name>_data.c

Creating report file <root_project_folder>\<name>_generate_report.txt
...

Update a proprietary source tree

The '--output' option is used to indicate the single destination of the generated NN C-files. Note that an empty file with the '.ioc' extension can be defined in the root directory of the custom source tree to use the discovery mechanism as for the update of an ioc-based project.