This semester we will be working on projects extending the DLX OS, which is an operating system that runs on a DLX virtual machine. Both the OS and the virtual machine were programmed by Ethan Miller of the University of California Santa Cruz; the DLX architecture was described by Hennessy & Patterson in their computer architecture texts and in The DLX Instruction Set Architecture Handbook (Sailer & Kaeli).

There will be four projects assigned over the semester. Due dates are listed below and on each project.
 
 

General Information

Here, you'll find information that applies across all of the projects. Project-specific information can be found in each project's page.

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.

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:

• You understand the problem and the solution before writing code.
• You can discover issues with your design before wasting time debugging code that you'll never use.
• You can get help with the concepts without getting bogged down in complex code.

Debugging & testing

One of the most important debugging tools you can use is the dbprintf() statement in your code. This statement is identical to a standard printf() statement (also available in the DLX OS) except that it has an extra argument before the formatting string. This first argument determines whether the dbprintf() statement actually prints anything.

Another debugging technique you may find useful is to turn on instruction and/or data tracing in the simulator. This doesn't affect the execution of the simulated program (the operating system), but does let you trace the action of the CPU to see where things go awry. The trace reports all of the instructions that are executed as well as any loads or stores that are done. Using this information and an assembly language listing of your operating system, you can follow your operating system as it runs. Often, the best solution is to start where the operating system malfunctions and work backwards, tracing the path of execution that led to that point.

Testing your code is an important part of the assignment. You should run as many tests as necessary to convince yourself (and the instructor) 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 part of each project will be submitted electronically, by e-mail to the instructor at clay at cs dot georgetown dot edu. While you will have the option of working on any machine you like, you have been provided with an account on cssun.georgetown.edu. This machine is backed-up regularly, and you should make sure that you have a working copy of your code on csssun before the submission deadline. In the event that something goes awry with mail submissions, the timestamped code on cssun will be your proof of having completed the project on time.

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 this 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 (local copy).

Documentation must be in one of two file formats: plain ASCII text (which MUST be kept to less than 80 columns in width), 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 cssun 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.

Please send documentation as an attachment to your mail.

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, such as testing procedures, etc. Don't submit object files or other files generated by the DLX compiler or assembler. Every file in the directory you submit that could be generated automatically by the DLX compiler or assembler will result in a 5 point deduction from your project grade. This doesn't include scripts, documentation, or input data-the DLX compiler and assembler can't generate these automatically.

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

You will submit your project code by mailing a single tar file containing a directory that is named the same as your login on cssun. To make an appropriate tar file for submission:

• While working, you should place each project in a separate directory in your cssun account. This example refers to you working directory as <project directory>.
• One you have finished working on your project, do a make clean to remove all automatically generated files from your working directory.
• cd .. out of your working directory
• rm -r <user_id> to remove the directory containing a prior submission if necessary - <user_id> is your cssun login.
• mkdir <user_id> to create a directory in which to place copies of the files to be submitted.
• cp -rp <project directory>/* <user_id> to copy all files (with the original modification times) to the new directory.
• tar -cf <user_id>.tar user_id to create a tar file named <user_id>.tar of the directory named <user_id>.
• Mail the tar file as an attachment to me. You can use pine on cssun to accomplish this relatively easily.
• At this point, you should do a chmod a-w <project directory>/* to prevent your project from being accidently modified or erased.

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, even if your implementation doesn't completely work, provided your design is logical and easy to understand. 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 else is!

The grading for each project be approximately 40% design, 60% implementation. We have 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 will 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 instructor could understand. Part of being a good computer scientist is coming up with simple designs and easy to understand code; a solution which 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.

Using the tools

The simulator and compiler/assembler should be capable of running on any Unix-like workstation. We've tested them under Linux and Solaris, 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.

Finding the tools

There are three pieces of code you need: the operating system code, the DLX simulator, and the DLX compiler/assembler. If you do the project on cssun, you will find these tools in the /home/student/cs374/dlx directory. You can set your path to include that directory, or create links to the executables there. Development should be done in your own directory on your own copy of the code in dlxos.tar.

If you want to run the system on your own Linux box, you'll need to build your own version of the assembler, compiler and emulator. You'll need the following tar files from http://www.soe.ucsc.edu/~elm/Software/Dlxos/:

dlxgcc-dist.tgz
dlxsim.tgz
dlxasm.tgz

Building the simulator is relatively straightforward: unpack the compressed tar file, enter the directory, and type gmake. The assembler is even easier-it's written in perl, so you just have to unpack it. The compiler is a little more difficult (you will need bison and flex installed):

• Unpack dlxgcc-dist.tgz.
• Change directories to gcc-2.7.2.3/config/dlx.
• Modify the Makefile in this directory by setting the PREFIX variable to be the directory that you want to install gcc-dlx into.
• Build the compiler by typing make.
• Install the compiler by typing make install.

Solving installation problems

• dlxasm is a perl script. The first line should point to the location of perl on your system (usually /usr/bin/perl on Linux).
• The Makefile in config/dlx uses /usr/ccs/bin/ar to build an archive. This should point to the ar implementation on your system (usually /usr/bin/ar on Linux).
• dlx-ld.c also uses /usr/ccs/bin/ar. The same change as above should be applied to the source file before building it.
• Make sure you modify the Makefile in config/dlx to use the correct PREFIX, which should be the location you want to install the binaries and libraries.

Additional Resources

• Additional documentation on DLX and DLXOS.