Intel® Quartus® Prime Pro Edition User Guide: Scripting

ID 683432
Date 12/04/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

4.1.30.33. qed::launch_connection (::quartus::qed)

The following table displays information for the qed::launch_connection Tcl command:

Tcl Package and Version

Belongs to ::quartus::qed

Syntax qed::launch_connection [-h | -help] [-long_help] [-open_project] [-open_timeout <open_timeout> ] [-force_open] [-load_db_state] [-async] [-timeout <timeout> ] <object>
Arguments -h | -help Short help
-long_help Long help with examples and possible return values
-open_project Flag to open the project once the connection is established
-open_timeout <open_timeout> Timeout for opening the project once the connection is established (0 = no timeout)
-force_open Flag to use -force when running project_open on the remote side
-load_db_state Flag to load the necessary compilation database state for the accessor executable once the connection is established and the project is open. For example, if the accessor executable is "quartus_sta", this initializes the timing netlist
-async Flag indicating not to wait for any issued remote commands to complete. With this flag, the return value is a token that can be passed to qed::get_return_value. By default, the return value of the remote command is reproduced (including any errors)
-timeout <timeout> Optional timeout for waiting for a return value in ms (default = 0 = no timeout)
<object> Identifier associated with the object, must be unique
Description
Starts one or more instances of the Quartus Prime Pro software running
in the background, to receive commands from the shell where the
workspace is open.

In most cases, you should use the "-open_project" option so that the
Quartus Prime Pro project is opened automatically after the software
instance has started. By default, the command does not open the
Quartus Prime Pro project after starting the instance of the software.

Use the "-timeout" option to specify the maximum time to wait for
the background instance of the Quartus Prime Pro software to start. The
timeout value is specified in seconds, and its default is 0, which
means to wait forever. Specifying "-timeout 0" is equivalent to
not using the "-timeout" option.

Use the "-load_db_state" option to prepare the project for
analysis after it opens. This option has no effect if you do not also
use the "-open_project" option, or if the project has no complete
compliation database. The initialization steps depend on the executable
that is started.

For example, when you use the Timing Analyzer
executable (quartus_sta), loading the compilation database follows the
initialization procedure in the Quartus Prime Timing Analyzer GUI:
 * create the timing netlist
 * read SDC files
 * update the timing netlist

The "-async" option causes the command to returns a token for use
with the "qed::get_return_value" command. By default the command will
wait, or block, until the background instances of the Quartus Prime
software have started, and any project opening or timing initialization
options have completed.

When you call "qed::launch_connection" with a project object without the
"-async" option, the command returns the value of whatever parts
of the initialization flow you have specified. Any errors that occur
starting the background software instance, opening the project, and
initializing timing, are returned with standard Tcl error semantics.

When you call "qed::launch_connection" with a project group object
without specifying the "-async" option, the command returns a Tcl dict where
keys are IDs of the projects in the project group, and the values are
two-element lists of the form { <code> <result> }. If the <code> value
is 1, the "launch_connection" command received an error starting
the background software instance, opening the project, or initializing
timing. When the <code> value is 1, the <result> contains the
received error message. If the <code> value is 0, the
"launch_connection" command was successful for the project, and
the <result> value contains the return value of whatever parts of the
initialization flow you have specified.

Information needed to start the Quartus Prime Pro background
software instances is set through the compute spec, which
is stored in an object property called compute_spec_arg.

You can set the compute spec on the workspace object,
on a project group object, and on individual
project objects. The "qed::launch_connection" command reads
the compute specs with a defined priority to determine how to
start the background software instances. First the
workspace compute spec is read, then a project group compute
spec, then a project compute spec.
If a conflict of compute specs occurs, the compute spec of a
project object overrides the compute spec of the project group
it is in, and the compute spec of a project group overrides the
compute spec of the workspace. This priority allows you to specify
a default compute spec at the workspace level and override or
customize it if necessary for project groups or projects.

Because the Quartus Exploration Dashboard supports a variety of
compute farms, and each type of compute farm has unique,
related requirements, you must use a command unique to each
type of compute farm to configure it. Refer to help for the
appropriate commands described below for details.

 * To execute on the local machine running the Quartus
    Exploration Dashboard, use the "qed::configure_local_compute_spec"
    command
 * To execute through the LSF workload management software,
    use the "qed::configure_lsf_compute_spec" command
 * To execute by connecting to remote machines with the ssh command,
    use the "qed::configure_ssh_compute_spec" command
Example Usage
    qed::create_object -type project project_A -qpf_path /file/path/to/project.qpf

    qed::launch_connection project_A
Return Value Code Name Code String Return
TCL_OK 0 INFO: Operation successful