"Tidy repo policy" - how to make it work with Vivado

Call: +44 (0)23 8098 8890
E-mail:

Posted 6th May 2020, By Tom J
Vivado plus Git icons

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:

FPGA repository screenshot

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

IET Enterprise Partners logo

Latest Blog Posts

VPK120 development board pictured wearing ear defenders with silent smiley on the fan
Posted 13th June 2023, By Aysa D
This blog contains the final steps for adding the minimal IP to send the necessary SYSMON data to the System Controller for controlling the fan on the AMD ...more
VPK120 development board pictured wearing ear defenders
Posted 25th May 2023, By Aysa D
Whilst developing on an AMD Versal VPK120 you will want to control the fan speed to keep the noise at manageable levels. This guide captures the steps taken to ...more
Robin on a bird table
Posted 20th January 2023, By Andy C
The customer is always right, and he hasn't changed his requirements, but the consultant says they're in constant flux. Who's right? Let's explore further ...
JonO interviewing Matthew
Posted 30th June 2022, By Jon O
30th June and it's Matthew's 2 year anniversary of joining as a full-time member of staff. Matthew spent 2 summers working for us as an intern before joining ...more

Latest News

Posted 12th September 2023
ITDev is proud to announce the launch of a new FPGA video IP core. The core allows integrators to quickly and easily add high-quality colour space conversion ...more
Shot of Sydney Harbour Bridge
Posted 3rd March 2023
We welcome David back from Australia and review some of the actvities we've been engaged with in February 2023.
Posted 9th August 2022
Last month we attended the second TechNES FPGA Frontrunners event, here's our write up from the day ...
Posted 28th July 2022
Here's a short report on our attendance at the ECS Taster week Careers Fair On Tues 26th July. A chance to promote industrial opportunties to year 11 students ...more