COMP1521 – 22T3 Outline Timetable Forum Assignment 1 Assignment 2
Understanding encoding of MIPS instructions
Understanding semantics of MIPS instructions
Generally building a concrete understanding of an example CPU Practicing C, including bit operations
The Assignment
mipsy is a MIPS emulator written in Rust.
You have extensively used mipsy in COMP1521 to run MIPS programs.
version: 1.3 last updated: 2022-11-02 03:30:00 Aims
The Assignment
Reference implementation
MIPS Instruction Subset
System Calls Registers Halting
Converting MIPS Assembler Instruction codes
Assignment 2: MIPS-C
The input to mipsy is usually a file containing MIPS assembly instructions. Examples
For example:
$ cat examples/42.s main:
li $a0, 42
li $v0, 1
li $a0, ‘\n’
li $v0, 11
# printf(“%d”, 42);
# printf(“%c”, ‘\n’);
Getting Started
Assumptions and Clarifications
Change Log Assessment
$ 1521 mipsy examples/42.s 42
Your task in this assignment is to write mipsc a MIPS emulator written in C.
DON’T PANIC, mipsc is much simpler than mipsy.
mipsc only needs to emulate the small subset of MIPS instructions listed below.
These instructions has been chosen to be simpler to emulate, but still allow interesting programs to be run.
The input to mipsc is a file containing hexadecimal numbers representing the 32-bit instruction codes of MIPS instructions. mipsc should read these instruction codes (code provided) and then emulate the instructions like this:
$ cat examples/42.hex 2004002a
$ dcc mipsc.c -o mipsc
$ ./mipsc examples/42.hex
0: 0x2004002A addi $4, $0, 42 >>> $4 = 42
1: 0x20020001 addi $2, $0, 1
>>> $2 = 1
2: 0x0000000C syscall
>>> syscall 1
3: 0x2004000A addi $4, $0, 10
>>> $4 = 10
4: 0x2002000B addi $2, $0, 11
>>> $2 = 11
5: 0x0000000C syscall
>>> syscall 11
If the command-line argument -r is given (code provided) then only the output from syscalls should be shown, like this: $ ./mipsc -r examples/42.hex
Reference implementation
A reference implementation is available as 1521 mipsc. Use it to find the correct output for any input like this:
Provision of a reference implementation is a common, efficient and effective method to provide or define an operational specification, and it’s something you will likely need to work with after you leave UNSW.
Where any aspect of this assignment is undefined in this specification you should match the reference implementation’s behaviour.
Discovering and matching the reference implementation’s behaviour is deliberately part of the assignment.
If you discover what you believe to be a bug in the reference implementation, report it in the class forum. If it is a bug, we may fix the bug, or indicate that you do not need to match the reference implementation’s behaviour in this case.
$ cat examples/square.hex 20100004
$ 1521 mipsc examples/square.hex 0: 0x20100004 addi $16, $0, 4 >>> $16 = 4
1: 0x20110003 addi $17, $0, 3
>>> $17 = 3
2: 0x72108002 mul $16, $16, $16
>>> $16 = 16
3: 0x72318802 mul $17, $17, $17
>>> $17 = 9
4: 0x02302020 add $4, $17, $16
>>> $4 = 25
5: 0x20020001 addi $2, $0, 1
>>> $2 = 1
6: 0x0000000C syscall
>>> syscall 1
7: 0x2004000A addi $4, $0, 10
>>> $4 = 10
8: 0x2002000B addi $2, $0, 11
>>> $2 = 11
9: 0x0000000C syscall
>>> syscall 11
$ 1521 mipsc -r examples/square.hex 25
MIPS Instruction Subset
You need to implement only these 14 MIPS instructions:
add $d, $s, $t
sub $d, $s, $t
slt $d, $s, $t
mult $s, $t
div $s, $t
mul $d, $s, $t
beq $s, $t, I
bne $s, $t, I
addi $t, $s, I
ori $t, $s, I
HI,LO = s * t
HI = s % t; LO = s / t
if (s == t) PC += I
if (s != t) PC += I
t = I << 16
Bit Pattern
000000ssssstttttddddd00000100000
000000ssssstttttddddd00000100010
000000ssssstttttddddd00000101010
0000000000000000ddddd00000010000
0000000000000000ddddd00000010010
000000sssssttttt0000000000011000
000000sssssttttt0000000000011010
011100ssssstttttddddd00000000010
000100ssssstttttIIIIIIIIIIIIIIII
000101ssssstttttIIIIIIIIIIIIIIII
001000ssssstttttIIIIIIIIIIIIIIII
001101ssssstttttIIIIIIIIIIIIIIII
00111100000tttttIIIIIIIIIIIIIIII
00000000000000000000000000001100
The instruction bit pattern uniquely identifies each instruction:
0: Literal bit zero
1: Literal bit one
I: Immediate (16-bit signed number) d, s, t: five-bit register number
System Calls
You only need to implement these 3 system calls.
Description
print integer
print character
$v0 Pseudo-C
1 printf("%d", $a0) 10 exit(0)
11 printf("%c", $a0)
Syscall 1 should print $a0 as a signed 32-bit integer. Syscall 11 should print the low byte (lowest 8 bits) of $a0 .
Syscall 10 should exit the program.
See the section on halting for more details.
If an invalid syscall number is supplied an error message should be printed: Match the reference implementation's message:
$ 1521 mipsc examples/bad_syscall.hex 0: 0x20021092 addi $2, $0, 4242
>>> $2 = 4242
1: 0x0000000C syscall
>>> syscall 4242
Unknown system call: 4242
After printing the error message, the program should exit. See the section on halting for more details.
All 32 registers, Plus Hi and Lo are set to be zero when execution begins.
The other 31 registers have no special meaning and can be used for any purpose.
The value of register $0 ($zero) is always 0. Instructions that attempt to change it have no effect.
The values of registers $2 ($v0) and $4 ($a0) are used by the syscall instruction. Hi and Lo are used by the MULT and DIV instructions.
And can only be read from by the MFHI and MFLO instructions.
Execution halts if an exit syscall (syscall 10) is executed.
Execution halts if it reaches the location after the last instruction.
Execution halts if there is a branch to the location immediately after the last instruction.
Execution halts with an error message if there is a branch to any other location beyond the range of specified instructions: Illegal branch to non-instruction: PC = ??
Execution halts after printing an error message,
eg: for an invalid syscall number or invalid instruction.
Converting MIPS Assembler Instruction codes
The command 1521 mips2hex will give you the hex codes for MIPS instructions.
$ cat examples/42.s main:
li $a0, 42
li $v0, 1
li $a0, ‘\n’
li $v0, 11
# printf(“%d”, 42);
# printf(“%c”, ‘\n’);
$ 1521 mips2hex examples/42.s 2004002a
1521 mips2hex has a couple of features that it make it easier for you to use MIPS programs as test inputs for mipsc . For convenience, 1521 mips2hex translates some common pseudo-instructions, e.g. LI into the instruction codes for real
instructions in the subset mipsc handles.
1521 mips2hex translates a few instructions outside the subset mipsc handles to the instruction codes for equivalent real
instructions in the subset mipsc handles.
1521 mips2hex handles branch labels for you. It calculates the branch offset and outputs the instruction codes for the
appropriate branch instructions.
Also for convenience 1521 mips2hex deletes the last instruction if it is JR because JR is not in the subset for this
assignment and a last JR is often just main returning.
Note, mipsc does not need to implement pseudo-instructions or instructions outside the specified subset.
Some example MIPS programs are available in a zip file You will also need to do your own testing and construct your own examples using 1521 mips2hex .
Note the assembler for the example programs contains pseudo-instructions such as LI.
1521 mips2hex translates these pseudo-instructions to real instruction codes in the subset for this assignment.
Getting Started
Create a new directory for this assignment called mipsc , change to this directory, and fetch the provided examples: by running these commands:
$ mkdir -m 700 mipsc $ cd mipsc
$ 1521 fetch mipsc
$ unzip examples.zip ….
Or, if you’re not working on CSE, you can download the examples.zip and starting code
You have been given starting code for this assignment in mipsc.c which already implements handling command line
arguments and reading the hexadecimal instruction code into an array.
$ dcc mipsc.c -o mipsc
$ ./mipsc examples/42.hex 0: 0x2004002A
1: 0x20020001
2: 0x0000000C
3: 0x2004000A
4: 0x2002000B
5: 0x0000000C
The code calls the function execute_instructions to simulate execution but the supplied code in execute_instructions only prints the instruction codes.
You need to change the code in execute_instructions to simulate the execution of the instructions. You should add extra functions and #defines.
You may (but are not required to) create extra .c or .h files.
Assumptions and Clarifications
Like all good programmers, you should make as few assumptions as possible.
If in doubt, match the output of the reference implementation.
You can assume mipsc.c is given a single file as a command line argument
You do not have to implement MIPS instructions, system calls, or features that are not explicitly mentioned in the tables above.
Your program should print an error message if given a hexadecimal number that does not correspond to an instruction in the above MIPS subset.
You can print this error message before executing the program or when execution reaches the invalid instruction code. Match the reference implementation’s message:
$ echo 12858AA > invalid.hex
$ cat invalid.hex
$ 1521 mipsc invalid.hex
Invalid instruction 0x012858AA at PC = 0
In the case of an invalid instruction, any output to stdout will be ignored.
As long as the given error message is printed to stderr, you program is correct.
The reference implementation uses %08X to print invalid instruction codes.
You will not be penalized if you implement extra MIPS instructions beyond the subset above and do not print an error
message for them.
Execution halts with an error message if there is a system call which is not in this subset. You can assume overflow does not occur during arithmetic or other operations.
You can assume that division by zero should result in a quotient and a remainder of 0. You do not need to handle instructions that access memory such as LW or SW.
You do not need to handle branch labels. 1521 mips2hex translates these into the relative offset which is part of the branch instruction code.
You do not need to handle pseudo-instructions. 1521 mips2hex translates these into the appropriate real instructions. Eg. LI is translated into ADDI.
You do not need to handle the JR instruction. 1521 mips2hex deletes the last instruction if it is JR.
Any other occurences of JR would be invalid.
The corresponding .hex files contains only real instructions in the assignment subset.
For convenience mips2hex translates some pseudo-instructions and a few instructions outside the subset into instruction
codes in the assignment subset.
This is mainly done to translate different types of branches into SLT plus BEQ or BNE.
The reference implementation will print error messages stderr. The provided code also uses stderr when appropriate.
Any additional error messages you add should also print to stderr.
Any messages that do not indicate an error should be printed to stdout.
Your submitted code must be C only. You may call functions from the standard C library (e.g., functions from stdio.h ,
stdlib.h , string.h , etc.) and the mathematics library ( math.h ). You may use assert.h .
You may not submit code in other languages. You may not use system function, or other C functions to run external
programs. You may not use functions from other libraries; in other words, you cannot use dcc’s -l flag.
Your program must not require extra compile options. It must compile with dcc *.c -o mipsc , and it will be run with dcc
when marking. Run-time errors from illegal C will cause your code to fail automarking.
If you need clarification on what you can and cannot use or do for this assignment, ask in the class forum.
If your program writes out debugging output, it will fail automarking tests: make sure you disable debugging output before submission.
You are required to submit intermediate versions of your assignment. See below for details.
Change Log
Version 1.0
(2022-10-31 12:00:00)
Version1.1
(2022-10-31 20:00:00)
Version 1.2
(2022-11-01 12:30:00)
Version 1.3
(2022-11-02 03:30:00)
Assessment
Initial release
(SPEC)FixbitpatternforMFHIandMFLO,whichhadanextra 0andweremissinga d
(SPEC) Fix the semantics of DIV, HI is remainder and LO is quotient, this was accidentally reversed
(REFERENCE) Fix the implementation of DIV, HI is remainder and LO is quotient, this was accidentally reversed
(SPEC) Add clarification that the program should halt when it tries to execute an invalid syscall
(REFERENCE) Fix MULT incorrectly handling negative numbers
When you think your program is working, you can use autotest to run some simple automated tests: $ 1521 autotest mipsc mipsc.c [optionally: any extra .c or .h files]
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 when errors have occurred, it is often substantially harder to automatically explain what that error was. The errors from 1521 autotest may be less clear than in labs. You will need to do your own debugging and analysis.
Remember that you can always compaire your code to the reference implement.
Submission
When you are finished working on the assignment, you must submit your work by running give : $ give cs1521 ass2_mipsc mipsc.c [optionally: any extra .c or .h files]
You must run give before Week 11 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 ass2_mipsc
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 11 Monday 11:59:59 (midday) (2022-11-21 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 15 marks to your final COMP1521 mark.
80% of the marks for assignment 2 will come from the performance of your code on a large series of tests.
20% of the marks for assignment 2 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:
$ dcc mipsc.c -o mipsc
$ ./mipsc examples/42.hex | tee mipsc.out 0: 0x2004002A addi $4, $0, 42
>>> $4 = 42
1: 0x20020001 addi $2, $0, 1
>>> $2 = 1
2: 0x0000000C syscall
>>> syscall 1
3: 0x2004000A addi $4, $0, 10
>>> $4 = 10
4: 0x2002000B addi $2, $0, 11
>>> $2 = 11
5: 0x0000000C syscall
>>> syscall 11
$ 1521 mipsc examples/42.hex | tee reference.out 0: 0x2004002A addi $4, $0, 42
>>> $4 = 42
1: 0x20020001 addi $2, $0, 1
>>> $2 = 1
2: 0x0000000C syscall
>>> syscall 1
3: 0x2004000A addi $4, $0, 10
>>> $4 = 10
4: 0x2002000B addi $2, $0, 11
>>> $2 = 11
5: 0x0000000C syscall
>>> syscall 11
$ diff -s mipsc.out reference.out
Files mipsc.out and reference.out are identical
100% for performance
90% for performance
80% for performance
65% for performance
¡Ü 40% for performance
Implements all behaviour perfectly, following the spec and reference implementation exactly.
All instructions and syscalls mostly works with one or two minor bugs. Most instructions mostly works with a few minor bugs.
Some instructions somewhat working
good progress, but not passing many/any autotests.
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 90% for style 80% for style 70% for style 60% for style ¡Ü 50% for style
An indicative style rubric follows:
perfect style
great style, almost all style characteristics perfect.
good style, one or two style characteristics not well done. good style, a few style characteristics not well done.
ok style, an attempt at most style characteristics.
an attempt at style.
Formatting (6/20):
Whitespace (e.g. 1 + 2 instead of 1+2 )
Indentation (consistent, tabs or spaces are okay)
Line length (below 100 characters unless very exceptional) Line breaks (using vertical whitespace to improve readability)
Documentation (8/20):
Header comment (with name, zID, description of program)
Function comments (above each function with a description)
Descriptive variable names (e.g. char *home_directory instead of char *h )
Descriptive function names (e.g. get_home_directory instead of get_hd )
Sensible commenting throughout the code (don’t comment every single line; leave comments when necessary)
Elegance (5/20):
Does this code avoid redundancy? (e.g. Don’t repeat yourself!)
Are helper functions used to reduce complexity? (functions should be small and simple where possible) Are constants appropriately created and used? (magic numbers should be avoided)
Portability (1/20):
Would this code be able to compile and behave as expected on other POSIX-compliant machines? (using standard libraries without platform-specific code)
Note that the following penalties apply to your total mark for plagiarism:
0 for asst2
0 FL for COMP1521
academic misconduct
knowingly providing your work to anyone
and it is subsequently submitted (by anyone).
submitting any other person’s work; this includes joint work.
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 is brought to you by the School of Computer Science and Engineering
at the University of New South Wales, Sydney.
For all enquiries, please email the class account at CRICOS Provider 00098G