diff --git a/docs/Experimental-Features.md b/docs/Experimental-Features.md index 50902427..419bdd39 100644 --- a/docs/Experimental-Features.md +++ b/docs/Experimental-Features.md @@ -141,173 +141,403 @@ 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. + +### Directory and File Structure + +Trace-related files are stored relative to the directory that contains the `*.csolution.yml` file. + +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`. + +TraceDecoder: OpenCSD + writer + CTF output + +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 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 + +#### Location -pyOCD stores raw trace streams from various sources in binary files, for example `.trace//ETM.raw`, `.trace//ER.raw`. +Locations can be symbols or a plain numeric addresses. An additional project or path to an image file may be specified. -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`. +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. -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. +ToDo: examples -The trace solution supports both interactive debug workflows and CI workflows. +#### 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 +``` ### Tools and Extensions -The following responsibilities are split across tools and VS Code extensions. +The trace workflow is split across the command-line tools and and VS Code extensions as shown below. -**[Arm CMSIS Solution](https://marketplace.visualstudio.com/items?itemName=Arm.cmsis-csolution):** +![Trace components and data flow](./images/Trace-Dataflow.png "Trace components and data flow") -- Input: `*.csolution.yml` and optional `.cmsis/*.dbgconf`. -- Output: `*.cbuild-run.yml` consumed by pyOCD. +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 Generation Setup View | `.cmsis/*.ctrace.yml` | Updated `.cmsis/*.ctrace.yml` | Configures trace capture. +pyTS symbol mapper | `.cmsis/*.ctrace.yml`, ELF/DWARF symbols | `.trace/*.ctrace-run.yml` | Resolves symbols and generates Corsight register valuesworkflows. +[pyOCD](pyOCD-Debugger.md) | `*.cbuild-run.yml`, `.trace/*.ctrace-run.yml` | Raw trace data files in `.trace/` | Programs trace registers and captures trace streams during the debug session. +Trace Decoder | Raw trace data files, `.trace/*.ctrace.run.yml` | CSV, CTF files, Trace Compass XML Analysis file | Generates CSV files (human readable) and CTF files +[Trace Viewer for VSCode](https://marketplace.visualstudio.com/items?itemName=eclipse-cdt.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. -**[Arm CMSIS Debugger](https://marketplace.visualstudio.com/items?itemName=Arm.vscode-cmsis-debugger) - Trace View:** +**Interactive Debug Workflow:** -- 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. +It is possible to change the **Trace Generation Setup** during debugging. For this workflow: -**[pyOCD](pyOCD-Debugger.md):** +- pyTS generates a new `*.ctrace-run.yml` file. +- pyOCD reloads this `*.ctrace-run.yml` file and deletes existing **Raw Trace Stream** files. -- Input: `*.cbuild-run.yml` and `.cmsis/*.ctrace.yml` (`register-values`). -- Output: raw trace data files in `.trace`. +**CI Workflow:** -**CLI symbol mapper for CI:** +CI requires a prepared `.cmsis/.ctrace.yml` file. This file is may be under source control or maintained manually. -- Purpose: resolve ELF symbol values and update `.cmsis/*.ctrace.yml` in CI workflows. +### Configuration Files -### Interactive Debug Workflow +Trace setup is split between target infrastructure configuration and capture configuration. -Phase | Where | Action | Output artifact -:---------------------|:--------------:|:-----------------------------------------------------------------------|:------------------------------- -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 +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. -### CI Workflow +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. -CI requires a prepared `.cmsis/*.ctrace.yml` (created interactively or maintained manually in source control). +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. -CI phase | Where | Action | Output artifact -:---------------------|:--------------:|:-----------------------------------------------------------------------|:------------------------------- -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 +### File Structure of `*.ctrace.yml` -### Configuration files +The `*.ctrace.yml` file starts with the node `ctrace:` and contains the trace capture settings for one target-set. -- 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`). +`ctrace:` | | Content +:-------------------------------------------------------|:------------|:------------------------------------ +    `created-by:` | Optional | Tool and version that created or last updated the file. +    `setup:` | Required | Setup for each processor -#### Structure of `*.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. + +**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: R + 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. + +`timestamps:` | | Content +:--------------------------------------------------------|:------------|:------------------------------------ +    `itm-prescaler:` | Optional | ITM timestamp prescaler: `1` (default), `4`, `16`, `64`. + +#### `timesync:` + +When `timesync:` is present, time synchronization between streams is enabled, for example between ITM and ETM by 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`, `R`, or `RW`. Default: `W`. +    `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. + +Supported DWT event selectors include `CYCCNT`, `CPICNT`, `EXCCNT`, `SLEEPCNT`, `LSUCNT`, and `FOLDCNT`. +`PMU` events may be added when supported by the target. They are emitted when one or more PMU counters with index 0..7 have an 8-bit overflow. + +**Example:** + +```yml +events: + - event: CPICNT + - event: FOLDCNT + - event: LSUCNT ``` -Validation rules: +#### `itm:` -- `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. +The `itm:` node enables ITM channels. + +`itm:` | | Content +:-------------------------------------|:------------|:------------------------------------ +`- enable:` |**Required** | ITM channel bit mask. +    `privileged:` | Optional | Privileged access only mask by blocks of eight channels. Default: `0`. + +Each bit in `enable:` represents one ITM channel. + +!!! 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 in CPU cycles. + +Supported values for DWT PC sampling `period:` are `0` (off), `64*1`, `64*2`, ... , `64*16`, `1024*1`, `1024*2`, ... , and `1024*16`. Default: `0`. + +#### `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` processor cycles. Default: `256M`. +`ETM` | `0` (off), `256`, `512`, `1k`, `2k`, ... , or `512k`, `1M` cycles/bytes. Default `1k`. + +!!! 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 +``` -### Target trace information setup +#### Register Accesses -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. +The `ctrace-run.yml` file contains the register values that are required for trace generation. It does not include enable sequences required by the Arm processor to access these registers. The debugger (pyOCD) has knowledge about the arichtectural defined trace components (listed in the table below) and therefore generates the right sequences, potentially with timeouts. -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 +The `ctrace-ref:` nodes references the trace generation configuration in `ctrace.yml` and contain register values that represents the references setup. +A single-core system has no `pname:` value; a multi-processor always includes a `pname:` value in the `ctrace-ref:` node. -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.) +ToDo Jens: ware the system wide settings? How are the represented? What trace component is configured with such settings? + - Entries in `*.ctrace.yml` without processor scope are expanded to each processor that supports the requested trace feature. ### 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? +- How are PMU events configured (what is captured with the PMU)? ### 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. diff --git a/docs/images/Trace-Dataflow.png b/docs/images/Trace-Dataflow.png new file mode 100644 index 00000000..cdbb8420 Binary files /dev/null and b/docs/images/Trace-Dataflow.png differ diff --git a/docs/images/overview.pptx b/docs/images/overview.pptx index e96ba2d6..fccb3f60 100644 Binary files a/docs/images/overview.pptx and b/docs/images/overview.pptx differ diff --git a/docs/images/trace_analysis.png b/docs/images/trace_analysis.png new file mode 100644 index 00000000..e033fde2 Binary files /dev/null and b/docs/images/trace_analysis.png differ diff --git a/docs/images/trace_capture.png b/docs/images/trace_capture.png new file mode 100644 index 00000000..f1fe17f1 Binary files /dev/null and b/docs/images/trace_capture.png differ diff --git a/docs/images/trace_communication.png b/docs/images/trace_communication.png new file mode 100644 index 00000000..463188a8 Binary files /dev/null and b/docs/images/trace_communication.png differ diff --git a/docs/images/trace_generation.png b/docs/images/trace_generation.png new file mode 100644 index 00000000..e50254f4 Binary files /dev/null and b/docs/images/trace_generation.png differ