# probe-rs/probe-rs architecture

> Architecture diagram of the GitHub repository probe-rs/probe-rs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/probe-rs/probe-rs
- Repository: https://github.com/probe-rs/probe-rs

## Overview

##### Project type and purpose
- This is a multi-crate Rust workspace providing a modern embedded-debugging toolkit (“probe-rs”) and a suite of companion command-line tools (cargo-flash, cargo-embed, GDB/DAP servers, etc.).
- The core library (“probe-rs”) exposes abstractions for connecting to probes, establishing debug sessions, halting/stepping cores, reading/writing memory, flashing, and trace. Additional crates (probe-rs-debug, probe-rs-target, probe-rs-mi) extend debug-info parsing, target definitions, and MI (Machine Interface) support. The “probe-rs-tools” crate implements the end-user CLIs and servers (DAP, GDB).

##### Top-level component breakdown
A. Workspace manager
- Cargo workspace (root Cargo.toml) aggregates all crates.
B. Core library (“probe-rs”)
- src/lib.rs & submodules:
- probe abstraction (open, connect, list probes)
- session & core (halt/run/step, memory access)
- flashing (builder, loader, algorithm)
- architecture modules (ARM, RISC-V, Xtensa)
- adapters for actual hardware probes (CMSIS-DAP, ST-Link, JLink, FTDI, Blackmagic, ESP-USB-JTAG, WLink, FakeProbe)
- Target definitions (.yaml under probe-rs/targets) loaded at runtime.
C. Support crates
1. probe-rs-debug: parse DWARF, unwind stacks, semihosting, RTT snapshots
2. probe-rs-target: structures & serialization for target pack data
3. probe-rs-mi: MI protocol support (GDB/IDE machine interface)
4. target-gen: CMSIS-Pack processor/flash-algorithm generator for YAML target files
5. rtthost: host side of RTT protocol
6. smoke-tester: integration tests (assembly, stepping, coredumps)
7. xtask: workspace maintenance tasks
D. End-user tools (probe-rs-tools/src/bin)
- cargo-flash, cargo-embed, probe-rs CLI, GDB server, DAP server, plus their subcommands and RPC layers.

##### How components interact
- User invokes a CLI tool (cargo-flash / cargo-embed / probe-rs).
→ CLI parses command args, constructs a session via probe-rs library
→ Library uses adapter crates to open a debug probe (USB/JTAG)
→ Library loads target definition (YAML) via probe-rs-target/target-gen
→ Library executes flash algorithm, memory reads/writes, core control
- GDB server & DAP server:
→ Listen on TCP or stdio, process GDB/DAP protocol messages
→ Marshal messages to probe-rs-mi (MI) or to library functions directly
→ Return responses/events back to client IDE/GDB
- probe-rs-debug & rtthost:
→ parse ELF/DWARF for backtraces, semihosting, RTT data
→ coordinate with library & CLI for debug-info-dependent features

##### Architectural patterns & principles
- Modular crate-based design (workspace + multiple crates).
- Adapter pattern: each hardware probe implements a common Probe trait.
- Strategy/Builder pattern: flashing pipeline built step by step.
- Protocol layers: RPC modules for MI, DAP, GDB encapsulate transport (websocket, TCP, stdio).
- Separation of concerns: core library (logic), adapters (hardware), tools (user interface), target definitions (data files).

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Workspace"
        WS[("Cargo Workspace")]:::workspace
    end
    click WS "https://github.com/probe-rs/probe-rs/blob/master/Cargo.toml"

    subgraph "Core Library\nprobe-rs"
        CoreLib[/probe-rs/src/lib.rs/]:::coreLib
        CoreAbst["Core Abstractions\n(session, memory)"]:::coreLib
        Flash["Flashing Pipeline"]:::coreLib
        ProbeTrait["Probe Trait"]:::coreLib
    end
    click CoreLib "https://github.com/probe-rs/probe-rs/blob/master/probe-rs/src/lib.rs"
    click CoreAbst "https://github.com/probe-rs/probe-rs/blob/master/probe-rs/src/core.rs"
    click Flash "https://github.com/probe-rs/probe-rs/tree/master/probe-rs/src/flashing/"
    click ProbeTrait "https://github.com/probe-rs/probe-rs/blob/master/probe-rs/src/probe.rs"

    subgraph "Adapters"
        CMSIS["CMSIS-DAP"]:::adapter
        STLINK["ST-Link"]:::adapter
        JLINK["JLink"]:::adapter
        FTDI["FTDI"]:::adapter
        BMG["Blackmagic"]:::adapter
        ESPUSB["ESP-USB-JTAG"]:::adapter
        WLINK["WLink"]:::adapter
        FAKE["FakeProbe"]:::adapter
    end
    click CMSIS "https://github.com/probe-rs/probe-rs/tree/master/probe-rs/src/probe/cmsisdap/"
    click STLINK "https://github.com/probe-rs/probe-rs/tree/master/probe-rs/src/probe/stlink/"
    click JLINK "https://github.com/probe-rs/probe-rs/tree/master/probe-rs/src/probe/jlink/"
    click FTDI "https://github.com/probe-rs/probe-rs/tree/master/probe-rs/src/probe/ftdi/"
    click BMG "https://github.com/probe-rs/probe-rs/tree/master/probe-rs/src/probe/blackmagic/"
    click ESPUSB "https://github.com/probe-rs/probe-rs/tree/master/probe-rs/src/probe/espusbjtag/"
    click WLINK "https://github.com/probe-rs/probe-rs/tree/master/probe-rs/src/probe/wlink/"
    click FAKE "https://github.com/probe-rs/probe-rs/blob/master/probe-rs/src/probe/fake_probe.rs"

    subgraph "Architecture Modules"
        ARM["ARM"]:::architecture
        RISCV["RISC-V"]:::architecture
        XTENSA["Xtensa"]:::architecture
    end
    click ARM "https://github.com/probe-rs/probe-rs/tree/master/probe-rs/src/architecture/arm/"
    click RISCV "https://github.com/probe-rs/probe-rs/tree/master/probe-rs/src/architecture/riscv/"
    click XTENSA "https://github.com/probe-rs/probe-rs/tree/master/probe-rs/src/architecture/xtensa/"

    Data["Target Definitions\n(YAML)"]:::data
    click Data "https://github.com/probe-rs/probe-rs/tree/master/probe-rs/targets/"

    WS --> CoreLib
    CoreLib --> CoreAbst
    CoreLib --> Flash
    CoreLib --> ProbeTrait
    ProbeTrait --> CMSIS
    ProbeTrait --> STLINK
    ProbeTrait --> JLINK
    ProbeTrait --> FTDI
    ProbeTrait --> BMG
    ProbeTrait --> ESPUSB
    ProbeTrait --> WLINK
    ProbeTrait --> FAKE
    CoreLib --> ARM
    CoreLib --> RISCV
    CoreLib --> XTENSA
    CoreLib --> Data

    subgraph "Support Crates"
        Debug["probe-rs-debug"]:::support
        TargetC["probe-rs-target"]:::support
        MI["probe-rs-mi"]:::support
        TargetGen["target-gen"]:::support
        RTTH["rtthost"]:::support
        Smoke["smoke-tester"]:::support
        XTask["xtask"]:::support
    end
    click Debug "https://github.com/probe-rs/probe-rs/blob/master/probe-rs-debug/src/lib.rs"
    click TargetC "https://github.com/probe-rs/probe-rs/blob/master/probe-rs-target/src/lib.rs"
    click MI "https://github.com/probe-rs/probe-rs/blob/master/probe-rs-mi/src/lib.rs"
    click TargetGen "https://github.com/probe-rs/probe-rs/blob/master/target-gen/src/main.rs"
    click RTTH "https://github.com/probe-rs/probe-rs/blob/master/rtthost/src/main.rs"
    click Smoke "https://github.com/probe-rs/probe-rs/blob/master/smoke-tester/src/main.rs"
    click XTask "https://github.com/probe-rs/probe-rs/blob/master/xtask/src/main.rs"

    subgraph "End-User Tools\nprobe-rs-tools"
        CLI1["cargo-flash"]:::cli
        CLI2["cargo-embed"]:::cli
        CLI3["probe-rs CLI"]:::cli
        GDBsrv["GDB Server"]:::server
        DAPsrv["DAP Server"]:::server
    end
    click CLI1 "https://github.com/probe-rs/probe-rs/blob/master/probe-rs-tools/src/bin/cargo-flash.rs"
    click CLI2 "https://github.com/probe-rs/probe-rs/blob/master/probe-rs-tools/src/bin/cargo-embed.rs"
    click CLI3 "https://github.com/probe-rs/probe-rs/tree/master/probe-rs-tools/src/bin/probe-rs/"
    click GDBsrv "https://github.com/probe-rs/probe-rs/tree/master/probe-rs-tools/src/bin/probe-rs/cmd/gdb_server/"
    click DAPsrv "https://github.com/probe-rs/probe-rs/tree/master/probe-rs-tools/src/bin/probe-rs/cmd/dap_server/"

    CLI1 --> CoreLib
    CLI2 --> CoreLib
    CLI3 --> CoreLib
    CLI3 --> Debug
    CLI3 --> RTTH
    GDBsrv --> MI
    DAPsrv --> MI
    MI --> CoreLib

    classDef workspace fill:#f9f,stroke:#333,stroke-width:1px;
    classDef coreLib fill:#bbf,stroke:#333,stroke-width:1px,shape:rounded;
    classDef adapter fill:#fea,stroke:#333,stroke-width:1px;
    classDef architecture fill:#afa,stroke:#333,stroke-width:1px;
    classDef data fill:#fffacd,stroke:#333,stroke-width:1px,shape:cylinder;
    classDef support fill:#ddf,stroke:#333,stroke-width:1px,shape:rounded;
    classDef cli fill:#cff,stroke:#333,stroke-width:1px;
    classDef server fill:#fcf,stroke:#333,stroke-width:1px;
```
