Document public readiness and add regression helpers

Author: t81dev

Makefile

@@ -79,6 +79,9 @@ $(BIN_DIR)/test_dynamic_detection: tests/test_dynamic_detection.c
 $(BIN_DIR)/test_phase10: tests/test_phase10.c $(SRC_DIR)/tfmbs_driver_mock.c $(SRC_DIR)/fabric_emulator.c
 	$(CC) $(CFLAGS) -I$(SRC_DIR) -o $@ $^
 
+$(BIN_DIR)/test_dma_driver: tests/test_dma_driver.c $(BIN_DIR)/libtfmbs_device$(SHLIB_EXT)
+	$(CC) $(CFLAGS) -o $@ $< -L$(BIN_DIR) -ltfmbs_device
+
 $(BIN_DIR)/test_multi_tile: tests/test_multi_tile.c $(BIN_DIR)/libtfmbs_device$(SHLIB_EXT)
 	$(CC) $(CFLAGS) -o $@ $< -L$(BIN_DIR) -ltfmbs_device
 
@@ -158,4 +161,4 @@ clean:
 	rm -rf $(PY_DIR)/build
 	rm -f tests/*.hex tests/*.txt tests/*.vvp tests/*.vcd
 
-.PHONY: all directories clean python_ext hw_sim run_sim verilate synth verify_pt5 test_bridge benchmark_hw profile
+.PHONY: all directories clean python_ext hw_sim run_sim verilate synth verify_pt5 test_bridge benchmark_hw profile

README.md

@@ -21,8 +21,20 @@ make all
 
 # 3. Explore the authoritative metrics
 cat BENCHMARKS.md
+
+# 4. Compile the Tfmbs MLIR plugin and run the regression guard
+./tools/run_tfmbs_regression.sh
 ```
 
+`tools/run_tfmbs_regression.sh` automates the `cmake -B build -G Ninja` / `ninja -C build tfmbs_plugin` flow, locates `mlir-opt` (defaults to `../llvm-project/build-shared/bin/mlir-opt`), and then runs `tests/mlir/run_tfmbs_to_linalg.py` with the built plugin; set `LLVM_DIR`, `MLIR_DIR`, `BUILD_DIR`, `MLIR_OPT`, or `TFMBS_PLUGIN` before invoking the script to override the defaults so your environment mirrors CI.
+
+## 📣 Public Readiness
+
+Before the hardware racks (XC7Z020/XC7Z045) return, reference [`docs/PUBLIC_READINESS.md`] for:
+- The public-facing story, compiler/telemetry workflow, and measurable evidence you can highlight in talks or write-ups.  
+- The offline tooling (`tools/run_tfmbs_regression.sh`, `tools/run_hw_dma_telemetry.sh`, `tools/capture_dma_telemetry.py`) that keeps DMA/telemetry, regression, and dashboard validation running without the FPGA.  
+- Clear outreach notes that list what’s ready today and the remaining hardware verification tasks waiting on the FPGA testbeds.
+
 ---
 
 ## 🏗️ Architecture & Vision
@@ -89,6 +101,8 @@ The project has completed **Phase 25 (Simulated RDMA Multi-Node Orchestration)**
 - **Operator fusion regression:** The CI job additionally runs `tests/mlir/run_tfmbs_to_linalg.py --mlir=tests/mlir/tfmbs_fusion.mlir` so the new `tfmbs-fuse` pass can combine sequential GEMV kernels before lowering and still emit `linalg.matmul`.
 - **Fusion dashboard:** Use `pytfmbs.AdaptiveRuntimeAgent.save_history("logs/adaptive_history.json")` after running workloads, then run `tools/adaptive_dashboard.py` to compare `fusion_order`/`fusion_sparsity` against the compiler hints stored in `tests/mlir/torch_tfmbs.mlir`.
 
+**Track status:** Track B (compiler & MLIR) is now fully operational—dialect, passes, lit guard, regression wiring, and the dashboard loop all run off the shared LLVM/MLIR build—while Track A awaits access to the XC7Z020/XC7Z045 boards so the FPGA verification checklist and synthesis docs can be filled in.
+
 ---
 
 ## 📝 Discrepancies & Notes

docs/FPGA_VERIFICATION_CHECKLIST.md

@@ -24,14 +24,15 @@ Based on the ROADMAP Phase 22 callout in `docs/ROADMAP.md` (Hardware Sovereignty
    - **DMA smoke test:** after flashing, run `tests/test_dma_driver` (with `TFMBS_DMA_RING` env var set to the desired queue depth) and the mock driver’s submit CLI; expect each `TFMBS_IOC_SUBMIT_DMA` call to log a descriptor completion before proceeding.
 
 ## 3. Hardware-in-the-Loop Validation
-- **Driver validation:** run `tests/test_dma_driver.c` (or similar) using the real kernel module or the mock driver wrapped around the hardware to ensure `TFMBS_IOC_SUBMIT_DMA` returns 0 and the ring does not overflow under high load.
-- **Telemetry capture:** execute standard workloads once the FPGA is connected, capturing metrics that match `tfmbs_ioc_metrics_t` fields (zero_skips, residency hits/misses, fallback/offload counts). Compare these against emulator baselines to verify accuracy.
+- **Driver validation:** run `tests/test_dma_driver.c` (or similar) using the real kernel module or the mock driver wrapped around the hardware to ensure `TFMBS_IOC_SUBMIT_DMA` returns 0 and the ring does not overflow under high load. While the FPGA racks are still offline, use `tools/run_hw_dma_telemetry.sh` to build the Verilator `fabric_tb`, run `bin/test_dma_driver`, and automatically capture telemetry via `tools/capture_dma_telemetry.py`.
+- **Telemetry capture:** execute standard workloads once the FPGA is connected, capturing metrics that match `tfmbs_ioc_metrics_t` fields (zero_skips, residency hits/misses, fallback/offload counts). Compare these against emulator baselines to verify accuracy. The offline helper already emits `logs/adaptive_history_dma.json` and invokes `tools/adaptive_dashboard.py` so the telemetry format is ready for the dashboard once the real hardware is attached.
 - **Benchmarks:** use existing benchmark scripts (e.g., anything under `benchmarks/` or `tests/`) to load 7B+ layers and run the DMA-enabled kernels, measuring throughput and energy to confirm the >50× efficiency target for Q3 2026 in the roadmap (`docs/ROADMAP.md:188-190`).
 
 ## 4. Acceptance Criteria & Documentation
 - Define pass/fail thresholds: ring buffer throughput (descriptor/s), DMA latency, telemetry fidelity, default tile count (4 tiles × 15 lanes) as in the mock driver.
 - Log results in a running report (e.g., `docs/hardware_verification_report.md`) with sections for synthesis, driver integration, telemetry comparison, and benchmark output.
 - Update `docs/ROADMAP.md` to note Phase 10 moving past “Mock” once the hardware driver demonstrates correct IOCTL/DMA behavior; cite the verification report.
+- Keep the public readiness narrative in sync with `docs/PUBLIC_READINESS.md` so outreach materials highlight both the ready software stack and the hardware steps still gated on the XC7Z020/XC7Z045 boards.
 
 ## 5. Next Steps (after verification)
 1. Share telemetry findings with the compiler/MLIR track so they can refine sensitivity heuristics based on hardware behavior (`docs/ROADMAP.md:156-170`).

docs/PUBLIC_READINESS.md

@@ -0,0 +1,32 @@
+# Public Readiness Snapshot
+
+This status note is designed to help anyone presenting Ternary Fabric publicly while the XC7Z020/XC7Z045 hardware remains unavailable. It bundles the public-facing story, compiler/telemetry workflow, measurable evidence, and outreach guidance so you can speak clearly about what’s ready today and what remains gated on silicon access.
+
+## 1. Public Story
+- **Architecture & Vision:** Reference the README/roadmap (Phases 0–26) for the semantic execution substrate, zero-skip, PT‑5 packing, and multi-fabric orchestration narrative. The README now covers how to build, run the `test_phase21` verification, and view benchmarks, while the roadmap documents Phases 0–27 plus the Track A/B/C splits. Currents status:
+  - Software stack is in Phase 25 (distributed orchestration) and Phase 26 (adaptive runtime) operational mode.  
+  - Compiler/MLIR stack (Phase 23) is fully built and regression-tested via shared LLVM/MLIR builds and `tests/mlir/run_tfmbs_to_linalg.py`.  
+  - Hardware proof is blocked on XC7Z020/XC7Z045 access; see `docs/FPGA_VERIFICATION_CHECKLIST.md` and `docs/hardware_verification_report.md` for the outstanding synthesis/driver/execution checklist that will kick off once the boards return.
+- **Toolkit readiness:** Documented Quick Start now includes the `tools/run_tfmbs_regression.sh` helper that configures Ninja, builds `tfmbs_plugin`, runs `mlir-opt`, and validates the lowering pipeline with the telemetry-rich MLIR fixtures. We also ship `tools/run_hw_dma_telemetry.sh` + `tools/capture_dma_telemetry.py` so the DMA/telemetry story can be exercised locally via Verilator and the adaptive dashboard before the physical FPGA is available.
+
+## 2. Compiler & Telemetry Regression Workflow
+- **TableGen & plugin:** `src/mlir/TfmbsOps.td` + generated headers define the dialect, and `TfmbsPasses.cpp` implements fusion + lowering. `CMakeLists.txt` produces `libtfmbs_dialect.*` / `libtfmbs_plugin.*`, and `tools/run_tfmbs_regression.sh` automatically discovers `mlir-opt` and runs `tests/mlir/run_tfmbs_to_linalg.py`.  
+- **Regression gate:** `tests/mlir/run_tfmbs_to_linalg.py` ensures `linalg.matmul` appears while `tfmbs.gemv`/`tfmbs.fused_gemv` vanish after the pipeline. CI + local helpers now iterate over `tests/mlir/tfmbs_*fusion*.mlir` plus `tests/mlir/torch_tfmbs.mlir` so telemetry attributes (`fusion_order`, `fusion_sparsity`, `tile_mask`) stay aligned.  
+- **Adaptive dashboard:** Runtime logs from `pytfmbs.AdaptiveRuntimeAgent.save_history(...)` are compared to compiler hints via `tools/adaptive_dashboard.py`. `tools/run_hw_dma_telemetry.sh` (which builds `hw_sim`, runs `bin/test_dma_driver`, captures metrics via `tools/capture_dma_telemetry.py`, and runs the dashboard) mirrors the telemetry contract expected from real hardware.
+
+## 3. Measurable Evidence
+- **Benchmarks:** `BENCHMARKS.md` summarizes phase-specific throughput (aggregated fabric GOPS, zero-skip reduction, PT-5 efficiency). When new simulation/driver logs are available, drop them into `logs/` (e.g., `logs/adaptive_history_dma.json`) and highlight throughput/latency columns from `benchmarks/` scripts.  
+- **Telemetry logs:** The helper tools now produce `logs/adaptive_history_dma.json` (Verilator) to show fusion order + sparsity metrics; once the FPGA runs, place the real hardware logs in `logs/` with timestamps for future comparisons.  
+- **Dashboard output:** After running `tools/adaptive_dashboard.py`, capture the console output and include it alongside the telemetry log to prove compiler/runtime agreement. Mention these artifacts when presenting the project to show you already validate the telemetry pipeline even before the hardware reconnects.
+
+## 4. Outreach Notes (Ready vs Waiting on XC7Z020/XC7Z045)
+- ✅ **Ready today**: Distributed multi-fabric orchestration (Phase 25) via simulation; compiler dialect/passes/regression tooling (Phase 23); adaptive runtime + telemetry dashboard (Phase 26); DMA mock driver + `libtfmbs_device.so`; tooling for capturing telemetry during Verilator runs.  
+- ⏳ **Waiting on hardware**: RTL synthesis + bitstream programming for XC7Z020/XC7Z045; real `/dev/tfmbs` IOCTL/DMA validation; hardware telemetry vs emulator parity; >50× efficiency proof on physical boards. These steps remain blocked until the FCX FPGA racks return.  
+- **Outreach story:** Frame the project as “software-ready with hardware verification queued” and point audiences to `docs/FPGA_VERIFICATION_CHECKLIST.md`/`docs/hardware_verification_report.md` for the precise checklist. Mention that the DMA/telemetry flow can already be exercised via `tools/run_hw_dma_telemetry.sh` while the physical testbeds remain offline.
+
+## Links
+- [README Quick Start](../README.md)  
+- [Roadmap (Track A/B/C)](ROADMAP.md)  
+- [FPGA Verification Checklist](FPGA_VERIFICATION_CHECKLIST.md)  
+- [Hardware Verification Report](hardware_verification_report.md)  
+- [Compiler Track Plan](compiler_track_plan.md)

docs/ROADMAP.md

@@ -163,10 +163,12 @@ Establishing TFMBS as a first-class citizen in the MLIR/LLVM ecosystem to enable
   - **Torch/ONNX fixtures:** `tools/torch_to_tfmbs.py` converts exported Torch/ONNX graphs into `tests/mlir/torch_tfmbs.mlir` that already carries `telemetry` metadata, which downstream passes lower into `linalg.matmul` with the same hints.
   - `pytfmbs.TFMBSLinear.telemetry_hint` mirrors the same dictionary (layer name, sparsity, tile mask) so Python front ends can emit the compile-time hints that the Adaptive Runtime Agent consumes later.
   - **CI regression:** GitHub Actions clones `llvm/llvm-project`, builds shared MLIR, runs `tools/torch_to_tfmbs.py`, and executes `tests/mlir/run_tfmbs_to_linalg.py` with the dialect plugin to guarantee `linalg.matmul` is present before every merge.
+  - **Lit guard:** The new `ninja -C build check-tfmbs` target runs the fusion/multi-fusion fixtures (`tests/mlir/tfmbs_fusion.mlir`, `tests/mlir/tfmbs_multi_fusion.mlir`) via the `run_tfmbs_to_linalg.py` helper, so CI now captures telemetry/fusion regressions immediately after the plugin build.
   - **Operator Fusion:** `TfmbsFusionPass` now collapses telemetry-aligned GEMV pairs into `tfmbs.fused_gemv`, the fusion pass is exercised by `tests/mlir/tfmbs_fusion.mlir`, and CI runs the fusion+lowering pipeline so fused kernels still output `linalg.matmul`.
   - **Multi-stage coverage:** CI also runs `tests/mlir/tfmbs_multi_fusion.mlir` to show the fusion pass covers longer pipelines while preserving telemetry hints.
   - **Adaptive dashboard:** `pytfmbs.AdaptiveRuntimeAgent` logs fusion telemetry so `tools/adaptive_dashboard.py` can compare runtime fusion_order/fusion_sparsity trends against the compiler hints for Phase 26 scheduling.
-  - **Compiler Plan:** See `docs/compiler_track_plan.md` for the current MLIR dialect status, TableGen targets, and next work items while hardware verification is pending.
+- **Compiler Plan:** See `docs/compiler_track_plan.md` for the current MLIR dialect status, generated TableGen headers, pass/plugin paths, and regression/dashboard scripts that keep telemetry hints aligned while the FPGA verification workqueue resumes.
+- **Track status:** All compiler deliverables for Phase 23 are in place (dialect, passes, CI, dashboard), so Track B is fully ready to supply telemetry hints once Track A’s FPGA verification (Phase 22/10) resumes on the XC7Z020/XC7Z045 boards.
 
 **Phase 26: Dynamic Semantic Scheduling & Precision Adaptation** ✅
 Using real-time telemetry to adjust execution precision and semantic depth based on model layer sensitivity.