Reworked for CMSIS-Toolbox 2.11 (#418)

ReinhardKeil · web-flow · commit 63a0b33e45b6 · 2025-09-08T10:30:35.000+02:00
## Fixes Open-CMSIS-Pack/devtools#2109 Open-CMSIS-Pack/devtools#2140 Open-CMSIS-Pack/devtools#2151 Open-CMSIS-Pack/devtools#2156 Open-CMSIS-Pack/devtools#2176
diff --git a/docs/YML-CBuild-Format.md b/docs/YML-CBuild-Format.md
@@ -16,6 +16,8 @@ File                                  | Description
 [`*.cbuild-set.yml`](#cbuild-setyml)  | [Context selection](build-overview.md#working-with-context-set) for the build process, enabled with option [--context-set:](build-tools.md#use-context-set).
 [`*.cbuild-run.yml`](#run-and-debug-management)  | Contains the information required to [download and debug](#run-and-debug-management) a *csolution project* to a target.
 
+!!! Note CMSIS-Toolbox 2.11 creates the `*.cbuild.yml` and `*.cbuild-run.yml` files in the `out` directory along with the related output files.
+
 ## Directory Structure
 
 The `csolution` based projects are portable across different host computers and use, therefore **relative file references**.
@@ -38,14 +40,19 @@ A typical directory structure of a `csolution` based application that uses commo
  ┣ myapp.cbuild-pack.yml
  ┣ myapp.cbuild-set.yml
  ┣ 📂 project1
- ┃  ┣  mypro1.cproject.yml
- ┃  ┣  mypro1.cbuild.Debug+Target.yml     # file references are relative to directory project1
+ ┃  ┣  mypro1.cproject.yml                 # file references are relative to directory project1
  ┣ 📂 project2
- ┃  ┣  mypro2.cproject.yml
- ┃  ┣  mypro2.cbuild.Debug+Target.yml     # file references are relative to directory project2
+ ┃  ┣  mypro2.cproject.yml                 # file references are relative to directory project
  ┣ 📂 layer
- ┃  ┣  mylayer.clayer.yml
-```
+ ┃  ┣  mylayer.clayer.yml                  # file references are relative to directory layer
+ ┣ 📂 out
+ ┃  ┣  myapp+Target.cbuild-run.yml         # file references are relative to directory out
+ ┣  ┣ 📂 mypro1\Target\Debug
+ ┣  ┣  ┣  mypro1.cbuild.Debug+Target.yml   # file references are relative to directory out\mypro1\Target\Debug
+ ┣  ┣ 📂 mypro2\Target\Debug
+ ┣  ┣  ┣  mypro2.cbuild.Debug+Target.yml   # file references are relative to directory out\mypro2\Target\Debug
+ 
+ ```
 
 ## Lock Pack Versions
 
@@ -139,10 +146,10 @@ build-idx:
       clayers:
         - clayer: $Board-Layer$
   cbuilds:
-    - cbuild: Device/HID/HID.Debug+B-U585I-IOT02A.cbuild.yml
+    - cbuild: out/HID/B-U585I-IOT02A/Debug/HID.Debug+B-U585I-IOT02A.cbuild.yml
       project: HID
       configuration: .Debug+B-U585I-IOT02A
-    - cbuild: Device/MassStorage/MassStorage.Release+B-U585I-IOT02A.cbuild.yml
+    - cbuild: out/MassStorage/B-U585I-IOT02A/Release/MassStorage.Release+B-U585I-IOT02A.cbuild.yml
       project: MassStorage
       configuration: .Release+B-U585I-IOT02A
   errors: true                  # indicates error
@@ -558,6 +565,7 @@ Keyword          | Description
 &nbsp;&nbsp;&nbsp; [`add-path:`](YML-Input-Format.md#add-path) | Additional include file paths.
 &nbsp;&nbsp;&nbsp; [`misc:`](YML-Input-Format.md#misc)         | Literal tool-specific controls.
 &nbsp;&nbsp;&nbsp; `instances:`                                | Number of component instances configured.
+&nbsp;&nbsp;&nbsp; `maxInstances:`                             | Maximum number component instances that can be configured.
 &nbsp;&nbsp;&nbsp; [`generator:`](#generator)                  | Generator information for components that are configurable via a generator.
 &nbsp;&nbsp;&nbsp; `implements:`                               | Refers to the API that the component is based on.
 &nbsp;&nbsp;&nbsp; [`files:`](#files-of-a-component)           | List of files that belong to this component.
diff --git a/docs/YML-Input-Format.md b/docs/YML-Input-Format.md
@@ -1411,6 +1411,8 @@ The `images:` node under `target-set:` specifies the projects with build-type an
 &nbsp;&nbsp;&nbsp; `info:`                            |   Optional   | Brief description of the image file.
 &nbsp;&nbsp;&nbsp; [`type:`](#type)                   |   Optional   | Specifies an explicit file of the image type.
 &nbsp;&nbsp;&nbsp; `load-offset:`                     |   Optional   | Offset applied to the binary content when loading the image file.
+&nbsp;&nbsp;&nbsp; [`device:`](#device)               |   Optional   | For image files a pname can be specified to denote the processor that runs the image.
+
 
 !!! Note
     Either `project-context:` or `image:` is required, but these nodes are mutually exclusive.
@@ -1422,9 +1424,9 @@ Specifies the load mode for an image file. This information is used by programme
 
 `load:`                              | Description
 :------------------------------------|:-------------
-&nbsp;&nbsp;&nbsp; `image+symbols`   | Load both the binary image and the debug symbol information (default for file `type: elf`).
+&nbsp;&nbsp;&nbsp; `image+symbols`   | Load both the binary image and the debug symbol information (default for `project-context` and `image` with file type elf).
 &nbsp;&nbsp;&nbsp; `symbols`         | Load only the debug symbol information.
-&nbsp;&nbsp;&nbsp; `image`           | Load only the binary image (default for other file types).
+&nbsp;&nbsp;&nbsp; `image`           | Load only the binary image (default `image` for other file types).
 &nbsp;&nbsp;&nbsp; `none`            | No content is loaded for this image, however it is part of the build process.
 
 #### `type:`
@@ -1449,7 +1451,7 @@ solution:
       board: FRDM-MCXN947
       device: NXP::MCXN947VDF
       target-set:
-        - set:                             // without id, <default> set
+        - set:                             # without id, <default> set
           debugger:
             name: ST-Link
           images:
@@ -1458,12 +1460,14 @@ solution:
         - set: production
           images:
           - project-context: core1.Release
+            device: :core1                 # specify the pname that runs the image
           - project-context: core0.Release
+            device: :core0                 # specify the pname that runs the image
 
     - type: Custom-HW
       device: NXP::MCXN947VDF
       target-set:
-        - set:                             // without id, <default> set
+        - set:                             # without id, <default> set
           debugger:
             name: ULINKplus
             protocol: swd
diff --git a/docs/build-tools.md b/docs/build-tools.md
@@ -22,7 +22,7 @@ There are several ways to configure the CMSIS-Pack repository:
 Orchestrate the overall build steps utilizing the various tools of the CMSIS-Toolbox and a CMake-based compilation process.
 
 ```txt
-cbuild: Build Invocation 2.9.0 (C) 2022-2025 Arm Ltd. and Contributors
+cbuild: Build Invocation 2.11.0 (C) 2022-2025 Arm Ltd. and Contributors
 
 Usage:
   cbuild [command] <name>.csolution.yml [options]
@@ -78,15 +78,19 @@ Commands:
   list configs                  Print list of configuration files
   list contexts                 Print list of contexts in a <name>.csolution.yml
   list components               Print list of available components
+  list debuggers                Print list of debuggers from debug-adapters.yml
   list dependencies             Print list of unresolved project dependencies
   list devices                  Print list of available device names
   list environment              Print list of environment configurations
+  list examples                 Print list of examples
+  list templates                Print list of templates
   list generators               Print list of code generators of a given context
   list layers                   Print list of available, referenced and compatible layers
   list packs                    Print list of used packs from the pack repository
   list target-sets              Print list of target-sets in a <name>.csolution.yml
   list toolchains               Print list of supported toolchains
   run                           Run code generator
+  rpc                           Run remote procedure call server
   update-rte                    Create/update configuration files and validate solution
 
 Options:
@@ -104,7 +108,6 @@ Options:
   -N, --no-update-rte           Skip creation of RTE directory and files
   -o,-O --output arg            Base folder for output files, 'outdir' and 'tmpdir' (default "Same as '*.csolution.yml'")
   -q, --quiet                   Run silently, printing only error messages
-  -R, --relative-paths          Print paths relative to project or ${CMSIS_PACK_ROOT}
   -S, --context-set             Select the context names from cbuild-set.yml for generating the target application
   -t, --toolchain arg           Selection of the toolchain used in the project optionally with version
   -v, --verbose                 Enable verbose messages
@@ -118,7 +121,8 @@ Use 'csolution <command> -h' for more information about a command.
 Manage the installation of *software packs* on the host computer.
 
 ``` txt
-cpackget version 2.1.7 (C) 2021-2023 Linaro, 2024-2025 Arm Ltd.
+cpackget version 2.1.9
+ (C) 2021-2023 Linaro, 2024-2025 Arm Ltd.
 
 Usage:
   cpackget [command] [flags]
@@ -229,7 +233,7 @@ To install software packs from a public web service, run:
 
 ```shell
 cpackget add Arm::CMSIS
-cpackget add Arm::CMSIS@5.9.0     # optional with version specification
+cpackget add Arm::CMSIS@6.1.0     # optional with version specification
 ```
 
 ### List Installed Packs
diff --git a/docs/index.md b/docs/index.md
@@ -40,6 +40,7 @@ Thank you for using the **CMSIS-Toolbox** that provides command-line tools for:
 
 Version            | Description
 :-----------------:|:-------------------------
+2.11.0             | CMSIS-Toolbox [2.11.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases/tag/2.11.0). For a [`image:`](YML-Input-Format.md#images) the [`device:`](YML-Input-Format.md#device) node can be used to specify a processor `pname`. [`csolution`](build-tools.md#csolution-invocation) adds commands that list debuggers, examples, and templates. The files [`cbuild.yml`](YML-CBuild-Format.md) and [`cbuild-run.yml`](YML-CBuild-Format.md) are now located in `out` directory.
 2.10.0             | CMSIS-Toolbox [2.10.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases/tag/2.10.0). Extends [`load:`](YML-Input-Format.md#load) to `project-context:`, adds a [server mode](Experimental-Features.md#server-mode) and corrects [several issues](https://github.com/orgs/Open-CMSIS-Pack/projects/22/views/7) such as ST-Link debug adapter selection and CubeMX support.
 2.9.0              | CMSIS-Toolbox [2.9.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases/tag/2.9.0). Added the input nodes [`link-time-optimize:`](YML-Input-Format.md#link-time-optimize) and [`target-set:`](YML-Input-Format.md#target-set) to configure application scope and [`debugger:`](YML-Input-Format.md#debugger). The [`images:`](YML-Input-Format.md#images) node (previously `load:`) adds ELF files generated with other systems. The [Run and Debug Configuration](build-overview.md#run-and-debug-configuration) using the [`cbuild-run.yml`](YML-CBuild-Format.md#run-and-debug-management) file is extended for multi-core systems and a range of supported [Debug Adapters](build-operation.md#debug-adapter-integration). See here for [more details](https://github.com/orgs/Open-CMSIS-Pack/projects/19).
 2.8.0              | CMSIS-Toolbox [2.8.0](https://github.com/Open-CMSIS-Pack/cmsis-toolbox/releases/tag/2.8.0). New YML input nodes to add [`memory:`](YML-Input-Format.md#memory), configure [`debugger:`](YML-Input-Format.md#debugger), and [`load:`](YML-Input-Format.md#images) to add image files. The [`*.cbuild-run.yml`](YML-CBuild-Format.md#run-and-debug-management) file contains run and debug information for a target. See here for [more details](https://github.com/orgs/Open-CMSIS-Pack/projects/17).
