CMSIS-Toolbox

https://open-cmsis-pack.github.io/cmsis-toolbox
Admin
CMSIS-Toolbox is a set of command-line tools for creating, configuring, and building embedded...
Tokens:173,949
Snippets:1,008
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example: install repository pack with cpackget add

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/build-tools

Example of installing a repository pack by specifying the .pdsc file path.

```shell
cpackget add /work/IoT_Socket/MDK-Packs.IoT_Socket.pdsc

```

--------------------------------

### Minimal project setup: Sample.csolution.yml and Sample.cproject.yml

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/build-overview

Minimal project setup requires two files: Sample.csolution.yml defines target type, compiler, and build types; Sample.cproject.yml defines files and components. When no packs are specified, the tools use the latest installed pack versions.

```yaml
solution:
  cdefault:                                   # use default setup for toolchains
  compiler: AC6                               # select the compiler to use

  packs:                                      # explicit pack selection may be omitted
    - pack: NXP::K32L3A60_DFP@16.0.0          # specify DFP
    - pack: NXP::FRDM-K32L3A6_BSP@16.0.0

  target-types:
    - type: FRDM-K32L3A6
      board: FRDM-K32L3A6

  build-types:                                # defines toolchain options for 'debug' and 'release'
    - type: Debug
      debug: on
      optimize: debug

    - type: Release
      debug: off
      optimize: balanced

  projects:
    - project: ./Sample.cproject.yml

```

```yaml
project:
  packs:
    - pack: ARM::CMSIS                        # specify additional packs

  groups:
    - group: App
      files:
        - file: ./main.c

  components:
    - component: CMSIS:CORE
    - component: Device:Startup

```

--------------------------------

### Install pack list from file with cpackget add -f

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/build-tools

Installs a list of software packs from a text file. Each line in the file specifies a single pack, optionally with version information as shown in the example list-of-packs.txt.

```shell
cpackget add -f list-of-packs.txt

```

```text
ARM::CMSIS
ARM::CMSIS-Driver
ARM::CMSIS-FreeRTOS@10.4.6
ARM::mbedTLS@1.7.0
AWS::backoffAlgorithm@1.0.0-Beta
  :

```

--------------------------------

### ctrace.yml example with data, events, and ITM

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/Experimental-Features

Complete example of a *.ctrace.yml file showing the ctrace node with setup, timestamps, data trace, events, and ITM configuration. The setup includes a pname placeholder, timestamps clock, timesync, data locations with access and match, events, and ITM enable/privileged settings.

```yaml
ctrace:
  created-by: CMSIS-Debugger v1.4.0
  setup:
    - pname: 
#     disable:    # disables trace without need to remove settings
      timestamps:
        clock: 24000000
      timesync:

      data:
        - location: mysimple

        - location: App|0x20001000
          access: RW
          size: 0x100
          output: PC

        - location: App|"main.c"::sample_counter
          access: R
          output: PC
          match:
            value: 0x00001234
            size: 4

      exceptions:
      events:
        - event: CPICNT
        - event: LSUCNT

      itm:
        enable: 0x0000000F
        privileged: 0x0

```

--------------------------------

### Minimal pyOCD setup with MySetup.csolution.yml and cbuild setup

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/pyOCD-Debugger

Defines a minimal pyOCD setup using a csolution file and generates the corresponding cbuild-run file. The YAML specifies the DFP, target device, image, and debugger configuration; the commands install the pack and run cbuild setup to produce out/MySetup+PSE8_Target.cbuild-run.yml.

```yaml
solution:
  packs:
    - pack: Infineon::PSE8xxx_DFP@1.0.1     # Device Family Pack (DFP)

  target-types:
    - type: PSE8_Target                     # Target name
      device: PSE812GOS2DFNC4B              # Device name from DFP
      target-set:
        - set:
          images:
            - image: out/MyFile.hex         # Image files used
          debugger:
            name: CMSIS-DAP@pyOCD           # Debugger configuration
            clock: 10000000
            protocol: swd

```

```shell
cpackget add Infineon::PSE8xxx_DFP@1.0.1
cbuild setup MySetup.csolution.yml --active PSE8_Target

```

--------------------------------

### Install pack from URL with cpackget add

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/build-tools

Downloads and installs a software pack that is available via a URL.

```shell
cpackget add https://vendor.com/example/Vendor.PackName.x.y.z.pack

```

--------------------------------

### Setup project for IDE with cbuild setup

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/build-tools

Sets up a project for an IDE: downloads missing packs, creates build information files, and generates compile_commands.json for IntelliSense.

```shell
cbuild setup example.csolution.yml --context-set --packs

```

--------------------------------

### pack: Examples

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/YML-Input-Format

Examples of pack specifications in csolution project files, demonstrating version constraints and wildcards.

```yaml
- pack:   ARM::CMSIS@5.9.0                 # 'CMSIS' Pack with version 5.9.0
- pack:   Keil::MDK-Middleware@>=7.13.0    # latest version 7.13.0 or higher
- pack:   Keil::MDK-Middleware@^7.13.0     # latest version 7.13.0 or higher, but lower than 8.0.0
- pack:   Keil::TFM                        # 'TFM' Pack from vendor Keil, latest installed version
- pack:   AWS                              # All Software Packs from vendor 'AWS', latest version
- pack:   Keil::STM*                       # Software Packs that start with 'STM' from vendor 'Keil'
- pack:   Keil::MDK-Middleware@>=8.0.0-0   # version 8.0.0 or higher including pre-release versions
```

--------------------------------

### Register an Example in PDSC File with <examples>

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/pack-tools

PDSC file snippet that registers an example using the <examples> element. It defines the example folder, documentation, board, and multiple project environments (csolution and uv) to support different tool environments.

```xml
  <examples>
    <example name="Fault example" folder="Examples/Fault/B-U585I-IOT02A" doc="README.md">
      <description>Example that shows the usage of Fault component on a Cortex-M33 with TrustZone</description>
      <board name="B-U585I-IOT02A" vendor="STMicroelectronics"/>
      <project>
        <environment name="csolution" load="Fault.csolution.yml"/>
        <environment name="uv" load="Fault.uvmpw"/>
      </project>
    </example>
  </examples>
```

--------------------------------

### Install local pack file with cpackget add

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/build-tools

Installs a software pack that is available on the local computer by referring to the .pack file itself.

```shell
cpackget add <path>/Vendor.PackName.x.y.z.pack

```

--------------------------------

### Register reference application in PDSC <examples>

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/pack-tools

Registers a reference application in a PDSC file using the <examples> element. Unlike regular examples, no <board> element is used because the reference application is hardware agnostic. The example loads its csolution project via the <environment> element with the csolution name.

```xml
  <examples>
    </example>
    <example name="Network" doc="README.md" folder="Examples/Network">
      <description>MDK-Middleware: IPv4/IPv6 Client and Server applications via Ethernet</description>
      <project>
        <environment name="csolution" load="Network.csolution.yml"/>
      </project>
    </example>


```

--------------------------------

### solution: node example in a .csolution.yml file

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/YML-Input-Format

Example of a `*.csolution.yml` file that collects related projects. It sets the minimum CMSIS-Toolbox version, uses the default toolchain controls, overrides the compiler to GCC, adds ST packs, defines a Test build-type with explicit pack specification, and lists two target-types (Board and Production-HW) with their respective board or device. The `projects` section references three project files.

```yaml
solution:
  created-for: cmsis-toolbox@2.6  # minimum CMSIS-Toolbox version required for project build
  cdefault:                       # use default setup of toolchain-specific controls.
  compiler: GCC                   # overwrite compiler definition in 'cdefaults.yml'

  packs:
    - pack: ST                    # add ST packs in 'cdefaults.yml'

  build-types:                    # additional build types
    - type: Test                  # build-type: Test
      optimize: none
      debug: on
      packs:                      # with explicit pack specification
        - pack: ST::TestSW
          path: ./MyDev/TestSW

  target-types:
    - type: Board                 # target-type: Board
      board: NUCLEO-L552ZE-Q

    - type: Production-HW         # target-type: Production-HW
      device: STM32U5X            # specifies device

  projects:
    - project: ./blinky/Bootloader.cproject.yml
    - project: /security/TFM.cproject.yml
    - project: /application/MQTT_AWS.cproject.yml
```

--------------------------------

### Declare multiple component instances with `instances:`

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/YML-Input-Format

Declares multiple instances of a component in a csolution YAML file. When the user selects multiple instances, all files with the `config` attribute in the `*.PDSC` file are copied multiple times, and the component name gets a postfix `_n` (instance number starting with 0).

```yaml
  components:
    - component: USB:Device
      instances: 2

```

--------------------------------

### csolution.yml for an Example with select-compiler and TrustZone

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/pack-tools

Example csolution.yml for a TrustZone Fault example on a Cortex-M33. Uses select-compiler instead of compiler, specifies minimum pack versions, and defines two build-types (Debug and Release). The projects list references two separate project files for Secure and NonSecure domains.

```yaml
solution:
# Optional: Add a brief description line (recommendation less than 128 characters)
  description: Example that shows the usage of Fault component on a Cortex-M33 with TrustZone

  created-for: CMSIS-Toolbox@2.6.0          # minimum CMSIS-Toolbox version, newer versions will work also
  cdefault:

  select-compiler:
    - compiler: GCC               # GCC is supported
    - compiler: AC6               # AC6 is supported
    - compiler: IAR               # IAR is supported

  packs:
    - pack: Keil::STM32U5xx_DFP@^2.1.0      # minimum compatible pack version
    - pack: Keil::B-U585I-IOT02A_BSP@^1.0.0

  target-types:
    - type: B-U585I-IOT02A
      board: STMicroelectronics::B-U585I-IOT02A
      device: STMicroelectronics::STM32U585AIIx

  build-types:
    - type: Debug
      debug: on
      optimize: debug

    - type: Release
      debug: off
      optimize: balanced

  projects:
    - project: ./Secure/Fault_S.cproject.yml
    - project: ./NonSecure/Fault_NS.cproject.yml
```

--------------------------------

### Define project setups with for-compiler and linker script

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/YML-Input-Format

Defines two project setups in a CMSIS-Toolbox project file: one for Arm Compiler 6 (AC6) and one for GCC. Each setup specifies a linker script and a define symbol. The `for-compiler` key selects the setup for the matching compiler.

```yaml
project:
  setups:
    - setup: Arm Compiler 6 project setup
      for-compiler: AC6
      linker:
        - script: my-project.sct
      define:
        - test: 12

   - setup: GCC project setup
     for-compiler: GCC
     linker:
       - script: my-project.inc
     define:
       - test: 11

```

--------------------------------

### board: name examples in YAML files

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/YML-Input-Format

Examples of board: values, including a board with vendor, a board without vendor, and a board with revision.

```yaml
board: Keil::MCB54110                             # The Keil MCB54110 board (with device NXP::LPC54114J256BD64)
board: LPCXpresso55S28                            # The LPCXpresso55S28 board
board: STMicroelectronics::NUCLEO-L476RG:Rev.C    # A board with revision specification
```

--------------------------------

### cbuild setup command for IDE project outline

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/build-tools

Use this command when an IDE starts to set up the project outline view and obtain information about components and software layers. The --active option selects one target in the format <target-type>[@<target-set>], --packs enables downloading missing public software packs, and --update-rte is used when the IDE changes device:, board:, or component: settings. The command creates build information files and generates compile_commands.json for IntelliSense in a VS Code IDE environment.

```text
cbuild setup example.csolution.yml --active <target-type>[@<target-set>] [--packs] [--update-rte]

```

--------------------------------

### component: Examples

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/YML-Input-Format

Examples of valid component specifications in csolution project files, showing various combinations of vendor, class, bundle, group, sub, variant, and version.

```yaml
- component: CMSIS:CORE                               # CMSIS Core component (vendor selected by `csolution` ARM)
- component: ARM::CMSIS:CORE                          # CMSIS Core component from vendor ARM (any version)
- component: ARM::CMSIS:CORE@5.5.0                    # CMSIS Core component from vendor ARM (with version 5.5.0)
- component: ARM::CMSIS:CORE@>=5.5.0                  # CMSIS Core component from vendor ARM (with version 5.5.0 or higher)

- component: Device:Startup                           # Device Startup component from any vendor

- component: CMSIS:RTOS2:Keil RTX5                    # CMSIS RTOS2 Keil RTX5 component with default variant (any version)
- component: ARM::CMSIS:RTOS2:Keil RTX5&Source@5.5.3  # CMSIS RTOS2 Keil RTX5 component with variant 'Source' and version 5.5.3

- component: Keil::USB&MDK-Pro:CORE&Release@6.15.1    # USB CORE component from bundle MDK-Pro in variant 'Release' and version 6.15.1

```

--------------------------------

### Custom output-dirs example

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/YML-Input-Format

Example of custom `output-dirs:` configuration. `tmpdir` and `outdir` are relative to the `csolution.yml` file; `outdir` uses `$Project$` and `$TargetType$` variables.

```yaml
output-dirs:
  tmpdir: ./tmp2                         # relative path to csolution.yml file
  outdir: ./out/$Project$/$TargetType$   # $BuildType$ no longer part of the outdir

```

--------------------------------

### device: naming examples in YAML files

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/YML-Input-Format

Illustrates valid `device:` entries, including variants with vendor, device name, and processor name. Notes that `Dname` is always required and vendor is evaluated from the DFP when omitted.

```yaml
device: NXP::LPC1768                       # The LPC1788 device from NXP
device: LPC1788                            # The LPC1788 device (vendor is evaluated from DFP)
device: LPC55S69JEV98                      # Device name (exact name as defined in the DFP)
device: LPC55S69JEV98:cm33_core0           # Device name (exact name as defined in the DFP) with Pname specified
device: :cm33_core0                        # Pname added to a previously defined device name (or a device derived from a board)
```

--------------------------------

### rte base-dir example

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/YML-Input-Format

Example of `rte:` configuration. The `base-dir` is relative to the `*.cproject.yml` file and is extended with the target type, resulting in `$ProjectDir()$/$TargetType$/RTE`.

```yaml
rte:
  base-dir: $TargetType$/RTE      # Path extended with target-type, results in `$ProjectDir()$/$TargetType$/RTE`

```

--------------------------------

### Run cbuild setup and observe undefined variable error

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/ReferenceApplications

Run `cbuild setup` with the `*.csolution.yml` file. This identifies compatible layers and produces an error about undefined variables, instructing to copy settings from `cbuild-idx.yml` to `csolution.yml`.

```text
>cbuild setup xxx.csolution.yml
error csolution: undefined variables in xxx.csolution.yml:
  - $Board-Layer$
To resolve undefined variables, copy the settings from cbuild-idx.yml to csolution.yml

```

--------------------------------

### project: node example for *.cproject.yml

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/YML-Input-Format

Shows the required and optional nodes of a `*.cproject.yml` file. Use this structure to define a project with compiler-specific options, include paths, components, and source file groups. The example includes a secure/non-secure split with `$OutDir(Secure)$` and `$Source(Secure)$` path variables.

```yaml
project:
  misc:
    - compiler: AC6                          # specify misc controls for Arm Compiler 6
      C: [-fshort-enums, -fshort-wchar]      # set options for C files
  add-path:
    - $OutDir(Secure)$                       # add the path to the secure project's output directory
  components:
    - component: Startup                     # Add startup component
    - component: CMSIS CORE
    - component: Keil RTX5 Library_NS
  groups:
    - group: Non-secure Code                 # Create group
      files:
        - file: main_ns.c                    # Add files to group
        - file: $Source(Secure)$interface.h
        - file: $Output(Secure)$_CMSE_Lib.o

```

--------------------------------

### pyOCD and ULINKplus debugger configuration examples

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/YML-Input-Format

Two example debugger configurations for pyOCD and ULINKplus. The first uses CMSIS-DAP@pyOCD with SWD protocol and 20 MHz clock. The second uses ULINKplus with JTAG protocol, 10 MHz clock, and a dbgconf file.

```yaml
debugger:
  name: CMSIS-DAP@pyOCD
  protocol: swd
  clock: 20000000               # 20 MHz

```

```yaml
debugger:
  name: ULINKplus
  protocol: jtag
  clock: 10000000               # 10 MHz
  dbgconf: MyHardware.dbgconf

```

--------------------------------

### layer: node example for *.clayer.yml

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/YML-Input-Format

Shows the structure of a `*.clayer.yml` file that defines a Software Layer. Use this to specify layer type, description, processor settings, components, and source file groups. The example sets the processor to secure and includes secure code and CMSE interface files.

```yaml
layer:
  type: Board
  description: Setup with Ethernet and WiFi interface
  processor:
    trustzone: secure        # set processor to secure
  components:
    - component: Startup
    - component: CMSIS CORE
  groups:
    - group: Secure Code
      files:
        - file: main_s.c
    - group: CMSE
      files:
        - file: interface.c
        - file: interface.h
        - file: tz_context.c

```

--------------------------------

### select-compiler: in csolution.yml

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/YML-Input-Format

Lists supported compilers in a csolution project file. The cbuild setup command uses this information to determine possible compiler choices. Only supported in *.csolution.yml files and requires CMSIS-Toolbox 2.5.0 or later.

```yaml
solution:
  created-for: cmsis-toolbox@2.5  # minimum CMSIS-Toolbox version required for project build
  select-compiler:                # list tested compilers that can be selected
    - compiler: GCC               # GCC is supported
    - compiler: AC6@6.22          # AC6 is supported, version number is a hint on what was tested

```

--------------------------------

### Release build-type with reordered key/value pairs

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/YML-Input-Format

Defines the same Release build-type as the previous example but with the key/value pairs in a different order. This illustrates that the order of list node key/value pairs does not affect the logical meaning.

```yaml
  build-types:
    - debug: off            # generate no debug information for the release build
      optimize: size        # optimize for size
      type: Release         # build-type name

```

--------------------------------

### Access sequences: solution definition, $cmse-lib$ references, and cbuild --active

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/YML-Input-Format

Shows the solution definition with target-types, build-types, and projects, then how a cproject.yml file references the TFM project's symbol output file using the $cmse-lib$ access sequence. The cbuild command selects the Production-HW build variant with --active. The final example uses the explicit build-type Debug and target-type Production-HW in the access sequence.

```yaml
solution:
  target-types:
    - type: Board               # target-type: Board
      board: NUCLEO-L552ZE-Q    # specifies board
      target-set:
        - set:
          - project-context: TFM.Debug
          - project-context: MQTT_AWS.Debug

    - type: Production-HW       # target-type: Production-HW
      device: STM32L5X          # specifies device
      target-set:
        - set:
          - project-context: TFM.Release
          - project-context: MQTT_AWS.Debug

  build-types:
    - type: Debug               # build-type: Debug
      optimize: none
      debug: on

    - type: Release             # build-type: Release
      optimize: size

  projects:
    - project: ./bootloader/Bootloader.cproject.yml           # relative path
    - project: /MyDevelopmentTree/security/TFM.cproject.yml   # absolute path
    - project: ./application/MQTT_AWS.cproject.yml            # relative path

```

```yaml
    files:
      - file: $cmse-lib(TFM)$                         # use symbol output file of TFM Project

```

```shell
cbuild iot-product.csolution.yml --active Production-HW

```

```yaml
    files:
    - file: `$cmse-lib(TFM.Release+Production-HW)$` # use symbol output file of TFM Project

```

--------------------------------

### Execute gen_image with executes: in csolution.yml

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/YML-Input-Format

Use in a *.csolution.yml file to run an external tool as a post-build step during a complete solution build (when --context is not used). The example invokes gen_image with the ELF files from the Application, TFM, and Bootloader projects as inputs and writes the combined image to $SolutionDir()$/$Solution$.out. The run command uses $input$ and $output$ access sequences for dependency checking.

```yaml
solution:                                     # executed as part of a complete solution build
    :
  executes:
    - execute: GenImage                       # generate final download image
      run: gen_image $input$ -o $output$ --sign    # command string
      input:
        - $elf(Application)$                  # combine these project parts
        - $elf(TFM)$
        - $elf(Bootloader)$
      output:
        - $SolutionDir()$/$Solution$.out      # output file name

```

--------------------------------

### Select processor core with device: in cproject.yml

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/YML-Input-Format

Selects the processor core for a project when the device has multiple cores. The device is chosen in the csolution.yml file, and only the pname is specified here. The first example selects the cm4 core, the second selects the cm0plus core.

```yaml
project:
  device: :cm4

```

```yaml
project:
  device: :cm0plus

```

--------------------------------

### Context list syntax: [.build-type][+target-type]

Source: https://open-cmsis-pack.github.io/cmsis-toolbox/YML-Input-Format

A context list entry combines an optional build-type (prefixed with `.`) and an optional target-type (prefixed with `+`). Each line represents one context name; the context name must start with `.` or `+` because the project-name cannot be used with `for-context:` or `not-for-context:`.

```yaml
  - [.build-type][+target-type]
  - [.build-type][+target-type]

```
Tokens:
Raw