# Gati Hardware Guide

This directory contains the FPGA hardware implementation of the Gati accelerator and the platform-specific projects required to generate FPGA bitstreams.

## Overview

The Gati hardware flow consists of two major steps:

1. **Hardware Configuration Generation**

   * Generate model-specific hardware parameters from an ONNX model.
   * Produces a Verilog configuration file used by the accelerator.

2. **FPGA Bitstream Generation**

   * Synthesize and place-and-route the hardware design.
   * Generate the final FPGA bitstream using the FPGA vendor toolchain.

---

## Directory Structure

```text
hardware/
├── gati/
├── rah-bit/
├── src/
├── vaaman/
└── ...
```

## Platform Projects

Each platform directory contains a complete FPGA project targeting a specific board and FPGA device.

Example:

```text
hardware/vaaman/
├── constraints.sdc
├── gati.xml
├── gati.peri.xml
├── ip/
```

The `vaaman` platform targets the Efinix Trion T120 FPGA and uses the Efinix Efinity toolchain.

---

## Hardware Configuration Generation

Before generating a bitstream, a model-specific hardware configuration must be created.

The hardware configuration is generated from an ONNX model using the Gati compiler.

The script is available [here](https://github.com/vicharak-in/gaticc/blob/master/scripts/gen_hardware.sh)

### Command

```bash
./gen_hardware.sh \
    -p <gati_platform> \
    -m <model.onnx> \
    -f <FPGA>
```

### Arguments

| Argument | Description                      |
| -------- | -------------------------------- |
| `-p`     | Path to Gati platform repository |
| `-m`     | Path to ONNX model               |
| `-f`     | Target FPGA device               |
| `-h`     | Show help                        |

### Example

```bash
./gen_hardware.sh \
    -p ~/gati_platform \
    -m yolov8n_quantized.onnx \
    -f T120
```

### What Happens

The script invokes:

```bash
gaticc \
    -g <model.onnx> \
    -f <gen_hardware.vh> \
    --fpga <FPGA>
```

which analyzes the ONNX model and generates a hardware configuration file:

```text
hardware/Gati/src/rtl/common/gen_hardware.vh
```

This file contains accelerator parameters derived from the network architecture and FPGA target.



### Supported Model 

All the supported model are available in the Model Zoo in the release section.

--- 

## FPGA Bitstream Generation

After the hardware configuration has been generated, the FPGA project can be synthesized using the Efinix Efinity toolchain.

### Opening the Project

Navigate to the Vaaman platform directory:

```bash
cd hardware/vaaman
```

Launch Efinity and open:

```text
hardware/vaaman/gati.xml
```

This project is pre-configured for the Vaaman platform and targets the Efinix Trion T120 FPGA.

### Important: Do Not Update IPs

> [!WARNING]
> When opening the project, Efinity may display a dialog prompting you to update or regenerate IP blocks.
>
> Select **"No"** or **"Skip"** and do **not update any IPs**.
>
> The project has been validated using the IP versions checked into the repository. Updating IPs may result in:
>
> * Build failures
> * Timing violations
> * Incompatible generated files
> * Functional mismatches with the validated hardware design
>
> Unless explicitly instructed by the Gati maintainers, always use the IP versions included in the repository.

### Building the Bitstream

Once the project is opened:

1. Run Synthesis
2. Run Place & Route
3. Run Timing Analysis
4. Generate Bitstream

The generated hardware configuration (`gen_hardware.vh`) will automatically be included during compilation.

### Output Files

Generated FPGA output files can be found in:

```text
hardware/vaaman/outflow/
```

The generated bitstream can then be programmed onto the FPGA using the Efinity Programmer.

---

## Generated Outputs

### Hardware Configuration

```text
hardware/Gati/src/rtl/common/gen_hardware.vh
```

Contains:

* Layer configuration
* Accelerator dimensions
* Memory allocation parameters
* FPGA-specific hardware settings

### FPGA Bitstream

Generated by the Efinity toolchain.

Typical outputs include:

```text
outflow/
├── *.hex
├── *.bit
└── reports/
```

Actual file names may vary depending on the target device and Efinity version.

---

## Tool Requirements

### Gati Compiler

The following tool must be available in your PATH:

```bash
which gaticc
```

### FPGA Toolchain

For the Vaaman platform:

* Efinity Toolchain
* Efinix Trion T120 Device Support

---

## Supported Platforms

| Platform | FPGA       | Toolchain |
| -------- | ---------- | --------- |
| Vaaman   | Trion T120 | Efinity   |

Additional FPGA targets may be added in future releases.

---

## Complete Build Flow

```text
ONNX Model
     │
     ▼
gaticc
     │
     ▼
gen_hardware.vh
     │
     ▼
Open gati.xml in Efinity
     │
     ▼
Synthesis
     │
     ▼
Place & Route
     │
     ▼
Timing Analysis
     │
     ▼
Bitstream Generation
     │
     ▼
Program FPGA
```