vivado-202304/README.md

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?
    • Top Level
    • Basic Project Structure

Background

Since the day I joined my lab, managing Vivado projects has always been a challenge 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-related project files and Verilog/VHDL files primarily, but it can also hold associated MATLAB files and related documentation explaining how the modules work and things that need to be taken care of when interfacing with the modules.

Top Level

The structure 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 (empty yet)	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	Project or board specific vivado projects, that can be run on hardware.	Yes	Yes	Yes
template	Project initialization template.	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

Basic Project Structure

As listed above, modules and 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, 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 our design sources outside of the Vivado project directory.

The basic 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: include how to use Vivado Manage IP project.

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

The structure is provided in the following table. It should be noted that anything listed below, except for the project directory, will be under revision control. For more details, one can refer to the .gitignore file.

Name	Description
constraints	All XDC constraint files and Tcl commands used as constraints.
docs	Any design related docs, specs, reports, etc.
ip	The IP source files and output products.
ipi-bds	The IP Integrator block design source file (.bd), along with IP subdirectory including IP source files and output products.
project	The Vivado projects. Each subdirectory contains a single Vivado project. Note that even if there is only one project, it should be included in a subdirectory so that the .gitignore file can correctly identify unwanted files.
rtl	All RTL-based source files including .include files.
scripts	Run scripts used to compile the design including any pre and post scripts used when launching runs, along with any other custom scripts.
testbenches	Simulation test benches and stimulus files.