Vivado is the hardware development suite used to implement a design in Xilinx FPGAs. In this post, I reported how to create a Vivado project using the Graphical User Interface (GUI). This is the fastest and most common approach to creating a project in Vivado.
The Vivado GUI performs the complete design flow for a Xilinx FPGA:
- Simulate
- Synthesize
- Map
- Route
- Analyze Timing
- Create a bit-stream FPGA configuration File
- Configure FPGA
- Debug the FPGA using ILA (Integrated Logic Analyzer)
Vivado also allows the user to perform the design flow using the TCL language.
TCL scripting is very useful for creating a compact and deterministic FPGA layout flow. This approach is adopted by expert users. You should take it into consideration even if you are not an expert. In this post, we are going to see a simple example that can be used as a template for the Vivado TCL project script. The project created using the TCL script can also be opened and edited using the Vivado GUI. All the analyses (timing, area, etc.) can be performed using GUI after design flow completion.
Vivado TCL Project Script architecture
The Vivado TCL script replicates the same steps we need to perform when we operate in the Vivado GUI. The TCL template implements the following steps:
- Create a project
- Add source files to project
- Add constraint files to project
- Design Synthesis
- Design Map&Route
Vivado TCL script — Create project
The TCL command syntax used to create a Vivado project is:
create\_project PROJECT_NAME DIR_OUTPUT_NAME -part FPGA_DEVICE
PROJECT_NAME: name of our project.
DIR_OUTPUT_NAME: name of the output folder where the project will be created.
FPGA_PART: device we want to use.
An example of create\_project usage is:
create\_project ${PROJECT_NAME} ${DIR_OUTPUT}/${PROJECT_NAME} -part xc7k70tfbg484-2
where we use local variables to create a generic Vivado script template.
Add source and constraint files in Vivado TCL project
The TCL command syntax used to add source files in a Vivado project is:
add\_files { FOLDER/FILE_NAME.vhd }
import\_files -force
import\_files -fileset constrs_1 -force -norecurse ${PROJECT_CONSTRAINT_FILE}
To update the compile order of the design sources in the current project, or in the specified fileset:
update\_compile\_order -fileset sources_1
Vivado TCL script — Start synthesis
After importing the design and constraint files, we need to start design synthesis:
launch\_runs synth_1
wait\_on\_run synth_1
open\_run synth_1 -name netlist_1
Note that we need to wait for synthesis completion. The script launches a task that must complete before proceeding.
Vivado TCL script — Start implementation
After design synthesis, we can launch the design implementation as Map&Route
launch\_runs impl_1 -to\_step write\_bitstream
wait\_on\_run impl_1
start\_gui
The last command opens the Vivado GUI with the implemented design so you can perform all the analyses.
How to run the Vivado TCL script
To run the TCL script, open a terminal (or DOS shell on Windows) and type the following command:
vivado -mode tcl -source TCL_NAME.tcl
Pay attention to the current folder where the script is executed. The current path of the terminal is the current path in the TCL script. Take it into account if you are using a relative path in the TCL script.
Vivado TCL script example
Below is a summary of the Vivado TCL commands reported above. You can use this script as a template for your Vivado design implementation. This Vivado TCL script has been derived from the example you can find in the Vivado installation folder used to demonstrate an RTL-to-bitstream Vivado project flow. This TCL script will create a project, copy source files into the project directory, run synthesis, implementation, and generate a bitstream. It will also write a few reports (timing and power) to disk and open the GUI when finished.
Remember that you need to create a constraint file if you want to generate the timing report.
A simple example of timing constraint file is:
create\_clock -period 5.000 -name CLOCK200 -waveform {0.000 2.500} [get\_ports i_clk]
where we are creating a clock constraint of 200 MHz. The timing group is “CLOCK200”, and the clock signal is the input port “i_clk”.
Vivado TCL project directory structure
A typical Vivado TCL project organizes source files in a clean directory structure:
project_root/
├── vhdl/ # RTL source files (.vhd, .v)
├── constraints/ # Constraint files (.xdc)
├── scripts/ # TCL scripts
└── layout/ # Output directory (generated by the script)
The TCL script template uses ../layout as output directory, assuming the script runs from a scripts/ subfolder. Source VHDL files are in ../vhdl/ and the constraint file is at the project root level (fpga_constraint.xdc).
The Vivado TCL script template is:
set PROJECT_NAME fpga_project
set PROJECT_CONSTRAINT_FILE ./fpga_constraint.xdc
set DIR_OUTPUT ../layout
file mkdir ${DIR_OUTPUT}
create_project ${PROJECT_NAME} ${DIR_OUTPUT}/${PROJECT_NAME} -part xc7k70tfbg484-2
add_files {../vhdl/fir.vhd }
import_files -force
import_files -fileset constrs_1 -force -norecurse ${PROJECT_CONSTRAINT_FILE}
# Mimic GUI behavior of automatically setting top and file compile order
update_compile_order -fileset sources_1
# Launch Synthesis and wait on completion
launch_runs synth_1
wait_on_run synth_1
open_run synth_1 -name netlist_1
# Generate a timing and power reports and write to disk
report_timing_summary -delay_type max -report_unconstrained -check_timing_verbose -max_paths 10 -input_pins -file ${DIR_OUTPUT}/syn_timing.rpt
report_power -file ${DIR_OUTPUT}/syn_power.rpt
# Launch Implementation
launch_runs impl_1 -to_step write_bitstream
wait_on_run impl_1
# Generate a timing and power reports and write to disk
# comment out the open_run for batch mode
open_run impl_1
report_timing_summary -delay_type min_max -report_unconstrained -check_timing_verbose -max_paths 10 -input_pins -file ${DIR_OUTPUT}/imp_timing.rpt
report_power -file ${DIR_OUTPUT}/imp_power.rpt
# comment out the for batch mode
start_gui
Conclusion
The TCL commands presented above can be used to create a Vivado TCL script to start a new design using Xilinx Vivado. The TCL script approach is very useful for creating a portable design across different versions of Vivado, allowing you to start a new design from RTL source files. The TCL script copies all the source files into the project directory so the layout project directory will be self-standing, containing all the design source files and project files.
Reference
[2] https://www.xilinx.com/products/design-tools/vivado.html