build-operation.md

Build Operation

CMSIS-Toolbox > Build Operation

This chapter explains the overall build process that of the CMSIS-Toolbox and how to add a new compiler toolchain.

Chapter Contents:

• Build Operation
  • Build Process Overview
    • cbuild Build Invocation
    • cbuild Setup Command
    • csolution Project Manager
  • Add Toolchain to CMSIS-Toolbox
    • Steps
    • CMake Variables
      • BRANCHPROT Values
  • Generator Integration
    • Generator Start via component
    • Global Generator Registry File

Build Process Overview

The section below describes the overall process to add a new compiler toolchain to the CMSIS-Toolbox.

cbuild Build Invocation

The cbuild Build Invocation utility controls the overall build process.

• Calls the csolution Project Manager (with option --no-update-rte) to process csolution project files.
• When option --packs is used, it downloads missing software packs using the cpackget Pack Manager.
• Calls cbuildgen with *.cprj files to generate CMakeList.txt files that include a compiler_name.<version>.cmake file for toolchain specific configuration.
  • With the experimental option --cbuild2cmake the `cbuild2cmake converter is called instead that uses the build information files instead of the *.cprj files.
• These CMakeList.txt files are then processed by the CMake tool to generate the build.ninja file with the actual build commands.
• This build.ninja file is then used by the Ninja tool to generate the binary image or a library file with the selected toolchain.

The picture below outlines these operations.

Note:

By default, the cbuild invocation does not update the RTE Directory. Use the option --update-rte if this is required.

cbuild Setup Command

The cbuild setup command prepares the data for an IDE environment. This command is called at start of an IDE or whenever one csolution project file is modified. The typical invocation is:

cbuild setup <name>.csolution.yml --packs --context-set --update-rte

This command checks for correctness of the csolution project files and creates the file compile_commands.json in the output directory of the related context. The operation is further controlled by options:

• The option --packs downloads missing software packs.
• The option --context-set restricts the operation to the context-set selected by the file *.cbuild-set.yml. If this file is missing a file *.cbuild-set.yml with selection of the first target-type and the first build-type for each project is created.
• The option --update-rte updates the configuration files of the application.

Note:

The file compile_commands.json is generated by CMake with the option --target database and contains all source files of the context along with compiler options. It is intended for the IntelliSense system of an IDE.

csolution Project Manager

The csolution Project Manager processes csolution project files (in YAML format) and the *.pdsc metadata files of software packs and performs the following operations:

• Generate build information in the Project Area with the following files: *.cbuild-idx.yml, *.cbuild.yml, and *.cprj files for the cbuild tool.
• Generate header files in the RTE Directory for each context with the following files: RTE_components.h and pre-include files from the *.pdsc metadata.
• Copy the configuration files from selected software components to the RTE Directory.

The picture below outlines these operations.

Add Toolchain to CMSIS-Toolbox

The following section explains how to add a compiler toolchain to the CMSIS-Toolbox.

Steps

The section below describes the steps to add a new compiler toolchain to the CMSIS-Toolbox.

1. Define a compiler_name for the new compiler toolchain, i.e. CLang.
2. Add this compiler_name to the "CompilerType": in the schema file ./tools/projmgr/schemas/common.schema.json.
3. Create a new CMake file in ./tools/buildmgr/cbuildgen/config with the naming convention compiler_name.<version>.cmake.
4. Map with the file compiler_name.<version>.cmake. the CMake input variables to the CMake toolchain variables.
   • Use an existing *.cmake file, i.e. GCC.<version>.cmake as reference.

CMake Variables

The CMakeLists.txt file sets the following CMake input variables that should be processed by compiler_name.<version>.cmake.

CMake Variable	Possible Values	Description
BYTE_ORDER	Little-endian, Big-endian	Endian processor configuration
CPU	DCoreEnum	Processor core selection
FPU	DfpuEnum	Floating point unit support
DSP	DdspEnum	DSP instruction set support
TZ	DtzEnum	TrustZone support
SECURE	DsecureEnum	Software model selection
MVE	DmveEnum	MVE instruction set support
BRANCHPROT	BRANCHPROT values	[Branch protection
OPTIMIZE	Optimize values	Generic optimize levels for code generation
WARNINGS	Warnings values	Control warning level for compiler diagnostic
DEBUG	Debug values	Control the generation of debug information
DEFINES	Define symbols	List of symbol #define statements

BRANCHPROT Values

The following table lists the possible values for the CMake variable BRANCHPROT.

Values	Description
NO_BRANCHPROT	Branch protection not used
BTI	Using BTI (Branch Target ID)
BTI_SIGNRET	Using BTI + Sign Return

The compiler_name.<version>.cmake sets the following CMake variables to specify the toolchain and select toolchain options.

CMake Variable	Description
ASM_CPU, CC_CPU, CXX_CPU	Device selection set according to the combination of device attributes (CPU, FPU, DSP, MVE, etc.)
AS_LEG_CPU, AS_ARM_CPU, AS_GNU_CPU	Similar to the previous item but for assembly dialect variants (if applicable)
ASM_FLAGS, CC_FLAGS, CXX_FLAGS, LD_FLAGS	Flags applicable to all modules of the given language
CC_SECURE, LD_SECURE	Flags applicable only for secure projects
_PI	Pre-include option
_ISYS	system include option
LIB_PREFIX	Generated library name prefix
LIB_SUFFIX	Generated library name suffix
EXE_SUFFIX	Generated executable name suffix
ELF2HEX	Flags for ELF to HEX conversion
ELF2BIN	Flags for ELF to BIN conversion
CMAKE_C_COMPILER_ID	CMake compiler identifier
CMAKE_C_COMPILER_VERSION	CMake compiler version

Generator Integration

The diagram below shows how a generator is integrated into the CMSIS build process. The data flow is exemplified on STM32CubeMX (Generator ID for this example is CubeMX). The information about the project is delivered to the generator using the Generator Information files (<csolution-name>.cbuild-gen-idx.yml and <context>.cbuild-gen.yml). This information provides CubeMX with the project context, such as selected board or device, and CPU mode such as TrustZone disabled/enabled.

The utility cbridge gets as parameter the <csolution-name>.cbuild-gen-idx.yml and calls the generator. For the CubeMX generator example these files are created:

• *.ioc CubeMX project file with current project settings
• *.c/.h source files, i.e. for interfacing with drivers
• <project-name>.cgen.yml (created by cbridge) provides the data for project import into the csolution build process.

Note: CubeMX itself does not have the required interfaces to the csolution project format. The utility cbridge converts the build information files into command-line options for CubeMX. cbridge also generates the <project-name>.cgen.yml based on the information generated by CubeMX.

Generator Start via component

A <component> element with a generator attribute in a *.PDSC file is used to start the generator. Typically this component is provided in a Device Family Pack (DFP) or a Board Support Pack (BSP).

Example component for CubeMX in DFP:

  <component generator="CubeMX" Cclass="Device" Cgroup="CubeMX" Cversion="0.9.0">
      <description>Configure device or board with STM32CubeMX</description>
  </component>

Note:

No <generator> element in the *.PDSC file is required when the Global Generator Registry File is used. The generator="id" attribute of the <component> element in the *.PDSC file is the reference to the - id: list node in the global.generator.yml file.

Global Generator Registry File

For generators that have no <generator> element in the *.PDSC file, the global.generator.yml in the CMSIS-Toolbox ./etc directory contains is used. The generator: node in this YAML file registers the supported generators with the following keys:

generator:		Content
- id:	Required	<generator-id> referred in the *.PDSC file
download-url:	Optional	URL for downloading the generator
run:	Required	Name and location of the utility that starts the generator
path:	Required	Output directory of the generator. Contains the file *.cgen.yml.

generator:
  - id: CubeMX
    download-url: https://www.st.com/en/development-tools/stm32cubemx.html#st-get-software
    run: ../bin/cbridge
    path: $SolutionDir()$/STM32CubeMX/$TargetType$

Note:

• The only argument to the run: command is the path to the Generator Information Index File. There are no configurable parameters for this utility. The invocation is:

  cbrige <csolution-name>.cbuild-gen-idx.yml