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
--hspoption enables thestedgeaicommand-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,536Comparison 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).
--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
--addressargument 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.