User Guide Debugging and Inspection

Debugging and Inspection

RTICX applications are written with a set of attributes (#[<distro>::app], #[task], #[sw_task], …) that are expanded into a large amount of generated Rust code. The rticx-expand cargo tool expands an application into a plain, compilable Rust file so you can:

• Step-debug with GDB through the generated code (entry point, dispatchers, interrupt handlers, resource proxies) instead of the attribute syntax.
• Inspect and security-vet exactly what the framework generates: no macro magic left between you and the code that actually runs on the device.
• Debug your own compilation passes by dumping the intermediate syntax after each pipeline stage (distribution developers, see Writing Compilation Passes).

Install

cargo install rticx-expand
# or from local source
cargo install --path path/to/rticx-expand

This installs the cargo-rticx-expand binary, invocable as cargo rticx-expand ….

Expand an application

Run from your application crate (the one whose Cargo.toml depends on the distribution):

cargo rticx-expand --example hello_rtic --features swtasks

Like cargo expand, this prints the expanded application to stdout. The output is the complete, compilable file: the expanded module spliced into your original source, so everything around it (#![no_std], #![no_main], imports, statics, and any code after the module) is preserved. Pipe it into a file and it stays executable:

cargo rticx-expand --example hello_rtic --features swtasks > expanded.rs

Merge the expansion into your source (GDB step-debugging)

To debug the generated code with GDB, replace the #[…::app] module in your source file with the expansion:

cargo rticx-expand --example hello_rtic --features swtasks --merge

The tool finds the file containing the #[<distro>::app] module automatically (or use --file if your app module lives in a separate file), keeps the original as <file>.old, and replaces the attribute and its module with the expanded code: all other code in the file (#![no_std], imports, statics, trailing items) stays untouched. The resulting file is a plain Rust file: set your GDB breakpoints anywhere in it and build/flash as usual.

The tool runs cargo check and reports its result, but the merge happens even when checking fails (for example because of an error in your task bodies), the expansion is still useful for inspection. If the macro itself panics or the crate fails to compile before reaching it, no expansion can be produced; the tool prints the cargo output and leaves your sources untouched.

Passes through to the build

Any build flag you would pass to cargo check works:

cargo rticx-expand --bin hello_rtic --target thumbv7m-none-eabi \
    --features swtasks --no-default-features

When multiple targets exist

If the package has several binaries/examples, specify the one to expand with --bin <name> or --example <name>.

Restore your original source

When you are done debugging after a --merge, use:

cargo rticx-expand restore

This replaces the merged file with its .old backup (auto-detected; use --file to disambiguate) and, with --remove-expansions, deletes the expansion directory. You can then rebuild the original RTICX sources.

Per-stage snapshots (pass/distribution developers)

Snapshot the module after every pipeline stage (each compilation pass and the core pass) into a directory of your choice:

cargo rticx-expand --example hello_rtic --features swtasks --expand-passes target/passes

The directory receives one file per stage, named so lexical order equals pipeline order:

target/passes/00_original.rs        # the module exactly as you wrote it
target/passes/01_SoftwareTasks.rs   # after the software tasks pass
target/passes/02_core.rs            # after the core pass (the final expansion)

Now point your diff tool at consecutive files to see exactly what each stage changed: no need to re-run with different pass selections:

diff -u target/passes/00_original.rs target/passes/01_SoftwareTasks.rs   # what the pass did
diff -u target/passes/01_SoftwareTasks.rs target/passes/02_core.rs       # what the core pass did
# or compare the whole chain side by side:
meld target/passes

File	Contents
00_original.rs	The module exactly as received, before any pass
NN_<Pass>.rs	Module state after the pass at pipeline position N
NN_<Pass>_input.rs	State the failing pass received (only when a pass errors)
NN_core.rs	The full, final expansion after the core pass
NN_post_passes.rs	State after all passes (only when core parsing fails)