DPST1092 Computer Systems Fundamentals - Assignment 1: Breakout in MIPS
Assignment 1: Breakout in MIPS
version: 1.0 last updated: 2024-09-20 12:00:00
Aims
- to give you experience writing MIPS assembly code
- to give you experience translating C to MIPS
- to give you experience with data and control structures in MIPS
Getting Started
Create a new directory for this assignment called breakout, change to this directory, and fetch the provided code by running these commands:
mkdir -m 700 breakout cd breakout 1092 fetch breakout
If you're not working at CSE, you can download the provided files as a zip file or a tar file.
This will add the following files into the directory:
breakout.s: a stub MIPS assembly file to complete.breakout.c: a reference implementation of Breakout in C.breakout.simple.c: a copy of the reference implementation of Breakout, for you to simplify.input.txt: example input file.breakout.mk: a make fragment for compilingbreakout.c.
Breakout: The Game
1092 mipsy breakout.s Welcome to 1092 breakout! In this game you control a paddle (---) with the a and d (or A and D for fast movement) keys, and your goal is to bounce the ball (*) off of the bricks (digits). Every ten bricks destroyed spawns an extra ball. The . key will advance time one step. Enter the width of the playing field: 12 SCORE: 0 ============== | | | | |000111222333| |000111222333| |000111222333| |000111222333| |000111222333| |000111222333| | | | | | * | | ------ | >> ; SCORE: 5 ============== | | | | |000111222333| |000111222333| |000111222333| |000111222333| |000111222333| |000 222333| | * | | | | | | ------ | >> q
breakout.c is an implementation of a version of Breakout, a popular and influential video game.
An example game of Breakout can be seen to the right.
A game of Breakout takes place on a 2D grid, where the player must move a paddle to bounce a ball (*) into a group of bricks (digits).
You can move the paddle left (a and A) and right (d and D).
Hitting bricks with the ball will destory the bricks, and reward the player with score points. Every 10 bricks destroyed will spawn a new ball, with up to 3 balls on the screen at any given time.
If a ball leaves the bottom of the screen then it is destroyed, and if there are no more balls left the game ends.
To get a feel for this game, try it out in a terminal:
dcc breakout.c -o breakout ./breakout
You should read through breakout.c. There are comments throughout it that should help you understand what the program is doing [citation needed] — which you'll need for the next part of the assignment.
breakout.s: The Assignment
Your task in this assignment is to implement breakout.s in MIPS assembly.
You have been provided with some assembly and some helpful information in breakout.s. Read through the provided code carefully, then add MIPS assembly so it executes exactly the same as breakout.c.
The functions run_command, print_deubg_info and print_screen_updates have already been translated to MIPS assembly for you.
You have to implement the following functions in MIPS assembly:
print_welcomemainread_grid_widthgame_loopinitialise_gamemove_paddlecount_total_active_ballsprint_cellregister_screen_updatecount_balls_at_coordinateprint_gamespawn_new_ballmove_ballsmove_ball_in_axishit_brickcheck_ball_paddle_collisionmove_ball_one_cell
You must translate each function separately to MIPS assembler, following the standard calling conventions used in lectures. When translating a function, you must not make any assumptions about the behaviour or side effects of any other function which is called.
Subsets
This assignment is split into four subsets. Later subsets will involve more complex translation.
| Subset | Functions | Performance Weight |
|---|---|---|
| Subset 0 |
| 10% |
| Subset 1 |
| 45% |
| Subset 2 |
| 25% |
| Subset 3 |
| 20% |
Commands
The run_command function calls various other functions. When translating you should follow the exact behaviour of the C code, however when testing you may find it useful to consult the following table of commands.
| Command | Description | Function called |
|---|---|---|
| a | Move the paddle one cell left | move_paddle |
| d | Move the paddle one cell right | move_paddle |
| A | Move the paddle three cells left | move_paddle |
| D | Move the paddle three cells right | move_paddle |
| . | Simulate the movement of the ball(s) | move_balls |
| ; | Simulate the movement of the ball(s) for 3 steps | move_balls |
| , | Simulate the movement of the ball(s) for ⅓ of a step | move_balls |
| ? | Output the internal state of the game | print_debug_info |
| h | Output the welcome message | print_welcome |
| s | Output changes to the screen (used by play-breakout) | print_screen_updates |
| p | Print the game, and turn off auto-printing | print_game |
| q | Quit the game | — |
Running & Testing
To run your MIPS code, simply enter the following in your terminal:
1092 mipsy breakout.s
Once you have finished your translation, to test your implementation, you can compile the provided C implementation, run it to collect the expected output, run your assembly implementation to collect observed output, and then compare them.
The game takes a lot of input, so it's a good idea to write a file with the input you want to test, and then pipe that into your program.
You have been given a file called input.txt as an example.
dcc breakout.c -o breakout cat input.txt | ./breakout | tee c.out cat input.txt | 1092 mipsy breakout.s | tee mips.out diff -s c.out mips.out Files c.out and mips.out are identical
Try this for different sequences of inputs. When testing some functions you may find using the ? command (which calls print_debug_info) to be useful.
Hints
You should implement all the functions from one subset before moving on to the next.
You may find the provided
run_command,print_debug_infoandprint_screen_updatesfunction implementations to be useful guidance for your implementation including comments, label names, indentation and register usage.
Simplified C code
You are encouraged to simplify your C code to remove any loop constructs and if-else statements, and test that your simplified code works correctly before translating it to MIPS, in a separate file breakout.simple.c.
This file will not be marked - you do not need to submit it.
In order to allow you to check that your simplified code works correctly, we have provided a simple set of automated tests.
You can run these tests by running the following command:
1092 autotest breakout.simple
An example game of Breakout
Assumptions, Clarifications, and Restrictions
Like all good programmers, you should make as few assumptions as possible.
Your submitted code must be hand-written MIPS assembly, which you yourself have written.
You may not submit code in other languages.
You may not submit compiled output.You may not copy a solution from an online source. e.g. Github.
Your functions will be tested individually. They must exactly match the behaviour of the corresponding C function and they must follow MIPS calling conventions.
The C code defines constants using
#define. Your MIPS translation should use the corresponding provided named constants, in the places where a#defineis used in the C code. You should not use a#defineconstant in your MIPS translation if it is not used in the corresponding part of the C code.There will be a correctness penalty for assignments that do not follow standard MIPS calling conventions including:
Function arguments are passed in registers
$a0..$a3.Function return values are passed in register
$v0Values in registers
$s0..$s7are preserved across function calls.
If a function changes these registers, it must restore the original value before returning.The only registers' values that can be relied upon across a function call are
$s0..$s7,$gp,$sp, and$fp.
All other registers must be assumed to be have, an undefined value after a function call, except$v0which has the function return value.
If you need clarification on what you can and cannot use or do for this assignment, ask in the class forum.
You are required to submit intermediate versions of your assignment. See below for details.
Breakout wrapper
If you complete this assignment, you may notice that the finished game is not particularly fun to play. To make the game more interesting to play, you can run a wrapper script that adds extra functionality to your MIPS translation. In a directory which contains your completed breakout.s, run:
1092 play-breakout 60
You can change the parameter 60 to other numbers for different grid widths. You can also optionally supply another parameter slow, medium (which is the default), fast or increasing to alter the game speed. For example, this will start a game with fast speed and a grid width of 42:
1092 play-breakout 42 fast
This adds colour and automatic time progression amongst other things. Inputs from the set aAdD are recognised. You may need to experiment with which terminal you use as well as terminal size to get the best playing experience. Note that this wrapper is just for fun, there are no marks associated with whether or not your translation works with the wrapper script.
