RTIC Scope

The framework is split into three main components: the canonical backend, the frontend(s), and the target-side tracing crate, cortex-m-rtic-trace.

The backend

is a host-side (i.e., the system that programs the target device) application which exposes two operations:

trace

where the target is flashed with the wanted firmware and the execution trace is captured and saved to file.

replay

where previously recorded traces are replayed for postmortem and offline analysis.

Frontend(s)

While tracing and replaying, a trace can be forwarded to a set of frontends via Unix domain sockets where virtually endless analytics can be applied. Consider, for example, a graphical frontend alike an oscilloscope or a logic analyzer, but instead of signals the RTIC tasks and their executation statuses (running, scheduled, preempted) are plotted. A dummy frontend (used for debug and reference purposes) is available out of the box; the dummy frontend prints received events, their absolute timestamps, and the time since the last chunk of events. For example:

dummy: @1625485615052692868 ns (+124999937 ns): [] # the local timestamp clock overflowed, but nothing else happened
dummy: @1625485615052769556 ns (+76688 ns): [Task { name: "app::toggle", action: Entered }]
dummy: @1625485615052790806 ns (+21250 ns): [Task { name: "app::toggle", action: Exited }]

At present, information only flows from the backend to the specified frontend, via --frontend. In the future, bidirectional communication will be possible, enabling a frontend to implement a complex hardware-in-the-loop testing suite, for example. Please refer to the project roadmap for future prospects.

The target-side tracing crate

cortex-m-rtic-trace, is a small auxiliary crate applied to the target application under trace. It only exposes the #[trace] macro, which is used to trace RTIC software tasks. NOTE: While hardware tasks are traced "free of charge" (see 5), software tasks are traced by writing to a u32-variable twice.

The framework is managed under the RTIC Scope organization on GitHub. Below is a list of the main repositories that constitute the RTIC Scope project. Any other crates listed under the organization but not here are branches of other repositories pending upstream merge.

cargo-rtic-scope

The RTIC Scope backend which builds the target application, recovers trace information, traces the target, replays traces, etc.

cortex-m-rtic-trace

no_std crate used to configure the target device for tracing purposes.

examples

A set of example target applications where the RTIC Scope framework is applied. These are also documented below.

api

The common API used between the RTIC Scope backend and all frontends.

frontend-dummy

A "noop" frontend implementation that writes received api::EventChunk structs to stderr with nanosecond timestamp information.

itm-decode

A host-side library that decodes the binary trace stream received from the target to workable Rust structures.

rfcs

A catch-all meta-repository for discussions and feature suggestions that that encompass more than a single repository.

rtic-scope.github.io

The source code for this web page.

• A target device with an ARMv7-M MCU.
• A hardware probe supported by probe-rs or some serial hardware that exposes a serial device which then can be used to read the trace stream from the target device.

• A Linux-based operating system with a recent Rust toolchain. Minimum supported Rust version TBA.

A stream of back-to-back ITM packets are read from a properly configured target or a file. Each packet contains a header and a number of payload bytes. Of special interest are exception trace packets:

The DWT unit can generate an Exception trace packet whenever then processor enters, exits, or returns to an exception. — Appendix D4.3.2

This packet then contains one of the exception numbers listed in the table below. These numbers are bound to RTIC tasks.

Henceforth, this document will refer to these exceptions/interrupt numbers as interrupt request (IRQ) numbers.

Software tasks are similarly traced, but come at a cost of a write to a u32 variable when entering and exiting the task, resulting in a cost of two writes. This variable is registered as a watch address in the DWT subsystem. Any writes to this address are asynchronously intercepted in hardware, and the new value is encapsulated in an ITM packet along with the ID of the DWT comparator.

The received IRQ numbers in a packet must be associated back to the correct RTIC tasks. This is done in a preparatory step before the target is flashed and traced. For example, when executing cargo rtic-scope --bin blinky [options...]:

1. Device-specific information is read from the crate's manifest metadata table. This table is expected to contain three fields which is otherwise non-trivial to resolve from blinky's source file alone. For example:

   [package.metadata.rtic-scope]
   # The name of the used peripheral access crate (PAC)
   pac = "stm32f4"
   # Required features of the above PAC, if any
   pac_features = ["stm32f401"]
   # The full path to the enum structure containing the exceptions and interrupts, in the PAC, used in the crate
   interrupt_path = "stm32f4::stm32f401::Interrupt"
   

   workspace.metadata.rtic-scope is used as fallback if package-level metadata is not specified. It is up to the end-user to verify this metadata. In the worst case that the metadata is incorrect but still builds and maps (step 3-4), incorrect data will be forwarded to specified sinks.

2. blinky is build via a regular cargo build --bin blinky and it's target directory is reused for intermediate artifacts.

3. The RTIC application declaration, #[app(...)] mod app {...}, is parsed from blinky's source code. From this declaration, IRQ labels are extracted from each #[task(binds = ...)] macro occurance, and software tasks are parsed and mapped from each #[trace]. For example, binds = SysTick, and binds = EXTI1 might be extracted. Here, each IRQ label is associated with the RTIC task it is bound to.

   This parsing step places some restrictions on how the source code for an RTIC application can be written. Refer to 6.2.

4. A shared object file is then built which translates IRQ labels to IRQ numbers by help of the metadata acquired in step 1. The source code for this object crate may look like the following:

   # generated Cargo.toml
   [package]
   name = "adhoc"
   version = "0.1.0"
   edition = "2018"
   
   [lib]
   crate_type = ["cdylib"]
   
   [workspace]
   # empty workspace, so that cargo does not think this crate belong to the
   # firmware which target/ we are in.
   
   [dependencies]
   cortex-m = "0.7"
   stm32f4 = { version = "", features = ["stm32f401"] }
   

   // generated lib.rs
   use stm32f4::stm32f401::Interrupt;
   
   // Only external interrupts need be written here.
   // Exceptions-bound tasks are resolved using the table above.
   
   #[no_mangle]
   pub extern fn rtic_scope_func_EXTI1() -> u8 {
       Interrupt::EXTI1.nr()
   }
   

   After loading the resultant shared library and calling all functions, a IRQ number -> IRQ label -> RTIC task map ("task map") is yielded.

This task map is then used to decorate ITM packets with RTIC-specific data. An absolute timestamp is also calculated for each set of trace packets received. This is done by sampling the time just before the target is reset and applying an offset based upon the trace clock frequency and local/global timestamps received over ITM. This frequency must be set via --tpiu-freq.

This (task map, reset timestamp, trace clock frequency) tuple constitutes the metadata of a trace, and is saved as a header to all trace files.

If the input buffer of the source is filled (i.e. that of a serial device or the internal buffer of a probe) packets will be lost or corrupted. A warning will be printed once before this buffer is overflowed, or if the buffer size cannot be determined.

During source code parsing, an #[app(...)] mod app { ... } is searched for. When parsing the source code, the file is tokenized, and tokens are skipped until #[app(...)] is encountered. This #[app(...)] macro TokenTree::Group is then passed to rtic_syntax::parse2. This limits how an RTIC application can be written to some degree. An example RTIC Scope-compliant application is then:

// other imports...

use rtic::app;
#[app(...)]
mod app {
    // whole application declared here
}

// any other code...

See the examples for more examples of RTIC Scope-compliant applications.

When tracing software tasks:

• a DWT comparator must be effectively consumed. Additionally, the ID of the comparator must be communicated to the backend by writing the value to a watch address.
• When entering/exiting a software task marked for tracing, a u8 (at minimum) must be written to a watch addess; a u32 in the worst case (depending on the number of tracing software tasks¹).