2.2.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 2.2.0



r1.0

Overview

The article describes the specificities of the command line for the STM32 target.

ST Community channel/forum for “STM32 MCUs”

Comparison with the X-CUBE-AI UI plug-in features

The stedgeai application is used as back-end by the X-CUBE-AI UI plug-in (refer to [UM]).

CLI as back-end

In comparison with the X-CUBE-AI UI plug-in, the following high-level features are not supported:

  • Extra C-code wrapper to manage multiple models. CLI manages only one model at the time.
  • Creation of a whole IDE project including the optimized inference runtime library, AI headers files and the C-files related to the hardware settings. CLI can only be used to generate the specialized NN C-files. However, it allows to update an initial IDE project, STM32CubeMX-based or proprietary source tree (see “Update an ioc-based project” section).
  • The check to know if a model fits in term of memory layout in a selected STM32 memory device. CLI reports (see ‘analyze’ command) only the main system level dimensioning metrics: ROM, RAM, MACC.. (Refer to [METRIC] for details)
  • For the “Validation process on target”, as a full STM32 project is expected, it must be generated previously through the UI. Note that this project can be updated later (see “Update an ioc-based project” section). “Validation process on desktop” is fully supported through the CLI without restriction.
  • Graphic visualization of the generated c-graph (including the usage of the RAM). CLI provides only a textual representation (table form) of the c-graph including a description of the tensors/operators (see ‘analyze’ command).

Supported STM32 series

The STM32 family of 32-bit microcontrollers is based on the Arm Cortex®-M processor.

supported series description
stm32f4/stm32g4/stm32f3/stm32wb all STM32F4xx/STM32G4xx/STM32F3xx/STM32WBxx devices with an Arm® Cortex® M4 core and FPU support enabled (simple precision).
stm32l4/stm32l4+ all STM32L4xx/STM32L4Rxx devices with an Arm® Cortex® M4 core and FPU support enabled (simple precision).
stm32n6 all STM32N6xx devices with an Arm® Cortex® M55 core including or not the Neural-ART accelarator™.
stm32l5/stm32u5/stm32h5/stm32u3 all STM32L5xx/STM32U5xx/STM32H5xx/STM32U3xx devices with a Arm® Cortex® M33 core and FPU support enabled (simple precision).
stm32f7 all STM32F7xx devices with a Arm® Cortex® M7 core and FPU support enabled (simple precision).
stm32h7 all STM32H7xx devices with a Arm® Cortex® M7 core and FPU support enabled (double precision).
stm32l0/stm32g0/stm32c0 all STM32L0xx//STM32G0xx/STM32C0xx devices with an Arm® Cortex® M0+ core, w/o FPU support and w/o DSP extension.
stm32f0 all STM32F0xx device with an Arm® Cortex® M0+ core, w/o FPU support and w/o DSP extension.
stm32wl all STM32WLxx device with an Arm® Cortex® M4 core, w/o FPU support and with DSP extension.

Warning

Be aware that all provided inference runtime libraries for the different STM32 series (excluding STM32WL series) are compiled with the FPU enabled and the hard float EABI option for performance reasons.

STM32N6xx considerations

  • For an STM32N6 device without the ST Neural-ART NPU is supported similarly to the classical STM32xx series. The optimized AI network runtime library is implemented to use the M-Profile Vector Extension (MVE). Consequently, the generated C-file cannot be executed on the host machine, and the “Validation on host” feature is not supported.

  • A specific ST Neural-ART Compiler generates the specialized C-files for an STM32N6 device with the ST Neural-ART NPU. No simulator or emulator is provided, so the “Validation on host” feature is not supported.

Generate command extension

Specific options

--dll

If defined, this option generates only a HOST shared library, which the ai_runner module can use for advanced validation purposes - Optional

--binary

If defined, this flag forces the generation of a binary file '<name>_data.bin'. The '<name>_data.c' and '<name>_data.h' files are always generated (see “Particular network data c-file” section). Note that this binary file contains ONLY the data of the different weights/bias tensors, C-implementation of the topology (including the metadata, scale/zero-point…) is always generated in the <name>.c/.h files. - Optional

--address

With --binary flag, this helper option can be used to indicate the address where the weights are located to generate a particular generated '<name>_data.c' file. - Optional

--copy-weights-at

With --binary flag and --address option, this helper option can be used to indicate the destination address where the weights should be copied at initialization time thanks to a particular generated '<name>_data.c' file. - Optional

Specific arguments to generate a relocatable binary model (refer to “Relocatable binary model support” article for details).

-r/--relocatable

If defined this option allows to generate a relocatable binary model. The '--binary' option can be used to have a separate binary file with only the data of the weight/bias tensors. - Optional

--lib

Indicates the root directory to find the relocatable network runtime libraries. Typical value: '$INSTALL_STEDGE_AI_DIR/Middlewares/ST/AI'. - Optional

--ihex

With --relocatable/--address options, if defined, an additional file (Intel hexadecimal object file format) is generated. --address option is used to define the base address. - Optional

Warning

the --split-weights and --copy-weights-at features are not supported with the --relocatable option.

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 are the convenience options to generate a specific ai_network_data_weights_get() function. The returned address is passed to the ai_<network>_init() function thanks the ai_network_params structure (refer to [[API]][X_CUBE_AI_API]). Note that this (including the copy function) can be fully managed by the application code itself.

If the --binary (or --relocatable) option is passed without the '--address' or '--copy-weights-at' arguments, 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 X-CUBE-AI IDE 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 (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

or

$ stedgeai generate -m <model_path> --target stm32  --c-api st-ai -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
...

For multiple networks support, the update mechanism for a particular model is the same. Users should be vigilant to use the correct name ('--name my_name') to avoid overwrite/updating an incorrect file and to be aligned with the multinetwork helpers functions which are only generated by the X-CUBE-AI UI: 'app_x-cube-ai.c/.h' files. If the number of networks is changed, X-CUBE-AI UI should be used to update the generated c-models.

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.