Skip to content

Improved README #17

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
HansSchneebauer merged 1 commit into from
Jun 17, 2026
Merged

Improved README #17

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 28 additions & 32 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,92 +4,88 @@

# AVH CI Template

This repository contains a **CI Template for unit test automation** that uses [GitHub Actions](https://github.com/features/actions) on a [GitHub-hosted runner](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners) with an Ubuntu Linux system. A report is optionally generated using the [Unity test framework](https://github.com/MDK-Packs/Unity).
[<img src="https://github.com/Arm-Examples/.github/blob/main/profile/cicd_intro.png" alt="Introduction to CI/CD test automation" width="317" height="193" align="left">](https://developer.arm.com/-/media/arm%20developer%20community/videos/tools%20and%20software/keil%20mdk/cicd_webinar.mp4?#t=04:15
"Introduction to CI/CD test automation")

The tests run on [**Arm Virtual Hardware - Fixed Virtual Platforms (AVH-FVP)**](https://arm-software.github.io/AVH/main/simulation/html/index.html) which are simulation models that implement a Cortex-M, Corstone, or Cortex-M/Ethos-U device sub-systems. These models are designed for software verification and testing. It allows simulation-based test automation of various software workloads, including unit tests, integration tests, and fault injection.
This repository contains a **CI template for unit test automation** that uses [GitHub Actions](https://github.com/features/actions) on [GitHub-hosted runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners) with Ubuntu Linux. A report can optionally be generated using the [Unity test framework](https://github.com/MDK-Packs/Unity).

The tools used in this **CI Template** are part of [Keil MDK Version 6](https://www.keil.arm.com/keil-mdk/). For evaluation purposes the *MDK - Community Edition* can be used, but commericial usage requires a license of the *MDK - Professional Edition*.
The tool installation is managed with [vcpkg](https://www.keil.arm.com/artifacts/) using a [configuration file](./vcpkg-configuration.json) that ensures consistent setup on Desktop computers and the CI system.
The tests run on [**Fixed Virtual Platforms (FVP) simulation models**](https://arm-software.github.io/AVH/main/simulation/html/index.html), which implement Cortex-M, Corstone, or Cortex-M/Ethos-U device subsystems. These simulation models are designed for software verification and testing. They enable simulation-based test automation for various software workloads, including unit tests, integration tests, and fault injection.

![Create, debug, and test](./create_debug_test.png)
The tools used in this **CI template** are part of [Keil MDK Version 6](https://www.keil.arm.com/keil-mdk/). For evaluation purposes, the *MDK - Community Edition* can be used, but commercial usage requires a license for the *MDK - Professional Edition*.
Tool installation is managed with [vcpkg](https://www.keil.arm.com/artifacts/) using a [configuration file](./vcpkg-configuration.json), which helps ensure a consistent setup on desktop computers and in CI.

## Usage
<br clear="left"/>

![CI Workflow explained: Create, debug, and test](https://github.com/Arm-Examples/.github/blob/main/profile/CICD_Overview.png "CI Workflow explained: Create, debug, and test")

This is a template repository that can be used as starting point for validation projects. Click **Use this template - Create a new repository** to start your own CI test project.
## Usage

> Login with your GitHub account to enable the button **Use this template - Create a new repository**.
This template repository can be used as a starting point for validation projects. Click **Use this template - Create a new repository** to start your own CI test project.
> [!IMPORTANT]
> Log in with your GitHub account to enable the **Use this template - Create a new repository** button.

The [Project](Project) tests a single function (*my_sum*) using the [Unity test framework](https://github.com/MDK-Packs/Unity) that is available as [CMSIS software pack](https://www.keil.arm.com/packs/unity-arm-packs). The initial configuration contains a "test case error" that exemplifies the Unity test reporting.
The [Project](Project) tests a single function (*my_sum*) using the [Unity test framework](https://github.com/MDK-Packs/Unity), which is available as a [CMSIS software pack](https://www.keil.arm.com/packs/unity-arm-packs). Users can modify the test cases to simulate an error and observe Unity test reporting.

> This video contains a demo: [Using CMSIS-Toolbox and Keil MDK v6 in CI/CD Workflows](https://on-demand.arm.com/flow/arm/devhub/sessionCatalog/page/pubSessCatalog/session/1718006126984001DUAn)
> [!TIP]
> This video demonstrates the workflow: [Using CMSIS-Toolbox and Keil MDK v6 in CI/CD Workflows](https://developer.arm.com/-/media/arm%20developer%20community/videos/tools%20and%20software/keil%20mdk/cicd_webinar.mp4?#t=04:15 "Using CMSIS-Toolbox and Keil MDK v6 in CI/CD Workflows")

### Repository Structure

Directory | Content
:-----------------------------|----------
[.github/workflows](.github/workflows) | Workflow YML files that gets you started with GitHub Actions for CMSIS projects.
[.github/workflows](.github/workflows) | Workflow YML files that get you started with GitHub Actions for CMSIS projects.
[Project](Project) | A simple unit test application in [*csolution project format*](https://github.com/Open-CMSIS-Pack/cmsis-toolbox).

### GitHub

With GitHub Actions two workflows are available:
With GitHub Actions, two workflows are available:

- [basic.yml](.github/workflows/basic.yml) compiles and runs the application.
- [basic_w_report.yml](.github/workflows/basic_w_report.yml) compiles and runs the application; then generates a test report using [phoenix-actions/test-reporting](https://github.com/phoenix-actions/test-reporting).

Use in the GitHub web interface the [*Actions*](/../../actions) view to execute the *CI test run* and get *Test results*.
Use the [*Actions*](/../../actions) view in the GitHub web interface to execute the *CI test run* and review *test results*.

### Desktop

**Prerequisite:**

- Install VS Code with [Arm Keil Studio Pack extensions](https://marketplace.visualstudio.com/items?itemName=Arm.keil-studio-pack).
- Click **Use this template - Create a new repository** to create you own CI test flow in your GitHub account.
- Click **Use this template - Create a new repository** to create your own CI test flow in your GitHub account.

**Build:**

In VS Code use:
In VS Code:

- Open *Source Control Activity Bar* and use *Clone Repository* to get the application on your local computer.
- Open the *Source Control Activity Bar* and use *Clone Repository* to get the application on your local computer.
- Open *CMSIS Activity Bar* and *Build* the application.

> **Note:**
> [!NOTE]
>
> When you open the project for the first time, the *Arm Tools Environment* managed with [vcpkg](https://www.keil.arm.com/artifacts/) gets installed which may take some minutes.
> When you open the project for the first time, the *Arm Tools Environment* managed with [vcpkg](https://www.keil.arm.com/artifacts/) is installed, which may take a few minutes.

**Run:**

In VS Code open the *CMSIS Activity Bar* and *Run* the application.
In VS Code, open the *CMSIS Activity Bar* and *Run* the application.

**Debug:**

In VS Code open the *CMSIS Activity Bar* and *Debug* the application.
In VS Code, open the *CMSIS Activity Bar* and *Debug* the application.

## More CI Examples

Arm is using CI validation tests for many projects. The list below are only a few examples that may be used to derive own CI test projects.
Arm uses CI validation tests like this for many projects. Most CMSIS software components are validated with FVP simulation, as shown in the table below. You can explore [other projects with topic "cicd"](https://github.com/search?q=topic%3Acicd+org%3AArm-Examples+fork%3Atrue&type=repositories) or read **[CI/CD](https://github.com/Arm-Examples/.github/blob/main/profile/CICD.md)** to learn more. While this test uses [FVP simulation models](https://arm-software.github.io/AVH/main/simulation/html/index.html), you can also run tests on [hardware targets using a self-hosted runner](https://github.com/Arm-Examples/.github/blob/main/profile/RPI_GH_Runner.md).

Resource | Description
:------------------|:------------------
[AVH-Hello](https://github.com/Arm-Examples/AVH-Hello) | Build and execution test for "Hello World" example using a GitHub Action matrix to target all Cortex-M processors, Arm Compiler or GCC, and AVH simulation.
[CMSIS Version 6](https://github.com/ARM-software/CMSIS_6/actions) | Runs a CMSIS-Core validation test across the supported processors using multiple compilers.
[RTOS2 Validation](https://github.com/ARM-software/CMSIS-RTX/actions) | Runs the CMSIS-RTOS2 validation across Keil RTX using source and library variants.
[STM32H743I-EVAL_BSP](https://github.com/Open-CMSIS-Pack/STM32H743I-EVAL_BSP) | Build test of a Board Support Pack (BSP) with MDK-Middleware [Reference Applications](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/ReferenceApplications.md) using Arm Compiler or GCC. The artifacts store the various example projects for testing on the hardware board.
[TFL Micro Speech](https://github.com/arm-software/AVH-TFLmicrospeech) | This example project shows the Virtual Streaming Interface with Audio input and uses [software layers](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/blob/main/docs/build-overview.md#software-layers) for retargeting.

## Other Developer Resources

Resource | Description
:------------------|:------------------
[Documentation](https://arm-software.github.io/AVH/main/overview/html/index.html) | Is a comprehensive documentation about Arm Virtual Hardware.
[Documentation](https://arm-software.github.io/AVH/main/overview/html/index.html) | Comprehensive documentation for FVP simulation models.
[Support Forum](https://community.arm.com/support-forums/f/arm-virtual-hardware-targets-forum) | Arm Virtual Hardware is supported via a forum. Your feedback will influence future roadmap.
[AVH-MLOps](https://github.com/ARM-software/AVH-MLOps) | Shows the setup of a Docker container with foundation tools for CI and MLOps systems.
[Marketing Overview](https://www.arm.com/virtual-hardware) | Gives you a top-level marketing message.

## Related Webinar Recordings

- [MDK v6 Technical Deep Dive](https://on-demand.arm.com/flow/arm/devhub/sessionCatalog/page/pubSessCatalog/session/1713958336497001CQIR)
- [CLI builds using CMSIS-Toolbox](https://on-demand.arm.com/flow/arm/devhub/sessionCatalog/page/pubSessCatalog/session/1708432622207001feYV)
- [Using CMSIS-Toolbox and Keil MDK v6 in CI/CD Workflows](https://on-demand.arm.com/flow/arm/devhub/sessionCatalog/page/pubSessCatalog/session/1718006126984001DUAn)
- [Using CMSIS-View and CMSIS-Compiler](https://on-demand.arm.com/flow/arm/devhub/sessionCatalog/page/pubSessCatalog/session/1706872120089001ictY)
- [Data streaming with CMSIS-Stream and SDS](https://on-demand.arm.com/flow/arm/devhub/sessionCatalog/page/pubSessCatalog/session/1709221848113001nOU5)