ECE 190 Spring 2011

Machine Problem 3
MP3.1 Due: 5 p.m., Wednesday March 9th, 2011
MP3.2 Due: 5 p.m., Friday March 18th, 2011

Problem Statement
For this machine problem, you will be writing a program in the LC-3 assembly language that
implements Conway’s “Game of Life.” A detailed description of “Life” can be found at:

http://en.wikipedia.org/wiki/Conway%27s_Game_of_Life

Your program will be responsible for evaluating a fixed-size 16x16 “life board” consisting of 256
individual cells each held in memory in row-major order. Row-major order implies that the game
board data for first row is stored first, followed by the second row, and so on. The final assembly
program will read in the board starting at memory address x5000 and from there a user will be able
to clear, configure, or “run” the board through a single iteration of “Life.”

For MP3.1 you are required to implement subroutines that clear, setup, and display the board as
well as implement all the keyboard and display I/O subroutines. For MP3.2 you are required to
implement the “Life” algorithm that applies the game rules to each cell of the board.

There is a great amount of detail to testing and implementing this MP. Be sure to read the ENTIRE
document, SEVERAL TIMES, to make sure you have a full understanding of the MP prior to coding.

Hand In
Because of the complexity (and error prone process) of turning in multiple files, “make handin-3.1”
and “make handin-3.2” commands have been provided (thanks to the Makefile!) that will turn in all
of your code. If you wish to handin only a specific file you can do so by typing “handin --MP 3.1
<file>” or “handin --MP 3.2 <file>”. You may hand in as many times as you like, but only the last
submission will be graded.

You can use the “verify --MP 3.1 <file>” and “verify --MP 3.2 <file>” commands to view any of the
files already submitted.

1
Game of Life
The “Life” board used in this MP is a 16x16 board (256 total cells) that is stored in row-major order
starting at memory address x5000. (Hint: Additional space is available starting at memory address
x6000 that you can use as temporary storage place to hold another copy of the board, if needed.)
Each memory location represents one cell where an x0000 represents a dead cell and an x0001
represents a live cell. Other states shall not exist (x0002-xFFFF) and you are not required to handle
them.

When displaying the board on the terminal, each live cell will be represented by the pound (‘#’)
character and each dead cell represented by a period (‘.’) character.

Any two cells are neighbors if they share a border, and each cell has eight neighbors. For example,
the live cell that is highlighted in red in the picture below has eight live neighbors that are all
highlighted in green. Each cell has an (X,Y) coordinate where the top left corner of the board has
coordinate (0,0). The board “wraps around” in the sense that each cell has eight neighbors
regardless of where it is located. For instance the cell at (15,1) has neighbors to the NE, E, and SE
with coordinates of (0,0), (0,1), and (0,2).

(0,0) (15,0) (0,0) (15,0)

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . # . . . . . . . . . . .
. . . # # # . . . . . . . . . . . . . # . # . . . . . . . . . .
. . . # # # . . . . . . . . . . . . # . . . # . . . . . . . . .
. . . # # # . . . . . . . . . . . . . # . # . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . # . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
(0,15) (15,15) (0,15) (15,15)
Initial State After One Generation

When iterating through the “Life” game, each cell lives or dies depending on the following rules, all
of which are shown in the above example:
1. Any live cell with fewer than two live neighbors dies.
2. Any live cell with two or three neighbors continues to live on.
3. Any live cell with more than three live neighbors dies.
4. Any dead cell with exactly three live neighbors is resurrected.

2
Required Decomposition
For this MP it is required to decompose the problem as outlined. Also note that each subroutine
must be contained in a different assembly source code file. For example, the PRINT_BOARD
subroutine must be placed in the assembly file print.asm.

In order to make partial credit grading and unit testing possible, each subroutine is required to use
specific registers for input and output data. Registers not used for subroutine output must be
callee-saved. For example, the CALC_ADDR subroutine must use R0 and R1 to input X and Y
coordinates and store the corresponding output address in R2. R0, R1, R3, R4, R5, R6, and R7 must
not have changed from the caller’s perspective after the callee returns.

The table below outlines the required functions, their corresponding file locations, and a
description of the inputs and outputs that you must implement. No other inputs and outputs to
these functions are allowed. Helper subroutines and constants allowed are provided that they are
contained in the same file as the subroutine they are meant to aid. mp3.asm (MAIN) and clear.asm
(CLEAR_BOARD) are already finished and need no editing.

Detailed function descriptions and requirements are listed in the comments at the top of each
corresponding file.

To call one of these subroutines from within another you will need to load the starting address into
a register and invoke JSRR.

Subroutine Starting Addr File Register Inputs Register Outputs

MAIN x3000 mp3.asm NONE NONE
GET_INPUT x4000 input.asm NONE R0 – Numeric Value of
User Input [0-9, A-F]
R1 – User typed q
CALC_ADDR x4100 addr.asm R0 – X Coordinate R2 – Mem Address
R1 – Y Coordinate
LIFE x4300 life.asm R0 – X Coordinate NONE
R1 – Y Coordinate
ITER_BOARD x4400 iter.asm NONE NONE
CLEAR_BOARD x4500 clear.asm NONE NONE
SETUP_BOARD x4600 setup.asm NONE NONE
PRINT_BOARD x4700 print.asm NONE NONE

3
Checkpoint 1 (Due: 5 p.m., Wednesday March 9th, 2011)
For the first checkpoint, you will need to implement all supporting subroutines necessary to clear,
setup, and print the 16x16 “Life” board. Skeleton code has been provided in mp3.asm, print.asm,
setup.asm, clear.asm, input.asm, and addr.asm.

Specifics
 Each function has required inputs and outputs outlined in each file.
 Each function also has a detailed description in the comments.
 Each function will be individually tested for maximum partial credit opportunities.
(Example: When testing SETUP_BOARD, we will use your setup.asm code and all other files
will use the gold code.)
 To receive any credit for CALC_ADDR you cannot use a loop to implement the
multiplication.
 To receive any credit for SETUP_BOARD you must call GET_INPUT and CALC_ADDR.
 To receive any credit for a file turned in, that file must compile.

Grading
Functionality (80% Total)
20%: PRINT_BOARD
20%: SETUP_BOARD
20%: GET_INPUT
20%: CALC_ADDR
Style (10%)
3%: No line of code is wider than 120 characters.
7%: Assembly code and comments are formatted properly.
Comments (10%)
3%: Register table included for every subroutine tested in MP3.1.
7%: Code is well commented.

Late Work Policy

MPs can be turned in up to 48 hours late with a late penalty of 0.625% per hour (rounded up to the
nearest hour). For example, turning in a project at 4:59pm on a Friday (actual due time 5pm
Wednesday) will result in a 30% late penalty.

4
Checkpoint 2 (Due: 5 p.m., Friday March 18th, 2011)
For the second checkpoint, you will need to finish the MAIN code and all supporting subroutines not
implemented in MP3.1. Specifically you will need to implement LIFE and ITER_BOARD.

Specifics
 Each function has required inputs and outputs outlined in each file.
 Each function also has a detailed description in the comments.
 Each function will be individually tested for maximum partial credit opportunities.
 To receive credit for LIFE you must implement a call (or calls) to CALC_ADDR (code reuse is a
good thing!). ITER_BOARD does not need to use CALC_ADDR.
 Loops are highly encouraged in ITER_BOARD.
 To receive any credit for a file turned in, that file must compile.

Grading
Functionality (80% Total)
40%: ITER_BOARD
40%: LIFE
Style (10%)
3%: No line of code is wider than 120 characters
7%: Assembly code and comments are formatted properly.
Comments (10%)
3%: Register table included for every subroutine tested in MP3.2.
7%: Code is well commented.

Late Work Policy

MPs can be turned in up to 48 hours late with a late penalty of 0.625% per hour (rounded up to the
nearest hour). For example, turning in a project at 4:59pm on a Friday (actual due time 5pm
Wednesday) will result in a 30% late penalty.

5
Style and Comments
MP3 must be written in LC-3 assembly language for any credit to be received. Each function,
including any provided constants, strings, or data must contain less than 256 instructions. As noted
in the ‘Specifics’ sections, some functions require (or prohibit) the use of certain function calls or
branching. Please read those sections carefully!

In general, you should use the commenting style provided in the Student Manual. For readability
reasons, you must not have more than 120 characters on a single line for this MP. If you are writing
a long comment that would otherwise exceed 120 characters, you should continue your comment
on the next line.

At the top of your code, you must include a comment section with your name, date (“Spring 2011”
is sufficient), a brief description of the function (basic description already provided but feel free to
add to it), and a register table describing how the registers are used in that subroutine.

Tools
You should use a recommended text editor to code your program.

To make the machine code conversion and testing process easier and more familiar to you, we a
have provided you with a Makefile. To convert your machine code to object files, you may simply
execute “make MP3.1” or “make MP3.2” at the terminal (you must be in the same directory as your
code and the provided Makefile). Make will print the results back to the terminal and if successful
will create all the object files necessary for that MP. Any time you change your code, you should
run “make MP3.1” or “make MP3.2” again to ensure that your object file is up to date.

If you prefer not to use make or if you need to do some manual testing/debugging, you may use the
“lc3as <file.asm>” command to manually convert your assembly code to object files. You will need
to compile mp3.asm, print.asm, setup.asm, clear.asm, input.asm, and addr.asm for MP3.1. To
compile MP3.2 code you will need iter.asm and life.asm in addition to the previously mentioned
files.

Once successfully compiled, you may manually test your code in the LC-3 simulator. To load a “Life”
board you can load one of the board files by typing “file boards/<board file >” in the simulator
environment or by manually setting memory addresses by executing the command “memory
<addr> <value>”. Remember that the board starts at x5000!

Because we have several files to load into the simulator, it will be necessary to load from the
simulator environment with boards/<board file>, print.obj, setup.obj, clear.obj, input.obj, addr.obj,
life.obj (if testing MP3.2), iter.obj (if testing MP3.2), and mp3.obj. You must use that order to
successfully load the program into the simulator.

6
Automated Testing
To run automated tests on your code, you may run one of the following commands:

Command Vector File Used

make test-input tests/test-input-vectors.txt
make test-addr tests/test-addr-vectors.txt
make test-life tests/test-life-vectors.txt
make test-setup NONE (manual testing only)
make test-print board=<board> NONE (manual testing only)
make test-iter board=<board> NONE (manual testing only)
make test-mp3.1 board =<board> NONE (manual testing only)
make test-mp3.2 board=<board> NONE (manual testing only)

Automated tested is only available for GET_INPUT, CALC_ADDR, and LIFE.

PRINT_BOARD, ITER_BOARD, SETUP_BOARD, and MAIN will need to be tested manually using the
lc3sim environment (see Tools for details). The Makefile provided automatically sets up the lc3sim
environment for testing those subroutines but you will have to test them yourself. If the subroutine
you are testing calls another subroutine (aka: one routine has a dependency on the other), you will
need to ensure that helping subroutine works too. For instance, you will need to have MAIN and
PRINT_BOARD working before you can test SETUP_BOARD or ITER_BOARD.

Test vector files listed in the table above contain a limited number of basic test cases and it is up to
you to create additional test cases. We recommend you create at least six additional test cases for
each subroutine, with at least a few “corner cases” (aka “edge” or “boundary” cases that can
sometimes bring out interesting bugs in your code). To add test cases, simply edit the necessary
test vector file in a text editor and follow the format specified in each vector file.

Note that for these test cases you must give the input as well as the expected output – the test
program matches the actual output of your program against this expected output, so accuracy in
creating test cases is imperative; inaccurate test cases will cause inaccurate test results. If your
code is passing the two test cases we have provided but failing any of yours, make sure you verify
the accuracy of those test cases before trying to track down any bugs.

When testing the full operation of LIFE keep in mind that some of the boards are “static” (they do
not change over iterations), some are “periodic” (meaning that after some number of iterations the
patterns repeat), and others are “decaying” (meaning that eventually they disappear entirely).

“make test-print”, “make test-iter”, “make test-mp3.1”, and “make test-mp3.2” have an additional
option to specify a board file that will be used during the test. The list of boards that are available
for your use is provided on the next page. For example, if you wish to test PRINT_BOARD and load
galaxy.asm into the simulator you may simply type “make test-print board=galaxy”.

7
Provided Boards and Making Additional Boards
Sixteen game boards have been provided for you in the “boards” directory for your use when
testing MP3.1 and MP3.2. Some of these boards (like “galaxy.c”) may not necessarily look like the
component you might think it would resemble (at least not until a few iterations of “Life” have been
performed).

The boards will be created the first time you execute a “make” command that requires the use of a
board file. If you want to re-compile all the boards simply call “make all-boards”. Each provided
board can be seen at one of the following URLs:
http://en.wikipedia.org/wiki/Oscillator_%28cellular_automaton%29
http://en.wikipedia.org/wiki/Conway%27s_Game_of_Life

Should you wish to make boards in addition to the ones provided, you are free to do so by following
these instructions:
1. Navigate to your MP3 directory.
2. “cd boards”
3. “cp empty.c <my_new_board_name>.c”
4. Open <my_new_board_name>.c using your preferred text editor
a. At the top there is a 16 x 16 pattern of 0’s and 1’s that you can edit.
b. Do NOT edit any other portion of the file.
c. When finished, save and exit.
5. “cd ..”

Once you create your board and wish to test PRINT_BOARD, for example, using the new board you
may do so by executing “make test-print board=<my_new_board_name>”. The Makefile will
generate the assembly file that represents the board you created in the C file and use it!

Each board is either “static”, “periodic”, or “decaying”. When testing MP3.2 you can use this
information to aid you in testing the MP. If the board is periodic the period is how many cycles it
takes for the board to being to repeat its original pattern again. If the board is decaying the period
lists how many cycles it will take to disappear completely.

Boards Type Period

beehive, block, empty, ship, print-1, print-3, print-4 Static 0
beacon, blinker Periodic 2
cross Periodic 3
clock Periodic 4
octagon Periodic 5
galaxy Periodic 8
glider Periodic 64
print-2 Decaying 1
line Decaying 29