pyTS

Python Trace Setup utility complementing pyOCD for CMSIS Debug integration

Install for development

Create a virtual environment for PyTS:

> python3 -m venv .venv
> source .venv/bin/activate
> which pip
.venv/bin/pip

Install pyTS itself and its runtime dependencies into the virtual environment in editable mode:

> pip install -e .
> which pyts
.venv/bin/pyts

Installing test tooling:

> pip install -e '.[test]'

Install type-check tooling:

> pip install -e '.[lint]'

Run tests and strict type checks:

> pytest -q
> pyright
> mypy

Windows user

Run pip commands with double-quotes, e.g.

> .venv/bin/activate.bat
> where pip
.venv/Scripts/pip.exe
> pip install -e ".[test]"

CLI

Generate a trace run configuration from a CMSIS cbuild-run file:

pyts <cbuild-run.yml>

The command returns status 0 when generation succeeds without error entries. If the written trace run file contains an error, it returns 2. Use --pedantic to also return 2 for warning entries; info entries do not affect the status. The file and result summary are still written when generation reports these diagnostics. --allow-missing permits writing the file with unresolved symbols, but any resulting error still returns 2.

The command reads .cmsis/<solution>+<target-type>[@<target-set>].ctrace.yml, resolves symbols from the cbuild-run ELF outputs, and writes the generated trace setup to .trace/<solution>+<target-type>[@<target-set>].ctrace-run.yml. If a .cmsis/~<solution>+<target-type>[@<target-set>].ctrace.yml file exists, pyTS prefers it and writes .trace/~<solution>+<target-type>[@<target-set>].ctrace-run.yml instead, leaving the production trace files unchanged.

For symbol locations that pyTS resolves, generated symbol-file: entries are relative to the ctrace-run.yml file. The .cbuild-run.yml input remains unchanged, so its output[].file paths keep their CMSIS-Toolbox-defined base directory.

When cbuild-run.system-resources.processors is available, pyTS uses each processor's core and pname to generate CMSIS ctrace-run.ctrace-disable and ctrace-run.ctrace-refs entries. The disable entries clear all modeled DWT comparators before active references are applied. Their content is independent of the selected trace features, allowing a debugger to turn off settings that were removed while an interactive session was running. Active reference regs lists contain masked architectural ITM and DWT register writes for ITM channels, local and global timestamps, basic DWTv1/DWTv2 data trace, exception trace, event trace, PC sampling, and DWT synchronization. Unsupported processor or feature combinations are reported on the corresponding reference with error.

DWT capabilities are derived from the processor core because cbuild-run does not provide comparator counts. Trace slots can be allocated for data trace; additional match slots are disabled by ctrace-disable but reserved for future instruction-trace start/stop support.

Core	Trace slots	Additional match slots
Cortex-M0	0	0
Cortex-M0+, Cortex-M23	0	2
Cortex-M3, Cortex-M4, Cortex-M7, Cortex-M33	4	0
SecurCore SC300, Cortex-M35P, STAR-MC1, STAR-MC3	4	0
Cortex-M52, Cortex-M55, Cortex-M85	4	4
Other or unknown cores	0	0

The data-trace allocator never consumes the additional match slots. Requests that exceed the trace-slot count are reported on the corresponding reference. Optional null values in trace lists and setup elements with required children are treated as not configured. A null setup element with no required children is treated as an empty mapping and uses the documented defaults; this applies to timestamps, timesync, exceptions, pcsampling, synchronization, and instructions. Within configured objects, optional null properties are treated as omitted.

Every registered feature uses its encoder default when absent. Missing data, event, and trace-halt lists contain no entries. Optional features such as local timestamps, exception trace, ITM channels, and PC sampling default to disabled; their initial disable writes are generated in ctrace-disable, so no additional feature reference is needed. A present empty node still enables presence flags such as timestamps and exceptions.

synchronization.DWT defaults to 16M. synchronization groups trace features; synchronization.DWT is the DWT synchronization feature. Its generated reference is synchronization/DWT, or <pname>/synchronization/DWT for a setup with pname. The default applies in every active setup when DWT is absent or null, including an absent, null, or empty group. Feature defaults are independent of whether their group is present. The modes are the strings 16M, 64M, 256M, and off to disable synchronization. String 0 is also accepted as a synonym for off. Integers parsed from YAML are converted to decimal strings before comparison, so integer 0 and string "0" are equivalent. Strings are compared exactly; booleans and floating-point values are invalid. YAML boolean resolution follows YAML 1.2 Core: unquoted off, on, yes, and no remain strings; true and false (including title-case and uppercase) remain booleans. Both quoted and unquoted off disable DWT synchronization and, like 0, emit no register writes or reference. The initial ctrace-disable writes already clear ITM_TCR.SYNCENA. timesync groups trace features; timesync.ITM is the feature that controls ITM global timestamps. It defaults to off for every active setup when the group is absent, null, or an empty mapping, or when ITM is absent or null. Its generated reference is timesync/ITM, or <pname>/timesync/ITM for a setup with pname. The off mode emits no register writes or reference, because ctrace-disable already clears the ITM global timestamp configuration. Default register writes do not add missing nodes to the preserved source setup. The presence-only disable node retains its meaning when empty. Additional properties in ctrace configurations are preserved but ignored, allowing future schema extensions without validation failures. Property names remain case-sensitive: an incorrectly cased optional property is ignored, while an incorrectly cased required property is reported as missing. The ctrace-run.ctrace-setup node retains the original source ctrace.setup content, with integer timesync.ITM and synchronization.DWT values normalized to decimal strings in the output copy. Enriched location metadata is used internally when generating ctrace-refs. Symbol extents and types are emitted as data[].symbol-size and data[].symbol-type in the generated references; data[].size remains the trace access size. DWARF types use language-neutral categories derived from their tags and encodings, such as signed, unsigned, bool, float, pointer, array, and struct; source-language type names are not emitted. When a symbol type cannot be deduced from DWARF, symbol-type is omitted. Addresses and register values and masks are written as 32-bit hexadecimal YAML integers. The generated ctrace-run mapping contains only generated-by, ctrace-setup, ctrace-disable, and ctrace-refs; other source ctrace properties are not copied. If no processor has DWT resources, ctrace-disable is emitted without children. Location-style and legacy symbol/address entries may coexist in one trace document; pyTS resolves both styles in document order using the same ELF cache. PC sampling periods use integer CPU-cycle counts: 0 disables sampling, while supported enabled periods are 64 * n or 1024 * n, where n is an integer from 1 through 16.

timesync.ITM controls global timestamp insertion in ITM streams for correlation across processors. It accepts the strings off (default), 128, 8192, or packet. Integers parsed from YAML are converted to decimal strings before comparison, so quoted and unquoted numeric modes are equivalent. Strings are compared exactly; booleans and floating-point values are invalid. These modes map to ITM_TCR[11:10] values 0, 1, 2, and 3 respectively. Enabled modes also set ITMENA and participate in stream/ATBID allocation; off clears only the global timestamp mode bits. For example:

ctrace:
  setup:
    - pname: CM4
      timesync:
        ITM: 8192

Enabled modes require a timestamp generator on the device, configured through the trace communication settings in *.csolution.yml and optionally *.dbgconf; pyTS configures timestamp insertion, not that generator.

pyTS reads YAML with YAML 1.2 Core implicit boolean resolution. Unquoted off, on, yes, and no remain strings in keys and values. Only true, false, and their title-case or uppercase forms become booleans. Other scalar parsing is unchanged, including hexadecimal integers. Boolean properties should use true or false.

Data trace supports the CMSIS output modes value, offset, PC, match, PC+value, offset+value, and PC+offset. DWTv1 supports value, offset, PC+value, and offset+value for all access types, plus PC for RW; it cannot produce match or PC+offset. One DWTv1 match: condition per processor can use the portable comparator 0/1 address-value pair with any otherwise supported output. Its address range size and matched data width are encoded independently. DWTv2 Main Extension processors support all output modes. Cortex-M23 cannot generate the required data trace packets. DWTv1 comparator ranges must be a naturally aligned power of two; when data[].size is not a power of two, or data[].address is not aligned to the comparator range, pyTS enlarges the size and realigns the address (rounding the address down) to the smallest naturally aligned power-of-two range that still covers the entire requested address/size range. The adjustment is reported on the corresponding reference with warning, naming the originally requested address and size, and the reference's address and size are updated to the effective values used for register generation. A data.size that exceeds the DWT mask capability (larger than 1 << 31) is still reported with error and no register setup.

DWTv2 offset output and arbitrary or unaligned ranges consume consecutive lower/limit comparator pairs. A one-byte range cannot emit an offset packet. A DWTv2 match: condition consumes an address/linked-value pair. The requested output applies to the address comparator (default value), while the linked value comparator implicitly uses match output. Data and match sizes must be equal and naturally aligned. Match sizes are 1, 2, or 4 bytes (default 4), and values must be unsigned and fit the selected width. Requests that cannot be represented exactly are reported on the corresponding reference with error and no register setup.

Packaging

The project uses a src/ layout and pyproject.toml metadata for PyPI distribution. Build a source distribution and wheel with:

.venv/bin/python -m pip install build
.venv/bin/python -m build

pyInstaller Builds

.venv/bin/python -m pip install pyinstaller
pyinstaller --clean --noconfirm --onefile --name pyTS src/pyts/__main__.py

No need at this point to commit the generated ./pyTS.spec to the repository.

Contributing

Contributions are welcome. Please open an issue to discuss significant changes and submit fixes or enhancements as pull requests. Before submitting a change, run the tests and strict type checks described in Install for development.

By submitting a contribution, you agree that it may be distributed under the project's Apache License 2.0.

License

This project is licensed under the Apache License 2.0. Third-party dependencies remain subject to their respective licenses; see the Third-Party Intellectual Property notice, generated with pip-licenses.