CMPS 111, Fall 2004

Projects

Here, you'll find information that applies across all of the projects. Project-specific information can be found in each project's home page. There will be four projects assigned this quarter, each one due about 2 weeks after it is assigned. Due dates are listed on the schedule and each individual project description:

Design & documentation

The assignments in this class do not require you to write large quantities of code. For most assignments, you need only write a few hundred lines of code, if not fewer. However, the concepts covered in class and in the operating system are quite difficult for most people. As a result, deciding which lines of code to write is very difficult. This means that a good design is crucial to getting your code to work, and well-written documentation is necessary to help you and your group to understand what your code is doing. A sample design document is available online.

The most important thing to do is write your design first and do it early! Each assignment is about two weeks long; your design should be complete by the end of the first week. Doing the design first has many advantages:

Doing your design early is the single most important factor for success in completing your programming projects!

Using the DLX tool set

There is a separate set of Web pages that describe how to use the DLX tools. These pages contain details on using the DLX compiler and simulator, as well as a discussion of how to use the DLX debugger. You should read these pages over before starting your first project.

Debugging & testing

Probably the best tool for debugging is gdb, which works with the DLX simulator to provide an environment similar to gdb on "vanilla" programs on Unix. Please read the DLX debugger page for more information.

Another useful tool is the dbprintf() statement in your code. This statement is identical to a standard printf() statement (also available in the DLXOS kernel) except that it has an extra argument before the formatting string. This first argument determines whether the dbprintf() statement actually prints anything. For example, dbprintf('m', "%d only when m is set\n", x) would print the string only when the m debugging flag was set. The DLXOS documentation has more details on this, and there are plenty of examples in the code.

Testing your code is an important part of the assignment. You should run as many tests as necessary to convince yourself (and the TA or grader) that your code works. This can be done by including several sets of tests in a single executable (selectable by passing arguments to the operating system via the -a option to the simulator) or by having several different versions of the source file. Either way, you should include a README file with your code to explain how you tested it.

Projects may not come with test data files, so you might have to make up your own. The best way to do this is to pretend that your job is to crash your program, and come up with input data or situations that are likely to cause problems. Many programs can deal with "normal" input; however, operating systems have to deal with all kinds of error conditions without crashing (though Micro$oft doesn't seem to have learned this...).

Handing in the project

Each project must be handed in using the submit system on the CATS instructional computing cluster. For each project, hand in documentation, code, and any test files you created (scripts or data).

Design documentation

Your design documentation should describe the design of your project. This includes the data structures you're going to use, as well as the high-level pseudo-code for each high-level function. For the first assignment, the high-level functions are pretty much the only functions you're going to need. For later assignments, though, you may have lower-level functions that aren't part of the "public" interface. We suggest that you document major functions that aren't visible—it makes design simpler—but you don't have to document every single function you're going to implement. A sample design document is available online.

Documentation must be in one of two file formats: plain ASCII text, or Adobe Portable Document Format (PDF). However, you don't have to purchase Adobe Acrobat to generate PDF. Instead, print your document to a file (this works on Macs, PCs, and Unix) and then use the Unix command ps2pdf on the Instructional Computing cluster to convert PostScript to PDF. Regardless of how you generate your PDF file, please stick to the basic fonts—Times, Helvetica, Courier, and Symbol—to ensure that it'll display correctly on most computers and printers.

Your final design document will be turned in as part of your full project, and will be the basis for the design grade for your project. Your design document should be called either design.txt (if the document is in ASCII) or design.pdf (if it's in PDF).

Project code

Please turn in all of the files you used to build your project: source code, Makefiles, and any other scripts you may have used. In addition, please include a README file to explain anything unusual to the TA—testing procedures, etc. Your code and other associated files should be in a single directory so they'll build properly in the handin directory.

Turning in files

Please turn in exactly two files for each project: a design document, and a compressed tar file containing all of your source code, test files, Makefiles, and anything else you need to run the code.

You can turn in the files by running this Unix command in your project directory:

submit cmps111-elm.f04 projn design.pdf projn.tar.gz

Of course, substitute design.txt for design.pdf if you used plain text for your design.

Generating the tar file can be tricky. You can take one of two approaches. First, you can use the Makefile that's supplied with DLXOS. make tarball will generate a tar file with all of the files you need and none that you don't. You can add additional files to the STUDENTFILES line near the top of the Makefile; any files on that line will be included as well. Second, you can run the tar and gzip commands yourself if you prefer. Please make sure that you only hand in source code, test files, and documentation; do not hand in generated files (those created only by the DLX compiler or assembler).

The default Makefile supplied with the operating system provides clean and spotless targest; make clean will remove most generated files from the project directory (make spotless removes them all) , which may be helpful for doing a "clean build" of the operating system or eliminating large (but automatically recoverable) files from old project directories.

Grading the projects

The intent of the grading for the project is not to differentiate among those students who do a careful design and implementation of the assignments. Rather, the grading helps us identify those students who (i) don't do the assignments or (ii) don't think carefully about the design, and therefore end up with a messy and over-complicated solution. Remember that you can't pass this course without at least making a serious attempt at each of the assignments. Further, the grading is skewed so that you will get substantial credit for a clean, logical, easy-to-understand design, even if your implementation doesn't completely work. This means that you should first strive to come up with a clean design of your project on paper. Also, don't try to add fancy features just because someone is!

The grade for each project will be 45% for design and 55% implementation. We've structured the grading in this way to encourage you to think through your solution before you start coding. If all you do is to work out a detailed design for what you would do to address the assignment (and if the design would work!), but you write no code, you'll still get almost half of the credit for the assignment. The implementation portion of the grade considers whether you implemented your design, ran reasonable test cases, and provided documentation that the TA could understand. Part of being a good computer scientist is coming up with simple designs and easy-to-understand code; a solution that works isn't necessarily the best that you can do. Thus, part of the design and implementation grade will be based on whether your solution is elegant, simple, and easy to understand.

Finding the DLX tools

The simulator and compilation tools should be capable of running on any Unix-like workstation. We've tested them under Linux (some versions), Solaris, and Mac OS X, but can't make guarantees for any other operating system. The dlxos code, however, runs only in the simulator, and should run anywhere the simulator can run. The DLX information pages contain instructions for installing the DLX tool set. We can't provide a lot of support for installing the tools in your own environment. If you think you might have difficulty installing the tools on your own system, you're encouraged to use the tools on the CATS machines.

There are three pieces of code you need: the operating system code, the DLX simulator, and the DLX binary tools. If you want to do your project work on the CATS instructional systems (or associated workstations), you only need the code for the operating system itself. Both the DLX simulator and the DLX toools are available on all CATS machines running Solaris that can mount AFS in the directory /afs/cats.ucsc.edu/courses/cmps111-elm/dlx/bin. You need not copy files from this directory; instead, make links to the executables (dlxsim and a lot of executables preceded by dlx-elf). Of course, your operating system development should be done in your home directory.

Additional Resources

Last updated 29 Sep 2004 by Ethan L. Miller (elm at ucsc dot edu)