From 31337873353f06004697c321ded5ffaa5cea64cb Mon Sep 17 00:00:00 2001 From: Reinhard Keil Date: Tue, 7 Jul 2026 15:09:12 +0200 Subject: [PATCH] Trace reworked after feedback --- docs/Experimental-Features.md | 492 +++++++++++++++++++++++++--------- 1 file changed, 372 insertions(+), 120 deletions(-) diff --git a/docs/Experimental-Features.md b/docs/Experimental-Features.md index 50902427..41f8cc12 100644 --- a/docs/Experimental-Features.md +++ b/docs/Experimental-Features.md @@ -141,173 +141,425 @@ Example: the [cmsis-to-zephyr-concept `ml_inference` example](https://github.com ## Trace -Trace captures target execution data via SWO (or trace port), ETB, MTB, and Event Recorder. +Trace captures target execution data through SWO or trace port and from sources such as ETB, MTB, and Event Recorder. Trace is obtained with these steps: -> Note -> -> - `` is the base name of the `*.ctrace.yml` file. This name is derived from the selected target-set, i.e. `SDS+AppKit-E8@HIL.ctrace.yml` is `` = `SDS+AppKit-E8@HIL`. +1. Configure trace communication (how trace leaves the MCU) with the `target-set:` in `*.csolution.yml` (and optional settings in `*.dbgconf`). +2. Configure trace generation (what the MCU produces: ITM, DWT, etc.) with the `*.ctrace.yml` file. +3. Collect trace information (debugger receives and records the stream) into raw data files. +4. Analyze trace data files (host tools interpret the collected data files) and generate *.csv files and CTF files. -The file `*.ctrace.yml` specifies the trace information that should be captured from the target. This file is created using the CMSIS-Debugger with dialog support (UX potentially similar to SDS extension). +!!! Note + - `` is the name of the target-set, for example `SDS+AppKit-E8@HIL`. + - Trace does not include SEGGER RTT, SystemView, or STDIO UART output. These features use separate data output paths. -pyOCD stores raw trace streams from various sources in binary files, for example `.trace//ETM.raw`, `.trace//ER.raw`. +### Directory and File Structure -CMSIS Debugger post-processes raw streams into CSV files (on demand for raw views) and [CTF format v1.8.3](https://diamon.org/ctf/v1.8.3/) for viewers and analysis tools. CTF output is written to `.trace//ctf`. +Trace-related files are stored relative to the directory that contains the `*.csolution.yml` file. -CMSIS Debugger uses the [CDT Trace](https://github.com/eclipse-cdt-cloud/vscode-trace-extension) extension as the VS Code viewer. This viewer requires a [Trace Compass XML Analysis file](https://archive.eclipse.org/tracecompass/doc/stable/org.eclipse.tracecompass.doc.user/Data-driven-analysis.html) that defines analysis views. The XML Analysis file should be generated by a pre-processing tool from the trace configuration files listed below. +Directory or File | Created by | Description +:------------------------------------|:----------------|:------------------------------------ +`.` | User | Contains the `*.csolution.yml` project file. +`.cmsis/.ctrace.yml` | CMSIS-Debugger | User trace intent and target-set specific trace capture configuration. +`.trace/.ctrace-run.yml` | pyTS | Generated trace run information, including resolved symbols and register values. +`.trace/.SWO.raw` | pyOCD | Raw trace data files, for example `.SWO`, `MTB`, or `ER`. +`.trace/.SWO.csv` | TraceDecoder | CSV files that represent raw data + ctrace-refs +`.trace//ctf` | TraceDecoder | CTF files such as `metadata`, `stream_0`, and `stream_1`. -The trace solution supports both interactive debug workflows and CI workflows. +TraceDecoder: OpenCSD + writer + CTF -### Tools and Extensions +The `.cmsis/.ctrace.yml` file configures the trace generation. It is created or updated by the user interface of the CMSIS-Debugger Trace View. + +A CLI tool (`pyTS`) resolves symbol-based settings in `*.ctrace.yml` against the ELF/DWARF information of the active target-set and generates the register setup for the hardware configuration. The output is the `.trace/.ctrace-run.yml` which is used by the debugger for register setup in hardware. During trace analysis the information of this file connects the raw trace data (with `atp-id`) back to the `*.ctrace.yml` configuration. + +Raw trace streams are stored as binary files, for example `.trace/.SWO.raw`. The TraceDecoder CLI tool can post-process raw streams into CSV files and [CTF format v1.8.3](https://diamon.org/ctf/v1.8.3/) for viewers and analysis tools. + +### Name Conventions -The following responsibilities are split across tools and VS Code extensions. +#### Location -**[Arm CMSIS Solution](https://marketplace.visualstudio.com/items?itemName=Arm.cmsis-csolution):** +Locations can be symbols or a plain numeric addresses. An additional project or path to an image file may be specified. -- Input: `*.csolution.yml` and optional `.cmsis/*.dbgconf`. -- Output: `*.cbuild-run.yml` consumed by pyOCD. +Location Form | Description +:-------------------------------------|:------------------------------------ +`symbol` | Finds matching symbols in all available symbol files. +`"sourcefile"::symbol` | Finds matching symbols in a source file across all available symbol files. +`project\|symbol` | Finds matching symbols in symbol files from a specific project. +`project\|"sourcefile"::symbol` | Finds matching symbols in a source file from a specific project. +`file-path\|symbol` | Finds matching symbols in symbol files from a specific image file. +`file-path\|"sourcefile"::symbol` | Finds matching symbols in a source file from a specific image file. -**[Arm CMSIS Debugger](https://marketplace.visualstudio.com/items?itemName=Arm.vscode-cmsis-debugger) - Trace View:** +ToDo: examples + +#### References + +References identify a node in the `ctrace.yml` that generated information in `ctrace-run.yml`. These nodes are used for diagnostics and for linking trace analysis results back to the trace setup. + +**Examples:** + +```yml +ctrace-ref: /data#2 # refers to pname section, `data:` node, list node #2 +ctrace-ref: data#2 # `data:` node, list node #2 +ctrace-ref: instruction:start#0 # `instruction:` node, `start:` node, list node #0 +``` -- Input: `.cmsis/*.ctrace.yml`, raw trace files in `.trace`, ELF/DWARF symbols. -- Output: - - updated `.cmsis/*.ctrace.yml` with resolved symbolic locations, - - CTF output in `.trace/ctf` for [VSCode Trace Server](https://marketplace.visualstudio.com/items?itemName=eclipse-cdt.vscode-trace-server), - - trace analysis views and CSV export for raw trace data files. +------- -**[pyOCD](pyOCD-Debugger.md):** +ToDo: RK replace this with pictures -- Input: `*.cbuild-run.yml` and `.cmsis/*.ctrace.yml` (`register-values`). -- Output: raw trace data files in `.trace`. +### Tools and Extensions -**CLI symbol mapper for CI:** +The trace workflow is split across the CMSIS-Toolbox, debugger, and VS Code extensions. -- Purpose: resolve ELF symbol values and update `.cmsis/*.ctrace.yml` in CI workflows. +Tool or Extension | Input | Output | Description +:------------------------------|:----------------------------------------------|:-------------------------------|:------------------------------------ +[Arm CMSIS Solution](https://marketplace.visualstudio.com/items?itemName=Arm.cmsis-csolution) | `*.csolution.yml`, optional `.cmsis/*.dbgconf` | `*.cbuild-run.yml` | Generates the run and debug information consumed by debuggers. +[Arm CMSIS Debugger](https://marketplace.visualstudio.com/items?itemName=Arm.vscode-cmsis-debugger) Trace View | `.cmsis/*.ctrace.yml`, raw trace files, ELF/DWARF symbols | Updated `.cmsis/*/ctrace.yml`, `.trace/*.ctrace-run.yml`, CTF output, CSV export, analysis views | Configures trace capture, resolves symbols, and post-processes trace data. +[pyOCD](pyOCD-Debugger.md) | `*.cbuild-run.yml`, `.target/*/ctrace-run.yml` | Raw trace data files in `.trace` | Programs trace registers and captures trace streams during the debug session. +CLI symbol mapper | `.cmsis/*.ctrace.yml`, ELF/DWARF symbols | `.trace/*.ctrace-run.yml` | Resolves symbols for CI and non-interactive workflows. +[CDT Trace](https://github.com/eclipse-cdt-cloud/vscode-trace-extension) and [VS Code Trace Server](https://marketplace.visualstudio.com/items?itemName=eclipse-cdt.vscode-trace-server) | CTF files, Trace Compass XML Analysis file | Trace viewer panes | Visualizes the CTF output in VS Code. ### Interactive Debug Workflow -Phase | Where | Action | Output artifact +Phase | Where | Action | Output :---------------------|:--------------:|:-----------------------------------------------------------------------|:------------------------------- -Configure | CMSIS Debugger | Load existing `.cmsis/*.ctrace.yml` at IDE start or target-set change. | n/a -Build update | CMSIS Debugger | On update of `*.cbuild-run.yml`, resolve symbols from ELF and validate. | Updated `register-values` in `*.ctrace.yml` -Start debug | pyOCD | Clear previous raw trace files and load `register-values` from `*.ctrace.yml` | n/a -Edit trace settings | CMSIS Debugger | Update `.cmsis/*.ctrace.yml`, re-resolve symbols, persist config. | Saved `.cmsis/*.ctrace.yml` with update `register-values`. -Capture | pyOCD | Capture trace during execution; A monitor command triggers `*.ctrace.yml` reload, changes delete raw trace data files. | Raw trace data files in `.trace` -Analyze | CMSIS Debugger | Open raw trace data files generate views, CSV, or CTF output (utilizing `*.ctrace.yml` values). | `.trace/ctf` files and analysis views +Configure | CMSIS-Debugger | Load `.cmsis/.ctrace.yml` when the IDE starts or when the target-set changes. | Active trace configuration. +Build update | CMSIS-Debugger | Resolve trace locations from ELF/DWARF data after `*.cbuild-run.yml` changes. | Updated `.trace/.ctrace-run.yml`. +Start debug | pyOCD | Clear previous raw trace files and configure trace registers from the generated trace run file. | Target trace setup. +Edit trace settings | CMSIS-Debugger | Update `.cmsis/.ctrace.yml`, resolve symbols, and persist the configuration. | Saved trace configuration and generated trace run file. +Capture | pyOCD | Capture trace data during execution. A monitor command may reload the trace configuration; changes delete previous raw trace data files. | Raw trace files in `.trace/`. +Analyze | CMSIS-Debugger | Open raw trace files and generate views, CSV files, or CTF output. | `.trace//ctf` and analysis views. ### CI Workflow -CI requires a prepared `.cmsis/*.ctrace.yml` (created interactively or maintained manually in source control). +CI requires a prepared `.cmsis/.ctrace.yml` file. This file may be created interactively and checked into source control, or maintained manually. -CI phase | Where | Action | Output artifact +CI Phase | Where | Action | Output :---------------------|:--------------:|:-----------------------------------------------------------------------|:------------------------------- -Build | CMSIS-Toolbox | Build the application. | ELF file and `*.cbuild-run.yml` -Resolve symbols | CLI tool | After build, resolve symbols in `.cmsis/*.ctrace.yml` using ELF/DWARF and validate. | Updated `register-values` in `*.ctrace.yml` -Run and capture | pyOCD | Load image and register values, delete previous raw trace data files, then capture trace data. | Raw trace data files in `.trace` -Post-process/analyze | CMSIS Debugger | Convert raw data to CTF and open analysis views (desktop step). | `.trace/ctf` and reports +Build | CMSIS-Toolbox | Build the application. | ELF file and `*.cbuild-run.yml`. +Resolve symbols | CLI tool | Resolve locations in `.cmsis/.ctrace.yml` using ELF/DWARF data and validate the configuration. | `.trace/.ctrace-run.yml`. +Run and capture | pyOCD | Load the image, configure trace registers, delete previous raw trace files, and capture trace data. | Raw trace files in `.trace/`. +Post-process | CMSIS-Debugger | Convert raw data to CTF and open analysis views on a desktop system. | `.trace//ctf` and reports. + +### Configuration Files + +Trace setup is split between target infrastructure configuration and capture configuration. + +Configuration File | Description +:------------------------------|:------------------------------------ +`*.csolution.yml` | Selects the target-set and debug adapter. It may also reference target-set specific debugger configuration files. +`.cmsis/*.dbgconf` | Optional target-set specific debugger configuration, for example trace clock, trace pins, ETB setup, and related hardware setup. +`.cmsis/.ctrace.yml` | User-authored trace capture configuration. This file defines which data, events, ITM channels, PC samples, or instruction trace streams are enabled. +`.trace/.ctrace-run.yml` | Generated trace run configuration. This file contains resolved symbols and ordered register accesses for pyOCD or other debug tools. + +The trace capture configuration is written to target trace resources such as `DWT`, `ITM`, `ETM`, `MTB`, or `PMU` registers. The generated register accesses are loaded by pyOCD when the debug session starts. + +In a later step, a preprocessing tool may generate `.trace/README.md` with setup instructions and code snippets that can be inserted in the application code. This file can also be consumed by automation and AI-based tooling. + +------ + +### File Structure of `*.ctrace.yml` + +The `*.ctrace.yml` file starts with the node `ctrace:` and contains the trace capture settings for one target-set. -### Configuration files +`ctrace:` | | Content +:-------------------------------------------------------|:------------|:------------------------------------ +    `created-by:` | Optional | Tool and version that created or last updated the file. +    `setup:` | Required | Setup for each processor -- Trace infrastructure (trace clock, ETB setup, trace pins, and related hardware setup) is configured in `*.csolution.yml` and optional target-set specific `.cmsis/*.dbgconf`. -- Trace information (captured data configuration) is configured in Trace View of **[Arm CMSIS Debugger](https://marketplace.visualstudio.com/items?itemName=Arm.vscode-cmsis-debugger)** and stored in target-set specific `.cmsis/*.ctrace.yml` (for example `SDS+AppKit-E8@HIL.ctrace.yml`). +`setup:` | | Content +:-------------------------------------------------------|:------------|:--------------------------------------- +`- pname:` | Optional | Section applies to a processor name (required for multi-processor systems) +    `disable:` | Optional | When set, this list node is ignored; useful for testing. +    [`timestamps:`](#timestamps) | Optional | Enables timestamps in the emitted trace streams. +    [`timesync:`](#timesync) | Optional | Enables time synchronization between trace streams. +    [`data:`](#data) | Optional | DWT data trace configuration. +    [`exceptions:`](#exceptions) | Optional | DWT exception trace configuration. +    [`events:`](#events) | Optional | DWT or PMU event trace configuration. +    [`itm:`](#itm) | Optional | ITM channel configuration. +    [`instructions:`](#instructions) | Future | ETB or MTB instruction trace configuration. +    [`pcsampling:`](#pcsampling) | Future | DWT PC sampling configuration. +    [`synchronization:`](#synchronization) | Optional | Trace synchronization packet period configuration. +    [`tracehalt:`](#tracehalt) | Future | Trace sink or formatter halt trigger configuration. -#### Structure of `*.ctrace.yml` +**Example:** ```yml -ctrace: # start of file (configure trace) -# User-authored fields (created by dialog in CMSIS-Debugger): +ctrace: created-by: CMSIS-Debugger v1.4.0 - instructions: # enable instruction trace (ETB, MTB only) - start: # with cross trigger - - location: mySymbol # can be code or data symbol - value: 0x10 # optional with data symbol - - timestamp: # enable timestamps - - data: # enable data trace - - location: mysymbol # required, symbol or address - access: rw # optional, default write - size: 8 # optional, default sizeof(symbol) - pc: no # optional, default PC value enabled - - location: - : - - exceptions: # enable exception trace - - pname: Core0 # only for Core0 (default all cores) - - - events: # enable all events or a specific list - - event: ///core1/CPI # Cycles per instruction - - event: EXE # Exception overhead - ... - # todo how to specify Cortex-M85 PMU Events - - itm: # enable ITM - - pname: Core0 - enable: 0xFFFFFFFF - privilege: 0x8 - -# Generated fields (managed by CMSIS Debugger and CLI tooling, do not edit manually): - ELF-files: # use for mapping locations - - file: program1.axf - pname: Core0 - - file: program2.axf - pname: Core1 - - register-values: - - pname: Core0 - ITM: - TER: 0xFFFFFFFF - TPR: 0x8 - DTW: - xxx: - symbol: mysymbol - - - - pname: Core1 - ITM: - DTW: + setup: + - pname: +# disable: # disables trace without need to remove settings + timestamps: + timesync: + + data: + - location: mysimple + + - location: \\App\0x20001000 + access: readwrite + size: 0x100 + output: PC + + - location: \\App\"main.c"\sample_counter + access: read + output: PC + match: + value: 0x00001234 + size: 4 + + exceptions: + events: + - event: CPICNT + - event: LSUCNT + + itm: + enable: 0x0000000F + privileged: 0x0 +``` + +#### `timestamps:` + +When `timestamps:` is present, timestamp generation is enabled in the trace stream. ITM uses local timestamps with a synchronous timestamp source. ETM uses the cycle counter. + +#### `timesync:` + +When `timesync:` is present, time synchronization between streams is enabled, for example between ITM and ETM global timestamps. + +#### `data:` + +The `data:` node configures DWT data trace. DWT comparator resources are limited and shared with data access breakpoints, trigger conditions, and trace start/stop logic. + +`data:` | | Content +:--------------------------------------------------------|:------------|:------------------------------------ +`- location:` |**Required** | Symbol or numeric address [location](#location) to trace. +    `access:` | Optional | Access type: `W` (default), `R`, or `RW`. +    `size:` | Optional | Number of bytes in the traced range. Default: `sizeof(symbol)`, `4` for numeric addresses. +    `pname:` | Optional | Processor name, required for numeric addresses in multi-processor systems. +    `output:` | Optional | Trace output mode (see table below). Default: `value`. +    `match:` | Optional | Value match condition. When present, trace is emitted only for matching accesses. +       `value:` |**Required** | Value to match. +       `size:` | Optional | Number of bytes to compare. Allowed values: 1, 2, 4. Default: 4. + +`output:` | Description +:---------------|:------------------------------------ +`value` | Emits the value of the access. +`address` | Emits the address offset. This is useful when tracing an address range. +`PC` | Emits the PC value that caused the access. +`match` | Emits only the comparator ID of a match. This requires Armv8-M and saves trace bandwidth. +`PC+value` | Emits PC and value. +`address+value` | Emits address offset and value. +`PC+address` | Emits PC and address offset. This requires Armv8-M. + +!!! Note + `size:` values greater than `4` may require two DWT comparators, depending on the DWT architecture. A `match:` condition can also require two DWT comparators. + +#### `exceptions:` + +The `exceptions:` node enables DWT exception trace. This does not enable ETM exception trace. + +#### `events:` + +The `events:` node enables DWT or PMU event trace for all processors or for a specific processor. + +`events:` | | Content +:-------------------------------------|:------------|:------------------------------------ +`- event:` |**Required** | Event selector, optionally scoped with `\\\`. + +Supported DWT event selectors include `CYCCNT`, `CPICNT`, `EXCCNT`, `SLEEPCNT`, `LSUCNT`, and `FOLDCNT`. PMU events may be added when supported by the target. + +ToDo: PMU details + +**Example:** + +```yml +events: + - event: CPICNT + - event: FOLDCNT + - event: LSUCNT +``` + +#### `itm:` + +The `itm:` node enables ITM channels. + +`itm:` | | Content +:-------------------------------------|:------------|:------------------------------------ +`- enable:` |**Required** | ITM channel bit mask, optionally scoped with `\\\`. +    `privileged:` | Optional | Privileged access mask by blocks of eight channels. Default: `0`. + +Each bit in `enable:` represents one ITM channel. When the processor scope is omitted, the ITM setting applies to all processors in the system that support ITM. + +!!! Note + ITM channel 0 is often used for `printf` output. This output should be routed to an output window or debug console instead of the trace analysis components. + +#### `pcsampling:` + +The `pcsampling:` node enables DWT PC sampling for selected processors. + +`pcsampling:` | | Content +:-------------------------------------|:------------|:------------------------------------ +`- period:` | Optional | Sampling period, optionally scoped with `\\\`. When the processor scope is omitted, the setting applies to all processors that support PC sampling. + +ToDo: The allowed sampling periods are target dependent and still need to be finalized. + +#### `synchronization:` + +The `synchronization:` node overrides component-specific synchronization packet frequencies. + +`synchronization:` | | Content +:-------------------------------------|:------------|:------------------------------------ +`- period:` |**Required** | Synchronization period in the form `[\\\]\`. + +Component | Supported Values +:---------|:------------------------------------ +`DWT` | `0` (off), `16M`, `64M`, `256M` (default) processor cycles. +`ETM` | `0` (off), `256`, `512`, `1k` (default), `2k`, ... , or `512k`, `1M` cycles/bytes. + +!!! Note + `k`=`2^10`, `M`=`2^20` + +**Example:** + +```yml +synchronization: + - period: DWT\16M + - period: ETM\1k +``` + +#### `instructions:` + +The `instructions:` node is reserved for ETB and MTB instruction trace. It is not required for the initial implementation. + +`instructions:` | | Content +:-------------------------------------|:------------|:------------------------------------ +    `start:` | Optional | Conditions that start instruction trace. +    `stop:` | Optional | Conditions that stop instruction trace. + +`start:` and `stop:` contain condition entries. These entries define when instruction trace starts or stops; they do not define trace output. + +`start:` or `stop:` | | Content +:------------------------------------------------------|:------------|:------------------------------------ +`- location:` |**Required** | Code symbol, data symbol, or numeric address [location](#location) used as the trace condition. +    `access:` | Optional | Access type: `X`, `R`, `W`, or `RW`. +    `size:` | Optional | Number of bytes in the condition range. Defaults to `sizeof(symbol)` for symbols and `4` for numeric addresses. +    `match:` | Optional | Value match condition for data symbols or numeric addresses. +       `value:` |**Required** | Value to match. +       `size:` | Optional | Number of bytes to compare. Allowed values: `1`, `2`, `4`. + +The default `access:` is `X` for code symbols and `W` for data symbols or numeric addresses. +ToDo: do not understand this: Multiple conditions may be supported as an `AND` combination when they affect the same ETM or MTB. + +#### `tracehalt:` + +The `tracehalt:` node is reserved for conditions that halt a trace sink or formatter by trace trigger. It affects all trace streams that use the sink, not only ETM instruction trace. + +`tracehalt:` | | Content +:-------------------------------------|:------------|:------------------------------------ +`- combine:` | Optional | Boolean operator for complex halt trigger conditions: `AND` (default) or `OR`. +    `location:` | Optional | Halt trigger location. ToDo: Details are still open. + +### File Structure of `*.ctrace-run.yml` + +The `*.ctrace-run.yml` file starts with the node `ctrace-run:`. It is generated from `*.ctrace.yml`, `*.cbuild-run.yml`, and ELF/DWARF symbol information. This file is a generated artifact and should not be edited manually. + +`ctrace-run:` | | Content +:--------------------------------------------------------|:------------|:------------------------------------ +    `generated-by:` | Optional | Tool and version that generated the file. +    `ctrace-refs:` |**Required** | List of [references](#references) in the `*.ctrace.yml` file. + +`ctrace-refs:` | | Content +:--------------------------------------------------------|:------------|:------------------------------------ +`- ctrace-ref:` |**Required** | [Reference](#references) to a node in the `*.ctrace.yml` file that generated the register setup +    `info:` | Optional | Additional information (i.e. alignment extension, etc.) +    `warning:` | Optional | Warning message +    `error:` | Optional | Error message when setup cannot be completed +    `symbol-file:` | Optional | Absolute path to the symbol file used in this reference +    `symbol-address:` | Optional | Address of the symbol +    `atp-id:` | Optional | ID in raw trace that links back to this entry +    `regs:` | Optional | Register setup + +`regs:` | | Content +:--------------------------------------------------------|:------------|:------------------------------------ +`- name:` |**Required** | Symbolic name of the register +    `value:` |**Required** | Value to write in this register +    `mask:` | Optional | Bit mask for value write (default: 0xFFFFFFFF) + +**Example:** + +```yml +ctrace-run: + generated-by: pyTS v0.0 + ctrace-refs: + - ctrace-ref: core0/itm + pname: + symbol-file: + symbol-address: address of symbol + atp-id: 1 + regs: + - name: ITM_TER0 + value: 0xFFFFFFFF +# mask + - name: + value: + + - ctrace-ref: data#0 + error | warning | info : cannot find symbol + + - ctrace-ref: data#1 + regs: + - name: DWT_COMP0 + value: 1 + - name: DWT_COMP1 + value: 2 ``` -Validation rules: +#### Register Accesses -- `location` entries accept symbol names or numeric addresses. -- `pname` defaults to all cores if omitted; set it to scope trace by core. -- `register-values` must be regenerated after each build that changes symbols. -- Fields under `ELF-files` and `register-values` are generated artifacts. +ToDo: rewrite this section -### Target trace information setup +Register accesses are generated in the recommended execution order and are executed from top to bottom. -The trace information configuration is written to `DWT` and `ITM` registers of the Cortex-M system. The setup is injected through generated `register-values` and loaded by pyOCD to the target. +- A single-core system uses one `register-access:` entry with no `pname:` value. +- A multi-processor system uses one `register-access:` entry per processor. +- Entries in `*.ctrace.yml` without processor scope are expanded to each processor that supports the requested trace feature. +- System-wide trace sources may use an entry without `pname:`. -In a later step, a pre-processing tool may generate `.trace/README.md` with setup instructions and code snippets that can be inserted in the application code. This file can also be consumed by automation and AI-based tooling. +Trace Component | Base Address | Description +:---------------|:------------:|:------------------------------------ +`ITM` | `0xE0000000` | Instrumentation Trace Macrocell. +`DWT` | `0xE0001000` | Data Watchpoint and Trace unit. +`PMU` | `0xE0003000` | Performance Monitoring Unit. +`ETM` | `0xE0041000` | Embedded Trace Macrocell. -### Overall directory and file structure +Register access rules: -Directory | Description -:--------------------------|:-------------------- -`.` (root) | Contains *.csolution.yml project file. -`.cmsis` | Contains `.ctrace.yml` that configures which trace information is captured (effectively the DWT, ITM register setup). -`.trace/` | Contains raw trace data files. -`.trace//ctf` | Contains CTF files (`metadata`, `stream_0`, `stream_1`, etc.) +- Register accesses are 32-bit little-endian values. +- Each register access carries a comment with the brief register name as defined in the Armv8-M Architecture Reference Manual. Armv8-M names are used for simplicity, because Armv8-M is a superset of Armv7-M for these registers. +- A `write` access may include `mask:`. When single bits are masked out, the operation becomes a read-modify-write access. +- A `read` access compares the value read from the target against the configured value. +- A `read` access may include `mask:` to compare selected bits only. A mask value of `0` ignores the read value but still performs the read, for example to trigger clear-on-read side effects. +- A `read` access may include `timeout:`. The debugger retries until the value matches or the timeout expires. +- If a read access times out, the debugger aborts configuration of the current component for the current processor and continues with the next component or processor. +- Symbol locations are resolved to numeric address and size values before register accesses are generated. When a resolved symbol is programmed into a comparator register, the register-name comment is extended with the original symbol name and size. ### Initial Implementation -Initial release focus is pyOCD with SWO UART and interactive operation in CMSIS-Debugger. +The initial implementation focuses on pyOCD with SWO UART and interactive operation in CMSIS-Debugger. -Subsequent releases extend this initial solution to: +Subsequent releases may extend this initial solution to: -- Instruction Trace (ETB, MTB), EventRecorder -- CI Workflow +- Instruction trace using ETB or MTB. +- Event Recorder. +- CI workflow automation. -### Open design questions +### Remaining Design Questions -- How should cross-trigger functionality be represented in `*.ctrace.yml`? -- Should core selection (`pname`) support richer selectors beyond current core names?\ -- UX: how to expose configuration and captured trace information. -- Rename "TRACE AND LIVE VIEW" to "TARGET MONITOR" with sub-sections LIVE WATCH and TRACE. +- Cross-trigger functionality will be represented later (potentially in `*.ctrace.yml`) +- "Trace and Live View" will be renamed to "Target Monitor" with the sub-sections "Live Watch" and "Trace" + - How should trace configuration and captured trace information be exposed in the user interface? ### Out-of-Scope -- Trace **does not** include RTT (SystemView) or STDIO UART output, which use separate data output paths. -- ITM0 is often used for printf output; this output should not be routed to trace components and should instead go to an output window or debug console. +- SEGGER RTT, SystemView, and STDIO UART output are not part of trace capture and use separate output paths. +- ITM channel 0 `printf` output should not be routed to trace analysis components. It should be shown in an output window or debug console.