$29
Homework #1 - MIPS_Convertor Solution
In this assignment, you will write a command line utility to translate MIPS
machine code between binary and human-readable mnemonic form.
The goal of this homework is to familiarize yourself with C programming,
with a focus on input/output, strings in C, and the use of pointers.
You **MUST** write your helper functions in a file separate from `main.c`. The
`main.c` file **MUST ONLY** contain `#include`s, local `#define`s and the `main`
function. This is the only requirement for project structure. Beyond this, you
may have as many or as few additional `.c` files in the `src` directory as you
wish. Also, you may declare as many or as few headers as you wish. In this
document, we use `hw1.c` as our example file containing helper functions.
# Getting Started
Fetch base code for `hw1` as described in `hw0`. You can find it at this link:
[https://gitlab02.cs.stonybrook.edu/cse320/hw1](https://gitlab02.cs.stonybrook.edu/cse320/hw1).
Both repos will probably have a file named `.gitlab-ci.yml` with different contents.
Simply merging these files will cause a merge conflict. To avoid this, we will
merge the repos using a flag so that the `.gitlab-ci.yml` found in the `hw1`
repo will be the file that is preserved.
To merge, use this command:
```
git merge -m "Merging HW1_CODE" HW1_CODE/master --strategy-option theirs
```
Here is the structure of the base code:
<pre>
hw1
├── include
│ ├── const.h
│ ├── debug.h
│ ├── hw1.h
│ └── instruction.h
├── Makefile
├── rsrc
│ ├── bcond.asm
│ ├── bcond.bin
│ ├── examples.asm
│ ├── examples.bin
│ ├── jump.asm
│ ├── jump.bin
│ ├── matmult.asm
│ ├── matmult.bin
│ ├── typei.asm
│ ├── typei.bin
│ ├── typer.asm
│ └── typer.bin
├── src
│ ├── hw1.c
│ ├── instr_table.c
│ └── main.c
└── tests
└── hw1_tests.c
</pre>
> :nerd: Reference for pointers: [http://beej.us/guide/bgc/output/html/multipage/pointers.html](http://beej.us/guide/bgc/output/html/multipage/pointers.html]).
> :nerd: Reference for command line arguments: [http://beej.us/guide/bgc/output/html/multipage/morestuff.html#clargs](http://beej.us/guide/bgc/output/html/multipage/morestuff.html#clargs).
**Note**: All commands from here on are assumed to be run from the `hw1` directory.
## A Note about Program Output
What a program does and does not print is VERY important.
In the UNIX world stringing together programs with piping and scripting is
commonplace. Although combining programs in this way is extremely powerful, it
means that each program must not print extraneous output. For example, you would
expect `ls` to output a list of files in a directory and nothing else.
Similarly, your program must follow the specifications for normal operation.
One part of our grading of this assignment will be to check whether your program
produces EXACTLY the specified output. If your program produces output that deviates
from the specifications, even in a minor way, or if it produces extraneous output
that was not part of the specifications, it will adversely impact your grade
in a significant way, so pay close attention.
**Use the debug macro `debug` (described in the 320 reference document in the
Piazza resources section) for any other program output or messages you many need
while coding (e.g. debugging output).**
# Part 1: Program Operation and Argument Validation
In this part, you will write a function to validate the arguments passed to your
program via the command line. Your program will support the following flags:
- If no flags are provided, you will display the usage and return with an
`EXIT_FAILURE` return code
- If the `-h` flag is provided, you will display the usage for the program and
exit with an `EXIT_SUCCESS` return code
- If the `-a` flag is provided, you will perform text-to-binary conversion
(i.e. "assembly"), reading text from `stdin` and writing binary to `stdout`.
- If the `-d` flag is provided, you will perform binary-to-text conversion
(i.e. "disassembly"), reading binary from `stdin` and writing text to `stdout`.
> The `-a` and `-d` flags are not allowed to be used in combination with each
> other
> :nerd: `EXIT_SUCCESS` and `EXIT_FAILURE` are macros defined in `<stdlib.h>` which
> represent success and failure return codes respectively.
> :nerd: `stdin`, `stdout`, and `stderr` are special files that are opened upon
> execution for all programs and do not need to be reopened.
Some of these operations will also need other command line arguments which are
described in each part of the assignment. The two usages for this program are:
<pre>
usage: ./hw1 -h [any other number or type of arguments]
usage: bin/hw1 [-h] -a|-d [-b BASEADDR] [-e ENDIANNESS]
-a Assemble: convert mnemonics to binary code
-d Disassemble: convert binary code to mnemonics
Additional parameters: [-b BASEADDR] [-e ENDIANNESS]
-b BASEADDR is the starting memory address for the code
It must be a hexadecimal number of 8 digits or less
-e ENDIANNESS specifies the byte order of the binary code
It must be a single character:
b for big-endian, or
l for little-endian
-h Display this help menu.
</pre>
A valid invocation of the program implies that the following hold about
the command-line arguments:
- All positional arguments (`-a|-d`) come before any optional
arguments (`-b and -e`). The optional arguments may come in any order
after the positional ones.
- If the `-h` flag is provided, it is the first positional argument after
the program executable.
- If an option requires a parameter, the corresponding parameter must be provided
(e.g. `-e` must always be followed by an ENDIANNESS specification).
- If `-b` is given, the BASEADDR argument will be given as a hexadecimal
number in which in addition to the digits ('0'-'9) either upper-case letters
('A'-'F') or lower-case letters ('a'-'f') may be used, in any combination.
- If `-e` is given, then the ENDIANNESS argument will be a single word
(i.e. will have no whitespace).
> :scream: You may only use `argc` and `argv` for argument parsing and
> validation. Using any libraries that parse command line arguments (e.g.
> `getopt`) is prohibited.
> :scream: Any libraries that help you parse strings are prohibited as well
> (`string.h`, `ctype.h`, etc). *This is intentional and will help you
> practice parsing strings and manipulate pointers.*
> :scream: You **MAY NOT** use dynamic memory allocation in this assignment
> (i.e. `malloc`, `realloc`, `calloc`, `mmap`, etc)
For example, the following are a subset of the possible valid argument
combinations:
- `$ bin/hw1 -h ...`
- `$ bin/hw1 -a`
- `$ bin/hw1 -a -e b`
- `$ bin/hw1 -d -b D000d000 -e l`
Some examples of invalid orderings would be:
- `$ bin/hw1 -e b -d`
- `$ bin/hw1 -b D000d000 -a -e b`
> :scream: The `...` means that all arguments, if any, are to be ignored; e.g.
> the usage `bin/hw1 -h -a -b D00D000 -e b` is equivalent to `bin/hw1 -h`
**NOTE:** The makefile compiles the `hw1` executable into the `bin` folder.
Assume all commands in this doc are run from from the `hw1` directory of your
repo.
### **Required** Validate Arguments Function
In `const.h`, you will find the following function prototype (function
declaration) already declared for you. You **MUST** implement this function
as part of the assignment.
<pre>
/**
* @brief Validates command line arguments passed to the program.
* @details This function will validate all the arguments passed to the
* program, returning 1 if validation succeeds and 0 if validation fails.
* Upon successful return, the selected program options will be set in the
* global variable "global_options", where they will be accessible
* elsewhere in the program.
*
* @param argc The number of arguments passed to the program from the CLI.
* @param argv The argument strings passed to the program from the CLI.
* @return 1 if validation succeeds and 0 if validation fails.
* Refer to the homework document for the effects of this function on
* global variables.
* @modifies global variable "global_options" to contain a bitmap representing
* the selected options.
*/
int validargs(int argc, char **argv);
</pre>
> :scream: This function must be implemented as specified as it will be tested
> and graded independently. **It should always return -- the USAGE macro should
> never be called from validargs.**
The `validargs` function should return 0 if there is any form of failure.
This includes, but is not limited to:
- Invalid number of arguments (too few or too many)
- Invalid ordering of arguments
- A missing parameter to an option that requires one (e.g. `-e` with no
ENDIANNESS specification).
- Invalid base address (if one is specified). A base address is invalid
if it contains characters other than the digits ('0'-'9), upper-case
letters ('A'-'F'), and lower-case letters ('a'-'f'), if it is more than
8 digits in length, or if it is not a multiple of 4096
(i.e. the twelve least-significant bits of its value are not all zero).
- Invalid endianness (if one is specified). An endiannness is invalid
if either it does not consist of a single character or that single character
is not either 'b' or 'l'.
The `global_options` variable of type `unsigned int` is used to record the mode
of operation (i.e. assemble/disassemble) of the program, as well as any selected flags
and base address. This is done as follows:
- If the `-h` flag is specified, the least significant bit is 1
- The second least significant bit is 0 if `-a` is passed (i.e. the user wants
assembly mode) and 1 if `-d` is passed (i.e. the user wants disassembly mode)
- The third least signficant bit is 1 if `-e b` is passed (i.e. the user wants
big-endian byte ordering) and 0 otherwise.
- If the `-b` option was specified, then the base address is given by taking
the value of `global_options` and clearing the 12 least significant bits.
If the `-b` option was not specified, then the 20 most significant bits of
`global_options` should all be 0 (i.e. the default base address is 0).
If `validargs` returns 0 indicating failure, your program must print
`USAGE(program_name, return_code)` and return `EXIT_FAILURE`.
**Once again, `validargs` must always return, and therefore it must not
call the `USAGE(program_name, return_code)` macro itself.
That should be done in `main`.**
If `validargs` sets the least significant bit of `global_options` to 1
(i.e. the `-h` flag was passed), your program must print `USAGE(program_name,
return_code)` and return `EXIT_SUCCESS`.
> :nerd: The `USAGE(program_name, return_code)` macro is already defined for you
> in `const.h`.
If validargs returns 1 and the least significant bit of `global_options` is 0,
your program must perform assembly or disassembly accordingly and return
`EXIT_SUCCESS` upon successful completion, or `EXIT_FAILURE` in case of an error.
If `-b` is provided, you must check to confirm that the specified base address
is valid.
If `-e` is provided, you must check that the specified endianness is either
the single character `b` or the single character `l`.
> :nerd: Remember `EXIT_SUCCESS` and `EXIT_FAILURE` are defined in `<stdlib.h>`.
> Also note, `EXIT_SUCCESS` is 0 and `EXIT_FAILURE` is 1.
> :nerd: We suggest that you create functions for each of the operations defined
> in this document. Writing modular code will help you isolate and fix
> problems.
### Sample validargs Execution
The following are examples of `global_options` settings for given inputs.
Each input is a bash command that can be used to run the program.
In the examples, all don't care bits (bits 3-11, where the least significant
bit is numbered 0 and the most significant bit is numbered 31) have been set to 0.
- Input: `bin/hw1 -h`. Setting: 0x1 (`help` bit is set. All other bits are
don't cares.)
- Input: `bin/hw1 -d`. Setting: 0x2 (`disassemble` bit is set).
- Input: `bin/hw1 -d -e b`. Setting: 0x6 (`disassemble` and
`big endian` bits are set).
- Input: `bin/hw1 -d -e b -b BaB000`. Setting: 0xBAB006 (`disassemble` and
`big endian` bits are set, base address is 0xBAB000).
- Input: `bin/hw1 -e b -d -b BaB000`. Setting: 0x0. This is an error
case because the argument ordering is invalid (`-e` is before `-d`).
In this case `validargs` returns 0, leaving `global_options` unset.
# Part 2: MIPS Instruction Format
Presumably you learned something about the MIPS process and its instruction set
in CSE 220. If you need to, review the materials used for that course.
You might also find useful information via
[this link](https://en.wikipedia.org/wiki/MIPS_architecture#Instruction_formats) or
[this one](https://www.cs.cornell.edu/courses/cs3410/2008fa/MIPS_Vol2.pdf).
Below we summarize the information about the MIPS instruction format that will
be needed to do the assignment.
Each MIPS instruction consists of one 32-bit word. We will number the bits
from 0 (least significant bit) to 31 (most significant bit) and we will think
of bit 31 as being "leftmost". To indicate a particular bit field from
the instruction word we will use a notation like 31:26, which indicates
bits 31 down to 26; that is, the 6 "leftmost", or most significant bits.
In every MIPS instruction, bit field 31:26 is used as a 6-bit opcode.
Most instructions are directly identified by one of the 64 possible values
of this field, but as we will see there are some special cases.
There are three types of MIPS instructions: R, I, and J.
Instructions of type R take up to three registers as arguments.
Instructions of type I take up to two registers and a 16-bit immediate value
(obtained from the 16 least significant bits of the instruction word).
Instructions of type J take a jump target from the 26 least signficant
bits of the instruction word.
The MIPS processor has 32 registers, which means that it takes 5 bits to
specify a register.
The registers are specified by the contents of bit fields
25:21 (called `RS`), 20:16 (called `RT`), and 15:11 (called `RD`),
or, in some cases, bit field 10:6.
In the files `instruction.h` and `instr_table.c` you have been provided
with a set of tables that can be used to decode MIPS binary instruction words.
Rather than going through full details of the MIPS instruction format,
we will just go through the procedure for decoding an instruction using the
tables.
The type `Opcode` is an enumerated type that assigns to integer values
in the range 0 to 63 the names of MIPS instructions, and in addition defines
names for three additional values `SPECIAL` (64), `BCOND` (65), and `ILLEGL` (66).
`Opcode` values in the range 0 to 63 serve as indices into the
instruction table `instrTable`. Each entry in this table uniquely identifies
a particular type of MIPS instruction and provides further information about it.
Our first objective in decoding an instruction is to determine the proper
`Opcode` value (in the discussion below we refer to this as "the Opcode"),
thereby obtaining access to the proper entry from the instruction table.
The starting point for obtaining the Opcode is the value in bits 31:26
of the instruction word.
This value is used as an index into `opcodeTable` and the value (of type `Opcode`)
at that index in the table is retrieved.
- If the value obtained from `opcodeTable` is neither `SPECIAL` nor `BCOND`,
then it is the Opcode.
- If the value obtained from `opcodeTable` is `SPECIAL` (this occurs when the
value of bits 31:26 is 000000), then the value in bits 5:0 of the instruction
word is used as an index into the table `specialTable` to obtain the Opcode.
- If the value obtained from `opcodeTable` is `BCOND`, then the value in bits
20:16 is examined. If the value is 00000, 00001, 10000, or 10001,
then the Opcode is `OP_BLTZ`, `OP_BGEZ`, `OP_BLTZAL`, or `OP_BGEZAL`, respectively,
otherwise it is an error.
Having determined the Opcode, it is then used as an index into `instrTable`
and the corresponding `Instr_info` structure is retrieved.
What happens next depends on the value of the `type` field.
This value can be `NTYP` (which occurs in a few entries of the table that
do not correspond to actual instructions), `RTYP`, which indicates an
instruction of type R, `ITYP`, which indicates an instruction of type I,
and `JTYP`, which indicates an instruction of type J.
The next task is to determine the sources of the instruction arguments.
For this, the information in the `srcs` field of the `Instr_info` structure is used.
This field consists of an array of three values of type `Source`.
The first entry in this array specifies the source of the first instruction
argument, the second entry specifies the source of the second instruction
argument, and the third entry specifies the source of the third argument.
There are five possible source values: `RS`, `RT`, `RD`, `EXTRA`, and `NSRC`.
The value `RS` indicates that the argument source is the register specified
by the RS field of the instruction word.
Similarly, the values `RT` and `RD` the argument source is the register
specified by the RT or RD field of the instruction word, respectively.
The value `EXTRA` indicates that the argument value has to be decoded
from the instruction word in a way that depends on the particular type
of instruction.
The value `NSRC` is used as a place-holder value for instructions that take fewer
than three arguments.
For arguments with source `EXTRA`, the actual argument is determined as follows:
- If the Opcode is `OP_BREAK`, then the argument consists of the 20-bit
value in bits 25:6 of the instruction word.
- For instructions of type R, the argument consists of the 5-bit value
in bits 10:6 of the instruction word.
- For instructions of type I, the argument is obtained by extracting the 16-bit
value in bits 15:0, treating bit 15 as a sign bit,
and performing sign-extension to a 32-bit signed integer.
For non-branch instructions of type I (such as `ADDI`),
this 32-bit signed integer is the immediate argument to the instruction.
For the conditional branch instructions
`BEQ`, `BGEZ`, `BGEZ`, `BGEZAL`, `BGTZ`, `BLEZ`, `BLTZ`, `BLTZAL`, `BNE`,
the 32-bit signed integer value is further processed by shifting it left by two bits
(which amounts to multiplication by 4) and then treating it as a PC-relative branch
offset. It is added to the current value of the PC register (this will be the memory
address at which the instruction "lives", plus 4) to obtain an absolute address
which is the branch target.
- For instructions of type J, the argument is obtained by extracting the 26-bit
value in bits 25:0 of the instruction word and treating it as an unsigned integer.
This value is shifted left by two bits and then added to the value obtained from
the PC by zeroing the 28 least significant bits, to obtain an absolute address
that is the jump target. (As above, the PC value is given by the memory address
of the instruction, plus 4.)
### Example 1:
The instruction word is 0x00c72820, which when written in binary is:
> <pre>
> 0000 0000 1100 0111 0010 1000 0010 0000
> OOOO OOSS SSST TTTT DDDD D FF FFFF
> </pre>
The letters written underneath the bits indicate the various bit fields:
`O` for the opcode field in bits 31:26,
`S` for the RS field in bits 25:21,
`T` for the RT field in bits 20:16,
`D` for the RD field in bits 15:11, and
`F` for the function code in bits 5:0.
The value in bits 31:26 is 000000; i.e. 0.
Using this as an index into `opcodeTable` yields `SPECIAL`,
so it is then necessary to use the value in bits 5:0 as an index into `specialTable`.
This index is 100000, or 32 in decimal, and the entry at that index is `OP_ADD`.
The corresponding entry in `instrTable` indicates that the `ADD` instruction is
of type R, and that the three arguments are given by RD, RS, and RT.
The value of RD (in bits 15:11) is 00101 indicating that the first argument is
register 5.
The value of RS (in bits 25:21) is 00110 indicating that the second argument is
register 6.
The value of RT (in bits 20:16) is 00111 indicating that the third argument is
register 7.
So the mnemonic form of this instruction is `add $5,$6,$7`.
### Example 2:
The instruction word is 0x8cc50007, which when written in binary is:
> <pre>
> 1000 1100 1100 0101 0000 0000 0000 0111
> OOOO OOSS SSST TTTT XXXX XXXX XXXX XXXX
> </pre>
The value in bits 31:26 is 100011, or 35.
Using this as an index into `opcodeTable` yields OP_LW.
The corresponding entry from instrTable indicates that the
instruction is of type I, with first argument source RT,
second argument source EXTRA, and the third argument source RS.
RT is 00101 so the first argument is register 5.
RS is 00110 so the third argument is register 6.
The second argument is obtained from bits 15:0, which have the value 7.
So the mnemonic form of this instruction is `lw $5,7($6)`.
### Example 3:
The instruction word is 0x10effc1f, which when written in binary is:
> <pre>
> 0001 0000 1110 1111 1111 1100 0001 1111
> OOOO OOSS SSST TTTT XXXX XXXX XXXX XXXX
> </pre>
The value in bits 31:26 is 000100, or 4.
Using this as an index into `opcodeTable` yields OP_BEQ.
The corresponding entry from instrTable indicates that the
instruction is of type I, with first argument source RS,
second argument source RT, and the third argument source EXTRA.
RS is 00111 so the first argument is register 7.
RT is 01111 so the third argument is register 15.
The third argument is obtained from bits 15:0, which is `fc1f` in hex.
This 16-bit value is sign-extended to the 32-bit signed value
`fffffc1f`, which is then shifted two bits to obtain `ffff f07c`,
or -3972 in decimal. This is the PC-relative branch offset.
This offset is added to the current value of the PC
(i.e. the memory address of the instruction, plus 4) to obtain
the final absolute address that is the branch target.
Assuming the memory addess of this instruction is `1000` in hex,
or 4096 in decimal, the branch target is 4096 + 4 - 3972, or 128 in decimal.
So the mnemonic form of this instruction is `beq $7,$15,128`.
### Example 4:
The instruction word is 0x08000400, which when written in binary is:
> <pre>
> 0000 1000 0000 0000 0000 0100 0000 0000
> OOOO OOXX XXXX XXXX XXXX XXXX XXXX XXXX
> </pre>
The value in bits 31:26 is 000010, or 2.
Using this as an index into `opcodeTable` yields OP_J.
The value in bits 25:0 is 0000400, which is shifted left two bits to obtain
`00001000` in hex.
Assuming that the memory address of the instruction is `40000000` in hex,
the PC value at the time of execution would be `40000004`.
Clearing the 28 least-significant bits yields `40000000`, and adding this
to `00001000` yields `40001000` in hex.
So the mnemonic form of this instruction is `j 0x40001000`.
> :scream: The MIPS instruction set does not support jumps to addresses
> whose four most-significant bits differ from those of the current PC value.
> Consequently, an attempt to assemble a jump instruction (i.e. `J` or `JAL`)
> whose target address differs in its four most-significant bits from the base
> address supplied with `-b` should be treated as an error.
# Part 3: **Required** `encode` and `decode` functions
In order to provide some additional structure for you, as well as to make it
possible for us to perform additional unit tests on your program,
you are required to implement the two functions below as part of your program.
The prototypes for these functions are given in `const.h`.
Once again, you **MUST** implement these functions as part of the assignment,
as we will be testing them separately.
<pre>
/**
* @brief Computes the binary code for a MIPS machine instruction.
* @details This function takes a pointer to an Instruction structure
* that contains information defining a MIPS machine instruction and
* computes the binary code for that instruction. The code is returne
* in the "value" field of the Instruction structure.
*
* @param ip The Instruction structure containing information about the
* instruction, except for the "value" field.
* @param addr Address at which the instruction is to appear in memory.
* The address is used to compute the PC-relative offsets used in branch
* instructions.
* @return 1 if the instruction was successfully encoded, 0 otherwise.
* @modifies the "value" field of the Instruction structure to contain the
* binary code for the instruction.
*/
int encode(Instruction *ip, unsigned int addr);
</pre>
<pre>
/**
* @brief Decodes the binary code for a MIPS machine instruction.
* @details This function takes a pointer to an Instruction structure
* whose "value" field has been initialized to the binary code for
* MIPS machine instruction and it decodes the instruction to obtain
* details about the type of instruction and its arguments.
* The decoded information is returned by setting the other fields
* of the Instruction structure.
*
* @param ip The Instruction structure containing the binary code for
* a MIPS instruction in its "value" field.
* @param addr Address at which the instruction appears in memory.
* The address is used to compute absolute branch addresses from the
* the PC-relative offsets that occur in the instruction.
* @return 1 if the instruction was successfully decoded, 0 otherwise.
* @modifies the fields other than the "value" field to contain the
* decoded information about the instruction.
*/
int decode (Instruction *ip, unsigned int addr);
</pre>
These functions each take as an argument a pointer to a structure of type
`Instruction`, which is defined in `instruction.h`.
The `decode` function assumes that the `value` field has been set to the
binary code for a MIPS instruction, and it decodes this value to fill in
the other fields.
The `info` field should be set to a pointer to the appropriate
`Instr_info` structure obtained from `instrTable`.
The entries of the `regs` array should be set to the contents of the
RS, RT, and RD fields of the instruction word. (**Note:** these should
always be set even if the particular instruction does not use those fields.)
The `extra` field should be set to the "extra" argument decoded from the
instruction word. As this is done differently for each type of instruction,
this does not have to be set unless the instruction uses `EXTRA` as an
argument source.
The entries of the `args` field should be set to the final values of the
instruction arguments, as required in order print out the instruction in
mnemonic form (i.e. `args[0]` corresponds to the first `%` in the
`format` string, `args[1]` corresponds to the second `%`,
and `args[2]` to the third). If the instruction takes fewer than three
arguments, the unused entries (i.e. the ones with src `NSRC`) should be
set to 0.
The `encode` function does the inverse operation from `decode`:
it assumes that all the fields other than `value` have been set,
and it computes the binary code for the instruction and stores
it in the `value` field.
> :scream: You should not define additional tables to help you map
> instruction mnemonics to `Opcode` values for implementing
> `encode`. Instead, to perform this mapping you should use a linear
> search of the existing `instrTable`. You should use the `sscanf`
> function to match a format string from the `instrTable` against a
> mnemonic instruction read from the input. The mapping defined by
> the `specialTable` should be inverted using a similar linear scan
> approach.
The implementation of `validargs`, `encode`, and `decode` constitutes most
of the work involved in implementing the program. Once these have been written,
finishing the program should be easy.
One requirement we have yet to consider is the endianness option.
Recall that "endianness" refers to the order in which the bytes in a multi-byte
quantity are stored in memory or written to a file.
In "little-endian" byte order, the **least-significant** byte is stored at the
lowest-numbered memory address or written first to a file.
In "big-endian" byte order, the **most-significant** byte is stored or written
first.
The default mode of operation of your program should be to use little-endian
byte order for reading and writing binary MIPS code. However, if the `-e b` option
is specified, then big-endian ordering should be used instead.
# Part 4: Running the Completed Program
In either assembly or disassembly mode, the program reads from `stdin` and writes
to `stdout`. In assembly mode, since the input is text, it is possible to enter
to enter assembly code directly from the terminal:
> <pre>
> $ bin/hw1 -a
> add $5,$6,$7
> j 0x1000
> </pre>
**NOTE:** In the above example, the program encrypts one line at a time
and stops encrypting after it reads `^d` (control-d) from `stdin`. Entering `^d`
into a terminal in a UNIX system signals an `EOF` (end of file) to the program.
If you run the program in assembly mode this way, the binary output of the
program will also be sent to the terminal. This binary data will appear
as "garbage" in the output. To avoid this, the binary output should be redirected,
either to a file or else via a pipe to a program that can produce a printable
representation of it.
To redirect the output to a file `hw1.out`, you can use:
> <pre>
> $ bin/hw1 -a > hw1.out
> add $5,$6,$7
> j 0x1000
> $ echo $?
> 0
> </pre>
> :nerd: The `>` symbol tells the shell to perform "output redirection":
> the file `hw1.out` is created (or truncated if it already existed -- be careful!)
> and the output produced by the program is sent to that file instead
> of to the terminal.
> :nerd: `$?` is an environment variable in bash which holds the return code of
> the previous program run. In the above, the `echo` command is used to display
> the value of this variable.
The contents of `hw1.out` can then be viewed using the `od` ("octal dump") command:
> <pre>
> $ od -X hw1.out
> 0000000 00c72820 08000400
> 0000010
> </pre>
> :nerd: The `-X` flag instructs `od` to interpret the file as a sequence of 32-bit
> words, which are printed as 8-digit hexadecimal values. In this case, the file
> contains two such words: `00c72820` and `08000400`. The values in the first
> column indicate the offsets from the beginning of the file, specified as 7-digit
> octal (base 8) numbers.
Alternatively, the output of the program could be redirected via a "pipe" to
the `od` command, without using any file:
> <pre>
> $ bin/hw1 -a | od -X
> add $5,$6,$7
> j 0x1000
> 0000000 00c72820 08000400
> 0000010
> </pre>
> :nerd: In this case, you won't see the output produced by `od` until
> `^d` has been typed, because when the output of a program is redirected to
> a pipe the system assumes that the program is being run non-interactively,
> so for efficiency it buffers a larger amount of the output rather than
> emitting it a line at a time.
In disassembly mode, it is not very useful to read the input from the terminal,
since it would be very difficult to generate the necessary binary data using
the keyboard. Instead, the input should be redirected *from* a file:
> <pre>
> $ bin/hw1 -d < hw1.out
> add $5,$6,$7
> j 0x1000
> </pre>
Finally, a pipe can be used to assemble and disassemble in a single run.
This is one way to test whether your program is working properly:
> <pre>
> $ bin/hw1 -a | bin/hw1 -d
> add $5,$6,$7
> j 0x1000
> add $5,$6,$7
> j 0x1000
> </pre>
The output should be identical to the input if the program is working properly.
## Testing Your Program
In testing your program, it is useful to be able to compare two files
to see if they have the same content. The `diff` command (use `man diff`
to read the manual page) is useful for comparison of text files.
On the other hand, the `cmp` command can be used to perform a byte-by-byte
comparison of two files, regardless of their content:
> <pre>
> $ cmp file1 file2
> </pre>
If the files have identical content, `cmp` exits silently.
If one file is shorter than the other, but the content is otherwise identical,
`cmp` will report that it has reached `EOF` on the shorter file.
Finally, if the files disagree at some point, `cmp` will report the
offset of the first byte at which the files disagree.
We can take this a step further and run an entire test without using any files:
> <pre>
> $ cmp <(echo "j 0x1000") <(echo "j 0x1000" | bin/hw1 -a | bin/hw1 -d)
> $ echo $?
> 0
> </pre>
> :nerd: `<(...)` is known as process substitution. It is allows the output of the
> program(s) inside the parentheses to appear as a file for the outer program.
Because both strings are identical, `cmp` outputs nothing.
Finally, we can test the program on entire files with a similar command:
> <pre>
> $ cmp <(cat rsrc/bcond.asm) <(cat rsrc/bcond.asm | bin/hw1 -a -b 1000 | bin/hw1 -d -b 1000)
> $ echo $?
> 0
> </pre>
> :nerd: `cat` is a command that outputs a file to `stdout`.
## Unit Testing
Unit testing is a part of the development process in which small testable
sections of a program (units) are tested individually to ensure that they are
all functioning properly. This is a very common practice in industry and is
often a requested skill by companies hiring graduates.
> :nerd: Some developers consider testing to be so important that they use a
> work flow called test driven development. In TDD, requirements are turned into
> failing unit tests. The goal is then to write code to make these tests pass.
This semester, we will be using a C unit testing framework called
[Criterion](https://github.com/Snaipe/Criterion), which will give you some
exposure to unit testing. We have provided a basic set of test cases for this
assignment.
The provided tests are in the `tests/hw1_tests.c` file. These tests do the
following:
- `validargs_help_test` ensures that `validargs` sets the help bit
correctly when the `-h` flag is passed in.
- `validargs_disassem_test` ensures that `validargs` sets the Disassembly bit
correctly when the `-d` flag is passed in.
- `help_system_test` uses the `system` syscall to execute your program through
Bash and checks to see that your program returns with `EXIT_SUCCESS`.
### Compiling and Running Tests
When you compile your program with `make`, a `hw1_tests` executable will be
created in your `bin` directory alongside the `hw1` executable. Running this
executable from the `hw1` directory with the command `bin/hw1_tests` will run
the unit tests described above and print the test outputs to `stdout`. To obtain
more information about each test run, you can use the verbose print option:
`bin/hw1_tests --verbose=0`.
The tests we have provided are very minimal and are meant as a starting point
for you to learn about Criterion, not to fully test your homework. You may write
your own additional tests in `tests/hw1_tests.c`. However, this is not required
for this assignment. Criterion documentation for writing your own tests can be
found [here](http://criterion.readthedocs.io/en/master/).
# Hand-in instructions
**TEST YOUR PROGRAM VIGOROUSLY!**
Make sure your directory tree looks like this and that your homework compiles:
<pre>
hw1
├── include
│ ├── const.h
│ ├── debug.h
│ ├── hw1.h
│ ├── instruction.h
│ └── ... Any additional .h files you defined
├── Makefile
├── rsrc
│ ├── bcond.asm
│ ├── bcond.bin
│ ├── examples.asm
│ ├── examples.bin
│ ├── jump.asm
│ ├── jump.bin
│ ├── matmult.asm
│ ├── matmult.bin
│ ├── typei.asm
│ ├── typei.bin
│ ├── typer.asm
│ ├── typer.bin
│ └── ... Any sample text files given or created (will not be used in graded)
├── src
│ ├── hw1.c
│ ├── instr_table.c
│ └── main.c
└── tests
├─── hw1_tests.c
└── ... Any additional criterion test files you may have written
</pre>
This homework's tag is: `hw1`
`$ git submit hw1`
> :nerd: When writing your program try to comment as much as possible. Try to
> stay consistent with your formatting. It is much easier for your TA and the
> professor to help you if we can figure out what your code does quickly!
