vivado-202401/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](#vivado-git-repository)
  - [Table of Contents](#table-of-contents)
  - [Background](#background)
  - [How this repository is constructed?](#how-this-repository-is-constructed)
    - [Overview](#overview)
    - [Top Level](#top-level)
    - [Basic Vivado Project Structure](#basic-vivado-project-structure)
  - [Demos](#demos)
    - [RTL Vivado Project Design Demo](#rtl-vivado-project-design-demo)
    - [RTL Vivado Project Recreate 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

``` plain
.
├── .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](https://docs.xilinx.com/v/u/2019.1-English/ug892-vivado-design-flows-overview)), 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](https://docs.xilinx.com/v/u/2019.1-English/ug892-vivado-design-flows-overview) and several Vivado quick take videos.

1. [*Using Vivado Design Suite with Revision Control*](https://www.xilinx.com/video/hardware/vivado-design-suite-revision-control.html): explains basic concepts of Vivado revision control.

2. [*Configuring and Managing Reusable IP in Vivado*](https://www.xilinx.com/video/hardware/configuring-managing-reusable-ip-vivado.html): includes how to use Vivado Manage IP project.

3. [*IP Revision Control*](https://www.xilinx.com/video/hardware/ip-revision-control.html): 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>`.

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

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

   ``` tcl
   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.