Local Version Control for Block Designs in Vivado

Tested with:

  1. Vivado 2022.2
  2. git-bash.exe

Intro:

In this article, I work through creating a minimal environment for setting up version control in Vivado on a single, local machine. I choose to create a TCL script with the write_tcl command suggested by Xilinx. However, the Xilinx documentation is a bit convoluted. The end of the article includes a couple of common errors that I ran into, as well as some thoughts on expanding this version control to work on different machines.

Vivado is a GUI based editor that works mainly as a wrapper around TCL scripts.

For anybody working on a project of any complexity, it is immediately clear why you would need version control across different block diagrams for testing and prototyping.

Prerequisites:

  1. Add the bin folder in Vivado to local environment variables

In order to run the vivado -mode tcl command in git-bash, I have to add the Vivado bin folder to the path. You can do this by going to environment variables and adding the bin folder for Vivado to the environment path. For us, the folder was found at C:\Xilinx\Vivado\<version number>\bin. vivado -mode tcl allows us to to run TCL scripts.

Version control in Vivado

1. Creating the project structure

I recommend creating a new folder for your project on a mounted hard drive. The TCL script that is generated by Vivado includes multiple absolute paths, which are easier to handle on a separate mounted drive.

Create the RTL project as usual on your mounted hard drive. In this tutorial, I will demonstrate the removal of two IP blocks in Vivado with version control.

2. Export TCL script with write_tcl

After creating the initial version of the project, go to File -> Project -> Write TCL. Change the path of the output folder for the TCL script to the mounted hard drive parent folder from earlier.

3. Which files to check into source control

Open the TCL script, in the header, it should list the files that should be checked into.

Check these files into git-bash.

Comment: At this point, it may be useful to add a .gitignore file in order to clean up the repository. I have provided a link to the .gitignore below that I use to clean up the repository.

At this point, I also delete the two IP blocks from the block design and check that into git-bash as well.

4. Confirming version control functionality

In order to re-generate the projects, go into git-bash and run the command vivado -mode tcl.

Run the command source <project name>.tcl. If everything runs successfully, it should recreate a folder in the parent directory called <project name>_Copy. You can confirm that the block diagram is recreated successfully.

Comment: I personally use git to clean my repository between runs. If you have used the .gitignore file that I provided1, you can use the command git clean -dfxn to confirm the files to clean, then git clean -dfx in order to remove the journal files and other junk that Vivado creates. This command also cleans up cached IP block implementations though, so be careful.

Here I delete two IP blocks, re-check the .bd files into version control, then re-generate the project.

Common errors that I ran into:

  • Absolute file paths

If you check the actual TCL script generated by write_tcl, you will see that there are a large number of hard-coded absolute paths in the TCL script. If you have an existing project that you want to add to version control, it might be difficult to reconfigure it.

I don’t recommend separating your project structure and output TCL script, as if you run it on a different machine, it will throw errors related to being unable to find the block design (.bd files) from the original machine.

  • Version controlling the .xpr project file

This file is like an xml file and also includes a lot of hard-coded absolute paths. I tried version controlling the project file itself instead of using the write_tcl function, but that was a mess and didn’t work.

Things to look forward to:

1. Dockerizing

George Hotz dockerized ISE on stream 2 and it would be useful to do something similar for Vivado. However, with the node-locked license, it may be difficult to recreate. Check out this post on the Xilinx forums for someone who did something similar. 3

2. Running synthesis and implementation + Vitis IDE workflow in TCL scripts.

There’s a way to run the entire workflow including the C code in Vitis and flash the board. Since Vitis IDE is an Eclipse wrapper, version control for it is pretty basic. In the future, I might do some testing around writing the entire workflow straight through. AMD calls this “Non-project mode” in the docs, but it seems unreasonable to try to do any FPGA work in Xilinx without the assistance of the GUI.

3. Testing version control of remote sources

I haven’t tested version controlling remote sources in Vivado. If anyone gives it a try, let me know!

Footnotes:

  1. https://gist.github.com/josephmaa/51006e1053a2758005078a5ff23742d0 ↩

  2. https://www.youtube.com/watch?v=bN8CSGCsM1w ↩

  3. https://www.reddit.com/r/FPGA/comments/bk8b3n/dockerizing_xilinx_tools/ ↩

2023

Back to Top ↑

2022

Detecting Traffic Flow

Learning about the architecture of model focused on a spatio-temporal graph convolutional neural network.

Back to Top ↑