Environment Requirements

Windows - MSYS2 (Recommended)

It is recommended that for Windows the MSYS2 system be used. This provides a compatible Bash shell and associated command line tools as well as useful tools for managing the installation using the well regarded Pacman tool from Arch Linux. It is recommended to use MSYS2 instead of Cygwin as MSYS2 is designed to integrate and interoperate with Windows commands where as Cygwin is designed to be used independent of Windows.

Installation instructions for MSYS2 can be found at: http://sourceforge.net/p/msys2/wiki/MSYS2%20installation/.

Windows - Cygwin

Alternatively it is possible to use Cygwin. Cygwin doesn't interoperate with Windows quite as well as MSYS2 but is still supported (for now). Installation instructions for Cygwin can be found at: https://www.cygwin.com/.

Linux

No special consideration is needed if Linux is being used; Linux is fully supported out of the box. There are no specific distribution requirements.

Project Organization

A project consists of zero or more reusable IP modules and one or more implementation targets. Reusable IP modules may be packaged for use with vendor IP based tools, or may be a collection of sources to be included directly by targets or other IP modules. All IP modules are located in either a global IP repository or the project specific IP repository in the ip_repo directory. A project should only have a single local IP repository

+ <ROOT>/
├─+ bin/
│ ├── vivado/
│ └── activate
│
├─+ ip_repo/
│ └─+ <IP>/
│   ├── bench/
│   ├── bin/
│   ├── doc/
│   ├── ip/
│   ├── out/
│   ├── prj/
│   ├─+ sim/
│   │ ├── rtl_sim/
│   │ └── gate_sim/
│   └── src/
│
└─+ <TARGET>/
  ├── bench/
  ├── bin/
  ├── bd/
  ├── doc/
  ├── ip/
  ├── out/
  ├── prj/
  ├─+ sim/
  │ ├── rtl_sim/
  │ └── gate_sim/
  └── src/

• bin/ - This is where any project wide scripts should be placed. Scripts may be makefiles, python, tcl, etc.

• bin/vivado/ - This is where any project wide scripts that are specific to the Vivado toolset should, in general, be placed. Scripts not pertaining to Vivado should never be placed in this directory.

• bin/activate - This is the project activate script. This scripts should be sourced in a Bash shell to initialize the environment for the project. Failing to source the activate script may result in broken project framework functionality.

• ip_repo/<IP>/ - Contains reusable IP. Reusable IP may be packaged IP suitable for use with Xilinx IP Integrator or may be 3rd party IP or library IP that is included as source. Any IP related tasks should be executed from this directory.

• <TARGET>/ - Contains top level target sources and project files. Sources may include the top level HDL, top level constraints, device pinout constraints, etc. Any target related tasks should be executed from this directory.

• */bench/ - Contains test bench sources. This does not included reusable bus functional models which should be contained in their own IP module or IP library. Test bench sources included here are top level tests, utility HDL libraries/packages, test configurations, etc.

• */bd/ - Where any block diagrams that are used by either a target or an IP are placed. Each block diagram should have its own sub-directory under this directory. This directory is not version controlled.

• */bin/ - Any scripts that are specific to an IP or target.

• */doc/ - Documentation related to the current IP or TARGET.

• */ip/ - Configured IP as generated by the Xilinx IP Integrator tool. These sources should only be managed through the IP Integrator tool and should not be directly edited or modified. Functional changes to any IP should be done using the IP wizard or by editing the sources under the appropriate ip_repo/<IP> directory.

• */out/ - Where any outputs from simulation, synthesis, or implementation are put. This includes run logs, checkpoints, netlists, bit files, compilation units, etc. This directory is not version controlled.

• */prj/ - The Vivado project working directory. This directory is not version controlled.

• */sim/rtl_sim/ - The RTL simulation project for either an IP or a Target. A makefile and Vivado Xsim *.prj defining the sources for the simulation file should be here.

• */sim/gate_sim/ - The gate simulation project for either an IP or a Target. A makefile and Vivado Xsim *.prj defining the sources for the simulation file should be here.

• */src/ - Any sources for the IP or Target. Sources may include, but are not limited to, HDL (VHDL or Verilog), Tcl, XDC constraints, etc.

Getting Started

Open a Bash shell and cd into the root project directory. Issue the follow sequence of commands to build the hardware implementation for the ZC702 board from Xilinx:

$ . bin/activate
$ cd zc702
$ make init
$ make bit

The generated outputs will be located in zc702/out/synth_1 and zc702/out/impl_1. The bit file is the FPGA image. The hwdef file may be used by the Vivado SDK to generate an appropriate hardware project, BSP, bootloader, and combined hardware and software loadable image.

Adding Targets

1. Createa new directory <TARGET> under the root project directory.

2. Create a new Vivado project named <TARGET> in <TARGET>/prj; this is where the XPR project file should reside.

3. Create a new HDL source file with the desired top level entity and save the file to the <TARGET>/src directory. Add this file to the Vivado project.

4. Create a new makefile at <TARGET>/makefile and give it the following contents:

   include $(PROJECT_ROOT)/bin/vivado_env.mk
   
   PRJ_NAME := <TARGET>
   
   PRJ_RUNS := \
       synth_1 \
       impl_1
   
   include $(VIVADO_RULES)
   

5. Save the project to Tcl scripts that can be version controlled:

   $ cd ip_repo/<IP_NAME>
   $ make save
   

Adding IP

IP is a collection of reusable HDL code. IP may contain synthesizable or behavioral elements, or both. An IP is very similar to a Target in that both contain HDL sources and a Vivado project. This means like a Target, an IP may be synthesized and routed. An IP may also be simulated.

The purpose of IP is to package reusable HDL code and to facilitate parallel development; that is to allow development of IP in parallel with each other and/or with a top level Target.

1. Create a new directory <IP_NAME> under the ip_repo directory.

2. Create a new Vivado project named <IP_NAME> in ip_repo/<IP_NAME>/prj; this is where the XPR project file should reside.

3. Create a new HDL source file with the desired top level entity and save the file to the ip_repo/<IP_NAME>/src directory. Add this file to the Vivado project.

4. With the Vivado project open, select Tools > Create and Package IP.... Click Next.

5. Select the Package your current project option and click Next.

6. Select how to include any additional IP referenced or used by the new IP. Click Next.

7. Click Finish.

8. Create a new makefile at ip_repo/<IP_NAME>/makefile and give it the following contents:

   include $(PROJECT_ROOT)/bin/vivado_env.mk
   
   PRJ_NAME := <IP_NAME>
   
   PRJ_RUNS := \
       synth_1 \
       impl_1
   
   include $(VIVADO_RULES)
   

9. Save the project to Tcl scripts that can be version controlled:

   $ cd ip_repo/<IP_NAME>
   $ make save
   

10. With the IP Vivado project open, the IP can be packaged by selecting the Package IP option from the Flow Navigator pane; follow the nomral Vivado IP packaging proceedure.

Simulating IP

$ cd ip_repo/ip_core/sim/rtl_sim
$ make

$ cd ip_repo/ip_core/sim/rtl_sim
$ make suite

$ cd ip_repo/ip_core/sim/rtl_sim
$ make list

$ cd ip_repo/ip_core/sim/rtl_sim
$ make test_1
$ make test_2
$ make test_3

Configuration IP

Block Diagrams