Vivado Projects in GitHub Repositories

This page contains information on setting up and working with GitHub managed Vivado repositories, in the style used by the tclbits "repo_files.tcl" script.

Background

To give a bit of history - Xilinx does not work well with version control. They never have, and I doubt they ever will. Vivado routinely touches internal project files so that virtually everything would need to be updated almost any time a project is opened, and Vitis frighteningly hides fixed paths in its configuration, meaning that any time a collaborator would check something out, the project would immediately stop working. I don't use "frighteningly" lightly in this case, since Vitis is built upon Eclipse, which has great GitHub integration - but attempting to use it with Vitis breaks the entire project.

The most common method I have seen to deal with this is to abandon Vivado project integration entirely and work solely with a command-line build script. I chose not to go this way because for me, I feel that the Vivado project integration speeds my workflow, and it was easier to change Vivado than to abandon those advantages. Because Vivado is built upon Tcl, it is not hard to change it.

Setting Up

As noted in the repo README, you need a Vivado_init.tcl script which replaces the open_project and close_project commands with ones that allow for per-project setup and teardown. An example script is in the repo here.

On Windows, I would also recommend using subst to create a virtual drive to shorten path lengths as described here.

Under the Hood

The basic ideas behind GitHub managed repositories are:

1. Keep the Vivado project in a subdirectory (vivado_project) and don't store anything from there (via gitignores).
2. Keep all sources in their own subdirectories (ip/, hdl/, constraints/, bd/, sim/).
3. For IPs and block diagrams, store only the descriptions (.xci or .bd) and let Vivado rebuild them, ignoring generated files (via gitignores).
4. Store the list of files in the Vivado project in tracked files (sources.txt, ips.txt, simulation.txt, constraints.txt, simips.txt).
5. Automatically check the internal list of files (what Vivado thinks is in the project) against those files at project open (this can be run while the project is open using the check_all Tcl command)
6. Automatically save the internal list of files to those tracked files at project close (this can be run while the project is open using the save_all Tcl command).
7. Change any Vivado project settings via Tcl commands at project open in the project_init.tcl script.

Recreating a Managed Repository

1. Clone the repository. Make sure to do it recursively as submodules are very common (git clone --recursive).
2. Open Vivado, or if it's already open, close the current project to get to the "welcome screen."
3. In the Tcl console, change directories to where you cloned the repository (cd path/to/repo).
4. Source the setup script, typically a Tcl file with the same name as the repository. This creates an empty project and opens it - and with the most recent project creation script, runs the project_init.tcl file to reload all of the sources.

Note: the next step should no longer be necessary for project creation scripts which auto-source the project_init.tcl at the end. You will know if this step is needed if step 4 completes quickly and the project is empty of source files.

5. Click the Tcl console table in Vivado, and in the entry window (where it says "Type a Tcl command here") type "source project_init.tcl". This will then take some time as it adds all of the files to the project. Note that previously this step was "close and reopen the project," but you should not do this as it can blow away the source tracking files. If you did this and the source tracking files are all empty, close Vivado and checkout all the ".txt" files in the top directory.

The project is now recreated. Building the project is the same as any other Vivado project. The first build will take quite some time as all of the IP files and block diagrams have to be rebuilt.

Adding Files/IP/Block Diagrams to Managed Repository

Never create a file/constraint/IP/Block Diagram in Vivado's default location ("local to project"). Vivado, by default, stores things in subdirectories underneath its project directory. Source files do not have to be in a specific location in the repository, but a conventional structure (which allows for simple gitignores) would be

• hdl/ contains Verilog/VHDL/etc. files used in the implementation
• sim/ contains Verilog/VHDL/etc. files used in simulation only - testbenches, models, etc. - plus waveconfigs (.wcfg).
• ip/ contains .xci files (each in their own subdirectory) for Vivado IP.
• bd/ contains block diagram (.bd) files (each in their own subdirectory).
• constraints/ contain .xdc and .tcl files used as constraints.

The repo_files.tcl maintenance commands make it easy to identify if you've accidentally created a source file in the default location - just check all of the .txt files for vivado_project (e.g. grep "vivado_project" *.txt).

Changing Build Settings

Whenever you change the build settings in Vivado, you need to make sure those changes are propagated to anyone else using the repository by having them happen in the project_init.tcl script. For instance, if you change the Verilog include directories, or add scripts that run during steps of the build, or change the build steps or settings.

A lot of these changes can be done using utility functions in the utility.tcl script. For changes that do not have utility functions, just look at what happens in the Tcl console when the settings is changed, and use that Tcl command.

For instance, changing the Route directive to AggressiveExplore results in

set_property STEPS.ROUTE_DESIGN.ARGS.DIRECTIVE AggressiveExplore [get_runs impl_1]

and enabling Post-Route Phys Opt Design results in

set_property STEPS.POST_ROUTE_PHYS_OPT_DESIGN.IS_ENABLED true [get_runs impl_1]

Creating a New Managed Project

To create a new managed project in the simplest way:

1. Create a directory named the same as your repository (this_project/) - we will call this repo_dir because the project_init.tcl template will create a function called get_repo_dir which you can call from the Tcl console.
2. Create a Vivado project in a vivado_project subdirectory of the repo_dir (this_project/vivado_project) as normal.
3. Run git init in the repo_dir.
4. Run git submodule add https://github.com/barawn/verilog-library-barawn/ in the repo_dir.
5. Copy the project_init_template.tcl and project_deinit_template.tcl templates into the repo_dir, renaming them to project_init.tcl and project_deinit.tcl.
6. Edit them to enable sourcing utility.tcl and repo_files.tcl, and uncomment the save_all and check_all function calls.
7. Copy and rename the top_gitignore from gitignores into the repo_dir as .gitignore. If you use IPs or BDs, you can create subdirectories for them and add their gitignores (ip_gitignore and bd_gitignore as well).
8. Copy and rename the project_create_template.tcl file into the repo_dir (conventionally named as <repository name>.tcl) and edit it to change the repository name and the part number.
9. Close and reopen the project. You are now ready to use the project. Remember when creating files/IPs/BDs that they do not go in the default location, but anywhere else in the repo_dir other than vivado_project.