Merge pull request #24 from t81dev/documentation-update-phase15-16200136749763687686

Update documentation to Phase 15 status

Author: t81dev

README.md

@@ -62,7 +62,7 @@ export FABRIC_SHORT_CIRCUIT=1
 LD_PRELOAD=./libtfmbs_intercept.so ./llama-cli -m model.gguf
 ```
 
-### Telemetry Insights (Phase 9)
+### Telemetry Insights
 ```text
 [TFMBS-Telemetry] GEMV Completed
   - Zero-Skips: 172,401 (65.8% reduction in total operations)
@@ -74,10 +74,11 @@ LD_PRELOAD=./libtfmbs_intercept.so ./llama-cli -m model.gguf
 
 ## 🏗️ Project State & Architecture
 
-The project is currently in **Phase 11**, offering a high-fidelity software emulator and **ASIC-ready synthesizable RTL**.
+The project is currently in **Phase 15**, offering deep integration with PyTorch and GGUF, alongside native hardware acceleration for advanced kernels.
 
-*   **Software Layer (Emulation):** Multi-tile scaling, kernel-style IOCTLs, LRU-based paging, and transparent `LD_PRELOAD` interposer.
-*   **Hardware Layer (RTL):** Parameterized Multi-Tile SIMD architecture with AXI4-Lite control plane and Zero-Skip TPE lanes.
+*   **Framework Layer:** Transparent PyTorch integration via `TFMBSLinear`, supporting automatic quantization and weight residency.
+*   **Software Layer (Emulation):** High-fidelity multi-tile emulator with IOCTL support (`/dev/tfmbs`), GGUF v2/v3 parsing, and transparent `LD_PRELOAD` interposer.
+*   **Hardware Layer (RTL):** ASIC-ready synthesizable RTL with native support for T-GEMM, T-CONV3D, T-LSTM, and T-Attention kernels.
 
 | Configuration | Lanes | Clock | Throughput (Peak) |
 | :--- | :--- | :--- | :--- |

TFMBS_DEVICE_SPEC.md

@@ -40,46 +40,37 @@ The primary workload for llama.cpp acceleration.
 - **Semantics:** Performs $y = Wx$, where $W$ is ternary, $x$ is typically binary/FP (quantized to ternary by the fabric if necessary), and $y$ is binary (accumulated results).
 
 ### 3.2 Async vs Sync
-- The interface supports both synchronous (blocking) and asynchronous (polling/interrupt) execution.
-- `fabric_exec_gemv` initiates the operation.
-- Completion is signalled via a status register or callback.
+- The interface supports both synchronous (blocking) and asynchronous (polling/interrupt) execution via IOCTL.
+- `TFMBS_IOC_SUBMIT` initiates the operation using a TFD.
+- `TFMBS_IOC_WAIT` blocks until completion.
+- Completion can also be polled via the `DONE` bit in the control register.
 
 ---
 
-## 4. Host API (C ABI)
+## 4. Host API (UAPI / IOCTL)
 
-The following functions define the standard interface for the Fabric Device:
+The normative interface for the Fabric Device is mediated via the `/dev/tfmbs` character device using the following IOCTLs:
 
 ```c
 /**
- * Allocate memory in the Fabric pool.
- * Returns a handle/pointer to Fabric-resident memory.
+ * Submit a Ternary Frame Descriptor for execution.
+ * Returns a unique task_id.
  */
-void* fabric_alloc(size_t size);
+#define TFMBS_IOC_SUBMIT _IOW(TFMBS_IOC_MAGIC, 1, tfmbs_tfd_t)
 
 /**
- * Free memory in the Fabric pool.
+ * Block until the specified task is complete.
  */
-void fabric_free(void* ptr);
+#define TFMBS_IOC_WAIT _IOW(TFMBS_IOC_MAGIC, 2, uint32_t)
 
 /**
- * Copy data from Host RAM to Fabric Memory.
- * Handles automatic PT-5 packing if requested.
+ * Submit a GEMV operation directly (Optimized path).
  */
-int fabric_memcpy_to(void* dest_fabric, const void* src_host, size_t size, int pack_pt5);
-
-/**
- * Copy data from Fabric Memory to Host RAM.
- * Handles automatic PT-5 unpacking if requested.
- */
-int fabric_memcpy_from(void* dest_host, const void* src_fabric, size_t size, int unpack_pt5);
-
-/**
- * Execute a Ternary General Matrix-Vector multiplication.
- */
-int fabric_exec_gemv(void* weight_ptr, void* input_ptr, void* output_ptr, int rows, int cols);
+#define TFMBS_IOC_SUBMIT_GEMV _IOW(TFMBS_IOC_MAGIC, 3, tfmbs_gemv_t)
 ```
 
+For high-level languages, the `pytfmbs` library provides a Pythonic wrapper around these low-level calls.
+
 ---
 
 ## 5. Implementation Requirements

USER_MANUAL.md

@@ -1,11 +1,11 @@
-# Ternary Fabric User Manual (v0.1)
+# Ternary Fabric User Manual (v0.2)
 
 Welcome to the **Ternary Fabric** user manual. This documentation is designed to help hardware designers, software developers, and researchers understand and utilize the ternary-native acceleration substrate.
 
 ## 📖 Table of Contents
 
 1.  **[Project Overview](docs/00_OVERVIEW.md)**
-    What is the Ternary Fabric? Design philosophy, core innovation, and Phase 6b status.
+    What is the Ternary Fabric? Design philosophy, core innovation, and Phase 15 status.
 2.  **[Installation & Setup](docs/01_INSTALL.md)**
     Dependencies, build instructions, and environment setup.
 3.  **[Quick Start Guide](docs/02_QUICK_START.md)**
@@ -17,17 +17,17 @@ Welcome to the **Ternary Fabric** user manual. This documentation is designed to
 6.  **[TFD & Execution Hints](docs/05_TFD.md)**
     The binary interface specification, kernel flags, and packing formats.
 7.  **[Kernel Reference](docs/06_KERNELS.md)**
-    Usage details for Production (T-GEMM, T-CONV) and Experimental (T-LSTM, T-ATTN) kernels.
+    Usage details for accelerated kernels (T-GEMM, T-CONV3D, T-LSTM, T-ATTN).
 8.  **[Software API Guide](docs/07_API.md)**
     Comprehensive guide to the `pytfmbs` Python library.
 9.  **[Profiling & Optimization](docs/08_PROFILING.md)**
     Measuring Zero-Skip effectiveness and tuning for multi-tile performance.
 10. **[How-To Tutorials](docs/09_TUTORIALS.md)**
     Step-by-step guides for quantization, multi-tile scaling, and DMA loading.
 11. **[Appendices](docs/10_APPENDICES.md)**
-    Acronyms, PT-5 details, and Phase 6b verification reports.
+    Acronyms, PT-5 details, and Phase 15 verification reports.
 12. **[Multi-Tile Scaling](docs/11_MULTI_TILE.md)**
-    Details on Phase 11 multi-tile topology and masking.
+    Details on multi-tile topology and masking.
 13. **[PyTorch Integration](docs/12_PYTORCH.md)**
     Using the Ternary Fabric within the PyTorch deep learning framework.
 14. **[Strategy Roadmap](docs/ROADMAP.md)**
@@ -52,9 +52,9 @@ LD_PRELOAD=./libtfmbs_intercept.so ./my_app
 
 ---
 
-## 📊 Interpreting Telemetry (Phase 9)
+## 📊 Interpreting Telemetry
 
-When running with the interposer, the Fabric provides real-time telemetry to `stderr`:
+When running with the interposer or Python API, the Fabric provides real-time telemetry:
 
 *   **Zero-Skips:** The number of operations eliminated because an operand was zero. Typically 50-75% for LLM workloads.
 *   **Pool Usage:** Current consumption of the 128MB emulation pool.
@@ -63,7 +63,7 @@ When running with the interposer, the Fabric provides real-time telemetry to `st
 
 ---
 
-## 🧠 Memory Management (Phase 7 & 8)
+## 🧠 Memory Management
 
 ### LRU Paging
 The Fabric emulator manages a fixed 128MB pool of "Fabric Memory". If an allocation exceeds this or the pool is full, the system uses a **Least Recently Used (LRU)** policy to evict resident PT-5 frames. Evicted frames are transparently re-hydrated if accessed again by the host.

WHITE_PAPER.md

@@ -49,11 +49,13 @@ Ternary Fabric sits at the intersection of Ternary Neural Networks (TNNs) and do
 *   **MIT Eyeriss:** A research-focused spatial accelerator that prioritizes data movement efficiency. Like the Ternary Fabric, it values energy efficiency but remains centered on binary-encoded weights.
 *   **AMD XDNA (AI Engine):** A tile-based architecture for Ryzen processors. XDNA offers high flexibility, but the Ternary Fabric's specialization in balanced-ternary allows for the complete elimination of multipliers, a step further in architectural optimization.
 
-## 5. Future Directions & Experimental Kernels
-With the core multi-tile architecture (Phase 6b) now validated, the project is expanding into complex recurrent and attention-based structures. Current experimental kernels include **T-LSTM** and **T-Attention**, which are undergoing functional verification in the software reference layer before being committed to RTL.
+## 5. Framework Integration & Native Kernels
+As of Phase 15, the Ternary Fabric has achieved deep integration with high-level frameworks like PyTorch and native hardware acceleration for complex structures.
+- **PyTorch Integration:** The `TFMBSLinear` module enables seamless acceleration of deep learning models with automatic quantization and residency management.
+- **Native RTL Kernels:** Recurrent and attention-based structures, including **T-LSTM**, **T-Attention**, and **T-CONV3D**, are now natively supported in hardware, providing extreme throughput for diverse AI workloads.
 
 ## 6. Conclusion
-The Ternary Fabric provides a scalable, efficient, and high-throughput substrate for the next generation of ternary-quantized neural networks. The successful implementation of Phase 6b demonstrates that ternary-native computing can scale to meet the demands of modern AI while maintaining a fraction of the power and area overhead of binary systems.
+The Ternary Fabric provides a scalable, efficient, and high-throughput substrate for the next generation of ternary-quantized neural networks. The successful completion of Phase 15 demonstrates that ternary-native computing can scale to meet the demands of modern AI, from LLMs to computer vision, while maintaining a fraction of the power and area overhead of binary systems.
 
 ---
 © 2026 Ternary Fabric Project.

docs/00_OVERVIEW.md

@@ -20,22 +20,25 @@ To save bandwidth, data is stored in a high-density **PT-5** format (5 trits per
 ### Multi-Tile Scalability
 The architecture is parameterized to scale from a single tile to a large matrix of tiles. Each tile operates in lock-step, sharing a frame controller but maintaining private SRAM for local data storage and high-throughput parallel execution.
 
-## 3. Project Status (Phase 9)
+## 3. Project Status (Phase 15)
 
 The project has evolved through several key phases:
 
 *   **Phases 1-2:** Specification of the TFMBS ABI and development of the PT-5 codec.
-*   **Phase 3:** RTL design of the Vector Engine and TPE lanes.
-*   **Phase 4:** Integration with Python via `pytfmbs` and development of the quantization toolkit.
-*   **Phase 5:** Implementation of hardware profiling counters and dynamic lane masking.
-*   **Phase 6:** Multi-tile scaling, broadcast weight support, and ASIC-ready SRAM wrappers.
-*   **Phase 7:** LRU-based Paging and block eviction for large models.
-*   **Phase 8:** Asynchronous execution with a background command queue.
-*   **Phase 9 (Current):** Integrated telemetry and proof-of-concept acceleration for binary hosts.
-
-## 4. Experimental Kernels
-
-Beyond the core hardware kernels, the fabric currently supports experimental reference implementations for **T-Conv3D**, **T-LSTM**, and **T-Attention**. These are wired into the `pytfmbs` API and TFMBS header, allowing for software-level verification and architectural exploration before full RTL acceleration.
+*   **Phase 3-4:** RTL design of the Vector Engine and integration with Python via `pytfmbs`.
+*   **Phase 5-6:** Hardware profiling, multi-tile scaling, and ASIC-ready SRAM wrappers.
+*   **Phase 7-9:** LRU-based Paging, asynchronous execution, and integrated telemetry.
+*   **Phase 10-11:** Transition to kernel-space IOCTL interface and multi-tile scaling.
+*   **Phase 12-14:** PyTorch integration, large-model batching, and native GGUF support.
+*   **Phase 15 (Current):** Native RTL acceleration for CONV3D, LSTM, and Attention kernels.
+
+## 4. Accelerated Hardware Kernels
+
+As of Phase 15, the fabric supports native RTL-accelerated kernels for:
+*   **T-GEMM:** General Matrix Multiply for LLM offloading.
+*   **T-Conv3D:** 3D Convolution with squared-stride address calculation.
+*   **T-LSTM:** Recurrent ternary operations with hardware-managed state persistence.
+*   **T-Attention:** Multi-head attention projections with persistent key-value caching support.
 
 ## 5. Key Terminology
 

docs/01_INSTALL.md

@@ -7,6 +7,7 @@ This guide covers the requirements and steps to set up the Ternary Fabric enviro
 ### Software Dependencies
 *   **Python 3.8+**
 *   **NumPy:** Used for data preparation and reference verification.
+*   **PyTorch (1.10+):** Required for `TFMBSLinear` and framework integration.
 *   **Setuptools:** Required to build the Python C-Extension.
 *   **GCC:** Needed for compiling the `pytfmbs` extension.
 
@@ -25,7 +26,7 @@ cd ternary-fabric
 
 ### Install Python Dependencies
 ```bash
-pip install numpy setuptools pytest
+pip install numpy torch setuptools pytest
 ```
 
 ### Build the `pytfmbs` Extension

docs/02_QUICK_START.md

@@ -45,7 +45,26 @@ results = fabric.results(0)
 print(f"Result for Lane 0: {results[0]}")
 ```
 
-## 2. Running the Full Example
+## 2. Advanced: PyTorch & GGUF
+For modern workloads, use the high-level `pytfmbs` integrations.
+
+### PyTorch Integration
+```python
+from pytfmbs import TFMBSLinear
+import torch
+
+model = TFMBSLinear(784, 60) # Accelerated Linear Layer
+output = model(torch.randn(1, 784))
+```
+
+### Loading GGUF Models
+```python
+import pytfmbs
+fabric = pytfmbs.Fabric()
+pytfmbs.load_gguf_tensor(fabric, "model.gguf", "blk.0.attn_q.weight", address=0x1000)
+```
+
+## 3. Running the Full Example
 A complete, executable version of this walkthrough is available in the repository:
 
 ```bash

docs/03_HARDWARE.md

@@ -68,6 +68,11 @@ Since trits are restricted to $\{-1, 0, 1\}$, multiplication is trivial:
 *   If both are non-zero and have the same sign, the result is $+1$ (Increment Accumulator).
 *   If they have different signs, the result is $-1$ (Decrement Accumulator/Two's Complement).
 
+### Native Kernel Support (Phase 15)
+The Vector Engine includes specialized logic for advanced kernels:
+*   **Squared-Stride Addressing (CONV3D):** Automatic offset calculation for 3D spatial traversal.
+*   **State Persistence (LSTM/ATTN):** When the `BIAS_EN` hint is set, the accumulator persists its value across frame descriptors, enabling efficient recurrent and attention-based state management.
+
 ## 4. Pipeline Execution Flow
 
 1.  **Submission:** The Host writes a TFD to the AXI registers.

docs/05_TFD.md

@@ -55,10 +55,10 @@ Bits  | Name           | Description
 | `0x03` | `MUL` | Element-wise multiplication (Result is not accumulated). |
 | `0x04` | `CONV2D`| 2D Convolution (Uses stride/pad hints). |
 | `0x05` | `MAXPOOL`| Ternary Max Pooling. |
-| `0x06` | `TGEMM` | Matrix multiplication (Optimized accumulation). |
-| `0x07` | `CONV3D`| 3D Convolution (Experimental). |
-| `0x08` | `LSTM`  | Ternary LSTM (Experimental). |
-| `0x09` | `ATTN`  | Ternary Attention (Experimental). |
+| `0x06` | `TGEMM` | Matrix multiplication (Native RTL). |
+| `0x07` | `CONV3D`| 3D Convolution (Native RTL). |
+| `0x08` | `LSTM`  | Ternary LSTM (Native RTL). |
+| `0x09` | `ATTN`  | Ternary Attention (Native RTL). |
 
 ## 5. Packing Formats (`packing_fmt`)
 

docs/07_API.md

@@ -20,13 +20,33 @@ Loads data via the AXI-Stream DMA interface.
 *   `data`: `bytes` object.
 
 ### `run(tfd_dict)`
-Submits a task and waits for completion.
+Submits a task and waits for completion (Synchronous).
 *   `tfd_dict`: Dictionary with keys like `frame_len`, `exec_hints`, `tile_mask`, etc.
 
+### `submit(tfd_dict)`
+Submits a task and returns immediately (Asynchronous). Returns a `task_id`.
+
+### `wait(task_id=None)`
+Blocks until the specified `task_id` (or the last submitted task) is complete.
+
+### `is_done(task_id=None)`
+Returns `True` if the specified `task_id` (or the last submitted task) has completed.
+
+### `run_batch(tfd_list)`
+Submits a list of TFDs for optimized batch execution.
+
 ### `results(tile_id=0)`
 Returns a list of 15 integers representing the accumulated results for the specified tile. Use `tile_id=-1` to get results for all tiles.
 
-## 2. Profiling Methods
+## 2. Framework & GGUF Integration
+
+### `pytfmbs.TFMBSLinear(in_features, out_features, ...)`
+A PyTorch layer that offloads GEMV operations to the Ternary Fabric. Supports automatic quantization and prefetching.
+
+### `pytfmbs.load_gguf_tensor(fabric, path, tensor_name, address)`
+Utility to load a tensor from a GGUF file directly into Fabric SRAM, with automatic dequantization and PT-5 packing.
+
+## 3. Profiling Methods
 
 ### `profile()`
 Returns a dictionary with aggregated global metrics: