# RTL Synthesis Guide

This guide covers synthesizing the ReviveSparc Verilog RTL for FPGA deployment.

## Overview

The ReviveSparc RTL implements a 6-stage, in-order, dual-issue SPARC V9 pipeline with chip multi-threading. It is written in synthesizable Verilog and targets Xilinx and Intel FPGAs.

## Pipeline Stages

```
Fetch   --> Decode --> Execute --> Memory --> Writeback --> Commit
  |          |           |           |           |           |
  v          v           v           v           v           v
 ICache   Decode     ALU/MUL    D-Cache    RegFile    TLB/MMU
```

## Prerequisites

- **Verilator** 5.x (for simulation)
- **Vivado** 2024.x or **Quartus** 23.x (for synthesis)
- **Python** 3.10+ (for build scripts)
- **FuseSoC** (optional, for IP management)

## Building the RTL Simulation

```bash
make rtl
```

This compiles the RTL with Verilator and produces a simulation binary.

### Running RTL Tests

```bash
make rtl-test
```

This runs the complete RTL test suite, including unit tests for each pipeline stage and integration tests for the full core.

## FPGA Synthesis

### Xilinx Vivado

```bash
cd rtl/syn/vivado
vivado -mode batch -source synth.tcl
```

This generates a bitstream for the default target board.

### Target Boards

| Board | Speed | Resources Used | Status |
|-------|-------|----------------|--------|
| Xilinx VC707 (Virtex-7) | 50 MHz, 4 cores | 65% LUT, 48% BRAM | Verified |
| Xilinx KC705 (Kintex-7) | 75 MHz, 2 cores | 55% LUT, 35% BRAM | Verified |
| Xilinx Arty A7 (Artix-7) | 40 MHz, 1 core | 70% LUT, 60% BRAM | Verified |
| Intel Arria 10 GX | 100 MHz, 4 cores | 60% ALM, 40% M20K | Verified |
| Intel Cyclone V | 50 MHz, 2 cores | 72% ALM, 55% M20K | Beta |

### Configuration

RTL parameters are set in `rtl/config.vh`:

```verilog
`define NUM_CORES        4
`define THREADS_PER_CORE 4
`define L1I_SIZE         16384
`define L1D_SIZE         16384
`define L2_SIZE          1048576
`define PIPELINE_STAGES  6
```

## Running on FPGA

1. Program the FPGA with the generated bitstream
2. Connect a USB-UART cable (default: 115200 baud, 8N1)
3. Load a program via the boot ROM interface:

```bash
./tools/fpga-load.py /dev/ttyUSB0 kernel.bin
```

4. The core resets and begins execution. Output appears on the serial console.

## Boot ROM

The boot ROM loads a program from the UART interface into memory and starts execution at the entry point. The boot ROM firmware is in `soft/bootrom/` and is pre-synthesized into the bitstream.

## Debug Interface

The RTL includes a JTAG-like debug interface accessible via the emulator:

```bash
./sparc-emu --connect-fpga /dev/ttyUSB1
```

This connects the emulator's debugger to the FPGA-resident cores, allowing register inspection and breakpoint management.

## Performance Results

| Configuration | FPGA | Frequency | DMIPS |
|---------------|------|-----------|-------|
| 1 core, 4 threads | Artix-7 | 40 MHz | 45 |
| 2 cores, 4 threads | Kintex-7 | 75 MHz | 168 |
| 4 cores, 4 threads | Virtex-7 | 50 MHz | 320 |
| 4 cores, 4 threads | Arria 10 | 100 MHz | 720 |

## Contributing RTL Changes

1. Write a Verilog testbench in `rtl/tb/`
2. Verify with Verilator: `make rtl-test`
3. Ensure lint passes: `make rtl-lint`
4. Submit a pull request on the [Git instance](https://git.revivesparc.com/Revivesparc/revivesparc) with simulation results