# rancunefr/xilinx_template architecture

> Architecture diagram of the GitHub repository rancunefr/xilinx_template, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rancunefr/xilinx_template
- Repository: https://github.com/rancunefr/xilinx_template

## Overview

##### Project Type and Purpose
- This is a “Vivado Make-based FPGA Project Template.”
- Its goal is to orchestrate the entire FPGA development flow (compile, simulate, synthesize, implement, generate bitstream, program board) using a portable Makefile and supporting Tcl scripts.
- You target Xilinx FPGAs (e.g. Basys-3) from the command line, with incremental builds via timestamp files.

##### Key Directories & Files
- Makefile & settings.mk: central build orchestrator and user-configurable variables (PART, SRC_*, TB_TOP, XDC).
- constr/: XDC constraint files (board pinout, timing).
- ip/: pre-built/custom IP cores plus config templates (clocking wizard “clocky”).
- scripts/: helper Tcl scripts invoked by the Makefile (synthesis, simulation, bitgen, upload).
- src/: RTL sources (SystemVerilog modules: principal, impulse, counter).
- tb/: testbench sources for behavioural simulation.
- output/: auto-generated netlists, reports, waveforms, bitfiles (not checked in).
- sim_libs/: time-annotated libraries for post-synthesis/implementation timing sims.

##### Main Architectural Components
a. Artifacts Layer
- RTL Sources (src/)
- Testbench Sources (tb/)
- Constraints (constr/)
- IP Cores & Configs (ip/)
- Build Config (settings.mk)
b. Orchestration Layer
- Makefile – defines targets (src, tb, synth, impl, binary, sim, upload)
- Timestamp files (.timestamp.*) for incremental builds
- Tcl Scripts (scripts/*.tcl)
c. Toolchain Layer
- Vivado CLI tools: xvlog, xelab, xsim, vivado (synth → P&R → bitgen → hw_server)
d. Simulation Infrastructure
- sim_libs/ (generated libraries)
- GTKWave viewer for VCD waveforms
e. Output / Deployment
- Generated Reports (timing, utilization)
- Bitstream (.bit/.bin)
- Programmed FPGA board via Vivado HW manager

##### Relationships & Data Flows
- User invokes `make <target>` → Makefile reads settings.mk
- Makefile calls Tcl scripts and/or Vivado CLI:
- “make src” → xvlog (RTL lint)
- “make tb” → xvlog + xelab (elaboration)
- “make sim” → xsim → output/waveforms/*.vcd → GTKWave
- “make synth” → synth_netlist → output/netlists
- “make impl” → place&route → output/reports
- “make binary” → bitgen → .bin file
- “make upload” → vivado hw_server → programs FPGA
- IP generation flow: ip/configs → `make ip_generate_instances` → ip/clocky.xci + sources → include in SRC_IP

##### Architectural Patterns & Principles
- Separation of concerns: source artifacts, build logic, toolchain, outputs.
- Incremental build via timestamp stamps to avoid redundant re-runs.
- Modular TCL scripts for each sub-task, invoked by Makefile.
- Directory-based layering: clear boundaries between design, testbench, constraints, IP, and outputs.

##### Essential Elements
- Clear labels on all components (e.g., “src/”, “scripts/”, “Vivado CLI”).

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Artifacts Layer"
        src["RTL Sources\n(src/)"]:::artifacts
        tb["Testbench Sources\n(tb/)"]:::artifacts
        constr["Constraints\n(constr/)"]:::artifacts
        ip["IP Cores & Configs\n(ip/)"]:::artifacts
        settings["Build Config\n(settings.mk)"]:::artifacts
    end

    subgraph "Orchestration Layer"
        makefile["Makefile"]:::orchestrator
        scripts["Tcl Scripts\n(scripts/)"]:::scripts
        timestamps["Timestamp Files\n(.timestamp.*)"]:::orchestrator
    end

    subgraph "Toolchain Layer"
        xvlog["xvlog"]:::tool
        xelab["xelab"]:::tool
        xsim["xsim"]:::tool
        vivado_cli["Vivado CLI\n(synth,P&R,bitgen,hw_server)"]:::tool
    end

    subgraph "Simulation Infrastructure"
        sim_libs["Simulation Libraries\n(sim_libs/)"]:::storage
        gtkwave["GTKWave Viewer"]:::tool
    end

    subgraph "Outputs"
        reports["Reports\n(output/reports)"]:::docs
        netlists["Netlists\n(output/netlists)"]:::docs
        waveforms["Waveforms\n(output/waveforms)"]:::docs
        bitstream["Bitstream\n(.bit/.bin)"]:::docs
    end

    fpga["FPGA Board"]:::hardware

    src --> makefile
    tb --> makefile
    constr --> makefile
    ip --> makefile
    settings --> makefile

    makefile --> timestamps
    makefile -->|"invokes"| scripts

    makefile -->|"xvlog"| xvlog
    makefile -->|"xelab"| xelab
    makefile -->|"xsim"| xsim
    makefile -->|"vivado synth"| vivado_cli
    makefile -->|"vivado P&R"| vivado_cli
    makefile -->|"vivado bitgen"| vivado_cli
    makefile -->|"vivado upload"| vivado_cli

    scripts --> xvlog
    scripts --> xelab
    scripts --> vivado_cli

    xvlog --> netlists
    xelab --> netlists

    xsim --> waveforms
    xsim --> sim_libs
    xsim --> gtkwave

    vivado_cli --> netlists
    vivado_cli --> reports
    vivado_cli --> bitstream

    bitstream --> fpga

    click src "https://github.com/rancunefr/xilinx_template/tree/master/src/"
    click tb "https://github.com/rancunefr/xilinx_template/tree/master/tb/"
    click constr "https://github.com/rancunefr/xilinx_template/tree/master/constr/"
    click ip "https://github.com/rancunefr/xilinx_template/tree/master/ip/"
    click settings "https://github.com/rancunefr/xilinx_template/blob/master/settings.mk"
    click makefile "https://github.com/rancunefr/xilinx_template/tree/master/Makefile"
    click scripts "https://github.com/rancunefr/xilinx_template/tree/master/scripts/"
    click sim_libs "https://github.com/rancunefr/xilinx_template/tree/master/sim_libs/"
    click reports "https://github.com/rancunefr/xilinx_template/tree/master/output/"
    click netlists "https://github.com/rancunefr/xilinx_template/tree/master/output/"
    click waveforms "https://github.com/rancunefr/xilinx_template/tree/master/output/"
    click bitstream "https://github.com/rancunefr/xilinx_template/tree/master/output/"

    classDef artifacts fill:#add8e6,stroke:#000,stroke-width:1px
    classDef orchestrator fill:#ffa500,stroke:#000,stroke-width:1px
    classDef scripts fill:#d3d3d3,stroke:#000,stroke-width:1px
    classDef tool fill:#d3d3d3,stroke:#000,stroke-width:1px
    classDef storage fill:#98fb98,stroke:#000,stroke-width:1px
    classDef docs fill:#ffffe0,stroke:#000,stroke-width:1px
    classDef hardware fill:#f0e68c,stroke:#000,stroke-width:1px
```
