tpt-embedded-tools

Host-side verification, simulation, and analysis suite for tpt-embedded-core.

Overview

tpt-embedded-tools provides CLI-native, CI-first tooling for the tpt-embedded-core no_std ESP32 firmware. While tpt-basestation serves end-users and tpt-embedded-core provides mathematically verified firmware, this suite enforces safety guarantees from the first line of code to deployment.

Architecture

tpt-embedded-tools/
├── libs/
│   ├── tpt-e-elf-parser/        # ELF/DWARF parsing for both Xtensa & RISC-V
│   ├── tpt-e-trace-codec/       # Binary wire schema for structured runtime traces
│   └── tpt-e-esp32-model/       # ESP32 peripheral/register data models
├── crates/
│   ├── tpt-e-simulator/         # Instruction-accurate ESP32 simulator
│   ├── tpt-e-probe/             # Host-side structured trace viewer/verifier
│   ├── tpt-e-stack-analyzer/    # Worst-case stack depth verifier
│   ├── tpt-e-hil-framework/     # Automated hardware-in-the-loop testing
│   ├── tpt-e-peripheral-prover/ # TRM-based register access verifier
│   ├── tpt-e-power-profiler/    # Code-to-physical-power correlator
│   └── tpt-e-invariant-checker/ # Cross-crate invariant static analyzer
└── .github/workflows/           # CI pipelines

Current Status

Status key: 🟢 MVP-complete (real logic, exercised by tests) · 🟡 partially functional (a real code path exists but with known, documented gaps) · 🔴 scaffold/stub only (no functional implementation yet).

Crate	Status	Description
tpt-e-elf-parser	🟡	ELF/header/symbol parsing + DWARF extraction work; disassembly-based call-graph edges are not yet built (edges are always empty)
tpt-e-trace-codec	🟢	Binary wire schema for runtime traces, with round-trip encode/decode
tpt-e-esp32-model	🟢	ESP32 peripheral/register models (timer, GPIO, UART)
tpt-e-simulator	🔴	Interpreter scaffold (fetch/trace loop, memory, peripherals) is wired up, but execute_xtensa/execute_riscv do not yet decode or execute real instructions
tpt-e-probe	🟡	File-based trace ingestion and invariant verification work; serial ingestion is not yet implemented
tpt-e-stack-analyzer	🟢	Worst-case stack depth analysis over a call graph, incl. recursion/ISR handling — most-tested crate; dynamic-dispatch detection is not yet implemented (see crate docs)
tpt-e-hil-framework	🟡	Mock-transport HIL test orchestration works in CI; real hardware (espflash) mode is not yet implemented
tpt-e-peripheral-prover	🔴	CLI scaffold only — register verification is not yet implemented
tpt-e-power-profiler	🟡	Power CSV ingestion and flat energy reports work; trace/power timestamp correlation and per-function breakdown are not yet implemented
tpt-e-invariant-checker	🟡	Recursive workspace scan with a simple textual DMA/sleep heuristic; not real static/ownership analysis yet

Quick Start

# Build all crates
cargo build --workspace

# Run all tests
cargo test --workspace

# Run clippy
cargo clippy --workspace -- -D warnings

# Check formatting
cargo fmt --all -- --check

Design Decisions

Simulator Backend

The simulator uses a pure-Rust interpreter behind an ExecutionBackend trait, enabling a future QEMU-FFI backend to be added without rearchitecting trace consumers.

Dual-ISA Strategy

Both Xtensa and RISC-V (RV32IMC) are supported via a shared Isa trait/enum used by tpt-e-elf-parser, tpt-e-simulator, and tpt-e-stack-analyzer.

ELF/DWARF Parsing

We use the goblin crate for ELF parsing, providing robust support for both EM_XTENSA and EM_RISCV architectures.

HIL Framework

Hardware-in-the-loop testing uses espflash for flash/reset orchestration, mirroring tpt-basestation's existing serial transport pattern.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.