To keep memory requirements as low as possible, only the minimum number of packages load automatically with each Intel^® Quartus^® Prime executable. To run commands from other packages, load those packages beforehand.

Run your scripts with executables that include the packages you use in the scripts. For example, to use commands in the sdc_ext package, you must use the quartus_sta executable because quartus_sta is the only executable with support for the sdc_ext package.

The following command prints lists of the packages loaded or available to load for an executable, to the console:

<executable name> --tcl_eval help

For example, type the following command to list the packages loaded or available to load by the quartus_fit executable:

quartus_fit --tcl_eval help

load_package [-version <version number>] <package name>

This command is similar to package require, but it allows to alternate between different versions of an Intel^® Quartus^® Prime Tcl package.

• This command opens the Intel^® Quartus^® Prime Command-Line and Tcl API help browser, which documents all commands and options in the Intel^® Quartus^® Prime Tcl API. At a system command prompt, access the Intel^® Quartus^® Prime Tcl API Help by typing:

  quartus_sh --qhelp

• The Tcl API Help can be accessed from the Tcl console as well. At a Tcl prompt, type

  help

  to access the help information. The output is:

help

help -tcl

help -pkg <package_name -[-version <version number>]

help -pkg ::quartus::project

help -pkg project

help -pkg project -version 1.0

<command_name> -h

<command_name> -help

project_open -h

project_open -help

package require ::quartus::<package name>[<version>]

package require ::quartus::project 1.0

load_package <package name> [-version <version number>]

load_package ::quartus::project -version 1.0

help -cmd <command_name>
	  -[-version <version>]

<command_name> -long_help

project_open -long_help

help -cmd project_open

help -cmd project_open -version 1.0

help -examples

help -quartus

quartus_sh --qhelp

help -timequestinfo

"TimeQuestInfo"

The Tcl API help is also available in Intel^® Quartus^® Prime online help. Search for the command or package name to find details about that command or package.

-<argument name> <argument value>

The cmdline package is included in the < Intel^® Quartus^® Prime directory>/common/tcl/packages directory.

For example, to run a script called myscript.tcl with one argument, Stratix^® , type the following command at a system command prompt:

quartus_sh -t myscript.tcl 
               Stratix®
             

quartus_sta -s

Commands you type in the Tcl shell are interpreted when you press Enter. To run a Tcl script in the interactive shell type:

source <script name>

If a command is not recognized by the shell, it is assumed to be external and executed with the exec command.

For example, the following command runs the Tcl command that prints out the commands available in the project package.

quartus_sh --tcl_eval help -pkg project 

Tcl messages appear in the System tab (Messages window). Errors and messages written to stdout and stderr also are shown in the Intel^® Quartus^® Prime Tcl Console window.

Click Project > Generate Tcl File for Project to automatically generate a .tcl file containing your assignments. You can source this file to recreate your project, and you can add other commands to this file, such as commands for compiling the design. This file is a good starting point to learn about project management and assignment commands.

• The execute_module command allows you to run an individual Intel^® Quartus^® Prime command-line executable.
• The execute_flow command allows you to run some or all the executables in commonly-used combinations.

Use the flow package instead of system calls to run Intel^® Quartus^® Prime executables from scripts or from the Intel^® Quartus^® Prime Tcl Console.

quartus_sh -t compile_revisions.tcl <project name> 

Compile All Revisions

load_package flow
project_open [lindex $quartus(args) 0]
set original_revision [get_current_revision]
foreach revision [get_project_revisions] {
	set_current_revision $revision
	execute flow -compile
}
set_current_revision $original_revision
project_close

If you know the exact report cell or cells you want to access, use the get_report_panel_data command and specify the row and column names (or x and y coordinates) and the name of the appropriate report panel. You can often search for data in a report panel. To do this, use a loop that reads the report one row at a time with the get_report_panel_row command.

Column headings in report panels are in row 0. If you use a loop that reads the report one row at a time, start with row 1 to skip column headings. The get_number_of_rows command returns the number of rows in the report panel, including the column heading row. Since the number of rows includes the column heading row, continue your loop if the loop index is less than the number of rows.

Report panels are hierarchically arranged and each level of hierarchy is denoted by the string “||“ in the panel name. For example, the name of the Fitter Settings report panel is Fitter||Fitter Settings because it is in the Fitter folder. Panels at the highest hierarchy level do not use the “||” string. For example, the Flow Settings report panel is named Flow Settings.

The following Tcl code prints a list of all report panel names in your project. You can run this code with any executable that includes support for the report package.

Print All Report Panel Names

load_package report
project_open myproject
load_report
set panel_names [get_report_panel_names]
foreach panel_name $panel_names {
post_message "$panel_name"
}

You can create a Comma Separated Value (.csv) file from any Intel^® Quartus^® Prime report to open with a spreadsheet editor.

The following Tcl code shows a simple way to create a .csv file with data from the Fitter panel in a report.

Create .csv Files from Reports

load_package report
project_open my-project
load_report
# This is the name of the report panel to save as a CSV file
set panel_name "Fitter||Fitter Settings"
set csv_file "output.csv"
set fh [open $csv_file w]
set num_rows [get_number_of_rows -name $panel_name]
# Go through all the rows in the report file, including the
# row with headings, and write out the comma-separated data
for { set i 0 } { $i < $num_rows } { incr i } {
	set row_data [get_report_panel_row -name $panel_name \
		-row $i]
	puts $fh [join $row_data ","]
}
close $fh
unload_report

You can modify the script to use command-line arguments to pass in the name of the project, report panel, and output file to use. You can run this script example with any executable that supports the report package.

The Intel^® Quartus^® Prime software includes comprehensive Tcl APIs and SDC extensions for the Timing Analyzer in the sta, and sdc_ext packages. The Intel^® Quartus^® Prime software also includes a tdc package that obtains information from the Timing Analyzer.

The following three global assignments control when a script is run automatically:

• PRE_FLOW_SCRIPT_FILE —before a flow starts
• POST_MODULE_SCRIPT_FILE —after a module finishes
• POST_FLOW_SCRIPT_FILE —after a flow finishes

A module is another term for an Intel^® Quartus^® Prime executable that performs one step in a flow. For example, two modules are Analysis and Synthesis (quartus_syn), and timing analysis (quartus_sta).

A flow is a series of modules that the Intel^® Quartus^® Prime software runs with predefined options. For example, compiling a design is a flow that typically consists of the following steps (performed by the indicated module):

1. Analysis and Synthesis (quartus_syn)
2. Fitter (quartus_fit)
3. Assembler (quartus_asm)
4. Timing Analyzer (quartus_sta)

Other flows are described in the help for the execute_flow Tcl command. In addition, many commands in the Processing menu of the Intel^® Quartus^® Prime GUI correspond to this design flow.

To make an assignment automatically run a script, add an assignment with the following form to the .qsf for your project:

set_global_assignment -name <assignment name> <executable>:<script name>

The Intel^® Quartus^® Prime software runs the scripts.

<executable> -t <script name> <flow or module name> <project name> <revision name>

The first argument passed in the argv variable (or quartus(args) variable) is the name of the flow or module being executed, depending on the assignment you use. The second argument is the name of the project and the third argument is the name of the revision.

set process  [lindex $quartus(args) 0]
set project  [lindex $quartus(args) 1]
set revision [lindex $quartus(args) 2]

project_open $project -revision $revision

When you use the POST_MODULE_SCRIPT_FILE assignment, the specified script is automatically run after every executable in a flow. You can use a string comparison with the module name (the first argument passed in to the script) to isolate script processing to certain modules.

set_global_assignment -name PRE_FLOW_SCRIPT_FILE quartus_sh:first.tcl
set_global_assignment -name POST_MODULE_SCRIPT_FILE quartus_sh:next.tcl
set_global_assignment -name POST_FLOW_SCRIPT_FILE quartus_sh:last.tcl

When you compile your project, the PRE_FLOW_SCRIPT_FILE assignment causes the following command to be run before compilation begins:

quartus_sh -t first.tcl compile top rev_1

Next, the Intel^® Quartus^® Prime software starts compilation with analysis and synthesis, performed by the quartus_syn executable. After the Analysis and Synthesis finishes, the POST_MODULE_SCRIPT_FILE assignment causes the following command to run:

quartus_sh -t next.tcl quartus_syn top rev_1

Then, the Intel^® Quartus^® Prime software continues compilation with the Fitter, performed by the quartus_fit executable. After the Fitter finishes, the POST_MODULE_SCRIPT_FILE assignment runs the following command:

quartus_sh -t next.tcl quartus_fit top rev_1

Corresponding commands are run after the other stages of the compilation. When the compilation is over, the POST_FLOW_SCRIPT_FILE assignment runs the following command:

quartus_sh -t last.tcl compile top rev_1

For example, if you want a script to run only after timing analysis, use a conditional test like the following example. It checks the flow or module name passed as the first argument to the script and executes code when the module is quartus_sta.

Restrict Processing to a Single Module

set module [lindex $quartus(args) 0]
if [string match "quartus_sta" $module] {
	# Include commands here that are run
	# after timing analysis
	# Use the post-message command to display
	# messages
	post_message "Running after timing analysis"
}

set_location_assignment -to address[10] Pin_M20

The Intel^® Quartus^® Prime software defaults to natural bus naming. You can turn off natural bus naming with the disable_natural_bus_naming command. For more information about natural bus naming, type the following at an Intel^® Quartus^® Prime Tcl prompt:

enable_natural_bus_naming -h

• -r
• -re
• -rev
• -revi
• -revis
• -revisio

There are two Intel^® Quartus^® Prime Tcl commands for working with collections, foreach_in_collection and get_collection_size. Use the set command to assign a collection ID to a variable.

foreach_in_collection Example

set all_instance_assignments [get_all_instance_assignments -name *]
foreach_in_collection asgn $all_instance_assignments {
	# Information about each assignment is
	# returned in a list. For information
	# about the list elements, refer to Help
	# for the get-all-instance-assignments command.
	set to [lindex $asgn 2]
	set name [lindex $asgn 3]
	set value [lindex $asgn 4]
	puts "Assignment to $to: $name = $value"
}

get_collection_size Example

set all_global_assignments [get_all_global_assignments -name *]
set num_global_assignments [get_collection_size $all_global_assignments]
puts "There are $num_global_assignments global assignments in your project"

The message type can be one of the following:

• info (default)
• extra_info
• warning
• critical_warning
• error

If you do not specify a type, Intel^® Quartus^® Prime software defaults to info.

With the Intel^® Quartus^® Prime software in Windows, you can color code messages displayed at the system command prompt with the post_message command. Add the following line to your quartus2.ini file:

DISPLAY_COMMAND_LINE_MESSAGES_IN_COLOR = on

The following example shows how to use the post_message command.

post_message -type warning "Design has gated clocks"

The global variable quartus(args) is a list of the arguments typed on the command-line following the name of the Tcl script.

cmdline Package

package require cmdline
variable ::argv0 $::quartus(args)
set options {
   { "project.arg" "" "Project name" }
   { "frequency.arg" "" "Frequency" }
}
set usage "You need to specify options and values"
array set optshash [::cmdline::getoptions ::argv $options $usage]
puts "The project name is $optshash(project)"
puts "The frequency is $optshash(frequency)"

If you save those commands in a Tcl script called print_cmd_args.tcl you see the following output when you type the following command at a command prompt.

Passing Command-Line Arguments for Scripts

quartus_sh -t print_cmd_args.tcl -project my_project -frequency 100MHz
The project name is my_project
The frequency is 100MHz

Virtually all Intel^® Quartus^® Prime Tcl scripts must open a project. You can open a project, and you can optionally specify a revision name with code like the following example. The example checks whether the specified project exists. If it does, the example opens the current revision, or the revision you specify.

Full-Featured Method to Open Projects

package require cmdline
variable ::argv0 $::quartus(args)
set options { \
{ "project.arg" "" "Project Name" } \
{ "revision.arg" "" "Revision Name" } \
}
array set optshash [::cmdline::getoptions ::argv0 $options]
# Ensure the project exists before trying to open it
if {[project_exists $optshash(project)]} {
	if {[string equal "" $optshash(revision)]} {
		# There is no revision name specified, so default
		# to the current revision
		project_open $optshash(project) -current_revision
	} else {
		# There is a revision name specified, so open the
		# project with that revision
		project_open $optshash(project) -revision \
			$optshash(revision)
	}
} else {
	puts "Project $optshash(project) does not exist"
	exit 1
}
# The rest of your script goes here

If you do not require this flexibility or error checking, you can use just the project_open command.

Simple Method to Open Projects

set proj_name [lindex $argv 0]
project_open $proj_name

help -quartus

Tcl commands are executed immediately as they are typed in an interactive Tcl shell. You can also create scripts (including the examples in this chapter) in files and run them with the Intel^® Quartus^® Prime executables or with the tclsh shell.

puts "Hello world"

Use double quotation marks to group the words hello and world as one argument. Double quotation marks allow substitutions to occur in the group. Substitutions can be simple variable substitutions, or the result of running a nested command. Use curly braces {} for grouping when you want to prevent substitutions.

set a 1

To access the contents of a variable, use a dollar sign (“$”) before the variable name. The following example prints "Hello world" in a different way.

set a Hello
set b world
puts "$a $b"

• Variable value substitution
• Nested command substitution
• Backslash substitution

set a [string length foo]

puts "This is a \$ special character"

puts "This is a\
$ special character and line continuation"

puts "This is backslash \is ignored"

puts "This is backslash\
	continued on next line"

set a 5
set b [expr { $a + sqrt(2) }]

The Intel^® Quartus^® Prime software supports all standard Tcl boolean and arithmetic operators, such as && (AND), || (OR), ! (NOT), and comparison operators such as < (less than), > (greater than), and == (equal to).

set a { 1 2 3 }

You can use the lindex command to extract information at a specific index in a list. Indexes are zero-based. You can use the index end to specify the last element in the list, or the index end-< n> to count from the end of the list. For example, to print the second element (at index 1) in the list stored in a use the following code.

puts [lindex $a 1]

The llength command returns the length of a list.

puts [llength $a]

The lappend command appends elements to a list. If a list does not already exist, the list you specify is created. The list variable name is not specified with a dollar sign (“$”).

lappend a 4 5 6

To set an element with an index of Mon to a value of Monday in an array called days, use the following command:

set days(Mon) Monday

The array set command requires a list of index/value pairs. This example sets the array called days:

array set days { Sun Sunday Mon Monday Tue Tuesday \
	Wed Wednesday Thu Thursday Fri Friday Sat Saturday }

set day_abbreviation Mon
puts $days($day_abbreviation)

Use the array names command to get a list of all the indexes in a particular array. The index values are not returned in any specified order. The following example is one way to iterate over all the values in an array.

foreach day [array names days] {
	puts "The abbreviation $day corresponds to the day\
name $days($day)"
}

Arrays are a very flexible way of storing information in a Tcl script and are a good way to build complex data structures.

 If-Then-Else Structure

if { $a > 0 } { 
	puts "The value is positive"
} elseif { $a < 0 } {
	puts "The value is negative"
} else {
	puts "The value is zero"
}

The following example uses a for loop to print each element in a list.

For Loop

set a { 1 2 3 }
for { set i 0 } { $i < [llength $a] } { incr i } {
	puts "The list element at index $i is [lindex $a $i]"
}

The following example uses a foreach loop to print each element in a list.

 foreach Loop

set a { 1 2 3 }
foreach element $a {
	puts "The list element is $element"
}

The following example uses a while loop to print each element in a list.

while Loop

set a { 1 2 3 }
set i 0
while { $i < [llength $a] } {
	puts "The list element at index $i is [lindex $a $i]"
	incr i
}

You do not have to use the expr command in boolean expressions in control structure commands because they invoke the expr command automatically.

 Simple Procedure

proc multiply { x y } {
	set product [expr { $x * $y }]
	return $product
}

The following example shows how to use the multiply procedure in your code. You must define a procedure before your script calls it.

 Using a Procedure

proc multiply { x y } {
	set product [expr { $x * $y }]
	return $product
}
set a 1
set b 2
puts [multiply $a $b]

Define procedures near the beginning of a script. If you want to access global variables in a procedure, use the global command in each procedure that uses a global variable.

 Accessing Global Variables

proc print_global_list_element { i } {
	global my_data
	puts "The list element at index $i is [lindex $my_data $i]"
}
set my_data { 1 2 3}
print_global_list_element 0

Tcl includes commands to read from and write to files. You must open a file before you can read from or write to it, and close it when the read and write operations are done.

To open a file, use the open command; to close a file, use the close command. When you open a file, specify its name and the mode in which to open it. If you do not specify a mode, Tcl defaults to read mode. To write to a file, specify w for write mode.

Open a File for Writing

set output [open myfile.txt w]

Tcl supports other modes, including appending to existing files and reading from and writing to the same file.

The open command returns a file handle to use for read or write access. You can use the puts command to write to a file by specifying a file handle.

Write to a File

set output [open myfile.txt w]
puts $output "This text is written to the file."
close $output

You can read a file one line at a time with the gets command. The following example uses the gets command to read each line of the file and then prints it out with its line number.

Read from a File

set input [open myfile.txt]
set line_num 1
while { [gets $input line] >= 0 } {
	# Process the line of text here
	puts "$line_num: $line"
	incr line_num
}
close $input

Tcl uses the hash or pound character (#) to begin comments. The # character must begin a comment. If you prefer to include comments on the same line as a command, be sure to terminate the command with a semicolon before the # character. The following example is a valid line of code that includes a set command and a comment.

set a 1;# Initializes a

Without the semicolon, the command is invalid because the set command does not terminate until the new line after the comment.

The Tcl interpreter counts curly braces inside comments, which can lead to errors that are difficult to track down. The following example causes an error because of unbalanced curly braces.

# if { $x > 0 } {
if { $y > 0 } {
	# code here
}

• Brent B. Welch and Ken Jones, and Jeffery Hobbs, Practical Programming in Tcl and Tk (Upper Saddle River: Prentice Hall, 2003)
• John Ousterhout and Ken Jones, Tcl and the Tk Toolkit (Boston: Addison-Wesley Professional, 2009)
• Mark Harrison and Michael McLennan, Effective Tcl/Tk Programming: Writing Better Programs in Tcl and Tk (Boston: Addison-Wesley Professional, 1997)

The following revision history applies to this chapter:

To use the Intel^® Quartus^® Prime Command-Line and Tcl API Help browser, type the following command:

quartus_sh --qhelp

This command starts the Intel^® Quartus^® Prime Command-Line and Tcl API Help browser, a viewer for information about the Intel^® Quartus^® Prime Command-Line executables and Tcl API.

Use the -h option with any of the Intel^® Quartus^® Prime Command-Line executables to get a description and list of supported options. Use the --help=< option name> option for detailed information about each option.

Figure 1.  Intel^® Quartus^® Prime Command-Line and Tcl API Help Browser

The following revision history applies to this chapter:

Refer to the following user guides for comprehensive information on all phases of the Intel^® Quartus^® Prime Pro Edition FPGA design flow.