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

```bash
# 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:

```bash
cd d:\goml\flashattentionv1
```

Create virtual environment:

```bash
# Create venv
python -m venv venv

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

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

Install dependencies:

```bash
pip install cocotb cocotb-test pytest numpy
```

Verify installation:

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

---

## Step 3: Verify RTL Files

Check that all RTL source files are present:

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

Optionally, check SystemVerilog syntax:

```bash
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)

```bash
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.

```bash
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:

```bash
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:
```bash
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:
```bash
# 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:
```bash
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:

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

### 2. Generate Waveforms (Optional)

To visualize signal behavior:

```bash
# 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! 🚀