COMP1521 - 24T3
Assignment 2: a simple MIPS emulator
Aims
Understanding encoding and semantics of MIPS instructions
Practising file operations in C
Practising C, including bit operations
Understanding UNIX file system syscalls
Assignment Overview
In COMP1521 you have been using mipsy to run your MIPS programs. mipsy is a MIPS emulator MIPS emulator, written in C.
Don't panic! You only need to implement a small subset of MIPS instructions.
Getting Started
Create a new directory for this assignment, change to this directory, and fetch the provi
mkdir -m 700 imps
cd imps
1521 fetch imps
If you're not working at CSE, you can download the provided files as a zip file or a tar
This will give you the following files :
imps.c
is where you will put your code to implement IMPS.
imps.mk
contains a Makefile fragment for IMPS.
Makefile
contains a Makefile for compiling your code.
examples
is a directory containing example assembly programs you can use to test IMPS.
test_subset_1.c
contains code that is run during subset 1 autotests. You do not need to undertsand or mod
You can run
make to compilethe providedcode, and you shouldbeableto run the result.
make
dcc imps.c -o imps
./imps
Usage : imps [-t] <executable>
You may optionally create extra .c or .h files. You can modify the provided Makefile frag
Subsets
The assignment is split into four subsets. In subset 1 you will implement a function that implement various instructions and syscalls. In subset 4 you will add a tracing mode to I
Subset 1
IMPS programs are stored in IMPS executable files, which contain the instructions in the and other information.
In subset 1 your task is to implement the function read_imps_file in imps.c, which will r provided two arguments :
char *path is the path to an IMPS executable.
struct imps_file *executable is a pointer to the struct imps_file where you will put th
An IMPS executable file always has 7 sections of varying lengths in this format :
section name length in bytes type
magic number 4 8-bit
|
num_instructions
|
|
4 32-bit, little-endian
|
|
entry_point
|
|
4 32-bit, little-endian
|
|
instructions
|
4 * num_instructions
|
32-bit, little-endian
|
|
debug_ofsets
|
4 * num_instructions
|
32-bit, little-endian
|
memory_size 2 16-bit, little-endian
initial_data memory_size 8-bit
Your task task is to read bytes e.g. using fgetc from file path, and then store the appro executable points.
An struct imps_file has this definition :
struct imps_file {
uint32_t num_instructions ;
uint32_t entry_point ;
uint32_t *instructions ;
uint32_t *debug_offsets ;
uint16_t memory_size ;
uint8_t *initial_data ;
} ;
You should allocate space on the heap for instructions, debug_offsets and initial_data us
You will find starting code and some hints in imps.c.
Unless there is an error, read_imps_file doesn't print anything.
The subset 1 autotests call your read_imps_file function directly and use extra code to p
Use the following command to run all the autotests for subset 1 :
1521 autotest imps S1 [optionally : any extra .c or .h files]
There are a number of ways in which a file might not follow the specified format for IMPS
Although it would be good practice to check all of them (and you can), you are only requi
If the file at path cannot be opened you should use perror(path) to output an error messa
If the magic number is incorrect you should output the line Invalid IMPS file to stderr a
For example :
./imps file-that-does-not-exist
file-that-does-not-exist : No such file or directory
./imps Makefile
Invalid IMPS file
Subset 2
In subset 2 your task is to implement the function execute_imps in imps.c, which will exe contains only the following instructions :
Instruction
✓ ADDI Rt, Rs, Imm16
✓ SYSCALL
✓ ADD Rd, Rs, Rt
✓ ORI Rt, Rs, Imm16
✓ LUI Rt, Imm16
Execution of the program starts from the entry_point (which is an index into the array of
Every time you execute an instruction you should first fetch it from the instructions arr instruction it is, using bitwise operations.
If the instruction has operands (e.g. registers, an immediate) you should extract those o
You will need to keep track of the values of the 32 general-purpose registers. When the p The $0 ($zero) register always has the value 0, and instructions that attempt to change i For this subset you only need to implement these three syscalls :
syscall 1 : print the integer in $a0 to stdout. You should use the provided print_int32_ syscall 10 : exit the program, with status 0. You may use exit(0) for this.
syscall 11 : print the character in $a0 to stdout. You should use putchar (or equivalent
Error handling
In subset 2 your IMPS implementation should handle the following errors :
If a syscall is run with $v0 not equal to a valid syscall number, you should output the
If an invalid instruction is run you should output the error message IMPS error : bad in out using print_uint32_in_hexadecimal.
If execution reaches past the end of the instructions array (which will occur if there' execution past the end of instructions.
All error message should be printed to stderr, and after an error occurs execution should
Autotests
Use the following command to run all of the autotests for subset 2 :
1521 autotest imps S2 [optionally : any extra .c or .h files]
For tests that only involve the ADDI and SYSCALL instructions, run :
1521 autotest imps S2_1 [optionally : any extra .c or .h files]
Subset 3
In this subset you need to also implement the following instructions :
Instruction
✓ CLO Rd, Rs
✓ CLZ Rd, Rs
✓ ADDU Rd, Rs, Rt
✓ ADDIU Rt, Rs, Imm16
✓ MUL Rd, Rs, Rt
✓ BEQ Rs, Rt, Offset16
✓ BNE R R Offset
|
✓
|
BNE
|
Rs, Rt, Offset16
|
|
✓
|
SLT
|
Rd, Rs, Rt
|
|
✓
|
LB
|
Rt, Offset16 (Rb)
|
|
✓
|
LH
|
Rt, Offset16 (Rb)
|
|
✓
|
LW
|
Rt, Offset16 (Rb)
|
|
✓
|
SB
|
Rt, Offset16 (Rb)
|
|
✓
|
SH
|
Rt, Offset16 (Rb)
|
|
✓
|
SW
|
Rt, Offset16 (Rb)
|
The CLZ (count leading zeros) instruction counts the number of zero bits which are to the 0b00000001010001011101010101110011 there are 7 leading zeros, so Rd should be set to 7.
The CLO instruction counts the number of leading one bits, for example if Rs = 0b11111110
The ADDU and ADDIU instructions have similar semantics to the ADD and ADDI instructions, the error checking part of this subset). They are included in this assignment since some
The BEQ and BNE instructions perform. conditional branches. If the branch condition is sat
the index of the current instruction and Offset16 is the offset encoded in the lower 16 bi The SLT instruction sets Rd to 1 if Rs < Rt, otherwise Rd gets set to 0.
The memory access instructions only need to handle access to the data segment. The initia executable. Access to the data segment starts from address 0x10010000, so for example the
Memory accesses should be little-endian (the same as mipsy). For subset 3 you also need to implement two more syscalls :
syscall 4 : print the nul-terminated string at address $a0 to stdout.
syscall 12 : read a single character from stdin (e.g. via getchar) and place that charac
Error handling
In subset 3 your IMPS implementation should additionally handle the following errors :
If the result of an ADD or ADDI instruction would result in a signed overflow you shoul various ways to detect overflow, including using a wider type to compute the result and the sign bits of the inputs and the result.
If a memory access is not correctly aligned, or if it is outside the range of the initi the error IMPS error : bad address for <size> access : <address> where <size> is byte, ha print_uint32_in_hexadecimal.
As in subset 1, error messages should be printed to stderr and errors should result in IM
Autotests
Use the following command to run all of the autotests for subset 3 :
1521 autotest imps S3 [optionally : any extra .c or .h files] For tests involving the CLO and CLZ instructions, run :
1521 autotest imps S3_1 [optionally : any extra .c or .h files] For tests involving the branch and SLT instructions, run :
1521 autotest imps S3_3 [optionally : any extra .c or .h files] For tests involving memory accesses, run :
1521 autotest imps S3_4 [optionally : any extra .c or .h files] For tests involving error checking in this subset, run :
1521 autotest imps S3_5 [optionally : any extra .c or .h files]
Subset 4
This subset is split into two parts. In the first part you will add a tracing mode to IMP
Tracing mode
Usually IMPS is run as ./imps <executable.imps>, however in this subset you will add a tr executable :
./imps -t <executable.imps>
The following changes occur in tracing mode :
Before execution starts IMPS should open the assembly source file. You can assume that with the .imps extension replaced with .s.
Just prior to an instruction executing, you should use the debug offset from the IMPS e position in the assembly source using fseek. You should then print out the line startin the debug offset is past the end of the assembly file no line is printed.
Just after each instruction is executed, if that instruction modified a register, you s $<reg> : <old val> -> <new val>
where <reg> is the human-friendly name for the register that changed, and <old val> and printed using print_uint32_in_hexadecimal.
The following is an example of running IMPS in tracing mode :
./imps -t examples/hi_addi_1.imps
addi $v0, $zero, 11
$v0 : 0x00000000 -> 0x0000000b
addi $a0, $zero, 'h'
$a0 : 0x00000000 -> 0x00000068 syscall
h addi $v0, $zero, 11
addi $a0, $zero, 'i'
$a0 : 0x00000068 -> 0x00000069 syscall
i addi $v0, $zero, 11
addi $a0, $zero, '\n'
$a0 : 0x00000069 -> 0x0000000a syscall
addi $v0, $zero, 10
$v0 : 0x0000000b -> 0x0000000a syscall
File syscalls
For the last part of this assignment, you will implement the open, read, write and close not result in IMPS performing actual file operations.
You must implement the following syscalls :
syscall 13 : open the file with path $a0 (which should be the address of a nul-terminate
If $a1 is equal to 0 the file is opened for reading, otherwise if $a1 is 1 the file is of flags.
If the file is opened for writing and the file does not exist it is created. If the file does exist it is not truncated.
The lowest unused file descriptor is allocated for this open file and returned via $v0. If an error occurs (such as the file not existing but being opened for reading) $v0 is syscall 14 : read from file descriptor $a0 into a buffer with address $a1 up to $a2 many If an error occurs (such as the file not being opened for reading) $v0 is set to -1, ot syscall 15 : write to file descriptor $a0 with the contents of a buffer with address $a1 If an error occurs (such as the file not being opened for writing) $v0 is set to -1, ot syscall 16 : close file descriptor $a0.
If an error occurs (such as the file descriptor being invalid) $v0 is set to -1, otherw You may assume the following limits are in place :
The maximum number of files you need to handle is 6.
The maximum number of open files at any given time is 8.
The maximum file size is 128 bytes.
You are encouraged to use the reference implementation to check your understanding of the
Autotests
Use the following command to run all of the autotests for subset 4 :
1521 autotest imps S4 [optionally : any extra .c or .h files] For tests involving tracing mode, run :
1521 autotest imps S4_1 [optionally : any extra .c or .h files] For tests involving the file syscalls, run :
1521 autotest imps S4_2 [optionally : any extra .c or .h files]
Reference implementation
A reference implementation is available as 1521 imps. Use it to find the correct output f
1521 imps examples/hi_addi_1.imps hi
Provision of a reference implementation is a common, efficient and effective method to pr likely need to work with after you leave UNSW.
Where any aspect of this assignment is undefined in this specification you should match t Discovering and matching the reference implementation's behaviour is deliberately part of
If you discover what you believe to be a bug in the reference implementation, report it i you do not need to match the reference implementation's behaviour in this case.
Examples
Some example MIPS programs are available in the provided examples directory. You will als
The 1521 imps-asm command can be used to create IMPS executables from assembly source cod create an IMPS executable my_example.imps.
If you pass the --also-disassemble flag to 1521 imps-asm a .disasm file will also be prod
When creating your own test cases make sure to not accidentally include instructions or s case you should use syscall 10 rather than jr $ra.
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 do not have to implement MIPS instructions, system calls, or features that are not You will not be penalized if you implement extra MIPS instructions beyond the ones spec You do not need to handle pseudo-instructions. 1521 imps-asm translates these into the
Your submitted code must be C only. You may call functions from the standard C library mathematics library (math.h). You may use assert.h.
You may not submit code in other languages. You may not use the system function, or oth 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 im 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 If your program writes out debugging output, it will fail automarking tests : make sure You are required to submit intermediate versions of your assignment. See below for deta
Change Log
Version 1.0
(2024-10-25 18:00:00)
Initial release
Assessment Testing
When you think your program is working, you can use autotest to run some simple automated
1521 autotest imps [optionally : any extra .c or .h files]
You can also run autotests for a specific subset. For example, to run all tests from subs
1521 autotest imps S1 [optionally : any extra .c or .h files]
Some tests are more complex than others. If you are failing more than one test, you are e you can run a specific test by giving its name to the autotest command :
1521 autotest imps S1_1_0 [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 o
Whilst we can detect errors have occurred, it is often substantially harder to automatica errors from 1521 autotest will become less and less clear or useful. You will need to do
Emulated tests
To help test the portability of your code in other environments, you can use the 1521 imp your code is incorrectly making assumptions about the system such as endianness or word s
There are two modes you can use with imps-emulated-tests, you can either run
1521 imps-emulated-tests user [optionally : any extra .c or .h files]
which will run your code against the full set of autotests using QEMU user mode em
Alternatively you can run
1521 imps-emulated-tests vm [optionally : any extra .c or .h files]
which will boot up a 32-bit SPARC virtual machine running NetBSD (also using QEMU), and t
Submission
When you are finished working on the assignment, you must submit your work by running giv give cs1521 ass2_imps imps.c [optionally : any extra .c or .h files]
You must run give before Week 10 Friday 18:00:00 to obtain the marks for this assignment. 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 vi
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_imps
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 de your work, you can view your results here ; The resulting mark will also be available via