Xilinx Vivado and Git

The easiest way to interact with source control systems in Vivado Projects is to use the Tcl scripted flow. The source files remain in their original locations and are passed to the Vivado synthesis and implementation (as reference).

There is a defined subset of Vivado Design Suite files that should be managed using revision control. There are a number of intermediate files generated by the Vivado that would be inefficient and unnecessary to manage. Items under version control in a typical Xilinx Vivado FPGA project:

• Scripts

  Scripts needed to create, recreate, generate, etc. the project.

• Block Design

  Top level with automatically generated and managed wrapper The block design is the primary source to recreate the design The top level wrapper HDL file shouldn’t be under version control since it can be recreated from the block diagram. It is not generated automatically, but there is a simple script to get around it.

• Custom IP cores

  Custom IP cores that are not available in a Vivado software. Copy the IPs “completely” in the IP folder; All IP directories and output product files with names intact. If using IP core constraints, the IP .xcix file with all third-party simulation and synthesis files in the ip_user_files and ip_static_files subdirectories.

• RTL and simulation test benches
  • All RTL-based source files including .include files
  • Simulation test benches and stimulus files
• Constraints:

  All XDC constraint files and Tcl commands used as constraints.

• HLS
  • All C source files
  • Packaged HLS IP for use in Vivado synthesis
  • Scripts
• SDK
  • Put the project file in the sdk folder.
  • the .gitignore will ignore the unnecessary files.
  • When there is a specific modification or a custom driver, put the bsp project as well.
• Documentation

  Any design related docs, specs, reports, etc.

The folder layout looks like this:

.
└── Project
  ├── bd
  │   └── design_1
  ├── ip
  ├── Makefile
  ├── scripts
  │   ├── build_bitstream.tcl
  │   ├── build_fpga.sh
  │   ├── create_project_tcl.tcl
  │   └── recreate_prj.tcl
  ├── sdk
  ├── work
  └── xdc

bd

the block design file (.bd)

ip

custom IP repository

scripts

TCL utility scripts

create_project.tcl

calls the write_project_tcl Vivado command with the correct parameters for the folder structure, to store the generated file () in the scripts folder and modifies it to regenerate the top level wrapper file when executed.

work

the temporary Vivado project files (not under version control)

xdc

contains the constraint file

Workflow:

Creating a Project

1. Create a new git local repository and add the files to it.

$ git init
~/vivado-project-template/.git/
$ git add .

1. Create your Vivado project and use work as the target directory. Make sure “create new directory” is not selected.
2. Create the block design. The block design has the same name as the project and it shoul be saved in the bd directory.
3. Generate the top level wrapper and let Vivado manage it.
4. (optional) Add your custom IP in the ip folder and add the ip folder to the IP Repository in your block design.
5. Proceed with the design and when it is finished, from the Vivado TCL console, run the create_project_tcl.tcl to create a script that will re-generate the Vivado project.

source scripts/create_project_tcl.tcl

1. Close Vivado and add two files to the git repo:

• the block design file
• the script that was generated when we executed create_project_tcl

$ git add bd/design_1/design_1.bd
$ git add scripts/recreate_prj.tcl
$ git commit -am "Initial commit"
 create mode .gitignore
 create mode Makefile 
 create mode bd/.gitignore
 create mode bd/design_1/design_1.bd
 create mode scripts/create_project_tcl.tcl
 create mode scripts/recreate_prj.tcl

All the other files can be regenerated so they don’t need to be under version control.

Re-create a Project

To recreate the project simply run the Makefile.

make

Now the project is recreated in the work directory the minimum source code files.

Notes:

• The various scripts assume a folders tree as described above.
• Before launching make, the work folder must be deleted (make clean takes care of that). This is “by design” since it avoids overwriting the project by mistake.
• The file recreate_prj.tcl must be under source version control.
• .gitignore files is used to avoid adding files generated by Vivado to the source version control repo.