Quartus® Prime Pro Edition User Guide: Platform Designer

ID 683609
Date 7/08/2024
Public
Document Table of Contents

7.7. Generate a Platform Designer System with qsys-script

You can use the qsys-script utility to create and manipulate a Platform Designer system with Tcl scripting commands. If you specify a system, Platform Designer loads that system before executing any of the scripting commands.
Note: You must provide a package version for the qsys-script. If you do not specify the --package-version=<value> command, you must then provide a Tcl script and request the system scripting API directly with the package require -exact qsys<version> command.

Platform Designer Command-Line Scripting

qsys-script --script=my_script.tcl \
--system-file=fancy.qsys

my_script.tcl contains:

package require -exact qsys 16.0
# get all instance names in the system and print one by one
set instances [ get_instances ]
foreach instance $instances {
    send_message Info "$instance"
}

You can use the following options with the qsys-script utility:

Table 207.  qsys-script Command-Line Options
Option Usage Description
--system-file=<file> Optional Specifies the path to a .qsys file. Platform Designer loads the system before running scripting commands.
--script=<file> Optional A file that contains Tcl scripting commands that you can use to create or manipulate a Platform Designer system. If you specify both --cmd and --script, Platform Designer runs the --cmd commands before the script specified by --script.
--cmd=<value> Optional A string that contains Tcl scripting commands that you can use to create or manipulate a Platform Designer system. If you specify both --cmd and --script, Platform Designer runs the --cmd commands before the script specified by --script.
--package-version=<value> Optional Specifies which Tcl API scripting version to use and determines the functionality and behavior of the Tcl commands. The Quartus® Prime software supports Tcl API scripting commands. The minimum supported version is 12.0. If you do not specify the version on the command-line, your script must request the scripting API directly with the package require -exact qsys < version > command.
--search-path=<value> Optional If you omit this command, a Platform Designer uses a standard default path. If you provide this command, Platform Designer searches a comma-separated list of paths. To include the standard path in your replacement, use "$", for example, /<directory path>/dir,$. Separate multiple directory references with a comma.
--quartus-project=<value> Optional Specifies the path to a .qpf Quartus® Prime project file. Utilizes the specified Quartus® Prime project to add the file saved using save_system command. If you omit this command, Platform Designer uses the default revision as the project name.
--new-quartus-project=<value> Optional Specifies the name of the new Quartus® Prime project. Creates a new Quartus® Prime project at the specified path and adds the file saved using save_system command to the project. If you omit this command, Platform Designer uses the Quartus® Prime project revision as the new Quartus® Prime project name.
--rev=<value> Optional Allows you to specify the name of the Quartus® Prime project revision.
--jvm-max-heap-size=<value> Optional The maximum memory size that the qsys-script tool uses. You specify this value as <size><unit>, where unit is m (or M) for multiples of megabytes, or g (or G) for multiples of gigabytes.
--metrics-log-file=[path_to_log_file]
Optional This switch creates a new file containing a set of metrics, at the path you specify. This switch must be used alongside the --record-metrics switch, or the switch does not function. The path to the log file must exist, or the FileDoesNotExists error appears. Platform Designer does not create any new directories listed in the path.
--record-metrics[=<foobar>]
Optional Enables metric logging. This feature logs the time Platform Designer takes to perform various operations. The other information includes:
  • The operation performed.
  • The IP instance name and its .ip file location.
  • The IP component type and its _hw.tcl file location.
The switch does not require a value, but it does accept a string value that has no effect on the metric logging. In the absence of the --metrics-log-file switch, Platform Designer creates the log file in the project directory with the name of metrics_<top-level name>.txt by default.
--help Optional Displays help for the qsys-script utility.