Skip to content

Section 11: Assembly Programming

Today we will continue to learn how to write simple assembly programs and test them on our processor FL model (also called a processor ISA simulator). As a reminder the, the TinyRV1 ISA manual is located here:

1. Logging into verilog-exam with VS Code

Next week is the Verilog coding exam! To make sure you have no issues next week, please try logging into the verilog-exam server. 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
  • Double click on ECE 2300 VS Code to start VS Code
  • Enter server number 99 to access the verilog-exam server
  • Enter your password
  • Be patient! It might take 2-3 minutes before you connect.
  • Make sure VS Code is full screen

Once you have connected VS Code to the server and you are at the terminal prompt you must man- ually source the setup script like this:

% source setup-ece2300.sh

Then use the following so the course instructors know you were able to successfully access the verilog-exam server.

% cd ${HOME}/ece2300
% echo "sucess" > success.txt

Now go ahead and close VS code so we can log into the ecelinux server in the next part.

2. Logging Into ecelinux with VS Code

To log into the ecelinux server use similar steps except enter the server number you usually use.

  • Open the ECE 2300 folder on the desktop
  • Double click on ECE 2300 VS Code to start VS Code
  • Enter server number to access the ecelinux servers

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-sec11-asm-prog sec11
% cd sec11
% 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/find.asm: Simple TinyRV1 assembly program
  • lab4/asm/find-adj-eq.asm: Simple TinyRV1 assembly program
  • lab4/asm/find-adj-neq.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/sec11
% 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. Find Assembly Program

Our first assembly program will search an array in memory to find if it contains the value 9. The program will set register x6 to be one if 9 is found and zero otherwise. The pseudocode for the find program is shown below.

a = [ 7, 2, 3, 9, 1, 8, 6, 4 ]
n = 8

found = 0
for i in range(1,n):
  if ( a[i] == 9 ):
    found = 1
    break

Here is the corresponding assembly.

.text
  addi x1, x0, 256        # a array
  addi x2, x0, 8          # n = 8
  addi x6, x0, 0          # found = 0

loop:
  lw   x3, 0(x1)          # read a[i]
  addi x4, x0, 9          #
  bne  x3, x4, notfound   # if ( a[i] != 9 ) goto notfound
  addi x6, x0, 1          # found = 1
  jal  x0, done           # goto done

notfound:
  addi x1, x1, 4          # a ptr bump
  addi x2, x2, -1
  bne  x2, x0, loop

done:
  jal  x0, done

.data
  .word 7
  .word 2
  .word 3
  .word 9
  .word 1
  .word 8
  .word 6
  .word 4

Take a few minutes to understand how the pseud-code maps to the assembly.

2.1. Executing find on a Worksheet

Let's start by using the paper worksheet to execute the find program by hand on pen-and-paper. Remember to use the following four steps before starting to execute the program:

    1. Write the assembly program into memory starting at address 0
    1. Write the data into memory starting at address 256
    1. Set the PC to zero (if shown on the worksheet)
    1. Set x0 to be zero

Carefully use Xs to indicate which instructions are excuted. Remember to only place Xs next to real instructions. Do not place an X next to an assembler directive, blank line, or label.

Discussion Check-Off Task 2: Review Worksheet

Compare your worksheet with a peer student's worksheet to make sure they are the same. Discuss any differences.

2.2. Executing find with the ISA Simluator

Now that we have executed the find program using pen-and-paper we can now execute the program on the ISA simulator.

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

% cd ${HOME}/ece2300/sec11/build
% code ../lab4/asm/find.asm

We first need to assemble the program from assembly instructions into machine instructions using an assembler.

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

The output will show each memory address in decimal and hex and the contents of that memory location. For addresses 0-252, it shows the assembly instruction and corresponding machine instruction in binary. For addresses 256-508, it shows the data in hex. Notice how for the instructions the assembler has converted all of the labels into absolute numeric addresses shown in the assembly, and these absolute addresses are converted into PC-relative immediates in the machine instructions.

You can save the machine instructions using the -o command line option.

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

Notice how the binary includes 128 lines, one for each 4B word in memory even if that word is zero. The binary is a complete memory image and contains all of the data required to initialize all 512B in physical memory.

You can disssemble the machine instructions back into assembly instructions using a disassembler.

% cd ${HOME}/ece2300/sec11/build
% ../scripts/tinyrv1-disassemble find.bin

The result should be similar to what we had in the find.asm file except using absolute numeric addresses instead of labels.

We are now ready to execute the find program on the ISA simulator.

% cd ${HOME}/ece2300/sec11/build
% make proc-isa-sim
% ./proc-isa-sim +bin=find.bin +tui

Step through the program and verify it corresponds to your pen-and-paper execution. Ensure that the result stored in x6 is correct. Use q to stop the simulation. Start running the simulation again.

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

You can enter a few commands at the (tui) prompt. Enter /100 to run 100 instructions without stopping and verify the result stored in x6 is one indicating that the program found the number 9 in the array. Use q to stop the simulation.

Discussion Check-Off Task 3: Verify find Program

Show a peer student what your TUI mode looks like after executing the find program. Verify the contents of x6 is one.

2. Find Adjacent Equal Assembly Program

Now it is your turn to write your own assembly program. Your first program should search an array in memory to find the first pair of consecutive elements that are equal. The program should then set register x6 to the value of the equal elements, or 99 if no such pair exists. The pseudocode is shown below.

a = [ 7, 2, 3, 9, 9, 8, 6, 4 ]
n = 8

found = 99
for i in range(1,n):
  if ( a[i] == a[i+1] ):
    found = a[i]
    break

We have provided you a template in find-adj-eq.asm.

% cd ${HOME}/ece2300/sec11/build
% code ../lab4/asm/find-adj-eq.asm

Go ahead and implement the program and verify it is working using the ISA simulator and TUI mode. Make sure the value in x6 is 9 at the end of the program indicating that the program found two consecutive elements with the value 9 in the array.

Discussion Check-Off Task 4: Verify find-adj-eq Program

Show a peer student what your TUI mode looks like after executing the find-adj-eq program.

3. Find Adjacent Not Equal Assembly Program

Let's write a more complicated assembly program which searches an array in memory to find the first pair of consecutive elements that are not equal. The program should then set register x6 and x7 to the values of these two elements or 99 if no such pair exists. The pseudocode is shown below.

a = [ 7, 7, 7, 7, 9, 9, 9, 4 ]
n = 8

first  = 99
second = 99
for i in range(n-1):
  if ( a[i] != a[i+1] ):
    first  = a[i]
    second = a[i+1]
    break

We have provided you a template in find-adj-eq.asm.

% cd ${HOME}/ece2300/sec11/build
% code ../lab4/asm/find-adj-neq.asm

Go ahead and implement the program and verify it is working using the ISA simulator and TUI mode. Make sure the value in x6 is 7 and x7 is 9 at the end of the program indicating that the program found two consecutive elements with the value 9 in the array.

Discussion Check-Off Task 5: Verify find-adj-neq Program

Show a peer student what your TUI mode looks like after executing the find-adj-neq program. Verify the contents of x6 is 7 and the contents of x7 is 9.

4. Challenge Program

This is an optional taks for the assembly experts in the class. Go back to the find.asm program and refactor the find program into a function which takes the value to search for as an argument. Then call this function twice, once with the value 9 (which should set x6 to one) and one with the value 5 (which should set x6 to zero). Here is the pseudo-code.

a = [ 7, 2, 3, 9, 1, 8, 6, 4 ]
n = 8

def find( v ):
  found = 0
  for i in range(1,n):
    if ( a[i] == 9 ):
      found = 1
      break
  return found

find(9)
find(5)

You will need to use a jal to implement the function call and jr to implement the function return. You can store the argument v in register x4 and the return value in register x6. Use the ISA simulator with TUI mode to verify your program.

Discussion Check-Off Task 6: Challenge Program

Show a peer student what your TUI mode looks like after executing the find program with a function call. Verify the contents of x6 is 1 for finding 9 and then 0 for finding 5.