Project Documentation
*********************

When you submit your projects, you will be expected to also turn in three files documenting them: README, DESIGNDOC and TESTCASE.  These guidelines explain what we want to see in those files.

Your submission should have exactly one of each file, in the appropriate directory (e.g. for Assignment 1, place the files in the threads directory).  These files must be written in plain text format (not Microsoft Word, not PDF).  We recommend a text width of 65 characters per line, with a hard limit of 80.  If you use tab characters in your document files, be sure that your text editor's tab width is set to 8.

README
======

This is the easiest of the bunch.  It's the document we'll read while trying to get your assignment to run.  First, place all of your names and Leland IDs (usernames) at the top.  Next, you should also explain any quirks with your program, such as known show-stopper bugs, weird dependencies, and so on.

If you added extra credit features to your project, explain them concisely in the README.  Otherwise, we're likely to miss them.

DESIGNDOC
=========

This file is our primary tool for assessing your design.  Therefore, you should be certain to explain your design in some decent amount of detail.  As a broad rule of thumb, we should be able to explain what basic data structures and algorithms you used to solve the problem after reading the DESIGNDOC, but without looking at the code.

The easiest way to present your DESIGNDOC is to break it down by parts of the project (e.g. for project 1, you can break the DESIGNDOC into four parts).  For each part, you should describe the functionality that needs to be added, the data structures and algorithms used to solve that problem from a high level, and the motivations for each decision/change you make to the code.  Your DESIGNDOC needs to explain and justify your design.  That is, we should be able to understand what you did, and why you chose to do it that way.  The ``why'' should be in concrete terms of greater speed, better space efficiency, cleaner code, or some other real measure of goodness.

Things you don't need: an explanation of the pre-existing Pintos code, an explanation of the project spec, justification for the project (e.g. we don't need you to explain to us why filesystems are important to an operating system), a play-by-play of every change you made to the system, any other pontificating.  (You may laugh at some of the things listed above, but we've gotten all of them in the past.) The DESIGNDOC needs to discuss design decisions and trade-offs and the rationales behind them.  Any other things can be left out, to save your time and ours.

Finally, please keep your DESIGNDOC as short as you can, without sacrificing key design decisions.  You should be brief, yet complete.  We don't want to read novels.

TESTCASE
========

The TESTCASE file should contain all the information about how you tested your programs.  At minimum, this file should contain the output from all the tests that we've provided, with any explanations needed to reproduce the output (arguments to the program, turning features on the program on or off, and so on).

Additionally, you should detail all tests you write yourself.  You are expected to write tests for features which our tests don't cover, and to write some additional stress tests, since our tests will not necessarily be too strenuous.  If you feel that such tests are not required, you should explain why you feel so.  For each test that you write, explain how we can use them, and show some sample output from a run.

Specifically, here are some pointers for writing TESTCASE files which will make them more succinct and us more likely to understand the tests you write:

  * Show us that you tested each part of your assignment.

  * Clearly state in your TESTCASE file what each test is supposed to test.  You should be testing not only the common case, but testing corner cases.  Specify what criteria or issue is being tested.  For example, in testing thread_join you would have specified that you test thread_join when it is called multiple times on the same child thread.

  * Make your tests as succinct as possible.  Most students in the past have done a great job with the testing of thread_join, creating very succinct short tests.  We like that.

  * Your test cases should be placed in a subdirectory called testcases within the project directory.  So for project 1, they should be in pintos/src/threads/testcases.

  * Think about what may actually crash your code.

  * Think about what the compiler might do to your code.  Suppose you write the following to test your virtual memory implementation's ability to expand the stack:

          int main (void) {
            int array[4096];
            array[123] = 234;
            return 0;
          }

     The compiler is quite likely to notice that the value that you write to the array is never used again and thereby decide not to write it at all.  The result is that your test does not test anything at all.

Your TESTCASE file is also where you can show us the improvements that your code makes to the performance of the system. You should be able to show us ``before'' and ``after'' performance data, and explain how the data shows the improvement.  For example, for Problem 1-4, you should show us in the TESTCASE printouts from a workload for the non-Solaris scheduler and the Solaris scheduler and explain why the Solaris scheduler is better.

Finally, we cannot stress enough the importance of being brief and complete.

Keep in mind that the quality of your testing is worth 10% of your project grade.  The bulk of this will be determined from the TESTCASE file.