Lab 01: Lab Setup

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

KeyError: 'username'

Make sure you follow the software setup documentation.

ALSO you need to do two Lab Safety Things for 6.205:

1. Please go to this link and take the EHS00509w Electrical Safety Awareness course. To do this, search for "509" under the Course Catalog Page, which should find the "Electrical Safety Awareness" course. Do this course. It isn't too bad.
2. Please go to this link and read and sign the undergraduate lab safety acknowledgement form. (Note this site still uses MIT certificates, not that Okta crap, so you do need to make sure your certificate is still valid.)

Overview

We're going to build two simple FPGA designs today. These should be relatively quick to synthesize since they are comprised of relatively simple logic (as designs get more complicated, builds will take longer...plus if you do the design poorly or lazily, it can take even longer). 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 python files (running the cocotb library) intended for simulation. You'll learn more about these in a bit.
• 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. 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¹.

Python Files

We will use Python files (and the cocotb library) to simulate our digital designs. Why simulation and not just build it and see what it does? 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 general XDC file top_level.xdc is provided for you here. This is a complete XDC for the board, but in any given lab we'll only use portions of it. By default ALL lines are commented out in this file. At the start of any project, you should 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 may need to update and modify this script, but for most things, it should just work.

• 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, make sure your Python environment is activated so that it will run as discussed here: Vivado

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