Xilinx Build Flow Analysis

This document outlines the Xilinx build process for the rapidrtl project, tracing the execution from the root Makefile through the various TCL scripts in the tcl/xilinx directory.

Build Flow Diagram

The following diagram illustrates how the Makefile targets trigger the TCL scripts and how those scripts interact and depend on each other.


flowchart TD
    subgraph root_makefile ["Makefile (Root)"]
        M_proj["make project"]
        M_synth["make synthesis"]
        M_impl["make implementation"]
        M_bit["make bitstream"]
    end

    subgraph tcl_xilinx ["tcl/xilinx/"]
        env["environment.tcl (Global Config)"]
        utils["impl_utils.tcl (Helper Procs)"]
        gen_proj["gen_project.tcl (Create Project)"]
        gen_synth["gen_synthesis.tcl (Synthesize)"]
        gen_impl["gen_implementation.tcl (Implement)"]
        gen_bit["gen_bitstream.tcl (Bitgen)"]
    end

    subgraph artifacts ["Build Artifacts"]
        xpr["Project File (.xpr)"]
        synth_dcp["synthesis.dcp"]
        impl_dcp["implementation.dcp"]
        bit_file["system.bit"]
    end

    %% Flow Connections
    M_proj --> gen_proj
    M_synth --> gen_synth
    M_impl --> gen_impl
    M_bit --> gen_bit

    %% Implicit Sources (using dashed lines)
    gen_proj -.-> env
    gen_synth -.-> env
    gen_impl -.-> env
    gen_bit -.-> env

    env -.-> utils
    gen_synth -.-> utils
    gen_impl -.-> utils

    %% Sequential Flow
    gen_proj --> xpr
    xpr -.-> gen_synth
    gen_synth --> synth_dcp
    synth_dcp -.-> gen_impl
    gen_impl --> impl_dcp
    impl_dcp -.-> gen_bit
    gen_bit --> bit_file

    %% Re-entry/Dependencies
    gen_impl -- "if dcp missing" --> gen_synth
    gen_bit -- "if dcp missing" --> gen_impl

Step-by-Step Breakdown

1. Initialization: environment.tcl

Almost every script in the flow sources environment.tcl at the start. It defines the "source of truth" for the project:

Project Structure: Root directory, project name, and working directories.
Hardware Targets: FPGA part number (xc7z020clg400-1).
Dependencies: It automatically sources impl_utils.tcl, providing access to shared utility procedures.

2. Project Creation: gen_project.tcl

Triggered by make project, this script builds the Vivado environment:

Project Creation: Initializes the .xpr project file.
IP Management: Imports Xilinx IP cores (.xci).
File Lists: Adds RTL files (VHDL 2008), constraints (.xdc), and simulation sources.
Dynamic Config: Sources any additional TCL files passed from the Makefile (e.g., Block Designs).

3. Synthesis: gen_synthesis.tcl

Triggered by make synthesis:

Run Management: Resets and launches synth_1.
IP Synthesis: Automatically waits for any Out-of-Context (OOC) IP synthesis to complete.
Checkpointing: Captures the state in dcp/synthesis.dcp.
Validation: Uses reportUnconnectedPins from impl_utils.tcl to check for logic errors.

4. Implementation: gen_implementation.tcl

Triggered by make implementation. This is the most complex part of the flow:

Auto-Synthesize: If synthesis.dcp is missing, it will automatically call gen_synthesis.tcl.
Iterative Optimization:
- Runs opt_design.
- Runs place_design with specific directives (e.g., Explore).
- Executes a Physical Optimization Loop (phys_opt_design) to squeeze timing.
- Executes a Routing Loop (route_design), trying different directives if timing isn't met.
Reporting: Generates a summary.rpt with critical timing information and resource utilization.

5. Bitstream Generation: gen_bitstream.tcl

Triggered by make bitstream:

Checkpoints: Opens the final implementation checkpoint (implementation.dcp).
Output: Generates the final hardware files:
- bitstream/system.bit: The FPGA configuration file.
- bitstream/system.ltx: The ILA debug probes file.

Key Observations

Non-Project vs Project Mode: The scripts use a hybrid approach, creating a project file but driving most actions via batch TCL commands for reproducibility.
Re-entrance: gen_implementation.tcl and gen_bitstream.tcl have logic to "catch up" by running previous stages if their deliverables (DCPs) are missing.
Timing Focus: The implementation script is heavily focused on timing closure, featuring multiple loops and directive exploration.

XILINX BUILD FLOW