At ITDev our values drive our decision making, the way we work and our relationships with our clients, suppliers and peers. We believe in a Smart approach to everything we do, whether that involves cutting edge video encoder development, the latest in open source software development, or something as comparatively trivial as maintaining a neat and tidy project repository.
This blog describes several workflows we have used to limit the number of files which need to be under version control when using Vivado, allowing for smaller and simpler project repositories. A repository should of course contain any source HDL files, the focus of this blog is on workflow suggestions for managing projects which also contain block designs and IP instances.
All FPGA engineers will be familiar with using version control systems in one form or another, and often when we use FPGA design tools such as Xilinx’s Vivado or Intel’s Quartus, we will end up with a large volume of temporary or otherwise inessential files which are generated during the build process. This is especially true for projects which contain multiple Xilinx/Intel IP instances. Maintaining a clean, streamlined and easy to use repository means deciding which of these files should be kept under version control. This can sometimes be challenging, especially since it is not always clear which files are absolutely necessary in order for FPGA tools to work, and which files can be safely discarded and regenerated later. One example would be that when using Altera’s Platform designer in Quartus Pro, removing a .qsys file may not cause failures in the build flow, but will prevent future edits to the IP cores. This can obviously cause problems further along in the development process, and highlights why an in-depth understanding of what the design tools are doing is useful.
Method 1: Keeping everything under version control
After a Vivado project is created it can be difficult to decide which of the project files should be placed under version control. The simplest method is, of course, to commit everything in a project repository, including all of the files generated during IP elaboration as well as log files and output files.
Pros
- No chance of losing files
- Extensive history of logs and reports
- Maximum flexibility for IP upgrades, version changes
Cons
- Large and cluttered repository
- Potential for large and confusing changesets between commits
- Potential to encounter unnecessary merge issues
Method 2: Partial version control using a tcl script
Vivado contains a tool to wrap an entire project into a tcl script. When Vivado is opened the script can be sourced to regenerate the project.
In the Vivado GUI select:
file->project->write tcl
and Vivado will generate a tcl script containing all the information necessary to regenerate the project. Only the tcl script and IP directories need to be kept under version control, the project file and sub-directories do not need to be committed. You can select whether the generated tcl script also contains any block design tcl scripts, or if they should be kept separately. When opening Vivado, use the tcl console to navigate to the project directory and source the tcl script, this will regenerate the project in its entirety.
Pros
- Lean and tidy repository
- No project file to commit – only the tcl script
- Similar method as exporting a BD (Block Design)
Cons
- No record of build logs
- Must be careful to source the tcl script from the appropriate directory
- Changesets are not always clear
Method 3: Lean version control using the project file and selected sources
Choosing which files to commit is fairly straightforward if you understand how Vivado manages a project. By using a text editor you can examine the Vivado project file:
<PROJECT_NAME>.xpr
to see which files are being sourced when the project opens. The project file will reference all HDL source files and the <pinout_filename>.xdc file. In order to source IP cores, the project file will reference:
<IP_NAME>.xci
Along with the BD file/tcl script, these files represent the bare minimum needed to regenerate the project, block design and IP cores. This means it can be possible to greatly reduce the number of files in a repository, albeit with a sacrifice in flexibility around such things as IP modification, version changes etc.
Pros
- Very lean repository
- Clear changesets
Cons
- No record of build logs
- Potential to break things if not handled carefully
- Can encounter issues when switching vivado version
Example
I’ll demonstrate below by building a small FPGA implementation containing a block design and a single instance of a Xilinx IP core, which targets a Xilinx Zynq Ultrascale+ development board. The repository had been intentionally reduced to the smallest possible size. Let’s take a look at the repository properties before we start a build.
This is the ‘clean’ pre-build directory immediately after checkout from the project repository. The single IP core has only it’s .xci file committed, and there is a tcl script to re-generate the block design. There is also a mixture of VHDL and Verilog source files as well as the Vivado project file and a constraints file. This directory contains 21 files in 5 folders, which constitute all the files necessary for someone to check out the repository and begin development, including opening the project in Vivado and building the FPGA image:
- <PROJECT_NAME>.xpr
- <CONSTRAINTS>.xdc
- <IP_NAME>.xci
- <BLOCK_DESIGN>.tcl
- HDL source files
If we open the project in Vivado and source the tcl script file to re-generate the block design, then run both the synthesis and implementation stages, we end up with the following in the same project folder:
We can see that the project folder has increased in size by a factor of over 300 during the build process, with Vivado creating several hundred folders and sub-folders containing files which have been generated during the IP elaboration, synthesis and implementation stages. This is a good demonstration of how bloated a version controlled repository can become if all files are blindly committed.
Summary
To summarise, it is usually best to take elements from each of these methods to tailor a version control strategy specific to each project. Each approach has its own merits and drawbacks, but by combining a good understanding of how Vivado works with some best practices for version control, it is possible to have a tidy, lean and easily maintainable repository which contains everything the engineers will need.
How ITDev Can Help
At ITDev we believe good engineering practice is essential to delivering high quality, engineered designs. Aligned with this we run a series of events and workshops to help develop industry best practices through collaborative sharing and learning.
Our team of engineers has extensive experience in FPGA design for both Xilinx and Intel (formerly Altera) devices. We provide technology consultancy as well as hardware & software design services. Initial discussions are always free of charge, so if you have any questions, or would like to find out more, we would be delighted to speak to you. Email us or call us on +44 (0)23 8098 8890.
Main image: Vivado and Git
