Xilinx provides the Vivado FPGA (and Vitis software) tools for developing VHDL and Verilog FPGA designs. But they really don’t provide good information on setting up your project to work with Source Code Control (SCC). If you look through the Xilinx support forums you can see this has been a problem for at least a decade. Users were left to find their own solutions. Files for SCC were scattered throughout the directory structure. Finally, in recent years (2020 versions and later) Xilinx has attempted to address the problem by placing the files that need to be controlled under the <project.name>.srcs directory *. Unfortunately, they have not yet created a complete workable solution.
However, this document demonstrates my solution to the SCC problem using Git. This description assumes you know how to use Git (There are many good tutorials for Git online if you need help).
The SCC problem becomes a little more complicated if you are using an embedded processor such as Zync or Microblaze in your FPGA design. Handling the software SCC requires a different approach than is used with the FPGA code. This will be addressed in a later section.
* Most of the files for SCC are under <project.name>.srcs. However, the design wrapper file is in another directory as described later. Also, there are some other options and settings that are stored elsewhere. These files may need to be added to the SCC or the settings will be lost.
Applicable Vivado and Vitis Versions
This document describes a process to use Vivado and Vitis with Git for SCC. Note that this document refers to Vivado and Vitis 2022.1. This probably applies to other versions as well, but your mileage will vary. If you are using a different version, you may have to adapt your approach.
Vitis includes a plug-in to handle Git. I prefer to use Git directly (or use the ToroiseGit shell). In this document I am using a standalone version of Git. Use whatever Git tools you are most comfortable with.
By default, Vivado likes to generate the Vitis Software files in the same directory structure as the Vivado project. We decided to separate them for several reasons (see “How to Use Source Code Control with Vitis”).
How to Use Source Code Control with Vitis
Adding Vivado Files to Source Code Control
We have separate directory structures for the Vivado and Vitis development. The reasons for this are:
- The method to work with Vivado and Vitis using Git are different.
- The SW programmer only needs to have the .xsa file that describes the hardware configuration to do his work. The SW developer wants to have a consistent hardware interface to test the software against. This way, hardware changes do not complicate the debugging process. When the programmer is ready to incorporate the new hardware changes, those can be brought in.
- The process for SCC is different for the Vivado code and the Vitis code. Having separate project directories makes this easier. You cannot do an automatic merge of the Vivado files under Git because Git does not know and should not try to merge Vivado files.
Steps for adding initial Vivado files to Git - Create your initial project in Vivado.
- Generate a .bit file using Vivado.
- Export the hardware (File | Export Hardware) and make sure to check the box to include the Bitstream. Save this file to a directory that is NOT under the Vivado project directory. This will become your SW development directory. (Note that every time you export hardware Vivado will select the FPGA directory as the destination by default and you will need to select the SW dev directory instead.
- Exit Vivado so that it saves, closes and releases all file handles.
- Add all of the files in the .srcs directory to Git
- Add the design wrapper file (under ,project_name>.gen/board/<board_design>/hdl (replace ‘board_design’ with the name of your design) (*Updated 8/11/22)
- Add the .xpr file.
- (Optional) Add any .wcfg files you may have saved when running your simulations.
- Add any external .tcl sripts you may have written (i.e. I added a .tcl script VivadoUpgradePactch.tcl to address a bug in the tool where it was treating a warning that should be ignored as an error)
- Commit the files.
Steps for Adding Initial Vitis files to Git
- Create a Git repository in the src directory where you put your code.
- Check in all of your user source files.
- Do NOT check in the Xilinx.spec, ldscript.ld files located in your src directory. These are Vitis generated files.
- Check in the .xsa file that should be in the SW development directory.
Switching Branches In Vivado
Vivado generates hundreds of intermediate files. When you switch branches it is important that you delete all of these intermediate files or you will get unpredictable and wrong results. - Check in the top level .gitignore file (Vitis generates other .gitgnore files in subdirectories. Do not check these in)
- These should be the only files you check in. Do not check in any files from Vitis(eclipse) subdirectories. These files must be generated by Vivado. If you check them in and restore those files, Vitis will say it can’t find them even if the file exists.
- Close Vivado so that it saves any open files and releases their handles.
- In the FPGA directory, delete all files except .git Folder.
- Switch to the new branch.
- Use the Git Revert function to restore the user files from from the local Git repository (you could also pull them from the remote repository).
- Start Vivado.
- Open the project.
- Wait until Vivado finishes regenerating all of the necessary files. If you start making changes before Vivado has finished creating all of the files, you will get unpredictable results. In the “Sources” tab you will see the spinning update indicator. Wait until the update indicator goes away.
- In the TCL Console window, run the command “reset_project”.
- You are now ready to work in Vivado.
- If you are making changes to the FPGA code or adding new IP, you will need to Regenerate the BSP package for the SW (See document “How to Regenerate the Board Support Package (BSP) and Do a Clean Rebuild after FPGA Changes”)
Working with Git during SW development
You can check in files from your src repository as often as you wish. However, do NOT check the files in the Platform and System Files folder. If the FPGA code changes, you will need to update these files. But you must Regenerate the BSP before compiling
The Vitis IDE is based on a modified Eclipse Open Source IDE. None of the files other than the src directory, the .xsa and top level .gitnore should be stored in the repository. Some of the user customizations and settings are stored in the other directories. If you try to add them to your source code control, the IDE will fail to run properly. The Eclipse settings store the file name and a “magic” number associated with that file (maybe a CRC??) if the file name and number do not match, Eclipse will tell you it cannot find the file even if is there. Theses files must be generate by Vivado, not from Git or they will not work.
This means that any IDE customization must be added manually after cloning the repository.is
When Cloning the Vitis Project:
These instructions assume you are cloning the Vitis project for the 1st time and that you do not already have an existing Vitis firmware directory.
- Close Vitis if it is open
- Make sure Vivado is open.
- Do File | Export Hardware
- When “Export Hardware Platform” dialog appear, click Next
- Check “Include bitstream”, then click Next
- Leave XSA file name as is (design_1_wrapper is the default)
- Change the Export to: field to point to your software directory. (by default, it tries to put the software directory under the FPGA directory. We do not want that)
- Click Next
- Click Finish
- Use Vivado to launch Vitis (Tools | Launch Vitis IDE
- Choose Create Application Project
- Click Next on the information dialog
- Click on the Create a new platform for hardware (XSA)
- Click on the Browse button and select the .XSA file that you exported from Vivado (in your software directory).
- Click Next
- In “Application project name”, enter “your_project_name” (lower case). Do not enter anything in “System project name”. Vitis will automatically populate that field.
- Click Next.
- A dialog “Domain” will appear. Do NOT change anything. Click Next.
- The “Templates” dialog will open. Select “Empty Application (C++)
Click Finish. - Vitis will now generate the BSP and project files.
- Use Git to restore the “src” directory files and the top level .gitignore and .xsa file. These are the only files that should be in the firmware repository.
- Compile and run.
.
Switching Branches In Vivado
Vivado generates hundreds of intermediate files. It uses these files so it can do incremental compilation. When you switch branches it is important that you delete all of these intermediate files or you will get unpredictable and wrong results.
- Close Vivado so that it saves any open files and releases their handles.
- In the FPGA directory, delete all files except .git Folder.
- Switch to the new branch.
- Use the Git Revert function to restore the user files from Git.
- Start Vivado.
- Open the project.
- Wait until Vivado finishes regenerating all of the necessary files. If you start making changes before Vivado has finished creating all of the files, you will get unpredictable results.
- You are now ready to work in Vivado.
- If you are making changes to the FPGA code or adding new IP, you will need to Regenerate the BSP package for the SW (See document “How to Regenerate the Board Support Package (BSP) and Do a Clean Rebuild after FPGA Changes”)
.
Switching Branches in Vitis
Switching branches in Vitis is easier. However, since we are not adding the BSP to git (that causes problems with Vivado) the currently load BSP may not match the current FPGA configuration. If it does not, you will need to regenerate the BSP files (See document “How to Regenerate the Board Support Package (BSP) and Do a Clean Rebuild after FPGA Changes”)
NOTE: There are several references to the document “How to Regenerate the Board Support Package (BSP) and Do a Clean Rebuild after FPGA changes”. I will publish this document when time permits.