"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

Tom

Graduate Engineer

BSc - Physics, University of Southampton

I started working at ITDev in April of 2018 as a graduate engineer, working within the electronics engineering department. During my degree I studied a broad range of topics including particle physics and orbital mechanics, both areas in which I used computational physics to aid in problem solving. I particularly enjoyed developing my own simulation to model planetary orbits in binary star systems.

My graduate experience at ITDev has been very enjoyable. Working on projects alongside experienced engineers creates a fast learning environment, and the friendly and supportive team have helped me to develop my skills as an engineer.

Outside of work I enjoy getting out into nature. I enjoy long distance walking and wildcamping, and have walked almost 1000 miles of the national trail network.

View all posts by Tom    |    View all ITDev team members

IET Enterprise Partners logo

Latest Blog Posts

Vivado plus Git icons
Posted 6th May 2020, By Tom J
Maintaining a neat and tidy desk is something many of us are familiar with. Doing the same for your FPGA repository can be slightly more challenging. Tom ...more
Linux penguin
Posted 1st May 2020, By Quentin D
Are you thinking about contributing to the Linux kernel? Let's have a look at how our internal 'Linux Maintainers Group' does it with Quentin's detailed guide ...more
Raspberry Pi image
Posted 9th April 2020, By Kris D
So you’ve got a project that needs both low and high-level interfacing. Perhaps it requires the use of multiple sensors or inputs to determine an output or ...more
Posted 18th March 2020, By Simon H
We recently used the Raspberry Pi as the basis of an Industrial IoT proof of concept. Here Simon reviews the benefits of this approach and why it was suitable ...more

Latest News

Spring 2020
Posted 17th April 2020
Following the beautiful weather over the Easter weekend, we are proud to be able to provide an update on our current activities, showing business is continuing ...more
Business as usual
Posted 20th March 2020
With a strong commitment to keeping our staff and clients safe during this period, we would like to reassure all our business contacts that we remain fully ...more
South Coast Tech Awards Trophy
Posted 6th December 2019
ITDev was excited to attend the first South Coast Technology Awards on Thursday 5th December at the Ageas Bowl. A much needed celebratory awards for a sector ...more
South Coast Tech Awards Finalist nomination image
Posted 31st October 2019
We're proud to announce that ITDev has been shorlisted as a Finalist in the Best 'Tech Employer' category in the South Coast Tech Awards.