docs/SIMULATION_SETUP.md

FlashAttention RTL - Simulation Setup & Run Guide

Overview

This guide helps you set up and run the Cocotb testbench for the FlashAttention RTL engine.

Simulator Stack:

• Verilator: Open-source Verilog/SystemVerilog simulator (C++ based, Windows-compatible)
• Cocotb: Coroutine-based testbench framework (Python)
• Python 3.8+: Scripting language for testbench

Target Module: 8×8 Systolic Array for matrix multiplication (Q4.4 fixed-point)

---

Prerequisites

Windows System Requirements

Before proceeding, ensure you have:

1. Python 3.8 or later

   python --version  # Should show 3.8+
   

2. Git Bash or WSL2 (for Unix-like commands on Windows)

   • Recommended: Git Bash (lightweight)
   • Alternative: Windows Subsystem for Linux 2

3. C++ Compiler (required by Verilator)

   • Option A: Microsoft Visual C++ (MSVC)
     • Install Visual Studio Community (free)
     • Select "Desktop Development with C++"
   • Option B: MinGW-w64 (lightweight alternative)
     • Download from: https://www.mingw-w64.org/
     • Add bin/ to Windows PATH

4. Verilator 5.0+ (Verilog/SystemVerilog simulator)

   # Download Windows binary or build from source
   # https://www.veripool.org/verilator/
   verilator --version
   

---

Step 1: Install Verilator (Windows)

Option A: Using Pre-built Binary (Easiest)

1. Download Verilator Windows binary from: https://www.veripool.org/verilator/
2. Extract to C:\Program Files\verilator\ (or custom location)
3. Add to Windows PATH:

   setx PATH "%PATH%;C:\Program Files\verilator\bin"
   

4. Verify:

   verilator --version
   

Option B: Build from Source

# Clone Verilator
git clone https://github.com/verilated/verilator

cd verilator
git checkout v5.012  # Latest stable

# Configure and build
autoconf
./configure --prefix=C:\Program Files\verilator
make
make install

# Add to PATH
setx PATH "%PATH%;C:\Program Files\verilator\bin"

---

Step 2: Set Up Python Environment

Navigate to project directory:

cd d:\goml\flashattentionv1

Create virtual environment:

# Create venv
python -m venv venv

# Activate (Windows Command Prompt)
venv\Scripts\activate

# OR activate (PowerShell)
venv\Scripts\Activate.ps1

Install dependencies:

pip install cocotb cocotb-test pytest numpy

Verify installation:

python -c "import cocotb; print(f'Cocotb {cocotb.__version__} installed')"

---

Step 3: Verify RTL Files

Check that all RTL source files are present:

# From project root
dir rtl\src\*.sv
# Should show:
#   processing_element.sv
#   systolic_array.sv

Optionally, check SystemVerilog syntax:

cd sim
verilator --lint-only ..\rtl\src\processing_element.sv ..\rtl\src\systolic_array.sv --top-module systolic_array

---

Step 4: Run Testbench

Quick Test (Syntax Check Only)

cd sim
make check_syntax

Expected output:

Checking SystemVerilog syntax with Verilator...
(no errors = success)

Full Simulation with Cocotb

Important: Cocotb testbenches must be run from sim/ directory.

cd sim

# Run all tests
python -m cocotb.simulator --simulator verilator \
    --testbench test_systolic_array \
    --toplevel systolic_array \
    --verilog_sources ../rtl/src/processing_element.sv \
    --verilog_sources ../rtl/src/systolic_array.sv

Or use the Makefile:

cd sim
make sim

---

Expected Output

When simulation runs successfully, you should see:

===========================
TEST: Systolic Array Basic Functionality
===========================
Starting 10ns clock...
Asserting reset...

Test 1: Small values (easy validation)
...
RTL output:
[[result matrix]]

Golden C: ...
RTL: ...
Result C[0,0]: golden=X, rtl=Y

✓ TEST PASSED
===========================

---

Troubleshooting

Error: "verilator: command not found"

Solution: Verilator is not in PATH. Verify installation:

where verilator    # Should show path
verilator --version

If not found, manually add Verilator bin/ directory to Windows PATH:

• Settings → Environment Variables → Edit PATH → Add C:\Program Files\verilator\bin
• Restart terminal and try again

Error: "cocotb: command not found" or "ModuleNotFoundError: No module named cocotb"

Solution: Cocotb not installed in Python environment:

# Make sure venv is activated
pip list | grep cocotb    # Should show installed packages
pip install cocotb cocotb-test

Error: "C++ compiler not found"

Solution: Required for Verilator compilation. Install:

• MSVC: Visual Studio Community with C++ workload
• OR MinGW: Download from mingw-w64.org, add to PATH

Error: SystemVerilog Syntax Issues

Solution: Verify RTL files are valid:

verilator --lint-only ../rtl/src/*.sv

Fix any reported syntax errors (modern SystemVerilog constructs like interface may need simulation-specific flags).

---

Next Steps (For Development)

After verifying the systolic array works:

1. Run Simplified Tests

Create simpler test vectors for quicker iteration:

python test_data_gen.py  # Generate test vectors
python test_systolic_array.py  # Run basic tests

2. Generate Waveforms (Optional)

To visualize signal behavior:

# Run with trace enabled
verilator --trace ../rtl/src/systolic_array.sv

# View waveform
gtkwave trace.vcd

3. Extend Testbench

Add more complex test cases to test_systolic_array.py:

• Multi-block cascades
• Edge cases (saturation, boundary conditions)
• Performance metrics (throughput, latency)

---

Configuration Options

Edit sim/Makefile or pyproject.toml to customize:

• Simulator: Change SIM = verilator to other simulators (iverilog, ModelSim, etc.)
• Trace: Add --trace to capture waveforms
• Optimization: Add -O3 for simulation speed

---

References

• Verilator: https://www.veripool.org/verilator/
• Cocotb: https://docs.cocotb.org/
• SystemVerilog: https://en.wikipedia.org/wiki/SystemVerilog
• Fixed-Point Arithmetic: Q-format reference in golden_model.py

---

Support

For issues:

1. Check RTL syntax: verilator --lint-only ../rtl/src/*.sv
2. Verify Python environment: pip list
3. Review Cocotb logs: Check console output for detailed error messages
4. Consult RTL comments: Each module has inline documentation

Good luck with your FlashAttention RTL! 🚀