Skip to content

List of children for trace: node #637

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
jreineckearm merged 5 commits into from
Jun 30, 2026
+72 −29
Merged

List of children for trace: node #637

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
28a19ca
List of children for trace: node
jreineckearm Jun 30, 2026
0e7c49b
Review Feedback
jreineckearm Jun 30, 2026
a82942c
Default trace config name if not given
jreineckearm Jun 30, 2026
d66311e
ETB -> trace-buffer
jreineckearm Jun 30, 2026
221c611
Merge branch 'main' into trace-array
jreineckearm Jun 30, 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
27 changes: 20 additions & 7 deletions docs/JLink-Debugger.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`

`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

Expand Down
10 changes: 5 additions & 5 deletions docs/build-operation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`**
Expand Down
64 changes: 47 additions & 17 deletions docs/pyOCD-Debugger.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -309,17 +309,51 @@ 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 [`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 `<solution-name>+<target-type>.trace`.
and uses the format `<solution-name>+<target-type>+<trace-config-name>.trace`.
The `<trace-config-name>` part is derived from the optional name of the configuration stored in the type node, i.e.
[`- swo-uart:`](#swo-uart) and the [`- trace-buffer:`](#trace-buffer). If no name is provided, the type itself is used.

`trace:` | | Description
:---------------------------------------------------------|:-------------|:------------------------------------
&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 (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`.

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

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`).
&nbsp;&nbsp;&nbsp; `mode:` | Optional | Trace: `off` (default), `server`, `file`.
&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-config-name>.trace`.
&nbsp;&nbsp;&nbsp; `input-clock:` | **Required** | Trace input clock frequency in Hz.
&nbsp;&nbsp;&nbsp; `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).

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 [`<debugvars>`](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
:----------------------------------------|:-------------|:------------------------------------
`- trace-buffer:` | **Required** | Transport mode is (on-chip) trace buffer. The node allows an optional name (default: `null`).
&nbsp;&nbsp;&nbsp; `mode:` | Optional | Trace: `off` (default), `server`, `file`.
&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-config-name>.trace`.

#### Trace Clocks

Expand All @@ -331,14 +365,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 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 [`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:`

Expand Down
Loading