From cdf91196a0300cfdc54a23f2cc6efcba9ecb9ebe Mon Sep 17 00:00:00 2001 From: Jens Reinecke Date: Tue, 19 May 2026 17:44:55 +0200 Subject: [PATCH 1/6] Remove `port-width` for pyOCD, be more specific about raw output Signed-off-by: Jens Reinecke --- docs/pyOCD-Debugger.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/pyOCD-Debugger.md b/docs/pyOCD-Debugger.md index 261256e4..1af76012 100644 --- a/docs/pyOCD-Debugger.md +++ b/docs/pyOCD-Debugger.md @@ -306,7 +306,7 @@ debugger: !!! Note The `trace:` feature is under development. This section provides a preview. -CMSIS-DAP supports the SWO trace output of Cortex-M devices. +CMSIS-DAP supports the SWO trace output of Cortex-M devices. The raw trace data are made available from pyOCD through a TCP connection. The often device-specific trace capture capabilities are configured using the [`*.dbgconf`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/dbg_debug_sqns.html#dbg_sqns_dbgconf) file. Such device-specific settings can also be individually overridden under [`debug-vars-set:`](#debug-vars-set) node of the [`cbuild-run.yml` file](YML-CBuild-Format.md#run-and-debug-management). This allows to pass changed settings in a single configuration file. @@ -320,10 +320,9 @@ and uses the format `+.trace`.     `mode:` | **Required** | Trace: `off` (default), `server`, `file`.     `input-clock:` | **Required** | Trace input clock frequency in Hz.     `port-type:` | Optional | Set trace port transport mode. Currently only `SWO-UART` is accepted. -    `port-width:` | Optional | Width of the trace port. Currently only the value '1' is accepted for `SWO-UART`.     `output-clock:` | Optional | Trace output clock for the selected port type. For `SWO-UART` mode this is the baudrate. -    `server-port:` | Optional | Set TCP/IP port number of Trace server (default: 5555). -    `file:` | Optional | Explicit path and name of the trace output file. Default: `+.trace`. +    `server-port:` | Optional | Set TCP/IP port number of Trace server in `server` mode (default: 5555). +    `file:` | Optional | Explicit path and name of the trace output file in `file` mode. Default: `+.trace`. #### Trace Clocks From d5cf3eeb5e415eb069e48283a09f89c790744511 Mon Sep 17 00:00:00 2001 From: Jens Reinecke Date: Wed, 20 May 2026 13:12:32 +0200 Subject: [PATCH 2/6] More clarifications, align pyOCD and J-Link settings. Signed-off-by: Jens Reinecke --- docs/JLink-Debugger.md | 9 +++++---- docs/pyOCD-Debugger.md | 9 ++++----- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/JLink-Debugger.md b/docs/JLink-Debugger.md index f9f5e3ff..66c63fa6 100644 --- a/docs/JLink-Debugger.md +++ b/docs/JLink-Debugger.md @@ -97,14 +97,15 @@ debugger: !!! Note The `trace:` feature is under development. This section provides a preview. -J-Link supports SWO Trace. +J-Link supports the SWO trace output of Cortex-M devices. The raw trace data are made available from the J-Link GDB Server through a TCP connection. `trace:` | | Description :--------------------------------------------|:-------------|:------------------------------------ +    `mode:` | **Required** | Trace: `off` (default), `server`.     `input-clock:` | **Required** | Trace input clock frequency in Hz. -    `port-type:` | Optional | Set trace port transport mode. Currently only `SWO-UART` is accepted. -    `output-clock:` | Optional | Trace output clock for the selected port type. For `SWO-UART` mode this is the baudrate. -    `server-port:` | Optional | Set TCP/IP port number of Trace server (default: 5555). +    `port-type:` | Optional | Set trace port transport mode. Currently only `swo-uart` is accepted (default: `swo-uart`). +    `output-clock:` | Optional | Trace output clock for the selected port type. For `swo-uart` mode this is the baudrate. +    `server-port:` | Optional | Set TCP/IP port number of trace server in `server` mode (default: 5555). #### Trace Clocks diff --git a/docs/pyOCD-Debugger.md b/docs/pyOCD-Debugger.md index 1af76012..f498e8f6 100644 --- a/docs/pyOCD-Debugger.md +++ b/docs/pyOCD-Debugger.md @@ -306,7 +306,7 @@ debugger: !!! Note The `trace:` feature is under development. This section provides a preview. -CMSIS-DAP supports the SWO trace output of Cortex-M devices. The raw trace data are made available from pyOCD through a TCP connection. +CMSIS-DAP supports the SWO trace output of Cortex-M devices. The raw trace data are made available from pyOCD through a TCP connection or a binary file. The often device-specific trace capture capabilities are configured using the [`*.dbgconf`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/dbg_debug_sqns.html#dbg_sqns_dbgconf) file. Such device-specific settings can also be individually overridden under [`debug-vars-set:`](#debug-vars-set) node of the [`cbuild-run.yml` file](YML-CBuild-Format.md#run-and-debug-management). This allows to pass changed settings in a single configuration file. @@ -319,9 +319,9 @@ and uses the format `+.trace`. :---------------------------------------------------------|:-------------|:------------------------------------     `mode:` | **Required** | Trace: `off` (default), `server`, `file`.     `input-clock:` | **Required** | Trace input clock frequency in Hz. -    `port-type:` | Optional | Set trace port transport mode. Currently only `SWO-UART` is accepted. -    `output-clock:` | Optional | Trace output clock for the selected port type. For `SWO-UART` mode this is the baudrate. -    `server-port:` | Optional | Set TCP/IP port number of Trace server in `server` mode (default: 5555). +    `port-type:` | Optional | Set trace port transport mode. Currently only `swo-uart` is accepted (default: `swo-uart`). +    `output-clock:` | Optional | Trace output clock for the selected port type. For `swo-uart` mode this is the baudrate. +    `server-port:` | Optional | Set TCP/IP port number of trace server in `server` mode (default: 5555).     `file:` | Optional | Explicit path and name of the trace output file in `file` mode. Default: `+.trace`. #### Trace Clocks @@ -338,7 +338,6 @@ The above configurations are passed to debug sequence implementations through [p - If `output-clock` is provided or has a value other than `0`, then the value directly maps to variable `__traceclockout`. - If `output-clock` is not provided or has the value `0`, then the highest achievable output clock frequency supported by the debug unit is written to `__traceclockout`. - `port-type` maps to bits `0..2` of variable `__traceout`. -- `port-width` maps to bits `16..21` of variable `__traceout` if the selected `port-type` is a synchronous trace port. !!! Note The linked description of pre-defined debug access variables needs to be updated to include the proposed new variables From 303ee90d06e6162b3374fe19aaac3892ecd45b9f Mon Sep 17 00:00:00 2001 From: Jens Reinecke Date: Wed, 17 Jun 2026 07:57:37 +0200 Subject: [PATCH 3/6] Feedback on `debug-vars-set` from Open-CMSIS-Pack Meeting (16/06/2026) - Turn *.dbgconf like string into yaml key-value pairs - Pending discussion: rename `debug-vars-set` Signed-off-by: Jens Reinecke --- docs/pyOCD-Debugger.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/pyOCD-Debugger.md b/docs/pyOCD-Debugger.md index f498e8f6..696e402f 100644 --- a/docs/pyOCD-Debugger.md +++ b/docs/pyOCD-Debugger.md @@ -308,7 +308,7 @@ debugger: CMSIS-DAP supports the SWO trace output of Cortex-M devices. The raw trace data are made available from pyOCD through a TCP connection or a binary file. The often device-specific trace capture capabilities are configured using the [`*.dbgconf`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/dbg_debug_sqns.html#dbg_sqns_dbgconf) file. -Such device-specific settings can also be individually overridden under [`debug-vars-set:`](#debug-vars-set) node of the [`cbuild-run.yml` file](YML-CBuild-Format.md#run-and-debug-management). +Such device-specific settings can also be individually overridden under the [`debug-vars-set:`](#debug-vars-set) node under the [`debugger:`](#debugger) node. This allows to pass changed settings in a single configuration file. Refer to the [``](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_debugvars) section in the device PDSC file to learn about settings available for a device. @@ -346,12 +346,12 @@ The above configurations are passed to debug sequence implementations through [p ### `debug-vars-set:` !!! Note - The `debug-vars-set:` feature is under development. This section provides a preview. + The `debug-vars-set:` feature to change settings is under development. This section provides a preview. -Device-specific sequence settings like for debug and trace connections are usually configured through the [`*.dbgconf`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/dbg_debug_sqns.html#dbg_sqns_dbgconf) file. The `debug-vars-set:` node provides an alternative way to configure such settings -together with other pyOCD debugger settings in a single place. +Device-specific sequence settings like for debug and trace connections are usually configured through the [`*.dbgconf`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/dbg_debug_sqns.html#dbg_sqns_dbgconf) file. The `debug-vars-set:` node under `debugger:` provides an alternative way to configure such +settings together with other pyOCD debugger settings in a single place. -The value of the `debug-vars-set:` node is a string of the same format as used in the [`*.dbgconf`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/dbg_debug_sqns.html#dbg_sqns_dbgconf) file. +The `debug-vars-set:` node can contain a list of child nodes which are key-value pairs. The keys are the debug access variables as defined in the [``](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_debugvars) section of the PDSC file. !!! Note - Settings that are not listed under this node default to their assignment in a provided [`*.dbgconf`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/dbg_debug_sqns.html#dbg_sqns_dbgconf) file. @@ -371,14 +371,14 @@ The value of the `debug-vars-set:` node is a string of the same format as used i pname: CM7 - port: 3334 pname: CM4 - debug-vars-set: | - // DBGMCU configuration register (DBGMCU_CR) - DbgMCU_CR = 0x00000007; - // TPIU Pin Routing (TRACECLK fixed on Pin PE2) - TraceD0_Pin = 0x00040003; // Pin PE3 - TraceD1_Pin = 0x00040004; // Pin PE4 - TraceD2_Pin = 0x00040005; // Pin PE5 - TraceD3_Pin = 0x00040006; // Pin PE6 + debug-vars-set: + # DBGMCU configuration register (DBGMCU_CR) + DbgMCU_CR: 0x00000007 + # TPIU Pin Routing (TRACECLK fixed on Pin PE2) + TraceD0_Pin: 0x00040003 # Pin PE3 + TraceD1_Pin: 0x00040004 # Pin PE4 + TraceD2_Pin: 0x00040005 # Pin PE5 + TraceD3_Pin: 0x00040006 # Pin PE6 ``` ## Minimal Setup From 4a679d96ef26aeda94880b9ecb63953b3a6cd54b Mon Sep 17 00:00:00 2001 From: Jens Reinecke Date: Fri, 19 Jun 2026 13:16:02 +0200 Subject: [PATCH 4/6] WiP: Replace `debug-vars-set` with `device-settings`, refine relation to `dbgconf` Signed-off-by: Jens Reinecke --- docs/YML-CBuild-Format.md | 4 ++++ docs/YML-Input-Format.md | 32 ++++++++++++++--------------- docs/pyOCD-Debugger.md | 42 +++++++++++++++++++++++---------------- 3 files changed, 45 insertions(+), 33 deletions(-) diff --git a/docs/YML-CBuild-Format.md b/docs/YML-CBuild-Format.md index 3ab33560..94b00350 100644 --- a/docs/YML-CBuild-Format.md +++ b/docs/YML-CBuild-Format.md @@ -1065,6 +1065,10 @@ The information for the `debugger:` node may be configured using the [`debugger: If no input (`*.csolution.yml`, BSP or DFP) provides debugger option values, the CMSIS-Toolbox uses the values under `defaults:` from the file [`./etc/debug-adapters.yml`](build-operation.md#debug-adapter-integration). +!!! Note + Device-specific connection and trace settings are usually based on the device's [``](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_debugvars) element in the PDSC file. This element can also specify a `*.dbgconf` file to enable modifications of these settings in a solution. + Support for this editable file remains with the `dbgconf:` node. However, the preference for storing such settings in `*.cbuild-run.yml` is the [`device-settings:`](pyOCD-Debugger.md#device-settings) node for pyOCD, or similar nodes for other debug adapters. This shall ensure that all solution settings are stored in a single, self-contained configuration file that debuggers consume. + **Example:** ```yml diff --git a/docs/YML-Input-Format.md b/docs/YML-Input-Format.md index 38cf1317..045de652 100644 --- a/docs/YML-Input-Format.md +++ b/docs/YML-Input-Format.md @@ -2525,22 +2525,22 @@ This section lists the options that are specific to pyOCD that connects to [CMSI #### `debugger:` for pyOCD -debugger: | | Description -:-------------------------------------------------------------------------|:-------------|:----------------------------------------------- -    `name:` | **Required** | Identifies the debug adapter with `@pyOCD`. -    `clock:` | Optional | Debug clock speed in Hz. -    `protocol:` | Optional | Debug protocol (jtag or swd). -    `dbgconf:` | Optional | [Configuration file](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/dbg_debug_sqns.html#dbg_sqns_dbgconf) for device settings such as trace pins and option bytes. -    `start-pname:` | Optional | Debugger connects at start to this processor. -    [`gdbserver:`](pyOCD-Debugger.md#gdbserver) | Optional | Extended Option: GDB Server configuration. -    [`telnet:`](pyOCD-Debugger.md#telnet) | Optional | Extended Option: Telnet service configuration. -    [`connect:`](pyOCD-Debugger.md#connect) | Optional | Extended Option: Connect mode to hardware. -    [`reset:`](pyOCD-Debugger.md#reset) | Optional | Extended Option: Reset type configuration for various cores. -    [`load-setup:`](pyOCD-Debugger.md#load-setup) | Optional | Extended Option: Reset type and Halt configuration for Load command. -    [`rtt:`](pyOCD-Debugger.md#rtt) | Optional | Extended Option: Segger RTT configuration. -    [`systemview:`](pyOCD-Debugger.md#systemview) | Optional | Extended Option: Segger SystemView configuration. -    [`trace:`](pyOCD-Debugger.md#trace) | Optional | Extended Option: Trace configuration. -    [`debug-vars-set:`](pyOCD-Debugger.md#debug-vars-set) | Optional | Extended Option: Overrides for device-specific [``](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_debugvars) settings. +debugger: | | Description +:--------------------------------------------------------------------------|:-------------|:----------------------------------------------- +    `name:` | **Required** | Identifies the debug adapter with `@pyOCD`. +    `clock:` | Optional | Debug clock speed in Hz. +    `protocol:` | Optional | Debug protocol (jtag or swd). +    `dbgconf:` | Optional | [Configuration file](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/dbg_debug_sqns.html#dbg_sqns_dbgconf) for device settings such as trace pins and option bytes. +    `start-pname:` | Optional | Debugger connects at start to this processor. +    [`gdbserver:`](pyOCD-Debugger.md#gdbserver) | Optional | Extended Option: GDB Server configuration. +    [`telnet:`](pyOCD-Debugger.md#telnet) | Optional | Extended Option: Telnet service configuration. +    [`connect:`](pyOCD-Debugger.md#connect) | Optional | Extended Option: Connect mode to hardware. +    [`reset:`](pyOCD-Debugger.md#reset) | Optional | Extended Option: Reset type configuration for various cores. +    [`load-setup:`](pyOCD-Debugger.md#load-setup) | Optional | Extended Option: Reset type and Halt configuration for Load command. +    [`rtt:`](pyOCD-Debugger.md#rtt) | Optional | Extended Option: Segger RTT configuration. +    [`systemview:`](pyOCD-Debugger.md#systemview) | Optional | Extended Option: Segger SystemView configuration. +    [`trace:`](pyOCD-Debugger.md#trace) | Optional | Extended Option: Trace configuration. +    [`device-settings:`](pyOCD-Debugger.md#device-settings) | Optional | Extended Option: Configuration through device-specific [``](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_debugvars) settings. **Examples:** diff --git a/docs/pyOCD-Debugger.md b/docs/pyOCD-Debugger.md index 696e402f..422d049b 100644 --- a/docs/pyOCD-Debugger.md +++ b/docs/pyOCD-Debugger.md @@ -307,10 +307,8 @@ debugger: The `trace:` feature is under development. This section provides a preview. CMSIS-DAP supports the SWO trace output of Cortex-M devices. The raw trace data are made available from pyOCD through a TCP connection or a binary file. -The often device-specific trace capture capabilities are configured using the [`*.dbgconf`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/dbg_debug_sqns.html#dbg_sqns_dbgconf) file. -Such device-specific settings can also be individually overridden under the [`debug-vars-set:`](#debug-vars-set) node under the [`debugger:`](#debugger) node. -This allows to pass changed settings in a single configuration file. -Refer to the [``](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_debugvars) section in the device PDSC file to learn about settings available for a device. +Device-specific trace capture capabilities are configured using the [`device-settings`](#device-settings) node under `debugger:`. Such settings are based +on the device's [``](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_debugvars) section in the PDSC file. The default trace output file and location is derived from the [`cbuild-run.yml` file](YML-CBuild-Format.md#run-and-debug-management) and uses the format `+.trace`. @@ -343,21 +341,17 @@ The above configurations are passed to debug sequence implementations through [p The linked description of pre-defined debug access variables needs to be updated to include the proposed new variables `__traceclockin` and `__traceclockout`. -### `debug-vars-set:` +### `device-settings:` !!! Note - The `debug-vars-set:` feature to change settings is under development. This section provides a preview. + The `device-settings:` feature is under development. This section provides a preview. -Device-specific sequence settings like for debug and trace connections are usually configured through the [`*.dbgconf`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/dbg_debug_sqns.html#dbg_sqns_dbgconf) file. The `debug-vars-set:` node under `debugger:` provides an alternative way to configure such -settings together with other pyOCD debugger settings in a single place. - -The `debug-vars-set:` node can contain a list of child nodes which are key-value pairs. The keys are the debug access variables as defined in the [``](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_debugvars) section of the PDSC file. +Device-specific debug and trace connections can be configured via the `device-settings` node under `debugger:`. It contains a list of child nodes with editable key-value pairs which are based on debug access variable defined in the device's [``](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_debugvars) section of the PDSC file. Alternatively, the path of a [`*.dbgconf`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/dbg_debug_sqns.html#dbg_sqns_dbgconf) file can be used in the `*.csolution.yml` file which gets expanded to key-value pairs while generating the `*.cbuild-run.yml` file. !!! Note - - Settings that are not listed under this node default to their assignment in a provided [`*.dbgconf`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/dbg_debug_sqns.html#dbg_sqns_dbgconf) file. - - If no [`*.dbgconf`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/dbg_debug_sqns.html#dbg_sqns_dbgconf) file is provided, or if a setting isn't assigned in this file, then it defaults to the value assigned in the device [``](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_debugvars) section of the PDSC file. - -**Example:** + - Settings that are not assigned under the `device-settings:` node or the referenced `*.dbgconf` file default to the values assigned in the device's [``](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_debugvars) section of the PDSC file. + +**Example:** MySetup.csolution.yml ```yml debugger: @@ -371,7 +365,22 @@ The `debug-vars-set:` node can contain a list of child nodes which are key-value pname: CM7 - port: 3334 pname: CM4 - debug-vars-set: +``` + +**Example:** MySetup.cbuild-run.yml + +```yml + debugger: + name: ST-Link@pyOCD + protocol: swd + clock: 10000000 + start-pname: CM7 + gdbserver: + - port: 3333 + pname: CM7 + - port: 3334 + pname: CM4 + device-settings: # DBGMCU configuration register (DBGMCU_CR) DbgMCU_CR: 0x00000007 # TPIU Pin Routing (TRACECLK fixed on Pin PE2) @@ -774,8 +783,7 @@ and pyOCD Debugger [Extended Options](#extended-options). ### `debug-vars:` -Contains default values for debug sequence variables. These values can be overridden by explicit settings in a -`*.dbgconf` file provided in the [`debugger:`](#debugger) node. +Contains the definition and default values for debug sequence variables. The default values can be overridden by corresponding key-value pairs under the `device-settings:` node under [`debugger:`](#debugger). `debug-vars:` | | Content :---------------------------------------------------------|--------------|:------------------------------------ From 6f151e71bdaefa9fd0ae9a49de7a0b010c396d30 Mon Sep 17 00:00:00 2001 From: Jens Reinecke Date: Fri, 19 Jun 2026 15:18:44 +0200 Subject: [PATCH 5/6] device-settings and dbgconf wording Signed-off-by: Jens Reinecke --- docs/YML-CBuild-Format.md | 8 ++++---- docs/pyOCD-Debugger.md | 11 +++++++---- 2 files changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/YML-CBuild-Format.md b/docs/YML-CBuild-Format.md index 94b00350..9fc7ae41 100644 --- a/docs/YML-CBuild-Format.md +++ b/docs/YML-CBuild-Format.md @@ -1055,6 +1055,10 @@ This node contains connection information for a debugger with initial settings c - `protocol:` and `clock:` are required by pyOCD but optional for other debug adapters. The file [`./etc/debug-adapters.yml`](build-operation.md#debug-adapter-integration) allows to specify default values for required options. - `start-pname:` is mandatory for multi-processor targets. If `start-pname:` is not configured using the [`debugger:`](YML-Input-Format.md#debugger) node in the `*.csolution.yml` file, the `pname:` of the first `*.cproject.yml` file is used. +!!! Note + Device-specific connection and trace settings are usually based on the device [``](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_debugvars) element in the PDSC file. This element can also specify a `*.dbgconf` file to enable modifications of these settings in a solution. + Support for this file remains via the `dbgconf:` node. However, it is preferred in `*.cbuild-run.yml` to store such settings in the [`device-settings:`](pyOCD-Debugger.md#device-settings) node for pyOCD, or in similar nodes for other debug adapters. This ensures that all solution settings are stored in a single, self-contained configuration file for a debug adapter. + The information for the `debugger:` node may be configured using the [`debugger:`](YML-Input-Format.md#debugger) node in the `*.csolution.yml` file. If not present the values from BSP are used; if not present DFP values. The values in the `*.csolution.yml` file overwrites values from BSP or DFP as shown in the table below. `*.cbuild-run.yml` | `*.csolution.yml` | BSP | DFP @@ -1065,10 +1069,6 @@ The information for the `debugger:` node may be configured using the [`debugger: If no input (`*.csolution.yml`, BSP or DFP) provides debugger option values, the CMSIS-Toolbox uses the values under `defaults:` from the file [`./etc/debug-adapters.yml`](build-operation.md#debug-adapter-integration). -!!! Note - Device-specific connection and trace settings are usually based on the device's [``](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_debugvars) element in the PDSC file. This element can also specify a `*.dbgconf` file to enable modifications of these settings in a solution. - Support for this editable file remains with the `dbgconf:` node. However, the preference for storing such settings in `*.cbuild-run.yml` is the [`device-settings:`](pyOCD-Debugger.md#device-settings) node for pyOCD, or similar nodes for other debug adapters. This shall ensure that all solution settings are stored in a single, self-contained configuration file that debuggers consume. - **Example:** ```yml diff --git a/docs/pyOCD-Debugger.md b/docs/pyOCD-Debugger.md index 422d049b..601ced50 100644 --- a/docs/pyOCD-Debugger.md +++ b/docs/pyOCD-Debugger.md @@ -307,8 +307,7 @@ debugger: The `trace:` feature is under development. This section provides a preview. CMSIS-DAP supports the SWO trace output of Cortex-M devices. The raw trace data are made available from pyOCD through a TCP connection or a binary file. -Device-specific trace capture capabilities are configured using the [`device-settings`](#device-settings) node under `debugger:`. Such settings are based -on the device's [``](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_debugvars) section in the PDSC file. +Device-specific trace capture capabilities are configured using the [`device-settings`](#device-settings) node under `debugger:`. The default trace output file and location is derived from the [`cbuild-run.yml` file](YML-CBuild-Format.md#run-and-debug-management) and uses the format `+.trace`. @@ -346,7 +345,11 @@ The above configurations are passed to debug sequence implementations through [p !!! Note The `device-settings:` feature is under development. This section provides a preview. -Device-specific debug and trace connections can be configured via the `device-settings` node under `debugger:`. It contains a list of child nodes with editable key-value pairs which are based on debug access variable defined in the device's [``](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_debugvars) section of the PDSC file. Alternatively, the path of a [`*.dbgconf`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/dbg_debug_sqns.html#dbg_sqns_dbgconf) file can be used in the `*.csolution.yml` file which gets expanded to key-value pairs while generating the `*.cbuild-run.yml` file. +Debug and trace connection sequences are often device-specific and can be configured. This node contains a list of editable key-value pairs which are based on debug access variables defined in the device [``](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_debugvars) section in a PDSC file. + +The `device-settings:` node has higher precedence than the `dbgconf:` node, i.e. if `device-settings:` is present then an also specified [`*.dbgconf`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/dbg_debug_sqns.html#dbg_sqns_dbgconf) file is ignored. + +If a `*.csolution.yml` specifies a `dbgconf:` node instead of a `device-settings:` node, then the referenced `*.dbgconf` file gets parsed and its contents is converted into a `device-settings:` node in the `*.cbuild-run.yml` file. !!! Note - Settings that are not assigned under the `device-settings:` node or the referenced `*.dbgconf` file default to the values assigned in the device's [``](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_debugvars) section of the PDSC file. @@ -367,7 +370,7 @@ Device-specific debug and trace connections can be configured via the `device-se pname: CM4 ``` -**Example:** MySetup.cbuild-run.yml +**Example:** MySetup.cbuild-run.yml generated from MySetup.csolution.yml ```yml debugger: From 68aa676a444d6f7b6c26403672dc663ea52c379c Mon Sep 17 00:00:00 2001 From: Jens Reinecke Date: Fri, 26 Jun 2026 16:11:13 +0200 Subject: [PATCH 6/6] debug-sequences-conf and traceSetup Signed-off-by: Jens Reinecke --- docs/YML-CBuild-Format.md | 21 +++++++++++++++++++++ docs/build-overview.md | 2 +- 2 files changed, 22 insertions(+), 1 deletion(-) diff --git a/docs/YML-CBuild-Format.md b/docs/YML-CBuild-Format.md index 9fc7ae41..9606512e 100644 --- a/docs/YML-CBuild-Format.md +++ b/docs/YML-CBuild-Format.md @@ -879,6 +879,7 @@ The following describes the overall structure of the `*.cbuild-run.yml` file. W     [`system-descriptions:`](#system-descriptions) | Optional | List of description files for peripherals and software components.     [`debugger:`](#debugger) |**Required**| Configuration information for the debug connection.     [`debug-sequences:`](#debug-sequences) | Optional | Tool actions for debugging, tracing, or programming. +    [`debug-sequences-conf:`](#debug-sequences-conf) | Optional | Configuration information for how to use debug sequences.     [`programming:`](#programming) | Optional | Algorithms for flash download.     [`flash-info:`](#flash-info) | Optional | Memory where the debugger uses JTAG/SWD sequences for programming.     [`debug-topology:`](#debug-topology) | Optional | Properties of the system hardware for debug functionality. @@ -1266,6 +1267,26 @@ debug-sequences: ReadDP(0x0); ``` +#### `debug-sequences-conf:` + +This node contains configuration information for how [debug sequences](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_sequence) are expected to be used by a debugger. + +`debug-sequences-conf:` | | Content +:------------------------------------|--------------|:------------------------------------ +    `traceSetup:` | Optional | Configure how to use trace sequences. Can be `full` or `legacy` (default: `legacy`). + +Value `full` for `traceSetup:` informs the debugger that all trace component setup is done by the trace sequences. Opposed to that, the `legacy` mode expected debuggers to program the CoreSight trace components as per built-in support knowledge. Going forward, `full` is the preferred mode to allow new CoreSight component support without debug tool updates. + +```yml +debug-sequences: + - name: TraceStart + : + +debug-sequences-conf: + traceSetup: full +``` + + #### `programming:` The `programming:` node collects the [flash algorithms](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/flashAlgorithm.html) of device memory (specified in DFP) and board memory (specified in BSP), and [`memory:`](YML-Input-Format.md#memory) specified the `*.csolution.yml` file. diff --git a/docs/build-overview.md b/docs/build-overview.md index 6ebb4c61..5bdcb8f0 100644 --- a/docs/build-overview.md +++ b/docs/build-overview.md @@ -1094,7 +1094,7 @@ With the VS Code extension [CMSIS Solution](https://marketplace.visualstudio.com ### Device Configuration -Several DFP contain `*.dbgconf` files that configure device-specific debug and trace parameters. The CMSIS-Toolbox provides this configuration information in the `*.build-run.yml` file for [debuggers with Debug Access Sequence support](YML-CBuild-Format.md#run-and-debug-management). +Several DFP contain `*.dbgconf` files that configure device-specific debug and trace parameters. The CMSIS-Toolbox provides this configuration information in the `*.cbuild-run.yml` file for [debuggers with Debug Access Sequence support](YML-CBuild-Format.md#run-and-debug-management). The `.cmsis` directory in the *csolution project* directory contains for each target a default `*.dbgconf` configuration file. For example: `.\.cmsis\MyApplication+MyBoard`. This file can be configured to reflect user settings.