Added pyOCD Debugger Information

Author: ReinhardKeil

docs/MCUXpressoConfig.md

@@ -1,4 +1,4 @@
-# Configure NXP Devices with MCUXpresso Config Tools
+# MCUXpresso for NXP Devices
 
 <!-- markdownlint-disable MD009 -->
 <!-- markdownlint-disable MD013 -->

docs/YML-Input-Format.md

@@ -2548,15 +2548,19 @@ CMSIS-DAP supports the SWO trace output of Cortex-M devices. The device-specific
 
 This section lists options that are specific for the Arm Debugger.
 
-debugger:                         |             | Description
-:---------------------------------|:------------|:-----------------------------------------------
-&nbsp;&nbsp;&nbsp; `name:`        |**Required** | Identifies the debug adapter with `<adapter>@Arm-Debugger`.
+debugger:                            |             | Description
+:------------------------------------|:------------|:-----------------------------------------------
+&nbsp;&nbsp;&nbsp; `name:`           |**Required** | Identifies the debug adapter with `<adapter>@Arm-Debugger`.
+&nbsp;&nbsp;&nbsp; `clock-armdbg`    |  Optional   | Debug clock speed. Possible values: auto (default), 50MHz, 33MHz, 25MHz, 20MHz, 10MHz, 5MHz, 2MHz, 1MHz, 500kHz, 200kHz, 100kHz, 50kHz, 20kHz, 10kHz, 5kHz
+&nbsp;&nbsp;&nbsp; `protocol-armdbg` |  Optional   | Debug protocol. Possible values: auto (default), JTAG, SWD
 
 **Example:**
 
 ```yml
 debugger:
   name: CMSIS-DAP@Arm-Debugger
+  protocol-armdbg: SWD
+  clock-armdbg: 5MHz
 ```
 
 ### Arm-FVP
@@ -2570,7 +2574,7 @@ debugger:                         |             | Description
 &nbsp;&nbsp;&nbsp; `name:`        |**Required** | Identifies the debug adapter with `Arm-FVP`.
 &nbsp;&nbsp;&nbsp; `model:`       |  Optional   | Filename (optionally with path) of the FVP executable. Default: `FVP_MPS2_Cortex-M3`.
 &nbsp;&nbsp;&nbsp; `config-file:` |  Optional   | Path and filename of the [FVP configuration file](https://arm-software.github.io/AVH/main/simulation/html/using.html).
-`args:`                           |  Optional   | Miscellaneous [command line arguments](https://arm-software.github.io/AVH/main/simulation/html/using.html).
+&nbsp;&nbsp;&nbsp; `args:`        |  Optional   | Miscellaneous [command line arguments](https://arm-software.github.io/AVH/main/simulation/html/using.html).
 
 The following `model:` executables are installed from the [Arm Tools Artifactory](https://www.keil.arm.com/artifacts/#models/arm/avh-fvp). You should use these models in combination with a `pack:` and `device:` as listed under 
 ["CMSIS-based projects for AVH FVPs"](https://arm-software.github.io/AVH/main/simulation/html/avh_fvp_cmsis.html). The PATH environment variable of your system can define the path to the FVP executable (then only the `model:` name from the list below is required. Optionally an explicit path can be specified in the `model:` node.

docs/build-operation.md

@@ -428,7 +428,7 @@ The options are added
 `values:`                                               |            | Content
 :-------------------------------------------------------|:-----------|:------------------------------------
 `- name:`                                               |**Required**| Label text for the option in the user interface.
-    `value:`                             |**Required**| Value used for the enum name in file csolution.yml file.
+    `value:`                             |  Optional  | Value used for the enum name in csolution.yml file. If empty, `name` is used as `value`.
     `description:`                       |  Optional  | Descriptive text (hover over or sub-text in dialog).
 
 **Example**
@@ -495,8 +495,7 @@ debug-adapters:
             yml-node: trace-port
             type: enum
             values: 
-              - name: UART
-                value: UART
+              - name: UART                 # UART is also used as value
                 description: SWO configured for UART protocol
               - name: Manchester
                 value: Man
@@ -543,7 +542,6 @@ debug-adapters:
             type: enum
             values:
               name: UART
-              value: UART
             default: UART
 
   - name: "Keil uVision"

docs/index.md

@@ -22,12 +22,10 @@ Thank you for using the **CMSIS-Toolbox** that provides command-line tools for:
 
 - [**Reference Applications**](ReferenceApplications.md) explains how to use and creates examples that show middleware usage on many different evaluation boards, including custom hardware.
 
-- [**Configure STM32 Devices with STM32CubeMX**](CubeMX.md) explains how to use [STM32CubeMX](https://www.st.com/en/development-tools/stm32cubemx.html) to manage device and board configuration.
-
-- [**Configure NXP Devices with MCUXpresso Config Tools**](./MCUXpressoConfig.md) shows how to use [MCUXpresso Config Tools](https://www.nxp.com/configtools) to manage device and board configuration.
-
 - [**Build Information Files**](YML-CBuild-Format.md) details the build information generated by the `csolution` tool. It includes license information for components and configuration for download and debug.
 
+- [**pyOCD Debugger**](pyOCD-Debugger.md) explains the usage of the [pyOCD](https://pyocd.io/) Debugger in combination with the CMSIS-Toolbox configuration features.
+
 - [**Theory of Operation**](build-operation.md) contains further details about the build process including CMake, West, generator (device configurators), and debugger integration for advanced users.
 
 - [**Pack Creation**](pack-tools.md) describes how to create software packs that optionally include examples and explains the pack creation tools `packchk` (software pack verification) and `svdconv` (SVD file verification and header file generator).
@@ -36,6 +34,10 @@ Thank you for using the **CMSIS-Toolbox** that provides command-line tools for:
 
 - [**Experimental Features**](Experimental-Features.md) for resource management of multi-project linker scripts, run and debug management.
 
+- **Device Configuration Tools**
+    - [**MCUXpresso for NXP Devices**](./MCUXpressoConfig.md) shows how to use [MCUXpresso Config Tools](https://www.nxp.com/configtools) to manage device and board configuration.
+    - [**STM32CubeMX for STM32**](CubeMX.md) explains how to use [STM32CubeMX](https://www.st.com/en/development-tools/stm32cubemx.html) to manage device and board configuration.
+
 ## Revision History
 
 Version            | Description

docs/pyOCD-Debugger.md

@@ -0,0 +1,139 @@
+# pyOCD Debugger
+
+!!! Note
+    - This section contains preliminary information and is work-in-progress.
+  
+The CMSIS-Toolbox has many features. For debuggers it organizes projects and configuration options.
+This chapter explains the usage of the [pyOCD](https://pyocd.io/) Debugger in combination with these CMSIS-Toolbox features.
+
+Other manual sections describe how to configure debuggers:
+
+- [Run and Debug Configuration](build-overview.md#run-and-debug-configuration) explains overall structure and how projects and images are configured.
+- [Debugger Configuration - pyOCD](YML-Input-Format.md#pyocd) contains details about the options that are specific to pyOCD.
+
+## Command Line Invocation
+
+The CMSIS-Toolbox debugger configuration is provided in the [file `*.cbuild-run.yml`](YML-CBuild-Format.md#file-structure-of-cbuild-runyml). Use the following command line syntax to leverage this information:
+
+```bash
+>pyOCD <command> --cbuild-run <cbuild-run.yml file> [options]
+```
+
+`<command>`          | Description
+:--------------------|:-------------------------------------
+`run`                | Execute application.
+`erase`              | Erase device
+`load`               | Load image to device.
+
+`<options>`          | Description
+:--------------------|:-------------------------------------
+`--timelimit sec`    | Terminate pyOCD when the timelimit is reached.  Applies to `run` command only.
+`--eot`              | Terminate when EOT character (`0x04`) is printed via a telnet channel. Applies to `run` command only.
+`--load`             | Erase device and flash program the images specified in cbuild-run.yml. Applies to `run` command only.
+`--udi <id>`         | Specify an id of a debug probe
+
+**Examples:**
+
+ToDo: command line examples
+
+## Content of `cbuild-run.yml`
+
+This section details the content of `cbuild-run.yml` file and how it is used to configure pyOCD. The `cbuild-run.yml` file is generated by the CMSIS-Toolbox from the information provided in the *csolution project*.
+However, it is possible to create a `*.cbuild-run.yml` file manually and the following section explains the file structure.
+
+**Configuration File Example:**
+
+```yml
+todo
+```
+
+### `cbuild-run:`
+
+The `cbuild-run:` node is the start of a `*.cbuild-run.yml` file.
+
+`cbuild-run:`                                               |            | Content
+:-----------------------------------------------------------|:-----------|:------------------------------------
+&nbsp;&nbsp;&nbsp; `device:`                                |  Optional  | Identifies the device.
+&nbsp;&nbsp;&nbsp; `device-pack:`                           |  Optional  | Identifies the device pack used.
+&nbsp;&nbsp;&nbsp; [`output:`](#output)                     |  Optional  | Lists the possible compiler selection that this project is tested with.
+&nbsp;&nbsp;&nbsp; [`system-resources:`](#system-resources) |  Optional  | When specified, the [`cdefault.yml`](build-overview.md#cdefaultyml) file is used to setup compiler specific controls.
+
+### `output:`
+
+`output:`                                                   |            | Content
+:-----------------------------------------------------------|:-----------|:------------------------------------
+&nbsp;&nbsp;&nbsp; `device:`                                |  Optional  | Identifies the device.
+&nbsp;&nbsp;&nbsp; `device-pack:`                           |  Optional  | Identifies the device pack used.
+&nbsp;&nbsp;&nbsp; [`output:`](#output)                     |  Optional  | Lists the possible compiler selection that this project is tested with.
+&nbsp;&nbsp;&nbsp; [`system-resources:`](#system-resources) |  Optional  | When specified, the [`cdefault.yml`](build-overview.md#cdefaultyml) file is used to setup compiler specific controls.
+
+### `system-resources:`
+
+```yml
+cbuild-run:
+  device:
+  device-pack:      ? is the board-pack: not used?
+  output:
+    - file:
+      info:
+      type:
+      load-offset:
+      load:
+      pname:
+  system-resources:
+    memory:
+      - name:
+        access:
+        start:
+        size:
+        pname:
+        alias:
+        from-pack:
+  system-descriptions:
+    - file:
+      type:
+      pname:
+  debugger:
+    name:
+    clock:
+    dbgconf:
+    start-pname:
+    gdbserver:
+      - port:
+        pname:
+      - port:
+        pname:
+  debug-vars:
+    vars:
+  debug-sequences:
+    - name:
+      info:
+      pname:
+      blocks:
+        - info:
+          if:
+          while:
+          execute:
+          timeout:
+          atomic:
+          blocks:
+  programming:
+    - algorithm:
+      ram-start:
+      size:
+      ram-start:
+      ram-size:
+      pname:
+  debug-topology:
+    debugports:
+      - dpid:
+        accessports:
+          - apid:
+            address:
+            index:
+    processors:
+      - pname:
+        apid:
+    swj:
+    dormant:
+```

mkdocs.yml

@@ -4,21 +4,23 @@ extra:
 repo_url: https://github.com/Open-CMSIS-Pack/cmsis-toolbox
 edit_uri: ./edit/main/docs
 nav:
-    - Home: index.md
-    - Overview: overview.md
-    - Installation: installation.md
-    - Build Tools: build-tools.md
-    - CSolution Project Structure: build-overview.md
-    - CSolution Project Format: YML-Input-Format.md
-    - Create Applications: CreateApplications.md
-    - Reference Applications: ReferenceApplications.md
-    - Configure STM32 Devices with STM32CubeMX: CubeMX.md
-    - Configure NXP Devices with MCUXpresso Config Tools: MCUXpressoConfig.md
-    - Build Information Files: YML-CBuild-Format.md
-    - Theory of Operation: build-operation.md
-    - Pack Creation: pack-tools.md
-    - Troubleshooting: Troubleshooting.md
-    - Experimental Features: Experimental-Features.md
+  - Home: index.md
+  - Overview: overview.md
+  - Installation: installation.md
+  - Build Tools: build-tools.md
+  - CSolution Project Structure: build-overview.md
+  - CSolution Project Format: YML-Input-Format.md
+  - Create Applications: CreateApplications.md
+  - Reference Applications: ReferenceApplications.md
+  - Build Information Files: YML-CBuild-Format.md
+  - pyOCD Debugger: pyOCD-Debugger.md
+  - Theory of Operation: build-operation.md
+  - Pack Creation: pack-tools.md
+  - Troubleshooting: Troubleshooting.md
+  - Experimental Features: Experimental-Features.md
+  - Device Configuration Tools:
+    - MCUXpresso for NXP Devices: MCUXpressoConfig.md
+    - STM32CubeMX for STM32 Devices: CubeMX.md
 theme:
   name: readthedocs
 markdown_extensions: