One of the skills which FPGA developers need to master is that of working with source control tools such as git. A few months ago I posted Hackster project which shows the basics of how to work with git, this project uses simple RTL and test bench source in its example.
Of course when we are working with Vivado we need to be able to also work with source control, while also working with the products of an IP centric design. This includes IP Integrator block diagrams and IP Instantiations either stand alone or as part of the IP Integrator design.
At first this might seem a little daunting, but with versions of Vivado 2022.1 and later this is straight forward. In this blog we will look through and explain how to add project files to a remote git repo and then clone to a different location and rebuild the project.
One of the key aspects for working with Vivado and source control is understanding the directory structure. One of the changes introduced from Vivado 2022.1 onwards is separation of source and generated files. Previously all source and associated generated files were stored together in the .srcs directory. Vivado 2022.1 onwards separated the source and generated files into their own directories with sources located under .srcs and generated files under .gen.
This means to recreate a project all we need to source control are .srcs directory and the project .xpr file if we have these we can recreate a project.
Lets take a look at how we can do this.
The first thing we need to do, is create a new project in Vivado 2024.1, this project will be targeting a Avnet ZU Board. The design created in IP Integrator will contain a Zynq MPSoC Processing System, Smart Interconnect and AXI Bram Controller. I also added in custom RTL source files which provide AXI access over the UART to show how custom RTL files can be included.
The completed diagram should look as below.
If we then explore the project directories created by Vivado we will see the following.
Looking into the sources files we will see the added VHD files, under the imports directory.
While the bd directory we will see the IP and block diagram files.
Under the IP directory we will find the .xci configuration file for each of the IP on the block diagram.
Exploring the .gen file will show the generated file for the top level VHDL (we let Vivado generate and manage it). Along with all of the generated files necessary for the IP, synthesis and simulation.
Having created a repo on my github account (MZ553) we can begin to add the project files into the git repo.
The first thing we need to do is initialise the repo, we can go this using the command
git initWith the repository initialised the next step is to add in the .xpr file and the .srcs directory we do this by using the command
git add git_demo.srcs/*git add git_demo.xprAt this stage we have told git we wish to monitor and source control the selected files. But we still have a long way to go before they appear in the github repository on line. The next step is to commit the files with a message
git commit -m “initial issue”This should show the files which have been added to the repository you will see the xpr, vhd and ip files.
We are now in a position that we can set the remote origin using the command
git remote add origin <url>
To push our data to the remote repository we can use the command
git push -u origin masterThe pushes the repository to the remote origin, opening the github web page should now see the files on the remote repository.
Of course having pushed the design to the repository we want to ensure we can rebuild the design. To do this I created a new directory and cloned the repository into it.
Having cloned the repository successfully I could then open the project, this will take a few minutes but we will see the project opening.
One of things you will notice is the generated top level wrapper is not included in the download as it was a generated file. We can easily regenerate the file again, and implement the design which when I tried it ran through with no issues.
Of course, as we change things in the design we need to add and update the git repository, you can do this using either the git terminal like I have used in this example, the git GUI or anther program. I tend to use smart git.
Of course we can still use the write_project_tcl and write_bd_tcl should we wish to and in some cases this makes sharing the project even easier.
In another blog soon we will look at how to work with Vitis and source control.
Workshops and Webinars
If you enjoyed the blog why not take a look at the free webinars, workshops and training courses we have created over the years. Highlights include
Professional PYNQ Learn how to use PYNQ in your developments
Introduction to Vivado learn how to use AMD Vivado
Ultra96, MiniZed & ZU1 three day course looking at HW, SW and PetaLinux
Arty Z7-20 Class looking at HW, SW and PetaLinux
Mastering MicroBlaze learn how to create MicroBlaze solutions
HLS Hero Workshop learn how to create High Level Synthesis based solutions
Perfecting Petalinux learn how to create and work with PetaLinux OS
Embedded System Book
Do you want to know more about designing embedded systems from scratch? Check out our book on creating embedded systems. This book will walk you through all the stages of requirements, architecture, component selection, schematics, layout, and FPGA / software design. We designed and manufactured the board at the heart of the book! The schematics and layout are available in Altium here Learn more about the board (see previous blogs on Bring up, DDR validation, USB, Sensors) and view the schematics here.
Sponsored by AMD
Comments