pw_stm32cube_build#

Pigweed AI summary: The pw_stm32cube_build module provides utilities for building a target with the stm32cube HAL and/or the stm32cube initialization code. The GN build files and headers are located in third_party/stm32cube, and the stm32cube directory setup requires specific directory/file names. The GN build arguments are defined in stm32cube.gni, and the stm32cube_builder utility contains backend scripts used by pw_package/stm32cube and the GN build scripts. The utility includes gen_file

The pw_stm32cube_build module provides helper utilities for building a target with the stm32cube HAL and/or the stm32cube initialization code.

The actual GN build files and headers live in third_party/stm32cube but are documented here. The rationale for keeping the build files in third_party is that code depending on stm32cube can clearly see that their dependency is on third party, not pigweed code.

STM32Cube directory setup#

Pigweed AI summary: The STM32Cube libraries are specific to each product family and rely on ST's MCU Components instead of the MCU Package. The required directories and files for each product family include hal_driver, cmsis_device, cmsis_core, and files.txt. These can be set up manually or using pw_package, which automatically downloads compatible repos and generates files.txt.

Each stm32 product family (ex. F4, L5, etc.) has its own stm32cube libraries. This integration depends on ST’s 3 core MCU Components instead of their monolithic MCU Package. The components are the hal_driver, cmsis_core, and cmsis_device. All of these repos exist on ST’s GitHub page. Compatible version tags are specified on the README.md of each MCU component. Within a single directory, the following directory/file names are required.

Dir/File Name

Description

hal_driver/

checkout of stm32{family}xx_hal_driver

cmsis_device/

checkout of cmsis_device_{family}

cmsis_core/

checkout of cmsis_core

files.txt

list of files generated by gen_file_list

pw_package#

Pigweed AI summary: The pw_package can be used to set up the stm32cube directory, which will download compatible repositories and generate the files.txt automatically. To do this, use the command "pw package install stm32cube_{family}" in the bash language.

The stm32cube directory can alternatively be setup using pw_package. This will automatically download compatible repos into the expected folders and generate the files.txt.

pw package install stm32cube_{family}

GN build#

Pigweed AI summary: This document provides information on the GN build for integrating stm32cube into a project. The primary source set is $dir_pw_third_party/stm32cube:stm32cube, which includes the HAL, init code, and templates. The stm32cube GN build arguments are defined in $dir_pw_third_party/stm32cube/stm32cube.gni, and include options for pointing to the stm32cube directory for each family, specifying the product, and setting the source sets for various components

The primary pw_source_set for this integration is $dir_pw_third_party/stm32cube:stm32cube. This source set includes all of the HAL, init code, and templates, depending on value of the GN args.

Headers#

Pigweed AI summary: The directory $dir_pw_third_party/stm32cube:stm32cube contains primary headers that external targets or applications would care about. The stm32cube/stm32cube.h header is a convenience define that includes the primary HAL header, which includes the entire HAL and all product-specific defines. This common header allows for stm32 family agnostic modules. The stm32cube/init.h header contains the pw_stm32cube_Init() function declaration, which should be included and implemented by target init code

$dir_pw_third_party/stm32cube:stm32cube contains the following primary headers that external targets / applications would care about.

{family}.h#

Pigweed AI summary: The {family}.h section contains the primary HAL header provided by stm32cube, which includes the entire HAL and all product specific defines. Examples of this include stm32f4xx.h and stm32l5xx.h.

ex. stm32f4xx.h, stm32l5xx.h

This is the primary HAL header provided by stm32cube. It includes the entire HAL and all product specific defines.

stm32cube/stm32cube.h#

Pigweed AI summary: The stm32cube/stm32cube.h integration provides a convenience define that includes {family}.h. This is useful because there is a lot of commonality between the HAL's of different stm32 families, allowing for stm32 family agnostic modules.

This is a convenience define provided by this integration. It simply includes {family}.h.

This is useful because there is a lot of commonality between the HAL’s of the different stm32 families. Although the API’s are not guaranteed to be compatible, many basic API’s often are (ex. GPIO, UART, etc.). This common header allows for stm32 family agnostic modules (ex. pw_sys_io_stm32, which could work with most, if not all families).

stm32cube/init.h#

Pigweed AI summary: The stm32cube/init.h file contains the pw_stm32cube_Init() function declaration, which is injected into ST's startup scripts if the built-in init functionality is used. This function should be included and implemented by target init code.

As described in the inject_init section, if you decide to use the built in init functionality, a pre main init function call, pw_stm32cube_Init(), is injected into ST’s startup scripts.

This header contains the pw_stm32cube_Init() function declaration. It should be included and implemented by target init code.

GN args#

Pigweed AI summary: This paragraph explains the GN build arguments for stm32cube, which are defined in a specific file. It also provides optional arguments for convenience when building for multiple families in the same project. The paragraph explains how to set the directory for the current build and for multi-target projects. It also lists several other arguments, including the product, config, timebase, cmsis init, and core init. The default values for these arguments are provided, but they can be customized if needed.

The stm32cube GN build arguments are defined in $dir_pw_third_party/stm32cube/stm32cube.gni.

dir_pw_third_party_stm32cube_xx#

Pigweed AI summary: The "dir_pw_third_party_stm32cube_xx" section provides instructions on how to set the stm32cube directory for each family that needs to be built for. These settings are optional but can be useful for projects that require building for multiple families.

These should be set to point to the stm32cube directory for each family that you need to build for. These are optional to set and are only provided for convenience if you need to build for multiple families in the same project.

dir_pw_third_party_stm32cube#

Pigweed AI summary: The paragraph discusses the need to point to the stm32cube directory for the current build and suggests setting this for each target in multi target projects using a standard practice. It provides an example of how to set the directory for each target.

This needs to point to the stm32cube directory for the current build.

For multi target projects, the standard practice to set this for each target:

dir_pw_third_party_stm32cube = dir_pw_third_party_stm32cube_f4

pw_third_party_stm32cube_PRODUCT#

Pigweed AI summary: This section provides information about a third-party product called "pw_third_party_stm32cube_PRODUCT," which is specified in detail, such as "stm32f429zit," "stm32l552ze," or "stm32f207zg."

The product specified in as much detail as possible. ex. stm32f429zit, stm32l552ze, stm32f207zg, etc.

pw_third_party_stm32cube_CONFIG#

Pigweed AI summary: This paragraph describes the pw_source_set that provides the stm32{family}xx_hal_conf.h file, with the default using the stm32{family}xx_hal_conf_template.h file within the tree.

The pw_source_set that provides stm32{family}xx_hal_conf.h. The default uses the in-tree stm32{family}xx_hal_conf_template.h.

pw_third_party_stm32cube_TIMEBASE#

Pigweed AI summary: This paragraph describes the pw_source_set that contains the timebase, which defaults to using the in-tree stm32xx_hal_timebase_tim_template.c.

The pw_source_set containing the timebase. The default uses the in-tree stm32{family}xx_hal_timebase_tim_template.c.

pw_third_party_stm32cube_CMSIS_INIT#

Pigweed AI summary: This paragraph describes the pw_source_set that contains the cmsis init logic, with the default using the in-tree system_stm32{family}xx.c.

The pw_source_set containing the cmsis init logic. The default uses the in-tree system_stm32{family}xx.c.

pw_third_party_stm32cube_CORE_INIT#

Pigweed AI summary: This paragraph describes the contents of a pw_source_set that contains core initialization logic for STM32Cube. It includes a startup file and a linker script, with a default template that matches the product. If the template is not used, custom linker and startup logic must be provided elsewhere in the build.

pw_source_set containing the core initialization logic. This normally includes a startup_stm32{...}.s + a dependent pw_linker_script. The default core_init_template uses the upstream startup and linker script matching pw_third_party_stm32cube_PRODUCT. If set to “”, you must provide your own linker/startup logic somewhere else in the build.

stm32cube_builder#

Pigweed AI summary: The stm32cube_builder utility contains backend scripts used by pw_package/stm32cube and the GN build scripts in third_party/stm32cube to interact with the stm32cube repos. It is only necessary to interact with stm32cube_builder directly for custom tasks such as using git submodules instead of pw_package, forking the stm32cube libraries, interfacing with a different build system, or using a custom init. The utility includes commands to generate a list of relevant files for a particular

stm32cube_builder is utility that contains the backend scripts used by pw_package/stm32cube and the GN build scripts in third_party/stm32cube to interact with the stm32cube repos. You should only need to interact with stm32cube_builder directly if you are doing something custom, like using git submodules instead of pw_package, forking the stm32cube libraries, interfacing with a different build system, or using your own init.

gen_file_list#

Pigweed AI summary: The article discusses the limitations of build systems like GN, which cannot depend on arbitrary directories and must have dependencies on specific files. To address this issue, a workaround called "files.txt" was created, which is a basic list of all the files in the stm32cube directory with relevant file extensions. The build system only directly depends on this list, which must be updated every time the underlying repos are updated. The article also provides a command to generate "files.txt" for correctly structured stm32cube

Build systems like GN are unable to depend on arbitrary directories. Instead, they must have dependencies on specific files. The HAL for each stm32 product family has different filenames, so files.txt was created as a workaround. files.txt is a basic list of all the files in the stm32cube directory with relavent file extensions. The build system only directly depends on this list, which must be updated everytime the underlying repos are updated.

This command will generate files.txt for correctly structured stm32cube directories.

stm32cube_builder gen_file_list /path/to/stm32cube_dir

find_files#

Pigweed AI summary: The "find_files" tool searches for specific files within a stm32cube directory for a particular product. The product string should be specified in detail as there may be different defines or init code for submembers of products. The tool only looks for init files if the "--init" flag is provided. The output is currently only provided in the GN 'scope' format to stdout and includes variables such as family, product_define, sources, headers, and include_dirs. The tool can be used by running

Within each stm32 family, there are specific products. Although most of the HAL is common between products, the init code is almost always different. find_files looks for all of the files relevant to a particular product within a stm32cube directory.

The product string should be specified in as much detail as possible because there are sometimes different defines or init code for submembers of products.

Ex. stm32f412cx, stm32f412rx, stm32f412vx, and stm32f412zx all have different init logic, while all stm32f439xx have the same init.

find_files only ever looks for init (linker + startup scripts) if the --init flag is provided.

The output is currently only provided in the GN ‘scope’ format to stdout. The following variables are output: family, product_define, sources, headers, include_dirs, and the following three if --init is specified: startup, gcc_linker, iar_linker.

stm32cube_builder find_files /path/to/stm32cube_dir stm32{family}{product} [--init]

inject_init#

Pigweed AI summary: The "inject_init" command adds a call to "pw_stm32cube_Init()" before the "main()" function in ST assembly files. This is necessary for Pigweed unit tests, which require initialization of "sys_io" before "main()" is called. The command takes in an ST assembly script and outputs the modified script to stdout or a specified path.

ST provides init assembly files for every product in cmsis_device. This is helpful for getting up and running quickly, but they directly call into main() before initializing the hardware / peripherals. This is because they expect to do that initialization in main(), then call into the user application. Upstream Pigweed unit tests expect at least sys_io to be initialized before main() is called.

This command injects a call to pw_stm32cube_Init() immediately before the call to main(). This function should be implemented by the target to do whatever init is necessary (hal init, sys_io init, clock configuration, etc.)

inject_init takes in an ST assembly script and outputs the same script with the pre main init call. The output is printed to stdout, or to the specified --out-startup-path.

stm32cube_builder inject_init /path/to/startup.s [--out-startup-path /path/to/new_startup.s]

icf_to_ld#

Pigweed AI summary: This section describes a script that converts ST's IAR linker script format to a basic GCC linker script format for Cortex-M builds. The converter only works with ST's current .icf file format and outputs .ld files with only RAM and FLASH sections. More complex scripts will require manual customization. The script can be run with a specified --ld-path or printed to stdout. Links to ST's GitHub page and STM32Cube MCU components are also provided.

Pigweed primarily uses GCC for its Cortex-M builds. However, ST only provides IAR linker scripts in cmsis_device for most product families. This script converts from ST’s IAR linker script format (.icf) to a basic GCC linker script (.ld). This is a very basic converter that only works with exactly how ST currently formats their .icf files.

The output .ld files only contain RAM and FLASH sections. Anything more complicated will require hand customized .ld scripts. Output is printed to stdout or the specified --ld-path.

stm32cube_builder inject_init /path/to/iar_linker.icf [--ld-path /path/to/gcc_linker.ld]