rvdbg User Guide
rvdbg uses one rvdbg.toml to flash, debug and inspect rustvisor boards. With a Lauterbach probe it uses TRACE32 PowerView; with StellarLINK it runs openocd-stellar as a separate process. Build firmware with your project’s own build system: rvdbg deploys existing images and helps inspect the target.
This guide covers Apple Silicon macOS and Linux x86_64/aarch64 hosts. The board defaults generated by rvdbg init target SR6P6. Before using another board, check scripts, core names, memory access ports and OTP ranges.
Start with your task
| Task | Read | Expected outcome |
|---|---|---|
| First use | Quick start | Install dependencies, configure, flash and inspect |
| Change images, probes or cores | Configuration | Identify effective images, backend and ports |
| Update code or symbols | Flashing and verification | Choose flash/load and handle multiple images |
| Breakpoints and stepping | Debugging | Connect an IDE/GDB and understand target state changes |
| Diagnose a running program | Inspection | Inspect PC, faults, memory, clocks and acceptance conditions |
| Logs and packets | RTT and FDX | Locate buffers and choose a transport |
| Scripts and agents | Automation | Interpret JSON, exit codes and session boundaries |
| Failed operations | Troubleshooting | Find the next check from the symptom |
Follow the table in order on your first visit; use task pages directly afterwards. Standard Markdown relative links work in GitHub and Obsidian. The mdBook website adds “Referenced by” sections to show which pages depend on the current page.
Backend differences
| Capability | TRACE32 | StellarLINK / OpenOCD |
|---|---|---|
| Flash, verify, status, halt and resume | Supported | Supported |
| IDEs | VS Code and RustRover/LSP4IJ over DAP | VS Code/Cortex-Debug and GDB |
| Ordinary RAM, RTT and FDX | Runtime access through AD: | Runtime access through MEM-AP |
| Debug symbols | rvdbg load | GDB reads the ELF |
| PER register names | reg, watch | Use addresses or check files instead |
| PRACTICE | eval, cmd, do | Unsupported |
| Trace export | trace, fault --trace | Unsupported |
| Clock diagram | clock --html | Text/JSON tree only |
Shared command names do not imply that every option works on both backends. See configuration for selection and individual task pages for restrictions.
Understand what an operation changes
Inspection commands such as status, mem, fault, verify and check without --halt do not automatically reset or halt the target to obtain a value. Some register reads will therefore fail. Distinguish ordinary RAM from MMIO with read side effects; see inspection.
flash writes Flash and resets the target; reset resets and halts it. halt, go and run-until change execution state. load loads symbols and resumes when necessary. IDE connection can also execute board reset hooks; see debugging.
ram --write changes target RAM. FDX sends can trigger firmware actions. cmd and do depend on the PRACTICE content and can perform arbitrary target operations.
Use rvdbg --help and rvdbg <command> --help for full arguments. This guide explains workflows and interpretation; consult your installed version’s help and rvdbg init output for defaults. See maintaining this guide for local previews and link conventions.