TPT Reverse Engineering Suite

TPT-RES is an open-source toolchain for systematically accelerating Linux hardware driver development through automated capture, binary analysis, specification synthesis, behavioral validation, and compliance certification.

What It Does

Getting a new hardware device working on Linux typically requires weeks of manual reverse engineering. TPT-RES compresses that into a structured, reproducible pipeline:

Hardware Device
    │
    ▼
[DriverScope]  ── eBPF capture of USB/PCI/I2C/SPI bus traffic
    │
    ▼
[FirmwareX]    ── Binary analysis, disassembly, ML pattern recognition
    │
    ▼
[ProtocolForge] ─ HWSpec DSL synthesis, SMT verification, AI import
    │
    ▼
[ShadowDriver] ── Behavioral replay, divergence detection, fault injection
    │
    ▼
[VendorBridge] ── Compliance pipeline, certification, badge generation

Crates

Crate	Purpose	Status
`tcr-core`	Shared types, knowledge graph schema, validation, monitoring	Stable
`tcr-crypto`	Ed25519 signatures, SHA-256 content addressing	Stable
`tcr-storage`	SQLite / PostgreSQL / S3 storage backends	Stable
`tcr-grpc`	gRPC inter-tool communication	Stable
`tcr-ai`	Unified LLM client — OpenRouter & Ollama	Stable
`driverscope`	eBPF capture engine, hardware identification, CLI	Linux only
`driverscope-ui`	GTK4/libadwaita desktop UI	Linux only
`firmwarex`	Binary analysis, disassembly, ONNX ML, AI annotation	Stable
`protocolforge`	HWSpec language, compiler, AI import, LKML patch gen	Stable
`shadowdriver`	Trace replay, divergence detection, fault injection	Stable
`vendorbridge`	Certification pipeline, badge generation, notifications	Stable

AI Integration

TPT-RES includes native LLM support via tcr-ai, with no external service required beyond a running Ollama instance or an OpenRouter API key.

Ollama (local, no API key):

# Pull a model once
ollama pull codellama

# Import a datasheet and generate a HWSpec draft
protocolforge import-ai --text datasheet.txt --provider ollama --model codellama

# Annotate a disassembly function
firmwarex annotate-ai --session <id> --addr 0x1234 --provider ollama

# Generate ONNX training data from driver source
firmwarex generate-training-data --count 500 --provider ollama --model codellama --out training.json

OpenRouter (cloud):

export OPENROUTER_API_KEY=your_key_here
protocolforge import-ai --text datasheet.txt --provider openrouter

Build

Prerequisites

Rust 1.75+ (rustup update stable)
For driverscope and driverscope-ui (Linux only):
- GTK 4.10+ and libadwaita 1.4+ (sudo apt install libgtk-4-dev libadwaita-1-dev)
- Linux kernel headers and clang for eBPF (sudo apt install linux-headers-$(uname -r) clang)

Build all crates

# All platform-independent crates
cargo build --workspace \
  --exclude driverscope \
  --exclude driverscope-ui

# Linux only — full workspace
cargo build --workspace

Run tests

# Cross-platform
cargo test --workspace \
  --exclude driverscope \
  --exclude driverscope-ui

# Full (Linux)
cargo test --workspace

Tools

DriverScope — Hardware Observatory

# Capture USB traffic for 30 seconds
driverscope capture --device 046d:0825 --duration 30

# Export session as self-contained HTML viewer
driverscope export --session <id> --format html --out trace.html

# Analyze and identify hardware
driverscope analyze --session <id>

FirmwareX — Binary Analysis

# Extract and analyze a Windows driver package
firmwarex analyze driver.cab

# AI-assisted function annotation
firmwarex annotate-ai --session <id> --provider ollama

# Generate ONNX training data
firmwarex generate-training-data --count 1000 --out training.json

ProtocolForge — Specification Synthesizer

# Parse and validate a HWSpec file
protocolforge validate device.hwspec

# Compile to C headers
protocolforge compile --target cheader device.hwspec --out include/

# Import from datasheet using AI
protocolforge import-ai --text datasheet.txt --provider ollama

# Generate LKML patch series
protocolforge patch --spec device.hwspec --driver-src ./driver/ --out patches/

VendorBridge — Compliance & Certification

# Run the full compliance pipeline against a driver submission
vendorbridge submit --driver-src ./driver/ --vendor "ACME Corp"

# Generate a Linux driver support badge SVG
vendorbridge badge --vid 0x046d --pid 0x0825 --tier certified > badge.svg

# Subscribe to support change notifications via webhook
vendorbridge watch --vid 0x046d --pid 0x0825 --webhook https://hooks.example.com/notify

# Generate an RSS feed of recent status changes
vendorbridge rss --out feed.xml

VS Code Extension

The vscode-extension/ directory contains a TypeScript extension providing:

HWSpec Explorer sidebar — tree view of all .hwspec files with registers, sequences, and invariants
Register hover — hover over any uppercase register name in C driver code to see its definition from the HWSpec
Commands: TPT-RES: Open in ProtocolForge, TPT-RES: Generate LKML Patch Series, TPT-RES: Import Datasheet with AI

cd vscode-extension
npm install
npm run compile
# Then install via "Install from VSIX" in VS Code

HWSpec Language

HWSpec is a domain-specific language for describing hardware register maps, initialization sequences, and behavioral invariants.

device Webcam {
    vendor_id: 0x046d;
    product_id: 0x0825;

    register CTRL at 0x00 {
        width: 32;
        access: rw;
        reset_value: 0x0000;
        field ENABLE[0:0] { description: "Enable sensor"; }
        field MODE[2:1]   { description: "Operating mode"; }
    }

    sequence init {
        step write CTRL.ENABLE = 1;
        step delay_us 500;
        step read CTRL expect 0x01 mask 0x01;
    }

    invariant "CTRL must be non-zero after init" {
        CTRL != 0;
    }
}

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Shared Infrastructure                │
│  tcr-core · tcr-crypto · tcr-storage · tcr-grpc · tcr-ai│
└─────────────────────────────────────────────────────────┘
         │              │              │
    DriverScope     FirmwareX    ProtocolForge
    (eBPF/GTK4)  (Binary/ML/AI)  (HWSpec/AI)
         │              │              │
         └──────────────┴──────────────┘
                        │
                  ShadowDriver
               (Replay/Validation)
                        │
                  VendorBridge
              (Compliance/Badges)

Storage: SQLite (local cache) · PostgreSQL (shared knowledge graph) · S3 (trace artifacts)

Contributing

See CONTRIBUTING.md.

License

Apache-2.0 — see LICENSE.

tpt-res

Languages