diff --git a/.ci/README.md b/.ci/README.md index 28984ee..4f70a09 100644 --- a/.ci/README.md +++ b/.ci/README.md @@ -6,13 +6,12 @@ Content of `.ci` Directory | Description ## GitHub Action Workflows -The [**`GitHub Actions`**](https://docs.github.com/en/actions) in the directory `.github/workflows` are the scripts for the CI tests. These scripts contain detailed comments about each step that is executed. -Projects in the Arm csolution-examples uses the **`ARM compiler (AC6)`** as well as the **`GCC`** toolchains. Not all workflows are using both compilers. +The [**GitHub Actions**](https://docs.github.com/en/actions) workflows in the directory `.github/workflows` run the CI tests. The examples use the **Arm Compiler (AC6)**, **GCC**, and **CLANG** toolchains. The toolchains tested depend on the example. -- **`Hello-CI.yml`** implements a build and execution test. The build steps are using **`AC6`** and **`GCC`** toolchains. The execution tests runs on [**`Arm Virtual Hardware - Fixed Virtual Platforms (AVH FVP)`**](https://arm-software.github.io/AVH/main/simulation/html/index.html) simulation models. The directory **`FVP`** contains configuration files for the **`FVP simulation models`**. +- **`Hello-CI.yml`** builds and executes the Debug and Release variants with **AC6**, **GCC**, and **CLANG**. The execution tests run on an [Arm Virtual Hardware Fixed Virtual Platform (AVH FVP)](https://arm-software.github.io/AVH/main/simulation/html/index.html). The directory `FVP` contains the simulation model configuration. -- **`DualCore-CI.yml`** implements a build test for a DualCore (**`cm0plus, cm4`**) project by using the **`AC6`** toolchain. The output of this build test is stored as artifact and can be downloaded. +- **`DualCore-CI.yml`** builds the dual-core Cortex-M0+ and Cortex-M4 project with **AC6**. The build output is stored as a downloadable artifact. -- **`SimpleTZ-CI.yml`** implements build tests for a **`TrustZone`** based project by using the **`AC6`** and **`GCC`** toolchains. The execution tests runs on [**`Arm Virtual Hardware - Fixed Virtual Platforms (AVH FVP)`**](https://arm-software.github.io/AVH/main/simulation/html/index.html) simulation models. The directory **`FVP`** contains configuration files for the **`FVP simulation models`**. +- **`SimpleTZ-CI.yml`** builds and executes the Debug and Release target sets of the TrustZone project with **AC6**. The execution tests run on an [Arm Virtual Hardware Fixed Virtual Platform (AVH FVP)](https://arm-software.github.io/AVH/main/simulation/html/index.html) using the configuration in the `FVP` directory. -- **`CubeMX-CI.yml`** implements a build test for a **`CubeMX`** generated project by using only the **`AC6`** toolchain. +- **`CubeMX-CI.yml`** builds the CubeMX-generated project with **AC6**. diff --git a/.github/workflows/CubeMX-CI.yml b/.github/workflows/CubeMX-CI.yml index f65f1f7..bf033cb 100644 --- a/.github/workflows/CubeMX-CI.yml +++ b/.github/workflows/CubeMX-CI.yml @@ -20,15 +20,15 @@ jobs: steps: - name: Checkout repo - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 #v7.0.1 + uses: actions/checkout@v7.0.1 - name: Install tools - uses: ARM-software/cmsis-actions/vcpkg@8a50b77681a484568e08f31fb7c2285c4735f682 #v1.3 + uses: ARM-software/cmsis-actions/vcpkg@v1.3 with: config: ".ci/vcpkg-configuration.json" - name: Activate Arm tool license - uses: ARM-software/cmsis-actions/armlm@8a50b77681a484568e08f31fb7c2285c4735f682 #v1.3 + uses: ARM-software/cmsis-actions/armlm@v1.3 - name: Build project with AC6 working-directory: ./CubeMX/ diff --git a/.github/workflows/DualCore-CI.yml b/.github/workflows/DualCore-CI.yml index bf2c473..f239467 100644 --- a/.github/workflows/DualCore-CI.yml +++ b/.github/workflows/DualCore-CI.yml @@ -20,22 +20,22 @@ jobs: steps: - name: Checkout repo - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 #v7.0.1 + uses: actions/checkout@v7.0.1 - name: Install tools - uses: ARM-software/cmsis-actions/vcpkg@8a50b77681a484568e08f31fb7c2285c4735f682 #v1.3 + uses: ARM-software/cmsis-actions/vcpkg@v1.3 with: config: ".ci/vcpkg-configuration.json" - name: Activate Arm tool license - uses: ARM-software/cmsis-actions/armlm@8a50b77681a484568e08f31fb7c2285c4735f682 #v1.3 + uses: ARM-software/cmsis-actions/armlm@v1.3 - name: Build HelloWorld with AC6 and all contexts working-directory: ./DualCore/ run: cbuild HelloWorld.csolution.yml --packs --toolchain AC6 - name: Upload HelloWorld AC6 build Artifacts - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a #v7.0.1 + uses: actions/upload-artifact@v7.0.1 with: name: HelloWorld_AC6 path: | diff --git a/.github/workflows/Hello-CI.yml b/.github/workflows/Hello-CI.yml index 8d08b39..730f72e 100644 --- a/.github/workflows/Hello-CI.yml +++ b/.github/workflows/Hello-CI.yml @@ -31,18 +31,18 @@ jobs: steps: - name: Checkout repo - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 #v7.0.1 + uses: actions/checkout@v7.0.1 - name: Install tools - uses: ARM-software/cmsis-actions/vcpkg@8a50b77681a484568e08f31fb7c2285c4735f682 #v1.3 + uses: ARM-software/cmsis-actions/vcpkg@v1.3 with: config: ".ci/vcpkg-configuration.json" - name: Activate Arm tool license - uses: ARM-software/cmsis-actions/armlm@8a50b77681a484568e08f31fb7c2285c4735f682 #v1.3 + uses: ARM-software/cmsis-actions/armlm@v1.3 - name: Set up Python - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 #v7.0.0 + uses: actions/setup-python@v7.0.0 with: python-version: '3.14' diff --git a/.github/workflows/SimpleTZ-CI.yml b/.github/workflows/SimpleTZ-CI.yml index a60f1b2..0752b90 100644 --- a/.github/workflows/SimpleTZ-CI.yml +++ b/.github/workflows/SimpleTZ-CI.yml @@ -31,24 +31,24 @@ jobs: steps: - name: Checkout repo - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 #v7.0.1 + uses: actions/checkout@v7.0.1 - name: Install tools - uses: ARM-software/cmsis-actions/vcpkg@8a50b77681a484568e08f31fb7c2285c4735f682 #v1.3 + uses: ARM-software/cmsis-actions/vcpkg@v1.3 with: config: ".ci/vcpkg-configuration.json" - name: Activate Arm tool license - uses: ARM-software/cmsis-actions/armlm@8a50b77681a484568e08f31fb7c2285c4735f682 #v1.3 + uses: ARM-software/cmsis-actions/armlm@v1.3 - name: Set up Python - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 #v7.0.0 + uses: actions/setup-python@v7.0.0 with: python-version: '3.14' - name: Build project CM33_s and CM33_ns for build-type ${{ matrix.build.type }} with ${{ matrix.compiler.name }} working-directory: ./SimpleTrustZone/ - run: cbuild SimpleTZ.csolution.yml --packs --context .${{ matrix.build.type }}+AVH --toolchain ${{ matrix.compiler.name }} + run: cbuild SimpleTZ.csolution.yml --packs --active AVH@${{ matrix.build.type }} --toolchain ${{ matrix.compiler.name }} - name: Execute project CM33_s and CM33_ns for build-type ${{ matrix.build.type }} with ${{ matrix.compiler.name }} using FVP_MPS2_Cortex-M33 diff --git a/.gitignore b/.gitignore index 24a97b2..0ba8642 100644 --- a/.gitignore +++ b/.gitignore @@ -51,20 +51,48 @@ Module.symvers Mkfile.old dkms.conf +# Clangd +.clangd + +# uv2csolution generated log file +uv2csolution.log + # CMSIS Solution files and folders not to be tracked +# generated RTE files +**/RTE/_*/RTE_Components.h +**/RTE/_*/Pre_Include_*.h + # default directory of build artifacts **/out # directory containing intermediate files to be regenerated **/tmp -# -.clangd + # Update config files must be merged before commit *.update@* + +# cbuild output files *.cbuild.yml *.cbuild-idx.yml *.cbuild-run.yml *.cbuild-set.yml -# RTE_Components.h files are always regenerated and must not be checked in -RTE_Components.h -# outdated file types + +# .vscode JSON and debug adapter files generated by CMSIS Solution even if opened in a subfolder +**/.vscode/cmsis.json +**/.vscode/launch.json +**/.vscode/tasks.json +**/.vscode/settings.json +.cmd.jlink + +# Exception for line 2: "*.d" +# CMSIS Solution drop-ins are user managed source files, despite the directory suffix ".d" +!.vscode.d/ + +# legacy intermediate project file *.cprj + +# SDS files +*.[sS][dD][sS] + +# FVP model generated files when using with SDS +**/__pycache__/ +sdsio.log diff --git a/CubeMX/CubeMX.csolution.yml b/CubeMX/CubeMX.csolution.yml index d0ac75d..31fc519 100644 --- a/CubeMX/CubeMX.csolution.yml +++ b/CubeMX/CubeMX.csolution.yml @@ -1,36 +1,54 @@ -solution: - created-for: CMSIS-Toolbox@2.6.0 - description: Simple CubeMX example - cdefault: - compiler: AC6 # currently required for components Compiler:I/O - - # it is recommended to list the pack or packs that define the device or board used in the csolution.yml file - packs: - - pack: ARM::CMSIS@^6.1.0 - - pack: Keil::B-U585I-IOT02A_BSP@^2.0.0 - - pack: Keil::STM32U5xx_DFP@^3.0.0 - - pack: ARM::CMSIS-RTX@^5.9.0 - target-types: - - type: MyBoard_ROM # My evaluation kit (Execution from ROM) - board: B-U585I-IOT02A # Board name as defined by the pack - variables: - - regions_header: RTE/Device/STM32U585AIIx/regions_B-U585I-IOT02A_ROM.h - - - type: MyBoard_RAM # My evaluation kit (Execution from RAM) - board: B-U585I-IOT02A # Board name as defined by the pack - variables: - - regions_header: RTE/Device/STM32U585AIIx/regions_B-U585I-IOT02A_RAM.h - define: - - VECT_TAB_SRAM - - build-types: # defines toolchain options for 'debug' and 'release' - - type: Debug - debug: on - optimize: debug - - - type: Release - debug: off - optimize: balanced - - projects: # list related projects - - project: ./CubeMX.cproject.yml +solution: + created-for: CMSIS-Toolbox@2.14.0 + description: Simple CubeMX example + cdefault: + compiler: AC6 # currently required for components Compiler:I/O + + # it is recommended to list the pack or packs that define the device or board used in the csolution.yml file + packs: + - pack: ARM::CMSIS@^6.1.0 + - pack: Keil::B-U585I-IOT02A_BSP@^2.0.0 + - pack: Keil::STM32U5xx_DFP@^3.0.0 + - pack: ARM::CMSIS-RTX@^5.9.0 + target-types: + - type: MyBoard_ROM # My evaluation kit (Execution from ROM) + board: B-U585I-IOT02A # Board name as defined by the pack + variables: + - regions_header: RTE/Device/STM32U585AIIx/regions_B-U585I-IOT02A_ROM.h + target-set: + - set: Debug + images: + - project-context: CubeMX.Debug + - set: Release + images: + - project-context: CubeMX.Release + + - type: MyBoard_RAM # My evaluation kit (Execution from RAM) + board: B-U585I-IOT02A # Board name as defined by the pack + variables: + - regions_header: RTE/Device/STM32U585AIIx/regions_B-U585I-IOT02A_RAM.h + define: + - VECT_TAB_SRAM + target-set: + - set: Debug + images: + - project-context: CubeMX.Debug + - set: Release + images: + - project-context: CubeMX.Release + + build-types: + - type: Debug # toolchain options for 'debug' + debug: on + optimize: debug + misc: + - for-compiler: AC6 + C: + - -funwind-tables # ensure reliable stack unwinding with GDB + + - type: Release # toolchain options for 'release' + debug: off + optimize: balanced + + projects: # list related projects + - project: ./CubeMX.cproject.yml diff --git a/CubeMX/README.md b/CubeMX/README.md index 3cf6fbd..e8d1692 100644 --- a/CubeMX/README.md +++ b/CubeMX/README.md @@ -8,13 +8,12 @@ This project uses two different target-types to configure execution from Flash R ### Tools -- [CMSIS-Toolbox 2.6.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases) or higher -- [Keil MDK 5.40](https://www2.keil.com/mdk5/) or higher +- [CMSIS-Toolbox 2.14.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases) or higher +- [Keil Studio](https://marketplace.visualstudio.com/items?itemName=Arm.keil-studio-pack) - [STM32CubeMX 6.11](https://www.st.com/en/development-tools/stm32cubemx.html) or higher ->**Note:** -> -> This example uses the Arm Compiler 6 (AC6). [Using GCC Compiler](#using-gcc-compiler) explains how to configure for different compiler. A similar process also works for IAR. +> [!NOTE] +> This example uses the Arm Compiler 6 (AC6). [Using GCC Compiler](#using-gcc-compiler) explains how to configure it for a different compiler. A similar process also works for IAR. ### Packs @@ -22,10 +21,10 @@ This project uses two different target-types to configure execution from Flash R ## Build Project -This command builds the project and downloads missing packs. If the file `CubeMX.cbuild-set.yml` is missing it creates this file with the context-set selection of the first `target-type` and the first `build-type`. +Build the `Debug` target set for the `MyBoard_ROM` target and download missing packs with: ```bash -> cbuild setup CubeMX.csolution.yml --context-set --packs +> cbuild CubeMX.csolution.yml --active MyBoard_ROM@Debug --packs ``` ## Run CubeMX @@ -33,17 +32,16 @@ This command builds the project and downloads missing packs. If the file `CubeMX To change the device configuration, start STM32CubeMX using the following command. ```bash -> csolution CubeMX.csolution.yml run --generator CubeMX --context-set +> csolution CubeMX.csolution.yml run --generator CubeMX --active MyBoard_ROM@Debug ``` -For using CubeMX refer to the documentation -[**CMSIS-Toolbox > Configure STM32 Devices with CubeMX**](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/tree/main/docs/CubeMX). +For information about using CubeMX, refer to +[**CMSIS-Toolbox > Configure STM32 Devices with CubeMX**](https://open-cmsis-pack.github.io/cmsis-toolbox/CubeMX/). The source code generated by CubeMX is imported using the file [STM32CubeMX\\CubeMX.cgen.yml](./STM32CubeMX/MyBoard_ROM/CubeMX.cgen.yml). This allows you to create different settings for each target, for example evaluation board and custom hardware. ->**Note:** -> -> Refer to the pack overview page, for example the [STM32F4_DFP](https://www.keil.arm.com/packs/stm32f4xx_dfp-keil) for information on how to use an IDE workflow with CubeMX. +> [!NOTE] +> Refer to the [STM32U5xx_DFP pack overview](https://www.keil.arm.com/packs/stm32u5xx_dfp-keil) for information on how to use an IDE workflow with CubeMX. ## Execute Project @@ -51,16 +49,16 @@ You may use the debugger of choice for executing this program. ## Using GCC Compiler -By default this project is the Arm Compiler 6 (AC6). Using STM32CubeMX it can be reconfigured for the GCC or IAR compiler. To configure it for the GCC compiler execute these steps: +By default, this project uses Arm Compiler 6 (AC6). It can be reconfigured for the GCC or IAR compiler using STM32CubeMX. To configure it for GCC, follow these steps: - In the file [`CubeMX.csolution.yml`](./CubeMX.csolution.yml) set `compiler: GCC`. -- Launch the STM32CubeMX generator with this CMSIS-Toolbox command: `csolution .csolution.yml run -g CubeMX -c ` +- Launch the STM32CubeMX generator with this CMSIS-Toolbox command: `csolution .csolution.yml run -g CubeMX -a @` - In STM32CubeMX: - Open from the menu Project Manager - Project - Toolchain/IDE: - Select STM32CubeIDE and disable Generate Under Root. - Click GENERATE CODE to recreate the CubeMX generated files for the GCC compiler. -- In the file [CubeMX.cproject.yml](./CubeMX.cproject.yml), update `linker:` node to reference the GCC linker script generated by CubeMX, typically found in folder `./STM32CubeMX//STM32CubeMX/STM32CubeIDE`. You may customize this linker script to meet your project's specific needs, but it should remain consistent with the CubeMX-generated startup and system files. -- [Rebuild the project](#build-project) using the CMSIS-Toolbox command `cbuild` with the option `--rebuild`. +- In the file [CubeMX.cproject.yml](./CubeMX.cproject.yml), update the `linker:` node to reference the GCC linker script generated by CubeMX, typically found in the folder `./STM32CubeMX//STM32CubeMX/STM32CubeIDE`. You may customize this linker script to meet your project's specific needs, but it should remain consistent with the CubeMX-generated startup and system files. +- Rebuild the selected target set with `cbuild CubeMX.csolution.yml --active @ --rebuild`. diff --git a/DualCore/HelloWorld.csolution.yml b/DualCore/HelloWorld.csolution.yml index bccefdb..84ad887 100644 --- a/DualCore/HelloWorld.csolution.yml +++ b/DualCore/HelloWorld.csolution.yml @@ -1,5 +1,5 @@ solution: - created-for: CMSIS-Toolbox@2.12.0 + created-for: CMSIS-Toolbox@2.14.0 cdefault: # List of tested compilers that can be selected @@ -31,11 +31,15 @@ solution: start-pname: cm4 build-types: - - type: Debug + - type: Debug # toolchain options for 'debug' debug: on optimize: debug + misc: + - for-compiler: AC6 + C: + - -funwind-tables # ensure reliable stack unwinding with GDB - - type: Release + - type: Release # toolchain options for 'release' debug: off optimize: balanced diff --git a/DualCore/README.md b/DualCore/README.md index 153e023..5e062b0 100644 --- a/DualCore/README.md +++ b/DualCore/README.md @@ -1,14 +1,13 @@ # Dual Core project -This example generates **HelloWorld** executables for the **FRDM-K32L3A6** evaluation board. The used **K32L3** microcontroller is a dual-core MCU ([**Cortex-M0plus**](https://developer.arm.com/Processors/Cortex-M0-Plus) and [**Cortex-M4**](https://developer.arm.com/Processors/Cortex-M4)) +This example generates **HelloWorld** executables for the **FRDM-K32L3A6** evaluation board. The **K32L3** microcontroller is a dual-core MCU with a [**Cortex-M0+**](https://developer.arm.com/Processors/Cortex-M0-Plus) and a [**Cortex-M4**](https://developer.arm.com/Processors/Cortex-M4). ## Prerequisites ### Tools -- [CMSIS-Toolbox 2.6.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases) or higher +- [CMSIS-Toolbox 2.14.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases) or higher - Arm Compiler 6.22 or higher -- GCC Compiler 13.2.1 or higher ### Packs @@ -18,8 +17,8 @@ This example generates **HelloWorld** executables for the **FRDM-K32L3A6** evalu The project is generated using the [CMSIS-Toolbox](https://open-cmsis-pack.github.io/cmsis-toolbox/build-overview) and is defined in [`csolution`](https://open-cmsis-pack.github.io/cmsis-toolbox/YML-Input-Format) format: -- [`HelloWorld.csolution.yml`](./HelloWorld.csolution.yml) lists the required packs, defines, hardware targets, and the build-types (along with the compiler). -- [`./cm0plus/HelloWorld_cm0plus.cproject.yml`](./cm0plus/HelloWorld_cm0plus.cproject.yml) defines the source files and the software components for the **Cortex-M0plus** core. +- [`HelloWorld.csolution.yml`](./HelloWorld.csolution.yml) lists the required packs and defines the hardware target, build types, compiler, and target set that groups both core images and configures the debugger. +- [`./cm0plus/HelloWorld_cm0plus.cproject.yml`](./cm0plus/HelloWorld_cm0plus.cproject.yml) defines the source files and the software components for the **Cortex-M0+** core. - [`./cm4/HelloWorld_cm4.cproject.yml`](./cm4/HelloWorld_cm4.cproject.yml) defines the source files and the software components for the **Cortex-M4** core. ## Generate the project binaries @@ -30,4 +29,4 @@ The project is generated using the [CMSIS-Toolbox](https://open-cmsis-pack.githu ## Execute Project -You may use the debugger of choice for executing this program. +Select the `FRDM-K32L3A6` target with `--active FRDM-K32L3A6` to build the Debug application containing both core images. The target set configures MCU-Link with pyOCD for downloading and debugging the application. diff --git a/Hello/Hello.csolution.yml b/Hello/Hello.csolution.yml index 6670ad1..2b96d4e 100644 --- a/Hello/Hello.csolution.yml +++ b/Hello/Hello.csolution.yml @@ -1,36 +1,40 @@ -solution: - created-for: CMSIS-Toolbox@2.6.0 - description: Print Hello World and a counter value via UART - cdefault: - - select-compiler: # list of tested compilers - - compiler: AC6 - - compiler: GCC - - compiler: CLANG - - compiler: GCC # selected compiler - - # It is recommended to list the pack or packs that define the device or board used in the csolution.yml file - packs: - - pack: ARM::CMSIS - - pack: ARM::CMSIS-RTX - - pack: ARM::V2M_MPS3_SSE_300_BSP # Corstone-300 (Cortex-M55) - - pack: ARM::CMSIS-Compiler # For retargeting stdout to UART - - - target-types: - - type: CS300 # Runs on Arm Virtual Hardware - device: ARM::SSE-300-MPS3 - - # add more hardware targets (don't forget to add the required packs) - build-types: # defines toolchain options for 'debug' and 'release' - - type: Debug - debug: on - optimize: debug - - - type: Release - debug: off - optimize: balanced - - projects: # list related projects - - project: ./Hello.cproject.yml +solution: + created-for: CMSIS-Toolbox@2.14.0 + description: Print Hello World and a counter value via UART + cdefault: + + select-compiler: # list of tested compilers + - compiler: AC6 + - compiler: GCC + - compiler: CLANG + + compiler: GCC # selected compiler + + # It is recommended to list the pack or packs that define the device or board used in the csolution.yml file + packs: + - pack: ARM::CMSIS + - pack: ARM::CMSIS-RTX + - pack: ARM::V2M_MPS3_SSE_300_BSP # Corstone-300 (Cortex-M55) + - pack: ARM::CMSIS-Compiler # For retargeting stdout to UART + + + target-types: + - type: CS300 # Runs on Arm Virtual Hardware + device: ARM::SSE-300-MPS3 + + # add more hardware targets (don't forget to add the required packs) + build-types: + - type: Debug # toolchain options for 'debug' + debug: on + optimize: debug + misc: + - for-compiler: AC6 + C: + - -funwind-tables # ensure reliable stack unwinding with GDB + + - type: Release # toolchain options for 'release' + debug: off + optimize: balanced + + projects: # list related projects + - project: ./Hello.cproject.yml diff --git a/Hello/README.md b/Hello/README.md index cac273f..4ec473c 100644 --- a/Hello/README.md +++ b/Hello/README.md @@ -6,9 +6,10 @@ This project prints "Hello World" and a counter value via the UART output. It is ### Tools -- [CMSIS-Toolbox 2.6.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases) or higher +- [CMSIS-Toolbox 2.14.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases) or higher - Arm Compiler 6.22 or higher - GCC Compiler 13.2.1 or higher +- CLANG 22.1 or higher - Arm Virtual Hardware for Corstone-300 v11.26.11 or higher ### Packs @@ -19,12 +20,11 @@ This project prints "Hello World" and a counter value via the UART output. It is The project is generated using the [CMSIS-Toolbox](https://open-cmsis-pack.github.io/cmsis-toolbox/build-overview) and is defined in [`csolution`](https://open-cmsis-pack.github.io/cmsis-toolbox/YML-Input-Format) format: -- [`Hello.csolution.yml`](./Hello.csolution.yml) lists the required packs, defines,hardware targets, and thebuild-types (along with the compiler). +- [`Hello.csolution.yml`](./Hello.csolution.yml) lists the required packs and defines the hardware targets, build types, and supported compilers. - [`Hello.cproject.yml`](./Hello.cproject.yml) defines the source files and the software components. -> **Note:** -> -> The project also builds with the GCC compiler. +> [!NOTE] +> The project supports the AC6, GCC, and CLANG compilers. ## Generate project binaries @@ -32,9 +32,10 @@ The project is generated using the [CMSIS-Toolbox](https://open-cmsis-pack.githu > cbuild Hello.csolution.yml --packs --toolchain AC6 ``` ->**Note:** During the build process required packs may be downloaded. +> [!NOTE] +> During the build process, required packs may be downloaded. -## Execute the project on ARM Virtual Hardware +## Execute the project on Arm Virtual Hardware The project is configured for execution on [**Arm Virtual Hardware**](https://developer.arm.com/Tools%20and%20Software/Arm%20Virtual%20Hardware) which removes the requirement for a physical hardware board. @@ -43,19 +44,15 @@ The project is configured for execution on [**Arm Virtual Hardware**](https://de #### For debug type ```bash -> FVP_Corstone_SSE-300 -f FVP/FVP_Corstone_SSE-300/fvp-config.txt -a ./out/Debug/Hello.axf +> FVP_Corstone_SSE-300 -f ../FVP/FVP_Corstone_SSE-300/fvp_config.txt -a ./out/Hello/CS300/Debug/Hello.axf ``` #### For release type ```bash -> FVP_Corstone_SSE-300 -f FVP/FVP_Corstone_SSE-300/fvp-config.txt -a ./out/Release/Hello.axf +> FVP_Corstone_SSE-300 -f ../FVP/FVP_Corstone_SSE-300/fvp_config.txt -a ./out/Hello/CS300/Release/Hello.axf ``` -### Execute this project in [**Keil Studio Cloud**](https://studio.keil.arm.com/) +### Use this project with Keil Studio -- Keil Studio Cloud integrates also the Arm Virtual Hardware for FVP_Corstone_SSE-300/_Ethos-U55/_Ethos-U65 models. The steps to use the example are: - - Start [Keil Studio Cloud](https://studio.keil.arm.com/) and login to the system using your account. - - Use **File - Clone** and enter the URL: (https://github.com/Open-CMSIS-Pack/csolution-examples). - - Select from the drop-down *Target hardware*: **Corstone SSE-300 (Cortex-M55, Ethos-U55, Ethos-U65)** - - Click **Run project** which executes the project build step and then starts running on Arm Virtual Hardware. +Install [Keil Studio](https://marketplace.visualstudio.com/items?itemName=Arm.keil-studio-pack) from the Visual Studio Marketplace, clone this repository, and open `Hello.csolution.yml` in VS Code. Keil Studio provides the CMSIS solution, build, and debug tooling required to work with the project. diff --git a/README.md b/README.md index 8f44517..c7242de 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-green?label=License)](https://github.com/Open-CMSIS-Pack/csolution-examples/blob/main/LICENSE-Apache-2.0) [![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD--3--Clause-green?label=License)](https://github.com/Open-CMSIS-Pack/csolution-examples/blob/main/LICENSE-BSD-3-Clause) -[![Hello: Test Build and Execution test](https://img.shields.io/github/actions/workflow/status/Open-CMSIS-Pack/csolution-examples/Hello-CI.yml?logo=arm&logoColor=0091bd&label=Hello:%20Test%20Build%20and%20Execution)](/.github/workflows/Hello-CI.yml) +[![Hello: Test Build and Execution](https://img.shields.io/github/actions/workflow/status/Open-CMSIS-Pack/csolution-examples/Hello-CI.yml?logo=arm&logoColor=0091bd&label=Hello:%20Test%20Build%20and%20Execution)](/.github/workflows/Hello-CI.yml) [![DualCore: Test Build](https://img.shields.io/github/actions/workflow/status/Open-CMSIS-Pack/csolution-examples/DualCore-CI.yml?logo=arm&logoColor=0091bd&label=DualCore:%20Test%20Build)](/.github/workflows/DualCore-CI.yml) [![CubeMX: Test Build](https://img.shields.io/github/actions/workflow/status/Open-CMSIS-Pack/csolution-examples/CubeMX-CI.yml?logo=arm&logoColor=0091bd&label=CubeMX:%20Test%20and%20Build)](/.github/workflows/CubeMX-CI.yml) [![SimpleTZ: Test Build and Execution](https://img.shields.io/github/actions/workflow/status/Open-CMSIS-Pack/csolution-examples/SimpleTZ-CI.yml?logo=arm&logoColor=0091bd&label=SimpleTZ:%20Test%20Build%20and%20Execution)](/.github/workflows/SimpleTZ-CI.yml) @@ -11,12 +11,15 @@ This is a collection of [CMSIS-Toolbox](https://open-cmsis-pack.github.io/cmsis- ## Tool Requirements -The examples use **CMSIS-Toolbox 2.13.0** or higher and require additional tools such as CMake, Ninja, Arm Compiler 6, GCC Compiler, and Arm Fixed Virtual Platforms (AVH-FVP). +The examples use **CMSIS-Toolbox 2.14.0** or higher. Depending on the example, additional tools include CMake, Ninja, Arm Compiler 6, GCC, CLANG, Arm Virtual Hardware Fixed Virtual Platforms (AVH FVP), and STM32CubeMX. Refer to the README of each example for its specific requirements. Refer to [**Installation of the CMSIS-Toolbox**](https://open-cmsis-pack.github.io/cmsis-toolbox/installation) for information on the setup of a development environment with these tools. When using VS Code with the [Arm Environment Manager](https://marketplace.visualstudio.com/items?itemName=Arm.environment-manager) the required tools are installed based on the settings in the file [`vcpkg-configuration.json`](./vcpkg-configuration.json) using the [Arm Tools Artifactory](https://artifacts.tools.arm.com/). +!!! Note + The Debug build type includes workarounds for known debugger issues. Refer to [CMSIS-Toolbox Troubleshooting](https://open-cmsis-pack.github.io/cmsis-toolbox/Troubleshooting/#stack-unwinding-fails-or-hangs) for details. + ## Project Examples Examples in this repository: @@ -26,36 +29,26 @@ Examples in this repository: [Hello](./Hello) | A simple project to get started. Requires no hardware as it runs on [AVH-FVP](https://github.com/ARM-software/AVH) simulation models. [DualCore](./DualCore) | Application with multiple processors that runs on the [NXP FRDM-K32L3A6](https://www.keil.arm.com/boards/nxp-frdm-k32l3a6-989d2e5/projects/) board. [SimpleTrustZone](./SimpleTrustZone) | Simple TrustZone example that shows the concept of secure and non-secure projects. Runs on [AVH-FVP](https://github.com/ARM-software/AVH) simulation models. -[CubeMX](./CubeMX) | Project that uses [STM32Cube](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/tree/main/docs/CubeMX.md) for device configuration and contains a RAM and ROM target. +[CubeMX](./CubeMX) | Project that uses [STM32CubeMX](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/tree/main/docs/CubeMX.md) for device configuration and contains a RAM and ROM target. Each *csolution project* example shows different aspects of the CMSIS-Toolbox. For example, the [CubeMX](./CubeMX) *csolution project* contains two targets that show RAM and ROM execution. ## Build Projects -Before you build projects, ensure that the pack index on your local computer is up-to-date with the command. - -```txt -> cpackget update-index -``` - -The project files contain a list of software packs that are used. When using the `cbuild` tool option `--packs` these packs are downloaded during the build process as shown in the following example command line: +The project files contain a list of software packs that are used. When using the `cbuild` tool option `--packs` these packs are downloaded during the build process as shown in the following example command line: ```txt -> cbuild Hello.csolution.yml --packs --context-set --toolchain AC6 --rebuild +> cbuild Hello/Hello.csolution.yml --packs --toolchain AC6 --rebuild ``` ## Template Projects -The directory [Templates](./Templates) may be used as starting point for different types of embedded applications: simple single core, multi-core, TrustZone, and unit test. +The directory [Templates](./Templates) contains structural templates for simple single-core, multi-core, TrustZone, and unit-test projects. They are not ready-to-build examples, but may be used as a starting point for an application. ## GitHub Action Workflows -The directory [.ci](./.ci) contains the required setup for the Continuous Integration (CI) test of these examples with [GitHub action](./.github) workflows. The tools are downloaded from the [Arm Tools Artifactory](https://artifacts.tools.arm.com/). The test results are available in the [*Actions*](/../../actions) view. +The directory [.ci](./.ci) contains the required setup for testing these examples with [GitHub Actions](./.github) workflows. The tools are downloaded from the [Arm Tools Artifactory](https://artifacts.tools.arm.com/). The test results are available in the [*Actions*](/../../actions) view. ## Examples in Other Repositories -Source | Description -:-----------------|:---------------------------------- -[github.com/Arm-Examples](https://github.com/Arm-Examples) | A collection of several example projects -[AWS_MQTT_MutualAuth_Demo](https://github.com/Open-CMSIS-Pack/AWS_MQTT_MutualAuth_SW_Framework) | MQTT demo that uses layers for re-targeting to different physical boards -[AVH_CI_Template](https://github.com/Arm-Examples/AVH_CI_Template) | CI Template for unit test automation that uses [GitHub Actions](https://github.com/features/actions) \ No newline at end of file +See [github.com/Arm-Examples](https://github.com/Arm-Examples) for a collection of embedded software example projects. diff --git a/SimpleTrustZone/README.md b/SimpleTrustZone/README.md index 6e4ab11..49eb842 100644 --- a/SimpleTrustZone/README.md +++ b/SimpleTrustZone/README.md @@ -1,16 +1,17 @@ # Simple TrustZone Application -- This [**ARM Cortex-M33**](https://developer.arm.com/Processors/Cortex-M33) secure/non-secure example project shows how to setup the [**TrustZone**](https://www.arm.com/technologies/trustzone-for-cortex-m) for running on [**ARMv8-M**](https://www.arm.com/architecture/cpu/m-profile) profile. +- This [**Arm Cortex-M33**](https://developer.arm.com/Processors/Cortex-M33) secure/non-secure example project shows how to set up [**TrustZone**](https://www.arm.com/technologies/trustzone-for-cortex-m) on the [**Armv8-M**](https://www.arm.com/architecture/cpu/m-profile) profile. - The application uses [**CMSIS**](https://www.arm.com/technologies/cmsis) and can be executed on an [**Arm Virtual Hardware (AVH)**](https://developer.arm.com/Tools%20and%20Software/Arm%20Virtual%20Hardware). -- The application demonstrates function calls between [**secure and non-secure**](https://developer.arm.com/documentation/100235/0004/the-cortex-m33-processor/security-state-switches) state. +- The application demonstrates function calls between the [**secure and non-secure**](https://developer.arm.com/documentation/100235/0004/the-cortex-m33-processor/security-state-switches) states. ## Prerequisites ### Tools -- [CMSIS-Toolbox 2.6.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases) or higher -- Arm Compiler 6.22 or higher -- Arm Virtual Hardware for FVP_MPS2_Cortex-M33 v11.26.11 +- [CMSIS-Toolbox 2.14.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases) or higher +- Arm Compiler 6.22 or higher +- GCC Compiler 13.2.1 or higher +- Arm Virtual Hardware for FVP_MPS2_Cortex-M33 v11.26.11 ### Packs @@ -18,39 +19,39 @@ ## Project Structure -The project is generated using the [CMSIS-Toolbox](https://open-cmsis-pack.github.io/cmsis-toolbox/build-overview) and is defined in [`csolution`](https://open-cmsis-pack.github.io/cmsis-toolbox/YML-Input-Format) format: - - -- [`SimpleTZ.csolution.yml`](./SimpleTZ.csolution.yml) lists the required packs, defines, hardware targets, and the build-types (along with the compiler). +The project is generated using the [CMSIS-Toolbox](https://open-cmsis-pack.github.io/cmsis-toolbox/build-overview) and is defined in [`csolution`](https://open-cmsis-pack.github.io/cmsis-toolbox/YML-Input-Format) format: + +- [`SimpleTZ.csolution.yml`](./SimpleTZ.csolution.yml) lists the required packs and defines the hardware target, build types, supported compilers, and target sets. - [`CM33_s.cproject.yml`](./CM33_s/CM33_s.cproject.yml) defines the source files and the software components used for the secure part. - [`CM33_ns.cproject.yml`](./CM33_ns/CM33_ns.cproject.yml) defines the source files and the software components used for the non-secure part. ## Theory of operation -### Secure application: -- Setup code and start for the non-secure application. - -### Non-secure application: -- Calls a secure function from non-secure state. -- Calls a secure function that call back to a non-secure function. - -### Output: -- Message : - - Switch from the secure execution to the non-secure execution. -- Messages : - - Start program execution in the non-secure state - - Show function calls and results of the program execution in the non-secure state - -## Generate the project binaries - -Note that the file [SimpleTZ.cbuild-set.yml](./SimpleTZ.cbuild-set.yml) contains the selected [context set](https://open-cmsis-pack.github.io/cmsis-toolbox/build-overview#working-with-context-set) for the application. - - -```txt -> cbuild SimpleTZ.csolution.yml --packs .Debug+AVH --toolchain AC6 --context-set -``` - -## Execute the project on ARM Virtual Hardware +### Secure application + +- Sets up and starts the non-secure application. + +### Non-secure application + +- Calls a secure function from the non-secure state. +- Calls a secure function that calls back to a non-secure function. + +### Output + +The output shows the transition from secure to non-secure execution followed by the function calls and their results in the non-secure application. + +## Generate the project binaries + +The solution provides `Debug` and `Release` target sets. Select the required set with the `--active` option: + +```txt +> cbuild SimpleTZ.csolution.yml --packs --active AVH@Debug --toolchain AC6 +> cbuild SimpleTZ.csolution.yml --packs --active AVH@Release --toolchain AC6 +``` + +Replace `AC6` with `GCC` to build a target set with the GCC compiler. + +## Execute the project on Arm Virtual Hardware ```txt > FVP_MPS2_Cortex-M33 -a ./out/CM33_ns/AVH/Debug/CM33_ns.axf -a ./out/CM33_s/AVH/Debug/CM33_s.axf -f ./../FVP/FVP_MPS2_Cortex-M33/fvp_config.txt --stat diff --git a/SimpleTrustZone/SimpleTZ.cbuild-set.yml b/SimpleTrustZone/SimpleTZ.cbuild-set.yml deleted file mode 100644 index 331b8d6..0000000 --- a/SimpleTrustZone/SimpleTZ.cbuild-set.yml +++ /dev/null @@ -1,5 +0,0 @@ -cbuild-set: - generated-by: vscode-cmsis-csolution version 1.52.1-23-g3f9a03e - contexts: - - context: CM33_s.Debug+AVH - - context: CM33_ns.Debug+AVH diff --git a/SimpleTrustZone/SimpleTZ.csolution.yml b/SimpleTrustZone/SimpleTZ.csolution.yml index 33ae80b..cbeae37 100644 --- a/SimpleTrustZone/SimpleTZ.csolution.yml +++ b/SimpleTrustZone/SimpleTZ.csolution.yml @@ -1,5 +1,5 @@ solution: - created-for: CMSIS-Toolbox@2.12.0 + created-for: CMSIS-Toolbox@2.14.0 cdefault: select-compiler: - compiler: AC6 @@ -16,7 +16,7 @@ solution: - type: AVH device: ARM::ARMCM33 target-set: - - set: + - set: Debug images: - project-context: CM33_ns.Debug - project-context: CM33_s.Debug @@ -25,12 +25,25 @@ solution: model: FVP_MPS2_Cortex-M33 config-file: ../FVP/FVP_MPS2_Cortex-M33/fvp_config.txt args: --stat + - set: Release + images: + - project-context: CM33_ns.Release + - project-context: CM33_s.Release + debugger: + name: Arm-FVP + model: FVP_MPS2_Cortex-M33 + config-file: ../FVP/FVP_MPS2_Cortex-M33/fvp_config.txt + args: --stat build-types: - - type: Debug + - type: Debug # toolchain options for 'debug' debug: on optimize: debug - - type: Release + misc: + - for-compiler: AC6 + C: + - -funwind-tables # ensure reliable stack unwinding with GDB + - type: Release # toolchain options for 'release' debug: off optimize: balanced diff --git a/Templates/Multicore/Core0/MyName0.cproject.yml b/Templates/Multicore/Core0/MyName0.cproject.yml index 8f83fac..f0c0e6e 100644 --- a/Templates/Multicore/Core0/MyName0.cproject.yml +++ b/Templates/Multicore/Core0/MyName0.cproject.yml @@ -1,13 +1,12 @@ project: # A project translates into one executable or library -# specify targeted processor instance - device: :myCore0 # replace with your device's Pname +# Select a processor of the device specified by the solution target + device: :MyCore0 # replace MyCore0 with the processor Pname; ':' inherits the device -# List the packs that define the device and/or board - packs: - - pack: ARM::CMSIS # The CMSIS base software pack -# - pack: MyVendor:MyPack # List additional software packs +# List packs required only by this core; shared packs are specified in the solution +# packs: +# - pack: MyVendor::MyCorePack groups: - group: Source Files @@ -19,12 +18,15 @@ project: # files: # - file: MyFile2.cpp -# A software component is a re-usable unit that may be configurable +# A software component is a reusable unit that may be configurable components: # List components to use for your application - component: CMSIS:CORE # The CMSIS-Core component used in most projects # - component: Device:Startup # - component: Cclass:Cgroup:Csub&Cvariant -# A software layer is a collection of pre-configured source files or components -# layers: # List software layers to use for your application -# - layer: MyLayer.clayer.yml +# Generate an ELF file for symbols, a HEX file for loading, and a linker map file + output: + type: + - elf + - hex + - map diff --git a/Templates/Multicore/Core1/MyName1.cproject.yml b/Templates/Multicore/Core1/MyName1.cproject.yml index d9623c6..92923a4 100644 --- a/Templates/Multicore/Core1/MyName1.cproject.yml +++ b/Templates/Multicore/Core1/MyName1.cproject.yml @@ -1,13 +1,12 @@ project: # A project translates into one executable or library -# specify targeted processor instance - device: :myCore1 # replace with your device's Pname +# Select a processor of the device specified by the solution target + device: :MyCore1 # replace MyCore1 with the processor Pname; ':' inherits the device -# List the packs that define the device and/or board - packs: - - pack: ARM::CMSIS # The CMSIS base software pack -# - pack: MyVendor:MyPack # List additional software packs +# List packs required only by this core; shared packs are specified in the solution +# packs: +# - pack: MyVendor::MyCorePack groups: - group: Source Files @@ -19,12 +18,15 @@ project: # files: # - file: MyFile2.cpp -# A software component is a re-usable unit that may be configurable +# A software component is a reusable unit that may be configurable components: # List components to use for your application - component: CMSIS:CORE # The CMSIS-Core component used in most projects - - component: Device:Startup +# - component: Device:Startup # - component: Cclass:Cgroup:Csub&Cvariant -# A software layer is a collection of pre-configured source files or components -# layers: # List software layers to use for your application -# - layer: MyLayer.clayer.yml +# Generate an ELF file for symbols, a HEX file for loading, and a linker map file + output: + type: + - elf + - hex + - map diff --git a/Templates/Multicore/MyName.csolution.yml b/Templates/Multicore/MyName.csolution.yml index cd31c19..e42820c 100644 --- a/Templates/Multicore/MyName.csolution.yml +++ b/Templates/Multicore/MyName.csolution.yml @@ -1,28 +1,42 @@ solution: -# A solution is a collection of related projects that share same base configuration +# A solution is a collection of related projects that share the same base configuration - created-for: CMSIS-Toolbox@2.6.0 - cdefault: # use cdefault.yml for default toolchain settings -# compiler: AC6 # uncomment to select a different compiler (AC6 or IAR) + created-for: CMSIS-Toolbox@2.14.0 + cdefault: # use settings from cdefault.yml + compiler: AC6 # select the compiler for this solution # List the packs that define the device and/or board packs: - - pack: MyDevice_DFP # replace with matching device family pack (DFP) for the device -# - pack: MyBoard_BSP # add a board support pack (BSP) when using a board + - pack: MyVendor::MyDevice_DFP # replace with matching device family pack (DFP) for the device +# - pack: MyVendor::MyBoard_BSP # add a board support pack (BSP) when using a board + - pack: ARM::CMSIS@^6.1.0 # pack shared by all projects in this solution # List different hardware targets that are used to deploy the solution target-types: - type: MyTargetName # choose a brief name for your target hardware device: MyDeviceName # replace with your device or comment out to use a board -# board: MyBoardName # optional specify you board (device selected by a board) +# board: MyBoardName # optionally specify your board (the board selects the device) + target-set: # group the project outputs into application images + - set: Debug + images: + - project-context: MyName0.Debug # image built from Core0/MyName0.cproject.yml + - project-context: MyName1.Debug # image built from Core1/MyName1.cproject.yml + - set: Release + images: + - project-context: MyName0.Release # image built from Core0/MyName0.cproject.yml + - project-context: MyName1.Release # image built from Core1/MyName1.cproject.yml # List different build types build-types: - - type: Debug + - type: Debug # toolchain options for 'debug' debug: on optimize: debug + misc: + - for-compiler: AC6 + C: + - -funwind-tables # ensure reliable stack unwinding with GDB - - type: Release + - type: Release # toolchain options for 'release' debug: off optimize: balanced diff --git a/Templates/README.md b/Templates/README.md index d170313..2e41574 100644 --- a/Templates/README.md +++ b/Templates/README.md @@ -1,57 +1,33 @@ -# CMSIS-Toolbox Templates - -The following `csolution.yml` templates may be used to create own embedded applications. - -Folder | Description -:------------------------------------|:---------------------------------- -[Simple](./Simple) | A `csolution.yml` template with a single `cproject.yml`. -[Multicore](./Multicore) | A `csolution.yml` template with multiuple `cproject.yml` each targeting one processor of a multicore device. -[TrustZone](./TrustZone) | A `csolution.yml` template with a non-secure `cproject.yml` and an optional secure `cproject.yml`. -[UnitTest](./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. - -## Overall Workflow - -1. **Device and/or board software packs** - - Visit **[www.keil.arm.com](https://www.keil.arm.com) - Hardware - Boards or Devices** to identify software packs for your hardware. - - Use `cpackget add` to install these software packs. - -2. **Adapt the `csolution.yml` and `cproject.yml` files to your application** - - Enter the device and/or board information along with software packs in `csolution.yml`. - - Add source files, software components, and potentially software layers to `cproject.yml`. - -## Useful Commands - -During the process the following CMSIS-Toolbox commands are useful to solve common problems: - -### List Available Devices or Boards - -_**error csolution:** specified device '...' was not found among the installed packs._ - -Use the `csolution` tool with the related `csolution.yml` file to list devices and/or boards that are available in the specified software packs. If the device or board is not listed, check without specifying the `csolution.yml` file. - -```txt -csolution list devices -s MyName.csolution.yml # list device or board of the specified packs -csolution list boards # list device or board of all installed packs -``` - -### List Available Components - -_**warning csolution:** dependency validation for context '...' failed_ - -The warning itself may list already required components that may be added to the `cproject.yml` file. -Use the `csolution` tool with the related `csolution.yml` file to list components available in the specified software packs. If the component is not listed, check without specifying the `csolution.yml` file. - -```txt -csolution list components -s MyName.csolution.yml # list components of the specified packs -csolution list components # list components of all installed packs -``` - -### List Available Layers - -Use the `csolution` tool with the related `csolution.yml` file to list layers available in the specified software packs. - -```txt -csolution list layers -s MyName.csolution.yml # list layers of the specified packs -``` +# CMSIS-Toolbox Templates + +These generic templates show the file structure for different types of `csolution` projects. They are not ready-to-build example projects; use them as a starting point for your own application. + +To use a template, copy the content of its folder to your application folder. Then adapt the names, replace the placeholders, and add the required application content. + +For guidance on creating an application from these templates, refer to [Create Applications](https://open-cmsis-pack.github.io/cmsis-toolbox/CreateApplications/). + +## Template Types + +### Simple + +The [Simple](./Simple) template shows the basic structure of a solution containing one project. It is a starting point for a single executable image or library. + +### Multicore + +The [Multicore](./Multicore) template contains one project for each processor in a multicore device. Target sets group the project images into Debug and Release applications. Select a set with `--active MyTargetName@Debug` or `--active MyTargetName@Release`. + +### TrustZone + +The [TrustZone](./TrustZone) template separates the secure and non-secure parts into projects and shows how the non-secure project uses the CMSE library generated by the secure project. Target sets group both images into Debug and Release applications. Select a set with `--active MyTargetName@Debug` or `--active MyTargetName@Release`. + +### UnitTest + +The [UnitTest](./UnitTest) template contains independent test projects that share common support through a reusable layer. It does not use target sets because the projects are separate test executables, typically used in CI. Use `--context .Debug` or `--context .Release` to select all matching test projects. + +## Pack Ownership + +Pack declarations define which software packs are available within solution, project, or layer scope. Avoid duplicate or conflicting pack requirements so projects and layers remain reusable. + +- `*.csolution.yml`: specify hardware packs and packs shared by all projects. +- `*.cproject.yml`: specify packs required by that project. +- `*.clayer.yml`: specify packs required by the reusable layer so they are available to every project that uses it. diff --git a/Templates/Simple/MyName.cproject.yml b/Templates/Simple/MyName.cproject.yml index 4833b90..9e1772d 100644 --- a/Templates/Simple/MyName.cproject.yml +++ b/Templates/Simple/MyName.cproject.yml @@ -1,10 +1,9 @@ project: # A project translates into one executable or library -# List the packs that define the device and/or board - packs: - - pack: ARM::CMSIS # The CMSIS base software pack -# - pack: MyVendor::MyPack # List additional software packs +# List packs required only by this project; shared packs are specified in the solution +# packs: +# - pack: MyVendor::MyProjectPack groups: - group: Source Files @@ -16,19 +15,16 @@ project: # files: # - file: MyFile2.cpp -# A software component is a re-usable unit that may be configurable +# A software component is a reusable unit that may be configurable components: # List components to use for your application - component: CMSIS:CORE # The CMSIS-Core component used in most projects # - component: Device:Startup&Baremetal # - component: Cclass:Cgroup:Csub&Cvariant -# A software layer is a collection of pre-configured source files or components -# layers: # List software layers to use for your application -# - layer: MyLayer.clayer.yml - -# Control output files (elf is generated by default) -# output: -# type: -# - elf -# - hex -# - bin +# Generate an executable with ELF, HEX, and linker map output files +# To generate a library archive instead, replace the type list below with: type: lib + output: + type: + - elf + - hex + - map diff --git a/Templates/Simple/MyName.csolution.yml b/Templates/Simple/MyName.csolution.yml index de7e691..489c280 100644 --- a/Templates/Simple/MyName.csolution.yml +++ b/Templates/Simple/MyName.csolution.yml @@ -1,28 +1,33 @@ solution: -# A solution is a collection of related projects that share same base configuration +# A solution is a collection of related projects that share the same base configuration - created-for: CMSIS-Toolbox@2.6.0 - cdefault: # use cdefault.yml for default toolchain settings -# compiler: AC6 # select a compiler (AC6, GCC, IAR, LLVM) + created-for: CMSIS-Toolbox@2.14.0 + cdefault: # use settings from cdefault.yml + compiler: AC6 # select the compiler for this solution # List the packs that define the device and/or board, optional with minimum version packs: - - pack: MyDevice_DFP # replace with matching device family pack (DFP) for the device -# - pack: MyBoard_BSP@^1.2.0 # add a board support pack (BSP) when using a board + - pack: MyVendor::MyDevice_DFP # replace with matching device family pack (DFP) for the device +# - pack: MyVendor::MyBoard_BSP@^1.2.0 # add a board support pack (BSP) when using a board + - pack: ARM::CMSIS@^6.1.0 # pack shared by all projects in this solution # List different hardware targets that are used to deploy the solution target-types: - type: MyTargetName # choose a brief name for your target hardware device: MyDeviceName # replace with your device or comment out to use a board -# board: MyBoardName # optional specify you board (device selected by a board) +# board: MyBoardName # optionally specify your board (the board selects the device) # List different build types build-types: - - type: Debug + - type: Debug # toolchain options for 'debug' debug: on optimize: debug + misc: + - for-compiler: AC6 + C: + - -funwind-tables # ensure reliable stack unwinding with GDB - - type: Release + - type: Release # toolchain options for 'release' debug: off optimize: balanced diff --git a/Templates/TrustZone/MyName.csolution.yml b/Templates/TrustZone/MyName.csolution.yml index e9e0281..5186b2e 100644 --- a/Templates/TrustZone/MyName.csolution.yml +++ b/Templates/TrustZone/MyName.csolution.yml @@ -1,32 +1,46 @@ solution: -# A solution is a collection of related projects that share same base configuration +# A solution is a collection of related projects that share the same base configuration - created-for: CMSIS-Toolbox@2.6.0 - cdefault: # use cdefault.yml for default toolchain settings -# compiler: AC6 # select a compiler (AC6, GCC, IAR, LLVM) + created-for: CMSIS-Toolbox@2.14.0 + cdefault: # use settings from cdefault.yml + compiler: AC6 # select the compiler for this solution # List the packs that define the device and/or board, optional with minimum version packs: - - pack: MyDevice_DFP # replace with matching device family pack (DFP) for the device -# - pack: MyBoard_BSP@^1.2.0 # add a board support pack (BSP) when using a board + - pack: MyVendor::MyDevice_DFP # replace with matching device family pack (DFP) for the device +# - pack: MyVendor::MyBoard_BSP@^1.2.0 # add a board support pack (BSP) when using a board + - pack: ARM::CMSIS@^6.1.0 # pack shared by all projects in this solution # List different hardware targets that are used to deploy the solution target-types: - type: MyTargetName # choose a brief name for your target hardware device: MyDeviceName # replace with your device or comment out to use a board -# board: MyBoardName # optional specify you board (device selected by a board) +# board: MyBoardName # optionally specify your board (the board selects the device) + target-set: # group the secure and non-secure application images + - set: Debug + images: + - project-context: MyNameS.Debug # secure image + - project-context: MyNameNS.Debug # non-secure image + - set: Release + images: + - project-context: MyNameS.Release # secure image + - project-context: MyNameNS.Release # non-secure image # List different build types build-types: - - type: Debug + - type: Debug # toolchain options for 'debug' debug: on optimize: debug + misc: + - for-compiler: AC6 + C: + - -funwind-tables # ensure reliable stack unwinding with GDB - - type: Release + - type: Release # toolchain options for 'release' debug: off optimize: balanced # List related projects projects: - - project: Secure/MyNameS.cproject.yml # secure project comes first to be built first - - project: NonSecure/MyNameNS.cproject.yml # non-secure project(s) come after + - project: Secure/MyNameS.cproject.yml # generates the CMSE library used by the non-secure project + - project: NonSecure/MyNameNS.cproject.yml # consumes the secure project's CMSE library diff --git a/Templates/TrustZone/NonSecure/MyNameNS.cproject.yml b/Templates/TrustZone/NonSecure/MyNameNS.cproject.yml index 2c37753..d92d5b0 100644 --- a/Templates/TrustZone/NonSecure/MyNameNS.cproject.yml +++ b/Templates/TrustZone/NonSecure/MyNameNS.cproject.yml @@ -3,16 +3,14 @@ project: processor: trustzone: non-secure -# List the packs that define the device and/or board - packs: - - pack: ARM::CMSIS # The CMSIS base software pack -# - pack: MyVendor:MyPack # List additional software packs +# List packs required only by this project; shared packs are specified in the solution +# packs: +# - pack: MyVendor::MyNonSecurePack -# additional include paths +# Additional include paths add-path: - ../Secure # Include path for CMSE Interface API -# groups: - group: Source Files # files: @@ -26,12 +24,15 @@ project: files: - file: $cmse-lib(MyNameS)$ # Cortex-M Security Extension's Secure Callable Entry Points -# A software component is a re-usable unit that may be configurable +# A software component is a reusable unit that may be configurable components: # List components to use for your application - component: CMSIS:CORE # The CMSIS-Core component used in most projects # - component: Device:Startup&Baremetal # - component: Cclass:Cgroup:Csub&Cvariant -# A software layer is a collection of pre-configured source files or components -# layers: # List software layers to use for your application -# - layer: MyLayer.clayer.yml +# Generate an ELF file for symbols, a HEX file for loading, and a linker map file + output: + type: + - elf + - hex + - map diff --git a/Templates/TrustZone/Secure/MyNameS.cproject.yml b/Templates/TrustZone/Secure/MyNameS.cproject.yml index 178fda6..95477ce 100644 --- a/Templates/TrustZone/Secure/MyNameS.cproject.yml +++ b/Templates/TrustZone/Secure/MyNameS.cproject.yml @@ -3,10 +3,9 @@ project: processor: trustzone: secure # This project is executed in secure mode -# List the packs that define the device and/or board - packs: - - pack: ARM::CMSIS # The CMSIS base software pack -# - pack: MyVendor:MyPack # List additional software packs +# List packs required only by this project; shared packs are specified in the solution +# packs: +# - pack: MyVendor::MySecurePack groups: - group: Source Files @@ -18,12 +17,15 @@ project: # files: # - file: MyFile2.cpp -# A software component is a re-usable unit that may be configurable +# A software component is a reusable unit that may be configurable components: # List components to use for your application - component: CMSIS:CORE # The CMSIS-Core component used in most projects # - component: Device:Startup&Baremetal # - component: Cclass:Cgroup:Csub&Cvariant -# A software layer is a collection of pre-configured source files or components -# layers: # List software layers to use for your application -# - layer: MyLayer.clayer.yml +# Generate an ELF file for symbols, a HEX file for loading, and a linker map file + output: + type: + - elf + - hex + - map diff --git a/Templates/UnitTest/Layer/MyName.clayer.yml b/Templates/UnitTest/Layer/MyName.clayer.yml index 72ca311..5269b9e 100644 --- a/Templates/UnitTest/Layer/MyName.clayer.yml +++ b/Templates/UnitTest/Layer/MyName.clayer.yml @@ -1,10 +1,10 @@ layer: -# A layer is a collection of pre-configured source files or components +# This reusable layer contains source files and components shared by the test projects -# List the packs used in the layer, optional with minimum version +# List packs required by this reusable layer packs: - - pack: ARM::CMSIS@^6.1.0 # The CMSIS base software pack -# - pack: MyVendor:MyPack # List additional software packs + - pack: ARM::CMSIS@^6.1.0 # provides the CMSIS:CORE component used by this layer +# - pack: MyVendor::MyHALPack groups: - group: Source Files @@ -16,8 +16,8 @@ layer: # files: # - file: MyFile2.cpp -# A software component is a re-usable unit that may be configurable - components: # List components to use in the layer +# A software component is a reusable unit that may be configurable + components: # List components provided by the layer - component: CMSIS:CORE # The CMSIS-Core component used in most projects # - component: Device:Startup&Baremetal # - component: Cclass:Cgroup:Csub&Cvariant diff --git a/Templates/UnitTest/MyName.csolution.yml b/Templates/UnitTest/MyName.csolution.yml index 7b149d8..4a956de 100644 --- a/Templates/UnitTest/MyName.csolution.yml +++ b/Templates/UnitTest/MyName.csolution.yml @@ -1,32 +1,36 @@ solution: -# A solution is a collection of related projects that share same base configuration +# A solution is a collection of related projects that share the same base configuration - created-for: CMSIS-Toolbox@2.6.0 - cdefault: # use cdefault.yml for default toolchain settings -# compiler: AC6 # select a compiler (AC6, GCC, IAR, LLVM) + created-for: CMSIS-Toolbox@2.14.0 + cdefault: # use settings from cdefault.yml + compiler: AC6 # select the compiler for this solution # List the packs that define the device and/or board, optional with minimum version packs: - - pack: MyDevice_DFP # replace with matching device family pack (DFP) for the device -# - pack: MyBoard_BSP@^1.2.0 # add a board support pack (BSP) when using a board + - pack: MyVendor::MyDevice_DFP # replace with matching device family pack (DFP) for the device +# - pack: MyVendor::MyBoard_BSP@^1.2.0 # add a board support pack (BSP) when using a board # List different hardware targets that are used to deploy the solution target-types: - type: MyTargetName # choose a brief name for your target hardware device: MyDeviceName # replace with your device or comment out to use a board -# board: MyBoardName # optional specify you board (device selected by a board) +# board: MyBoardName # optionally specify your board (the board selects the device) # List different build types build-types: - - type: Debug + - type: Debug # toolchain options for 'debug' debug: on optimize: debug + misc: + - for-compiler: AC6 + C: + - -funwind-tables # ensure reliable stack unwinding with GDB - - type: Release + - type: Release # toolchain options for 'release' debug: off optimize: balanced -# List related projects +# List independent test projects projects: - project: Test0/MyName0.cproject.yml - project: Test1/MyName1.cproject.yml diff --git a/Templates/UnitTest/Test0/MyName0.cproject.yml b/Templates/UnitTest/Test0/MyName0.cproject.yml index b58aff3..a9280c8 100644 --- a/Templates/UnitTest/Test0/MyName0.cproject.yml +++ b/Templates/UnitTest/Test0/MyName0.cproject.yml @@ -1,10 +1,9 @@ project: -# A project translates into one executable or library +# A test project translates into an independent test executable -# List the packs used in the layer, optional with minimum version - packs: - - pack: ARM::CMSIS@^6.1.0 # The CMSIS base software pack -# - pack: MyVendor:MyPack # List additional software packs +# List packs required only by this test project; layer packs are specified in the layer +# packs: +# - pack: MyVendor::MyTestPack groups: - group: Source Files @@ -16,12 +15,17 @@ project: # files: # - file: MyFile2.cpp -# A software component is a re-usable unit that may be configurable - components: # List components to use for your application - - component: CMSIS:CORE # The CMSIS-Core component used in most projects -# - component: Device:Startup&Baremetal +# List components required only by this test project; shared components are in the layer +# components: # - component: Cclass:Cgroup:Csub&Cvariant -# A software layer is a collection of pre-configured source files or components - layers: # List software layers to use for your application +# Import the reusable layer containing support shared by the test projects + layers: - layer: ../Layer/MyName.clayer.yml + +# Generate an ELF file for symbols, a HEX file for loading, and a linker map file + output: + type: + - elf + - hex + - map diff --git a/Templates/UnitTest/Test1/MyName1.cproject.yml b/Templates/UnitTest/Test1/MyName1.cproject.yml index 8e57b9b..a9280c8 100644 --- a/Templates/UnitTest/Test1/MyName1.cproject.yml +++ b/Templates/UnitTest/Test1/MyName1.cproject.yml @@ -1,10 +1,9 @@ project: -# A project translates into one executable or library +# A test project translates into an independent test executable -# List the packs that define the device and/or board - packs: - - pack: ARM::CMSIS # The CMSIS base software pack -# - pack: MyVendor:MyPack # List additional software packs +# List packs required only by this test project; layer packs are specified in the layer +# packs: +# - pack: MyVendor::MyTestPack groups: - group: Source Files @@ -16,13 +15,17 @@ project: # files: # - file: MyFile2.cpp -# A software component is a re-usable unit that may be configurable - components: # List components to use for your application - - component: CMSIS:CORE # The CMSIS-Core component used in most projects -# - component: Device:Startup&Baremetal +# List components required only by this test project; shared components are in the layer +# components: # - component: Cclass:Cgroup:Csub&Cvariant -# A software layer is a collection of pre-configured source files or components - layers: # List software layers to use for your application +# Import the reusable layer containing support shared by the test projects + layers: - layer: ../Layer/MyName.clayer.yml +# Generate an ELF file for symbols, a HEX file for loading, and a linker map file + output: + type: + - elf + - hex + - map