version control of vivado vhdl project

Question

I am wondering if there is a way of version control in vivado for a VHDL project. One way would be to add the version number to the bitstream file name.

Would that be possible? What other options are there if that isn't possible?

Thanks in advance

Answer 1

Think about what you require

• Version information format and size: What is the version? Is a natural number? String? Real? Do you save date or time stamp? Do you need a build number? Need extra space for sub-unit versions?

• Version source and design flow: What sets the version? Is it a source control tool? Do you manually set the version? Do you need automation to update parts of the version information (timestamp, build number, etc.)?

• Version accessibility/observability: Where do you want to read the version number and have it viewable? In the source code? External file? The bitstream file name? The flash file contents? Do you need the FPGA logic to be able to access the version information (to be read via communication channel, embedded processor, etc.)?

• Vendor Tools/Device/System/Source dependency: Implementation and automation of version information may depend on several things: Each vendor has different tools (even within the same vendor's). Different devices may allow you to do different things. The system where you work may allow different forms of automation (OS, installed script tools, etc.). The source files (VHDL, Verilog, System C, ...) and directory structure may influence the applicability of your solution.

---

Automation options

Makefile (builder script) automation

The most flexible way is to have some kind of builder script which may or may not be hooked to your source control mechanism (makefile, perl, python, etc.). Think about the transportability of your project between designers and even design platforms (Windows, Linux, etc.).

Pros:

• Complete control of what you want to do.
• Can be hooked to any source control automation.
• Can be modified to work on any platform when using standard tools (be sure to take special care of file paths which differ between OS).

Cons:

• Does not flow well with GUI vendor tools (see Vivado TCL hooks).

Vivado TCL hooks

Vivado has TCL hooks which you can use to run when you synthesize, implement, etc.

Using a pre-synthesis TCL hook will allow you to connect a script to run just before synthesis, and implement your version information update mechanism.

Using a post-bitstream TCL hook will allow you to connect a script to run just after bitstream file creation, and create a file name matching your updated version information, or other final operation you may require.

More information:
http://www.xilinx.com/support/documentation/sw_manuals/xilinx2014_4/ug894-vivado-tcl-scripting.pdf
http://www.xilinx.com/support/documentation/sw_manuals/xilinx2014_4/ug835-vivado-tcl-commands.pdf

Pros:

• Works with a GUI flow (automatically takes care of everything when you click on Synthesize).

Cons:

• (Vivado) tool dependent
• Need to remember to create the hooks in your Vivado project

---

Implementation options

Source code modification

Version number, build number, timestamp, and basically everything you need can be modified (within the VHDL/Verilog code) automatically using a script which parses a known file format. I've done this with Vivado TCL hooks and a well formatted package VHDL file. Works like a charm.

Note: When updating source files using pre-synthesis TCL hooks, Vivado will think the files were modified after, and will consider the implementation as not updated. I added to the script a command to save the current timestamp of the package file, updated it, and then wrote back the timestamp (meaning the package file will forever hold its system date and time).

Pros:

• Version information easily viewable accessible to designer (package file).
• Version information easily accessible for logic usage.
• Device independent.

Cons:

• Version information cannot be read by examining the bitstream file.
• Writing the script may take some work and may force you to a standardisation of your project sources directory structure [which may not be a totally bad thing ;) ]

Top level entity/module generic

Generics at the top level design module/entity can be modified by the Synthesis tool and accessed by the design's logic.

Pros:

• Less complicated scripting than modifying the source code.

Cons:

• Version information cannot be read by examining the bitstream file.
• You still need to save your version/build number somewhere (a file).
• For VHDL/Verilog, using generics is more complicated than using a package, since you need to wire the generics through your hierarchies until you reach the design code which writes the value to a register.
• Synthesis tool dependency. Different tools have different commands to update the top level generic values.

JTAG USERCODE

Most FPGAs support the IEEE Std. 1149.1 JTAG feature USERCODE, which gives the user a 32-bit value to identify the bitstream. This value can be set using the Vendor tools when creating the bitstream file. However, this value cannot be read by the FPGA's logic (unless you implement logic to read the flash and track the correct address for this value, which is a big overkill).

Pros:

• Fit for most devices.
• Version information is accessible by examining the file.

Cons:

• Version information cannot be read by the logic without extreme procedures.
• Limited information size (only 32 bits).

Xilinx USR_ACCESS Register

Similar to the JTAG USERCODE, Xilinx have a implemented a USR_ACCESS Register for Virtex-5, Virtex-6, and all 7 series devices. They provided a primitive for VHDL/Verilog to allow you to read the value via logic.

More information here: http://www.xilinx.com/support/documentation/application_notes/xapp497_usr_access.pdf

Pros:

• Version information can be read by the design logic.
• Version information is accessible by examining the file.

Cons:

• Solution for specific devices (not even all Xilinx devices support this).
• Limited information size (only 32 bits).

ROM static information

You can implement a version information ROM and use an external file to set its value. (see Verilog : Memory block Instantiation)

Pros:

• Can include large version information (even ASCII code).
• Version information viewable by the designer (external file).
• Fit for most devices and tools which accept the VHDL/Verilog code for ROM.

Cons:

• A bit more complicated logic may be required to read all the ROM (depends on how you implement it).
• It is difficult (yet possible) to examine version information by examining the file (You need to extract ROM bitstream locations).

Flash image modification

Many systems have their FPGAs load from flash devices. Usually there is more room than just the FPGA bitstream. It is possible to create a large flash image file to include extra information, among which is version information. This is probably to worst option of all I've written above, and mentioned this for completeness.

Pros:

• Potentially large information cache.
• Flash image file can be examined for version information.

Cons:

• Difficult to implement.
• Dependent on vendor tools.

---