µScope

Binary trace format for cycle-accurate hardware introspection.

What's in the box

Crate	Path	Description
uscope	crates/uscope/	Transport layer: reader, writer, schema, checkpoints, delta replay, mipmaps
uscope-cpu	crates/uscope-cpu/	CPU protocol library: instruction lifecycle, counters, buffers, performance analysis
uscope-cli	crates/uscope-cli/	CLI for inspecting traces: info, state, timeline, counters, buffers
uscope-mcp	crates/uscope-mcp/	MCP server for AI-assisted trace debugging with Claude
gen-uscope	crates/gen-uscope/	Synthetic trace generator for testing
konata2uscope	crates/konata2uscope/	Converts Konata pipeline logs to µScope

Also:

• Specification (src/) — Transport layer and CPU protocol specs
• C DPI library (dpi/) — Standalone C99 writer for simulator integration

Architecture

┌──────────────────────────────────────────────┐
│ Consumers: uscope-cli, uscope-mcp, Reflex │
└──────────────┬───────────────────────────────┘
│
┌──────────────▼───────────────────────────────┐
│ uscope-cpu: CPU protocol interpretation │
│ CpuTrace, instructions, stages, counters, │
│ buffers, lazy loading, performance analysis │
└──────────────┬───────────────────────────────┘
│
┌──────────────▼───────────────────────────────┐
│ uscope: Transport layer (format only) │
│ Reader, Writer, Schema, Checkpoints, Deltas │
└──────────────────────────────────────────────┘

Quick start

Rust library

[dependencies]
uscope = { path = "crates/uscope" } # transport onlyuscope-cpu = { path = "crates/uscope-cpu" } # + CPU protocol

use uscope_cpu::CpuTrace;letmut trace = CpuTrace::open("trace.uscope")?;println!("{:#?}", trace.file_info());println!("IPC at cycle 100: {}", trace.counter_rate_at(0,100,64));

CLI

# File overview
cargo run --bin uscope-cli -- info trace.uscope
# Buffer state at cycle 50
cargo run --bin uscope-cli -- state trace.uscope --cycle 50
# Instruction lifecycle
cargo run --bin uscope-cli -- timeline trace.uscope --entity 42
# Counter values over a range
cargo run --bin uscope-cli -- counters trace.uscope --range 100:200
# Buffer occupancy with pointer positions
cargo run --bin uscope-cli -- buffers trace.uscope --cycle 50
# JSON output for scripting
cargo run --bin uscope-cli -- info trace.uscope --json

MCP server (for Claude)

# Start MCP server for a trace file
cargo run --bin uscope-mcp -- --trace trace.uscope
# Claude Code configuration (.claude/settings.json):
{
"mcpServers": {
"uscope": {
"command": "cargo",
"args": ["run", "--bin", "uscope-mcp", "--", "--trace", "/path/to/trace.uscope"]
}
}
}

MCP tools available to Claude:

• file_info — trace header, schema, metadata
• state_at_cycle — buffer contents at a specific cycle
• entity_timeline — instruction lifecycle (stages, retire/flush)
• counter_values — counter data over a range
• buffer_occupancy — buffer fill level with pointer positions
• analyze_performance — IPC, stall analysis, bottleneck identification

C DPI

make -C dpi
# link with -luscope_dpi

konata2uscope

cargo run -p konata2uscope -- trace.log -o trace.uscope

Documentation

Built with mdbook:

mdbook serve

Tests

cargo test --workspace # All Rust tests
make -C dpi test # C library test (writes trace, verified by Rust reader)

License

• Code: Apache-2.0
• Specification text: CC-BY-4.0