Whoever is familiar with Vivado already knows that it generates a huge quantity of files and that understanding a proper version control thus seems to be not as simple. The truth is, that Vivado’s design indeed consist of a plenty of different file types, but most of them are auto generated and or managed by the GUI and or the IP integrator. This includes out-of context runs, caches, simulation files, test benches, waveform configurations, settings, checkpoint files and all files, that are on some level a part of a synthesis / implementation runs. Fortunately not all of these files needs to be versioned. There are 2 proper approaches to use the version control with Vivado. The first one is a so called non-project mode, which uses TCL scripting to properly include, configure, link and setup all files necessary to create a design, synthesize it, implement it and generate the resulting bitstream. In fact if you look closely at the GUI, it does basically the same as this scripting approach, but I would say its a bit easier to configure the various settings from the GUI rather than from a TCL script. Advantage of using the scripting mode is that you have a better control over that the script does and how it does it. You don’t need to include all the generated files as all the necessary design files are created during scripting and launching (Eg. no OOC runs are available) – this on the hand however eats more resources and design compilation time. Furthermore, manually creating, scripting and managing large files such as the BD files is time-consuming. A design may consist (among other files) from the following file types:

  • RTL Files (VHD / Verilog / System Verilog)
  • Constraints (.xdc )
  • IP files (.xcix)
  • DSP Files (.slx)
  • TCL Scripts (.tcl)
  • HLS files (.c / .h)
  • Documentation (.txt / doc …)

The key concept of Vivado’s version control for the project mode is in fact shown in one of the Xilinx’s quick take videos available here: https://www.youtube.com/watch?v=L17LvqkAv28 .Basically, It tells us the following: Manage all IP (.xcix) files from Vivado and make sure that they are not copied into the project. Instead one has to maintain a WORK directory for the Vivado project itself and leave all the design files outside the project (WORK directory). A good directory structure is in fact the key concept for the project mode as all the Vivado’s generated directories (.runs / .src / .cache / .sim / .hw … ) should be excluded from the version control.The only file from WORK directory, that should be included for version control is the .xpr project file. For BD files, Xilinx’s also recommends to create a special folder and include all the files within the folder for version control as well. I would only love to add that the “Generated products” for the BD should be managed on a global scale rather than “Per IP / Per BD”. 

This approach is still not completely Ideal, as one has to take extra care to use the same Vivado version and same directory structure for all users, since the paths inside the .xpr are absolute. The cooperation on files, which are harder to track should also be done with caution on per user basis – this includes the BD files / .slx files and or .xcix files for example. Overall, I believe this approach is excelent if one doesn’t have the time to properly script everything, but still would like to use the version control system with GUI. Furthermore, the IP/BD/SLX files are most of the time considered as static from my experience, although making a proper commits with changes may help in navigating what changes were made to the IPs.

 

I have created a reference VersionControl design for your own testing at gitlab.beechwood.eu  It uses Vivado 2019.1 version and the design is targeted for ZCU104 device. The default project path is at C:\vivado_versioncontrol (git clone via https link directly from C:/ drive on windows).

 

I found the Xilinx’s documentation quite useful as well, most notably the UG994 and UG892.