====== Getting Started with Vivado ====== For the most up to date version of this guide, please visit [[programmable-logic/guides/getting-started-with-vivado|Getting Started with Vivado for Hardware-Only Designs]]. {{ :vivado:getting_started:v2019.2:action.png?nolink&800 |The Vivado Start Page}} ----- ===== Introduction ===== 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.// ---- ===== Prerequisites ===== Prior to starting this guide make sure to install Vivado: * For versions 2019.2 and later, see [[vivado:installing-vivado:v2019.2]]. * For versions prior to 2019.2, see [[vivado:installing-vivado:start]]. ---- ===== Guide ===== ==== 1. Launching Vivado ==== **Windows**\\ Open the start menu or desktop shortcut created during the installation process. {{ :vivado:getting_started:v2019.2:windows-shortcut.png? |}} **Linux**\\ Open a terminal, cd into a working directory that can be cluttered with temporary Vivado files and logs, then run the following: source /Vivado//settings64.sh && vivado {{ :vivado:getting_started:linux_start_vivado.png |}} ---- ==== 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). {{ :vivado:getting_started:v2019.2:welcome.png?direct&800 |}} ---- ==== 3. Creating a New Project ==== === 3.1 === 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. {{ :vivado:getting_started:v2019.2:new-project-wiz-1.png |}} === 3.2 === 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 [[wp>CamelCase]].// Click **Next** to continue. {{ :vivado:getting_started:v2019.2:new-project-wiz-2.png |}} === 3.3 === 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. {{ :vivado:getting_started:v2019.2:new-project-wiz-3.png |}} === 3.4 === 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 [[vivado:installing-vivado:v2019.2#installing_digilent_board_files]], and close and relaunch Vivado before continuing this guide.// Click **Next** to continue. {{ :vivado:getting_started:v2019.2:new-project-wiz-4.png |}} === 3.5 === The last page of the New Project Wizard summarizes the options selected throughout. Verify that everything is correct, and click **Finish**. {{ :vivado:getting_started:v2019.2:new-project-wiz-5.png |}} ---- ==== 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. * //Simulation// * Allows for verification of the output of a design prior to programming their device. * //RTL Analysis// * Shows how the tools are interpreting their code. * //Synthesis// * Gives access to Synthesis settings, a view of the synthesized design, and post-synthesis reports. * //Implementation// * 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. {{ vivado:getting_started:v2019.2:flow-navigator.png |}} ---- ==== 5. The Project Manager ==== === 5.1 === This tool is where most development will occur and is the initial tool open after creating a new project. {{ :vivado:getting_started:v2019.2:project-manager.png |}} === 5.2 === The //Project Manager// consists of four panes, //Sources//, //Properties//, //Results//, and the //Workspace//. {{ :vivado:getting_started:v2019.2:project-manager-breakdown.png |}} === 5.3 === 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 ({{:vivado:getting_started:add_sources_btn.png?nolink}}) in the Flow Navigator. {{ :vivado:getting_started:v2019.2:project-manager-breakdown-1.png |}} === 5.4 === 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. {{ :vivado:getting_started:v2019.2:project-manager-breakdown-2.png |}} === 5.5 === 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. {{ :vivado:getting_started:v2019.2:project-manager-breakdown-3.png |}} === 5.6.1 === 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. {{ :vivado:getting_started:v2019.2:project-manager-breakdown-5.png |}} === 5.6.2 === 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. {{ :vivado:getting_started:v2019.2:project-manager-breakdown-6.png |}} === 5.6.3 === 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. {{ :vivado:getting_started:v2019.2:project-manager-breakdown-7.png |}} === 5.6.4 === 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. {{ :vivado:getting_started:v2019.2:project-manager-breakdown-8.png |}} === 5.6.5 === 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. {{ :vivado:getting_started:v2019.2:project-manager-breakdown-9.png |}} ---- ==== 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 [[https://github.com/Digilent/digilent-xdc/archive/master.zip|digilent-xdc-master.zip]], the ZIP Archive containing each of these master XDC files, then extract it in a memorable location. === 6.1 === In the //Project Manager// section of the //Flow Navigator//, click the {{:vivado:getting_started:v2016.4:sources:add-sources.png}} button. {{ :vivado:getting_started:v2019.2:add-constraint-1.png |}} === 6.2 === In the wizard that pops up, select //Add or create constraints// then click **Next**. {{ :vivado:getting_started:v2019.2:add-constraint-2.png |}} === 6.3 === 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**. {{ :vivado:getting_started:v2019.2:add-constraint-3.png |}} === 6.4 === 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. {{ :vivado:getting_started:v2019.2:add-constraint-4.png |}} === 6.5 === 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.// {{ :vivado:getting_started:v2019.2:add-constraint-5.png |}} === 6.6 === In the //Sources// pane of the //Project Manager//, expand the //Constraints// folder, then double click on the XDC file that was just added. {{ :vivado:getting_started:v2019.2:edit-constraint-1.png |}} === 6.7 === 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[0] 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 [[wp>low-voltage differential signalling]].// Lastly, change the names inside of the get_ports calls to 'led' from 'led[0]'. Do the same for the clock if it is something other than 'clk' or 'clk_p' and 'clk_n'. {{ :vivado:getting_started:v2019.2:edit-constraint-2.png |}} ---- ==== 7. Creating a Verilog Source File ==== === 7.1 === 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**. {{ :vivado:getting_started:v2019.2:add-source-1.png |}} === 7.2 === 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.// {{ :vivado:getting_started:v2019.2:add-source-3.png |}} === 7.3 === Next, a //File type//, //File name//, and //File location// must be chosen. For the purposes of this guide, make sure to pick //Verilog// and //// 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 [[wp>CamelCase]].// Click **OK** to continue. {{ :vivado:getting_started:v2019.2:add-source-4.png |}} === 7.4 === Make sure that the new Verilog source file has been added into the list of sources, then click **Finish**. {{ :vivado:getting_started:v2019.2:add-source-5.png |}} === 7.5 === 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// ({{:vivado:getting_started:v2016.4:sources:add-port.png?direct|}}) 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.// {{ :vivado:getting_started:v2019.2:add-source-6.png |}} === 7.6 === 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. {{ :vivado:getting_started:v2019.2:edit-source-1.png?600 |}} 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[24]; 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. === 8.1 === 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. {{ :vivado:getting_started:v2019.2:generate-bitstream.png |}} === 8.2 === The first prompt will ask whether or not to first run Synthesis and Implementation. Click **Yes**. {{ :vivado:getting_started:v2019.2:generate-bitstream-1.png |}} === 8.2 === 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. {{ :vivado:getting_started:v2019.2:generate-bitstream-2.png |}} === 8.3 === 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**. {{ :vivado:getting_started:v2019.2:generate-bitstream-3.png |}} ---- ==== 9. The Hardware Manager ==== The //Hardware Manager// is used for programming the target device. {{ :vivado:getting_started:v2019.2:hardware-manager-1.png?600 |}} 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 {{:vivado:getting_started:open_target_banner.png?nolink}} link in the green banner or click the {{:vivado:getting_started:open_target_btn.png?nolink}} button in the //Flow Navigator// under {{:vivado:getting_started:hw_man_btn.png?nolink}}. From the drop-down that opens, select {{:vivado:getting_started:open_new_target_btn.png?nolink}}. Once the wizard opens, click **Next** to get past the welcome screen. {{ :vivado:getting_started:v2019.2:hardware-manager-2.png |}} 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. {{ :vivado:getting_started:v2019.2:hardware-manager-4.png |}} 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. {{ :vivado:getting_started:v2019.2:hardware-manager-5.png |}} The final screen shows a summary of the options selected in the wizard. Verify the information and click **Finish**. The board is now connected to the Hardware Manager. {{ :vivado:getting_started:v2019.2:hardware-manager-6.png |}} <-- --> Auto-Connect # The second method is to automatically open the target. To get to the {{:vivado:getting_started:auto_connect_btn.png?nolink}} button either open the Hardware Manager and click the {{:vivado:getting_started:open_target_banner.png?nolink}} link in the //green banner// at the top of the window or click the {{:vivado:getting_started:open_target_btn.png?nolink}} button in the //Flow Navigator// under {{:vivado:getting_started:hw_man_btn.png?nolink}}. From the drop-down that opens select {{:vivado:getting_started:auto_connect_btn.png?nolink}}. 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 {{:vivado:getting_started:prog_dev_banner.png?nolink}} link in the //green banner// at the top of the window or click the {{:vivado:getting_started:prog_dev_btn.png?nolink}} button in the //Flow Navigator// under the //Hardware Manager//. From the drop-down that opens, select the device to program {{ :vivado:getting_started:v2019.2:hardware-manager-7.png |}} In the dialog that opens, the //Bitstream File// field should be automatically filled in with the bit file generated earlier. If not, click the {{:vivado:getting_started:browse_btn.png?nolink}} button at the right end of the field and navigate to the following folder: \\ ///.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. {{ :vivado:getting_started:v2019.2:hardware-manager-8.png |}} ----- ==== 10. Finished! ==== 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/start|Programmable Logic]] page. /* {{tag>learn programmable-logic software tutorial vivado arty arty-a7 arty-s7 arty-z7 basys-3 cmod-a7 cmod-s7 cora-z7 genesys-2 nexys-4-ddr nexys-a7 nexys-video zybo-z7 zybo zedboard }} */