Details of the Sample Script - 2024.2 English

Vivado Design Suite User Guide: Using Tcl Scripting (UG894)

Document ID
UG894
Release Date
2024-11-13
Version
2024.2 English
  1. The project is created with the create_project command. The project directory and the target device are specified. The project directory is automatically created if it does not already exist.

    In this example, the output directory where the various reports are saved is the same as the project directory.

  2. All the files that are used in a project need to be explicitly declared and added to the project. This is done with the add_files command. When a file is added to the project, it is added to a specific fileset. A fileset is a container that groups files together for a purpose. In this example script, most of the files are added to the default fileset (sources_1). Only the Verilog test bench cpu_tb.v is added to the default simulation fileset sim_1.

    The files are also copied inside the project directories with the import_files command. By doing this, the project points to the local copy of the source files and does not track the original source files anymore.

  3. The design is synthesized by launching a synthesis run in the background (launch_run synth_1). The Vivado IDE automatically generates all the necessary scripts to run synthesis in a separate Vivado session. Because synthesis runs in a different process, it is necessary to wait for its completion before continuing the current script. This is done by using the wait_on_run command.

    Once the synthesis run is completed, the results can be loaded in memory with the open_run synth_1 command. A checkpoint without constraints is saved in the project directories, where synthesis was run. In this example, it can be found under:

    ./Tutorial_Created_Data/cpu_project/project_cpu.runs/synth_1/top.dcp
    Note: The names synth_1 and impl_1 are default names for the synthesis and implementation runs. Additional runs can be created with create_run command.
  4. The implementation is done by using the launch_run command. The complete P&R flow from pre-place optimization to writing the bitstream can be performed in a single command. In this example script, the implementation is done up to the bitstream generation (launch_run impl_1 -to_step write_bitstream).

The optional step phys_opt_design is enabled in the script through the property STEPS.PHYS_OPT_DESIGN.IS_ENABLED. Unlike with the Non-Project flow which allows dynamically calling the implementation commands based on conditions defined by the user, the run of a project flow must be configured statically before it is launched. This is why, in this example, the physical logic optimization step is enabled without checking the timing slack value after placement, unlike in the Compilation with a Non-Project flow example.

The various reports are generated before or after each implementation step by using the run Tcl hook properties STEPS.<STEPNAME>.TCL.PRE and STEPS.<STEPNAME>.TCL.POST. These properties allow the user to specify where a Tcl script is executed in the flow when using the run infrastructure. See Defining Tcl Hook Scripts for additional information.

Because the implementation run is executed in a separate Vivado session, all the Tcl variables and procs need to be initialized in that session to be used by the scripts. This can be done in several ways:

Method 1
Define the Tcl variables and procs in your Vivado_init.tcl (see Initializing Tcl Scripts). This is sticky to all your Vivado projects and sessions.
Method 2
Add a Tcl script which contains the variables and procs to the constraints set used by the run. It is always sourced as part of your constraints when opening the design in memory.
Method 3
Set STEPS.OPT_DESIGN.TCL.PRE to a Tcl script which contains the variables and proc. This script is only sourced if the OPT_DESIGN step is enabled, which is true by default.

The current example uses the Method 3. The Tcl scripts are associated with the implementation steps as follows:

set_property STEPS.OPT_DESIGN.TCL.PRE    [pwd]/pre_opt_design.tcl    [get_runs impl_1]
set_property STEPS.OPT_DESIGN.TCL.POST   [pwd]/post_opt_design.tcl   [get_runs impl_1]
set_property STEPS.PLACE_DESIGN.TCL.POST  [pwd]/post_place_design.tcl  [get_runs impl_1]
set_property STEPS.PHYS_OPT_DESIGN.TCL.POST [pwd]/post_phys_opt_design.tcl [get_runs impl_1]
set_property STEPS.ROUTE_DESIGN.TCL.POST  [pwd]/post_route_design.tcl  [get_runs impl_1]

The absolute Tcl script path must be specified because the implementation run is executed in a sub-directory of the project tree, which is different from the one where the full compilation Tcl script is executed.

  • pre_opt_design.tcl
    ############## pre_opt_design.tcl ##################
    set outputDir [file dirname [info script]]/Tutorial_Created_Data/cpu_project
    source [file dirname [info script]]/reportCriticalPaths.tcl
    #
    report_timing_summary -file $outputDir/post_synth_timing_summary.rpt
    report_utilization -file $outputDir/post_synth_util.rpt
    reportCriticalPaths $outputDir/post_synth_critpath_report.csv

    The two first lines correspond to the initialization of the variable and proc used by several scripts later in the implementation run. The next three lines run some utilization and timing reports. It is generally recommended to run timing analysis at the beginning of implementation to validate the timing constraints used during place and route, and ensure there is no large violation. The reportCriticalPaths report provides more information on the worst paths of the design. This Tcl proc is described further in Defining Tcl Procedures.

  • post_opt_design.tcl
    ############## post_opt_design.tcl ##################
    # Run custom script to report critical timing paths
    reportCriticalPaths $outputDir/post_opt_critpath_report.csv

    This script does not need to define the outputDir variable and reportCriticalPaths proc because they are already defined in pre_opt_design.tcl which is sourced earlier in the run in the same Vivado session.

    It is recommended to also run utilization and timing analysis after opt_design.

  • post_place_design.tcl
    ############## post_place_design.tcl ##################
    report_clock_utilization -file $outputDir/clock_util.rpt

    After placement, you can review the utilization of the clock resources and where they are located in the device. It is recommended to run timing analysis to identify large timing violations that cannot be resolved later in the flow.

  • post_phys_opt_design.tcl
    ############## post_phys_opt_design.tcl ##################
    report_utilization -file $outputDir/post_phys_opt_util.rpt
    report_timing_summary -file $outputDir/post_phys_opt_timing_summary.rpt

    Like after placement, it is important to review the timing report at this point of the flow.

  • post_route_design.tcl
    ############## post_route_design.tcl ##################
    report_route_status -file $outputDir/post_route_status.rpt
    report_timing_summary -file $outputDir/post_route_timing_summary.rpt
    report_power -file $outputDir/post_route_power.rpt
    report_drc -file $outputDir/post_imp_drc.rpt
    write_verilog -force $outputDir/cpu_impl_netlist.v -mode timesim -sdf_anno true

    After route, the timing analysis uses actual routed net delays and must be reviewed for timing sign-off. The route status report summarizes the number of unresolved routing issues. If there are any, the DRC report often helps identify what the routing issues are.

    Note: When running an implementation step inside the hook script, you can use the Tcl variable ACTIVE_STEP to, for instance, make the report file names unique. The variable ACTIVE_STEP is automatically updated by Vivado when using the run infrastructure. See Sharing Hook Scripts Between Steps for more information.
    Note: Most of the Tcl reports generated during post-route above are also automatically created by the run infrastructure. Similarly, a design checkpoint is generated after each step of the flow, so there is usually no need to call the write_checkpoint command in your scripts when using a project flow. You can find all the checkpoints and default reports in the implementation run directory:
    ./Tutorial_Created_Data/cpu_project/project_cpu.runs/impl_1/
      top_opt.dcp
      top_placed.dcp
      top_physopt.dcp
      top_routed.dcp
      top_clock_utilization_placed.rpt
      top_control_sets_placed.rpt
      top_utilization_placed.rpt
      top_io_placed.rpt
      top_drc_routed.rpt
      top_power_routed.rpt
      top_route_status.rpt
      top_timing_summary_routed.rpt

    After the implementation run is complete, the implemented design can be loaded in memory with the open_run impl_1 command.