Com Sci 230

Step 5: Modify Nachos

Now, you will modify threads/scheduler.cc to print more diagnostic information.

1. Go to your code/threads directory, and check in scheduler.cc with RCS before you change it. Usually, you will need to do mkdir RCS, but I already did that because I had to fix Nachos for the Solaris system. Do ls -l RCS and you'll see that I already checked in Makefile and two other files. Do ci -l scheduler.cc. ci will prompt you for a comment. You can safely skip this comment (type a period followed by return), since it is just a general description of the file. Then, do ls -l RCS again to see that you have checked in scheduler.cc.
2. Open scheduler.cc in your editor. Find a call to SWITCH(oldThread, nextThread), followed by a DEBUG command printing out currentThread. Add a pair of comments just after this DEBUG command, of the form

   // New from your name
   
   // End your name
   

   Throughout the project, mark every change that you make to a Nachos with similar marks (or ``Modified by your name'' if you change old code instead of adding new code). This is important for your lab technique, and also I will only evaluate the work that you mark in this way.
3. Make two copies of the DEBUG command inside your marks. Modify them to print out oldThread and nextThread, with appropriate identifying text. Usually, you will add a comment describing the impact of such a change, but in this case the DEBUG commands are self-documenting.
4. Execute gmake again in your code directory. Find the line in its output indicating that threads/scheduler and threads/nachos were recompiled. Go back to code/threads and do ls -l, noticing what has and hasn't changed.
5. Run threads/nachos with and without the -d option. Look at the diagnostic output from your new DEBUG commands. You should be puzzled. They are not what the C source code in scheduler.cc suggests.
6. When you have succeeded in compiling and testing your change, go to code/threads and do ci -l scheduler.cc again. This time, type in a comment, such as, ``Added debug output of oldThread and nextThread after the context switch.'' It is very important to form a habit of checking in with RCS after every small change.
7. Try out rlog scheduler.cc and rcsdiff scheduler.cc with various options to see what sort of information RCS offers you. My recommended form of check-in, ci -l, checks the file out again. If you goof up the check-in, you will need to learn about the check-out command, co. If you goof up the code files, and need to unwind from an error, you will need to read the manual pages for RCS, ci, and co very carefully.
8. Add more DEBUG commands in strategic places to illuminate the flow of control in context switching. Use the character flag `c' (for context switch to enable these new DEBUG commands. Don't modify switch.s, but trace back from the call to SWITCH in scheduler.cc. Look at my guide to reading the Nachos source for help. You should definitely add DEBUG commands to scheduler.cc and to thread.cc.
9. Create a new test program to display the context switch more efficiently than threadtest.cc does. In this case, do not modify threadtest.cc. Instead, copy threadtest.cc to a new file, such as switchtracetest.cc, and modify the new file to suit. When you first check in the new file to RCS, provide a comment of the form ``Initialized from threadtest.cc.'' Give the functions in your new files new names, of course.
10. Run gmake again, just to be sure that your new material compiles. By now, you are probably tired of watching the voluminous output from gmake in your code directory. The Makefiles in Nachos are organized so that you can make a single directory by executing gmake in that directory (don't assume that this works for all code distributions). But, you need to set things up for switchtracetest.cc, and the right way is a bit delicate. code/threads/Makefile is generated automatically, and you should not change it. Rather, look at code/Makefile.common. Notice how threadtest.cc and threadtest.o are mentioned there. Add switchtracetest.cc and switchtracetest.o in analogous form (of course, you checked in code/Makefile.common with RCS first). Execute gmake depend in code/threads to update code/threads/Makefile, and then execute gmake to compile your new code. Whew.
11. Run nachos again. Nothing changed, because your new test program didn't get invoked.
12. Look at threads/main.cc, and notice the call to the function ThreadTest(). You need to change main.cc to call your new function (I called mine TraceSwitch). But, you want to do this without losing the old possibilities of ThreadTest. Notice the conditional compilation of the call to ThreadTest:

    #ifdef THREADS
        ThreadTest();
    #endif
    

    Run grep THREADS Make* to find out where THREADS is defined. Look at the output from gmake, and notice how the definition of THREADS gets into the command that compiles main.cc. You need to do something similar to choose between ThreadTest and TraceSwitch. I chose a variable called SWITCHTRACE, and created the following nested conditional:

    #ifdef THREADS
    #ifdef SWITCHTRACE
        TraceSwitch();
    #else
        ThreadTest();
    #endif
    #endif
    

    We are still essentially concerned with threads, so we don't want to disable THREADS, in case some other code depends on it (now or in the future). Our final problem is to define SWITCHTRACE for next compile. Look again at the way SWITCHTRACE is defined in the Makefile. It's best not to change the Makefile itself, but we can override variable settings when running gmake. gmake DEFINES="-DTHREADS -DSWITCHTRACE" will do it.
13. Well, gmake DEFINES="-DTHREADS -DSWITCHTRACE" probably had no impact, because a mere change in command-line parameters doesn't trigger recompilation. The -W option to gmake is supposed to deal with this problem, but it doesn't appear to work. So, do touch main.cc to mark main.cc as recently changed, and then do your gmake.

Com Sci 330 only: find and fix the ``undead thread'' problem

By a combination of studying the Nachos code, reading my guide to the code, and running interesting test cases with enlightening debug output, understand the somewhat subtle way in which Nachos removes a thread that has Finished. Discover and demonstrate a subtle bug that sometimes leaves a Finished thread forever in an ``undead'' state (a similar problem happens in UNIX sometimes). The problem occurs when one thread tries to Finish, the next thread is brand new and it Finishes in its first period of execution. Explain the consequences of this bug (they are not usually disastrous, but they can be modestly harmful). Correct the bug, by replicating a small bit of code that needs to appear twice, but only appears once. Demonstrate the behavior of your correcton.

My guide to Nachos code discusses this problem in some detail.

Step 6: Demonstrate your work

Although most people find this counterintuitive, merely getting a computer program to work is less important than demonstrating its behavior to other people. A large part of my evaluation of your project work will depend on your demonstrations. I may occasionally provide test data for input, but designing your own tests is a crucial part of each project assignment. For this preliminary assignment, there isn't much to demonstrate, but we'll go through the motions anyway, to practice for the real thing.

1. In your code directory, create a subdirectory named Project_1_tests. Put in this directory all supporting materials for your demonstration, particularly files of test input (file-name.in) and the corresponding output (file-name.out).
2. In your code directory, create a file named project_1_notes.txt. This is the first file that I will look at, and I will expect it to lead me to all other interesting material.
3. In project_1_notes.txt provide the following 3-4 sections:
   1. A brief statement of the project goals, and what you achieved.
   2. A brief explanation of the changes and additions that you made to Nachos code. This section must contain explicit references to the files that you changed and added. List the changed and added files in an index at the end of the section.
   3. A demonstration of what you accomplished. This section must contain precise instructions that will lead me through the demonstration. Prepare sample inputs in separate files. Provide in this section the commands that I can execute to observe the demonstration. I will execute the commands by cutting and pasting directly from your instructions. After each command that I should execute, describe briefly what we learn from the output.
   4. Optional discussion of your conclusions and observations.

Step 7: Submit your work

When you have a coherent, documented version of your project work, run the command /usr/local/classes/current/CS230/01/bin/submit-project Project_1. This command copies your work to a directory where I can evaluate it. You may resubmit as often as you like before 7:30 AM on Wednesday 15 April. Each new submission will wipe out the previous one, and I will only evaluate the last one. I suggest that you submit well organized, but incomplete, results several times along the way. With this strategy, you can reduce last-minute panic, since you'll only be risking the latest improvements, and not all of the early work. But, please do not submit work without the required internal documentation and explanation. That is, submit work that is incomplete in project functionality, but not work that is incomplete in organization.

Soren Dayton (csdayton@cs) created the submit-project command, and he needs to install it in the directory that I mentioned. He will post final instructions when the installation is done. Contact him by e-mail with minor problems. If there are serious problems with the procedure, I will deal with them on Wednesday, and will not penalize anyone for lateness due to the submission procedures.