diff --git a/tools/projmgr/docs/Manual/Build-Operation.md b/tools/projmgr/docs/Manual/Build-Operation.md index 3e4cf4705..d6d1c4577 100644 --- a/tools/projmgr/docs/Manual/Build-Operation.md +++ b/tools/projmgr/docs/Manual/Build-Operation.md @@ -1,108 +1,3 @@ -# Build Operation +# Note - - - - -The following chapter explains the overall build process that of the CMSIS-Toolbox and how to add a new compiler toolchain. - -**Table of Contents** - -- [Build Operation](#build-operation) - - [Build Process Overview](#build-process-overview) - - [`csolution` tool](#csolution-tool) - - [`cbuild` tool](#cbuild-tool) - - [Add Toolchain to CMSIS-Toolbox](#add-toolchain-to-cmsis-toolbox) - - [Steps](#steps) - - [CMake Variables](#cmake-variables) - - [`BRANCHPROT` Values](#branchprot-values) - -## Build Process Overview - -The section below describes the overall process to add a new compiler toolchain to the CMSIS-Toolbox. - -### `csolution` tool - -The [**csolution - CMSIS Project Manager**](Overview.md) processes user [**Input Files** (in YAML format)](YML-Input-Format.md) and the `*.pdsc` metadata files of **Software Packs** and performs the following operations: - -- Generate build information in the [**Project Area**](Overview.md#project-area) with the following files: [`*.cbuild-idx.yml`, `*.cbuild.yml`](YML-CBuild-Format.md), and `*.cprj` files for the **cbuild** tool. -- Generate header files in the [**RTE Directory**](Overview.md#rte-directory-structure) for each [context](YML-Input-Format.md#context) with the following files: [RTE_components.h](Overview.md#rte_componentsh) and pre-include files from the `*.pdsc` metadata. -- [Copy the configuration files](Overview.md#plm-of-configuration-files) from selected software components to the [**RTE Directory**](Overview.md#rte-directory-structure). - -The picture below outlines these operations. - -![Operation of `csolution` tool](./images/csolution-operation.png "Operation of `csolution` tool") - -### `cbuild` tool - -The [**cbuild - Build Manager**](../../../buildmgr/docs/cbuild.md) uses a `*.cprj` build information files to perform the following operations: - -- Generate a `CMakeList.txt` file that includes a `compiler_name..cmake` file for toolchain specific configuration. This file contains the complete build information for a `*.cproject.yml` file and describes how to build a binary image or a library file. -- This `CMakeList.txt` file is 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. - -![Operation of `csolution` tool](./images/cbuild-operation.png "Operation of `csolution` tool") - -## 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`](https://github.com/Open-CMSIS-Pack/devtools/blob/main/tools/projmgr/schemas/common.schema.json). -3. Create a new CMake file in [`./tools/buildmgr/cbuildgen/config`](https://github.com/Open-CMSIS-Pack/devtools/tree/main/tools/buildmgr/cbuildgen/config) with the naming convention `compiler_name..cmake`. -4. Map with the file `compiler_name..cmake`. the **CMake** input variables to the **CMake** toolchain variables. - - Use an existing `*.cmake` file, i.e. `GCC..cmake` as reference. - -### CMake Variables - -The `CMakeLists.txt` file sets the following **CMake** input variables that should be processed by `compiler_name..cmake`. - -CMake Variable | Possible Values | Description -:------------------------------------------------|:--------------------------|:----------------------- -`BYTE_ORDER` | Little-endian, Big-endian | [Endian processor configuration](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#Dendian) -`CPU` | [DCoreEnum](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#DcoreEnum) | Processor core selection -`FPU` | [DfpuEnum](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#DfpuEnum) | Floating point unit support -`DSP` | [DdspEnum](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#DdspEnum) | DSP instruction set support -`TZ` | [DtzEnum](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#DtzEnum) | TrustZone support -`SECURE` | [DsecureEnum](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#DsecureEnum) | Software model selection -`MVE` | [DmveEnum](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#DmveEnum) | MVE instruction set support -`BRANCHPROT` | [`BRANCHPROT` values](#branchprot-values) | [Branch protection -`OPTIMIZE` | [Optimize values](YML-Input-Format.md#optimize) | Generic optimize levels for code generation -`WARNINGS` | [Warnings values](YML-Input-Format.md#warnings) | Control warning level for compiler diagnostic -`DEBUG` | [Debug values](YML-Input-Format.md#debug) | Control the generation of debug information -`DEFINES` | [Define symbols](YML-Input-Format.md#define) | 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..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 - \ No newline at end of file +Document moved to [CMSIS-Toolbox](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/build-operation.md) diff --git a/tools/projmgr/docs/Manual/Linker-Script-Management.md b/tools/projmgr/docs/Manual/Linker-Script-Management.md index a0dc99229..479f9bd49 100644 --- a/tools/projmgr/docs/Manual/Linker-Script-Management.md +++ b/tools/projmgr/docs/Manual/Linker-Script-Management.md @@ -1,63 +1,3 @@ -# Linker Script Management +# Note - - - - -**Table of Contents** - -- [Linker Script Management](#linker-script-management) - - [Overview](#overview) - - [Linker Script Preprocessing](#linker-script-preprocessing) - - [Automatic Linker Script generation](#automatic-linker-script-generation) - - [File locations](#file-locations) - - [User Modifications to Memory Regions](#user-modifications-to-memory-regions) - - [Linker Script Templates](#linker-script-templates) - -## Overview - -A Linker Script contains a series of Linker directives that specify the available memory and how it should be used by a project. The Linker directives reflect exactly the available memory resources and memory map for the project context. - -The following sequence describes the Linker Script management of the **csolution - CMSIS Project Manager**: - -1. The [`linker:`](YML-Input-Format.md#linker) node specifies an explicit linker script and/or memory regions header file. This overrules linker scripts that are part of software components or specified using the `file:` notation. - -2. If no [`linker:`](YML-Input-Format.md#linker) node is used, a linker script file can be provided as part of software components. The extensions `.sct`, `.scf`, `.ld`, and `.icf` are recognized as Linker Script files. - -3. If no Linker script is found, a [Linker Script is generated](#automatic-linker-script-generation) based on information that is provided by the `` element in Device Family Packs (DFP) and Board Support Packs (BSP). - -## Linker Script Preprocessing - -A Linker Script file is preprocessed when a `regions:` header file is specified in the [`linker:`](YML-Input-Format.md#linker) node or when the [Linker Script file is automatically generated](#automatic-linker-script-generation). A standard C preprocessor is used to create the final linker script as shown below. - -![Linker Script File Generation](./images/linker-script-file.png "Linker Script File Generation") - -## Automatic Linker Script generation - -If a project context does not specify any linker script a `regions_.h` is generated and a toolchain specific linker script template is used. - -If `regions_.h` is **not** available, it is generated based on information of the software packs using the: - -- [`` - `` element in the DFP](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_boards_pg.html#element_board_memory) -- [`` - `` element in the BSP](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_memory) - -### File locations - -The file `regions_.h` is generated in the [RTE directory](Overview.md#rte-directory-structure) path `\RTE\Device\`. The actual file name is extended with: - -- `Bname` when the `*.cproject.yml` file uses in the project context a [`board:`](YML-Input-Format.md#board-name-conventions) specification, i.e. `regions_IMXRT1050-EVKB.h` -- `Dname` name when the `*.cproject.yml` file uses in the project context only a [`device:`](YML-Input-Format.md#device-name-conventions) specification, i.e. `regions_stm32u585xx.h`. - -### User Modifications to Memory Regions - -The file `regions_.h` can be modified by the user as it might be required to adjust the memory regions or give additional attributes (such as `noinit`). Therefore this file should have [Configuration Wizard Annotations](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/configWizard.html). - -### Linker Script Templates - -The following compiler specific Linker Script files are used when no explicit file is specified. The files are located in the directory `/etc` of the CMSIS-Toolbox. - -Linker Script Template | Linker control file for ... -:-----------------------|:----------------------------- -ac6_linker_script.sct | Arm Compiler version 6 -gcc_linker_script.ld | GCC Compiler -iar_linker_script.icf | IAR Compiler +Content moved to [CMSIS-Toolbox](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/build-overview.md#linker-script-management) diff --git a/tools/projmgr/docs/Manual/Overview.md b/tools/projmgr/docs/Manual/Overview.md index db2430757..d209b63bd 100644 --- a/tools/projmgr/docs/Manual/Overview.md +++ b/tools/projmgr/docs/Manual/Overview.md @@ -1,833 +1,3 @@ -# csolution: CMSIS Project Manager - Users Manual (Draft) +# Note - - - -Manual Chapters | Content -:-------------------------------------------------------|:------------------------- -[Usage](#usage) | Overall Concept, tool setup, and invocation commands. -[Project Examples](#project-examples) | Various example projects to get started. -[Project Structure](#project-structure) | Overall structure of projects. -[YML Input Format](YML-Input-Format.md) | Format of the various YAML input files (`*.csolution.yml`, `*.cproject.yml`, `*.clayer.yml`, `cdefault.yml`). -[Linker Script Management](Linker-Script-Management.md) | Specify the available memory and control the linker operation. -[Build Operation](Build-Operation.md) | Build process overview and toolchain interface for adding additional compilers. -[YML CBuild Format](YML-CBuild-Format.md) | Format of the YAML CBuild output file. -[Reference Application Framework](RefApp-Framework.md) | Enables example projects that scale across many boards and production hardware. - -> **Note:** -> ->This documentation uses the filename extension `*.yml`, but the extension `*.yaml` is also supported. - -**Table of Contents** - -- [csolution: CMSIS Project Manager - Users Manual (Draft)](#csolution-cmsis-project-manager---users-manual-draft) - - [Revision History](#revision-history) - - [Overview of Operation](#overview-of-operation) - - [Theory of Operation](#theory-of-operation) - - [Usage](#usage) - - [Requirements](#requirements) - - [Invocation](#invocation) - - [Command Examples](#command-examples) - - [List Environment](#list-environment) - - [List Installed Packs](#list-installed-packs) - - [Install Missing Packs](#install-missing-packs) - - [List Devices or Boards](#list-devices-or-boards) - - [List Unresolved Dependencies](#list-unresolved-dependencies) - - [Create Build Information](#create-build-information) - - [Select a Toolchain](#select-a-toolchain) - - [List Compatible Layers](#list-compatible-layers) - - [Use Generators (i.e. CubeMX)](#use-generators-ie-cubemx) - - [Project Examples](#project-examples) - - [GitHub repositories](#github-repositories) - - [Minimal Project Setup](#minimal-project-setup) - - [Project Templates](#project-templates) - - [Compiler Agnostic Project](#compiler-agnostic-project) - - [Software Layers](#software-layers) - - [Configuration Settings](#configuration-settings) - - [Software Layers in Packs](#software-layers-in-packs) - - [Project Setup for Multiple Targets and Builds](#project-setup-for-multiple-targets-and-builds) - - [Project Setup for Related Projects](#project-setup-for-related-projects) - - [Project Structure](#project-structure) - - [Working Areas](#working-areas) - - [Project Area](#project-area) - - [RTE Directory Structure](#rte-directory-structure) - - [Output Directory Structure](#output-directory-structure) - - [Software Components](#software-components) - - [PLM of Configuration Files](#plm-of-configuration-files) - - [RTE\_Components.h](#rte_componentsh) - -## Revision History - -Version | Description -:------------------|:------------------------- -Draft | Work in progress - -## Overview of Operation - -The **csolution - CMSIS Project Manager** processes **user input files** (in YAML format) and **software packs** -(in Open-CMSIS-Pack format) to create self-contained CMSIS-Build input files that allow to generate independent projects -which may be a part of a more complex application. - -The **csolution - CMSIS Project Manager** supports the user with the following features: - -- Access to the content of software packs in Open-CMSIS-Pack format to: - - Setup the tool chain based on a *Device* or *Board* that is defined in the CMSIS-Packs. - - Add software components that are provided in the various software packs to the application. -- Organize applications (with a `*.csolution.yml` file) into projects that are independently managed - (using `*.cproject.yml` files). -- Organize software layers (with a `*.clayer.yml` file) that enable code reuse across similar applications. -- Manage multiple hardware targets to allow application deployment to different hardware - (test board, production hardware, etc.). -- Manage multiple build types to support software verification (debug build, test build, release build, ect.) -- Support multiple compiler toolchains (GCC, Arm Compiler 6, IAR, etc.) for project deployment. - -### Theory of Operation - -The diagram below outlines the operation of the `csolution convert` command. It processes one or more [`context`](YML-Input-Format.md#context) configurations of the application project (called solution). Refer to ["Project Examples"](#project-examples) for more information. - -![Overview](./images/Overview.png "Overview") - -Input Files | Description -:------------------------|:--------------------------------- -[Generic Software Packs](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/cp_PackTutorial.html#cp_SWComponents) | Provide re-usable software components that are typically configurable towards a user application. -[DFP Software Packs](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/cp_PackTutorial.html#createPack_DFP) | Device related information (including memory sizes) for the tool configuration. -[BSP Software Packs](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/cp_PackTutorial.html#createPackBoard) | Board specific configuration (i.e. additional memory resources). -[cdefault.yml](YML-Input-Format.md#default) | When enabled with [`cdefault:`](YML-Input-Format.md#solution), setup of toolchain specific controls and pre-defined toolchains. -[*.csolution.yml](YML-Input-Format.md#solution) | Complete scope of the application with build order of sub-projects. Defines [target](YML-Input-Format.md#target-types) and [build](YML-Input-Format.md#build-types) types. -[*.cproject.yml](YML-Input-Format.md#project) | Content of an independent build (linker run) - directly relates to a `*.cprj` file. -[*.clayer.yml](YML-Input-Format.md#layer) | Set of source files along with pre-configured components for reuse in different applications. - -Output Files | Description -:------------------------|:--------------------------------- -[*.cbuild-idx.yml](YML-CBuild-Format.md#file-structure-of-cbuild-idxyml) | Index file of all `*.cbuild.yml` build descriptions; contains also overall information for the application. -[*.cbuild.yml](YML-CBuild-Format.md#file-structure-of-cbuild-yml) | Build description of a single [`*.cproject.yml`](YML-Input-Format.md#project-file-structure) input file (replaces *.CPRJ in CMSIS-Toolbox 2.1 - schedule for Q3'23) -[Project Build Files *.cprj](https://arm-software.github.io/CMSIS_5/Build/html/cprjFormat_pg.html) | Project build information for a Open-CMSIS-Pack based tool environment. -[Run-Time Environment (RTE)](#rte-directory-structure) | Contains the user configured files of a project along with RTE_Components.h inventory file. -[Linker Script Files](Linker-Script-Management.md#automatic-linker-script-generation) | Header file that describes the memory resources. - -To build an application project, the `csolution convert` command executes the following steps: - -1. Read Input Files: - - Read *.YML input files and check files against schema (disable schema check with option: `--no-check-schema`) - - Parse *.YML input nodes. - - Load software packs for selected contexts (control packs with option: `--load [latest|all|required]`). - -2. Process each project context (select a specific context with option: `--context`): - - Apply [`pack:`](YML-Input-Format.md#pack), [`device:`](YML-Input-Format.md#device) and [`board:`](YML-Input-Format.md#board) to filter the content of software packs. - - From [`groups:`](YML-Input-Format.md#groups) add the list of user source files. - - From [`components:`](YML-Input-Format.md#components) add the list of component source files. - - From [*.GPDSC files](#use-generators-ie-cubemx) add the list of generated source files. - -3. Generate output files: - - Update [configuration files](#plm-of-configuration-files) in RTE directory (disable with option: `--no-update-rte`). - - Print results of software component dependency validation. - - Create `cbuild-idx.yml`, `cbuild.yml` and `*.CPRJ` files. - -## Usage - -### Requirements - -The CMSIS-Pack repository must be present in the development environment. - -- There are several ways to initialize and configure the pack repository, for example using the - `cpackget` tool available from -- Before running the **csolution - CMSIS Project Manager** the location of the pack repository shall be set via the environment variable - `CMSIS_PACK_ROOT` otherwise its default location (todo what is the default?) will be taken. - -### Invocation - -```text -csolution: Project Manager 2.0.0 (C) 2023 Arm Ltd. and Contributors - -Usage: - csolution [.csolution.yml] [options] - -Commands: - convert Convert user input *.yml files to *.cprj files - list boards Print list of available board names - list contexts Print list of contexts in a .csolution.yml - list components Print list of available components - list dependencies Print list of unresolved project dependencies - list devices Print list of available device names - list environment Print list of environment configurations - list generators Print list of code generators of a given context - list layers Print list of available, referenced and compatible layers - list packs Print list of used packs from the pack repository - list toolchains Print list of supported toolchains - run Run code generator - update-rte Create/update configuration files and validate solution - -Options: - -c, --context arg [...] Input context names [][.][+] - --context-replacement arg Input context replacement name [][.][+] - -d, --debug Enable debug messages - -D, --dry-run Enable dry-run - -e, --export arg Set suffix for exporting .cprj retaining only specified versions - -f, --filter arg Filter words - -g, --generator arg Code generator identifier - -l, --load arg Set policy for packs loading [latest | all | required] - -L, --clayer-path arg Set search path for external clayers - -m, --missing List only required packs that are missing in the pack repository - -n, --no-check-schema Skip schema check - -N, --no-update-rte Skip creation of RTE directory and files - -o, --output arg Output directory - -t, --toolchain arg Selection of the toolchain used in the project optionally with version - -v, --verbose Enable verbose messages - -V, --version Print version - -Use 'csolution -h' for more information about a command. -``` - -### Command Examples - -#### List Environment - -Print the current directory settings which allows to verify the correctness of the tool installation. - -```text -csolution list environment -``` - -#### List Installed Packs - -Print list of installed packs. The list can be filtered by words provided with the option `--filter`: - -```text -csolution list packs [--filter ""] -``` - -Print list of packs that are required by the ``. - -```text -csolution list packs example.csolution.yml -``` - -#### Install Missing Packs - -Print list of missing packs to the file `packs.txt` that are required by the `` but not available -in the pack repository. This missing packs might be installed using the -[`cpackget`](../../../cpackget/docs/cpackget.md) tool. - -```text -csolution list packs example.csolution.yml -m >packs.txt -cpackget update-index // optional to ensure that pack index is up-to-date -cpackget add -f packs.txt -``` - -#### List Devices or Boards - -Print list of available device or board names. The list can be filtered by words provided with the option `--filter`: - -```text -csolution list devices -csolution list boards --filter NXP -``` - -#### List Unresolved Dependencies - -Print list of unresolved project dependencies. Device, board, and software components are specified as part of the -`*.csolution.yml` and `*.cproject.yml` files. The list may be filtered by words provided with the option `--filter`: - -```text -csolution list dependencies mysolution.csolution.yml [-f ""] -``` - -#### Create Build Information - -Convert `example.csolution.yml` into build information files. - -```text -csolution convert example.csolution.yml -``` - -Convert specific contexts of a `*.csolution.yml` file into build information files. - -```text -csolution convert SimpleTZ.csolution.yml -c CM33_s.Debug -c CM33_ns.Release+AVH -``` - -#### Select a Toolchain - -List and select a specific toolchain (in this case AC6 for Arm Compiler version 6) for the compilation of a project. - -```text -csolution list toolchains --verbose -csolution convert example.csolution.yml -t AC6 -``` - -#### List Compatible Layers - -List compatible layers for `./fxls8962_normal_spi.csolution.yml` and the context `*+frdmk22f_agmp03`. This contains also setup information. - -```text -csolution list layers ./fxls8962_normal_spi.csolution.yml -c *+frdmk22f_agmp03 -``` - -Refer to [Working with Layers](RefApp-Framework.md#working-with-layers) for more information. - -#### Use Generators (i.e. CubeMX) - -List external code generators that are used to create software components in `*.gpdsc` format. It outputs the generator -ID that is required for the `run` command. - -```text -csolution list generators mysolution.csolution.yml -``` - -Run a generator (in this case STCubeMX) for a specific project context. - -```text -csolution run -g STCubeMX mysolution.csolution.yml -c Blinky.Debug+STM32L4 -``` - -## Project Examples - -### GitHub repositories - -The following repositories provide several working examples: - -Repository | Description -:---------------------|:------------------------------------- -[csolution-examples](https://github.com/Open-CMSIS-Pack/csolution-examples) | Contains a simple Hello World example and links to other working examples. -[vscode-get-started](https://github.com/Open-CMSIS-Pack/vscode-get-started) | Contains the setup for a VS Code development environment including an example project. - -The section below explains the the overall concepts consider by the **csolution - CMSIS Project Manager** based on examples. - -### Minimal Project Setup - -A minimal application requires two files: - -- `Sample.csolution.yml` that defines the a [target type](YML-Input-Format.md#target-types) with [device](YML-Input-Format.md#device) and selects the [compiler](YML-Input-Format.md#compiler). -- `Sample.cproject.yml` that defines the files and software components that belong to the device. - -### Project Templates - -The following `*.csolution.yml` templates may be used to create own embedded applications. - -Template | Description -:-----------|:------------------------------ -[Simple](https://github.com/Open-CMSIS-Pack/csolution-examples/tree/main/Templates/Simple) | A csolution.yml template with a single cproject.yml. -[Multicore](https://github.com/Open-CMSIS-Pack/csolution-examples/tree/main/Templates/Multicore) | A csolution.yml template with multiuple cproject.yml each targeting one processor of a multicore device. -[TrustZone](https://github.com/Open-CMSIS-Pack/csolution-examples/tree/main/Templates/TrustZone) | A csolution.yml template with a non-secure cproject.yml and an optional secure cproject.yml. -[UnitTest](https://github.com/Open-CMSIS-Pack/csolution-examples/tree/main/Templates/UnitTest) | A csolution.yml template that shares one HAL clayer.yml with multiple cproject.yml files for unit testing. - -To use these templates, copy the content of the folder to your own application folder. Then adapt the names accordingly and add missing information. - -Refer to [Overall Workflow](https://github.com/Open-CMSIS-Pack/csolution-examples/tree/main/Templates#overall-workflow) for more details. - -**Simple Project: `Sample.csolution.yml`** - -```yml -solution: - created-for: CMSIS-Toolbox@2.0.0 - cdefault: - compiler: AC6 # explicit selection of compiler - - packs: - - pack: NXP::K32L3A60_DFP@16.0.0 # specify DFP - - pack: NXP::FRDM-K32L3A6_BSP@16.0.0 - - target-types: - - type: FRDM-K32L3A6 - board: FRDM-K32L3A6 - - build-types: # defines toolchain options for 'debug' and 'release' - - type: Debug - debug: on - optimize: none - - - type: Release - debug: off - optimize: balanced - - projects: - - project: ./Sample.cproject.yml -``` - -**Simple Project: `Sample.cproject.yml`** - -```yml -project: - packs: - - pack: ARM::CMSIS # specify additional packs - - groups: - - group: App - files: - - file: ./main.c - - components: - - component: ARM::CMSIS:CORE - - component: Device:Startup -``` - -### Compiler Agnostic Project - -With generic [**Translation Control**](YML-Input-Format.md#translation-control) settings it is possible to create projects that work across the range of supported compilers (AC6, GCC, IAR). The compiler selection and potential compiler specific settings can be stored in the file `cdefault.yml`. By replacing the `cdefault.yml` file it is possible to re-target application projects. [**Translation Control**](YML-Input-Format.md#translation-control) settings are mapped to specify compiler by the build tools. - -**Default settings for multiple compiler toolchains** - -```yml -default: - compiler: GCC # selects the default compiler for an installation - - misc: - - for-compiler: GCC - C: - - -std=gnu11 - Link: - - --specs=nano.specs - - --specs=rdimon.specs - - - for-compiler: AC6 - C-CPP: - - -Wno-macro-redefined - - -Wno-pragma-pack - - -Wno-parentheses-equality - C: - - -std=gnu11 - ASM: - - -masm=auto - Link: - - --entry=Reset_Handler - - --info summarysizes - - - for-compiler: IAR - C-CPP: - - --dlib_config DLib_Config_Full.h - Link: - - --semihosting -``` - -**Simple Compiler Agnostic Project: `Sample.csolution.yml`** - -```yml -solution: - cdefault: # use default setup of toolchain specific controls - compiler: AC6 # explicit compiler selection (optional) - - packs: - - pack: ARM::CMSIS - - pack: Keil::LPC1700_DFP - - target-types: # multiple device or boards - - type: MyHardware - device: NXP::LPC1768 - - - type: MyBoard - board: MCB1700 - - build-types: - - type: debug # options for 'debug' - optimize: none - debug: on - - - type: release # options for 'release' - optimize: balanced - debug: off - - projects: - - project: ./Sample.cproject.yml -``` - -**Simple Compiler Agnostic Project: `Sample.cproject.yml`** - -```yml -project: - groups: - - group: App - files: - - file: ./main.c - - components: - - component: ARM::CMSIS:CORE - - component: Device:Startup -``` - -### Software Layers - -Software layers collect source files and software components along with configuration files for re-use in different projects as shown in the picture below. - -![Project Layers](./images/Layers.png "Project Layers") - -An application could be composed of various layers, for example to compose an IoT cloud application: - -- **Demo.cproject.yml**: Implements the IoT Reference example. -- **Socket.clayer.yml**: A software layer that provides the Socket interface for internet connectivity. -- **Board.clayer.yml**: A software layer that provides the hardware interfaces to the device hardware. - -**Example:** - -The project [AWS_MQTT_MutualAuth_SW_Framework](https://github.com/Open-CMSIS-Pack/AWS_MQTT_MutualAuth_SW_Framework) provides an example for software layers. - -#### Configuration Settings - -A software layer is a set of source files and pre-configured software components that can be shared across multiple projects. For sharing the configuration settings of software components across multiple projects, -the configuration files of a [`layer`](YML-Input-Format.md#layer) are stored within the directory structure of the software layer. This separate [RTE Directory Structure](#rte-directory-structure) allows that projects -can share a `layer` with common configuration settings. - -#### Software Layers in Packs - -A collection of software layers can be stored in software packs using the element [``](todo-link). Using the `list layers` command it is possible to identify compatible software by iterating the [`layers:` - `type:`](YML-Input-Format.md#layers---type) - [`connections`](YML-Input-Format.md#connections). -filter conditions to it. In combination with interfaces specifications, an interactive IDE should be able to display suitable layers that could be added to an application. - -### Project Setup for Multiple Targets and Builds - -Complex examples require frequently slightly different targets and/or modifications during build, i.e. for testing. The -picture below shows a setup during software development that supports: - -- Unit/Integration Testing on simulation models (called Virtual Hardware) where Virtual Drivers implement the interface - to simulated I/O. -- Unit/Integration Testing the same software setup on a physical board where Hardware Drivers implement the interface to - physical I/O. -- System Testing where the software is combined with more software components that compose the final application. - -![Target and Build Types](./images/TargetBuild-Types.png "Target and Build Types") - -As the software may share a large set of common files, provisions are required to manage such projects. The common way -in other IDE's is to add: - -- **target-types** that select a target system. In the example this would be: - - `Virtual`: for Simulation Models. - - `Board`: for a physical evaluation board. - - `Production-HW`: for system integration test and the final product delivery. -- **build-types** add the flexibility to configure each target build towards a specific testing. It might be: - - `Debug`: for a full debug build of the software for interactive debug. - - `Test`: for a specific timing test using a test interface with code maximal optimization. - - `Release`: for the final code deployment to the systems. - -It is required to generate reproducible builds that can deployed on independent CI/CD test systems. To achieve that, the **csolution - CMSIS Project Manager** generates *.cprj output files with the following naming conventions: - -`[.][+target-type].cprj` this would generate for example: `Multi.Debug+Production-HW.cprj` - -This output file convention is identical with the [context: name conventions](YML-Input-Format.md#context-name-conventions) and enables that each `target-type:` and/or `build-type:` can be identified and independently generated which provides the support for test automation. It is however not required to build every possible combination, this should be under user control. - -**Flexible Builds for multi-target projects** - -Currently multi-target projects require the setup of a `*.csolution.yml` file to define `target-types` and -`build-types`. Note, that this is currently under review, but this documents the current status. - -**File: MultiTarget.csolution.yml** - -```yml -solution: - cdefault: # use default setup of toolchain specific controls - compiler: AC6 - - : # pack definition not shown - - target-types: - - type: Board - board: NUCLEO-L552ZE-Q - - - type: Production-HW - device: STM32L552XY # specifies device - - - type: Virtual - board: VHT-Corstone-300 # Virtual Hardware platform (appears as board) - - build-types: - - type: Debug - optimize: none - debug: on - - - type: Test - optimize: size - debug: on - - - type: Release - optimize: size - debug: off - -projects: - - project: ./MyProject.cproject.yml -``` - -**File: MyProject.csolution.yml** - -```yml -project: - groups: - - group: My group1 - files: - - file: file1a.c - - file: file1b.c - - file: file1c.c - - - group: My group2 - files: - - file: file2a.c - - - group: Test-Interface - for-context: .Test - files: - - file: fileTa.c - - layers: - - layer: NUCLEO-L552ZE-Q/Board.clayer.yml # tbd find a better way: i.e. $Board$.clayer.yml - for-context: +Board - - - layer: Production.clayer.yml # added for target type: Production-HW - for-context: +Production-HW - - - layer: Corstone-300/Board.clayer.yml # added for target type: AVH-Corstone-300 - for-context: +AVH-Corstone-300 - - components: - - component: Device:Startup - - component: CMSIS:RTOS2:FreeRTOS - - component: ARM::CMSIS:DSP&Source # not added for build type: Test - not-for-context: .Test -``` - -### Project Setup for Related Projects - -A solution is the software view of the complete system. It combines projects that can be generated independently and -therefore manages related projects. It may be also deployed to different targets during development as described in the -previous section under [Project Setup for Multiple Targets and Builds](#project-setup-for-multiple-targets-and-builds). - -The picture below shows a system that is composed of: - -- Project A: that implements a time-critical control algorithm running on a independent processor #2. -- Project B: which is a diagram of a cloud connected IoT application with Machine Learning (ML) functionality. -- Project C: that is the data model of the Machine Learning algorithm and separate to allow independent updates. -- Project D: that implements the device security (for example with TF-M that runs with TrustZone in secure mode). - -In addition such systems may have a boot-loader that can be also viewed as another independent project. - -![Related Projects of an Embedded System](./images/Solution.png "Related Projects of an Embedded System") - -To manage the complexity of such related a projects, the `*.csolution.yml` file is introduced. At this level the -`target-types:` and `build-types:` may be managed, so that a common set is available across the system. However it should -be also possible to add project specific `build-types` at project level. (tdb: `target-types` might be only possible at -solution level). - -- `target-types:` describe a different hardware target system and have therefore different API files for peripherals or a - different hardware configuration. - -- `build-types:` describe a build variant of the same hardware target. All `build-types` share the same API files for - peripherals and the same hardware configuration, but may compile a different variant (i.e. with test I/O enabled) of - an application. - -**Related Projects: `iot-product.csolution.yml`** - -```yml -solution: - : # setup not shown - - target-types: - - type: Board - board: NUCLEO-L552ZE-Q - - - type: Production-HW - device: STM32U5X # specifies device - - build-types: - - type: Debug - optimize: none - debug: on - - - type: Test - optimize: size - debug: on - - projects: - - project: ./security/TFM.cproject.yml - for-context: .Release - - project: ./application/MQTT_AWS.cproject.yml - - project: ./bootloader/Bootloader.cproject.yml - not-for-context: +Virtual -``` - -## Project Structure - -This section describes how the files of a `csolution` based project should be organized to allow the scenarios described above. This section gives also guidelines for a directory structure. - -Refer to [Directory Control](./YML-Input-Format.md#directory-control) for information about configuring this directories. - -### Working Areas - -The table below explains the different working area sections of an application project. - -Working Area | Access | Description -:-----------------------------------------------------------------|:------:|:------------------ -[Project Area](#project-area) | RW | Contains user source code files managed by the user along with the project files (see next item). -[Project files](./YML-Input-Format.md#project-file-structure) | RW | Created by a user or an IDE front-end to describe the application project. -Component source code | RO | Content of software packs; specified by environment variable [`CMSIS_PACK_ROOT`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/installation.md#environment-variables) or [`pack: path`](./YML-Input-Format.md#pack) in project files. -[Component Configuration​](#rte-directory-structure) | RW | User editable config files of software components that are copied to the RTE directory. -Generator artifacts​ | RO | Managed by domain specific configuration tools such as STM32CubeMX or MCUXpresso. -[Build artifacts](./YML-Input-Format.md#directory-control) | RW | Created during the build process for example by a compiler. - -### Project Area - -There are no strict rules on how to organize the project area that stores the user source code. However the following guidelines are given: - -- Each [solution](#project-examples) should have a distinct base directory. This directory contains the file `*.csolution.yml` which refers to the independent projects defined with `*.cproject.yml` files. - -- Each project should have a distinct base directory. This directory contains the file `*.cproject.yml` that defines the content of the project. The source code of the project might be grouped in sub-directories that are typically stored in this base directory. The [component configuration​](#rte-directory-structure) of the software components is typically stored in a sub-directory with the name `./RTE`. A `*.cproject.yml` may refer one or more [software layers](#software-layers) with `*.clayer.yml` files. - -- Each software layer should have a distinct base directory with a similar structure as a project. This base directory contains the file `*.clayer.yml` that defines the content of the software layer. It also contains the user source code (optionally organized in sub-directories and the [component configuration​](#rte-directory-structure) of software components that belong to this layer, typically stored in a sub-directory with the name `./RTE`. - -### RTE Directory Structure - -The table below summarizes the overall directory structure and further details the `./RTE` directory. The `./RTE` directory contains the configuration information for software components and is managed by the **csolution - CMSIS Project Manager**. It contains: - -- Configuration files of the software components. These files have `attr="config"` in the PDSC-file of the software packs. Refer to [PLM of Configuration Files](#plm-of-configuration-files) for more information. -- The file [`RTE_components.h`](#rte_componentsh) and pre-include files that are generated based on the PDSC-file information of the software packs. - -> **Note:** -> -> The `./RTE` directory structure is maintained by tools. You should not modify the structure of this directory. However the complete directory should be committed to a repository of a version control system. - -Directory Structure | Content -:-----------------------------------|:--------------- -`` | Base directory that contains one or more `*.csolution.yml` files. -`` | Each project has its own directory, this base directory contains the `*.cproject.yml` file. -`/RTE/` | Configurable files for each component `Cclass` have a common directory. -`/RTE//` | Configurable files for components that have a condition to a `device` are in a separate directory. -`/RTE/` | Directory for `RTE_components.h` and pre-include files that are generated by the **csolution - CMSIS Project Manager**. -`` | Each layer has its own base directory; this directory contains the `*.clayer.yml` file. -`/RTE/` | Configurable files for each component `Cclass` have a common directory. -`/RTE//` | Configurable files for components that have a condition to a `device` are in a separate directory. - -- The `` has the following format: `__`. - -> **Note:** -> -> CBuild does no longer generate the `` by default. It is therefore required to align the naming of `` with other tools (MDK, CMSIS-Pack-Eclipse, etc.) that support the CMSIS-Pack system. - -### Output Directory Structure - -By default the following output and working directories are used. The content of these output directories is generated by the `cbuild` step. - -Output / Working Directory | Content -:---------------------------------------------|:--------------- -`./out///` | Contains the final binary and symbol files of a project context. -`./tmp///` | Contains interim files (`*.o`, `*.lst`) of a project context. - -### Software Components - -Software components are re-usable library or source files that require no modification in the user application. -Optionally, configurable source and header files are provided that allow to set parameters for the software component. - -- Configurable source and header files are copied to the project using the directory structure explained above. -- Libraries, source, and header files that are not configurable (and need no modification) are stored in the directory - of the software component (typically part of CMSIS_Pack_ROOT) and get included directly from this location into the - project. -- An Include Path to the header files of the software component is added to the C/C++ Compiler control string. - -> **Note:** -> -> The option `--no-update-rte` disables generation of files in the `./RTE` directory and therefore the management of configuration files and the `RTE_Components.h` file. - -### PLM of Configuration Files - -Configurable source and header files have a version information that is required during Project Lifetime Management -(PLM) of a project. The version number is important when the underlying software pack changes and provides a newer -configuration file version. - -Depending on the PLM status of the application, the `csolution` performs for configuration files the following -operation: - -1. **Add** a software component for the first time: the related config file is copied twice into the related `RTE` - project directory. The first copy can be modified by the user with the parameters for the user application. The - second copy is an unmodified backup file with the format `..base@version`. - - **Example:** A configuration file `ConfigFile.h` at version `1.2.0` is copied: - - ```c - ./RTE/component_class/ConfigFile.h // user editable configuration file - ./RTE/component_class/ConfigFile.h.base@1.2.0 // current unmodified configuration file with version - // information; used as a base for version comparison - ``` - - The `csolution` outputs a user notification to indicate that files are added: - - ```text - ./RTE/component_class/ConfigFile.h - info: component 'name' added configuration file version '1.2.0' - ``` - - >**NOTE:** - > - > The unmodified files with `@version` information should be committed to the repository of the version control system as this files are used to upgrade configuration information using merge utilities. - -2. **Upgrade** (or downgrade) a software component: if the version of the unmodified backup file is identical, no - operation is performed. If the version differs, the new configuration file is copied with the format - `..update@version`. - - **Example:** after configuration file `ConfigFile.h` to version `1.3.0` the directory contains these files: - - ```c - ./RTE/component_class/ConfigFile.h // user editable configuration file (based on current version) - ./RTE/component_class/ConfigFile.h.update@1.3.0 // new configuration file; used to start a 3-way merge - ./RTE/component_class/ConfigFile.h.base@1.2.0 // current unmodified configuration file with version - // information; used as a base for version comparison - ``` - - The `csolution` outputs a user notification to indicate that configuration files have changed: - - ```text - ./RTE/component_class/ConfigFile.h - warning: component 'name' upgrade for configuration file version '1.3.0' - added, but file inactive - ``` - -3. **User action to complete upgrade**: The user has now several options (outside of `csolution`) to merge the - configuration file information. A potential way could be to use a 3-way merge utility. After merging the - configuration file, the hidden backup should be deleted and the unmodified new version should become the hidden - backup. The previous configuration file may be stored as backup as shown below. - - ```c - ./RTE/component_class/ConfigFile.h // new configuration file with merge configuration - ./RTE/component_class/ConfigFile.h.bak // previous configuration file stored as backup - ./RTE/component_class/ConfigFile.h.base@1.3.0 // current unmodified configuration file with version - // information; used as a base for version comparison - ``` - -> **Note: Multiple Instances of Configuration files** -> ->The system is also capable of handling multiple instances of configuration files as explained in the CMSIS-Pack specification under ->[Component Instances](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_components_pg.html#Component_Instances). ->In this case the instance %placeholder% is expanded as shown below: -> -> ```c -> ./RTE/component_class/ConfigFile_0.h -> ./RTE/component_class/ConfigFile_0.h.base@1.2.0 -> ./RTE/component_class/ConfigFile_1.h -> ./RTE/component_class/ConfigFile_1.h.base@1.2.0 -> ``` - -### RTE_Components.h - -The file `./RTE/RTE_Components.h` is automatically created by the CMSIS Project Manager (during CONVERT). For each -selected software component it contains `#define` statements required by the component. These statements are defined in -the `*.PDSC` file for that component. The following example shows a sample content of a RTE_Components.h file: - -```c -/* Auto generated Run-Time-Environment Component Configuration File *** Do not modify ! *** */ - -#ifndef RTE_COMPONENTS_H -#define RTE_COMPONENTS_H - -/* Define the Device Header File: */ -#define CMSIS_device_header "stm32f10x.h" - -#define RTE_Network_Interface_ETH_0 /* Network Interface ETH 0 */ -#define RTE_Network_Socket_BSD /* Network Socket BSD */ -#define RTE_Network_Socket_TCP /* Network Socket TCP */ -#define RTE_Network_Socket_UDP /* Network Socket UDP */ - -#endif /* RTE_COMPONENTS_H */ -``` - -The typical usage of the `RTE_Components.h` file is in header files to control the inclusion of files that are related -to other components of the same software pack. - -```c -#include "RTE_Components.h" -#include CMSIS_device_header - -#ifdef RTE_Network_Interface_ETH_0 // if component Network Interface ETH 0 is included -#include "Net_Config_ETH_0.h" // add the related configuration file for this component -#endif -``` +Document moved to [CMSIS-Toolbox](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/build-overview.md) diff --git a/tools/projmgr/docs/Manual/RefApp-Framework.md b/tools/projmgr/docs/Manual/RefApp-Framework.md index bb8a8e084..ae5d98e14 100644 --- a/tools/projmgr/docs/Manual/RefApp-Framework.md +++ b/tools/projmgr/docs/Manual/RefApp-Framework.md @@ -1,342 +1,3 @@ -# Reference Application Framework +# Note -(Proposal) - - - - - -**Table of Contents** - -- [Reference Application Framework](#reference-application-framework) - - [Overview](#overview) - - [Software Layers](#software-layers) - - [Interface Definitions](#interface-definitions) - - [Target Hardware Abstraction](#target-hardware-abstraction) - - [Connections](#connections) - - [Arduino Shield](#arduino-shield) - - [Software Layer Types](#software-layer-types) - - [Board](#board) - - [Shield](#shield) - - [RTOS](#rtos) - - [Socket](#socket) - - [Stream](#stream) - - [Working with Layers](#working-with-layers) - - [Install missing software packs](#install-missing-software-packs) - - [Compile application](#compile-application) - - [Add new targets](#add-new-targets) - - [Known problems](#known-problems) - - [Finalize Workflow](#finalize-workflow) - -## Overview - -The following section describes the structure of a standardized **Reference Application Framework** that allows to demonstrate a range of application examples: - -- Cloud connectivity using SDKs from Cloud Service Providers. -- Sensor reference examples. -- Machine Learning applications that use sensors and audio inputs. -- Middleware examples such as TCP/IP stack and file system. - -These reference examples can target various evaluation boards. It is also possible to target production hardware and use the examples as starting point for embedded IoT and ML applications. This is enabled by: - -- Software layers with defined and standardized interfaces that contain re-usable parts of applications. -- Description of standardized connections (provided and consumed interfaces) between these software layers. -- Consistent bootstrap and startup sequence that initializes the system resources and starts the application software. -- Board software layer that provides connections for many different applications. - -![Layers of Reference Examples](./images/Reference-Example.png "Layers of Reference Examples") - -> **Note:** -> -> The various software layer types are optional; the usage depends on the reference application. The layer type board is an exception, as it is the base software layer that implements the system startup. - -### Software Layers - -The following table lists the various software layers types that are used to compose reference applications. - -Software Layer Type | Description of the operations -:----------------------|:---------------------------------- -Socket | Provides an IoT_Socket for network connectivity. -RTOS | Provides a CMSIS-RTOS2 compliant RTOS; various RTOS implementations may provide extra functionality. -Stream | Provides middleware for sensor, audio, and video data streaming to DSP and ML algorithms. -Board | System startup: board/device hardware initialization; transfers control to application. Exposes various drivers and interfaces. -Shield | Provides software definitions and support for additional hardware provided on shields that extend a physical hardware board. - -Each of the software layers is described in the section [Software Layer Types](#software-layer-types) - -### Interface Definitions - -The interfaces between the software layers are defined in header files. As such is it possible to reuse the various software blocks with other build systems that are not CMSIS aware. - -The header files `CMSIS_board_header`, `iot_socket.h`, `cmsis_os2.h`, and `todo: cmsis_stream.h` are typically used by the reference application to access the software layers. - -Header File | Description -:------------------------|:---------------------------------- -`CMSIS_board_header` | `#define` of the board header file; gives access to drivers defined in the board connections. -`CMSIS_shield_header` | `#define` of the shield header file; gives access to drivers defined in the shield connections. -`CMSIS_target_header` | `#define` of the target header file; combines drivers defined in Board and Shield layers. -[`iot_socket.h`](https://github.com/MDK-Packs/IoT_Socket/blob/develop/include/iot_socket.h) | Defines the interface to the [IoT Socket](https://github.com/MDK-Packs/IoT_Socket). -[`cmsis_os2.h`](https://github.com/ARM-software/CMSIS_5/blob/develop/CMSIS/RTOS2/Include/cmsis_os2.h) | Defines the interface to the [RTOS](https://arm-software.github.io/CMSIS_5/RTOS2/html/group__CMSIS__RTOS.html). -`cmsis_stream.h` | ToDo: Defines the interface for data streaming. - -### Target Hardware Abstraction - -**Proposed Software Structure (work-in-progress)** - -The Board and Shield layer combined are the Target Hardware Abstraction (defined in `CMSIS_target_header`) for the IoT/ML Software Platform (composed of Reference Application, Socket, RTOS and Stream layer). Using the CMSIS-Toolbox, the `target-type:` selection allows to change both the Board and Shield layer along with the `CMSIS_target_header` definition. This retargets the IoT/ML Software Platform to run on a different hardware target as shown in the picture below. This is a typical use case for validation and prototyping during software development. - -![Target Layer](./images/Target-Layer.png "Target Layer") - -Some applications require Process Isolation to separate safety critical functionality from uncritical functionality. The parts of the IoT/ML Software Platform are typical qualified uncritical functionality. In such a design the Target it is required to rquGoing forward, - -![Process Isolation](./images/Process-Isolation.png "Process Isolation") - -### Connections - -The [connections](YML-Input-Format.md#connections) are only used to identify compatible software layers. There are no strict rules for the **`connect` Name** it is therefore possible to extend it with additional name spacing, i.e. prefix with *ST_* to denote ST specific interfaces. - -There are also no strict rules how the different software layers consume or provide the `connect` names. However guidelines will be developed once reference applications mature. - -Currently the following **`connect` names** are used. - -`connect` name | Value | Description -:----------------------|:-----------------------|:-------------------- -. |. | **Arduino Shield Interface** -ARDUINO_UNO_UART | CMSIS-Driver instance | CMSIS-Driver UART connecting to UART on Arduino pins D0..D1 -ARDUINO_UNO_SPI | CMSIS-Driver instance | CMSIS-Driver SPI connecting to SPI on Arduino pins D10..D13 -ARDUINO_UNO_I2C | CMSIS-Driver instance | CMSIS-Driver I2C connecting to I2C on Arduino pins D20..D21 -ARDUINO_UNO_I2C-Alt | CMSIS-Driver instance | CMSIS-Driver I2C connecting to I2C on Arduino pins D18..D19 -ARDUINO_UNO_D0 .. D21 | - | CMSIS-Driver GPIO connecting to Arduino pins D0..D21 -. |. | **CMSIS Driver and RTOS Interfaces** -CMSIS_\ | CMSIS-Driver instance | [CMSIS-Driver](https://arm-software.github.io/CMSIS_5/Driver/html/modules.html) name, i.e. CMSIS_I2C, CMSIS_ETH_MAC. -CMSIS-RTOS2 |. | CMSIS-RTOS2 compliant RTOS -. | | **Network Connectivity** -IoT_Socket |. | IP Socket (BSD like) Network layer -. |. | **I/O Retargeting** -STDERR |. | Standard Error output -STDIN |. | Standard Input -STDOUT |. | Standard Output -. |. | **Memory allocation** -Heap | Heap Size | Memory heap configuration in startup -. |. | **Data Streaming Interfaces** -Stream_Audio |. | Audio Data Stream (todo) -Stream_SDS |. | Synchronous Data Stream (Sensors) (todo) -. | | **PSA Security Interfaces** -PSA_\ |. | Interfaces for Crypto, Storage, Firmware Update - -### Arduino Shield - -The software layers [Board](#board) and [Shield](#shield) are currently based on Arduino UNO connectors. To combine different boards and shields a consistent pin naming is required. The standardized mapping is shown in the diagram below. - -![Arduino Shield Pinout](./images/Arduino-Shield.png "Arduino Shield Pinout") - -## Software Layer Types - -### Board - -Provides system startup, board/device hardware initialization, and transfers control to the application. It also exposes various drivers and interfaces. - -**Features:** - -- System startup -- Heap and Stack configuration -- Device/Board hardware initialization -- Shield setup [optional] -- Application startup for applications with and without RTOS -- [Event Recorder](https://arm-software.github.io/CMSIS-View/main/evr.html) initialization [optional] -- [Fault Storage](https://arm-software.github.io/CMSIS-View/main/evr.html) [optional] -- RTOS initialization and startup [optional] -- Drivers for peripherals or Arduino interfaces [optional] -- STDIO re-targeting to debug interfaces [optional] -- PSA interfaces [optional] - -**Files:** - -- CMSIS startup and system file for device initialization. -- `main.c` source module that implements the function `main`. -- Optional drivers and interfaces (CMSIS-Drivers, GPIO, STDIO). -- Files that relate to the device and/or board configuration (i.e. generated by MCUXpresso or STM32CubeMX) -- Linker script definition - -The `main.c` source module of the Board software layer uses the following entry points to the application code: - -- `app_initialize` initializes the software stack and is executed in Handler mode. -- `app_main` transfers execution to the application. For RTOS-based applications this is a RTOS thread. - -**RTOS Usage** - -The board layer supports application with or without RTOS. The function `extern void app_main (void *argument)` defines the entry point of the application. - -- Application using RTOS: - - Before RTOS is started the function `app_initialize` is called where the user can create application threads. A default implementation (defined `weak`) is part of the board layer: - - ``` c - __WEAK int32_t app_initialize (void) { - osThreadNew(app_main, NULL, NULL); - } - ``` - - By default, `app_main` is the thread that starts executing with default settings (priority, stack). - -- Application not using RTOS: - - `app_main` is the entry of the application and executes as a single thread. - -### Shield - -Support for additional hardware via plugin shields (i.e. Arduino Uno). Arduino shields [*consume connections*](YML-Input-Format.md#example-sensor-shield) with the prefix `ARDUINO_UNO_`. Potentially other shields could be covered. - -Shields may feature various hardware modules such as WiFi chips or MEMS sensors. Frequently the Shield software layer only defines a header file that redirects the Arduino specific `connect:` to a chip specific `connect:` that is then used by application software. - -The Shield software layer is configured from the Board software layer which calls the following function: - -``` c -extern int32_t shield_setup (void); -``` - -**Example:** - -Connections (consumed): - -- ARDUINO_UNO_* (provided by board layer) -- STDIN/OUT (if used by the driver) -- RTOS2 (if used by the driver) - -Connections (provided): - -- CMSIS_WiFi (WiFi Shield) -- \ -- \_\ - -Note regarding sensors: - -\ is typically a sensor name (for example NXP sensors: FXLS8974, FXAS21002, … -Sensor can use different buses (I2C, SPI) and have optional interrupt lines. It makes sense to define sensor connections with specifying features to cover various layer combinations. Examples of connections: -FXLS8974 sensor: - -- Connected via I2C: - - FXLS8974_I2C: connected via I2C - - FXLS8974_INT: interrupt line (optional) -- Connected via SPI: - - FXLS8974_SPI: connected via SPI - - FXLS8974_CS: SPI CS (can be any Arduino Dx pin to cover multiple devices on the same SPI bus) - - FXLS8974_INT: interrupt line (optional) - -### RTOS - -The RTOS software layer provides a CMSIS-RTOS2 compliant RTOS. Various implementations can be used; currently RTX and FreeRTOS is provided as software layer. Some RTOS functionality might be used by peripheral drivers, the PSA interface or the application itself. When present, the RTOS is initialized and started in the [Board](#board) software layer. - -> **Note:** -> -> The *CMSIS-RTOS2 connect name* may be also provided by the application software. For example, the AWS IoT stack implements FreeRTOS and also exposes CMSIS-RTOS2 API as the underlying driver interfaces may require it. - -### Socket - -Provides an [IoT Socket](https://github.com/MDK-Packs/IoT_Socket) compliant socket. Various implementation can be used. - -Currently layers are available for: - -- WiFi using CMSIS-Driver with built-in TCP/IP stack. -- TCP/IP middleware over Ethernet (using Ethernet CMSIS-Driver). -- VSocket over Arm Virtual Hardware (AVH). - -The IoT Socket is initialized and started from the application by calling the following function: - -``` c -extern int32_t socket_startup (void); -``` - -### Stream - -Provides middleware for data streaming in a format that is consumed by DSP or ML algorithms. Proposals for these interfaces will be provided. - -The data streaming interfaces relate to: - -- [SDS-Framework](https://github.com/Arm-software/SDS-Framework) for recording, analyzing, and playback of data streams. -- [CMSIS-DSP compute graph](https://github.com/ARM-software/CMSIS-DSP) that allows to optimize data flows between DSP and ML algorithms. - -## Working with Layers - -The following section explains how to operate with layers. It uses the projects: - -- [AWS_MQTT_MutualAuth_SW_Framework](https://github.com/Open-CMSIS-Pack/AWS_MQTT_MutualAuth_SW_Framework/tree/develop) - currently the branch `develop`. When cloning this project ensure that you also get the git sub-module `framework`. -- [RefApp-Framework](https://github.com/Open-CMSIS-Pack/RefApp-Framework) contains the software layers that are used by various projects. It is represented by the git sub-module `framework` in the example above. - -[AWS_MQTT_MutualAuth_SW_Framework](https://github.com/Open-CMSIS-Pack/AWS_MQTT_MutualAuth_SW_Framework/tree/develop) is a AWS Cloud connector project that is defined in `Demo.csolution.yml`. The directory `framework` contains various [software layers](#software-layers) that are compatible with this application. - -### Install missing software packs - -Before - -```text -csolution list packs -s Demo.csolution.yml -m >packs.txt -cpackget update-index // optional to ensure that pack index is up-to-date -cpackget add -f packs.txt -``` - -### Compile application - -To generate the application variants enter: - -``` txt -csolution convert -s Demo.csolution.yml -``` - -Despite the fact that currently warnings are generated, it creates the following projects: - -``` txt -./AWS_MQTT_MutualAuth_SW_Framework/Demo.Debug+AVH_MPS3_Corstone-300.cprj - info csolution: file generated successfully -./AWS_MQTT_MutualAuth_SW_Framework/Demo.Debug+AVH_MPS3_Corstone-310.cprj - info csolution: file generated successfully -./AWS_MQTT_MutualAuth_SW_Framework/Demo.Debug+B-U585I-IOT02A.cprj - info csolution: file generated successfully -./AWS_MQTT_MutualAuth_SW_Framework/Demo.Debug+IMXRT1050-EVKB.cprj - info csolution: file generated successfully -./AWS_MQTT_MutualAuth_SW_Framework/Demo.Debug+IMXRT1050-EVKB_DA16200.cprj - info csolution: file generated successfully -./AWS_MQTT_MutualAuth_SW_Framework/Demo.Debug+IMXRT1050-EVKB_WizFi360.cprj - info csolution: file generated successfully -./AWS_MQTT_MutualAuth_SW_Framework/Demo.Release+AVH_MPS3_Corstone-300.cprj - info csolution: file generated successfully -./AWS_MQTT_MutualAuth_SW_Framework/Demo.Release+AVH_MPS3_Corstone-310.cprj - info csolution: file generated successfully -./AWS_MQTT_MutualAuth_SW_Framework/Demo.Release+B-U585I-IOT02A.cprj - info csolution: file generated successfully -./AWS_MQTT_MutualAuth_SW_Framework/Demo.Release+IMXRT1050-EVKB.cprj - info csolution: file generated successfully -./AWS_MQTT_MutualAuth_SW_Framework/Demo.Release+IMXRT1050-EVKB_DA16200.cprj - info csolution: file generated successfully -./AWS_MQTT_MutualAuth_SW_Framework/Demo.Release+IMXRT1050-EVKB_WizFi360.cprj - info csolution: file generated successfully -``` - -Each of these projects can be translated using: - -```txt -cbuild "Demo.Debug+AVH_MPS3_Corstone-300.cprj" -``` - -### Add new targets - -To add a new target, add in `Demo.csolution.yml` under `target-types:` a new type as shown below: - -```txt - - type: test - device: NXP::MIMXRT1052DVL6B -``` - -Compatible layers can be listed using the command: - -```txt -csolution list layers -s Demo.csolution.yml -c Demo.Release+test verbose -L ./framework -l all - -./AWS_MQTT_MutualAuth_SW_Framework/framework/layer/Board/B-U585I-IOT02A/IoT/Board.clayer.yml (layer type: Board) -./AWS_MQTT_MutualAuth_SW_Framework/framework/layer/Shield/WiFi/Inventek_ISMART43362-E/Shield.clayer.yml (layer type: Shield) -./AWS_MQTT_MutualAuth_SW_Framework/framework/layer/Shield/WiFi/Sparkfun_DA16200/Shield.clayer.yml (layer type: Shield) -./AWS_MQTT_MutualAuth_SW_Framework/framework/layer/Shield/WiFi/Sparkfun_ESP8266/Shield.clayer.yml (layer type: Shield) -./AWS_MQTT_MutualAuth_SW_Framework/framework/layer/Shield/WiFi/WizNet_WizFi360-EVB/Shield.clayer.yml (layer type: Shield) -./AWS_MQTT_MutualAuth_SW_Framework/framework/layer/Socket/WiFi/Socket.clayer.yml (layer type: Socket) -``` - -Each of the different layers is working with the new added target. - -### Known problems - -- Not every target requires a `Shield`, but `csolution` complains about a missing $Shield-Layer$. csolution should not search for additional layers when all `consumed connections` are `provided` the the layers already. -- The board `B-U585I-IOT02A` as onboard WiFi and would not work with a `Shield`. The tool does not raise a conflict when the same `connection:` is `provided` multiple times, - nor does check that a Shiel layer is not required. - -### Finalize Workflow - -- The current workflow needs review and improvements in the usability. -- Layers should be provided in packs, the workflow with packs has not been validated yet. +Document moved to [CMSIS-Toolbox](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/build-overview.md#reference-application-framework) diff --git a/tools/projmgr/docs/Manual/Simplified Generator Proposal.md b/tools/projmgr/docs/Manual/Simplified Generator Proposal.md new file mode 100644 index 000000000..f77f2fc54 --- /dev/null +++ b/tools/projmgr/docs/Manual/Simplified Generator Proposal.md @@ -0,0 +1,140 @@ +# Generator Workflow (Proposal) - Revised 4. Sept 2023 + + +- [Generator Workflow (Proposal) - Revised 4. Sept 2023](#generator-workflow-proposal---revised-4-sept-2023) + - [User Steps](#user-steps) + - [Generator Interface](#generator-interface) + - [Project Scenarios](#project-scenarios) + - [Single-Core](#single-core) + - [Multi-Core or TrustZone](#multi-core-or-trustzone) + - [Global Generator Registry](#global-generator-registry) + - [Impact to PDSC files and Packs](#impact-to-pdsc-files-and-packs) + - [Other](#other) + +>**NOTE:** +> +> This document is a refined [Generator Proposal](https://github.com/Open-CMSIS-Pack/devtools/blob/main/tools/projmgr/docs/Manual/Generator%20\(Proposal\).md). It focuses on existing generators such as STM32CubeMX. + +## User Steps + +The user steps for creating a `csolution` based application with a Generator are: + +- Create the `*.csolution.yml` container that refers the projects and selects `device:` or `board:` (by using `target-types:`) +- Create `*.cproject.yml` files that are referred by the `*.csolution.yml` container. +- Add `components:` and/or `layers:` to the `*.cproject.yml` file +- For components that have a **GenID**, run the related generator. + +Typically generators are used to: + +- Configure device and/or board settings, for example clock configuration or pinout. +- Add and configure software drivers, for example for UART, SPI, or I/O ports. +- Configure parameters of an algorithm, for example DSP filter design or motor control parameters. + +## Generator Interface + +The diagram below shows how the Generator is integrated into the CMSIS-Build tools. The data flow is exemplified on STM32CubeMX (or just CubeMX). The information about the project is delivered in `*.cbuild-gen-idx.yml` and `.cbuild-gen.yml` files. This information provides CubeMX with the project context, such as selected board or device, and CPU mode such as TrustZone disabled/enabled. + +![Generator Information](./images/Generator-Information.png "Generator Information") + +CubeMX/CubeMXBridge generates: + +- `*.ioc` CubeMX project file with current project settings +- `*.c/.h` source files, i.e. for interfacing with drivers +- `cgen.yml` which provides the data for project import into the csolution build process. + +> **Note:** As CubeMX itself does not have the required interfaces to the csolution project format, there is a utility `CubeMX Bridge` that converts the `*.cbuild-gen*.yml` files into command-line options for CubeMX. It also generates the `cgen.yml` based on the information generated by CubeMX. + +## Project Scenarios + +The following is an analysis of the different project scenarios, again exemplified with STM32CubeMX. +Note that the directory structure can be controlled already using the key [`generators:`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/YML-Input-Format.md#generators). Hence the following is just a proposal for default locations. + +### Single-Core + +All generator files belong to only one `cproject.yml` or `clayer.yml` file. A potential default directory structure is: + +- When all components with **GenID** are in `cproject.yml`. + - Base Directory: `$ProjectDir()$/generated.$GenID$` + - `cgen.yml` file: `$ProjectDir()$/RTE/Device/$Dname$` +- When all components with **GenID** are in `clayer.yml`: + - Base Directory: `$LayerDir()$/generated.$GenID$` + - `cgen.yml` file: `$LayerDir()$/RTE/Device/$Dname$` + +### Multi-Core or TrustZone + +Generator files belong to `csolution.yml` or to a `clayer-idx.yml` file. + +- When all components with **GenID** are in `cproject.yml` files: + - Base Directory: `$SolutionDir()$/generated.$GenID$` + - multiple `cgen.yml` files: `$ProjectDir()$/RTE/Device/$Dname$` +- When all components with **GenID** are in `clayer.yml`: + - Base Directory: `$LayerIdxDir()$/generated.$GenID$` + - multiple `cgen.yml` files: `$LayerDir()$/RTE/Device/$Dname$` + +> **Notes:** +> +> - New Access Sequences are introduced: `$GenID$`, `$LayerDir()$`, `$LayerIdxDir()$`. +> - When components with **GenID** are intermixed (some in `*.clayer.yml`, some in `*.cproject.yml`) an error is displayed with the request to use explicit [`generators:`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/YML-Input-Format.md#generators) settings. + +```txt +error: requires explicit generator base directory, use key `generator:` +``` + +## Global Generator Registry + +As there is typically only one Generator of type **GenID** installed, a global registry could be introduced. + +- In CMSIS-Toolbox `./etc` directory either a global file `generators.yml` or a file `$GenID$.generator.yml could be introduced that registers the generators. +- In CMSIS-Toolbox `./bin` directory the 'Bridge programs' for CubeMX and potentially MCUxpresso could be added. + +**Potential format of generators.yml:** + +```yml +generators: + - generator: CubeMX # potentially with version added by `@` notation + download-url: https://www.st.com/en/development-tools/stm32cubemx.html + exe: ../bin/CubeMX2cgen + args: + - arg: + - arg: + - arg: + dirs: + - generator-type: single # for single-core project + work-dir: $GenBaseDir()$/generated.STM32CubeMX + gen-dir: ./RTE/Device/$Dname$ + - generator-type: multi # for multi-core or TrustZone enabled projects + work-dir: $GenBaseDir()$/generated.STM32CubeMX + gen-dir: ./RTE/Device/$Dname$ + - generator: MCUxpresso + : + - generator: Renesas... +``` + +## Impact to PDSC files and Packs + +The following changes might be implemented in the PDSC files: + +- Element [``](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_generators_pg.html) is optional as there is a [global registration of generators](#global-generator-registry). +- Element [``](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_components_pg.html#element_component) + - Attribute `generator` checks if a `cgen.yml` or `*.gpdsc` file is present. + - Add new attribute `generator-type` with option `single` (default) and `multi` to define the [project scenarios](Project Scenarios). As a `` can have conditions, it is possible to use a `single` structure when for example TrustZone is disabled. + - Allow that a `` with a `` can be empty (has no source files). + +**Example component for CubeMX:** + +```xml + + Run STM32CubeMX for device configuration + +``` + +The proposed changes allow to use: + +- Standard STM32CubeMX device and board firmware packs. Except adding the STM32CubeMX component shown above, there is **no special work** in the Packs required. Specifically the reformatting of the STM32CubeMX firmware in components is not longer required. +- It is possible to start from a `device` or `board` which utilizes the feature set of STM32CubeMX. + +## Other + +- `cgen.yml` format needs formal definition. Starting proposal is to use `*.clayer.yml`. Extensions are possible as discussed in [637](https://github.com/Open-CMSIS-Pack/devtools/issues/637). However suggestion is to implement only the currently used feature set. +- It might be required to make the location of `cgen.yml` configurable to support situations where the same device is used in multiple `target-types:` with different configurations. +- Here are [Example Projects](https://github.com/DavidLesnjak/cgen_mockup) that use this proposal. diff --git a/tools/projmgr/docs/Manual/YML-CBuild-Format.md b/tools/projmgr/docs/Manual/YML-CBuild-Format.md index e5f3e5400..3a9be18c0 100644 --- a/tools/projmgr/docs/Manual/YML-CBuild-Format.md +++ b/tools/projmgr/docs/Manual/YML-CBuild-Format.md @@ -1,445 +1,3 @@ -# YAML CBuild Format - - +# Note -The following chapter explains the YAML CBuild format that describes how to build a complete application. - -**Table of Contents** - -- [YAML CBuild Format](#yaml-cbuild-format) - - [CBuild Output Files](#cbuild-output-files) - - [Directory Structure](#directory-structure) - - [File Structure of `*.cbuild-idx.yml`](#file-structure-of-cbuild-idxyml) - - [File Structure of `*.cbuild.yml`](#file-structure-of-cbuildyml) - - [CBuild-specific Nodes](#cbuild-specific-nodes) - - [`licenses:`](#licenses) - - [`cprojects:`](#cprojects) - - [`context-set:`](#context-set) - - [`packs:`](#packs) - - [`generators:`](#generators) - - [Source File Management](#source-file-management) - - [`linker:`](#linker) - - [`groups:`](#groups) - - [`files:` of a group](#files-of-a-group) - - [`components:`](#components) - - [`files:` of a component](#files-of-a-component) - - [`constructed-files:`](#constructed-files) - - [`messages:`](#messages) - -## CBuild Output Files - -The `*.cbuild-idx.yml` and `*.cbuild.yml` output files are generated by the `csolution` utility and contain information on how to build the complete application. - -File | Description -:-------------------|:---------------------- -`*.cbuild-idx.yml` | Index file of all `*.cbuild.yml` build descriptions; contains also overall information for the application. -`*.cbuild.yml` | Build description of a single [`*.cproject.yml`](YML-Input-Format.md#project-file-structure) input file. - -The `*.cbuild.yml` output file has the following usage: - -- It contains all information for the build step of a project that is part of an application. -- As it contains information about all software packs used including version information, this file can be used as `lock-file` to ensure that subsequent runs of `csolution` use the very same software packs. -- It can be used as input file for a generator as it contains explicit information about source files and avoids the complexity of a pack data management at the generator level. - -### Directory Structure - -As `csolution` based projects should be portable across different host computers, **relative file references** are used within the directory structure. - -- All file references use relative paths to the base directory of the related `*.yml` file. Files that are within the file structure of the `csolution` base directory are also referenced using relative paths, i.e. `../layers/layer1/source-file1.c`. - -> ToDo: Question: when are relative paths used to the base directory and when are absolute paths used? - -- Files that are located in the [CMSIS-Pack root directory](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/installation.md#environment-variables) are prefixed with %CMSIS_PACK_ROOT%. - -- Files outside of the directory structure of `csolution` based application use absolute paths. If absolute paths are used, a `warning` is issued in the `*.cbuild-idx.yml` file. - -A typical directory structure of a `csolution` based application that uses common layers source files is shown below. - -```yml -📦 # csolution base directory - ┣ myapp.csolution.yml - ┣ myapp.cbuild-idx.yml - ┣ 📂 project1 - ┃ ┣ mypro1.cproject.yml - ┃ ┣ mypro1.cbuild.yml # file references are relative to directory project1 - ┣ 📂 project2 - ┃ ┣ mypro2.cproject.yml - ┃ ┣ mypro2.cbuild.yml # file references are relative to directory project2 - ┣ 📂 layer -``` - -### File Structure of `*.cbuild-idx.yml` - -`build-idx:` | Content -:--------------------------------------------------|:------------------------------------ -   `generated-by:` | Reference to csolution tool along with version information used to generate this application. -   `cdefault:` | Relative path and name of the [`*.cdefault.yml`](YML-Input-Format.md#default) input file used to generate this application. -   `csolution:` | Relative path and name of the [`*.csolution.yml`](YML-Input-Format.md#solution) input file used to generate this application. -   [`cprojects:`](#cprojects) | List of `*.cproject.yml` and `*.clayer.yml` input files used to generate this application. -   [`licenses:`](#licenses) | ToDo: List of software license agreements used by this application. -   `cbuilds:` | List of `*.cbuild.yml` output files that are generated for this application. -   [`context-set:`](#context-set) | Selected context that is generated for this application. - -**Example:** - -```yml -build-idx: - generated-by: csolution 1.4.0 - cdefault: HelloWorld.cdefault.yml - csolution: HelloWorld.csolution.yml - cprojects: - - cproject: cm0plus/HelloWorld_cm0plus.cproject.yml - - cproject: cm4/HelloWorld_cm4.cproject.yml - - licenses: # ToDo: all licenses used in the projects - - cbuilds: - - cbuild: cm0plus/HelloWorld_cm0plus.Debug+FRDM-K32L3A6.cbuild.yml - - cbuild: cm0plus/HelloWorld_cm0plus.Release+FRDM-K32L3A6.cbuild.yml - - cbuild: cm4/HelloWorld_cm4.Debug+FRDM-K32L3A6.cbuild.yml - - cbuild: cm4/HelloWorld_cm4.Release+FRDM-K32L3A6.cbuild.yml -``` - -### File Structure of `*.cbuild.yml` - -The `cbuild.yml` file is structured into several sections. The top-level structure is outlined below. - -`build:` | Content -:--------------------------------------------------|:------------------------------------ -   `generated-by:` | Reference to csolution tool along with version information used to generate this application. -   `context:` | Project [context](YML-Input-Format.md#context-name-conventions) of this build description. -   `compiler:` | [Compiler toolchain](YML-Input-Format.md#compiler) used for code generation. -   `board:` | [Board name](YML-Input-Format.md#board) used for this context. -   `device:` | [Device name](YML-Input-Format.md#device) with processor core selection used in this project context. -   `processor:` | List of [processor attributes](YML-Input-Format.md#processor) used in this project context. -   [`packs:`](#packs) | List of software [packs](#packs) along with path information used to generate this project context. -   `optimize:` | Generic [optimize](YML-Input-Format.md#optimize) level for code generation. -   `debug:` | Global control the generation of [debug](YML-Input-Format.md#debug) information. -   `warnings:` | Global control [warning](YML-Input-Format.md#warnings) level for compiler diagnostics. -   `misc:` | Global control of [miscellaneous](YML-Input-Format.md#misc) literal tool-specific controls. -   `define:` | List of global [define](YML-Input-Format.md#define) symbol settings. -   `add-path:` | List of global [include path](YML-Input-Format.md#add-path) settings. -   `output-type:` | Select the [output type](YML-Input-Format.md#output-type) (exe or lib) for this project context. -   `output-dirs:` | Specifies the [directories](YML-Input-Format.md#output-dirs) used to generate the output files. -   `linker:` | Specifies the [linker script processing](#linker) used to generate the output files. -   [`components:`](#components) | List of software components used. -   [`groups:`](#groups) | List of source file groups along with source files. -   [`constructed-files:`](#constructed-files) | List of files that are generated by RTE management of `csolution` tool. -   [`messages:`](#messages) | ToDo: List of messages (errors, warnings, etc.) that apply to this project context. - -**Example:** - -```yml -build: - context: HelloWorld_cm0plus.Debug+FRDM-K32L3A6 - compiler: AC6 - device: K32L3A60VPJ1A:cm0plus - processor: - fpu: off - endian: little - trustzone: non-secure - packs: - - pack: ARM::CMSIS@5.9.0 - path: ${CMSIS_PACK_ROOT}/ARM/CMSIS/5.9.0 - - pack: NXP::K32L3A60_DFP@15.0.0 - path: ${CMSIS_PACK_ROOT}/NXP/K32L3A60_DFP/15.0.0 - optimize: none - debug: on - misc: - C: - - -std=c99 - - -fno-builtin - CPP: - - -fno-builtin - Link: - - --diag_suppress 6314 - - --entry=Reset_Handler - define: - - CPU_K32L3A60VPJ1A_cm0plus - - MCMGR_HANDLE_EXCEPTIONS=1 - : - - _RTE_ - add-path: - - ../middleware/multicore/mcmgr/src - - RTE/Board_Support/K32L3A60VPJ1A_cm0plus - - RTE/_HelloWorld_cm0plus.Debug_FRDM-K32L3A6 - - ${CMSIS_PACK_ROOT}/ARM/CMSIS/5.9.0/CMSIS/Core/Include - - ${CMSIS_PACK_ROOT}/NXP/K32L3A60_DFP/15.0.0 - : - output-type: exe - output-dirs: - gendir: generated - intdir: ../tmp/HelloWorld_cm0plus/FRDM-K32L3A6/Debug - outdir: ../out/HelloWorld_cm0plus/FRDM-K32L3A6/Debug - rtedir: RTE - components: - - component: ARM::CMSIS:CORE@5.6.0 - condition: ARMv6_7_8-M Device - from-pack: ARM::CMSIS@5.9.0 - selected-by: ARM::CMSIS:CORE - - component: NXP::Device:CMSIS:K32L3A60_system@1.0.0 - condition: device.K32L3A60_AND_device.K32L3A60_CMSIS - from-pack: NXP::K32L3A60_DFP@15.0.0 - selected-by: NXP::Device:CMSIS:K32L3A60_system - files: - - file: ${CMSIS_PACK_ROOT}/NXP/K32L3A60_DFP/15.0.0/system_K32L3A60_cm0plus.c - category: sourceC - - component: NXP::Device:SDK Drivers:clock@2.2.1 - condition: device.K32L3A60_AND_driver.common - from-pack: NXP::K32L3A60_DFP@15.0.0 - selected-by: NXP::Device:SDK Drivers:clock - files: - - file: ${CMSIS_PACK_ROOT}/NXP/K32L3A60_DFP/15.0.0/drivers/fsl_clock.c - category: sourceC - - component: NXP::Device:SDK Drivers:common@2.3.2 - condition: device.K32L3A60_AND_device.K32L3A60_CMSIS_AND_driver.clock - from-pack: NXP::K32L3A60_DFP@15.0.0 - selected-by: NXP::Device:SDK Drivers:common - files: - - file: ${CMSIS_PACK_ROOT}/NXP/K32L3A60_DFP/15.0.0/drivers/fsl_common.c - category: sourceC - - file: ${CMSIS_PACK_ROOT}/NXP/K32L3A60_DFP/15.0.0/drivers/fsl_common_arm.c - category: sourceC - : - groups: - - group: Application - files: - - file: ./hello_world_core1.c - category: sourceC - - file: ./RTE/Device/K32L3A60VPJ1A_cm0plus/K32L3A60xxx_cm0plus_flash.scf - category: linkerScript - - group: Middleware - files: - - file: ../middleware/multicore/mcmgr/src/mcmgr.c - category: sourceC - : - constructed-files: - - file: RTE/_HelloWorld_cm0plus.Debug_FRDM-K32L3A6/RTE_Components.h - category: header -``` - -## CBuild-specific Nodes - -### `licenses:` - -> ToDo - -The `licenses:` node collects the software licenses from all components and software packs that are used in a `csolution` based software project. - -`licenses:` | Content -:------------------------------------------------------------------|:------------------------------------ -`- license:` | SPDX-name of the license, `` to indicate a dedicated license agreement, or ``. -  `license-agreement:` | In cased of `` a link to the license agreement. -   [`packs:`] | List of software packs that use this license. -   [`components:`] | List of software components that use this license. - -**Example:** - -```yml -licenses: - - license: Apache-2.0 - packs: - - pack: ARM::CMSIS@5.9.0 - - pack: ARM::mbedTLS@1.7.0 - components: - - component: ARM::CMSIS:RTOS2:FreeRTOS&Cortex-M - - - license: - packs: - - pack: ARM::CMSIS-Driver@2.7.2 - - - license: - license-agreement: %CMSIS_PACK_ROOT%/Keil/STM32U5xx_DFP/2.0.0/Package_license.md - packs: - - pack: Keil::STM32U5xx_DFP@2.0.0 -``` - -### `cprojects:` - -The `cprojects:` node lists all `*.cproject.yml` input files along with `*.clayer.yml` files that are used to compose the application. - -`cprojects:` | Content -:------------------------------------------------------------------|:------------------------------------ -`- cproject:` | Relative path and name of a [`*.cproject.yml`](YML-Input-Format.md#project) input file. -  `clayers:` | List of [`*.clayer.yml`](YML-Input-Format.md#layer) input files used by this `*.cproject.yml` file. - -**Example:** - -```yml - cprojects: - - cproject: AWS_MQTT_MutualAuth_SW_Framework/Demo.cproject.yml - clayers: - - clayer: AWS_MQTT_MutualAuth_SW_Framework/Socket/FreeRTOS+TCP/Socket.clayer.yml - - clayer: AWS_MQTT_MutualAuth_SW_Framework/Socket/WiFi/Socket.clayer.yml - - clayer: AWS_MQTT_MutualAuth_SW_Framework/Socket/VSocket/Socket.clayer.yml - : -``` - -### `context-set:` - -**ToDo: Proposal (would replace cbuild: node)** - -The `context-set:` node contains a list of generated files. Note that this depends on the `--context` parameters that are passed to `csolution`. - -The example below shows the content of the `DualCore` example with the following `csolution` invocation: - -```txt -csolution convert HelloWorld.csolution.yml --context HelloWorld_cm0plus.Debug+FRDM-K32L3A6 --context -HelloWorld_cm4.Release+FRDM-K32L3A6 -``` - -```yml - context-set: - - context: HelloWorld_cm4.Release+FRDM-K32L3A6 - bin: ./out/FRDM-K32L3A6/HelloWorld_cm4.bin - hex: ./out/FRDM-K32L3A6/HelloWorld_cm4.hex - elf: ./out/FRDM-K32L3A6/HelloWorld_cm4.axf - map: ./out/FRDM-K32L3A6/HelloWorld_cm4.map - log: ./out/FRDM-K32L3A6/HelloWorld_cm4.Release+FRDM-K32L3A6.log - - context: HelloWorld_cm0plus.Debug+FRDM-K32L3A6 - bin: ./out/FRDM-K32L3A6/HelloWorld_cm0plus.bin - hex: ./out/FRDM-K32L3A6/HelloWorld_cm0plus.hex - elf: ./out/FRDM-K32L3A6/HelloWorld_cm0plus.axf - map: ./out/FRDM-K32L3A6/HelloWorld_cm0plus.map - log: ./out/FRDM-K32L3A6/HelloWorld_cm0plus.Debug+FRDM-K32L3A6.log -``` - -### `packs:` - -The `packs:` node is the start of a pack list that is used for the project context. - -`packs:` | Content -:-----------------------------------------------------|:------------------------------------ -`- pack:` | Explicit pack specification with exact version information used. -   `path:` | Path name that stores the software pack (see note). - -> **Note:** -> ->Packs that are located in the [CMSIS-Pack root directory](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/installation.md#environment-variables) are prefixed with %CMSIS_PACK_ROOT%. - -**Example:** - -```yml - packs: - - pack: ARM::CMSIS-FreeRTOS@10.4.6 - path: ${CMSIS_PACK_ROOT}/ARM/CMSIS-FreeRTOS/10.4.6 - - pack: ARM::CMSIS@5.9.0 - path: ${CMSIS_PACK_ROOT}/ARM/CMSIS/5.9.0 - : - - pack: MDK-Packs::IoT_Socket@1.3.1 - path: ../IoT_Socket -``` - -### `generators:` - -The `generators:` node contains information for calling a generator. - -`generators:` | Content -:-------------------------------------------------------------------|:------------------------------------ -`- generator:` | Section for a specific generator. -   [`path:`](YML-Input-Format.md#generators) | Path name for storing the files generated. -   `gdpsc:` | File name of the *.GDPSC file that stores the information in `path:`. -   `command:` | Section for invoking the generator on different Host operating systems. - -**Example:** - -```yml - generators: - - generator: STM32CubeMX - path: RTE/Device - gpdsc: RTE/Device/STM32L475VGTx/FrameworkCubeMX.gpdsc - command: - win: - file: ${CMSIS_PACK_ROOT}/Keil/STM32L4xx_DFP/2.6.1/MDK/CubeMX/STM32CubeMxLauncher.exe - arguments: - - STM32L475VGTx - - ../../Release+STM32L4.cprj - - ${CMSIS_PACK_ROOT}/Keil/STM32L4xx_DFP/2.6.1 -``` - -## Source File Management - -Keyword | Description -:----------------|:------------------------------------ -`groups:` | Start of a list that adds source groups and files. -`components:` | Start of a list that adds software components. - -### `linker:` - -`linker:` | Content -:-------------------------------------------------|:-------------------------------- -`- regions:` | Path and file name of `regions_.h`, used to generate a Linker Script via pre-processor. -`- script:` | Path and file name of the Linker Script template that is pre-processed. -[`- define:`](YML-Input-Format.md#define) | Define symbol settings for the linker script file preprocessor. - -### `groups:` - -`groups:` | Content -:--------------------------------------------------------|:------------------------------------ -`- group:` | Name of the group. -   [`optimize:`](YML-Input-Format.md#optimize) | Optimize level for code generation. -   [`debug:`](YML-Input-Format.md#debug) | Generation of debug information. -   [`warnings:`](YML-Input-Format.md#warnings) | Control generation of compiler diagnostics. -   [`define:`](YML-Input-Format.md#define) | Define symbol settings for code generation. -   [`add-path:`](YML-Input-Format.md#add-path) | Additional include file paths. -   [`misc:`](YML-Input-Format.md#misc) | Literal tool-specific controls. -   [`groups:`](#groups) | Start a nested list of groups. -   [`files:`](#files-of-a-group) | List of files that belong to a group - -### `files:` of a group - -`files:` | Content -:--------------------------------------------------------|:------------------------------------ -`- file:` | Name of the file. -   [`category:`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_components_pg.html#FileCategoryEnum) | File category according Open-CMSIS-Pack specification -   [`optimize:`](YML-Input-Format.md#optimize) | Optimize level for code generation. -   [`debug:`](YML-Input-Format.md#debug) | Generation of debug information. -   [`warnings:`](YML-Input-Format.md#warnings) | Control generation of compiler diagnostics. -   [`define:`](YML-Input-Format.md#define) | Define symbol settings for code generation. -   [`add-path:`](YML-Input-Format.md#add-path) | Additional include file paths. -   [`misc:`](YML-Input-Format.md#misc) | Literal tool-specific controls. - -### `components:` - -`components:` | Content -:--------------------------------------------------------|:------------------------------------ -`- component:` | Name of the software component. -   [`condition:`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_conditions_pg.html#element_condition) | Reference to the condition ID of the software pack that triggered inclusion of this component. -   `from-pack:` | Pack that defines this component. -   `selected-by:` | The original component name used in `cproject/clayer.YML`. -   [`optimize:`](YML-Input-Format.md#optimize) | Optimize level for code generation. -   [`debug:`](YML-Input-Format.md#debug) | Generation of debug information. -   [`warnings:`](YML-Input-Format.md#warnings) | Control generation of compiler diagnostics. -   [`define:`](YML-Input-Format.md#define) | Define symbol settings for code generation. -   [`add-path:`](YML-Input-Format.md#add-path) | Additional include file paths. -   [`misc:`](YML-Input-Format.md#misc) | Literal tool-specific controls. -   `instances:` | Configure component instances. -   [`generator:`] | Generator ID for components that are configurable via a generator. -   [`files:`](#files-of-a-component) | List of files that belong to this component. - -### `files:` of a component - -`files:` | Content -:--------------------------------------------------------|:------------------------------------ -`- file:` | Name and path to the file. -   [`category:`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_components_pg.html#FileCategoryEnum) | File category according Open-CMSIS-Pack specification -   [`attr:`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_components_pg.html#FileAttributeEnum) | File category according Open-CMSIS-Pack specification -   [`condition:`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_conditions_pg.html#element_condition) | Reference to the condition ID of the software pack that triggered inclusion of this file. - -## `constructed-files:` - -A list of files that are generated by the RTE management of the `csolution` tool. - -`constructed-files:` | Content -:--------------------------------------------------------|:------------------------------------ -`- file:` | Name and path to the file. -   [`category:`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_components_pg.html#FileCategoryEnum) | File category according Open-CMSIS-Pack specification - -### `messages:` - -> ToDo: Messages that apply to this project context. - -`messages:` | Content -:--------------------------------------------------------|:------------------------------------ -`- error:` | Error message -`- warning:` | Warning message -`- info:` | Info message +Document moved to [CMSIS-Toolbox](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/YML-CBuild-Format.md) diff --git a/tools/projmgr/docs/Manual/YML-Input-Format.md b/tools/projmgr/docs/Manual/YML-Input-Format.md index e86a052f3..5499bdb3d 100644 --- a/tools/projmgr/docs/Manual/YML-Input-Format.md +++ b/tools/projmgr/docs/Manual/YML-Input-Format.md @@ -1,2269 +1,3 @@ -# YAML Input Format +# Note - - - - -The following chapter explains the YAML format that is used to describe the `*.yml` input files for the **CSolution** -Project Manager. - -**Table of Contents** - -- [YAML Input Format](#yaml-input-format) - - [Name Conventions](#name-conventions) - - [Filename Extensions](#filename-extensions) - - [`pack:` Name Conventions](#pack-name-conventions) - - [`component:` Name Conventions](#component-name-conventions) - - [`device:` Name Conventions](#device-name-conventions) - - [`board:` Name Conventions](#board-name-conventions) - - [`context:` Name Conventions](#context-name-conventions) - - [Access Sequences](#access-sequences) - - [Variables](#variables) - - [Order of List Nodes](#order-of-list-nodes) - - [Project File Structure](#project-file-structure) - - [`default:`](#default) - - [`solution:`](#solution) - - [`project:`](#project) - - [`layer:`](#layer) - - [Directory Control](#directory-control) - - [`output-dirs:`](#output-dirs) - - [`generators:`](#generators) - - [`generators: - options:`](#generators---options) - - [`rte:`](#rte) - - [Toolchain Options](#toolchain-options) - - [`compiler:`](#compiler) - - [`linker:`](#linker) - - [`output:`](#output) - - [Translation Control](#translation-control) - - [`language-C:`](#language-c) - - [`language-CPP:`](#language-cpp) - - [`optimize:`](#optimize) - - [`debug:`](#debug) - - [`warnings:`](#warnings) - - [`define:`](#define) - - [`undefine:`](#undefine) - - [`add-path:`](#add-path) - - [`del-path:`](#del-path) - - [`misc:`](#misc) - - [Project Setups](#project-setups) - - [`setups:`](#setups) - - [Pack Selection](#pack-selection) - - [`packs:`](#packs) - - [`pack:`](#pack) - - [Target Selection](#target-selection) - - [`board:`](#board) - - [`device:`](#device) - - [Processor Attributes](#processor-attributes) - - [`processor:`](#processor) - - [Context](#context) - - [`target-types:`](#target-types) - - [`build-types:`](#build-types) - - [`context-map:`](#context-map) - - [Conditional Build](#conditional-build) - - [`for-compiler:`](#for-compiler) - - [`for-context:`](#for-context) - - [`not-for-context:`](#not-for-context) - - [Context List](#context-list) - - [Usage](#usage) - - [Multiple Projects](#multiple-projects) - - [`projects:`](#projects) - - [Source File Management](#source-file-management) - - [`groups:`](#groups) - - [`files:`](#files) - - [`layers:`](#layers) - - [`layer:` - `type:`](#layer---type) - - [`components:`](#components) - - [`instances:`](#instances) - - [Pre/Post build steps](#prepost-build-steps) - - [`execute:`](#execute) - - [`connections:`](#connections) - - [`connect:`](#connect) - - [`set:`](#set) - - [`provides:`](#provides) - - [`consumes:`](#consumes) - - [Example: Board](#example-board) - - [Example: Simple Project](#example-simple-project) - - [Example: Sensor Shield](#example-sensor-shield) - - [Generator (Proposal)](#generator-proposal) - - [Workflow assumptions](#workflow-assumptions) - - [Steps for component selection and configuration](#steps-for-component-selection-and-configuration) - - [Enhance Usability](#enhance-usability) - - [Workflow](#workflow) - - [Example Content of `*.cgen.json` (in this case `STM32CubeMX.cgen.json`)](#example-content-of-cgenjson-in-this-case-stm32cubemxcgenjson) - - [Changes to the \*.GPDSC file](#changes-to-the-gpdsc-file) - - [Changes to the \*.PDSC file](#changes-to-the-pdsc-file) - -## Name Conventions - -### Filename Extensions - -The **csolution - CMSIS Project Manager** recognizes the [categories](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_components_pg.html#FileCategoryEnum) of [files](#files) based on the filename extension in the YAML input files as shown in the table below. - -File Extension | [Category](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_components_pg.html#FileCategoryEnum) | Description -:--------------------------------------------|:-------------|:--------------------- -`.c`, `.C` | sourceC | C source file -`.cpp`, `.c++`, `.C++`, `.cxx`, `.cc`, `.CC` | sourceCpp | C++ source file -`.h`,`.hpp` | header | Header file -`.asm`, `.s`, `.S` | sourceAsm | Assembly source file -`.ld`, `.scf`, `.sct`, `.icf` | linkerScript | Linker Script file -`.a`, `.lib` | library | Library file -`.o` | object | Object file -`.txt`, `.md`, `.pdf`, `.htm`, `.html` | doc | Documentation - -### `pack:` Name Conventions - -The **csolution - CMSIS Project Manager** uses the following syntax to specify the `pack:` names in the `*.yml` files. - -```yml -vendor [:: pack-name [@[~ | >=] version] ] -``` - -Element | | Description -:------------|--------------|:--------------------- -`vendor` | **Required** | Vendor name of the software pack. -`pack-name` | Optional | Name of the software pack; wildcards (\*, ?) can be used. -`version` | Optional | Version number of the software pack, with `@1.2.3` that must exactly match, `@~1.2`/`@~1` that matches with semantic versioning, or `@>=1.2.3` that allows any version higher or equal. - -> **Note:** -> -> When no version is specified, the **csolution - CMSIS Project Manager** only loads the latests version of a software pack. This also applies when wildcards are used in the `pack-name`. - -**Examples:** - -```yml -- pack: ARM::CMSIS@5.5.0 # 'CMSIS' Pack (with version 5.5.0) -- pack: Keil::MDK-Middleware@>=7.13.0 # 'MDK-Middleware' Software Pack from vendor Keil (with version 7.13.0 or higher, latest available to the tool) -- pack: Keil::TFM # 'TFM' Software Pack from vendor Keil (with latest version available to the tool) -- pack: AWS # All latest versions of Software Packs from vendor 'AWS' -- pack: Keil::STM* # All latest versions of Software Packs that start with 'STM' from vendor 'Keil' -``` - -### `component:` Name Conventions - -The **csolution - CMSIS Project Manager** uses the following syntax to specify the `component:` names in the `*.yml` files. - -```yml -[Cvendor::] Cclass [&Cbundle] :Cgroup [:Csub] [&Cvariant] [@[~ | >=]Cversion] -``` - -Components are defined using the [Open-CMSIS-Pack - `` element](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_components_pg.html#element_component). Several parts of a `component` are optional. For example it is possible to just define a component using `Cclass` and `Cgroup` name. All elements of a component name are summarized in the following table. - -Element | | Description -:----------|--------------|:--------------------- -`Cvendor` | Optional | Name of the component vendor as defined in `` element or by the package vendor of the software pack. -`Cclass` | **Required** | Component class name as defined in `` element of the software pack. -`Cbundle` | Optional | Bundle name of the component class as defined in `` element of the software pack. -`Cgroup` | **Required** | Component group name as defined in `` element of the software pack. -`Csub` | Optional | Component sub-group name as defined in `` element of the software pack. -`Cvariant` | Optional | Component sub-group name as defined in `` element of the software pack. -`Cversion` | Optional | Version number of the component, with `@1.2.3` that must exactly match, `@~1.2`/`@~1` that matches with semantic versioning, or `@>=1.2.3` that allows any version higher or equal. - -**Partly defined components** - -A component can be partly defined in `csolution` input files (`*.cproject.yml`, `*.clayer.yml`, `*.genlayer.yml`) by omitting `Cvendor`, `Cvariant`, and `Cversion`, even when this are part of the `components` element of the software pack. The component select algorithm resolves this to a fully defined component by: - -- when a partly specified component resolves to several possible choices, the tool selects: - - (a) the default `Cvariant` of the component as defined in the PDSC file. - - (b) the component with the higher `Cversion` value. - - (c) and error message is issued when two identical components are defined by multiple vendors and `Cvendor` is not specified. -- the partly specified component is extended by: - - version information from the software pack. - - default variant definition from the software pack. - -The fully resolved component name is shown in the [`*.cbuild.yml`](YML-CBuild-Format.md) output file. - -**Multiple component definitions are rejected** - -- If a component is added more then once in the `csolution` input files and an *error* is issued. -- An attempt to select multiple variants (using `Cvariant`) of a component results in an *error*. - -**Examples:** - -```yml -- component: CMSIS:CORE # CMSIS Core component (vendor selected by `csolution` ARM) -- component: ARM::CMSIS:CORE # CMSIS Core component from vendor ARM (any version) -- component: ARM::CMSIS:CORE@5.5.0 # CMSIS Core component from vendor ARM (with version 5.5.0) -- component: ARM::CMSIS:CORE@>=5.5.0 # CMSIS Core component from vendor ARM (with version 5.5.0 or higher) - -- component: Device:Startup # Device Startup component from any vendor - -- component: CMSIS:RTOS2:Keil RTX5 # CMSIS RTOS2 Keil RTX5 component with default variant (any version) -- component: ARM::CMSIS:RTOS2:Keil RTX5&Source@5.5.3 # CMSIS RTOS2 Keil RTX5 component with variant 'Source' and version 5.5.3 - -- component: Keil::USB&MDK-Pro:CORE&Release@6.15.1 # USB CORE component from bundle MDK-Pro in variant 'Release' and version 6.15.1 -``` - -### `device:` Name Conventions - -The device specifies multiple attributes about the target that ranges from the processor architecture to Flash -algorithms used for device programming. The following syntax is used to specify a `device:` value in the `*.yml` files. - -```yml -[ [ Dvendor:: ] Dname] [:Pname] -``` - -Element | | Description -:-------------|----------|:--------------------- -`Dvendor` | Optional | Name (without enum field) of the device vendor defined in `` element of the software pack. -`Dname` | Optional | Device name (Dname attribute) or when used the variant name (Dvariant attribute) as defined in the \ element. -`Pname` | Optional | Processor identifier (Pname attribute) as defined in the `` element. - -> **Note:** -> -> - All elements of a device name are optional which allows to supply additional information, such as the `:Pname` at -> different stages of the project. However the `Dname` itself is a mandatory element and must be specified in -> context of the various project files. -> - `Dvendor::` must be used in combination with the `Dname`. - -**Examples:** - -```yml -device: NXP::LPC1768 # The LPC1788 device from NXP -device: LPC1788 # The LPC1788 device (vendor is evaluated from DFP) -device: LPC55S69JEV98 # Device name (exact name as defined in the DFP) -device: LPC55S69JEV98:cm33_core0 # Device name (exact name as defined in the DFP) with Pname specified -device: :cm33_core0 # Pname added to a previously defined device name (or a device derived from a board) -``` - -### `board:` Name Conventions - -Evaluation Boards define indirectly a device via the related BSP. The following syntax is used to specify a `board:` -value in the `*.yml` files. - -```yml -[vendor::] board_name [:revision] -``` - -Element | | Description -:------------|--------------|:--------------------- -`vendor` | Optional | Name of the board vendor defined in `` element of the board support pack (BSP). -`Bname` | **Required** | Board name (name attribute) as defined in the \ element of the BSP. -`revision` | Optional | Board revision (revision attribute) as defined in the \ element of the BSP. - -> **Note:** -> -> When a `board:` is specified, the `device:` specification can be omitted, however it is possible to overwrite the device setting in the BSP with an explicit `device:` setting. - -**Examples:** - -```yml -board: Keil::MCB54110 # The Keil MCB54110 board (with device NXP::LPC54114J256BD64) -board: LPCXpresso55S28 # The LPCXpresso55S28 board -board: STMicroelectronics::NUCLEO-L476RG:Rev.C # A board with revision specification -``` - -### `context:` Name Conventions - -A `context:` name combines `project-name`, `built-type`, and `target-type` and is used on various places in the CMSIS-Toolbox. The following syntax is used to specify a `context:` name. - -```yml -[project-name][.build-type][+target-type] -``` - -Element | | Description -:-------------------|--------------|:--------------------- -`project-name` | Optional | Project name of a project (base name of the *.cproject.yml file). -`.build-type` | Optional | The [`build-type`](#build-types) name that is currently processed (specified with `-type: name`). -`+target-type` | Optional | The [`target-type`](#target-types) name that is currently processed (specified with `-type: name`). - -- When `project-name` is omitted, the `project-name` is the base name of the `*.cproject.yml` file. -- When `.build-type` is omitted, it matches with any possible `.build-type`. -- When `+target-type` is omitted, it matches with any possible `+target-type`. - -By default the specified `-type: name` of [`build-types:`](#build-types) and [`target-types:`](#target-types) nodes in the `*.csolution.yml` file are directly mapped to the `context` name. - -Using the [`context-map:`](#context-map) node it is possible to assign a different `.build-type` and/or `+target-type` mapping for a specific `project-name`. - -**Example:** - -Show the different possible context settings of a `*.csolution.yml` file. - -```txt -AWS_MQTT_MutualAuth_SW_Framework>csolution list contexts -s Demo.csolution.yml -Demo.Debug+AVH -Demo.Debug+IP-Stack -Demo.Debug+WiFi -Demo.Release+AVH -Demo.Release+IP-Stack -Demo.Release+WiFi -``` - -The `context` name is also used in [`for-context:`](#for-context) and [`not-for-context:`](#not-for-context) nodes that allow to include or exclude items depending on the `context`. In many cases the `project-name` can be omitted as the `context` name is within a specific `*.cproject.yml` file or applied to a specific `*.cproject.yml` file. - -## Access Sequences - -The following **access sequences** allow to use arguments from the CMSIS Project Manager as arguments of the various -`*.yml` files in the key values for `define:`, `add-path:`, `misc:`, `files:`, and `execute:`. The **access sequences** -can refer in a different project and provide therefore a method to describe project dependencies. - -Access Sequence | Description -:----------------------------------------------|:-------------------------------------- -**Target** | **Access to target and build related settings** -`$Bname$` | [Bname](#board-name-conventions) of the selected board as specified in the [`board:`](#board) node. -`$Dname$` | [Dname](#device-name-conventions) of the selected device as specified in the [`device:`](#device) node. -`$Pname$` | [Pname](#device-name-conventions) of the selected device as specified in the [`device:`](#device) node. -`$BuildType$` | [Build-type](#build-types) name of the currently processed project. -`$TargetType$` | [Target-type](#target-types) name of the currently processed project. -`$Compiler$` | [Compiler](#compiler) name of the compiler used in this project context as specified in the [`compiler:`](#compiler) node. -**YML Input** | **Access to YML Input Directories and Files** -`$Solution$` | Solution name (base name of the *.csolution.yml file). -`$SolutionDir()$` | Path to the directory of the current processed `csolution.yml` file. -`$Project$` | Project name of the current processed `cproject.yml` file. -`$ProjectDir(context)$` | Path to the directory of a related `cproject.yml` file. -**Output** | **Access to Output Directories and Files** -`$OutDir(context)$` | Path to the output directory of a related project that is defined in the `*.csolution.yml` file. -`$bin(context)$` | Path and filename of the binary output file generated by the related context. -`$cmse-lib(context)$` | Path and filename of the object file with secure gateways of a TrustZone application generated by the related context. -`$elf(context)$` | Path and filename of the ELF/DWARF output file generated by the related context. -`$hex(context)$` | Path and filename of the HEX output file generated by the related context. -`$lib(context)$` | Path and filename of the library file of the related context. - -For a [`context`](#context-name-conventions) the `project-name`, `.build-type`, and `+target-type` are optional; when omitted the current processed context is used. Example: `$ProjectDir()$` is the directory of the current processed `cproject.yml` file. - -> **Note:** -> -> The access sequences below are not completed yet, as they require a change to CMSIS-Build. - -Access Sequence | Description -:----------------------------------------------|:-------------------------------------- -`$Bpack$` | Path to the pack that defines the selected board (BSP). -`$Dpack$` | Path to the pack that defines the selected device (DFP). -`$PackRoot$` | Path to the CMSIS Pack Root directory. -`$Pack(vendor.name)$` | Path to specific pack [with latest version ToDo: revise wording]. Example: `$Pack(NXP.K32L3A60_DFP)$`. - -**Example:** - -For the example below we assume the following `build-type`, `target-type`, and `projects` definitions. - -```yml -solution: - target-types: - - type: Board # target-type: Board - board: NUCLEO-L552ZE-Q # specifies board - - - type: Production-HW # target-type: Production-HW - device: STM32U5X # specifies device - - build-types: - - type: Debug # build-type: Debug - optimize: none - debug: on - - - type: Release # build-type: Release - optimize: size - - projects: - - project: ./bootloader/Bootloader.cproject.yml # relative path - - project: /MyDevelopmentTree/security/TFM.cproject.yml # absolute path - - project: ./application/MQTT_AWS.cproject.yml # relative path -``` - -The `project: /application/MQTT_AWS.cproject.yml` can now use **Access Sequences** to reference files or directories in -other projects that belong to a solution. For example, these references are possible in the file `MQTT_AWS.cproject.yml`. - -The example below uses the `build-type` and `target-type` of the current processed context. In practice this means that -the same `build-type` and `target-type` is used as for the `MQTT_AWS.cproject.yml` project. - -```yml - files: - - file: $cmse-lib(TFM)$ # use the symbol output file of the TFM Project -``` - -The example below uses from the TFM project always `build-type: Debug` and the `target-type: Production-HW`. - -```yml - files: - - file: `$cmse-lib(TFM.Release+Production-HW)$` # use the symbol output file of the TFM Project -``` - -The example below uses the `build-type: Debug`. The `target-type` of the current processed context is used. - -> **Note:** -> -> `-execute` is scheduled for implementation in CMSIS-Toolbox 2.1 (Q3'23) - -```yml - - execute: Generate Image - os: Windows # on Windows run from - run: $DPack$/bin/gen_image.exe # DFP the get_image tool - arg: -input $elf(TFM.Debug)$ -output $OutDir(TFM.Debug)$ -``` - -The example below creates a `define` that uses the device name. - -```yml -groups: - - group: "Main File Group" - define: - - $Dname$ # Generate a #define 'device-name' for this file group -``` - -## Variables - -The `variables:` node defines are *key/value* pairs that can be used to refer to `*.clayer.yml` files. The *key* is the name of the *variable* and can be used in the following nodes: [`layers:`](#layers), [`define:`](#define), [`add-path:`](#add-path), [`misc:`](#misc), [`files:`](#files), and [`execute:`](#execute) - -Using variables that are defined in the `*.csolution.yml` file, a `*.cproject.yml` file requires no modifications when new `target-types:` are introduced. The required `layers:` could be instead specified in the `*.csolution.yml` file using a new node `variables:`. - -**Example:** - -*Example.csolution.yml* - -```yml -solution: - target-types: - - type: NXP Board - board: IMXRT1050-EVKB - variables: - - Socket-Layer: ./Socket/FreeRTOS+TCP/Socket.clayer.yml - - Board-Layer: ./Board/IMXRT1050-EVKB/Board.clayer.yml - - - type: ST Board - board: B-U585I-IOT02A - variables: - - Socket-Layer: ./Socket/WiFi/Socket.clayer.yml - - Board-Layer: ./Board/B-U585I-IOT02A/Board.clayer.yml -``` - -*Example.cproject.yml* - -```yml - layers: - - layer: $Socket-Layer$ - type: Socket - - - layer: $Board-Layer$ # no `*.clayer.yml` specified. Compatible layers are listed - type: Board # layer of type `Board` is expected -``` - -## Order of List Nodes - -The *key*/*value* pairs in a list node can be in any order. The two following list nodes are logically identical. This -might be confusing for `yml` files that are generated by an IDE. - -```yml - build-types: - - type: Release # build-type name - optimize: size # optimize for size - debug: off # generate no debug information for the release build -``` - -```yml - build-types: - - debug: off # generate no debug information for the release build - optimize: size # optimize for size - type: Release # build-type name -``` - -## Project File Structure - -The table below explains the top-level elements in each of the different `*.yml` input files that define the overall application. - -Keyword | Description -:--------------------------------|:------------------------------------ -[`default:`](#default) | Start of `cdefault.yml` file that is used to setup the compiler along with some compiler-specific controls. -[`solution:`](#solution) | Start of `*.csolution.yml` file that [collects related projects](Overview.md#solution-collection-of-related-projects) along with `build-types:` and `target-types:`. -[`project:`](#project) | Start of `*.cproject.yml` file that defines files, components, and layers which can be independently translated to a binary image or library. -[`layer:`](#layer) | Start of `*.clayer.yml` file that contains pre-configured software components along with source files. - -### `default:` - -When [`cdefault:`](#solution) is specified in the `*.csolution.yml` file, the **csolution - CMSIS Project Manager** uses a file with the name `cdefault.yml` or `cdefault.yaml` to setup -the compiler along with some specific default controls. The search order for this file is: - -- A `cdefault.yml` or `cdefault.yaml` file in the same directory as the `.csolution.yml` file. -- A `cdefault.yml` or `cdefault.yaml` file in the directory specified by the environment variable [`CMSIS_COMPILER_ROOT`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/installation.md#environment-variables). -- A `cdefault.yml` or `cdefault.yaml` file in the directory [`/etc`](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/installation.md##etccmake). - -The `default:` node is the start of a `cdefault.yml` or `cdefault.yaml` file and contains the following. - -`default:` | Content -:-----------------------------------------------------|:------------------------------------ -   [`compiler:`](#compiler) | Toolchain selection. -   [`misc:`](#misc) | Literal tool-specific controls. - -**Example:** - -```yml -default: - compiler: AC6 - misc: - - ASM: - - -masm=auto - - - Link: - - --info sizes --info totals --info unused --info veneers --info summarysizes - - --map -``` - -### `solution:` - -The `solution:` node is the start of a `*.csolution.yml` file that collects related projects as described in the section -["Project setup for related projects"](Overview.md#project-setup-for-related-projects). - -`solution:` | | Content -:----------------------------------------------------|:-----------|:------------------------------------ -    `created-by:` | Optional | Identifies the tool that created this csolution project. -    `created-for:` | Optional | Specifies the tool for building this csolution project, i.e. **ctools@1.5.0** -    `description:` | Optional | Brief description text of the solution. -    `cdefault:` | Optional | When specified, the [`cdefault.yml`](#default) file is used to setup compiler specific controls. -    [`compiler:`](#compiler) | Optional | Overall toolchain selection for the solution. -    [`language-C:`](#language-c) | Optional | Set the language standard for C source file compilation. -    [`language-CPP:`](#language-cpp) | Optional | Set the language standard for C++ source file compilation. -    [`output-dirs:`](#output-dirs) | Optional | Control the output directories for the build output. -    [`generators:`](#generators) | Optional | Control the directory structure for generator output. -    [`packs:`](#packs) | Optional | Defines local packs and/or scope of packs that are used. -    [`target-types:`](#target-types) |**Required**| List of target-types that define the target system (device or board). -    [`build-types:`](#build-types) | Optional | List of build-types (i.e. Release, Debug, Test). -    [`projects:`](#projects) |**Required**| List of projects that belong to the solution. - -**Example:** - -```yml -solution: - created-for: cmsis-toolbox@2.0 # minimum CMSIS-Toolbox version required for project build - cdefault: # use default setup of toolchain specific controls. - compiler: GCC # overwrite compiler definition in 'cdefaults.yml' - - packs: - - pack: ST # add ST packs in 'cdefaults.yml' - - build-types: # additional build types - - type: Test # build-type: Test - optimize: none - debug: on - packs: # with explicit pack specification - - pack: ST::TestSW - path: ./MyDev/TestSW - - target-types: - - type: Board # target-type: Board - board: NUCLEO-L552ZE-Q - - - type: Production-HW # target-type: Production-HW - device: STM32U5X # specifies device - - projects: - - project: ./blinky/Bootloader.cproject.yml - - project: /security/TFM.cproject.yml - - project: /application/MQTT_AWS.cproject.yml -``` - -### `project:` - -The `project:` node is the start of a `*.cproject.yml` file and can contain the following: - -`project:` | | Content -:---------------------------------------------------|:-----------|:------------------------------------ -    `description:` | Optional | Brief description text of the project. -    [`output:`](#output) | Optional | Configure the generated output files. -    [`generators:`](#generators) | Optional | Control the directory structure for generator output. -    [`rte:`](#rte) | Optional | Control the directory structure for [RTE (run-time environment)](Overview.md#rte-directory-structure) files. -    [`packs:`](#packs) | Optional | Defines packs that are required for this project. -    [`language-C:`](#language-c) | Optional | Set the language standard for C source file compilation. -    [`language-CPP:`](#language-cpp) | Optional | Set the language standard for C++ source file compilation. -    [`optimize:`](#optimize) | Optional | Optimize level for code generation. -    [`linker:`](#linker) | Optional | Instructions for the linker. -    [`debug:`](#debug) | Optional | Generation of debug information. -    [`define:`](#define) | Optional | Preprocessor (#define) symbols for code generation. -    [`undefine:`](#undefine) | Optional | Remove preprocessor (#define) symbols. -    [`add-path:`](#add-path) | Optional | Additional include file paths. -    [`del-path:`](#del-path) | Optional | Remove specific include file paths. -    [`misc:`](#misc) | Optional | Literal tool-specific controls. -    [`device:`](#device) | Optional | Device setting (specify processor core). -    [`processor:`](#processor) | Optional | Processor specific settings. -    [`groups:`](#groups) |**Required**| List of source file groups along with source files. -    [`components:`](#components) | Optional | List of software components used. -    [`layers:`](#layers) | Optional | List of software layers that belong to the project. -    [`connections:`](#connections) | Optional | List of consumed and provided resources. - -**Example:** - -```yml -project: - misc: - - compiler: AC6 # specify misc controls for Arm Compiler 6 - C: [-fshort-enums, -fshort-wchar] # set options for C files - add-path: - - $OutDir(Secure)$ # add the path to the secure project's output directory - components: - - component: Startup # Add startup component - - component: CMSIS CORE - - component: Keil RTX5 Library_NS - groups: - - group: Non-secure Code # Create group - files: - - file: main_ns.c # Add files to group - - file: $Source(Secure)$interface.h - - file: $Output(Secure)$_CMSE_Lib.o -``` - -### `layer:` - -The `layer:` node is the start of a `*.clayer.yml` file and defines a [Software Layer](./Overview.md#software-layers). It can contain the following nodes: - -`layer:` | | Content -:------------------------------------------------------------|:-----------|:------------------------------------ -    [`type:`](#layer---type) | Optional | Layer type for combining layers; used to identify [compatible layers](Overview.md#list-compatible-layers). -    `description:` | Optional | Brief description text of the layer. -    [`language-C:`](#language-c) | Optional | Set the language standard for C source file compilation. -    [`language-CPP:`](#language-cpp) | Optional | Set the language standard for C++ source file compilation. -    [`optimize:`](#optimize) | Optional | Optimize level for code generation. -    [`debug:`](#debug) | Optional | Generation of debug information. -    [`warnings:`](#warnings) | Optional | Control generation of compiler diagnostics. -    [`define:`](#define) | Optional | Define symbol settings for code generation. -    [`undefine:`](#undefine) | Optional | Remove define symbol settings for code generation. -    [`add-path:`](#add-path) | Optional | Additional include file paths. -    [`del-path:`](#del-path) | Optional | Remove specific include file paths. -    [`misc:`](#misc) | Optional | Literal tool-specific controls. -    [`generators:`](#generators) | Optional | Control the directory structure for generator output. -    [`packs:`](#packs) | Optional | Defines packs that are required for this layer. -    [`for-device:`](#device-name-conventions) | Optional | Device information, used for consistency check (device selection is in `*.csolution.yml`). -    [`for-board:`](#board-name-conventions) | Optional | Board information, used for consistency check (board selection is in `*.csolution.yml`). -    [`connections:`](#connections) | Optional | List of consumed and provided resources. -    [`processor:`](#processor) | Optional | Processor specific settings. -    [`linker:`](#linker) | Optional | Instructions for the linker. -    [`groups:`](#groups) | Optional | List of source file groups along with source files. -    [`components:`](#components) | Optional | List of software components used. - -**Example:** - -```yml -layer: - type: Board - description: Setup with Ethernet and WiFi interface - processor: - trustzone: secure # set processor to secure - components: - - component: Startup - - component: CMSIS CORE - groups: - - group: Secure Code - files: - - file: main_s.c - - group: CMSE - files: - - file: interface.c - - file: interface.h - - file: tz_context.c -``` - -## Directory Control - -The following nodes control the directory structure for **CSolution** based projects. - -### `output-dirs:` - -Allows to control the directory structure for build output files. - ->**Note:** -> -> This control is only possible at `csolution.yml` level. -> -> Only relative paths to the base directory of the `csolution.yml` file are permitted. Use command line options of the `cbuild` tool to redirect the absolute path for this working directory. - -`output-dirs:` | | Content -:----------------------------------|--------------|:------------------------------------ -    `intdir:` | Optional | Specifies the directory for the interim files (temporary or object files). -    `outdir:` | Optional | Specifies the directory for the build output files (ELF, binary, MAP files). - -The default setting for the `output-dirs:` are: - -```yml - intdir: $SolutionDir()$/tmp/$Project$/$TargetType$/$BuildType$ - outdir: $SolutionDir()$/out/$TargetType$ -``` - -**Example:** - -```yml -output-dirs: - intdir: ./tmp2 # relative path to csolution.yml file - outdir: ./out/$Project$/$TargetType$ # $BuildType$ no longer part of the outdir -``` - -### `generators:` - -Allows to control the directory structure for generator output files. - -When no explicit `generators:` is specified, the **CSolution** Project Manager uses as path: - -- The `workingDir` defined in the [generators element](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_generators_pg.html#element_generator) of the PDSC file. -- When no `workingDir` is defined the default directory `$ProjectDir()$/generated/` is used; `` is defined by the `id` in the generators element of the PDSC file. - -The `generators:` node can be added at various levels of the `*.yml` input files. The following order is used: - -1. Use `generators:` specification of the `*.clayer.yml` input file, if not exist: -2. Use `generators:` specification of the `*.cproject.yml` input file, if not exist: -3. Use `generators:` specification of the `*.csolution.yml` input file. - ->**Notes:** -> -> - Only relative paths are permitted to support portablity of projects. -> - The location of the `*.yml` file that contains the `generators:` node is the reference for relative paths. - -`generators:` | | Content -:------------------------------|------------|:------------------------------------ -    `base-dir:` | Optional | Base directory for unspecified generators; default: `$ProjectDir()$/generated`. -    `options:` | Optional | Specific generator options; allows explicit directory configuration for a generator. - -> **Note:** -> -> The base directory is extended for each generator with `/`; `` is defined by the `id` in the generators element of the PDSC file. - -#### `generators: - options:` - -`options:` | | Content -:------------------------------|------------|:------------------------------------ -`- generator:` | Optional | Identifier of the generator tool, specified with `id` in the [generators element](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_generators_pg.html#element_generator) of the PDSC file. -    `path:` | Optional | Specifies the directory for generated files. Relative paths used the location of the `yml` file as base directory. - -**Example:** - -```yml -generators: - base-dir: $SolutionDir()$/MyGenerators # Path for all generators extended by '/' - - options: - - generator: Cube # for the generator `Cube` use this path - path: ./CubeFiles # relative path to the *.yml file that contains this setting -``` - -### `rte:` - -Allows to control the directory structure for [RTE (run-time environment)](Overview.md#rte-directory-structure) files. - ->**Notes:** -> -> - This control is only possible at `*.cproject.yml` level. -> - Only relative paths are permitted to support portablity of projects. -> - The location of the `*.cproject.yml` file is the reference for relative paths. - -`rte:` | | Content -:------------------------------|------------|:------------------------------------ -    `base-dir:` | Optional | Base directory for unspecified generators; default: `$ProjectDir()$/RTE`. - -```yml -rte: - base-dir: $TargetType$/RTE # Path extended with target-type, results in `$ProjectDir()$/$TargetType$/RTE` -``` - -## Toolchain Options - -The following code translation options may be used at various places such as: - -- [`solution:`](#solution) level to specify options for a collection of related projects -- [`project:`](#projects) level to specify options for a project - -### `compiler:` - -Selects the compiler toolchain used for code generation. -Optionally the compiler can have a version number specification. - -Compiler Name | Supported Compiler -:-----------------------------------------------------|:------------------------------------ -`GCC` | GCC Compiler -`CLANG` | LLVM/Clang Compiler -`AC6` | Arm Compiler version 6 -`IAR` | IAR Compiler - -**Example:** - -```yml -compiler: GCC # Select GCC Compiler -``` - -```yml -compiler: AC6@6.18.0 # Select Arm Compiler version 6 -``` - -### `linker:` - -The `linker:` node specifies an explicit Linker Script and/or memory regions header file. It can be applied in `*.cproject.yml` and `*.clayer.yml` files. If multiple `linker:` nodes are specified an error is issued. - -`linker:` | | Content -:-----------------------------------------------------------|:-----------|:-------------------------------- -**`- regions:`** |**Optional**|**Path and file name of `regions_.h`, used to generate a Linker Script.** -    [`for-compiler:`](#for-compiler) | Optional | Include Linker Script for the specified toolchain. -    [`for-context:`](#for-context) | Optional | Include Linker Script for a list of *build* and *target* type names. -    [`not-for-context:`](#not-for-context) | Optional | Exclude Linker Script for a list of *build* and *target* type names. -**`- script:`** |**Optional**|**Explicit file name of the Linker Script, overrules files provided with [`file:`](#files) or components.** -    [`for-compiler:`](#for-compiler) | Optional | Include Linker Script for the specified toolchain. -    [`for-context:`](#for-context) | Optional | Include Linker Script for a list of *build* and *target* type names. -    [`not-for-context:`](#not-for-context) | Optional | Exclude Linker Script for a list of *build* and *target* type names. -**[`- define:`](#define)** |**Optional**|**Define symbol settings for the linker script file preprocessor.** -    [`for-compiler:`](#for-compiler) | Optional | Apply define settings for the specified toolchain. -    [`for-context:`](#for-context) | Optional | Include define settings for a list of *build* and *target* type names. -    [`not-for-context:`](#not-for-context) | Optional | Exclude define settings for a list of *build* and *target* type names. - -> **Note:** -> -> If no `script:` file is specified, compiler specific [linker script template files](Linker-Script-Management.md#linker-script-templates) are used. - -### `output:` - -Configure the generated output files. - -`output:` | | Content -:--------------------------------------|:-----------|:-------------------------------- -    `base-name:` | Optional | Specify a base name for all output files. -    `type:` | Optional | A list of output types for code generation (see list below). - -`type:` | Description -:-----------------|:------------- -`- lib` | Library or archive. Note: GCC uses the prefix `lib` in the base name for archive files. -`- elf` | Executable in ELF format. The file extension is toolchain specific. -`- hex` | Intel HEX file in HEX-386 format. -`- bin` | Binary image. - -The **default** setting for `output:` is: - -```yml -output: - base-name: $Project$ # used the base name of the `cproject.yml` file. - type: elf # Generate executeable file. -``` - -**Example:** - -```yml -output: # configure output files - base-name: MyProject # used for all output files, including linker map file. - type: - - elf # Generate executeable file. - - hex # generate a HEX file - - bin # generate a BIN file -``` - -Gnerate a **library**: - -```yml -output: # configure output files - type: lib # Generate executeable file. -``` - -## Translation Control - -The following translation control options may be used at various places such as: - -- [`solution:`](#solution) level to specify options for a collection of related projects -- [`project:`](#projects) level to specify options for a project -- [`groups:`](#groups) level to specify options for a specify source file group -- [`files:`](#files) level to specify options for a specify source file - -> **Note:** -> -> `define:`, `add-path:`, `del-path:` and `misc:` are additive. All other keywords overwrite previous settings. - -### `language-C:` - -Set the language standard for C source file compilation. - -Value | Select C Language Standard -:-----------------------------------------------------|:------------------------------------ -`c90` | compile C source files as defined in C90 standard (ISO/IEC 9899:1990). -`gnu90` | same as `c90` but with additional GNU extensions. -`c99` (default) | compile C source files as defined in C99 standard (ISO/IEC 9899:1999). -`gnu99` | same as `c99` but with additional GNU extensions. -`c11` | compile C source files as defined in C11 standard (ISO/IEC 9899:2011). -`gnu11` | same as `c11` but with additional GNU extensions. - -### `language-CPP:` - -Set the language standard for C++ source file compilation. - -Value | Select C++ Language Standard -:-----------------------------------------------------|:------------------------------------ -`c++98` | compile C++ source files as defined in C++98 standard (ISO/IEC 14882:1998). -`gnu++98` | same as `c++98` but with additional GNU extensions. -`c++03` | compile C++ source files as defined in C++03 standard (ISO/IEC 14882:2003). -`gnu++03` | same as `c++03` but with additional GNU extensions. -`c++11` | compile C++ source files as defined in C++11 standard (ISO/IEC 14882:2011). -`gnu++11` | same as `c++11` but with additional GNU extensions. -`c++14` (default) | compile C++ source files as defined in C++14 standard (ISO/IEC 14882:2014). -`gnu++14` | same as `c++14` but with additional GNU extensions. -`c++17` | compile C++ source files as defined in C++17 standard (ISO/IEC 14882:2014). -`gnu++17` | same as `c++17` but with additional GNU extensions. -`c++20` | compile C++ source files as defined in C++20 standard (ISO/IEC 14882:2020). -`gnu++20` | same as `c++20` but with additional GNU extensions. - -### `optimize:` - -Generic optimize levels for code generation. - -Value | Code Generation -:-----------------------------------------------------|:------------------------------------ -`balanced` | Balanced optimization (default) -`size` | Optimized for code size -`speed` | Optimized for execution speed -`none` | No optimization (provides better debug illusion) - -**Example:** - -```yml -groups: - - group: "Main File Group" - optimize: none # optimize this file group for debug illusion - files: - - file: file1a.c - - file: file1b.c -``` - -### `debug:` - -Control the generation of debug information. - -Value | Code Generation -:-----------------------------------------------------|:------------------------------------ -`on` | Generate debug information (default) -`off` | Generate no debug information - -**Example:** - -```yml - build-types: - - type: Release - optimize: size # optimize for size - debug: off # generate no debug information for the release build -``` - -### `warnings:` - -Control warning level for compiler diagnostics. - -Value | Control diagnostic messages (warnings) -:-----------------------------------------------------|:------------------------------------ -`on` | Generate warning messages -`off` | No warning messages generated - -### `define:` - -Contains a list of symbol #define statements that are passed via the command line to the development tools for C, C++ source files, or the [linker](#linker) script file preprocessor. - -`define:` | Content -:-----------------------------------------------------------|:------------------------------------ -    `- ` | #define symbol passed via command line -    `- : ` | #define symbol with value passed via command line -    `- : \"\"` | #define symbol with string value passed via command line - ->**Note:** -> -> This control only applies to C and C++ source files (or to the [linker](#linker) script preprocessor). For assembler source files use the `misc:` node. - -**Example:** - -```yml -define: # Start a list of define statements - - TestValue: 12 # add symbol 'TestValue' with value 12 - - TestMode # add symbol 'TestMode' -``` - -### `undefine:` - -Remove symbol #define statements from the command line of the development tools. - -`undefine:` | Content -:----------------------------------------------------|:------------------------------------ -   `- ` | Remove #define symbol - -**Examples:** - -```yml -groups: - - group: "Main File Group" - undefine: - - TestValue # remove define symbol `TestValue` for this file group - files: - - file: file1a.c - undefine: - - TestMode # remove define symbol `TestMode` for this file - - file: file1b.c -``` - -### `add-path:` - -Add include paths to the command line of the development tools for C and C++ source files. - -`add-path:` | Content -:----------------------------------------------------------|:------------------------------------ -    `- ` | Named path to be added - ->**Note:** -> -> This control only applies to C and C++ source files. For assembler source files use the `misc:` node. - -**Example:** - -```yml -project: - misc: - - for-compiler: AC6 - C: [-fshort-enums, -fshort-wchar] - - for-compiler: GCC - C: [-fshort-enums, -fshort-wchar] - - add-path: - - $OutDir(Secure)$ # add path to secure project's output directory -``` - -### `del-path:` - -Remove include paths (that are defined at the cproject level) from the command line of the development tools. - -`del-paths:` | Content -:----------------------------------------------------------|:------------------------------------ -    `- ` | Named path to be removed; `*` for all - -**Examle:** - -```yml - target-types: - - type: CM3 - device: ARMCM3 - del-paths: - - /path/solution/to-be-removed -``` - -### `misc:` - -Add miscellaneous literal tool-specific controls that are directly passed to the individual tools depending on the file type. - -`misc:` | | Content -:------------------------------------------|--------------|:------------------------------------ -[`- for-compiler:`](#for-compiler) | Optional | Name of the toolchain that the literal control string applies to. -    `C-CPP:` | Optional | Applies to `*.c` and `*.cpp` files (added before `C` and `CPP:`). -    `C:` | Optional | Applies to `*.c` files only. -    `CPP:` | Optional | Applies to `*.cpp` files only. -    `ASM:` | Optional | Applies to assembler source files only. -    `Link:` | Optional | Applies to the linker (added before `Link-C:` or `Link-CPP:`). -    `Link-C:` | Optional | Applies to the linker; added when no C++ files are part of the project. -    `Link-CPP:` | Optional | Applies to the linker; added when C++ files are part of the project. -    `Library:` | Optional | Applies to the library manager or archiver. - -**Example:** - -```yml - build-types: - - type: Debug - misc: - - for-compiler: AC6 - C-CPP: - - -O1 - - -g - - for-compiler: GCC - C-CPP: - - -Og - - - type: Release - compiler: AC6 - misc: - - C: - - -O3 - - - type: GCC-LibDebug - compiler: GCC - misc: - - Library: - - -lm - - -lc - - -lgcc - - -lnosys -``` - -## Project Setups - -The `setups:` node can be used to create setups that are specific to a compiler, target-type, and/or built-type. - -### `setups:` - -The `setups:` node collects a list of `setup:` notes. For each context, only one setup will be selected. - -The result is a `setup:` that collects various toolchain options and that is valid for all files and components in the -project. It is however possible to change that `setup:` settings on a [`group:`](#groups) or [`file:`](#files) level. - -`setups:` | | Content -:----------------------------------------------------|:-------------|:------------------------------------ -`- setup:` | **Required** | Description of the setup -    [`for-context:`](#for-context) | Optional | Include group for a list of *build* and *target* types. -    [`not-for-context:`](#not-for-context) | Optional | Exclude group for a list of *build* and *target* types. -    [`for-compiler:`](#for-compiler) | Optional | Include group for a list of compilers. -    [`output:`](#output) | Optional | Configure the generated output files. -    [`language-C:`](#language-c) | Optional | Set the language standard for C source file compilation. -    [`language-CPP:`](#language-cpp) | Optional | Set the language standard for C++ source file compilation. -    [`optimize:`](#optimize) | Optional | Optimize level for code generation. -    [`debug:`](#debug) | Optional | Generation of debug information. -    [`warnings:`](#warnings) | Optional | Control generation of compiler diagnostics. -    [`define:`](#define) | Optional | Define symbol settings for code generation. -    [`undefine:`](#undefine) | Optional | Remove define symbol settings for code generation. -    [`add-path:`](#add-path) | Optional | Additional include file paths. -    [`del-path:`](#del-path) | Optional | Remove specific include file paths. -    [`linker:`](#linker) | Optional | Remove specific include file paths. -    [`misc:`](#misc) | Optional | Literal tool-specific controls. -    [`processor:`](#processor) | Optional | Processor configuration. - -```yml -project: - setups: - - setup: Arm Compiler 6 project setup - for-compiler: AC6 - linker: - - script: my-project.sct - define: - - test: 12 - - - setup: GCC project setup - for-compiler: GCC - linker: - - script: my-project.inc - define: - - test: 11 -``` - -## Pack Selection - -The `packs:` node can be specified in the `*.csolution.yml` file allows you to: - -- Reduce the scope of software packs that are available for projects. -- Add specific software packs optional with a version specification. -- Provide a path to a local installation of a software pack that is for example project specific or under development. - -The [Pack Name Conventions](#pack-name-conventions) are used to specify the name of the software packs. -The `pack:` definition may be specific to a [`context`](#context) that specifies `target-types:` and/or `build-types:` or provide a local path to a development repository of a software pack. - ->**Notes:** -> -> - By default, the **csolution - CMSIS Project Manager** only loads the latest version of the installed software packs. It is however possible to request specific versions using the `- pack:` node. -> -> - An attempt to add two different versions of the same software pack results in an error. - -### `packs:` - -The `packs:` node is the start of a pack selection. - -`packs:` | Content -:-----------------------------------------------------|:------------------------------------ -    [`- pack:`](#pack) | Explicit pack specification (additive) - -### `pack:` - -The `pack:` list allows to add specific software packs, optional with a version specification. The version number can -have also the format `@~1.2`/`@~1` that matches with semantic versioning. - -`pack:` | Content -:-----------------------------------------------------------|:------------------------------------ -    `path:` | Explicit path name that stores the software pack -    [`for-context:`](#for-context) | Include pack for a list of *build* and *target* types. -    [`not-for-context:`](#not-for-context) | Exclude pack for a list of *build* and *target* types. - -**Example:** - -```yml -packs: # start section that specifics software packs - - pack: AWS # use packs from AWS - - pack: NXP::*K32L* # use packs from NXP relating to K32L series (would match K32L3A60_DFP + FRDM-K32L3A6_BSP) - - pack: ARM # use packs from Arm - - - pack: Keil::Arm_Compiler # add latest version of Keil::Arm_Compiler pack - - pack: Keil::MDK-Middleware@7.13.0 # add Keil::MDK-Middleware pack at version 7.13.0 - - pack: ARM::CMSIS-FreeRTOS@~10.4 # add CMSIS-FreeRTOS with version 10.4.x - - - pack: NXP::K32L3A60_DFP # add pack for NXP device - path: ./local/NXP/K32L3A60_DFP # with path to the pack (local copy, repo, etc.) - - - pack: AWS::coreHTTP # add pack - path: ./development/AWS/coreHTTP # with path to development source directory - for-context: +DevTest # pack is only used for target-type "DevTest" -``` - -## Target Selection - -### `board:` - -Specifies a [unique board name](#board-name-conventions), optionally with vendor that must be defined in software packs. -This information is used to define the `device:` along with basic toolchain settings. - -### `device:` - -Specifies a [unique device name](#device-name-conventions), optionally with vendor that must be defined in software -packs. This information is used to define the `device:` along with basic toolchain settings. - -A `device:` is derived from the `board:` setting, but an explicit `device:` setting overrules the `board:` device. - -If `device:` specifies a device with a multi-core processor, and no explicit `pname` for the processor core selection is specified, the default `pname` of the device is used. - -At the level of a `cproject.yml` file, only the `pname` can be specified as the device itself is selected at the level of a `csolution.yml` file. - -## Processor Attributes - -### `processor:` - -The `processor:` keyword specifies the TrustZone configuration for this project. - -`processor:` | Content -:------------------------------------|:------------------------------------ -    `trustzone:` | TrustZone mode: `secure` \| `non-secure` \| `off`. - -The default setting for `trustzone:` is: - -- `off` for devices that support this option, but TrustZone is configurable. -- `non-secure` for devices that have TrustZone enabled. - -**Example:** - -```yml -project: - processor: - trustzone: secure -``` - -## Context - -A [`context`](#context-name-conventions) is an enviroment setup for a project that is composed of: - -- `project-name` that is the base name of the `*.cproject.yml` file. -- `.build-type` that defines typically build specific settings such as for debug, release, or test. -- `+target-type` that defines typically target specific settings such as device, board, or usage of processor features. - -The section -[Project setup for multiple targets and test builds](Overview.md#project-setup-for-multiple-targets-and-builds) -explains the overall concept of `target-types` and `build-types`. These `target-types` and `build-types` are defined in the `*.csolution.yml` that defines the overall application for a system. - -The settings of the `target-types:` are processed first; then the settings of the `build-types:` that potentially overwrite the `target-types:` settings. - -### `target-types:` - -The `target-types:` node may include [toolchain options](#toolchain-options), [target selection](#target-selection), and [processor attributes](#processor-attributes): - -`target-types:` | | Content -:--------------------------------------------------|--------------|:------------------------------------ -`- type:` | **Required** | The target-type name that is used to create the [context](#context-name-conventions) name. -    [`compiler:`](#compiler) | Optional | Toolchain selection. -    [`language-C:`](#language-c) | Optional | Set the language standard for C source file compilation. -    [`language-CPP:`](#language-cpp)| Optional | Set the language standard for C++ source file compilation. -    [`optimize:`](#optimize) | Optional | Optimize level for code generation. -    [`debug:`](#debug) | Optional | Generation of debug information. -    [`warnings:`](#warnings) | Optional | Control Generation of debug information. -    [`define:`](#define) | Optional | Preprocessor (#define) symbols for code generation. -    [`undefine:`](#undefine) | Optional | Remove preprocessor (#define) symbols. -    [`add-path:`](#add-path) | Optional | Additional include file paths. -    [`del-path:`](#del-path) | Optional | Remove specific include file paths. -    [`misc:`](#misc) | Optional | Literal tool-specific controls. -    [`board:`](#board) | **see Note** | Board specification. -    [`device:`](#device) | **see Note** | Device specification. -    [`processor:`](#processor) | Optional | Processor specific settings. -    [`context-map:`](#context-map) | Optional | Use different `target-types:` for specific projects. -    [`variables:`](#variables) | Optional | Variables that can be used to define project components. - -> **Note::** -> -> Either `device:` or `board:` is required. - -### `build-types:` - -The `build-types:` node may include [toolchain options](#toolchain-options): - -`build-types:` | | Content -:--------------------------------------------------|--------------|:------------------------------------ -`- type:` | **Required** | The build-type name that is used to create the [context](#context-name-conventions) name. -    [`compiler:`](#compiler) | Optional | Toolchain selection. -    [`language-C:`](#language-c) | Optional | Set the language standard for C source file compilation. -    [`language-CPP:`](#language-cpp)| Optional | Set the language standard for C++ source file compilation. -    [`optimize:`](#optimize) | Optional | Optimize level for code generation. -    [`debug:`](#debug) | Optional | Generation of debug information. -    [`define:`](#define) | Optional | Preprocessor (#define) symbols for code generation. -    [`undefine:`](#undefine) | Optional | Remove preprocessor (#define) symbols. -    [`add-path:`](#add-path) | Optional | Additional include file paths. -    [`del-path:`](#del-path) | Optional | Remove specific include file paths. -    [`misc:`](#misc) | Optional | Literal tool-specific controls. -    [`context-map:`](#context-map) | Optional | Use different `build-types:` for specific projects. -    [`variables:`](#variables) | Optional | Variables that can be used to define project components. - -**Example:** - -```yml -target-types: - - type: Board # target-type name, used in context with: +Board - board: NUCLEO-L552ZE-Q # board specifies indirectly also the device - - - type: Production-HW # target-type name, used in context with: +Production-HW - device: STM32L552RC # specifies device - -build-types: - - type: Debug # build-type name, used in context with: .Debug - optimize: none # specifies code optimization level - debug: on # generates debug information - - - type: Test # build-type name, used in context with: .Test - optimize: size - debug: on -``` - -The `board:`, `device:`, and `processor:` settings are used to configure the code translation for the toolchain. These -settings are processed in the following order: - -1. `board:` relates to a BSP software pack that defines board parameters, including the - [mounted device](https://arm-software.github.io/CMSIS_5/Pack/html/pdsc_boards_pg.html#element_board_mountedDevice). - If `board:` is not specified, a `device:` must be specified. -2. `device:` defines the target device. If `board:` is specified, the `device:` setting can be used to overwrite the - device or specify the processor core used. -3. `processor:` overwrites default settings for code generation, such as endianess, TrustZone mode, or disable Floating - Point code generation. - -**Examples:** - -```yml -target-types: - - type: Production-HW - board: NUCLEO-L552ZE-Q # hardware is similar to a board (to use related software layers) - device: STM32L552RC # but uses a slightly different device - processor: - trustzone: off # TrustZone disabled for this project -``` - -```yml -target-types: - - type: Production-HW - board: FRDM-K32L3A6 # NXP board with K32L3A6 device - device: :cm0plus # use the Cortex-M0+ processor -``` - -### `context-map:` - ->**Scheduled for CMSIS-Toolbox 2.0 - Q2** - -The `context-map:` node allows for a specific `project-name` the remapping of `target-types:` and/or `build-types:` to a different `context:` which enables: - -- Integrating an existing `*.cproject.yml` file in a different `*.csolution.yml` file that uses different `build-types:` and/or `target-types:` for the overall application. -- Defines how different `*.cproject.yml` files of a `*.csolution.yml` are to the binary image of the final target (needs reflection in cbuild-idx.yml). - -The `context-map:` node lists the remapping the [`context:`](#context-name-conventions) of a `project-name` for specific `target-types:` and `build-types:`. - -`context-map:` | | Content -:--------------------------------------------------|--------------|:------------------------------------ -    `- context:` | **Required** | Specify a next context for a project - -For the `context-map:` it is required to specify the `project-name` in the `context:` list. This project will use a different `.build-type` and/or `+target-type` as applied in the `context:`. This remapping of the context applies for the specific type in the `build-types:` or `target-types:` list. - -**Example 1:** - -This application combines two projects for a multi-processor device, but the project `HelloCM7` requires a different setting for the build-type name `Release` as this enables different settings within the `*.cproject.yml` file. - -```yml - target-types: - - type: DualCore - device: MyDualCoreDevice - - build-types: - - type: Release # When applying build-type name 'release': - context-map: - - context: HelloCM7.flex_release # project HelloCM7 uses build-type name "flex_release" instead of "release" - - projects: - - project: ./CM7/HelloCM7.cproject.yml - - project: ./CM4/HelloCM4.cproject.yml -``` - -**Example 2:** - -The following example uses three projects `Demo`, `TFM` and `Boot`. The project `TFM` should be always build using the context `TFM.Release+LibMode`. For the target-type name `Board`, the Boot project requires the `+Flash` target, but any build-type could be used. - -```yml - target-types: - - type: Board # When applying target-type: 'Board': - context-map: - - context: TFM.Release+LibMode # for project TFM use build-type: Release, target-type: LibMode - - context: Boot+Flash # for project Boot use target-type: Flash - board: B-U585I-IOT02A - - type: AVH # When applying target-type: 'AVH': - context-map: - - context: TFM.Release+LibMode # for project TFM use build-type: Release, target-type: LibMode - device: ARM::SSE-300-MPS3 - - projects: - - project: ./App/Demo.cproject.yml - - project: ./Security/TFM.cproject.yml - - project: ./Loader/Boot.cproject.yml -``` - -## Conditional Build - -It is possible to include or exclude *items* of a [*list node*] in the build process. - -- [`for-compiler:`](#for-compiler) includes *items* only for a compiler toolchain. -- [`for-context:`](#for-context) includes *items* only for a [*context*](#context-name-conventions) list. -- [`not-for-context:`](#not-for-context) excludes *items* for a [*context*](#context-name-conventions) list. - -> **Note:** -> -> `for-context` and `not-for-context` are mutually exclusive, only one occurrence can be specified for a - *list node*. - -### `for-compiler:` - -Depending on a [compiler](#compiler) toolchain it is possible to include *list nodes* in the build process. - -**Examples:** - -```yml -for-compiler: AC6@6.16 # add item for Arm Compiler version 6.16 only - -for-compiler: # add item - - AC6 # for Arm Compiler (any version) - - GCC # for GCC Compiler -``` - -### `for-context:` - -A [*context*](#context-name-conventions) list that adds a list-node for specific `target-type` and/or `build-type` names. - -### `not-for-context:` - -A [*context*](#context-name-conventions) list that removes a list-node for specific `target-types:` and/or `build-types:`. - -### Context List - -It is also possible to provide a [`context`](#context-name-conventions) list with: - -```yml - - [.build-type][+target-type] - - [.build-type][+target-type] -``` - -**Examples:** - -```yml -for-context: - - .Test # add item for build-type: Test (any target-type) - -for-context: # add item - - .Debug # for build-type: Debug and - - .Release+Production-HW # build-type: Release / target-type: Production-HW - -not-for-context: +Virtual # remove item for target-type: Virtual (any build-type) -not-for-context: .Release+Virtual # remove item for build-type: Release with target-type: Virtual -``` - -### Usage - -The keyword `for-context:` and `not-for-context:` can be applied to the following *list nodes*: - -List Node | Description -:------------------------------------------|:------------------------------------ -[`- project:`](#projects) | At `projects:` level it is possible to control inclusion of project. -[`- layer:`](#layers) | At `layers:` level it is possible to control inclusion of a software layer. - -The keyword `for-context:`, `not-for-context:`, and `for-compiler:` can be applied to the following *list nodes*: - -List Node | Description -:------------------------------------------|:------------------------------------ -[`- component:`](#components) | At `components:` level it is possible to control inclusion of a software component. -[`- group:`](#groups) | At `groups:` level it is possible to control inclusion of a file group. -[`- setup:`](#setups) | At `setups:` level it is define toolchain specific options that apply to the whole project. -[`- file:`](#files) | At `files:` level it is possible to control inclusion of a file. - -The inclusion of a *list node* is processed for a given project [*context*](#context-name-conventions) respecting its hierarchy from top to bottom: - -`project` --> `layer` --> `component`/`group` --> `file` - -In other words, the restrictions specified by `for-context:` or `not-for-context` for a *list node* are automatically applied to its children nodes. Children *list nodes* inherit the restrictions from their parent. - -## Multiple Projects - -The section [Project setup for related projects](Overview.md#project-setup-for-related-projects) describes the -organization of multiple projects. The file `*.csolution.yml` describes the relationship of this projects and may also re-map -`target-types:` and `build-types:` for this projects using [`context-map:`](#context-map). - -### `projects:` - -The YAML structure of the section `projects:` is: - -`projects:` | | Content -:---------------------------------------------------------|--------------|:------------------------------------ -[`- project:`](#project) | **Required** | Path to the project file. -    [`for-context:`](#for-context) | Optional | Include project for a list of *build* and *target* types. -    [`not-for-context:`](#not-for-context) | Optional | Exclude project for a list of *build* and *target* types. -    [`compiler:`](#compiler) | Optional | Specify a specific compiler. -    [`language-C:`](#language-c) | Optional | Set the language standard for C source file compilation. -    [`language-CPP:`](#language-cpp) | Optional | Set the language standard for C++ source file compilation. -    [`optimize:`](#optimize) | Optional | Optimize level for code generation. -    [`debug:`](#debug) | Optional | Generation of debug information. -    [`warnings:`](#warnings) | Optional | Control generation of compiler diagnostics. -    [`define:`](#define) | Optional | Define symbol settings for code generation. -    [`undefine:`](#undefine) | Optional | Remove define symbol settings for code generation. -    [`add-path:`](#add-path) | Optional | Additional include file paths. -    [`del-path:`](#del-path) | Optional | Remove specific include file paths. -    [`misc:`](#misc) | Optional | Literal tool-specific controls. - -**Examples:** - -This example uses two projects that are build in parallel using the same `build-type:` and `target-type:`. Such a setup is typical for multi-processor systems. - -```yml - projects: - - project: ./CM0/CM0.cproject.yml # include project for Cortex-M0 processor - - project: ./CM4/CM4.cproject.yml # include project for Cortex-M4 processor -``` - -This example uses multiple projects, but with additional controls. - -```yml - projects: - - project: ./CM0/CM0.cproject.yml # specify cproject.yml file - for-context: +CM0-Addon # build only when 'target-type: CM0-Addon' is selected - for-compiler: GCC # build only when 'compiler: GCC' is selected - define: # add additional defines during build process - - test: 12 - - - project: ./CM0/CM0.cproject.yml # specify cproject.yml file - for-context: +CM0-Addon # specify use case - for-compiler: AC6 # build only when 'compiler: AC6' is selected - define: # add additional defines during build process - - test: 9 - - - project: ./Debug/Debug.cproject.yml # specify cproject.yml file - not-for-context: .Release # generated for any 'build-type:' except 'Release' -``` - -## Source File Management - -Keyword | Used in files | Description -:----------------|:---------------------------------|:------------------------------------ -`groups:` | `*.cproject.yml`, `*.clayer.yml` | Start of a list that adds [source groups and files](#source-file-management) to a project or layer. -`layers:` | `*.cproject.yml` | Start of a list that adds software layers to a project. -`components:` | `*.cproject.yml`, `*.clayer.yml` | Start of a list that adds software components to a project or layer. - -### `groups:` - -The `groups:` keyword specifies a list that adds [source groups and files](#source-file-management) to a project or layer: - -`groups:` | | Content -:---------------------------------------------------------|--------------|:------------------------------------ -`- group:` | **Required** | Name of the group. -    [`for-context:`](#for-context) | Optional | Include group for a list of *build* and *target* types. -    [`not-for-context:`](#not-for-context) | Optional | Exclude group for a list of *build* and *target* types. -    [`for-compiler:`](#for-compiler) | Optional | Include group for a list of compilers. -    [`language-C:`](#language-c) | Optional | Set the language standard for C source file compilation. -    [`language-CPP:`](#language-cpp) | Optional | Set the language standard for C++ source file compilation. -    [`optimize:`](#optimize) | Optional | Optimize level for code generation. -    [`debug:`](#debug) | Optional | Generation of debug information. -    [`warnings:`](#warnings) | Optional | Control generation of compiler diagnostics. -    [`define:`](#define) | Optional | Define symbol settings for code generation. -    [`undefine:`](#undefine) | Optional | Remove define symbol settings for code generation. -    [`add-path:`](#add-path) | Optional | Additional include file paths. -    [`del-path:`](#del-path) | Optional | Remove specific include file paths. -    [`misc:`](#misc) | Optional | Literal tool-specific controls. -    [`groups:`](#groups) | Optional | Start a nested list of groups. -    [`files:`](#files) | Optional | Start a list of files. - -**Example:** - -See [`files:`](#files) section. - -### `files:` - -Add source files to a project. - -`files:` | | Content -:---------------------------------------------------------|--------------|:------------------------------------ -`- file:` | **Required** | Name of the file. -    [`for-context:`](#for-context) | Optional | Include file for a list of *build* and *target* types. -    [`not-for-context:`](#not-for-context) | Optional | Exclude file for a list of *build* and *target* types. -    [`for-compiler:`](#for-compiler) | Optional | Include file for a list of compilers. -    [`language-C:`](#language-c) | Optional | Set the language standard for C source file compilation. -    [`language-CPP:`](#language-cpp) | Optional | Set the language standard for C++ source file compilation. -    [`optimize:`](#optimize) | Optional | Optimize level for code generation. -    [`debug:`](#debug) | Optional | Generation of debug information. -    [`warnings:`](#warnings) | Optional | Control generation of compiler diagnostics. -    [`define:`](#define) | Optional | Define symbol settings for code generation. -    [`undefine:`](#undefine) | Optional | Remove define symbol settings for code generation. -    [`add-path:`](#add-path) | Optional | Additional include file paths. -    [`del-path:`](#del-path) | Optional | Remove specific include file paths. -    [`misc:`](#misc) | Optional | Literal tool-specific controls. - -> **Note:** -> -> It is also possible to specify a [Linker Script](Linker-Script-Management.md). Files with the extension `.sct`, `.scf`, `.ld`, and `.icf` are recognized as Linker Script files. - -**Example:** - -Add source files to a project or a software layer. Used in `*.cproject.yml` and `*.clayer.yml` files. - -```yml -groups: - - group: "Main File Group" - not-for-context: # includes this group not for the following: - - .Release+Virtual # build-type 'Release' and target-type 'Virtual' - - .Test-DSP+Virtual # build-type 'Test-DSP' and target-type 'Virtual' - - +Board # target-type 'Board' - files: - - file: file1a.c - - file: file1b.c - define: - - a: 1 - undefine: - - b - optimize: size - - - group: "Other File Group" - files: - - file: file2a.c - for-context: +Virtual # include this file only for target-type 'Virtual' - define: - - test: 2 - - file: file2a.c - not-for-context: +Virtual # include this file not for target-type 'Virtual' - - file: file2b.c - - - group: "Nested Group" - groups: - - group: Subgroup1 - files: - - file: file-sub1-1.c - - file: file-sub1-2.c - - group: Subgroup2 - files: - - file: file-sub2-1.c - - file: file-sub2-2.c -``` - -It is also possible to include a file group for a specific compiler using [`for-compiler:`](#for-compiler) or a specific -target-type and/or build-type using [`for-context:`](#for-context) or [`not-for-context:`](#not-for-context). - -```yml -groups: - - group: "Main File Group" - for-compiler: AC6 # includes this group only for Arm Compiler 6 - files: - - file: file1a.c - - file: file2a.c - - - group: "Main File Group" - for-compiler: GCC # includes this group only for GCC Compiler - files: - - file: file1b.c - - file: file2b.c -``` - -### `layers:` - -Add a software layer to a project. Used in `*.cproject.yml` files. - -`layers:` | | Content -:---------------------------------------------------------|--------------|:------------------------------------ -[`- layer:`](#layer) | Optional | Path to the `*.clayer.yml` file that defines the layer. -    [`type:`](#layer---type) | Optional | Refers to an expected layer type. -    [`for-context:`](#for-context) | Optional | Include layer for a list of *build* and *target* types. -    [`not-for-context:`](#not-for-context) | Optional | Exclude layer for a list of *build* and *target* types. - -**Example:** - -```yml - layers: - # Socket - - layer: ./Socket/FreeRTOS+TCP/Socket.clayer.yml - for-context: - - +IP-Stack - - layer: ./Socket/WiFi/Socket.clayer.yml - for-context: - - +WiFi - - layer: ./Socket/VSocket/Socket.clayer.yml - for-context: - - +AVH - - # Board - - layer: ./Board/IMXRT1050-EVKB/Board.clayer.yml - for-context: - - +IP-Stack - # - +WiFi - - layer: ./Board/B-U585I-IOT02A/Board.clayer.yml - for-context: - - +WiFi - - layer: ./Board/AVH_MPS3_Corstone-300/Board.clayer.yml - for-context: - - +AVH -``` - -#### `layer:` - `type:` - -The `layer:` - `type:` is used in combination with the meta-data of the [`connections:`](#connections) to check the list of available `*.clayer.yml` files for matching layers. Instead of an explicit `layer:` node that specifies a `*.clayer.yml` file, the `type:` is used to search for matching layers with the `csolution` command `list layers`. - -**Example:** - -```yml - layers: - - type: Socket # search for matching layers of type `Socket` - - - type: Board # search for matching layers of type `Board` -``` - -When combined with [`variables:`](#variables) it is possible to define the required `*.clayer.yml` files at the level of the `*.csolution.yml` file. Refer to [`variables:`](#variables) for an example. - -### `components:` - -Add software components to a project or a software layer. Used in `*.cproject.yml` and `*.clayer.yml` files. - -`components:` | | Content -:---------------------------------------------------------|--------------|:------------------------------------ -`- component:` | **Required** | Name of the software component. -    [`for-context:`](#for-context) | Optional | Include component for a list of *build* and *target* types. -    [`not-for-context:`](#not-for-context) | Optional | Exclude component for a list of *build* and *target* types. -    [`language-C:`](#language-c) | Optional | Set the language standard for C source file compilation. -    [`language-CPP:`](#language-cpp) | Optional | Set the language standard for C++ source file compilation. -    [`optimize:`](#optimize) | Optional | Optimize level for code generation. -    [`debug:`](#debug) | Optional | Generation of debug information. -    [`warnings:`](#warnings) | Optional | Control generation of compiler diagnostics. -    [`define:`](#define) | Optional | Define symbol settings for code generation. -    [`undefine:`](#undefine) | Optional | Remove define symbol settings for code generation. -    [`add-path:`](#add-path) | Optional | Additional include file paths. -    [`del-path:`](#del-path) | Optional | Remove specific include file paths. -    [`misc:`](#misc) | Optional | Literal tool-specific controls. -    [`instances:`](#instances) | Optional | Add multiple instances of component configuration files (default: 1) - -**Example:** - -```yml -components: - - component: ARM::CMSIS:RTOS2:FreeRTOS&Cortex-M - - - component: ARM::RTOS&FreeRTOS:Config&CMSIS RTOS2 - - component: ARM::RTOS&FreeRTOS:Core&Cortex-M - - component: ARM::RTOS&FreeRTOS:Event Groups - - component: ARM::RTOS&FreeRTOS:Heap&Heap_5 - - component: ARM::RTOS&FreeRTOS:Stream Buffer - - component: ARM::RTOS&FreeRTOS:Timers - - - component: ARM::Security:mbed TLS - define: - - MBEDTLS_CONFIG_FILE: "aws_mbedtls_config.h" - - component: AWS::FreeRTOS:backoffAlgorithm - - component: AWS::FreeRTOS:coreMQTT - - component: AWS::FreeRTOS:coreMQTT Agent - - component: AWS::FreeRTOS:corePKCS11&Custom - define: - - MBEDTLS_CONFIG_FILE: "aws_mbedtls_config.h" -``` - -> **Note:** -> -> The name format for a software component is described under [Name Conventions - Component Name Conventions](#component-name-conventions). - -### `instances:` - -Allows to add multiple instances of a component and actually applies to configuration files. -Detailed description is [here](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_components_pg.html#Component_Instances) - -**Example:** - -```yml -components: - - component: USB:Device - instances: 2 -``` - -If the user selects multiple instances of the same component, all files with attribute `config` in the `*.PDSC` file -will be copied multiple times to the project. The name of the component (for example config_mylib.h) will get a postfix -`_n` whereby `n` is the instance number starting with 0. - -Instance 0: config_usb_device_0.h -Instance 1: config_usb_device_1.h - -The availability of instances in a project can be made public in the `RTE_Components.h` file. The existing way to extend -the `%Instance%` with the instance number `n`. - -## Pre/Post build steps - ->**Scheduled for CMSIS-Toolbox 2.1 - Q3'23** -Tbd: potentially map to CMake add_custom_command. - -### `execute:` - -Execute and external command for pre- or post-build steps (such as code signing). - -`- execute:` | | Content -:---------------------------------|:--------------|:------------------------------------ -`- execute:` description | **Required** | Execute an external command with description -    `os:` name | Optional | Executable on named operating systems (if omitted it is OS independent). -    `run:` name | Optional | Executable name, optionally with path to the tool. -    `args:` name | Optional | Executable arguments. -    `stop:` name | Optional | Stop on exit code. - -Potential usage before/after build: - -```yml -solution: - : - : - projects: - - execute: Generate Keys for TF-M - os: Linux - run: KeyGen.exe - - project: /security/TFM.cproject.yml - - project: /application/MQTT_AWS.cproject.yml - - execute: Copy output files - run: cp *.out ./output -``` - -Potential usage during build steps: - -```yml -project: - : - : - groups: - - group: "Main File Group" - files: - - execute: Generate file1a.c - run: xyz.exe - .... - - file: file1a.c -``` - -## `connections:` - -The `connections:` node contains meta-data that describes the compatiblity of `*.cproject.yml` and `*.clayer.yml` project parts. The `connections:` node lists functionality (drivers, pins, and other software or hardware resources). The node `consumes:` lists required functionality; the node `provides:` is the implemented functionality of that project part. - -This enables, for example, reference applications that work across a range of different hardware targets where: - -- The `*.cproject.yml` file of the reference application lists with the `connections:` node the required functionality with `consumes:`. - -- The `*.clayer.yml` project part lists with the `connections:` node the implemented functionality with `provides:`. - -This works across multiple levels, which means that a `*.clayer.yml` file could also require other functionality using `consumes:`. - -The `connections:` node is used to identify compatible software layers. These software layers could be stored in CMSIS software packs using the following structure: - -- A reference application described in a `*.cproject.yml` file could be provided in a git repository. This reference application uses software layers that are provided in CMSIS software packs. - -- A CMSIS Board Support Pack (BSP) contains a configured board layer desribed in a `*.clayer.yml` file. This software layer is pre-configured for a range of use-cases and provides drivers for I2C and SPI interfaces along with pin definitions and provisions for an Ardunio shield. - -- For a sensor, a CMSIS software pack contains the sensor middleware and software layer (`*.clayer.yml`) that describes the hardware of the Ardunio sensor shield. This shield can be applied to many different hardware boards that provide an Ardunio shield connector. - -This `connections:` node enables therefore software reuse in multiple ways: - -- The board layer can be used by many different reference applications, as the `provided:` functionlity enables a wide range of use cases. - -- The sensor hardware shield along with the middleware can be used across many different boards that provide an Ardunio shield connector along with board layer support. - -The structure of the `connections:` node is: - -`connections:` | | Description -:------------------------------------|--------------|:------------------------------------ -[- `connect:`](#connect) | **Required** | Lists specific functionality with a brief verbal description - -### `connect:` - -The `connect:` node describes one or more functionalities that belong together. - -`connect:` | | Description -:------------------------------------|--------------|:------------------------------------ -[`set:`](#set) | Optional | Specifies a *config-id*.*select* value that identifies a configuration option -`info:` | Optional | Verbal desription displayed when this connect is selected -[`provides:`](#provides) | Optional | List of functionality (*key*/*value* pairs) that are provided -[`consumes:`](#consumes) | Optional | List of functionality (*key*/*value* pairs) that are required - -### `set:` - -Some hardware boards have configuration settings (DIP switch or jumper) that configure interfaces. These settings have impact to the functionality (for example hardware interfaces). With `set:` *config-id*.*select* the possible configration options are considered when evaluating compatible `*.cproject.yml` and `*.clayer.yml` project parts. The **csolution - CMSIS Project Manager** iterates the `connect:` node with a `set:` *config-id*.*select* as described below: - -- For each *config-id* only one `connect:` node with a *select* value is active at a time. Each possible *select* value is checked for a matching configuration. - -- When project parts have a matching configuration, the `set:` value along with the `info:` is shown to the user. This allows the user to enable the correct hardware options. - -Refer to [Example: Sensor Shield](#example-sensor-shield) for a usage example. - -### `provides:` - -A user-defined *key*/*value* pair list of functionality that is implemented or provided by a `project:` or `layer:`. - -The **csolution - CMSIS Project Manager** combines all the *key*/*value* pairs that listed under `provides:` and matches it with the *key*/*value* pairs that are listed under `consumes:`. For *key*/*value* pairs listed under `provides:` the following rules exist for a match with `consumes:` *key*/*value* pair: - -- It is possible to omit the *value*. It matches with an identical *key* listed in `consumes:` -- A *value* is interpreted as number. Depending on the value prefix, this number must be: - - when `consumes:` *value* is a plain number, identical with this value. - - when `consumes:` *value* is prefixed with `+`, higher or equal then this *value* or the sum of all *values* in multiple `consumes:` nodes. - -### `consumes:` - -A user-defined *key*/*value* pair list of functionality that is requried or consumed by a `project:` or `layer:`. - -For *key*/*value* pairs listed under `consumed:` the following rules exist: - -- When no *value* is specified, it matches with any *value* of an identical *key* listed under `provides:`. -- A *value* is interpreted as number. This number must be identical in the `provides:` value pair. -- A *value* that is prefixed with `+` is interpreted as a number that is added together in case that the same *key* is listed multiple times under `consumes:`. The sum of this value must be lower or equal to the *value* upper limit of the `provides:` *key*. - -### Example: Board - -This `connections:` node of a board layer describes the available interfaces. The WiFi interface requires a CMSIS-RTOS2 function. - -```yml - connections:   # describes functionality of a board layer - - connect: WiFi interface - provides: - - CMSIS-Driver WiFi: - requires: - - CMSIS-RTOS2: - - - connect: SPI and UART interface - provides: - - CMSIS-Driver SPI: - - CMSIS-Driver UART: -``` - -### Example: Simple Project - -This shows a the `connections:` node of a complete application project that is composed of two software layers. - -*MyProject.cproject.yml* - -```yml - connections: - - connect: all resources - provides: - - RTOS2: # implements RTOS2 API interface - consumes: - - IoT_Socket: # requires IoT_Socket interface - - STDOUT: # requires STDOUT interface - - Heap: +30000 # requires additional 30000 bytes memory heap - : - layers: - - layer: MySocket.clayer.yml - - layer: MyBoard.clayer.yml -``` - -*MySocket.clayer.yml* - -```yml - connections: - - connect: - consumes: - - RTOS2: # requires RTOS2 API interface - - VSocket: # requires VSocket interface - - Heap: +20000 # requires additional 20000 bytes memory heap - provides: - - IoT_Socket: # provides IoT_Socket interface -``` - -*MyBoard.clayer.yml* - -```yml - connections: - - connect: - consumes: - - RTOS2: - provides: - - VSocket: - - STDOUT: - - Heap: 65536 -``` - -### Example: Sensor Shield - -This sensor shield layer provides a set of interfaces that are configurable. - -```yml - connections: -   - connect: I2C Interface 'Std' -    set: comm.I2C-Std - info: JP1=Off  JP2=Off - provides: -    - Sensor_I2C: -      consumes: -        - Ardunio_Uno_I2C: - -    - connect: I2C Interface 'Alt' -    set: comm.I2C-Alt - info: JP1=On  JP2=Off - provides: -    - Sensor_I2C: -      consumes: -        - Ardunio_Uno_I2C-Alt: - -    - connect: SPI Interface 'Alt' -    set: comm.SPI - info: JP2=On - provides: -    - Sensor_SPI: -      consumes: -        - Ardunio_Uno_SPI: - -   - connect: Sensor Interrupt INT0 -    set: SensorIRQ.0 - info: JP3=Off -     provides: -      - Sensor_IRQ: -   consumes: -      - Ardunio_Uno_D2: - -   - connect: Sensor Interrupt INT1 -    set: SensorIRQ.1 - info: JP3=On -     provides: -      - Sensor_IRQ: -   consumes: -      - Ardunio_Uno_D3: -``` - -## Generator (Proposal) - ->Note: Superseeded by [Generator%20(Proposal).md](Generator%20(Proposal).md) - ---> Requires Review - -### Workflow assumptions - -The composition of a solution of a solution should have the following steps: - -- Create `*.cproject.yml` files and the `*.csolution.yml` container that refers the projects. -- Select `device:` or `board:` (optionally by using `target-types:`) -- Add `components:` or `layers:` to the `*.cproject.yml` file -- For components that have configuration, run the generator in configuration mode - - change pinout, clock, resources, etc. - - reflect configuration in *.gpdsc file (and related settings files) - -> **Note:** -> -> Components can have multiple [instances](#instances). - -### Steps for component selection and configuration - -The following explains the generator workflow of CSolution / CBuild for configuration of components: - -1. User selects components in `*.cproject.yml` under `components:` - - When these components require generation, user is notified to run a generator. - - "CSolution Run GenID” is invoked for a list of components. - - CSolution generates `*.cgen.json` file that provides project context and a list of user-selected components. - -2. Running the Generator (for Component Configuration, i.e. pin selection) - - Generator reads `*.cgen.json` file - - User performs the configuration is done. - - Interactive mode (where a settings file is generated) - - Remote mode (where a settings file is an input) **IS THIS REALLY REQUIRED** - - Generator creates a `*.gpdsc` file that informs the CSolution tool about - - (a) the fact that a component is configured and has generated code, - - (b) additional components that are the result of some user configuration. - - Discussions: - - is a component list or a dependency list - - Generator might be VS Code plugin or web based - -3. User creates CBuild output with CSolution Convert command - - Both `*.cproject.yml` and `*.gpdsc` are read by Csolution and create the complete list of selected components. - - If `*.gpdsc` does not contain component information about a component that has `genId` and selected in - `*.cproject.yml` the generator configuration is incomplete. This can happen when a component is added at a later - step. - - Likewise the Generator can detect with the `` attribute that a component is longer required. - In this case the user is notified to run a generator. - -### Enhance Usability - -Add Run Generator buttons to Cclass descriptions. - -![Add Run Generator buttons to Cclass](./images/gen.png "Add Run Generator buttons to Cclass") - -### Workflow - -1. For `*.cproject.yml` files that contain selected `` with a `generator` or `genid` attribute the - `csolution` manager checks if a file with the name `.//RTE+/.cgen.json` exists. - - When this file is missing, it is required to use the command `csolution run genid` to start the generator. - - When this file exists, the `csolution` manager checks if the list of components with `genid` has changed. If this - is the case it is required to use the command `csolution run genid` to reconfigure generated components. -2. The command `csolution run genid` creates the file `.//RTE+/.cgen.json` and starts the - generator. The generator creates a `*.GDPSC` file along with other source files that are required - [as specified](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_generators_pg.html#element_generators). - -#### Example Content of `*.cgen.json` (in this case `STM32CubeMX.cgen.json`) - -The `*.cgen.json` file is passed to generator as argument. - -> **Note:** -> -> Shown is still a `*.yml` file, but the equivalent data would be formatted in `*.json` format. - -```yml -cgenerator: - device: STM32F407IGHx - board: NucleoF407 - solution: C:/tmp/MySolution/MySolution.csolution.yml - project: C:/tmp//MySolution/Blinky/Blinky.cproject.yml - context: .Debug+Nucelo # build-type and target-type of the current generated context - destination: C:/tmp/MySolution/Blinky/RTE+Nucelo/ - - packs: # packs that are used for the project - - pack: Keil::STM32F4xx_DFP@2.16.1 - path: C:/CMSIS-PACKS/Keil/STM32F4xx_DFP/2.16.1/ - - pack: Keil::STM32F4xx_BSP@2.1.1 - path: C:/CMSIS-PACKS/Keil/STM32F4xx_BSP/2.1.1/ - - components: # components that have a genid and are specified in *.cproject.yml - - component: Device:STM32Cube HAL:Common - - component: Board:LED - - component: Device:HAL:UART - instances: - - WiFi: 0 - setup: wifi-config.json - baudrate: 19200 - - Debug: 2 - baudrate: 57600 -``` - -### Changes to the *.GPDSC file - -To indicate that a component was generated due to a user selection in `*.cproject.yml`, the `component` element is -extended with `User` attribute. When set to `1` it indicates that a component is included due to the selection in -`*.cproject.yml`. - -When a user removes this component in the `*.cproject.yml`, the CSolution could detect that a Run command should be -executed. - -### Changes to the *.PDSC file - -- Add `` to `` element. The `key` is used to invoke the generator and pass the `.cgen.json` file. - - on Windows to a registry key to invoke the generator tool - - on Linux and MacOS to an environment variable that specifies how to invoke the generator tool - - todo: Web based tools? -- Add `genId` to `component` element. Indicates that a component is managed by the ``. -- Add `inherent` to `component` element. Indicates that a component is managed by the `` - Components with inherent attribute are not selectable by the user (and could be managed by the ``). - Components with `inherent` attribute have the following behavior: - - Are selected when a condition requires this component. - - Are de-selected when a no condition requires this component. - - IDE's may choose to hide such components in the RTE selection (default might be to show it). -- Add new file category: - - `genParms` template parameters - - `genInput` source templates for the generator and other related input files for the generator - -**Example:** - -```xml - - - - ST Microelectronics: STCubeMX Environment - STCubeMX_CGENFILE - - url - $PRTE/Device - - - - - - - - - STM32F4xx Hardware Abstraction Layer (HAL) and Drivers - STM32F412 Board Abstraction Layer (HAL) and Drivers - - - - - Common HAL driver - - #define RTE_DEVICE_HAL_COMMON - - - - - - - - - - - - Analog-to-digital converter (ADC) HAL driver - - #define RTE_DEVICE_HAL_ADC - - - - - - - - - - : - - STMicroelectronics STM32F4 Discovery Kit - http://www.st.com/st-web-ui/static/active/en/resource/technical/document/data_brief/DM00037955.pdf - - LED Interface for STMicroelectronics STM32F4-Discovery Kit - - - - - - - -``` - -**Example *.gpdsc file** - -```xml - - - - Keil - FrameworkCubeMX - STM32CubeMX generated pack description - project-path - - - - Generated: 23/09/2021 14:18:05 - - - - - STM32CubeMX Environment -