Getting Started with Vivado
The goal of this guide is to familiarize the reader with the Vivado tools through the hello world of hardware, blinking an LED.
Note: While this guide was created using Vivado 2016.4, the workflow described has not substantially changed, and the guide works as described through Vivado 2019.2, the latest version as of time of writing.
Prior to starting this guide make sure to install Vivado:
- For versions 2019.2 and later, see Installing Vivado, Vitis, and Digilent Board Files.
- For versions prior to 2019.2, see Installing Vivado, Xilinx SDK, and Digilent Board Files.
1. Launching Vivado
Open a terminal, cd into a working directory that can be cluttered with temporary Vivado files and logs, then run the following:
source <install_path>/Vivado/<version>/settings64.sh && vivado
2. The Start Page
This is the screen that displays after Vivado starts up. The buttons are described below using the image to the right as a guide.
1. Create Project
This button will open the New Project wizard. This wizard steps the user through creating a new project. The wizard is stepped through in section 3.
2. Open Project
This button will open a file browser. Navigate to the desired Xilinx Project (.xpr) file and click Open to open the project in Vivado.
3. Open Example Project
This will guide the user through creating a new project based on an example project. These projects will not work on all devices.
4. Open Hardware Manager
This will open the Hardware Manager without an associated project. If connecting to and programming a device is all that is required by the user, then this is the button to use.
5. TCL Console
While not a button, the TCL console is a very handy piece of Vivado. Primarily, it is used to run scripts that can be used to reproduce projects, designs, or any other action that can be taken in the graphical user interface (GUI).
3. Creating a New Project
From the start page, click the Create New Project button to start the New Project Wizard.
The first page of the wizard, see right, summarizes what this wizard will do. Click Next to continue to the first step.
The first step is to set the name of the project. Vivado will use this name when generating its folder structure.
Important: Do NOT use spaces in the project name or location path. This will cause problems with Vivado. Instead use an underscore, a dash, or CamelCase.
Click Next to continue.
Now that the project has a name and a place to save its files the type of project to create must be selected. Select RTL Project and make sure to check Do not specify sources at this time. Source files will be added and created after the project has been created. Advanced users may find the other options on this screen useful, but they are out of the scope of this guide.
Click Next to continue.
Next it is time to choose the target device. Click the Boards tab at the top of the dialog, then search for and select the board from the list.
Important: If the board does not appear in this list, then Digilent's board files haven't yet been installed. If this is the case, refer to installing_digilent_board_files, and close and relaunch Vivado before continuing this guide.
Click Next to continue.
The last page of the New Project Wizard summarizes the options selected throughout. Verify that everything is correct, and click Finish.
4. The Flow Navigator
The Flow Navigator is how a user navigates between different Vivado tools.
The Navigator is broken into seven sections:
- Project Manager
- Allows for quick access to project settings, adding sources, language templates, and the IP catalog.
- IP Integrator
- Tools for creating Block Designs, most often used for designs involving a Zynq Processing System, or a MicroBlaze Processor.
- Allows for verification of the output of a design prior to programming their device.
- RTL Analysis
- Shows how the tools are interpreting their code.
- Gives access to Synthesis settings, a view of the synthesized design, and post-synthesis reports.
- Gives access to Implementation settings, a view of the implemented design, and post-implementation reports.
- Program and Debug
- Generates a bitstream and uses the Hardware Manager to program a board.
5. The Project Manager
This tool is where most development will occur and is the initial tool open after creating a new project.
The Sources pane contains the project hierarchy and is used for opening up files. The folder structure is organized such that the hardware description language (HDL) files are kept under the Design Sources folder, constraints are kept under the Constraints folder, and simulation files are kept under the Simulation Sources folder. Files can be opened in the Workspace by double-clicking on the corresponding entry in the Sources pane. Sources can also be added by either right clicking the folder to add the file to and selecting Add Sources or by clicking the Add Sources button () in the Flow Navigator.
The Properties pane allows for viewing and editing of file properties. When a file is selected in the Sources pane its properties are shown in here. This pane can usually be ignored.
The most important pane in the Project Manager is the Workspace. The Workspace is where reports are opened for viewing and HDL/constraints files are opened for editing. Initially the Workspace displays the Project Summary which show some basic information from some of the reports.
The unnamed pane at the bottom of the Project Manager window consists of several different useful tools for debugging a project. First, as mentioned before, the TCL Console is a tool that allows for running commands directly without the use of the main graphical user interface. Some Messages may link to the TCL Console to provide more information regarding an error.
The most important one to know is the Messages tool. This tool parses the TCL console for errors, warnings, and other important information and displays it in an informative way.
These tools can be accessed by selecting the different tabs at the bottom of this pane.
The Log tool displays the output from the latest Synthesis, Implementation, and Simulation runs. Digging into this is usually not necessary as the reports and messages views store the information in the log in a more readable format.
The Reports tool is useful for quickly jumping to any of the many reports that Vivado generates on a design. These reports include power, timing, and resource utilization just to name a few.
The last tool is the Design Runs. Using this tool, run settings can be edited and new runs can be created It also displays the status of each of these runs, and when completed, some information about them, including their elapsed time.
6. Adding a Constraint File
In order to connect HDL code with the physical pins of the FPGA, a constraint file needs to be added or created. Digilent has produced a Xilinx Design Constraint (XDC) file for each of our boards. Download digilent-xdc-master.zip, the ZIP Archive containing each of these master XDC files, then extract it in a memorable location.
At this stage, Vivado provides a list of all of the constraint files that will be added or created when we click Finish. Currently this list is empty, but this will change when the master XDC is added. Click Add Files.
Find the directory the digilent-xdc-master.zip archive was extracted into, then click on the file for the board. This should add the name of the file to the File Name field.
Click OK to continue.
Make sure that the selected XDC file has been added into the list of sources, and that the Copy constraints files into project is checked, then click Finish.
Note: Leaving the Copy… box unchecked means that any editing done to the constraint file will be reflected in the original copy. Checking the box is HIGHLY recommended.
In the Sources pane of the Project Manager, expand the Constraints folder, then double click on the XDC file that was just added.
Each of Digilent's XDC files contains constraints for each pin of each peripherals on the respective board. For this demo, only constraining the default system clock and a single led is required.
Find and uncomment the lines including get_ports with the names led and clk by removing the '#' symbol at the beginning of the line. Uncomment the create_clock line that follows the clock port/s definition as well.
Note: The clock port is occasionally named something like sysclk, but should appear at the top of the XDC file.
Note: For some boards, the clock port will consist of two different ports, clk_p and clk_n. In this case, both lines should be uncommented. A board using clk_p/clk_n pins means that the input clock that uses differential logic. For more information, read this article on low-voltage differential signalling.
Lastly, change the names inside of the get_ports calls to 'led' from 'led'. Do the same for the clock if it is something other than 'clk' or 'clk_p' and 'clk_n'.
7. Creating a Verilog Source File
For this step, the other method of adding or creating a file will be used. Right click on the Design Sources folder in the Sources pane, then click Add Sources.
In the resulting wizard, make sure Add or create design sources is selected, then click Next.
As before, a list of all of the source files that will be added or created is displayed. Instead of clicking Add Files, click Create File.
Note: It is also possible to add existing source files in the same way as we added the constraint file above.
Next, a File type, File name, and File location must be chosen. For the purposes of this guide, make sure to pick Verilog and <Local to project> for the type and location, and give the file a name ending in '.v'.
Important: Do NOT use spaces in file names. This will cause problems with Vivado. Instead use an underscore, a dash, or CamelCase.
Click OK to continue.
Make sure that the new Verilog source file has been added into the list of sources, then click Finish.
Unlike when the constraint file was added, at this point a Define Module dialog will pop up. The Verilog module can be renamed using the Module name field, but this is unnecessary. The Verilog module's clock and led ports need to be defined. Clicking the Add () button will add an empty slot for a port to the I/O Port Definitions list.
There are five fields to define for each of the module's I/O ports:
- Port Name: This field defines the name of the port and needs to match one of the names used in the XDC file.
- Direction: This drop-down menu can be set to input, output, or inout, defining the direction that signals propagate through this port, with respect to the module. Outputs are the signals that the module will be controlling.
- Bus: This can be checked or not, when checked, this port consists of multiple single bit signals, grouped into a single bus.
- MSB: The index of the most significant bit of the port, if it is a bus. This option is grayed out for single-bit ports.
- LSB: The index of the least significant bit of the port, if it is a bus. This option is grayed out for single-bit ports.
If the board uses differential clocking, add two single-bit input ports with the same names as the positive and negative clock ports that were uncommented in the XDC file. Otherwise, add a single single-bit input port with the same name as the clock port that was uncommented in the XDC file.
Add a single-bit output port with the same name as the LED port that was uncommented in the XDC file.
Once these two or three ports have been added, click OK to continue.
Note: When defining a module which will be instantiated in another module, which we will not go into in this guide, be aware that the port names should not be declared in the XDC, this is only done for the 'top' module.
At this point, the new source file will be added to the Design Sources folder in the Sources pane of the Project Manager. Expand this folder and double click on the file to open it.
Next, some Verilog code needs to be written to define how the design will actually behave.
Between the ');' that comes after the module's port list and the 'endmodule' statement, add the following code:
reg [24:0] count = 0; assign led = count; always @ (posedge(clk)) count <= count + 1;
If the board is differentially clocked, add the following lines of code after ');' and before the 'reg [24:0] count = 0;' line:
wire clk; IBUFGDS clk_inst ( .O(clk), .I(clk_p), .IB(clk_n) );
This design implements a simple 25-bit counter, that rolls over after 2^25 clock cycles. The LED is held high for the second half of the counter's full cycle.
It should be noted that the rate at which the clock will blink will differ depending on the board used. System clocks on different Digilent boards run at a number of different rates, depending on the needs of the board. The system clock period in nanoseconds can be found on the create_clock line of the XDC file.
8. Synthesis, Implementation, and Bitstream Generation
In order to create a file that can be used to program the target board, each stage of the “compilation pipeline” needs to be run.
- Synthesis turns HDL files into a transistor level description based on timing and I/O constraints. The output of Synthesis is then passed to Implementation.
- Implementation has several steps. The steps that are always run are Opt Design (Optimize the design to fit on the target FPGA), Place Design (Lay out the design in the target FPGA fabric), and Route Design (Route signals through the fabric). This output is then passed on to Bitstream Generation.
- Bitstream Generation generates the final outputs needed for programming the FPGA.
To run each of these steps in order, click the Generate Bitstream button in the Flow Navigator. With no settings changed, the generator will create a '.bit' file which can be used to program the board.
The final prompt before launching the runs gives several options on where and how to launch the runs. Leave everything as default, though increasing the number of jobs may improve how quickly the bitstream can be generated.
Finally, the bitstream will be generated. Note that this process may take several minutes (or longer for more complex designs).
When the bitstream is finalized, another prompt pops up, which provides a quick way of navigating to several useful tools for analyzing and using the results. Select Open Hardware Manager, then click OK.
9. The Hardware Manager
The Hardware Manager is used for programming the target device.
The first step to programming a device is to connect the Vivado Hardware Server to it. There are two ways to do this.
- Open New Hardware Target
The first method is to manually open the target. This is required if the hardware is connected to another computer. To get to the Open Hardware Target wizard either open the Hardware Manager and click the link in the green banner or click the button in the Flow Navigator under . From the drop-down that opens, select .
Once the wizard opens, click Next to get past the welcome screen.
The next screen asks if the hardware server is local or remote. For the purposes of this guide, the board must be plugged into the computer being used.
Click Next to continue.
This screen gives a list of devices connected to the hardware server. If there is only one connected it should be the only device shown. If there are multiple connected devices, determine the serial number of the device to connect to and find it in the list.
Click Next to continue.
- The second method is to automatically open the target. To get to the button either open the Hardware Manager and click the link in the green banner at the top of the window or click the button in the Flow Navigator under . From the drop-down that opens select . Vivado will attempt to find a hardware server running on the local machine and will connect to the device on the server.
Programming the Board
To program the device with the bit file generated earlier, either click the link in the green banner at the top of the window or click the button in the Flow Navigator under the Hardware Manager. From the drop-down that opens, select the device to program
In the dialog that opens, the Bitstream File field should be automatically filled in with the bit file generated earlier. If not, click the button at the right end of the field and navigate to the following folder:
<Project Directory>/<Project Name>.runs/impl_1/
Select the bit file found there (blinky.bit for example). Now click Program. This will connect to the board, clear the current configuration, and program using the new bit file.
You should now see one of the LEDs on the board blinking! A worthwhile next project would be to change the Verilog source file to make this LED blink at one Hertz, which is left as an exercise for the reader.
Be sure to visit the board's resource center for more tutorials and demo projects. A link to each resource center can be found in this wiki's Programmable Logic page.