Tonbandgerät

Tonbandgerät /ˈtoːnbantɡərɛːt/ n.

  1. German for audio tape recorder.
  2. An electrical device for recording sound on magnetic tape for playback at a later time.

A small embedded systems tracer with support for bare-metal and FreeRTOS-based targets.

Philipp Schilk, 2024

Overview

A sample trace

Tonbandgerät’s core is a small, portable, trace event generator and handler written in C and designed for embedded systems. It requires minimal porting and configuration, and features multiple backends for gathering and transmitting traces.

It can be used both with an RTOS, or in bare-metal environments to instrument user code and track hardware events by tracing interrupts. Full tracing of FreeRTOS tasks and resources is also supported out-of-the-box.

Tonbandgerät is based on a simple custom binary trace format designed to be fairly fast to encode and keep traces as small as possible. Recorded traces can be viewed in Google’s in-browser perfetto after conversion with the provided CLI tool or in-browser converter.

Documentation

The documentation for Tonbandgerät can be found in the docs/ folder and compiled for viewing with mdbook by running mdbook build in docs/. The latest version of the documentation can also be viewed online here.

Trace Converter + Viewing

The trace converter is written in rust, can be found here. For convenience, there is also a WASM version with web frontend, which runs in the browser and can be found here.

Licensing

The target tracer sources and documentation are released under the MIT License. All conversion and analysis tools, such as the decoder and converter, the CLI, and the web converter are released under the GNU GPL3 License.

Status

🚧 Note

Tonbandgerät is in early development and by no means considered stable. Everything - including the binary trace format - is subject to change.

Please report any issues here.

Completed:

Tonbandgerät:

  • Trace encoder.
  • Streaming backend.
  • Snapshot backend.
  • Metadata buffer.
  • Initial FreeRTOS support.

Conversion tools:

  • CLI converter.
  • In-browser converter.

Other:

  • STM32 + FreeRTOS example project.

Work-In-Progress:

Tonbandgerät:

  • Support for multicore tracing, including FreeRTOS SMP: Implemented and theoretically (almost?) done, but completely untested. Currently this is limited to cores that share a single, monotonic, time stamp timer.

  • Full FreeRTOS support, including some PRs: PRs are in a draft state/being reviewed. Certain FreeRTOS (rare) are not yet traced correctly due to insufficient tracing hooks. Tracing of streambuffers, direct-to-task notification, timers, and event groups are not yet Implemented.

Other:

  • This documentation.

Planned:

Tonbandgerät:

  • Post-mortem backend.
  • Task stack utilization tracing.
  • Multi-core for cores without common timebase.

Other:

  • More examples, including a bare-metal project, RTT-backed project, and RP2040 SMP project.
  • More example ports.

Ideas:

Support Other RTOSes:

  • All FreeRTOS-specific functionality has already been seperated into its own “module”, and more RTOSes could be added as separate modules.

Custom UI:

  • Perfetto, while incredibly powerful and simple to target, is not a perfect match for Tonbandgerät. It cannot display arbitrary tracks, forcing them to be global or part of a process/thread hierarchy. This could be improved by generating synthetic linux ftrace events, but that is a can of worms I don’t quite want to open. Furthermore, as it stands at the time of writing, a perfetto-based trace will never be able to display trace events in real time.

  • A custom UI would enable real-time viewing an be the first step towards a more “integrated” desktop tool that could also handle trace recording (building on probe.rs for RTT communication). A gui built on tauri and/or egui could continue to enable the current in-browser experience.

  • This would require a better in-memory model of trace data. Likely something like an in-memory DB? Apache Arrow?