COMP1521 Assignment 1: Battleship in MIPS
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 battlesmips,
change to this directory,
and fetch the provided code
by running these commands:
mkdir battlesmips
cd battlesmips
1521 fetch battlesmips
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:
battlesmips.s: a stub MIPS assembly file to complete.
battlesmips.c: a reference implementation of battleship in C.
battlesmips_EOF.c: additional C file for testing.
input.txt: example input file.
battleship: The Game
1521 mipsy battlesmips.s
It is blue’s turn
0 1 2 3 4 5 6
0 – – – – – – –
1 – – – – – – –
2 – – – – – – –
3 – – – – – – –
4 – – – – – – –
5 – – – – – – –
6 – – – – – – –
Please enter the row for your target
Please enter the column for your target
Hit successful!
It is blue’s turn
0 1 2 3 4 5 6
0 X – – – – – –
1 – – – – – – –
2 – – – – – – –
3 – – – – – – –
4 – – – – – – –
5 – – – – – – –
6 – – – – – – –
Please enter the row for your target
Please enter the column for your target
Hit successful!
It is blue’s turn
0 1 2 3 4 5 6
0 X – – – – – X
1 – – – – – – –
2 – – – – – – –
3 – – – – – – –
4 – – – – – – –
5 – – – – – – –
6 – – – – – – –
Please enter the row for your target
Please enter the column for your target
You missed!
It is red’s turn
battlesmips.c is a (simplified) implementation of
the classic board game battleship!
An example game of battleship can be seen to the right.
A game of battleship takes place over a number of turns,
as two players battle it out to sink each other’s ships!
First, the players must place their ships (not shown on the right).
Then players alternate in turns guessing where the ships are on the board.
If a player “hits” a ship, they get to take another turn.
The game is played on a 7 x 7 board.
To get a feel for this game, try it out in a terminal:
dcc battlesmips_EOF.c -o battlesmips
./battlesmips
You have been provided with two files: battlesmips.c and battlesmips_EOF.c
battlesmips.c is the file you should be translating into MIPS.
This implementation doesn’t handle EOF correctly.
When ^D is pressed, the program will enter an infinite loop.
battlesmips_EOF.c correctly handles EOF.
This has been provided to make exploring the reference implementation easier.
You do not need to translate this file (there are only small differences between it and battlesmips.c).
You should read through battlesmips.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.
battlesmips.s: The Assignment
Your task in this assignment is
to implement battlesmips.s in MIPS assembly.
You have been provided with some assembly
and some helpful information in battlesmips.s.
Read through the provided code carefully,
then add MIPS assembly
so it executes exactly the same as battlesmips.c.
The functions
print_board,
swap_turn,
get_end_row, and
get_end_col
have already been translated to MIPS assembly for you.
You have to implement the following functions in MIPS assembly:
initialise_boards,
initialise_board,
setup_boards,
setup_board,
place_ship,
is_coord_out_of_bounds,
is_overlapping,
place_ship_on_board,
play_game,
play_turn,
perform_hit,
check_player_win,
check_winner,
You must translate each function separately to MIPS assembler,
following the standard calling conventions used in lectures.
To run your MIPS code, simply enter the following in your terminal:
1521 mipsy battlesmips.s
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 — for example:
The game takes a lot of input,
so it’s a good idea to write a file with the input you want to test,
then pipe that into your program.
You have been given a file called input.txt
as an example.
dcc battlesmips.c -o battlesmips
cat input.txt | ./battlesmips | tee c.out
cat input.txt | 1521 mipsy battlesmips.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.
Each function is worth some amount of marks:
Function Mark
initialise_boards 2
initialise_board 5
setup_boards 2
setup_board 3
place_ship 10
is_coord_out_of_bounds 3
is_overlapping 7
place_ship_on_board 7
play_game 3
play_turn 5
perform_hit 3
check_winner 2
check_player_win 5
These marks represent relative difficulty.
E.g. main may not be worth exactly 1 mark,
but will be worth half the marks of initialise_boards.
Functions are not in order of difficulty.
You may find it easier to implement
the smaller functions before moving
on to the larger ones.
mipsy supports defining constants
somewhat like #define in C:
#define CARRIER_SYMBOL ‘C’
#define BATTLESHIP_SYMBOL ‘B’
#define DESTROYER_SYMBOL ‘D’
#define SUBMARINE_SYMBOL ‘S’
#define PATROL_BOAT_SYMBOL ‘P’
But the MIPS syntax is a bit different:
CARRIER_SYMBOL = ‘C’
BATTLESHIP_SYMBOL = ‘B’
DESTROYER_SYMBOL = ‘D’
SUBMARINE_SYMBOL = ‘S’
PATROL_BOAT_SYMBOL = ‘P’
You may find the discussion of the assignment
during this lecture helpful.
You may find the provided implementations of
functions to be useful guidance for your
your implementations 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 testing that your simplified
code works correctly before translating it
to MIPS, in a separate file
battlesmips.simple.c.
This file will not be marked. You will not need
to submit it.
In order to allow you to ensure that your
simplified code works correctly, we have provided
a series of automated tests.
You can run these tests by running the following
1521 autotest battlesmips.simple
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 match the behaviour of the corresponding
C function and they must follow MIPS calling
conventions.
There will be a correctness penalty
for assignments that do not follow
standard MIPS calling conventions including:
That function arguments shall be passed in
registers $a0..$a3.
That function return values shall be passed through
register $v0.
That values in registers $s0..$s7
shall be preserved across function calls:
if a function changes these registers,
it must restore the original value before returning.
That 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 clobbered,
with a completely undefined 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.
Change Log
Version 1.0
(2022-10-04 09:00:00)
Initial release
Version 1.1
(2022-10-22 01:00:00)
Swap the mark values for check_player_win and check_winner
Assessment
When you think your program is working,
you can use autotest
to run some simple automated tests:
1521 autotest battlesmips battlesmips.s
1521 autotest will not test everything.
Always do your own testing.
Automarking will be run by the lecturer after the submission deadline,
using a superset of tests to those autotest runs for you.
Whilst we can detect that errors have occurred,
it is often substantially harder to explain what that error was.
The errors from 1521 autotest
will be less clear and useful than in labs.
You will need to do your own debugging and analysis.
Autotest can only test your program as a whole.
You will need to complete all the functions before you can test your program with autotest.
You are strongly encouraged to test individual functions yourself.
Submission
When you are finished working on the assignment,
you must submit your work by running give:
give cs1521 ass1_battlesmips battlesmips.s
You must run give before Week 7 Monday 11:59:59 (midday)
to obtain the marks for this assignment.
Note that this is an individual exercise,
the work you submit with give must be entirely your own.
You can run give multiple times.
Only your last submission will be marked.
If you are working at home, you may find it more convenient
to upload your work via
give’s web interface.
You cannot obtain marks by emailing your code to tutors or lecturers.
You can check your latest submission on CSE servers with:
1521 classrun check ass1_battlesmips
You can check the files you have submitted here.
Manual marking will be done by your tutor,
who will mark for style and readability,
as described in the Assessment section below.
After your tutor has assessed your work,
you can view your results here;
The resulting mark will also be available
via give’s web interface.
This assignment is due Week 7 Monday 11:59:59 (midday) (2022-10-24 11:59:00).
The UNSW standard late penalty for assessment is 5% per day for 5 days – this is implemented hourly for this assignment.
Your assignment mark will be reduced by 0.2% for each hour (or part thereof) late past the submission deadline.
For example,
if an assignment worth 60% was submitted half an hour late,
it would be awarded 59.8%, whereas if it was submitted past 10 hours late,
it would be awarded 57.8%.
Beware – submissions 5 or more days late will receive zero marks.
This again is the UNSW standard assessment policy.
Assessment Scheme
This assignment will contribute
to your final COMP1521 mark.
80% of the marks for assignment 1
will come from the performance of your code
on a large series of tests.
20% of the marks for assignment 1
will come from hand marking.
These marks will be awarded on the basis of
clarity, commenting, elegance and style.
In other words, you will be assessed on
how easy it is for a human to read and understand your program.
An indicative assessment scheme for performance follows.
The lecturer may vary the assessment scheme
after inspecting the assignment submissions,
but it is likely to be broadly similar to the following:
100% for performance
implements all behaviours perfectly,
following the spec exactly.
90% for performance
implements all behaviours perfectly,
but doesn’t conform to the MIPS ABI
75% for performance
implements all simple and
all moderate difficulty functions correctly.
65% for performance
implements all simple and
some moderate difficulty functions correctly.
≤ 50% for performance
good progress,
simple functions work correctly.
An indicative assessment scheme for style follows.
The lecturer may vary the assessment scheme
after inspecting the assignment submissions,
but it is likely to be broadly similar to the following:
100% for style perfect style
90% for style great style, almost all style characteristics perfect.
80% for style good style, one or two style characteristics not well done.
70% for style good style, a few style characteristics not well done.
60% for style ok style, an attempt at most style characteristics.
≤ 50% for style an attempt at style.
An indicative style rubric follows.
The lecturer may vary the assessment scheme
after inspecting the assignment submissions,
but it is likely to be broadly similar to the following:
Formatting (8/20):
Whitespace
Indentation (consistent, tabs or spaces are okay)
Line length (below 120 characters unless very exceptional)
Line breaks (using vertical whitespace to improve readability)
Documentation (12/20):
Header comment (with name, zID, description of program)
Function comments (above each function with a description)
Sensible commenting throughout the code
Note that the following penalties apply to your total mark for plagiarism:
assignment 1
knowingly providing your work to anyone
and it is subsequently submitted (by anyone).
submitting any other person’s work; this includes joint work.
misconduct
submitting another person’s work without their consent;
paying another person to do work for you.
Intermediate Versions of Work
You are required to submit intermediate versions of your assignment.
Every time you work on the assignment
and make some progress
you should copy your work to your CSE account
and submit it using the give command below.
It is fine if intermediate versions do not compile
or otherwise fail submission tests.
Only the final submitted version of your assignment will be marked.
Assignment Conditions
Joint work is not permitted on this assignment.
This is an individual assignment.
The work you submit must be entirely your own work:
submission of work even partly written by
any other person is not permitted.
Do not request help from anyone
other than the teaching staff of COMP1521 —
for example, in the course forum, or in help sessions.
Do not post your assignment code to the course forum.
The teaching staff can view code
you have recently submitted with give,
or recently autotested.
Assignment submissions are routinely examined
both automatically and manually
for work written by others.
Rationale:
this assignment is designed to
develop the individual skills needed
to produce an entire working program.
Using code written by, or taken from, other people
will stop you learning these skills.
Other CSE courses focus on skills needed for working in a team.
The use of code-synthesis tools,
such as GitHub Copilot,
is not permitted on this assignment.
Rationale:
this assignment is designed to develop your understanding of basic concepts.
Using synthesis tools will stop you learning these fundamental concepts,
which will significantly impact your ability to complete future courses.
Sharing, publishing, or distributing
your assignment work is not permitted.
Do not provide or show your assignment work to any other person,
other than the teaching staff of COMP1521.
For example, do not message your work to friends.
Do not publish your assignment code via the Internet.
For example, do not place your assignment in a public GitHub repository.
Rationale:
by publishing or sharing your work,
you are facilitating other students using your work.
If other students find your assignment work
and submit part or all of it as their own work,
you may become involved in an academic integrity investigation.
Sharing, publishing, or distributing
your assignment work
after the completion of COMP1521
is not permitted.
For example, do not place your assignment in a public GitHub repository
after this offering of COMP1521 is over.
Rationale:
COMP1521 may reuse assignment themes
covering similar concepts and content.
If students in future terms find your assignment work
and submit part or all of it as their own work,
you may become involved in an academic integrity investigation.
Violation of any of the above conditions
may result in an academic integrity investigation,
with possible penalties
up to and including a mark of 0 in COMP1521,
and exclusion from future studies at UNSW.
For more information,
read the UNSW Student Code,
or contact the course account.
COMP1521 22T3: Computer Systems Fundamentals