Review Of: Chapters 1 - 2.

You may work individually or in groups of 2 people to finish this project. I expect that the programming will be your group's effort and not the effort of other persons.

Goal

Write a program that will read in strings representing machine language and write out the corresponding assembly language instructions ("disassembling" the machine code to assembly code).

For example, consider disassembling the following machine code. (The columns and spaces are just for readability; the actual file would just have 32 "bit" characters per line, without spaces.)

100011	01001	01000	0000010010110000			I format instruction
000000	10010	01000	01000	00000	100000	R format instruction
101011	01001	01000	0000010010110000			I format instruction

     lw $t0, 1200($t1)
     add $t0, $s2, $t0
     sw $t0, 1200($t1)

Behavioral Requirements:

Your program should handle all of the instructions and registers in the MIPS Instructions Table and MIPS Registers Table I have provided online. You should be able to handle all 32 registers and all three instruction formats (R, I, and J), including all forms of addressing (for example, lw addresses, beq addresses, and j addresses). You should also be able to handle error conditions, such as invalid opcodes and funct codes. You may find Figures 2.1 (p. 78), 2.6 (p. 100), and 2.14 (p. 121) helpful in addition to the tables I have provided.

Design and Coding Tips:

You should be able to use the verifyMIPSInstruction and binToDec functions you wrote for the Disassembler Utilities Project, as well as the Makefile, header files, and print functions you downloaded for that program. The main function you used to test those utility functions makes a good template for the main method for the disassembler program, so a good starting point is to copy disUtilDriver.c, call it disassembler.c, and then edit it to start implementing your Disassembler project. One of the changes would be to change #include "disUtil.h" to #include "disassembler.h". Remember to change the comments at the top of the file to reflect the different purpose, input, and output of the Disassembler program. Edit the Makefile and change the all: target near the top to include both disUtil and disassembler. (Alternatively, you could change it to just specify disassembler.) Note that the Makefile assumes that the name of the file containing the main function for the Disassembler project is disassembler.c; if you name it something else you will have to fix the Makefile.

You will also want to copy the names.h, instructionNames.c, and registerNames.c files from the Encoding/Decoding Names project.

Finally, there are several new files in the Disassembler repository that you will use for the Disassembler as well:

• disassembler.h
• smallSampleTestfile.input
• smallSampleTestfile.output

As you move beyond these utility functions to the full disassembler program, you may find this structure chart useful, although you should not feel constrained by it.

Testing Tips:

It's difficult to generate an appropriate range of test cases in binary machine code, but you can use the K Sub-MIPS Simulator to turn assembly language instructions into machine code for you.

The input file should contain one MIPS instruction (32 bits) in pseudo-machine language format per line. (It is "pseudo" because each line actually contains 32 ASCII characters representing the 32 bits of a single MIPS instruction.) Your program should:

• Read in the line and verify that it contains exactly 32 characters representing binary digits. Print an error message and go on to the next line if it does not. Keep track of the line numbers so that you can include the line number as part of the error message.
• Determine the opcode and, from that, determine the instruction format type (i.e., R-format, I-format, or J-format).
• Parse the instruction based on the format type. Register numbers should be converted to the proper mnemonic (e.g., register 8 should be converted to $t0). The format type and opcode will also tell you the addressing type. (You may have already completed the getRegName function to do this.)
• For branch and jump instructions, you will not be able to generate label mnemonics.  You should instead print the address that would be associated with the label, if the label existed.  For branch instructions, you may assume that the offset will always be positive (a forward reference) since the binToDec function from the Disassembler Utilities Project only handles positive numbers, but the disassembled code should state the actual address, not the offset.
• Handle all error conditions gracefully. In other words, an error condition should not cause your program to terminate unless it is an error that cannot be recovered from. Otherwise, your program should print a message indicating the type and location of the error and then continue to process the next instruction.

For example, consider the following machine code. (The columns and spaces are just for readability; the actual file would just have 32 "bit" characters per line, without spaces.)

100011	01001	01000	0000010010110000			I format instruction
000000	10010	01000	01000	00000	100000	R format instruction
101011	01001	01000	0000010010110000			I format instruction

35	9	8	1200
0	18	8	8	0	32
43	9	8	1200

     lw $t0, 1200($t1)
     add $t0, $s2, $t0
     sw $t0, 1200($t1)

Ensuring Quality

As specified in the syllabus, your program should adhere to the Kalamazoo College CS Program Style Guide and Documentation Standards, including use of the Braces Line Up style pattern. You may also use the associated template files: the function template file and the header template file.

To ensure that all function calls are syntactically correct (match the function definitions), you should include function declarations for all of your functions in one or more header files (for example, disassembler.h), and include the header file(s) in all appropriate C source files (*.c files).

The Makefile I have provided specifies a set of compiler options that will help you catch many errors at compile time. These options generate warnings about questionable constructions that often indicate programmer confusion or actual logic errors. You may have to make adjustments to the Makefile, though, if the specific options or option names for your compiler are somewhat different.

You may use this sample testfile — smallSampleTestfile.input — as a starting point for testing. It contains sample "machine code" (actually ASCII characters representing binary digits). You can compare your output to the expected output in smallSampleTestfile.output to check your progress. Note, though, that these two files only test some cases; they do not provide a thorough test suite.

Submission Requirements:

Your submission should contain;

• All the source code for your disassembler (including header file(s) and makefiles).
• Your test input file(s) in MIPS machine language.
• External documentation (e.g., a README file, man page or help file) that a new user could use to know how (and why) to use your program. It should include a description of your program, along with some sample input and sample output (which need not be the same as your test file(s), since the point of the sample input/output is to help with your description), and instructions on how to run the program. The Program Style Guide has a little more information on what should be included in external documentation.
• The output produced by your test input file(s).

Rubric:

The rubric for grading this project is based on the following general categories.

  External Documentation                                        1 pt
  Compiles and runs                                             1 pt
  Correctness: General Functionality                            2 pts
  Correctness: all R-, I-, and J-Format Instructions           12 pts
  Thorough Test Suite                                           1 pt
  Comments, Documentation, Clean Programming Style              2 pt

Note that developing a thorough test suite is an important aspect of this assignment.