Skip to content

Updates for settings for pyOCD Trace #604

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ReinhardKeil merged 7 commits into from
Jun 29, 2026
+86 −51
Merged

Updates for settings for pyOCD Trace #604

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
cdf9119
Remove `port-width` for pyOCD, be more specific about raw output
jreineckearm May 19, 2026
d5cf3ee
More clarifications, align pyOCD and J-Link settings.
jreineckearm May 20, 2026
303ee90
Feedback on `debug-vars-set` from Open-CMSIS-Pack Meeting (16/06/2026)
jreineckearm Jun 17, 2026
4a679d9
WiP: Replace `debug-vars-set` with `device-settings`, refine relation…
jreineckearm Jun 19, 2026
6f151e7
device-settings and dbgconf wording
jreineckearm Jun 19, 2026
841fffc
Merge branch 'main' into pyocd-trace-updates
jreineckearm Jun 26, 2026
68aa676
debug-sequences-conf and traceSetup
jreineckearm Jun 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions docs/JLink-Debugger.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
25 changes: 25 additions & 0 deletions docs/YML-CBuild-Format.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -1055,6 +1056,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 [`<debugvars>`](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
Expand Down Expand Up @@ -1262,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
:------------------------------------|--------------|:------------------------------------
&nbsp;&nbsp;&nbsp; `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.
Expand Down
32 changes: 16 additions & 16 deletions docs/YML-Input-Format.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2525,22 +2525,22 @@ This section lists the options that are specific to pyOCD that connects to [CMSI

#### `debugger:` for pyOCD

debugger: | | Description
:-------------------------------------------------------------------------|:-------------|:-----------------------------------------------
&nbsp;&nbsp;&nbsp; `name:` | **Required** | Identifies the debug adapter with `<adapter>@pyOCD`.
&nbsp;&nbsp;&nbsp; `clock:` | Optional | Debug clock speed in Hz.
&nbsp;&nbsp;&nbsp; `protocol:` | Optional | Debug protocol (jtag or swd).
&nbsp;&nbsp;&nbsp; `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.
&nbsp;&nbsp;&nbsp; `start-pname:` | Optional | Debugger connects at start to this processor.
&nbsp;&nbsp;&nbsp; [`gdbserver:`](pyOCD-Debugger.md#gdbserver) | Optional | Extended Option: GDB Server configuration.
&nbsp;&nbsp;&nbsp; [`telnet:`](pyOCD-Debugger.md#telnet) | Optional | Extended Option: Telnet service configuration.
&nbsp;&nbsp;&nbsp; [`connect:`](pyOCD-Debugger.md#connect) | Optional | Extended Option: Connect mode to hardware.
&nbsp;&nbsp;&nbsp; [`reset:`](pyOCD-Debugger.md#reset) | Optional | Extended Option: Reset type configuration for various cores.
&nbsp;&nbsp;&nbsp; [`load-setup:`](pyOCD-Debugger.md#load-setup) | Optional | Extended Option: Reset type and Halt configuration for Load command.
&nbsp;&nbsp;&nbsp; [`rtt:`](pyOCD-Debugger.md#rtt) | Optional | Extended Option: Segger RTT configuration.
&nbsp;&nbsp;&nbsp; [`systemview:`](pyOCD-Debugger.md#systemview) | Optional | Extended Option: Segger SystemView configuration.
&nbsp;&nbsp;&nbsp; [`trace:`](pyOCD-Debugger.md#trace) | Optional | Extended Option: Trace configuration.
&nbsp;&nbsp;&nbsp; [`debug-vars-set:`](pyOCD-Debugger.md#debug-vars-set) | Optional | Extended Option: Overrides for device-specific [`<debugvars>`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_debugvars) settings.
debugger: | | Description
:--------------------------------------------------------------------------|:-------------|:-----------------------------------------------
&nbsp;&nbsp;&nbsp; `name:` | **Required** | Identifies the debug adapter with `<adapter>@pyOCD`.
&nbsp;&nbsp;&nbsp; `clock:` | Optional | Debug clock speed in Hz.
&nbsp;&nbsp;&nbsp; `protocol:` | Optional | Debug protocol (jtag or swd).
&nbsp;&nbsp;&nbsp; `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.
&nbsp;&nbsp;&nbsp; `start-pname:` | Optional | Debugger connects at start to this processor.
&nbsp;&nbsp;&nbsp; [`gdbserver:`](pyOCD-Debugger.md#gdbserver) | Optional | Extended Option: GDB Server configuration.
&nbsp;&nbsp;&nbsp; [`telnet:`](pyOCD-Debugger.md#telnet) | Optional | Extended Option: Telnet service configuration.
&nbsp;&nbsp;&nbsp; [`connect:`](pyOCD-Debugger.md#connect) | Optional | Extended Option: Connect mode to hardware.
&nbsp;&nbsp;&nbsp; [`reset:`](pyOCD-Debugger.md#reset) | Optional | Extended Option: Reset type configuration for various cores.
&nbsp;&nbsp;&nbsp; [`load-setup:`](pyOCD-Debugger.md#load-setup) | Optional | Extended Option: Reset type and Halt configuration for Load command.
&nbsp;&nbsp;&nbsp; [`rtt:`](pyOCD-Debugger.md#rtt) | Optional | Extended Option: Segger RTT configuration.
&nbsp;&nbsp;&nbsp; [`systemview:`](pyOCD-Debugger.md#systemview) | Optional | Extended Option: Segger SystemView configuration.
&nbsp;&nbsp;&nbsp; [`trace:`](pyOCD-Debugger.md#trace) | Optional | Extended Option: Trace configuration.
&nbsp;&nbsp;&nbsp; [`device-settings:`](pyOCD-Debugger.md#device-settings) | Optional | Extended Option: Configuration through device-specific [`<debugvars>`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_debugvars) settings.

**Examples:**

Expand Down
2 changes: 1 addition & 1 deletion docs/build-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
69 changes: 39 additions & 30 deletions docs/pyOCD-Debugger.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -306,11 +306,8 @@ 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 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.
Refer to the [`<debugvars>`](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.
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:`.

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 `<solution-name>+<target-type>.trace`.
Expand All @@ -319,11 +316,10 @@ and uses the format `<solution-name>+<target-type>.trace`.
:---------------------------------------------------------|:-------------|:------------------------------------
&nbsp;&nbsp;&nbsp; `mode:` | **Required** | Trace: `off` (default), `server`, `file`.
&nbsp;&nbsp;&nbsp; `input-clock:` | **Required** | Trace input clock frequency in Hz.
&nbsp;&nbsp;&nbsp; `port-type:` | Optional | Set trace port transport mode. Currently only `SWO-UART` is accepted.
&nbsp;&nbsp;&nbsp; `port-width:` | Optional | Width of the trace port. Currently only the value '1' is accepted for `SWO-UART`.
&nbsp;&nbsp;&nbsp; `output-clock:` | Optional | Trace output clock for the selected port type. For `SWO-UART` mode this is the baudrate.
&nbsp;&nbsp;&nbsp; `server-port:` | Optional | Set TCP/IP port number of Trace server (default: 5555).
&nbsp;&nbsp;&nbsp; `file:` | Optional | Explicit path and name of the trace output file. Default: `<solution-name>+<target-type>.trace`.
&nbsp;&nbsp;&nbsp; `port-type:` | Optional | Set trace port transport mode. Currently only `swo-uart` is accepted (default: `swo-uart`).
&nbsp;&nbsp;&nbsp; `output-clock:` | Optional | Trace output clock for the selected port type. For `swo-uart` mode this is the baudrate.
&nbsp;&nbsp;&nbsp; `server-port:` | Optional | Set TCP/IP port number of trace server in `server` mode (default: 5555).
&nbsp;&nbsp;&nbsp; `file:` | Optional | Explicit path and name of the trace output file in `file` mode. Default: `<solution-name>+<target-type>.trace`.

#### Trace Clocks

Expand All @@ -339,27 +335,26 @@ 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
`__traceclockin` and `__traceclockout`.

### `debug-vars-set:`
### `device-settings:`

!!! Note
The `debug-vars-set:` feature 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 provides an alternative way to configure such settings
together with other pyOCD debugger settings in a single place.
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 [`<debugvars>`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_debugvars) section in a PDSC file.

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 `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.

!!! 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 [`<debugvars>`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_debugvars) section of the PDSC file.
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.

**Example:**
!!! 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 [`<debugvars>`](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:
Expand All @@ -373,14 +368,29 @@ 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
```

**Example:** MySetup.cbuild-run.yml generated from MySetup.csolution.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)
TraceD0_Pin: 0x00040003 # Pin PE3
TraceD1_Pin: 0x00040004 # Pin PE4
TraceD2_Pin: 0x00040005 # Pin PE5
TraceD3_Pin: 0x00040006 # Pin PE6
```

## Minimal Setup
Expand Down Expand Up @@ -776,8 +786,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
:---------------------------------------------------------|--------------|:------------------------------------
Expand Down
Loading