Mishmash of Notes on Vivado

Vivado Mishmash #

The following lecture focusing on many small glue items needed for working fluently in Vivado. This includes pathing, constraints and tcl with a little bit of hardware information added in.

Table of Contents #

settings.sh #

Depending on your installation (and most likely for Linux), you will want to source settings64.sh to correctly set up all pathing.

Default Hardware Constraint Files #

Digilent is nice and provides a default hardware constraint file for each of their development boards. This can help save a lot of time sorting through documentation. They can be found here: https://github.com/Digilent/digilent-xdc/tree/master

Recommended directory structure. Often times it’s needed to deploy the same design onto different chips. Only one chip per GUI Vivado project is allowed (if used in TCL mode, then you can specify more).

Create the following directory structure and files README.md and .gitignore

project_name/
	bitstream_archive/
	src/
		verilog/
		constraints/ 
	scripts/
	vivado_projects/
		vivado_project_1
	README.md
	.gitignore

Then in the root of the directory (i.e., project_name) run

git init

This will start a git repository.

Gitignore #

A gitignore file is a file that defines which files should be tracked by git and which should not. For Vivado projects this is extremely important because it creates a lot of temporary cache files. For more information see the gitignore documentation.

Copy the below gitignore into .gitignore. source

## gitignore template for Xilinx Vivado Design Suite
## website: https://www.xilinx.com/support/download.html

## [home]
*.jou
*.log
*.debug
*.str
*.zip
*.tmp
*.rst
*.os
*.js
*.pb
*.dcp
*.hwdef
*.vds
*.veo
*.wdf
*.vdi
*.dmp
*.rpx
*.rpt
*_stub.v
*_stub.vhdl
*_funcsim.v
*_funcsim.vhdl
.project

## [dir]
*.cache
.metadata
*.data
*.ipdefs
.Xil
*.sdk
*.hw
*.ip_user_files

#### IP synth
*_synth_*

.jobs

#### project synth
*/*.runs/synth*/*.xml
*/*.runs/synth*/*.txt
*/*.runs/synth*/*.sh
*/*.runs/synth*/*.tcl
*/*.runs/synth*/*.bat
*/*.runs/synth*/*.xdc
!*/*.runs/synth*/*utilization*.rpt

*.runs/synth*/*.xml
*.runs/synth*/*.txt
*.runs/synth*/*.sh
*.runs/synth*/*.tcl
*.runs/synth*/*.bat
*.runs/synth*/*.xdc
!*.runs/synth*/*utilization*.rpt

#### project impl
*/*.runs/impl*/*.xml
*/*.runs/impl*/*.html
*/*.runs/impl*/*.txt
*/*.runs/impl*/*.sh
*/*.runs/impl*/*.tcl
*/*.runs/impl*/*.bat
!*/*.runs/impl*/*utilization*.rpt

*.runs/impl*/*.xml
*.runs/impl*/*.html
*.runs/impl*/*.txt
*.runs/impl*/*.sh
*.runs/impl*/*.tcl
*.runs/impl*/*.bat
!*.runs/impl*/*utilization*.rpt

#### block design
*/*/bd/*/hdl
*/*/*/bd/*/hdl

*/*/bd/*/*.xdc
*/*/*/bd/*/*.xdc

*/*/bd/*/ip/*/*.xdc
*/*/*/bd/*/ip/*/*.xdc

*/*/bd/*/ip/*/*/
*/*/*/bd/*/ip/*/*/

*/*/bd/*/ip/*/*.vhd
*/*/*/bd/*/ip/*/*.vhd

*/*/bd/*/ip/*/*.xml
*/*/*/bd/*/ip/*/*.xml

*.c
*.h
*.vho
*.html
*/*/bd/*/ip/*/*.tcl
*/*/*/bd/*/ip/*/*.tcl
hw_handoff
ipshared

Adding Sources #

When you add files, make sure that you DESELECT the Copy sources into project checkbox. You do NOT want it to copy files into the Vivado project structure (see below). You want Vivado to reference the file in place.

Setting up for Example #

We will resume the previous example, but in the new project structure.

Verilog #

Create the file project_name/src/verilog/top.v and copy the contents below into the file:

// Time scale is used for simulation
`timescale 1ns / 1ps


module top(
    // Define the inputs and outputs to the module
    output  wire        led,
    output  wire        locked_led,
    input   wire        CLK100MHZ
    );

    // Counter for clock divider
    reg     [24:0]  counter = 24'd0;

    wire slow_clk;

    // Paste PLL instantiation template here!


    // Clock divider
    // Count up on every 100MHz positive clock edge
    // The register will overlfow and loop
    always @(posedge slow_clk)
    begin
        counter <= counter + 1;
    end

    // Assign the last bit in the counter to the LED.
    // Thus the LED will blink every 100e6/2^25 Hz
    assign led = counter[24];

endmodule

Now in Vivado, add top.v to the project. But DO NOT copy the source into the project.

Constraints #

Create project_name/srce/constraints/arty_constraints.xdc to the project and copy the contents below into the file.

#####################
### Clocking
#####################
## This tells vivado to route the signal as a clock
create_clock -add -name sys_clk_pin -period 10.00 -waveform {0 5} [get_ports { CLK100MHZ }];
## Put PLL Clock constraints below!


#####################
### I/O
#####################
## Set the port to the package pin wired to the LED on the dev board
set_property -dict { PACKAGE_PIN H5    IOSTANDARD LVCMOS33 } [get_ports { led }]; ##IO_L24N_T3_35 Sch=led[4]
set_property -dict { PACKAGE_PIN J5    IOSTANDARD LVCMOS33 } [get_ports { locked_led }]; ##IO_25_35 Sch=led[5]
## Create the clock port which is wired to a 100MHz crystal oscillator on the dev board
set_property -dict { PACKAGE_PIN E3    IOSTANDARD LVCMOS33 } [get_ports { CLK100MHZ }]; ##IO_L12P_T1_MRCC_35 Sch=gclk[100]

In Vivado, add the constraints file to the project, but again, DO NOT copy it into the project.

Just Enough TCL #

Tcl is a weird language, but it’s useful. It is a dynamics interpreted language that is rather like csh and Lisp. We don’t need to know a lot about TCL, but just enough to understand how to write constraints since xdc files are actually tcl.

General Language Structure #

Tcl is a “command driven”, white space delineated language. You give a command, then arguments to commands like csh.

command argument_1 argument_2

Arguments can be grouped with "" or {}

command "this is one argument"
command {this is one argument}
command these are all separate arguments

Comments # 

## This is a comment

Printing # 

## Write "hello world" to the console
puts "hello world"

Remember! The double quotes are needed to group arguments.

Variables #

Setting Variables #

In tcl, there are strings, ints, doubles and a few other types. But they all can be evaluated to strings.

set a_variable "a value" ## string
set b_variable 1.2345 ## double

Accessing Variables #

Variables are accessed with the $ operater like bash or csh.

puts $a_variable
puts $b_variable

This is actually a value substitution.

Command Returns #

The return value from a command may be embedded as arguments in other commands. For example, the command pwd returns the working directory so we can store that in a variable

set our_working_dir [pwd]

Substitution and Evaluation #

There are two steps to a command execution in Tcl: substitution and evaluation.

Substitutions #

One pass of substitutions are made in the following order:

  1. Command Returns [] - First, the interpreter evaluates any commands in square brackets [] and inserts their returns as arguments to the command.
  2. Double Quotes "" - Any variables in double quotes are replaced with their values.
  3. Braces {}- Any variables in braces are FORBIDDEN from being substituted.

Evaluation #

The resulting command after the respective substitutions are made, the resulting command is executed.

Example #

Consider the tcl constraint below.

set_output_delay -clock pll_10MHz 1.000 [get_ports led]

The command set_output_delay as arguments -clock pll_10MHz 1.000 and the results of evaluating the command get_ports with the argument led. We will see many more commands like this.

Summary #

There is a lot more to tcl including loops, control logic, operators, etc,, but for our purposes we need not go further. For more information, please see the official tcl documentation.

PLL IP Block and Timing Constraints #

This is an example of using a PLL IP block. The emphasis here is not on PLLs, but instead using IP blocks and how to handle timing constraints.

Creating the IP Block #

Open the IP catalog from the Flow Navigator

Search for clocking wizard in the IP Catalog

In the clocking wizard set the following (see two Figs below):

  • Component Name: pll0
  • Clocking Options
    • Primitive: PLL
    • Port Name: pll_in1
    • Enable Optional Inputs/Outputs
      • Reset: FALSE
  • Output Clocks
    • Port Name: pll_out1

Then click ok.

On the next screen, select Global. This option lets you synthesize the IP out of context (i.e., apart from all the other synthesis). Super useful, but adds some unneeded complexity for now. Click Generate.

Yay! You have now create a PLL IP Block

Using the IP Block #

Now we need to instantiate the IP block in our design. Under sources open Ip Sources and select the instantiation template pll0.veo. This is the verilog needed to instantiate the pll. The instantiation template should have a section that looks like this:

//----------- Begin Cut here for INSTANTIATION Template ---// INST_TAG

	pll0 instance_name (
	    // Clock out ports
	    .pll_out1(pll_out1),     // output pll_out1
	    // Status and control signals
	    .locked(locked),       // output locked
		// Clock in ports
	    .pll_in1(pll_in1)      // input pll_in1
	);

// INST_TAG_END ------ End INSTANTIATION Template ---------

Take the instantiation template and copy and paste it into top.v at the specified location. Then wire it in appropriately so that the snipped code should look like:

// ... snip

// Paste PLL def here!
    pll0 pll_inst0 (
        // Clock out ports
        .pll_out1(slow_clk),     // output pll_out1
        // Status and control signals
        .locked(locked_led),       // output locked
       // Clock in ports
        .pll_in1(CLK100MHZ)      // input pll_in1
    );

// snip ...

Now run Synthesis and Implementation! Once they are complete, open the implementation. There will be a warning:

This is because we did not constrain the newly created PLL clock.

Timing Constraints #

Issues #

  1. There is a warning from Vivado under Messages then Implementation Design that there is no port named pll_in1.
  2. Under Timing there are multiple High Severity warnings. The top warnings are that there are multiple clocks. We will call this the second issue.
  3. The third issue is that there is no output delay.

Solutions #

Issue 1 and 2 #

The first thing to note is that IP blocks come with their own generate constraint files. Under IP Sources you can see the generated constraint files.

And under Compile Order and selecting the Implementation compile order, we can see that the PLL constraint files are evaluated before our constraint file. It is possible (though unnecessary right now) to change that order.

One thing to note is that this file is scoped to the pll0 instance. So it only knows ports, pins, etc. associated to the pll0. The pll0_board.xdc and pll0_ooc.xdc files are empty. The pll0.xdc file contains (comments added):

## This creates a clock associated to thesubtitutions port pll_in1 of the pll0. Remember, the file is scoped only to the pll0
create_clock -period 10.000 [get_ports pll_in1]

## This sets the jitter. 
set_input_jitter [get_clocks -of_objects [get_ports pll_in1]] 0.100

## Nothing wrong with this line.
set_property PHASESHIFT_MODE WAVEFORM [get_cells -hierarchical *adv*]

However, in the last example, we defined the CLK100MHZ clock in arty_constraints.xdc as so:

#####################
### Clocking
#####################
## This tells vivado to route the signal as a clock
create_clock -add -name sys_clk_pin -period 10.00 -waveform {0 5} [get_ports { CLK100MHZ }];
## Put PLL Clock constraints below!

## snip...

Since these are both connected to the same net, they conflict and since the arty_constraints.xdc file is compiled AFTER the pll0.xdc it overrides (removes) the first definition in synthesis. Then in implementation it can’t find the correct port. Hence, we need to remove the old definition. The relevant portion of arty_constraints.xdc should look like this:

#####################
### Clocking
#####################
## Put PLL Clock constraints below!

## snip...

This is the cause of both issue (1) and issue (2).

Renaming Clocks #

Now, Vivado automatically creates clock names, but they aren’t always logical. Let’s rename the 10MHz PLL output clock using the create_generated_clock command:

#####################
### Clocking
#####################
## Vivado automatically creates a generated clock definition
## But we can use the create_generated_clock command to rename it.
create_generated_clock -name pll_10MHz [get_pins pll_inst0/*/*/CLKOUT0]
Note on the 10MHz Clock Definition #

Astute readers will notice that we only renamed the 10MHz clock and never defined it. This is because Vivado automatically adds a definition for it that we cannot see.

Issue 3 #

Now we can address the third issue: no output delay. In order to perform Static Timing Analysis (STA), Vivado needs to know the delay between the FPGA and the next external component in the signal chain so that it can make sure to hit the timing requirements. The command set_output_delay sets the delay required. Since we don’t have any specified timing requirements we will set it to 1us arbitrarily.

#####################
### Clocking
#####################
## Vivado automatically creates a generated clock definition
## But we can use the create_generated_clock command to rename it.
create_generated_clock -name pll_10MHz [get_pins pll_inst0/*/*/CLKOUT0]

## Set the output clock delay
set_output_delay 1.000 [get_ports led]

Now running Synthesis and Implementation should be clean!

More Fun with Timing Constraints #

From the previous example, it is evident that timing constraints can be tricky and warrents more discussion. At a high level, there are four steps to writing timing constraints

  1. Create Clocks
    1. This is where all primary, virtual, and generated clocks with their parameters (such as jiter) are set.
  2. Input/Output Delay
    1. This is where you set how the FPGA clocks relate to the outside world both in and out.
  3. Clock Groups and CDC
    1. Here you define how clocks relate to each other.
  4. Timing Exceptions
    1. This is where you allow for weird timing behavior like loops or any unusual timing. Mostly, these commands are disabling different analysis types.

In order to better illustrate timing constraints we will continue the above example with a small modification.

Source: https://docs.amd.com/r/en-US/ug949-vivado-design-methodology/Defining-Timing-Constraints-in-Four-Steps

Example #

Setup #

First, let’s modify top.v in the four places as shown below. The goal of the modification is to create a new generated clock, led_clk. This new clock will need to be constrained. Note: any signal used as as the clock signal to a flip-flop (i.e., always @(posedge CLOCK_SIGNAL))...) is considered a clock to Vivado.

// Time scale is used for simulation
`timescale 1ns / 1ps

module top(
    // Define the inputs and outputs to the module
    /************* MOD HERE!! ************/
    output  reg         led = 0,    // Note this is a register now!
    /************* MOD HERE!! ************/
    output  wire        locked_led,
    input   wire        CLK100MHZ
    );

    // Counter for clock divider
    reg     [24:0]  counter = 24'd0;
    wire    slow_clk;

    /************* MOD HERE!! ************/
    wire    led_clk;
    /************* MOD HERE!! ************/


    // Paste PLL def here!
    pll0 pll_inst0 (
        // Clock out ports
        .pll_out1(slow_clk),     // output pll_out1
        // Status and control signals
        .locked(locked_led),       // output locked
       // Clock in ports
        .pll_in1(CLK100MHZ)      // input pll_in1
    );


    // Clock divider
    // Count up on every 100MHz positive clock edge
    // The register will overlfow and loop
    always @(posedge slow_clk)
    begin
        counter <= counter + 1;
    end

    /************* MOD HERE!! ************/
    assign led_clk = counter[24];
    /************* MOD HERE!! ************/


    /************* MOD HERE!! ************/
    // At the posedge of the led_clk, switch the led reg
    always @(posedge led_clk)
    begin
        led <= ~led;
    end
    /************* MOD HERE!! ************/

endmodule

Running synthesis and implementation give the following timing errors

which we must now solve.

Resolution #

To resolve the clocking constraints, we will work through each step of the four step process.

Create Clocks #

First we need to create the generated clock. There are three different types of clocks in Vivado:

  • Primary Clocks
    • Primary clocks are physical clocks external to the FPGA like crystal oscillators. They are defined with the create_clock command
  • Generated Clocks
    • Generated clocks are clocks that are created internal to the FPGA. These could be PLLs, MMCMs, or created by user defined logic. They are defined with the create_generated_clock command.
  • Virtual Clocks
    • Virtual clocks don’t have any physical representation. They are used for timing reference and are defined by the create_clock command.

Since we are creating a clock with a clock divider in logic, we have a generated clock. Using the appropriate command, the arty_constraints.xdc becomes:

#####################
### Clocking
#####################
## Vivado automatically creates a generated clock definition
## But we can use the create_generated_clock command to rename it.
create_generated_clock -name pll_10MHz [get_pins pll_inst0/*/*/CLKOUT0]

## Create the led_clk generated clock
create_generated_clock -name led_clk -source [get_pins pll_inst0/pll_out1] -divide_by 16777216 [get_nets led_clk]

## Set the output clock delay
set_output_delay -clock pll_10MHz 1.000 [get_ports led]

## snip...

Run Synthesis and Implementation. The original warnings are gone, but we will now get some new timing warnings.

Input/Output Delay #

Since we didn’t add any new inputs/outputs we skip this step.

Clock Groups #

The warnings from Vivado say there is no common period between related clocks.

Looking in the manual we can see this occurs when no common period is found in 1000 clock cycles of analysis. Since the led_clk is 2^24 times slower than pll_10MHz, there is clearly no period. To get more information in the TCL commandline run

report_clock_interaction -name timing0

which will open a window like this:

This window shows us that the interaction between led_clk to pll_10MHz is unsafe. To solve this, we will explicitly tell Vivado that led_clk and pll_10MHz don’t have a common period by placing led_clk and pll_10MHz in separate clock groups that are asynchronously related. The constraints file now looks like:

## ...snip

## Set the output clock delay
set_output_delay -clock pll_10MHz -1.000 [get_ports led]

## set the clock groups
set_clock_groups -asynchronous -group [get_clocks pll_10MHz ] -group [get_clocks -include_generated_clocks led_clk]

## snip...

After synthesis and implementation, re-running report_clock_interaction -name timing0 now gives:

Timing Exceptions #

Nothing we are doing is too fancy so there are no timing exceptions. We will deal with these in the future with ring oscillators.

Summary #

In summary we have gone over the basics of timing constraints. They can get a little complicated, but as long as you follow the Xilinx UltraFast workflow they aren’t too bad. Don’t forget to look at the resources below.

Timing Resources #

Documentation #

Templates #

Go to Tools > Language Templates. This opens a set of templates for different constraint operations.

Booting onto SPI Flash #

The standard for booting from SPI flash is given in XAPP586. It is rather long, but the steps are not too bad.

Configuration #

  1. Set the appropriate jumpers or dip switches on the dev board.
  2. Go to Project Settings / Bitstream check “-bin”. This will tell Vivado to create a *.bin.
  3. Run synthesis!! Vivado will not allow some settings to be changed until synthesis has been run.
  4. Go to Tools / Edit Device Properties OR open a synthesized design and go to Settings / Bitstream / Configure additional bitstream settings
    1. General: Enable Bitstream Compression (this isn’t strictly necessary, but it does speed up the memory writing process)
    2. Configuration: Set the Configuration rate. This is the SPI flash clock rate. For example, the Arty is 33MHz
    3. Configuration Modes: You can select two different configuration modes. Chose the normal JTAG programming mode and then the correct SPI configuration For example, the Arty is Master SPI x4
  5. Run Generate Bitstream
  6. Open the Hardware Manager
  7. Right click on the device and select Add Configuration Memory Device
    1. Add the appropriate memory device. For example the Arty has a s25fl128xxxxxx0-spi-x1_x2_x4
    2. Then program the device with the *.bin generate with the bitstream creation.
  8. Don’t forget! You will need to reprogram the device after loading memory! (reset button or power cycle)

Programing Memory #

  1. Open the hardware manager
  2. Right click on the memory device and select Program Configuration Memory Device
  3. Select the *.bin and select ok

Parameters #

Dev Board SPI Flash Vivado Configuration Memory Device Configuration Rate SPI Configuration
Arty A7 S25FL128SAG[M|N]FI00 or S25FL127SABMFx00 ​ s25fl128sxxxxxx0-spi-x1_x2_x4 33MHz Master SPI x4
CW305 mx25l3233fmi1-08 mx25l3233f-spi-x1_x2_x4 3MHz Master SPI x1

Pitfalls #

  • Don’t forget any jumpers or dip switches!
  • Watch out for the 1x or 2x when choosing the hardware SPI configuration.

TCL Pre-Post Scripts #

Synthesis tcl.pre #

The following example script sets parameters DATE_CODE and HASH_CODE in the Verilog to the synthesis date/time and git has.

## Current date, time, and seconds since epoch
set compileTime [clock format [clock seconds] -format {%m-%d-%y_%H:%M}]
## Get the git hashtag for this project
set curr_dir [pwd]
set proj_dir [get_property DIRECTORY [current_project]]
cd $proj_dir
set git_hash [exec git log -1 --pretty='%h']
## strip forbidden characters
set git_hash [ string trim $git_hash "\'\"" ]
## Show this in the log
puts HASHCODE=$git_hash

## Set the generics (This only works if using vivado in batch (non GUI) mode
## set_property generic "DATE_CODE=32'h$datecode HASH_CODE=32'h$git_hash" [current_fileset]
## If using GUI, set the following in other options
## -generic "DATE_CODE=$compileTime HASH_CODE=$git_hash"

Since the generics are evaluated before tcl.pre is called in project mode of Vivado, they must be passed to synthesis through arguments. The arguments can be set in Settings / Synthesis / Settings and More Options

-generic "DATE_CODE=$compileTime HASH_CODE=$git_hash"

Figure 1. The more options settings..

Bitstream tcl.post #

The following post bitstream tcl script copies the newly created bit stream and bin stream into an archival directory at the repo’s top level for a simple version control. The difficulty with this script is that in project mode Vivado runs everything in a backend thread that does not have all of the objects the frontend does. For example, the NAME property on the current_project object returns Project. So you have to strip out the info rather weirdly. Similarly pathing is all relative in a hidden directory that is later removed (I think).

### Script copies an archive of the bitstreams to a top level dir.
## Get the fpga part
set fpga [get_property PART [current_project]]
## Get the git hash
set curr_dir [pwd]
set proj_dir [get_property DIRECTORY [current_project]]
cd $proj_dir
set git_hash [exec git log -1 --pretty='%h']
## strip forbidden characters
set git_hash [ string trim $git_hash "\'\"" ]
## Get the project name
set proj_name [ lindex [ file split [ exec pwd ] ] end-2 ]
## Get the toplevel dir of the project
set top_git_dir [exec git rev-parse --show-toplevel]
cd $curr_dir
## Create bitstream generation time stamp
set bitstream_gen_ts [clock format [clock seconds] -format {%m-%d-%y_%H-%M}]
## Create the new bitstream name and paths
set new_bitstream_name ${proj_name}_${fpga}_${git_hash}_${bitstream_gen_ts}.bit
set orig_bit_path [ glob *.bit ]
set new_bit_path [file join $top_git_dir bitstream_archive $new_bitstream_name]
## Copy the file
file copy -force $orig_bit_path $new_bit_path