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]).

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.

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.

Specific options

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.