Lab 12 - Final Project

Lab 12 - Final Project

For this laboratory you will write a custom program for your RISC-V processor that implements a simple game on the Basys 3 board.

Learning Outcomes

  • Demonstrate understanding of RISC-V assembly language programming
  • Create custom software that controls the I/O interfaces of the FPGA system


In this final laboratory you will be able to create a custom program that executes on your RISC-V processor and that implements some interactive activity such as a game. This preliminary will guide you through a number of steps that you will need to prepare you to complete this custom program. The interactive program you create for this lab should be creative and you should try to choose something that interests you and ideally entertaining. The following suggestions may help you come up with some ideas:

  • A “paint” program that allows you to move the cursor around the screen using the buttons and then place or “paint” the custom character at the cursor location
  • A simple Pong game that moves a ‘ball’ across the screen along with paddles with players to hit the ball back
  • Draw a moving snake on the screen that reacts to the user’s buttons
  • A simple tetris game with rotating blocks falling down the screen
  • A maze game where the player moves a block through a predetermined maze built from walls
  • Hangman game that requests letters from the user and builds a hangman guy as mistakes are made

Unlike the previous labs, you can complete this lab with a partner. You can split up the work involvd with the custom project between two people. Note that submissions involving two people will be expected to be more complex than thosse submitted by individuals.

There are several additional capabilities and features of the I/O subsystem that will help you create a fun and interesting game. The preliminary will review several of these features.

Font ROM

The I/O system circuit provided in previous labs contains an internal memory that defines the the “font” of the characters that are displayed.
This memory is “Read Only Memory” (ROM) and cannot be changed at run-time. Each character is defined as an image that is 8 pixels wide and 16 pixels high. The characters are defined with two colors: foreground and background (i.e., on and off). The figure below demonstrates the definition of the character ‘A’ in this font:

The description of each character is defined within a text file that indicates which pixels are in the foreground (on) using a binary ‘1’ and which pixels are in the background (off) using the binary ‘0’. The following example demonstrates the text lines in this file that define of the character ‘A’:

// code x41
00000000   // 0
00000000   // 1
00010000   // 2    *
00111000   // 3   ***
01101100   // 4  ** **
11000110   // 5 **   **
11000110   // 6 **   **
11111110   // 7 *******
11000110   // 8 **   **
11000110   // 9 **   **
11000110   // a **   **
11000110   // b **   **
00000000   // c
00000000   // d
00000000   // e
00000000   // f

Each line of the text file defines eight bits of one row of a character. There are 16 lines for each character along with comments (i.e., ‘//’) indicating what the character should look like. The characters are ordered by their ASCII value. The entire font is defined in the text file linked below. Download this file and browse through its contents to answer several questions in learning suite about this file.


Determine the character represented by 0x18 in the file

What is the 8-bit binary value associated with line 7 of the 0x35 ASCII character (i.e., the number 5)

You can modify the font memory to create new characters that are more useful for the game you create in this lab. You can come up with custom non-ASCII characters that are specific for your lab project. For this lab, you will be required to modify the font ROM to include at least four new characters to represent a unique figures for your final lab. The example below demonstrates a simple attempt at a “pacman” character. Note that you can create larger images by using multiple unique characters side by side and above and below each other.

Binary file representation of the pacman character:

// custom character
00000000   // 0
00000000   // 1
00000000   // 2    
00000000   // 3   
00011000   // 4    **   
01111110   // 5  ****** 
01111100   // 6  *****  
11110000   // 7 ****
11110000   // 8 ****
01111100   // 9  *****  
01111110   // a  ****** 
00011000   // b    **   
00000000   // c
00000000   // d
00000000   // e
00000000   // f

Character Colors

As the preliminary of Lab #10 described, you have the ability to set a default foreground color and background color for the characters displayed on the screen. In addition to setting a default foreground/background color, it is also possible to set a custom foreground and background color for each character on the display. This allows you to create interesting colored characters with differing backgrounds that move around on the display.

To set a custom foreground and background color for a particular location on the VGA display, write a value to the character location with a non-zero color set in the upper 25 bits of the 32-bit word. If any bits [31:8] are non-zero, the VGA memory will store the store bits [19:8] into the foreground color for the character and store bits [31:20] into the background color for the character. The 32-bits used by the VGA character memory are defined as follows:

Background Color Foreground Color Unused Character Value
data[31:20] data[19:8] data[7] data[6:0]

For example, to write the character “!” (ASCII 0x21) with a red foreground color (0xf00) and a blue background color (0x00f), you would write the following value to the VGA display:

0x21 | (0xf00 << 8) |  (0x00f << 20)  = 0x00ff0021

To write the character “$” (ASCII 0x24) to the display using the default background and foreground, then write the character value 0x24 to the memory (bit 7 is zero for 7-bit ASCII characters).

Determine the 32-bit value needed to write the character ‘?’ with a background of yellow (0xff0) and a foreground of cyan (0x0ff)

Character Memory

The VGA display circuitry includes a character generator that will display characters in a grid of 80 columns by 30 rows.
The initial contents of this character memory can be set to provide an interesting “background” to your display. The character memory file contains a sequential list of 32-bit hexadecimal numbers that each will be placed in the character memory in sequential order. The following text demonstrates the first fewe lines of the “checker” memory background (linked below). The file format accepts c-style single line comments:

// Row 0
f000ff20  // 0,0
00ff0020  // 1,0

Several example background memory files have been provided for you below:

  • checker_mem.txt
  • random_mem.txt
  • border_mem.txt

Desceribe the details of the character located on row 12, column 27 in the “checker_mem.txt” file


Exercise #1 - I/O System Simulation

In this first exercise you will simulate your processor from the previous lab executing within the I/O system executing a program that writes to the VGA. You will have a new top-level I/O design named that will insert your processor from lab 11. Begin this exercise by creating a new project for this lab by executing the script create_final_project.tcl in Vivado. This script will add of the HDL files you need to build your final processor.

A simple test I/O program, final_iosystem.s, has been written that operates on the I/O system described above. You will need to compile this program and set the ‘text’ and ‘data’ memories of the top-level design with the compiled memory files from this assembly language program. You will also need to add the memories your project as you have done in previous labs.

This program is a simple game that will have you move the ‘A’ character to the location of the ‘B’ character and time how long it takes. The assembly language file uses some interesting syntax that we have not used before in class to read from and write to data memory in the data segment. The following instruction will read the memory location in the data segment specified by the label ‘ENDING_CHARACTER’:

# 'gp' holds the base address of the data segment
# 'ENDING_CHARACTER' is a constant label pointing to a specific locatation in the data memory
# This syntax will be replaced by 
#   lw t0, X(gp)  where X is the constant offset of this variable from the base of the .data segment
lw t0, %lo(ENDING_CHARACTER)(gp)                   # Load character value to write

# Later in the code is a memory location reserved in the data segment for this value

    .word CHAR_C_YELLOW

Two instructions are needed to perform a ‘store’ in the data segment:

# This instruction loads the address of the ENDING_CHARACTER_LOC variable into t1
# (it is a constant offset added to the value of gp)
lw t1, %lo(ENDING_CHARACTER_LOC)(gp)               # Load address of character location
# This instruction stores the contents of t0 into the address loaded by t1
sw t0, 0(t1)

Simulate your system by executing the final_sim.tcl TCL script. This script will drive the top-level I/O and press button right, wait for the button to propagate through the debouncer and then press the button down.

Review the simulation console to answer the questions about the tcl script execution in learning suite.

Exercise #2 - Download System

After verifying your processor works correctly with the I/O system, create a bitstream of your system and download it to your board. Also, create a “.dcp” file for your system as described in the following tutorial. You will need this .dcp file to update the program running on the system in a later exercise.

Carefully review the synthesis logs to see if there are any unusual synthesis warnings.

Summarize the utilized resources for your implemented design and determine the worst negative slack timing of your processor.

After generating the bitfile, download the bitfile onto your Basys3 board and play the “game” implemented in the precompiled program. Indicate the “time” it took you to move the ‘A’ character to the ‘C’ character as indicated by the seven segment display.

Indicate your best game completion time.

Exercise #3 - Memory Update

In this exercise you will update the bitfile to include a modified font ROM and background character arrray. Specifically, copy the font_mem.txt file and rename it to font_mem_mod.txt. Modify the following characters used in the default program (you can modify additional characters if you like):

  • ‘A’
  • ‘C’
  • ‘Z’

You will need to include this in your lab submission. The following command demonstrates how you can modify your bitstream file to include the modified font characters. A new file, font.dcp, is also created that you will use later in this exercise. Note: You will need to create a checkpoinot (.dcp) file to run this command as described in the update memory tutorial.

$ vivado -mode batch -source ../resources/load_mem.tcl -tclargs updateFont final_io.dcp font_mem_mod.txt font.bit font.dcp

Download this bitfile and verify that your updated bitstream has your updated characters.

In addition to changing three characters, you need to create a new custom background file that provides a different background. You can copy one of the existing memory files listed above and modify it to provide an interesting background. Name your background background_mem.txt. You will need to include this in your lab submission.

The following command demonstrates how to update your bitfile with a new background. Note that you need to use the ‘font.dcp’ checkpoint file generated in the previous command so that your background also uses your new characters. This command generates a new bitfile with your updated background and a new dcp file (that you can use to change the program at a later time).

$ vivado -mode batch -source ../resources/load_mem.tcl -tclargs updateBackground font.dcp background_mem.txt back.bit back.dcp

Download your bitstream to make sure you have the updated characters and background.

Exercise #4 - Interactive Game

For your final exercise you will create a custom interactive game that uses the buttons and switches and displays the results on the VGA display. There is no new Verilog required for this exercise - your program should interface with the I/O sub-system that is given to you. This program will be much more involved than any of the simple programs you have written so far. Most of the time spent on this lab will be writing and debugging your program.

The minimum requirements of your program are as follows:

  • Use the VGA display - You must include at least four modified characters in the font ROM. Your project font file should be named project_font.txt.
  • The program must have at least 128 instructions in a single assembly file named project.s
  • The system must have a custom background display (named project_background.txt)
  • Use at least two button
  • Write something to the 7-segment display
  • Use at least one LED

Create a text file that includes a detailed description of your program (named instructions.txt). Provide sufficient information for a user of your interactive program to use (i.e., an instruction manual). These instructions must match the operation of your final program. Note: If you completed your project as a team, clearly indicate in your ‘instructions.txt’ file the names and net IDs of both people working on the project.

Pass Off

To create your submission .zip archive, make sure the following files are in the ‘lab12’ directory:

  • font_mem_mod.txt
  • background_mem.txt
  • project.s
  • project_font.txt
  • project_background.txt
  • instructions.txt

Note: If you are working in a team, make sure both students submit the same files in their own repository.

Make sure you do not add unnecessary files (including Vivado project files) to your repository. Tag your repository with the string lab12_submission and push your repository back to the origin. Test your submission by running the pass-off script found in the starter code. Review the instructions for submitting and passing off labs to make sure you have completed the lab properly.

How many hours did you work on the lab?

Provide any suggestions for improving this lab in the future.

Last Modified: 2022-05-31 12:23:24 -0500