Vivado Git Repository

This repository includes all the design sources and third-party reference used in my vivado project.

Table of Contents

• Vivado Git Repository
  • Table of Contents
  • Background
  • How this repository is constructed?
    • Overview
    • Top Level
    • Basic Vivado Project Structure
  • Demos
    • RTL Vivado Project Design Demo
    • RTL Vivado Project Recreate Demo

Background

Since the day I joined my lab, managing Vivado projects has always been a pain in the ass for me and my colleagues. It was not until I accidentally overwrote the initial version of one of my modules that I realized how crucial revision control is for software/hardware developers. After spending a couple of days learning Vivado revision control tricks, I created this repository.

How this repository is constructed?

This repository is designed to store Vivado project design sources and Verilog/VHDL files primarily, but it can also hold associated MATLAB codes of algorithm verification or data analysis and related documentation explaining how the modules work and things that need to be taken care of when interfacing with the modules.

Overview

.
├── .git
├── .gitignore
├── README.md
├── adi_library/
│   └── ...
├── common
│   ├── adder_tree_ppl.v
│   └── ...
├── custom_ips
│   └── ...
├── modules/
│   └── xc7k410tffg900-2/
│       └── tx_qpsk/
│           ├── project.tcl
│           ├── constraints
│           ├── docs
│           ├── ip/
│           │   ├── hrc_64_12_025.xcix
│           │   ├── coe/
│           │   │   └── hrc_64_12_025.coe
│           │   └── managed_ip_project/
│           │       └── ...
│           ├── ipi-bds
│           │   └── ...
│           ├── rtl/
│           │   └── tx_qpsk.v
│           ├── scripts
│           └── testbenches/
│               └── tb_tx_qpsk.v
├── projects/
│   └── datalink_814/
│       └── dl814_k7/
│           ├── project.tcl
│           ├── constraints/
│           │   └── k7410t_ad9516_2ad9361_physical.xdc
│           ├── docs
│           ├── ip/
│           │   ├── sys_clk_gen.xcix
│           │   └── managed_ip_project/
│           │       └── ...
│           ├── ipi-bds/
│           │   └── system_bd/
│           │       ├── system_bd.bd
│           │       └── hdl/
│           │           └── system_bd_wrapper.v
│           ├── project/
│           │   └── project/
│           │       ├── project.hw/
│           │       │      project.lpr
│           │       ├── project.runs/
│           │       │   └── impl_1/
│           │       │       ├── system_top.bit
│           │       │       └── ...
│           │       └── project.sdk/
│           │           ├── system_top.hdf
│           │           ├── dl814_cmos_48m/
│           │           │   └── src
│           │           │       └── ...
│           │           └── dl814_cmos_48m_bsp
│           │               └── system.mss
│           ├── rtl
│           │   ├── system_top.v
│           │   └── ...
│           ├── scripts
│           └── testbenches
└── template
    ├── constraints
    ├── docs
    ├── ip
    ├── ipi-bds
    ├── project
    ├── rtl
    ├── scripts
    └── testbenches

Top Level

The organization of the top level structure is shown in the table below.

Name	Description	Synthesis Required	Implementation Required	Bitstream Required
adi_library	ADI no-OS IP Library, built with Xilinx Vivado 2019.1.	N/A	N/A	N/A
common	Common Verilog/VHDL modules that can work solely without other IPs.	Yes	No	No
custom_ips	Custom IPs.	Yes	No	No
modules	Verilog/VHDL modules that work with other IPs, thus the modules are FPGA specific and they are managed in project mode. In the future the modules may also be categorised by different Vivado versions.	Yes	No	No
projects	Engineering project or board specific Vivado projects, that can be run on hardware.	Yes	Yes	Yes
template	Git-friendly Vivado project structure initialization template. (However this folder cannot be managed with git since it is empty.)	N/A	N/A	N/A
.gitignore	gitignore file that tells git which files to ignore.	N/A	N/A	N/A
README.md	This readme.	N/A	N/A	N/A

All Vivado projects that are managed in project mode is named project or projectxxx, considering that Windows OS limit the file path length to 260 characters.

Basic Vivado Project Structure

As listed above, modules and Vivado projects are managed in project mode, in which Vivado automatically manages the source files, constraints, IPs, run results, and so on. However, the directory structures are not friendly to revision control systems because they contain many redundant files that do not require revision control, such as synthesis and implementation results, and simulation intermediate files.

Fortunately, Vivado designers have already considered almost everything related to revision control. According to the Vivado Design Suite User Guide: Design Flows Overview (UG892), the only thing we need to do is store the design sources outside of the Vivado project directory.

The basic git-friendly Vivado project structure is based on UG892 and several Vivado quick take videos.

1. Using Vivado Design Suite with Revision Control: explains basic concepts of Vivado revision control.

2. Configuring and Managing Reusable IP in Vivado: includes how to use Vivado Manage IP project.

3. IP Revision Control: mainly focuses on the new feature of Vivado 2021.1 that makes revision control easier.

The repository follows a maximum flexibility revision control strategy, wherein all output products undergo revision control to reduce the Vivado project rebuild time and provide an option of using IP in future releases of Vivado without upgrading.

The table below outlines the git-friendly Vivado project structure. It is important to note that all items listed, except for most files in the project directory, will be under revision control. For additional information, please refer to the .gitignore file.

Name	Description
rtl	All RTL-based source files including .include files.
ip	The IP source files and output products. The IPs are stored using core container feature, and managed by Vivado Manage IP project.
ipi-bds	The IP Integrator block design source file (.bd), along with IP subdirectory including IP source files and output products.
testbenches	Simulation test benches and stimulus files.
constraints	All XDC constraint files and Tcl commands used as constraints.
project	Vivado project directory. For single project mode, there is no project subdirectories needed; for multi project mode, each project is stored in a subdirectory containing a single Vivado project. It should be noted that the .gitignore is different for single project mode and multi project mode, because the directory depth are not the same. Therefore, .gitignore should always be checked before the first commit.
scripts	Run scripts used to compile the design including any pre and post scripts used when launching runs, along with any other custom scripts such as MATLAB scripts.
docs	Any design related documentations, specifications, reports, etc.
project.tcl	The script used to recreate the associated Vivado project.

Demos

RTL Vivado Project Design Demo

1. Initialize project directory structure

   Copy the ./template folder to target engineering project folder (./projects/<engProj>). Then rename the folder to <gitProj>.

2. Create Vivado RTL Project

   • For single project mode, create Vivado RTL Project named project in ./projects/<engProj>/<gitProj>/project with option Create project subdirectory unchecked . The location of the Vivado project should be ./projects/<engProj>/<gitProj>/project.

   • For multi project mode, create Vivado RTL Project named <vivadoProj> in ./projects/<engProj>/<gitProj>/project with option Create project subdirectory checked . The location of the Vivado project should be ./projects/<engProj>/<gitProj>/project/<vivadoProj>.

3. Add RTL sources

   • Add existing RTL sources (e.g. ./projects/<engProj>/<gitProj>/rtl/<rtlName>.v) via File -> Add Sources -> Add or create design sources -> Add Files with option Copy sources into project unchecked.

   • Create new RTL sources via File -> Add Sources -> Add or create design sources -> Create File, change the File location to ./projects/<engProj>/<gitProj>/rtl. Several subdirectories can be created to group modules with distinct functions.

4. Add IP

   • Add existing IP (e.g. ./projects/<engProj>/<gitProj>/ip/<ipName>.xcix) via File -> Add Sources -> Add or create design sources -> Add Files with option Copy sources into project unchecked.

   • Create new IP. First, create Manage IP project with IP location at ./projects/<engProj>/<gitProj>/ip. Then, use the Manage IP project to customize and manage IP, and generate output products. Finally, add IP ./projects/<engProj>/<gitProj>/ip/<ipName>.xcix via ile -> Add Sources -> Add or create design sources -> Create File to the Vivado project with option Copy sources into project unchecked. Several subdirectories can be created to group IPs with distinct functions.

5. Add IPI Block Design

   • Add existing ipi-bd file (e.g. ./projects/<engProj>/<gitProj>/ipi-bds/<bdName>/<bdName>.bd) and its wrapper (assuming the wrapper is generated with option Let Vivado manage wrapper and auto-update, e.g. ./projects/<engProj>/<gitProj>/ipi-bds/<bdName>/hdl/<bdName>_wrapper.v) via File -> Add Sources -> Add or create design sources -> Add Files, with option Copy sources into project unchecked.

   • Create new ipi-bd via Flow -> Create Block Design, change the Directory to ./projects/<engProj>/<gitProj>/ipi-bds. Once the IPI design is complete, generate the wrapper with option Let Vivado manage wrapper and auto-update.

6. Add Constraints

   • Add existing constraint file (e.g. ./projects/<engProj>/<gitProj>/constraints/<constraintName>.xdc) via File -> Add Sources -> Add or create constraints -> Add Files with option Copy constraints files into project unchecked.

   • Create new constraint file via File -> Add Sources -> Add or create constraints -> Create File, change the File location to ./projects/<engProj>/<gitProj>/constraints. Several subdirectories may be created to group constraints with distinct functions.

   • Create new constraints with GUI interactively. Remember to change the File location to ./projects/<engProj>/<gitProj>/constraints before saving any constrains.

7. Add Simulation Sources

   • Add existing testbench (e.g. ./projects/<engProj>/<gitProj>/testbenches/<testbenchName>.v) via File -> Add Sources -> Add or create simulation sources -> Add Files with option Copy sources into project unchecked.

   • Create new testbenches via File -> Add Sources -> Add or create simulation sources -> Create File, change the File location to ./projects/<engProj>/<gitProj>/testbenches. Several subdirectories can be created to group modules with distinct functions.

   The stimulus files should be included in testbenches folder.

8. Run Synthesis, Implementation and Generate Bitstream via Flow -> Run Synthesis, Flow -> Run Implementation and Flow -> Generate Bitstream

9. (Optional) Export Hardware and Develop Xilinx SDK/Vitis Programmes

10. Generate Project Recreation Script

    Create new script used to recreate the Vivado project via File -> Project -> Write Tcl with all checkbox set as default, set Output File to be ./projects/<engProj>/<gitProj>/project.tcl.

11. (Optional) Archive Project

    Archive the Vivado project into a compressed zip file via File -> Archive, change Archive location to anywhere except the git repository, because the archived project is currently not under revision control. The archive command copies all local or remote sources and run results, so the archive is self-contained.

RTL Vivado Project Recreate Demo

1. Pull the Repository to Local (Sparse checkout Recommended).

2. Source the Project Script

   Open Vivado. In Tcl Console, change current working directory to ./projects/<engProj>/<gitProj>.

   cd ./projects/<engProj>/<gitProj>
   

   Make sure all files included the script header are present, then source the script.

   source ./project.tcl
   

   Xilinx recommends sourcing the Tcl script from the same directory in which the project was created, to maintain the relative path between the current working directory and the source files.