STM32CubeMX
Appendix B STM32CubeMX C code generation design choices and limitations ¶
A.9 GPIO signals mapping ¶
I/O signals (GPIO_Input, GPIO_Output, GPIO_Analog) can be assigned to pins either manually through the Pinout view or automatically through the Pinout menu. Such pins can no longer be assigned automatically to another signal: STM32CubeMX signal automatic placement does not take into account this pin anymore since it does not shift I/O signals to other pins.
The pin can still be manually assigned to another signal or to a reset state.
Appendix B STM32CubeMX C code generation design
choices and limitations ¶
B.1 STM32CubeMX generated C code and user sections ¶
The C code generated by STM32CubeMX provides user sections as illustrated below. They allow user C code to be inserted and preserved at next C code generation.
User sections shall neither be moved nor renamed. Only the user sections defined by STM32CubeMX are preserved. User created sections will be ignored and lost at next C code generation.
/* USER CODE BEGIN 0 */
(..)
/* USER CODE END 0 */
Note: STM32CubeMX may generate C code in some user sections. It will be up to the user to clean the parts that may become obsolete in this section. For example, the while(1) loop in the main function is placed inside a user section as illustrated below:
/* Infinite loop */
/* USER CODE BEGIN WHILE */ while (1)
{
/* USER CODE END WHILE */
/* USER CODE BEGIN 3 */
}
/* USER CODE END 3 */
B.2 STM32CubeMX design choices for peripheral initialization ¶
STM32CubeMX generates peripheral _Init functions that can be easily identified thanks to the MX_ prefix:
static void MX_GPIO_Init(void); static void MX_<Peripheral Instance Name>_Init(void); static void MX_I2S2_Init(void);
An MX_<peripheral instance name>_Ini t function exists for each peripheral instance selected by the user (e.g, MX_I2S2_Init). It performs the initialization of the relevant handle structure (e.g, &hi2s2 for I2S second instance) that is required for HAL driver initialization (e.g., HAL_I2S_Init) and the actual call to this function:
void MX_I2S2_Init(void)
{ hi2s2.Instance = SPI2; hi2s2.Init.Mode = I2S_MODE_MASTER_TX; hi2s2.Init.Standard = I2S_STANDARD_PHILLIPS; hi2s2.Init.DataFormat = I2S_DATAFORMAT_16B; hi2s2.Init.MCLKOutput = I2S_MCLKOUTPUT_DISABLE; hi2s2.Init.AudioFreq = I2S_AUDIOFREQ_192K; hi2s2.Init.CPOL = I2S_CPOL_LOW; hi2s2.Init.ClockSource = I2S_CLOCK_PLL; hi2s2.Init.FullDuplexMode = I2S_FULLDUPLEXMODE_ENABLE;
HAL_I2S_Init(&hi2s2);
}
By default, the peripheral initialization is done in main.c. If the peripheral is used by a middleware mode, the peripheral initialization can be done in the middleware corresponding
.c file.
Customized HAL_<Peripheral Name>_MspInit() functions are created in the stm32f4xx_hal_msp.c file to configure the low-level hardware (GPIO, CLOCK) for the selected peripherals.
B.3 STM32CubeMX design choices and limitations for
middleware initialization ¶
STM32CubeMX does not support C user code insertion in Middleware stack native files although stacks such as LwIP might require it in some use cases.
STM32CubeMX generates middleware Init functions that can be easily identified thanks to the MX_ prefix:
MX_LWIP_Init(); // defined in lwip.h file
MX_USB_HOST_Init(); // defined in usb_host.h file
MX_FATFS_Init(); // defined in fatfs.h file
Note however the following exceptions:
No Init function is generated for FreeRTOS unless the user chooses, from the Project Settings window, to generate Init functions as pairs of .c/.h files. Instead, a
StartDefaultTask function is defined in the main.c file and CMSIS-RTOS native function ( osKernelStart) is called in the main function.
If FreeRTOS is enabled, the Init functions for the other middlewares in use are called from the StartDefaultTask function in the main.c file.
Example:
void StartDefaultTask(void const * argument)
{
/* init code for FATFS */
MX_FATFS_Init();
/* init code for LWIP */
MX_LWIP_Init();
/* init code for USB_HOST */
MX_USB_HOST_Init();
/* USER CODE BEGIN 5 */ /* Infinite loop */ for(;;)
{
osDelay(1);
}
/* USER CODE END 5 */
}
USB peripheral initialization is performed within the middleware initialization C code in the usbh_conf.c file, while USB stack initialization is done within the usb_host.c file.
When using the USB Host middleware, the user is responsible for implementing the USBH_UserProcess callback function in the generated usb_host.c file.
From STM32CubeMX user interface, the user can select to register one class or all classes if the application requires switching dynamically between classes.
USB peripheral initialization is performed within the middleware initialization C code in the usbd_conf.c file, while USB stack initialization is done within the usb_device. c file.
USB VID, PID and String standard descriptors are configured via STM32CubeMX user interface and available in the usbd_desc.c generated file. Other standard descriptors (configuration, interface) are hard-coded in the same file preventing support of USB composite devices.
When using the USB Device middleware, the user is responsible for implementing the functions in the usbd_<classname>_if.c class interface file for all device classes (such as usbd_storage_if.c).
USB MTP and CCID classes are not supported.
FatFs is a generic FAT/exFAT file system solution well suited for small embedded systems.
FatFs configuration is available in ffconf.h generated file.
The initialization of the SDIO peripheral for the FatFs SD card mode and of the FMC peripheral for the FatFs External SDRAM and External SRAM modes are kept in the main.c file.
Some files need to be modified by the user to match user board specificities (BSP in STM32Cube embedded software package can be used as example):
bsp_driver_sd.c/.h generated files when using FatFs SD card mode
bsp_driver_sram.c/.h generated files when using FatFs External SRAM mode
bsp_driver_sdram.c/.h generated files when using FatFs External SDRAM mode.
Multi-drive FatFs is supported, which means that multiple logical drives can be used by the application (External SDRAM, External SRAM, SD card, USB disk, User defined). However support of multiple instances of a given logical drive is not available (e.g. FatFs using two instances of USB hosts or several RAM disks).
NOR and NAND flash memory are not supported. In this case, the user shall select the FatFs user-defined mode and update the user_diskio.c driver file generated to implement the interface between the middleware and the selected peripheral.
FreeRTOS is a free real-time embedded operating system well suited for microcontrollers.
FreeRTOS configuration is available in FreeRTOSConfig.h generated file.
When FreeRTOS is enabled, all other selected middleware modes (e.g., LwIP, FatFs, USB) will be initialized within the same FreeRTOS thread in the main.c file.
When GENERATE_RUN_TIME_STATS, CHECK_FOR_STACK_OVERFLOW, USE_IDLE_HOOK, USE_TICK_HOOK and USE_MALLOC_FAILED_HOOK parameters
are activated, STM32CubeMX generates freertos.c file with empty functions that the user shall implement. This is highlighted by the tooltip (see Figure 739).
Figure 739. FreeRTOS HOOK functions to be completed by user
LwIP is a small independent implementation of the TCP/IP protocol suite: its reduced RAM usage makes it suitable for use in embedded systems with tens of Kbytes of free RAM.
LwIP initialization function is defined in lwip.c, while LwIP configuration is available in lwipopts.h generated file.
STM32CubeMX supports LwIP over Ethernet only. The Ethernet peripheral initialization is done within the middleware initialization C code.
STM32CubeMX does not support user C code insertion in stack native files. However, some LwIP use cases require modifying stack native files (e.g., cc.h, mib2.c): user modifications shall be backed up since they will be lost at next STM32CubeMX generation.
Starting with LwIP release 1.5, STM32CubeMX LwIP supports IPv6 (see Figure 741).
DHCP must be disabled, to configure a static IP address.
Figure 740. LwIP 1.4.1 configuration
MEM_USE_POOLS: user C code to be added either in lwipopts.h or in cc.h (stack file).
PPP_SUPPORT, PPPOE_SUPPORT: user C code required
MEMP_SEPARATE_POOLS with MEMP_OVERFLOW_CHECK > 0: a stack patch required
MEM_LIBC_MALLOC & RTOS enabled: stack patch required
LWIP_EVENT_API: stack patch required
In STM32CubeMX, the user must enable FreeRTOS in order to use LwIP with the netconn and sockets APIs. These APIs require the use of threads and consequently of an operating system. Without FreeRTOS, only the LwIP event-driven raw API can be used.
Libjpeg is a widely used C-library that allows reading and writing JPEG files. It is delivered within STM32CubeF7, STM32CubeH7, STM32CubeF2 and STM32CubeF4 embedded software packages.
STM32CubeMX generates the following files, whose content can be configured by the user through STM32CubeMX user interface:
libjpeg.c/.h
The MX_LIBJPEG_Init() initialization function is generated within the libjpeg.c file. It is empty. It is up to the user to enter in the user sections the code and the calls to the libjpeg functions required for the application.
jdata_conf.c
This file is generated only when FatFs is selected as data stream management type.
jdata_conf.h
The content of this file is adjusted according to the datastream management type selected.
jconfig.h
This file is generated by STM32CubeMX. but cannot be configured.
jmorecfg.h
Some but not all the define statements contained in this file can be modified through the STM32CubeMX libjpeg configuration menu.
Figure 742. Libjpeg configuration window
mbedtls_config.h
mbedtls.h
net_sockets.c (generated only if LwIP is enabled)
mbedtls.c
touchsensing.c/.h
tsl_user.c/.h
tsl_conf.h
pdm2pcm.h/.c
STM32WPAN BLE and Thread middleware are now supported in STM32CubeMX.
Note: The BLE Transparent mode and all Thread applications require either the USART or the LPUART peripheral to be configured as well.
To enable Thread some peripherals (RTC, HSEM, RF) must be activated first.
Then, an application type must be selected and the relevant parameters configured.
Figure 754. Thread application selection
The restriction about applications comes from a simple generated code consideration: an application is meant to be the root of the execution (excluding the main function).
This means that the generated function defines the execution of the selected application. In that sense, it is meant to be the last call of the main method, and must not give hand back to the main function.Two applications cannot be called, as this means generating calls in the main function, and then the second call is never reached.
If you need to call both applications:
An RTOS must run them in threads, or
You manually add the right code to execute them (in that context, they are not applications, as they are not at the root of the execution), or
Change the meaning of the application components.
B.3.13 OpenAmp and RESMGR_UTILITY
New software and hardware have been introduced on dual-core products to enable multi-core cooperation.
For STM32MPUs only: the inter-processor communication controller (IPCC) used to exchange data between two processor instances relies on the fact that shared memory buffers are allocated in the MCU SRAM and that each processor owns specific register bank and interrupts.
For STM32MPUs only: the OpenAMP middleware for intercommunication between Cortex-A and Cortex-M cores implements the RPMsg messaging protocol (see Figure 755). • The resource manager library (RESMGR_UTILITY) for system resource management:
multi-processor devices give the possibility to run independent firmware on several cores (see Figure 756). This implies a core could use some peripherals without knowledge of the usage of these same peripherals: the role of the resource management library is to control the assignment of a peripheral to a dedicated core and to provide a method to configure the system resources used to operate that peripheral (see Figure 757).
