# Firmware Build Flow

This page details the toolchain requirements, directory setup, and step-by-step Tcl workflow needed to generate the FPGA bitstreams and overlay artifacts for the FIREQ platform.

---

## Toolchain & Prerequisites

The firmware build flow relies on the AMD/Xilinx Vivado Design Suite:
* **Recommended Version**: **Vivado 2023.2**.
* **Board Files**: Board support files for the **RFSoC4x2** flow are located under the `board_files/` directory in the repository root. The **ZCU216** uses standard AMD/Xilinx board definitions.

---

## Step-by-Step Project Build Flow

To build the overlay bitstream from scratch using the provided Tcl generation scripts, follow these steps:

### 1. Workspace Preparation
Create a dedicated `workspace/` directory in the root of the firmware repository (if it does not already exist):

```bash
mkdir -p workspace
```

### 2. Vivado Project Initialization

1. Launch AMD Xilinx Vivado.
2. If building for the RFSoC4x2, add the repository's `board_files/` directory to your Vivado Board Repository paths (`Tools -> Settings -> Vivado Store / Board Repository`).
3. Set `workspace/` as your active working directory.

### 3. Executing the Block Diagram Script
In the Vivado Tcl Console, navigate to the `workspace/` directory and source the appropriate board overlay Tcl script from `board_overlay/`:

- **For ZCU216 Overlay**:

```tcl
cd workspace
source ../board_overlay/zcu216_overlay/zcu216_overlay.tcl
```
- **For RFSoC4x2 Overlay**:


```tcl
cd workspace
source ../board_overlay/rfsoc4x2_overlay/rfsoc4x2_overlay.tcl
```
This script automatically recreates the Vivado IP Integrator Block Diagram, imports all custom IP definitions (Generators, Sequencers, Acquisition units, DSP wrappers), and configures the system clocks and constraints.

### 4. Synthesis, Implementation, and Bitstream Generation

1. In Vivado, click **Run Synthesis** and wait for completion.
2. Click **Run Implementation**.
3. Once implementation completes without timing violations, click **Generate Bitstream**.

## Common Includes & Parametrization
The firmware codebase relies on global SystemVerilog header files to ensure modularity, parameter sharing, and clean compile-time definitions across custom IP blocks:

- **`COMMON_INCLUDES.svh`**: Contains global macro definitions, system-wide data structure widths, fixed-point math definitions, and common interface constants shared across all modules.
- **`PROJECT_INCLUDES.svh`**: Defines project-specific and overlay-specific hardware parameters (e.g., memory buffer depths, channel counts, and specific register addresses).
These include files are automatically parsed during IP synthesis and block diagram generation to guarantee architectural consistency between IP modules.

## Output Artifacts & Deployment Preparation
Upon successful bitstream generation, export the target hardware artifacts:

1. **Export Bitstream**: Locate the generated `.bit` file (usually inside `workspace/<project_name>.runs/impl_1/`).
2. **Export Hardware Handoff**: Locate the matching `.hwh` file (generated under `workspace/<project_name>.gen/sources_1/bd/<bd_name>/hw_handoff/`).
3. **Artifact Alignment**: Rename both files so that they share the exact same base name in the same directory (e.g., `FIREQ_overlay.bit` and `FIREQ_overlay.hwh`).

> **Important**: Matching base names are strictly required by the PYNQ framework and `FIREQ-Server` to dynamically bind hardware memory maps during startup.