Skip to content

Section 9: ISA Simulators

Today we will learn how to use a Verilog functional-level (FL) model. This is a new kind of Verilog modeling which only models the functional-level behavior of a module and is not meant to be synthesizable. A FL model is a kind of "executable specification" which can be very useful for verification, since we can compare the behavior of our gate-level or RTL model to the FL model to ensure correctness.

We will be exploring a FL model of a TinyRV1 processor; these kind of models are often called "instruction set architecture simulators" or "ISA simulators" since they model just the ISA without any of the microarchitectural implementation details. Go ahead and open up the TinyRV1 ISA manual here:

1. Logging Into ecelinux with VS Code

We have drastically simplified the process of logging into ecelinux with VS Code using the workstations. Find a free workstation and log into the workstation using your NetID and standard NetID password. Then complete the following steps:

  • Open the ECE 2300 folder on the desktop to locate two shortcuts
    • ECE 2300 Handouts: opens the handouts page
    • ECE 2300 VS Code: starts VS Code (enter server number and password)

That is it! Our custom ECE 2300 VS Code script will take care of:

  • installing Remote SSH, Verilog HDL, Surfer extensions
  • configuring SSH for accessing ecelinux without extra prompts
  • starting VS Code connected to ecelinux without extra prompts
  • opening the file explorer in your ${HOME}/ece2300 directory
  • installing the Verilog HDL extension on the server
  • opening a terminal

There is no need to fork the repo for today's discussion section. Simply clone the repo as follows.

% source setup-ece2300.sh
% mkdir -p ${HOME}/ece2300
% cd ${HOME}/ece2300
% git clone git@github.com:cornell-ece2300/ece2300-sec09-isa-sim sec09
% cd sec09
% tree

The repo includes the following files:

  • Makefile.in: Makefile for the build system
  • configure: Configure script for the build system
  • configure.ac: Used to generate the configure script
  • scripts: Scripts used by the build system
  • ece2300: ECE 2300 unit testing library and miscellaneous macros
  • lab4/lab4.mk: Tells build system about files in this subproject
  • lab4/tinyrv1.v: Verilog helper module for the TinyRV1 ISA
  • lab4/test/ProcFL.v: Verilog functional-level model for the TinyRV1 ISA
  • lab4/sim/proc-isa-sim.v: Interactive TinyRV1 ISA simulator
  • lab4/asm/prog1.asm: Simple TinyRV1 assembly program
  • lab4/asm/prog2.asm: Simple TinyRV1 assembly program

Go ahead and create a build directory, run configure to generate a Makefile, and run the tests.

% cd ${HOME}/ece2300/sec09
% mkdir -p build
% cd build
% ../configure
% make check

To make it easier to cut-and-paste commands from this handout onto the command line, you can tell Bash to ignore the % character using the following command:

% alias %=""

Now you can cut-and-paste a sequence of commands from this tutorial document and Bash will not get confused by the % character which begins each line.

Throughout this handout you will see discussion check-off tasks. The TAs will not be assessing your understanding. Instead, students should show their work to another student and then together they will perform a self and peer assessment of each discussion check-off task. The student peer will initial the check-off. As always, the assesssment should based on the demonstrated understanding using our five-point scale as follows:

  • 5 (Mastery): Student mastered the check-off without any help and feels very confident in their understanding; student could teach other students about the corresponding concepts

  • 4 (Accomplished): Student accomplished the check-off with maybe a little help and feels good about their understanding, but could probably use a little more time to really master their understanding; student is probably not quite ready to teach other students about the corresponding concepts

  • 3 (Progressing): Student completed the check-off but needed significant help; student is not quite confident in their understanding and needs more time to really improve their understanding of the corresponding concepts

  • 2 (Beginning): Student started but did not finish the check-off

The goal is not for one student to judge another student, but for the two students to agree on the demonstrated level of understanding. There is nothing wrong with agreeing on a 4 or 3. This can help a student crystallize where they should focus their time to improve the understanding!

Near the end of the discussion section, the student should raise their hand and show their overall progress to a TA who will initial and collect the check-off sheet.

Discussion section check-off sheets are not graded!

Unlike the lab check-off sheets, the discussion check-off sheets are not graded. They will not impact your grade in the course in any way. The discussion check-off sheets provide formative self and peer assessment. They enable students to gauge their progress in mastering the concepts presented in the discussion section, and enable the instructors to get an overall feel for how the class is doing. Please make sure your self and peer assessments are honest and accurate!

Discussion Check-Off Task 1: Verify Initial Release

We always start by running make check to get a high-level view of what is and is not working. So go ahead and do make check again and look closely at what tests are passing and what tests are failing. Show a peer student the result of make check. Work together to conduct a self and peer assessment and have the peer student initial the check-off.

2. Assembling a Simple TinyRV1 Program

A processor executes a machine program which is a sequence of machine instructions. Each machine instruction is a sequence of ones and zeros that tells the processor what to do. Writing machine programs by hand is tedious, so usually we write the more human readable assembly programs which are sequence of assembly instructions. Each assembly instruction is a string that specifies the kind of instruction and the instruction operands. There is a one-to-one mapping between machine instructions and assembly instructions. We use two tools to convert between machine and assembly programs:

  • Assembler translates assembly programs into machine programs
  • Disassembler translates machine programs into assembly programs

Go ahead and open the provide assembly program in VS Code.

% cd ${HOME}/ece2300/sec09/build
% code ../lab4/asm/prog1.asm

It should look like this:

addi x1, x0,  9  # R[x1] = R[x0] + 9
addi x2, x1,  7  # R[x2] = R[x1] + 7
addi x1, x0, 13  # R[x1] = R[x0] + 13
addi x1, x1,  2  # R[x1] = R[x1] + 2
addi x6, x1,  0  # R[x6] = R[x1] + 0

There is one assembly instruction per line, and comments are denoted with the #. This simple program calculates 2+2 and stores the result in register x3.

Let's use a TinyRV1 assembler to translate this assembly program into a machine program.

% cd ${HOME}/ece2300/sec09/build
% ../scripts/tinyrv1-assemble ../lab4/asm/prog1.asm

The result should look like this:

00000000_10010000_00000000_10010011
00000000_01110000_10000001_00010011
00000000_11010000_00000000_10010011
00000000_00100000_10000000_10010011
00000000_00000000_10000011_00010011

There are three instructions and each instruction translates into a 32-bit machine instruction. Take a few minutes to look at ISA manual and convince yourself that the assembler has transated these three assembly instructions into the correct machine instructions.

We can save the machine instructions into a "binary file" with then -o command line option like this:

% cd ${HOME}/ece2300/sec09/build
% ../scripts/tinyrv1-assemble -o prog1.bin ../lab4/asm/prog1.asm
% cat prog1.bin

We can use a TinyRV1 disassembler to translate the binary file which contains the machine program back into the corresponding assembly instrucitons.

% cd ${HOME}/ece2300/sec09/build
% ../scripts/tinyrv1-disassemble prog1.bin

3. Simulating TinyRV1 Arithmetic Instructions

Let's now use an ISA simulator to simulate this simple TinyRV1 program. Start by looking at the Verilog FL model for the TinyRV1 instruction set using VS Code.

% cd ${HOME}/ece2300/sec09/build
% code ../lab4/test/ProcFL.v

IMPORTANT: this kind of Verilog modeling is very different from what we have used in the past! This Verilog FL model is not synthesizable. It is not meant to model the details of the hardware but is instead meant o provide a high-level functional level model which we can use for verification.

We need to first build the ISA simulator.

% cd ${HOME}/ece2300/sec09/build
% make proc-isa-sim

Now let's run our TinyRV1 program binary on the ISA simulator.

% cd ${HOME}/ece2300/sec09/build
% ./proc-isa-sim +bin=prog1.bin +step

Press enter to execute instruction one at a time. Press q and then enter to quit the simulation. The trace output should look like this:

cycle pc         inst                 wreg wdata
------------------------------------------------------
   0: 0x00000000 addi x1, x0, 9          1 0x00000009
   1: 0x00000004 addi x2, x1, 7          2 0x00000010
   2: 0x00000008 addi x1, x0, 13         1 0x0000000d
   3: 0x0000000c addi x1, x1, 2          1 0x0000000f
   4: 0x00000010 addi x6, x1, 0          6 0x0000000f
   5: 0x00000014 illegal inst

The trace output shows the cycle number, program counter (PC), instruction, what register the instruction is writing (wreg), and what data is being written to that register (wdata).

The TinyRV1 ISA manual says that the PC is reset to 0 so the very first instruction executed is at memory address 0. The trace output shows that the first instruction writes the value 9 to register x1, the second instruction adds 7 to the value in register x1 and writes the result to register x2, and so on.

We can also use a text user interface (TUI) mode to better visualize the execution of the ISA simulator much in the same way as we use worksheets in lecture.

% cd ${HOME}/ece2300/sec09/build
% ./proc-isa-sim +bin=prog1.bin +tui

The TUI output should look like this:

>addi x1, x0, 9               Registers         Memory         MemMapped IO
 addi x2, x1, 7             .----------.     .----------.      .----------.
 addi x1, x0, 13        x31 |        x | 508 |        x | out3 |        0 |
 addi x1, x1, 2         ... |   ....   | ... |   ....   | out2 |        0 |
 addi x6, x1, 0         x15 |        x | 296 |        x | out1 |        0 |
 illegal inst           x14 |        x | 292 |        x | out0 |        0 |
 illegal inst           x13 |        x | 288 |        x |  in3 |        0 |
 illegal inst           x12 |        x | 284 |        x |  in2 |        0 |
 illegal inst           x11 |        x | 280 |        x |  in1 |        0 |
 illegal inst           x10 |        x | 276 |        x |  in0 |        0 |
 illegal inst            x9 |        x | 272 |        x |      '----------'
 illegal inst            x8 |        x | 268 |        x |
 illegal inst            x7 |        x | 264 |        x | enter to execute
 illegal inst            x6 |        x | 260 |        x | current inst
 illegal inst            x5 |        x | 256 |        x | /quit : quit
 illegal inst            x4 |        x | ... |   ....   | /run : run
                         x3 |        x |  12 | 00208093 | /N : sim N cycs
    Prog Counter         x2 |        x |   8 | 00d00093 | /inN=M : set in
   .------------.        x1 |        x |   4 | 00708113 |
   |          0 |        x0 |        0 |   0 | 00900093 | cycles = 0
   '------------'           '----------'     '----------' stats  = 0

Notice that the instructions are stored in the first three words in memory! 0x00900093 is the hexadecimal representation of the first instruction (addi x1, x0, 9). The instructions are always stored in memory starting from address 0. The little > indicates which instruction will be executed next. The program counter, registers, and memory all represent the state before this instruction is executed. Press enter to execute the first instruction. You should see the > advance to the next instruction, the PC updated to 4, and the value 2 in register x1. Step through all three instructions to verify that the registers end up with the correct values. Press q and then enter to quit the simulation.

Take a look at the assembly program in prog2.asm. Use tinyrv1-assemble to assemble this program into a binary program. Then execute this program using the TUI mode.

Discussion Check-Off Task 2: Verify Program 2

Show a peer student what your TUI mode looks like after executing the final instruction in the program.

4. Writing TinyRV1 Assembly Programs

In this section, you will write, assemble, and execute two TinyRV1 assembly programs.

  • Fibannci Program: This new assembly program should be named fib.asm. The assembly program should generate the Fibonacci sequence in registers x1 through x7.

  • Cube Program: This new assembly program should be named cube.asm. The assembly program should write x2 with the cube of the value in register x1.

For both programs use tinyrv1-assemble to assemble the program and then proc-isa-sim to simulate the program using TUI mode.

Discussion Check-Off Task 3: Verify Fibonacci Program

Show a peer student what your TUI mode looks like after executing the final instruction in the program. Have the peer student verify that your program does indeed produce the Fibonacci sequence.

Discussion Check-Off Task 4: Verify Cube Program

Show a peer student what your TUI mode looks like after executing the final instruction in the program. Have the peer student verify that your program does indeed write x2 with the cube of the value in register x1.