From 28a19caced3c4baa5a61533a59faf5f8f5a5aa05 Mon Sep 17 00:00:00 2001 From: Jens Reinecke Date: Tue, 30 Jun 2026 08:43:32 +0200 Subject: [PATCH 1/4] List of children for trace: node Signed-off-by: Jens Reinecke --- docs/JLink-Debugger.md | 27 ++++++++++++++++++------- docs/build-operation.md | 10 +++++----- docs/pyOCD-Debugger.md | 44 +++++++++++++++++++++++++++++------------ 3 files changed, 56 insertions(+), 25 deletions(-) diff --git a/docs/JLink-Debugger.md b/docs/JLink-Debugger.md index 66c63fa6..1a6770d1 100644 --- a/docs/JLink-Debugger.md +++ b/docs/JLink-Debugger.md @@ -99,13 +99,26 @@ debugger: 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 (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). +The `trace:` node has one child type per supported trace transport mode which offers mode-specific options. Currently, the [`swo-uart`](#swo-uart) type is supported. + +!!! Note + The `trace:` node is implemented as a list. However, currently only one node is supported. Additional nodes are ignored. + +```yml +trace: + - swo-uart: TraceConfigName # Trace mode is SWO UART + input-clock: 120000000 # Trace clock = 120 MHz +``` + +#### `swo-uart` + +`swo-uart:` | | Description +:---------------------------------------------------------|:-------------|:------------------------------------ +    `swo-uart:` | **Required** | Transport mode is SWO UART. The node allows an optional name (default: `null`). +    `mode:` | Optional | Trace: `off` (default), `server`. +    `input-clock:` | **Required** | Trace input clock frequency in Hz. +    `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/build-operation.md b/docs/build-operation.md index f473b68f..2979c525 100644 --- a/docs/build-operation.md +++ b/docs/build-operation.md @@ -446,14 +446,14 @@ solution: : target-set: - set: - debugger:0 + debugger: name: CMSIS-DAP@pyOCD protocol: swd - clock: 10000000 # SWD clock = 10MHz + clock: 10000000 # SWD clock = 10MHz trace: - mode: UART - clock: 120000000 # Trace clock = 120 MHz - telnet: # Enable telnet with defaults + - swo-uart: # Trace mode is SWO UART + input-clock: 120000000 # Trace clock = 120 MHz + telnet: # Enable telnet with defaults ``` **Example `debug-adapters.yml`** diff --git a/docs/pyOCD-Debugger.md b/docs/pyOCD-Debugger.md index 601ced50..4d24ee99 100644 --- a/docs/pyOCD-Debugger.md +++ b/docs/pyOCD-Debugger.md @@ -310,16 +310,38 @@ CMSIS-DAP supports the SWO trace output of Cortex-M devices. The raw trace data 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`. +and uses the format `+[+].trace`. -`trace:` | | Description +The `trace:` node has one child type per supported trace transport mode which offers mode-specific options. Currently, the [`swo-uart`](#swo-uart) type and the [`etb`](#etb) type are supported. + +!!! Note + The `trace:` node is implemented as a list. However, currently only one node is supported. Additional nodes are ignored. + +```yml +trace: + - swo-uart: TraceConfigName # Trace mode is SWO UART + input-clock: 120000000 # Trace clock = 120 MHz +``` + +#### `swo-uart` + +`swo-uart:` | | Description :---------------------------------------------------------|:-------------|:------------------------------------ -    `mode:` | **Required** | Trace: `off` (default), `server`, `file`. +    `swo-uart:` | **Required** | Transport mode is SWO UART. The node allows an optional name (default: `null`). +    `mode:` | Optional | 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 (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`. +    `file:` | Optional | Explicit path and name of the trace output file in `file` mode. Default: `+[+].trace`. + +#### `etb` + +`etb:` | | Description +:---------------------------------------------------------|:-------------|:------------------------------------ +    `etb:` | **Required** | Transport mode is Embedded Trace Buffer. The node allows an optional name (default: `null`). +    `mode:` | Optional | Trace: `off` (default), `server`, `file`. +    `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 @@ -331,14 +353,10 @@ For more complex multi-core systems, the clock is normally derived from the syst The above configurations are passed to debug sequence implementations through [pre-defined debug access variables](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html#DebugVars). The following mapping is expected: -- `input-clock` directly maps to variable `__traceclockin`. -- 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`. - -!!! Note - The linked description of pre-defined debug access variables needs to be updated to include the proposed new variables - `__traceclockin` and `__traceclockout`. +- `input-clock` directly maps to variable [`__traceclockin`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html#__traceclockin). +- If `output-clock` is provided or has a value other than `0`, then the value directly maps to variable [`__traceclockout`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html#__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`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html#__traceclockout). +- The selected transport mode (currently [`swo-uart`](#swo-uart) or [`etb`](#etb)) maps to bits `0..2` of variable [`__traceout`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html#__traceout). ### `device-settings:` From 0e7c49bd8185dbc8e9f8b5a3654dfd1cd26621ba Mon Sep 17 00:00:00 2001 From: Jens Reinecke Date: Tue, 30 Jun 2026 12:22:30 +0200 Subject: [PATCH 2/4] Review Feedback - Confusing duplication of `swo-uart`/`etb` - Leftover use of trace mode in descriptions - Bug in explanation Signed-off-by: Jens Reinecke --- docs/JLink-Debugger.md | 14 +++++++------- docs/pyOCD-Debugger.md | 30 +++++++++++++++--------------- 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/JLink-Debugger.md b/docs/JLink-Debugger.md index 1a6770d1..227f1cc9 100644 --- a/docs/JLink-Debugger.md +++ b/docs/JLink-Debugger.md @@ -112,13 +112,13 @@ trace: #### `swo-uart` -`swo-uart:` | | Description -:---------------------------------------------------------|:-------------|:------------------------------------ -    `swo-uart:` | **Required** | Transport mode is SWO UART. The node allows an optional name (default: `null`). -    `mode:` | Optional | Trace: `off` (default), `server`. -    `input-clock:` | **Required** | Trace input clock frequency in Hz. -    `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:` | | Description +:-----------------------------------------|:-------------|:------------------------------------ +`- swo-uart:` | **Required** | Transport mode is SWO UART. The node allows an optional name (default: `null`). +    `mode:` | Optional | Trace: `off` (default), `server`. +    `input-clock:` | **Required** | Trace input clock frequency in Hz. +    `output-clock:` | Optional | Trace output clock frequency in Hz, i.e. the baudrate, for the SWO output. +    `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 4d24ee99..31435f37 100644 --- a/docs/pyOCD-Debugger.md +++ b/docs/pyOCD-Debugger.md @@ -325,23 +325,23 @@ trace: #### `swo-uart` -`swo-uart:` | | Description -:---------------------------------------------------------|:-------------|:------------------------------------ -    `swo-uart:` | **Required** | Transport mode is SWO UART. The node allows an optional name (default: `null`). -    `mode:` | Optional | Trace: `off` (default), `server`, `file`. -    `input-clock:` | **Required** | Trace input clock frequency in Hz. -    `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:` | | Description +:----------------------------------------|:-------------|:------------------------------------ +`- swo-uart:` | **Required** | Transport mode is SWO UART. The node allows an optional name (default: `null`). +    `mode:` | Optional | Trace: `off` (default), `server`, `file`. +    `input-clock:` | **Required** | Trace input clock frequency in Hz. +    `output-clock:` | Optional | Trace output clock frequency, i.e. the baudrate, for the SWO output. +    `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`. #### `etb` -`etb:` | | Description -:---------------------------------------------------------|:-------------|:------------------------------------ -    `etb:` | **Required** | Transport mode is Embedded Trace Buffer. The node allows an optional name (default: `null`). -    `mode:` | Optional | Trace: `off` (default), `server`, `file`. -    `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:` | | Description +:----------------------------------------|:-------------|:------------------------------------ +`- etb:` | **Required** | Transport mode is Embedded Trace Buffer. The node allows an optional name (default: `null`). +    `mode:` | Optional | Trace: `off` (default), `server`, `file`. +    `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 @@ -354,7 +354,7 @@ For more complex multi-core systems, the clock is normally derived from the syst The above configurations are passed to debug sequence implementations through [pre-defined debug access variables](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html#DebugVars). The following mapping is expected: - `input-clock` directly maps to variable [`__traceclockin`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html#__traceclockin). -- If `output-clock` is provided or has a value other than `0`, then the value directly maps to variable [`__traceclockout`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html#__traceclockout). +- If `output-clock` is provided and has a value other than `0`, then the value directly maps to variable [`__traceclockout`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html#__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`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html#__traceclockout). - The selected transport mode (currently [`swo-uart`](#swo-uart) or [`etb`](#etb)) maps to bits `0..2` of variable [`__traceout`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html#__traceout). From a82942cbc357aa28e522064bbbbe6a8c8faff317 Mon Sep 17 00:00:00 2001 From: Jens Reinecke Date: Tue, 30 Jun 2026 13:03:05 +0200 Subject: [PATCH 3/4] Default trace config name if not given Signed-off-by: Jens Reinecke --- docs/pyOCD-Debugger.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/pyOCD-Debugger.md b/docs/pyOCD-Debugger.md index 31435f37..feb5d896 100644 --- a/docs/pyOCD-Debugger.md +++ b/docs/pyOCD-Debugger.md @@ -309,10 +309,13 @@ 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. Device-specific trace capture capabilities are configured using the [`device-settings`](#device-settings) node under `debugger:`. +The `trace:` node has one child type per supported trace transport mode which offers mode-specific options. Currently, the [`swo-uart`](#swo-uart) type and the [`etb`](#etb) type are supported. + 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`. +and uses the format `++.trace`. +The `` part is derived from the optional name of the configuration stored in the type node, i.e. +[`- swo-uart:`](#swo-uart) and the [`- etb:`](#etb). If no name is provided, the type itself is used. -The `trace:` node has one child type per supported trace transport mode which offers mode-specific options. Currently, the [`swo-uart`](#swo-uart) type and the [`etb`](#etb) type are supported. !!! Note The `trace:` node is implemented as a list. However, currently only one node is supported. Additional nodes are ignored. @@ -332,7 +335,7 @@ trace:     `input-clock:` | **Required** | Trace input clock frequency in Hz.     `output-clock:` | Optional | Trace output clock frequency, i.e. the baudrate, for the SWO output.     `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`. +    `file:` | Optional | Explicit path and name of the trace output file in `file` mode. Default: `++.trace`. #### `etb` @@ -341,7 +344,7 @@ trace: `- etb:` | **Required** | Transport mode is Embedded Trace Buffer. The node allows an optional name (default: `null`).     `mode:` | Optional | Trace: `off` (default), `server`, `file`.     `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`. +    `file:` | Optional | Explicit path and name of the trace output file in `file` mode. Default: `++.trace`. #### Trace Clocks From d66311e3048044ecaddf25a60b515d42a991e32e Mon Sep 17 00:00:00 2001 From: Jens Reinecke Date: Tue, 30 Jun 2026 15:04:43 +0200 Subject: [PATCH 4/4] ETB -> trace-buffer Signed-off-by: Jens Reinecke --- docs/pyOCD-Debugger.md | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/docs/pyOCD-Debugger.md b/docs/pyOCD-Debugger.md index feb5d896..15aa32dd 100644 --- a/docs/pyOCD-Debugger.md +++ b/docs/pyOCD-Debugger.md @@ -309,12 +309,12 @@ 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. Device-specific trace capture capabilities are configured using the [`device-settings`](#device-settings) node under `debugger:`. -The `trace:` node has one child type per supported trace transport mode which offers mode-specific options. Currently, the [`swo-uart`](#swo-uart) type and the [`etb`](#etb) type are supported. +The `trace:` node has one child type per supported trace transport mode which offers mode-specific options. Currently, the [`swo-uart`](#swo-uart) type and the [`trace-buffer`](#trace-buffer) type are supported. 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`. The `` part is derived from the optional name of the configuration stored in the type node, i.e. -[`- swo-uart:`](#swo-uart) and the [`- etb:`](#etb). If no name is provided, the type itself is used. +[`- swo-uart:`](#swo-uart) and the [`- trace-buffer:`](#trace-buffer). If no name is provided, the type itself is used. !!! Note @@ -328,20 +328,29 @@ trace: #### `swo-uart` +Configuration for the SWO trace output in UART mode. + `trace:` | | Description :----------------------------------------|:-------------|:------------------------------------ `- swo-uart:` | **Required** | Transport mode is SWO UART. The node allows an optional name (default: `null`).     `mode:` | Optional | Trace: `off` (default), `server`, `file`. -    `input-clock:` | **Required** | Trace input clock frequency in Hz. -    `output-clock:` | Optional | Trace output clock frequency, i.e. the baudrate, for the SWO output.     `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`. +    `input-clock:` | **Required** | Trace input clock frequency in Hz. +    `output-clock:` | Optional | Trace output clock frequency, i.e. the baudrate, for the SWO output. + +#### `trace-buffer` + +Configuration for the target device trace buffer. This type covers on-chip trace buffer variants like the Embedded Trace Buffer (ETB), +the Embedded Trace FIFO (ETF, in circular buffer mode), the Embedded Trace Router, and the Micro Trace Buffer (MTB). -#### `etb` +Some of the listed on-chip trace buffer solutions provide sophisticated options to configure exact memory placement and bus access setup. +Such settings are often use-case and device specific. They are usually exposed through the device [``](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_family_pg.html#element_debugvars), +and configured through the `device-settings:` or the `*.dbgconf` file. `trace:` | | Description :----------------------------------------|:-------------|:------------------------------------ -`- etb:` | **Required** | Transport mode is Embedded Trace Buffer. The node allows an optional name (default: `null`). +`- trace-buffer:` | **Required** | Transport mode is (on-chip) trace buffer. The node allows an optional name (default: `null`).     `mode:` | Optional | Trace: `off` (default), `server`, `file`.     `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`. @@ -359,7 +368,7 @@ The above configurations are passed to debug sequence implementations through [p - `input-clock` directly maps to variable [`__traceclockin`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html#__traceclockin). - If `output-clock` is provided and has a value other than `0`, then the value directly maps to variable [`__traceclockout`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html#__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`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html#__traceclockout). -- The selected transport mode (currently [`swo-uart`](#swo-uart) or [`etb`](#etb)) maps to bits `0..2` of variable [`__traceout`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html#__traceout). +- The selected transport mode (currently [`swo-uart`](#swo-uart) or [`trace-buffer`](#trace-buffer)) maps to bits `0..2` of variable [`__traceout`](https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/debug_description.html#__traceout). ### `device-settings:`