4.1.31.32. qed::launch_connection (::quartus::qed)

Quartus® Prime Pro Edition User Guide: Scripting

Download PDF

ID 683432

Date 9/29/2025

Version

Public

4.1.31.32. 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 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 project is opened automatically after the software instance has started. By default, the command does not open the Quartus Prime 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 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 background software instances is set through the compute spec, which is stored in an object property called compute_spec. See qed::get_inherited_compute_spec for more details. 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 "rpc::create_local_compute_spec" command * To execute through the LSF workload management software, use the "rpc::create_lsf_compute_spec" command * To execute by connecting to remote machines with the ssh command, use the "rpc::create_ssh_compute_spec" command Once created, a compute specification must be applied to a project, a group that contains the project, or the workspace itself before a project can use it to launch connections.
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