Tcl Scripts for Automatic Build Identification

[#1]

Tcl Scripts for Automatic Build Identification

Description

This guide demonstrates several ways to add automatic build identification to your projects using Tcl scripts. The two scripts presented in this guide create either a Verilog module or a Memory Initialization File (MIF) that contains a timestamp, the host name, and the physical address from your machine at compilation time. These scripts can be run manually or can be executed automatically each time you compile your design.

Before You Begin

This guide assumes that you have prior experience using Quartus II as well as some familiarity with Verilog and Tcl. To run the scripts presented in this guide, you must have the following software installed:

• The Quartus® II software version 4.1 or later

Reference Scripts

Two Tcl scripts are provided with this guide in the build_identification.zip file: the Build ID Verilog Module Script (build_id_verilog.tcl) and the Build ID Memory Initialization File Script (build_id_mif.tcl).

The Build ID Verilog Module Script 

The build_id_verilog.tcl script generates a Verilog file (build_id.v) with a module (build_id) that contains a timestamp, physical address, and host name for the current build. These values are available from the build_date, build_time, physical_address, and host_name output ports of the build_id module in the build_id.v Verilog source file.

The format for each value is as follows:

• Build Date
  • Width: 32 bits
  • Format: Decimal number of the format mmddyyyy
• Build Time
  • Width: 32 bits
  • Format: Decimal number of the format hhmmss
• Physical Address
  • Width: 48 bits
  • Format: Hexadecimal number
• Host name
  • Width: 120 bits
  • Format: Hexadecimal number with pairs of digits equal to ASCII code for the first 15 characters of the host name. For added clarity, host names with fewer than 30 hexadecimal digits (15 characters) are padded on the left with zeros.

The follow code is an example output of the build_id_verilog.tcl script:

// Build ID Verilog Module

//

// Date: 08012011

// Time: 083920

// Physical Address: 12-34-56-78-9A-BC

// Host Name: MY-COMPUTER

module build_id

(

output [31:0] build_date,

output [31:0] build_time,

output [47:0] physical_address,

output [119:0] host_name

);

assign project_date = 32'd08012011;

assign project_time = 32'd083920;

assign physical_address = 48'h123456789ABC;

assign host_name = 120'h000000004d592d434f4d5055544552;

endmodule

The Build ID Memory Initialization File Script 

The build_id_mif.tcl script generates a Memory Initialization File (build_id.mif) that contains a timestamp, physical address, and host name for the current build. The address range and format for each value is as follows:

• Build Date
  • Address range: 00 to 03
  • Width: 32 bits
  • Format: Unsigned integer of the format mddyyy (represented in hexadecimal in the MIF)
• Build Time
  • Address range: 04 to 07.
  • Width: 32 bits
  • Format: Unsigned integer of the format hhmmss (represented in hexadecimal in the MIF)
• Physical Address:
  • Address range: 08 to 0f.
  • Width: 64 bits
  • Format: Unsigned long integer.
• Host name
  • Starting address: 10.
  • Format: Null-terminated ASCII string.

The follow code is an example output of the build_id_mif.tcl script:

-- Build ID Memory Initialization File

--

-- Date: 08012011

-- Time: 083920

-- Physical Address: 12-34-56-78-9A-BC

-- Host Name: MY-COMPUTER

DEPTH = 28

WIDTH = 8;

ADDRESS_RADIX = HEX;

DATA_RADIX = HEX;

CONTENT

BEGIN

-- Build Date

000 : 00;

001 : 7A;

002 : 40;

003 : EB;

-- Build Time

004 : 00;

005 : 01;

006 : 47;

007 : D0;

-- Physical Address

008 : 00;

009 : 00;

00a : 12;

00b : 34;

00c : 56;

00d : 78;

00e : 9A;

00f : BC;

-- Host Name

010 : 4D;

011 : 59;

012 : 2D;

013 : 43;

014 : 4F;

015 : 4D;

016 : 50;

017 : 55;

018 : 54;

019 : 45;

01a : 52;

01b : 00;

END;

Running the Scripts

Both scripts can be run manually through theTcl Console in Quartus or can be added to the compilation flow to run automatically with each build.

To run the scripts manually:

1. In Quartus, open the Tcl Console by selecting View > Utility Windows > Tcl Console or by pressingAlt + 2.
2. In the console, type either of the following commands as shown in Figure 1:

• source build_id_verilog.tcl
  • source build_id_mif.tcl

Figure 1 – Running the Build ID Memory Initialization Script in the Tcl Console 6/67/Running_the_Build_ID_script.png

After the script has finished running, a confirmation message will be displayed in the Messages Window, shown in Figure 2. If the Messages Window is not visible, open it by selecting View > Utility Windows > Messages or by pressing Alt + 3.

Figure 2 – Confirmation message from the Build ID Memory Initialization Script 3/3b/Build_ID_confirmation.png

To run the scripts automatically with each build:

1. In Quartus, open the Tcl Console by selecting View > Utility Windows > Tcl Console or by pressing Alt + 2.
2. In the console, type either command:

• set_global_assignment -name PRE_FLOW_SCRIPT_FILE quartus_sh:build_id_verilog.tcl
  • set_global_assignment -name PRE_FLOW_SCRIPT_FILE quartus_sh:build_id_mif.tcl

These commands tell Quartus to automatically run the selected script before each compilation. The Verilog module or Memory Initialization File will be regenerated every time you compile your design.

Downloads

• build_identification.zip - Tcl scripts and documentation

Additional Resources

• Tcl Scripting – Quartus II Handbook v11.0.0, Volume 2, Chapter 3
• Memory Initialization File (.mif) Definition – Quartus II Help v11.0