Cleaned project files and updated README.md files (#40)

Author: ReinhardKeil

.ci/README.md

@@ -1,11 +1,9 @@
 # Continuous Integration (CI) test for csolution-examples
 
-  
 Content of `.ci` Directory   | Description
 :----------------------------|:-----------------
 `vcpkg-configuration.json`   | Tool setup for the CI test.
 
-
 ## 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.
@@ -17,4 +15,4 @@ Projects in the Arm csolution-examples uses the **`ARM compiler (AC6)`** as well
 
 - **`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`**.
 
-- **`CubeMX-CI.yml`**  implements a build test for a **`CubeMX`** generated project by using only the **`AC6`** toolchain. The output of this build test is stored as artifact and can be downloaded.
+- **`CubeMX-CI.yml`**  implements a build test for a **`CubeMX`** generated project by using only the **`AC6`** toolchain.

CubeMX/README.md

@@ -1,48 +1,67 @@
-# CubeMX project
+# CubeMX Example
 
-This project shows the usage of CubeMX. Refer to the documentation chapter
-[**CMSIS-Toolbox > Configure STM32 Devices with CubeMX**](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/tree/main/docs/CubeMX.md) for details.
+This *csolution project* shows the usage of [STM32CubeMX](https://www.st.com/en/development-tools/stm32cubemx.html) which uses a [generator import file](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/YML-CBuild-Format.md#generator-import-file) to obtain the device configuration and HAL driver source files.
+
+This project uses two different target-types to configure execution from Flash ROM or execution from RAM. It uses a [variable](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/YML-Input-Format.md#variables) to define the regions header file for each target in the file [`CubeMX.csolution.yml`](./CubeMX.csolution.yml).
 
 ## Prerequisites
 
 ### Tools
 
-- [CMSIS-Toolbox 2.3.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases) or higher
-- [Keil MDK 5.37](https://www2.keil.com/mdk5/) or higher
+- [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
 - [STM32CubeMX 6.11](https://www.st.com/en/development-tools/stm32cubemx.html) or higher
 
->**Note:** later versions will also compile with GCC.
+>**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.
 
 ### Packs
 
-- Required packs are listed in the file [`CubeMX.csolution.yml`](./CubeMX.csolution.yml) and [`CubeMX.cproject.yml`](./CubeMX.cproject.yml)
+- Required packs are listed in the file [`CubeMX.csolution.yml`](./CubeMX.csolution.yml)
+
+## Build Project
 
-DFP and BSP development packs are available here [github.com/Open-CMSIS-Pack/pack-examples](https://github.com/Open-CMSIS-Pack/pack-examples). Clone the repo to `<working-dir>` and install the packs by executing:
+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`.
 
 ```bash
-> cpackget add <working-dir>\pack-examples\STM32U5xx_DFP\Keil.STM32U5xx_DFP.pdsc
-> cpackget add <working-dir>\pack-examples\B-U585I-IOT02A_BSP\Keil.B-U585I-IOT02A_BSP.pdsc 
+> cbuild setup CubeMX.csolution.yml --context-set --packs
 ```
 
 ## Run CubeMX
 
-This command starts STM32CubeMX using the specified context.
+To change the device configuration, start STM32CubeMX using the following command.
 
 ```bash
-> csolution CubeMX.csolution.yml run --generator CubeMX --context CubeMX.Debug+MyBoard
+> csolution CubeMX.csolution.yml run --generator CubeMX --context-set
 ```
 
-For using CubeMX refer to the documentation chapter
+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.md).
 
-## Generated Project
-
-```bash
-> cbuild CubeMX.csolution.yml --packs --update-rte
-```
+The source code generated by CubeMX is imported using the file [STM32CubeMX\<target-type>\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:** During the build process required packs may be downloaded.
+>**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.
 
 ## Execute Project
 
 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:
+
+- In the file [`CubeMX.csolution.yml`](./CubeMX.csolution.yml) set `compiler: GCC`.
+
+- Launch the STM32CubeMX generator with this CMSIS-Toolbox command: csolution <solution_name>.csolution.yml run -g CubeMX -c <context>
+
+- 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 configuration to reference appropriate [GCC linker script template](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/build-overview.md#linker-script-templates). You may customize this GCC linker script template file to your project's requirements.
+
+[Rebuild the project](#build-project) using the CMSIS-Toolbox command `cbuild` with the option `--rebuild`.

DualCore/README.md

@@ -9,9 +9,6 @@ This example generates **HelloWorld** executables for the **FRDM-K32L3A6** evalu
 - [CMSIS-Toolbox 2.6.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 Corstone-300 v11.26.11
-
-All these tools can be installed via [vcpkg](https://learn.arm.com/learning-paths/microcontrollers/vcpkg-tool-installation/)
 
 ### Packs
 
@@ -31,3 +28,7 @@ The project is generated using the [CMSIS-Toolbox](https://github.com/Open-CMSIS
 ```txt
 > cbuild HelloWorld.csolution.yml --packs --toolchain AC6
 ```
+
+## Execute Project
+
+You may use the debugger of choice for executing this program.

Hello/Hello.csolution.yml

@@ -2,7 +2,10 @@ solution:
   created-for: [email protected]
   description: Print Hello World and a counter value via UART
   cdefault:
-  compiler: AC6
+
+  select-compiler:                            # list of tested compilers
+    - compiler: AC6
+    - compiler: GCC
 
   # It is recommended to list the pack or packs that define the device or board used in the csolution.yml file
   packs:

Hello/README.md

@@ -9,13 +9,11 @@ This project prints "Hello World" and a counter value via the UART output. It is
 - [CMSIS-Toolbox 2.6.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 Corstone-300 v11.26.11
-
-All these tools can be installed via [vcpkg](https://learn.arm.com/learning-paths/microcontrollers/vcpkg-tool-installation/)
+- Arm Virtual Hardware for Corstone-300 v11.26.11 or higher
 
 ### Packs
 
-- Required packs are listed in the file [`Hello.csolution.yml`](./Hello.csolution.yml)
+- Required packs are listed in the file [`Hello.csolution.yml`](./Hello.csolution.yml). The file [`Hello.cbuild-pack.yml`](./Hello.cbuild-pack.yml) records the versions that have been used to generate the application.
 
 ## Project Structure
 
@@ -24,10 +22,14 @@ The project is generated using the [CMSIS-Toolbox](https://github.com/Open-CMSIS
 - [`Hello.csolution.yml`](./Hello.csolution.yml) lists the required packs, defines,hardware targets, and thebuild-types (along with the compiler).
 - [`Hello.cproject.yml`](./Hello.cproject.yml) defines the source files and the software components.
 
+> **Note:**
+>
+> The project also builds with the GCC compiler.
+
 ## Generate project binaries
 
-```txt
-> cbuild Hello.csolution.yml --packs
+```bash
+> cbuild Hello.csolution.yml --packs --toolchain AC6
 ```
 
 >**Note:** During the build process required packs may be downloaded.
@@ -37,16 +39,21 @@ The project is generated using the [CMSIS-Toolbox](https://github.com/Open-CMSIS
 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.  
 
 ### Execute this project via command line
+
 #### For debug type
-  ```txt
-  > FVP_Corstone_SSE-300 -f FVP/FVP_Corstone_SSE-300/fvp-config.txt -a ./out/Debug/Hello.axf
-  ```
+
+```bash
+> FVP_Corstone_SSE-300 -f FVP/FVP_Corstone_SSE-300/fvp-config.txt -a ./out/Debug/Hello.axf
+```
+
 #### For release type
-  ```txt
-  > FVP_Corstone_SSE-300 -f FVP/FVP_Corstone_SSE-300/fvp-config.txt -a ./out/Release/Hello.axf
-  ```
+
+```bash
+> FVP_Corstone_SSE-300 -f FVP/FVP_Corstone_SSE-300/fvp-config.txt -a ./out/Release/Hello.axf
+```
 
 ### Execute this project in [**Keil Studio Cloud**](https://studio.keil.arm.com/)
+
 - 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).

README.md

@@ -1,27 +1,33 @@
-[![License](https://img.shields.io/github/license/Open-CMSIS-Pack/csolution-examples?label)](https://github.com/Open-CMSIS-Pack/csolution-examples/blob/main/LICENSE)
+[![License](https://img.shields.io/github/license/Open-CMSIS-Pack/csolution-examples)](https://github.com/Open-CMSIS-Pack/csolution-examples/blob/main/LICENSE)
 [![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)
 [![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)
 
-# CMSIS-Toolbox Examples in `csolution` project format
+# CMSIS-Toolbox Examples in *csolution project format*
 
-This is a collection of [CMSIS-Toolbox](https://github.com/Open-CMSIS-Pack/cmsis-toolbox) project examples using the [`csolution` project format](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/YML-Input-Format.md) utility.  The project files are provided for experimentation, exploration and education purposes.
+This is a collection of [CMSIS-Toolbox](https://github.com/Open-CMSIS-Pack/cmsis-toolbox) project examples in [*csolution project format*](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/YML-Input-Format.md).  The project examples are provided for experimentation, exploration and education purposes.
 
-> **Note:** These examples use **CMSIS-Toolbox 2.6.0** or higher.
->
-> Refer to [**Installation of the CMSIS-Toolbox**](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/installation.md) for information how to setup an environment.
+## Tool Requirements
+
+The examples use **CMSIS-Toolbox 2.6.0** or higher and require additional tools such as CMake, Ninja, Arm Compiler 6, GCC Compiler, and Arm Fixed Virtual Platforms (AVH-FVP).
+
+Refer to [**Installation of the CMSIS-Toolbox**](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/installation.md) 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/).
 
 ## Project Examples
 
 Examples in this repository:
 
-Source                               | Description
+*csolution project*                  | Description
 :------------------------------------|:----------------------------------
-[Hello](./Hello)                     | A simple project to get started.
-[DualCore](./DualCore)               | Application with multiple processors.
-[SimpleTrustZone](./SimpleTrustZone) | Simple TrustZone example.
-[CubeMX](./CubeMX)                   | Project that uses [STM32Cube](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/tree/main/docs/CubeMX.md) as generator for device configuration.
+[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.
+
+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
 
@@ -37,12 +43,18 @@ The project files  contain a list of software packs that are used. When using th
 > cbuild Hello.csolution.yml --packs --context-set --toolchain AC6 --rebuild 
 ```
 
-## Examples in other repositories
+## 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.
+
+## 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.
+
+## Examples in Other Repositories
 
 Source            | Description
 :-----------------|:----------------------------------
-[Hello](./Hello)  | A simple project to get started
-[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
-[Arm TrustZone Demo](https://github.com/MDK-Packs/TrustZone)                                                       | Example that uses TF-M and Bootloader for firmware update.  Runs on [STM32U5 board](https://www.st.com/en/evaluation-tools/b-u585i-iot02a.html) or [AVH](https://avh.arm.com/)
-
->**Note:** The examples may require additional tools. Refer to the instructions for each example to install the required toolchain.
+[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)

SimpleTrustZone/CM33_s/RTE/_Debug_AVH/RTE_Components.h

@@ -1,6 +1,6 @@
 /*
  * CSOLUTION generated file: DO NOT EDIT!
- * Generated by: csolution version 2.5.0
+ * Generated by: csolution version 2.6.0
  *
  * Project: 'CM33_s.Debug+AVH' 
  * Target:  'Debug+AVH' 
@@ -15,6 +15,9 @@
  */
 #define CMSIS_device_header "ARMCM33.h"
 
+/* ARM::CMSIS-View:Event Recorder&[email protected] */
+#define RTE_CMSIS_View_EventRecorder
+#define RTE_CMSIS_View_EventRecorder_DAP
 
 
 #endif /* RTE_COMPONENTS_H */

SimpleTrustZone/README.md

@@ -42,8 +42,10 @@ The project is generated using the [CMSIS-Toolbox](https://github.com/Open-CMSIS
 
 ## Generate the project binaries
 
+Note that the file [SimpleTZ.cbuild-set.yml](./SimpleTZ.cbuild-set.yml) contains the selected [context set](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/build-overview.md#working-with-context-set) for the application.
+
 ```txt
-> cbuild SimpleTZ.csolution.yml --packs .Debug+AVH --toolchain AC6
+> cbuild SimpleTZ.csolution.yml --packs .Debug+AVH --toolchain AC6 --context-set
 ```
 
 ## Execute the project on ARM Virtual Hardware

SimpleTrustZone/SimpleTZ.csolution.yml

@@ -1,6 +1,8 @@
 solution:
   created-for: [email protected]
   cdefault:
+  select-compiler:
+    - compiler: AC6
 
   packs:
     - pack: ARM::CMSIS

Templates/Multicore/MyName.csolution.yml

@@ -1,7 +1,7 @@
 solution:
-# A solution is a collection of related projects that share same base configration
+# A solution is a collection of related projects that share same base configuration
 
-  created-for: CMSIS-Toolbox@2.0.0
+  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)
 
@@ -20,7 +20,7 @@ solution:
   build-types:
     - type: Debug
       debug: on
-      optimize: none
+      optimize: debug
 
     - type: Release
       debug: off