launch_runs - 2021.2 English

Vivado Design Suite Tcl Command Reference Guide (UG835)
Document ID
UG835
Release Date
2021-10-22
Version
2021.2 English

Launch a set of runs

Syntax

launch_runs [‑jobs <arg>] [‑scripts_only] [‑lsf <arg>] [‑sge <arg>]
    [‑cluster_configuration <arg>] [‑dir <arg>] [‑to_step <arg>]
    [‑next_step] [‑host <args>] [‑remote_cmd <arg>] [‑email_to <args>]
    [‑email_all] [‑pre_launch_script <arg>] [‑post_launch_script <arg>]
    [‑custom_script <arg>] [‑force] [‑quiet] [‑verbose] <runs>...

Usage

Name Description
[-jobs] Number of jobs Default: 1
[-scripts_only] Only generate scripts
[-lsf] Use LSF to launch jobs. Required argument is the bsub command line to pass to LSF Default: empty
[-sge] Use SGE to launch jobs. Required argument is the qsub command line to pass to SGE Default: empty
[-cluster_configuration] Run jobs on a particular cluster configuration (picks cluster configuration from GUI settings). Default: empty
[-dir] Launch directory
[-to_step] Last Step to run. Ignored when launching multiple runs. Not valid with -next_step
[-next_step] Run next step. Ignored when launching multiple runs. Not valid with -to_step.
[-host] Launch on specified remote host with a specified number of jobs. Example: -host {machine1 2} -host {machine2 4}
[-remote_cmd] Command to log in to remote hosts Default: ssh -q -o ConnectTimeout=30 -o ConnectionAttempts=3 -o BatchMode=yes
[-email_to] List of email addresses to notify when jobs complete (only applicable with -host)
[-email_all] Send email after each job completes (only applicable with -host)
[-pre_launch_script] Script to run before launching each job (only applicable with -host)
[-post_launch_script] Script to run after each job completes (only applicable with -host)
[-custom_script] User run script map file which contains run name to user run script mapping
[-force] Run the command, even if there are pending constraint changes, which will be lost (in a Dynamic Function eXchange design)
[-quiet] Ignore command errors
[-verbose] Suspend message limits during command execution
<runs> Runs to launch

Categories

Project

Description

Launches synthesis and implementation runs when running the Vivado tools in Project Mode. Refer to the Vivado Design Suite User Guide: Design Flows Overview (UG892) for a complete description of Project Mode and Non-Project Mode.

A run must be previously defined using the create_run command, and the properties of the run must be previously configured using the set_property command. Both synthesis and implementation runs can be specified in the same launch_runs command. However, to launch an implementation run, the parent synthesis run must already be complete.

In Non-Project Mode, Vivado synthesis can be launched directly using the synth_design command, and does not require the use of a defined run.

In Non-Project Mode, Vivado implementation steps can be launched individually with the opt_design, power_opt_design, place_design, route_design, phys_opt_design, and write_bitstream commands.

Arguments

-jobs <arg> - (Optional) The number of parallel jobs to run on the local host. The number of jobs for a remote host is specified as part of the -host argument. You do not need to specify both -jobs and -host.

-scripts_only - (Optional) Generate a script called runme.bat for each specified run so you can queue the runs to be launched at a later time.

-lsf <arg> - (Optional) Use IBM Platform Load Sharing Facility (LSF) to launch synthesis and implementation runs. The bsub command line to pass to LSF must be specified as a required argument.

-sge <arg> - (Optional) Use Oracle Grid Engine or Sun Grid Engine (SGE) to launch synthesis and implementation runs. The qsub command line is a required argument to submit a job to SGE.

-cluster_configuration <arg> - (Optional) Run jobs on a particular cluster configuration. Name of the cluster configuration is specified to submit a job on a particular cluster.
  • To get the list of the cluster configurations, use the get_cluster_configurations command.
  • To create a cluster configuration, use the create_cluster_configuration command.
  • To remove a cluster configuration, use the remove_cluster_configurations command.
  • To validate a cluster configuration, use the validate_cluster_configurations command.

-dir <arg> - (Optional) The directory for the tool to write run results into. A separate folder for each run is created under the specified directory. As a default the tool will write the results of each run into a separate folder under the <project>.runs directory.

-to_step <arg> - (Optional) Launch the run through the specified step in the implementation process, and then stop. For instance, run implementation through the place_design step, and then stop. This will allow you to look at specific stages of a run without completing the entire run. The following are the valid steps for implementation runs.
  • opt_design - Optionally optimize the logical design to more efficiently use the target device resources. This step is usually enabled by default even though it is an optional step.
  • power_opt_design - Optionally optimize elements of the logic design to reduce power demands of the implemented FPGA.
  • place_design - Place logic cells onto the target device. This is a required step.
  • power_opt_design (Post-Place) - Optionally optimize power demands of the placed logic elements. This step must be enclosed in quotes or braces since it includes multiple words (e.g. -to_step "power_opt_design (Post-Place)" ).
  • phys_opt_design - Optionally optimize design timing by replicating drives of high-fanout nets to better distribute the loads.
  • route_design - Route the connections of the design onto the target FPGA. This is a required step.
  • write_bitstream - Generate a bitstream file for Xilinx device configuration. This is a required step.
Note: The specified -to_step must be enabled for the implementation run using the set_property command, or the Vivado tool will return an error.
-next_step - (Optional) Continue a prior run from the step at which it was stopped. This option can be used to complete a run previously launched with the -to_step argument.
Note: The -to_step and -next_step arguments may not be specified together, and are ignored when launching multiple runs.
-host <args> - (Optional) Launch on the named remote host with a specified number of jobs. The argument is in the form of {<hostname> <jobs> }, for example: -host {machine1 2}. If the -host argument is not specified, the runs will be launched from the local host.
Note: This argument is supported on the Linux platform only.

-remote_cmd <arg> - (Optional) The command to use to login to the remote host to launch jobs. The default remote command is "ssh -q -o BatchMode=yes".

-email_to <args> - (Optional) Email addresses to send a notification to when the runs have completed processing. This option also requires the use of -host with an SMTP server running to send Email notifications.

-email_all - (Optional) Send a separate Email for each run as it completes. This option also requires the use of -host with an SMTP server running to send Email notifications.

-pre_launch_script <arg> - (Optional) A shell script to run on the specified host before launching each job. This option also requires the use of -host.

-post_launch_script <arg> - (Optional) A shell script to run on the specified host after completion of all jobs. This option also requires the use of -host.

-custom_script <arg> - (Optional) Specify a script map file, which contains a mapping of run names and scripts to launch for that run.

-force - (Optional) Launch the run regardless of any pending constraint changes for Partial Reconfiguration designs.
Note: This argument applies only to Partial Reconfiguration projects. Any pending constraint changes will be lost to the specified runs.
-quiet - (Optional) Execute the command quietly, returning no messages from the command. The command also returns TCL_OK regardless of any errors encountered during execution.
Note: Any errors encountered on the command-line, while launching the command, will be returned. Only errors occurring inside the command will be trapped.
-verbose - (Optional) Temporarily override any message limits and return all messages from this command.
Note: Message limits can be defined with the set_msg_config command.

<runs> - (Required) The names of synthesis and implementation runs to launch. One or more run names may be specified.

Examples

The following command launches three different synthesis runs with two parallel jobs: 
launch_runs synth_1 synth_2 synth_4 -jobs 2
Note: The results for each run will be written to a separate folder synth_1, synth_2, and synth_4 inside of the <project>.runs directory.
The following example creates a results directory to write run results. In this case a separate folder named impl_3, impl_4, and synth_3 will be written to the specified directory. In addition, the -scripts_only argument tells the tool to write runme.bat scripts to each of these folders but not to launch the runs at this time. 
launch_runs impl_3 impl_4 synth_3 -dir C:/Data/FPGA_Design/results -scripts_only
The following example configures the impl_1 run, setting options for Vivado Implementation 2013, enabling some of the optional optimizations, and then launches the run to the place_design step: 
set_property flow {Vivado Implementation 2013} [get_runs impl_1]
set_property STEPS.POWER_OPT_DESIGN.IS_ENABLED true [get_runs impl_1]
set_property STEPS.POST_PLACE_POWER_OPT_DESIGN.IS_ENABLED true \
   [get_runs impl_1]
set_property STEPS.PHYS_OPT_DESIGN.IS_ENABLED true [get_runs impl_1]
launch_runs -to_step place_design impl_1

See Also