diff --git a/docs/JLink-Debugger.md b/docs/JLink-Debugger.md index 66c63fa6..227f1cc9 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` + +`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/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..15aa32dd 100644 --- a/docs/pyOCD-Debugger.md +++ b/docs/pyOCD-Debugger.md @@ -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 `+.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 [`- trace-buffer:`](#trace-buffer). If no name is provided, the type itself is used. -`trace:` | | Description -:---------------------------------------------------------|:-------------|:------------------------------------ -    `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 (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`. + +!!! 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`). +    `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`. +    `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). + +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 +:----------------------------------------|:-------------|:------------------------------------ +`- 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`. #### Trace Clocks @@ -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:`