### 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 Source: https://open-cmsis-pack.github.io/cmsis-toolbox/pack-tools PDSC file snippet that registers an example using the element. It defines the example folder, documentation, board, and multiple project environments (csolution and uv) to support different tool environments. ```xml Example that shows the usage of Fault component on a Cortex-M33 with TrustZone ``` -------------------------------- ### 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 /Vendor.PackName.x.y.z.pack ``` -------------------------------- ### Register reference application in PDSC Source: https://open-cmsis-pack.github.io/cmsis-toolbox/pack-tools Registers a reference application in a PDSC file using the element. Unlike regular examples, no element is used because the reference application is hardware agnostic. The example loads its csolution project via the element with the csolution name. ```xml MDK-Middleware: IPv4/IPv6 Client and Server applications via Ethernet ``` -------------------------------- ### 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 [@], --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 [@] [--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] ```