Version management is essential in FPGA projects; otherwise, questions like “Who wrote this?” and “Which version is running on the board?” can be quite frustrating. Today, we will discuss three common methods.

Why is Version Management Necessary for FPGAs?

• Some bugs are caused by new logic, and without version numbers, it is difficult to trace back.

• The version of the FPGA bitstream file is often hard to identify at a glance.

• During software or low-level driver debugging, confusion over FPGA versions can double debugging costs.

Method 1: Automatically Generate Compilation Timestamps with Vivado (The Simplest)

Using a Tcl script, automatically write the current date and time each time a bitstream is generated.

The key steps are as follows:

Create a new file version_date.v in the project with content similar to:

parameter [31:0] FPGA_VERSION_A = 32'h20250831; // Date
parameter [31:0] FPGA_VERSION_B = 32'h000000;   // Time

Write a Tcl script (e.g., update_version.tcl) to set the path in the synthesis settings, updating version_date.v each time you compile:

set file_addr "../../version_date.v"
set time_now [clock seconds]
set time0 [clock format $time_now -format "%Y%m%d"]
set time1 [clock format $time_now -format "%H%M%S"]
set f [open $file_addr w]
puts $f "parameter [31:0] FPGA_VERSION_A = 32'h$time0;"
puts $f "parameter [31:0] FPGA_VERSION_B = 32'h$time1;"
close $f

Include this version_date.v in the top-level Verilog:

assign version_date = FPGA_VERSION_A;
assign version_time = FPGA_VERSION_B;

Each time you debug on the board, read these two values in the logic or test interface to immediately know which version was compiled on which date.

Advantages: Fully automated, no need to write version numbers, updates on compilation

Disadvantages: File paths can easily be mistaken, especially since Windows systems are not sensitive to file paths, making this inclusion method hard to master

Method 2: Embed Compilation Timestamps in Bitstream Using USR_ACCESS (Officially Recommended)

Xilinx officially supports using the BITSTREAM.CONFIG.USR_ACCESS parameter set to TIMESTAMP during bitstream compilation, automatically writing the compilation time into the 32-bit USR_ACCESS register in the configuration stream (https://docs.amd.com/v/u/en-US/xapp1232-bitstream-id-with-usr_access). This value can also be read in FPGA logic through the USR_ACCESS primitive.

Specific process:

In the Vivado GUI: Go to Tools → Project Settings → Bitstream, find BITSTREAM.CONFIG.USR_ACCESS, set it to TIMESTAMP, and then regenerate the bitstream.

In the design, instantiate the Xilinx primitive, for example:

wire [31:0] version_id;
USR_ACCESSE2 usr_access_inst (
    .CFGCLK(), 
    .DATA(version_id), 
    .DATAVALID()
);

Add a control register in the FPGA or read version_id through the JTAG/SPI interface.

For detailed operation instructions, refer to the Xilinx application document XAPP1232.

https://docs.amd.com/v/u/en-US/xapp1232-bitstream-id-with-usr_access

Advantages:

Automation—no need to manually maintain version numbers.

Accurate information—the bitstream carries the timestamp, so there’s no fear of forgetting to update.

Easy to view—version information can be easily read through logic or software.

Disadvantages:

Information is fixed as a timestamp and cannot embed Git Hash or semantic versioning.

You still need to deploy the reading logic yourself.

Method 3: Automatically Inject Build Information (Best Engineering Practice)

This modern method is suitable for CI/CD and team projects: dynamically generate HDL source files containing version numbers and build times during the build process, then merge them into the design.

// Automatically generated file build_info.v
module build_info;
  localparam string GIT_HASH = "a1b2c3d";
  localparam string BUILD_DATE = "2025-08-30";
endmodule

Use scripts (shell, Python, etc.) in cmake/Makefile to obtain the Git hash and time, then write it:

echo "module build_info; localparam GIT_HASH = \"$HASH\"; localparam BUILD_DATE = \"$DATE\"; endmodule" > build_info.v

Then include “build_info.v” in the main project to read the version identifier.

Advantages:

The most comprehensive information (Git commit number, date, branch, etc. can all be included).

High degree of automation, suitable for team collaboration.

Easy to synchronize with software versions.

Disadvantages:

Initial setup is complex and requires script support.

Cross-platform (Windows/Linux) script compatibility needs attention.

Comparison Table of the Three Methods

Method	Degree of Automation	Information Content	Difficulty of Use	Recommended Scenarios
Automatic Timestamp version_date.v	High	Date + Time	Low	Quick start, personal projects
USR_ACCESS Timestamp	High	Compilation Timestamp	Medium	Xilinx platform projects
Automatically Inject Build Information	High	Git Hash + Time	Medium to High	Team/CI/CD projects

Conclusion: How to Choose the Most Reliable Method?

Want to save trouble? Just rename the project, but you may face “correction costs exploding” at any time.

Want to automatically and accurately know when this board was compiled? Choose the USR_ACCESS timestamp.

Want to synchronize with Git + software versions and plan for future CI/CD packaging? Go for the automatically injected source code solution.

Remember this: “An FPGA without a version number is more chaotic than bits.” “An FPGA project without version management will eventually kneel down in the debugging field.”

If anyone has better methods for version management or any questions about the above methods, feel free to leave a comment for discussion~

Disclaimer:This article is reproduced from the OPENFPGA WeChat public account. For issues related to content, copyright, and others, please contact the staff via WeChat (13237418207), and we will coordinate with you to delete it as soon as possible!Submissions/Recruitment/Advertising/Course Cooperation/Resource Exchange, please add WeChat: 13237418207

Previous Recommendations

Who says configuration is difficult? This article will help you easily master Xilinx 7 series FPGA configuration techniques

Using CCIX for Evaluating High-Speed Cache Coherency Host-to-FPGA Interfaces

FPGA Digital Signal Processing Communication Class I/Q Signal Generation

“180-Day FPGA Development Online Practical Training Course – Fanyi”

Scanthe codetoaddcustomerserviceWeChat,note“Join the group“tobringyouintoFanyiEducationOfficialTechnicalWeChatgroup,andconnectwithmanyexpertsinelectronictechnologytodiscusstechnicalissuesandshareinsights~