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.

Copyright 2026 TPT Solutions