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):

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:

cd workspace
source ../board_overlay/zcu216_overlay/zcu216_overlay.tcl

  • For RFSoC4x2 Overlay:

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.