PROGRAMMING PROJECT 1a:
UTILITY FUNCTIONS FOR A DISASSEMBLER



Review Of: C

You should work individually on this project.



Utility Functions for a Disassembler Project

In this project you will complete two utility functions that will be useful for processing the input for a disassembler (the subject of our next project). You will also complete a test driver to test your two functions. (A test driver is a main function written to "drive" tests of other functions.)

The goal of the project is to gain more familiarity with C by writing some useful functions for a future programming project.

Files: Complete the functions and test driver in the following files. (More information about this program appears below.)

Some other files that will be useful are:

The Makefile contains information for the make command, telling it how to compile this program (and the future disassembler program). (Type make at a command-line prompt or, if you are using an IDE, your IDE may be able to use makefiles.)

The make command will create a compiled executable with the same name as the test driver file, but without the .c extension, i.e., pp1a. You can run your program by typing its name at the command line. It takes two optional parameters: a filename and an integer 1 if you want to turn on debugging. If you run the program with the minimalist starter test file provided above, you'll see that for now it just prints the contents of the test file with a line number inserted at the beginning of each line.

    ./pp1a testfileStarter.txt

Compare the test file with your output and then modify the test file and run the program again to verify its behavior. (The test file is just made of plain ASCII text, so you can modify it with any program that allows you to edit plain text files. Note that C source files are plain text files also, so you can use whatever you use to edit C source files to also edit test files.) Test the program with and without the second parameter, 1.

Project Description:

The input file for the disassembler we will write shortly will contain strings representing MIPS instructions, one per line. Actual MIPS instructions would be stored in 32-bit integers; instead, our file will contain lines of 32 characters ('0' or '1'), where each line represents the 32 bits in a machine language MIPS instruction.

The purpose of the functions you are completing in this project is to read in the strings representing MIPS instructions, make sure they are valid, and decode subsets of the instructions in decimal format.

verifyMIPSInstruction:

The main function in the test driver (pp1a.c) currently reads lines in from a file until reaching the end of the file. If the line ends with a newline, the program strips the newline from the string by replacing it with a null byte. The code that is missing should call verifyMIPSInstruction to verify that the format contains a MIPS instruction in the proper format or print an error if it does not. If the instruction is valid, main should call binToDec several times, with various parameters, to test it effectively and print the results. (Until you have completed the missing code in binToDec, a single call will be a sufficient test.)

The verifyMIPSInstruction function should verify that the string provided to it is 32 characters long and that the characters in the string are all 0's or 1's (character '0' or character '1'). If the instruction is valid, verifyMIPSInstruction should return 1. Otherwise, it should print an error message indicating the error and the line on which it occurred before returning 0.

Test your modifications before going further by adding appropriate data to the existing test file or by creating new data files. Be sure to include tests cases that exercise every path through your code as well as all appropriate boundary conditions (e.g., empty lines, too-long lines, invalid data in the first / last positions, etc.).

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.

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.

binToDec:

The binToDec function should interpret a substring of characters in an array as a binary number, convert it to an integer in decimal format, and return the integer. The first parameter is the array of characters; the second and third parameters are the beginning index and ending index of the substring. For example, assume A is a character array that contains the following characters.

       1 0 1 1 0 1 0 0 1
The call binToDec(A, 2, 5) should convert the string of binary digits '1' '1' '0' '1' (the substring A[2] - A[5], inclusive) to the decimal integer 13 and return it. One efficient solution involves building the decimal number from the least significant digit to the most significant digit by adding in (or not) the appropriate power of two. Rather than calculating the power of two for each digit, you can store the power of two in a variable and multiply it by two when you go to the next digit. (What should the power-of-two variable be initialized to for the least significant digit?)

To test binToDec thoroughly, you should call it in a number of different ways whenever the instruction format is valid. Think particularly about what kinds of boundary conditions you should test for.

Submission Requirements:

You should submit a zip (or tar or 7z) file that contains:

Your program should also work with other input files that may be developed for consistent grading. (Notes: Before zipping up your directory, please rename it to start with your first name, e.g., Alyce_PP1a, so that I don't have a dozen folders with similar names. It is also a good idea to run make clean in the directory before zipping it up; this will remove the machine-specific executable and intermediate "object code" files, since your code will have to be re-compiled on my machine anyway.)

The rubric for grading Programming Project #1a will based on the following.

  PP1a -- Compiles and runs                                            5 pts
  PP1a -- Correctness (satisfies 11 specific criteria)                 13 pts
  PP1a -- Internal documentation and coding style                      6 pts
            (2 pts per file for comments/readability/style:
             good comments, good variable names, indentation, etc)
  PP1a -- Reasonable efficiency                                        2 pts
  PP1a -- Test cases                                                   12 pts

  Total:                                                               38 pts

Note that almost a third of the points are related to testing.