Lab 01: Lab Setup

Error on line 5 of Python tag (line 6 of source):
    kerberos = cs_user_info['username']

KeyError: 'username'

Overview

We're going to build two simple FPGA designs today. These should be relatively quick to synthesize since they are comprised of combinational-only logic.We will go through the whole build process and discuss how to set up your file tree for a design. Be aware: We are doing this in a different way than we have in the past, and in a way that is not often discussed online. However, doing it this way will:

• Make the build quicker
• Work in a manner closer to how you would in industry
• Avoid using Vivado's GUI infrastructure
• Allow you to use whatever code editor you're most comfortable with
• Let you keep track of files in a version-control-friendly way (if you so desire)

The Project Folder

So let's get started! On your computer make a new directory and call it lab01. In that folder, make the following subdirectories called:

• hdl: This will contain .sv and .v files intended for synthesis. This is the stuff that's actually going onto your FPGA development board, to program it and make it do interesting things.
• sim: This will contain .sv and .v files intended for simulation. You'll learn more about these, how they differ from proper source files, and how we use them in a bit. They are the same type of file as those that go in hdl but used for a very different purpose so we'll want to keep them separate.
• xdc: This will contain the constraints file for sythesis. We'll explain what this is later, but there is usually only one of these, and it has a .xdc extension.
• obj: This will contain output products and information from Vivado. This includes the bit file, which is eventually written to the FPGA, as well as any logs and reports we may request.

SV Files

These are your (System) Verilog files. They have an ".sv" extension on them to inform Vivado (and other software) that they use the SystemVerilog standard. Occasionally we'll also use regular ".v" files for particular purposes. The purpose of these files can be divided into two categories:

• Synthesis Files: These files describe hardware designs. These eventually get turned into actual circuits onboard the FPGA. As mentioned previously, we place them in the hdl directory.
• Simulation Files: These files, often called "test benches" are not meant to be synthesized. Instead, they are used to test other Verilog files. These files will live in the sim directory. It is best to keep them separate so that Vivado doesn't try to synthesize non-synthesizable logic.

Why simulation? Since Verilog takes a long time to build for FPGAs, using test benches to simulate modules off-FPGA dramatically reduces development time. When writing software (ie, your 6.101/6.009 lab) your code executes quickly, and writing tests might feel like a waste of time. Since we're writing code to describe hardware, not software, our code takes way longer to build, making simulations significantly more valuable.

XDC Files

An FPGA is a chip. That chip has a bunch of metal pins on it that are named with a letter-number grid scheme like "C13" or "K15"¹. We use an XDC file to apply settings to these pins, as well as to give them more meaningful names. For example, pin C17 is hardwired to one of the LEDs on our FPGA development board, so we call it led[0] in the XDC file. Then in our actual top level design we can refer to that pin as led[0].

A starter XDC file top_level.xdc is provided for you here. This is not a complete XDC, only really having relevant pin-labels for this first week's assignments. We'll have other starter ones for later labs. By default ALL lines are commented out. At the start of any project, uncomment the lines used as inputs/outputs in your top_level module, which serves as the entry point for your entire design. Go ahead and put a copy of this file into your xdc directory. We'll come back to it in the rest of the lab.

Output Files

When you build a design with Vivado it outputs a .bit file that configures the FPGA's internals to match your design. It also generates a number of reports about resources used, timing issues, and other things. Much of the time the pot of gold at the end of the rainbow is the .bit file, though the reports can be really helpful too. For now this directory is empty since we haven't run Vivado yet.

Build

Regardless of the way you'll be running Vivado, you should download this pretty general build.tcl file and place it in the root of your project directory. This file is a TCL script (often pronounced "tickle"). It is a widely used programming language you'll often encounter in electronics design fields. Vivado can be run using this tcl script (rather than us having to push a bunch of a buttons like a peasant), so it saves some time. In future labs/weeks, we'll update and modify this script, but for now, as it stands should be a pretty good starter.

• If you installed Vivado locally, you'll use your preferred Vivado setup to generate a bitstream for this design.
• If you are running Vivado on a lab machine, do the same as above.
• If you're using lab-bc, clone remote recursively as discussed on Vivado

Once you're done, continue onto the real stuff in the first part of lab :D