Assignment 0: Introducing Nachos

Due date: January 26th

Individual submissions for this assignment. Students will work in teams of three for the remaining assignments.

1. Introduction

This assignment will familiarize you with Nachos, the operating system and machine simulator combination that you will use to implement the concepts discussed in class. This assignment will also give you a chance to write a relatively simple program in the subset of C++ that we will use for this class.

2. What is Nachos?

Nachos is divided into two main parts:

the operating system, whose functionality you will augment in subsequent homework assignments.
the machine simulator, which emulates the physical hardware on which your operating system will run.

As this course is about writing operating systems, and not designing or simulating hardware, you may not change the machine simulator but may modify or augment any portion of the operating system code that runs on it. The machine simulator resides in the directory /c/cs422/nachos/code/machine. Other components (such as thread management) reside under the directory /c/cs422/nachos/code.

There will be a Nachos programming assignment for each of the following topics:

thread management
multiprogramming
virtual memory
filesystems

The assignments are cumulative in that you use code developed in each assignment to complete subsequent ones.

Nachos runs as a UNIX user process; your operating system code and the machine simulator are linked together into a single executable. In reality, operating systems run on bare hardware (without machine simulator code). This hardware handles everything from interrupts to registers to page tables. User processes run on top of the operating system and make system calls, calls to operating system functions in the kernel. The concept of using a simulated machine is a useful one in operating system design, as it can be significantly more difficult to debug and test an operating system running on real, bare hardware. While the Nachos machine simulator functions well as a platform for developing operating system code and corresponds roughly to the physical hardware of a DECstation, its emulation is by no means exhaustive.

3. Machine Directory Questions

Enclosed is a brief description of the code in the Nachos directory machine. You should use this list to guide you in reviewing all of the existing code in the system. The description also includes questions to help you notice and pinpoint some of the most important parts of the system. The key part of this exercise is understanding the base system. Your goal is to clearly grasp how it all fits together so that you can make intelligent design decisions when you approach future assignments. This may seem tedious, but if you understand how the base system works now, you will have much less difficulty completing future assignments.

These questions are not meant to be tricky--most of the answers can be found in comments in the Nachos source and in the Nachos Roadmap, though you may have to look elsewhere (such as the textbook) for some backgound information.

3.1 Mipssim

3.1.1 mipssim.h

Defines opcodes and decoding tables.

3.1.2 mipssim.cc

This is the actual machine simulator; it contains some of the methods for the Machine and Instruction classes.

Machine::Run - called when you start a new program; loops eternally calling OneInstruction() and then counting a tick (OneTick()).
Machine::OneInstruction - executes a single instruction: fetches the instruction from memory (possible exception), calls InstructionDecode(), computes the next PC, calls ExecuteInstruction(), does delayed loads, and sets the PC.
Machine::DelayedLoad - executes a delayed load.
Instruction::Decode - sets source, destination, and target registers, and extracts the opcode.
Auxiliary functions:
TypeToReg - fetches a register number from an instruction.
Mult - implements R2000 multiplication.

3.1.3 Questions

1. How many different instruction formats are there? What are they called?

2. How many registers can you possibly have in a single instruction?

3. What is the minimum number of MIPS assembly instructions needed to add the contents of two registers, and store the result back to memory? Why can't this be done in a single instruction?

3.2 Machine

3.2.1 machine.h

Defines the machine constants (e.g., sector size, page size, physical memory size, TLB size, etc.) and register names (e.g., stack, pc, etc.).

3.2.2 machine.cc

Provides most of the routines and data structures associated with the Machine class.

Machine::Machine - creates the machine and initializes all the registers, calling on a lot of other constructors to "put the machine together." For example, TLB or page tables are created here, as is the memory array.
Machine::~Machine - deallocates machine resources.
Machine::RaiseException - simulates a machine exception; saves required state and dispatches to the appropriate exception handler.
Machine::Debugger - implements a very crude debugging environment for user- level programs.
Machine::DumpState - used for debugging; dumps out the machine registers.
Machine::ReadRegister - returns the value stored in a simulated register.
Machine::WriteRegister - sets the value of a register.
Auxiliary Functions:
CheckEndian - verifies that the underlying hardware uses correct byte-ordering.

3.2.3 Questions

1. What causes the machine to change into system mode? What events in the user program can cause this?

2. Let's say that you wanted to execute: register 3 gets register 1 + register 2. What single C statement, involving three function calls, could you use to do this?

3. If you execute DumpState(), will you see the contents of the memory of your Nachos machine?

4. How many registers are there in this machine?

5. Can this machine have both a TLB and a page table?

3.3 Console

3.3.1 console.h

Defines the Console class. The console is the controlling terminal of a machine. We conventionally think of the console (or a terminal) as a single device, but in reality there are two: the keyboard for input and the display for output.

3.3.2 console.cc

Console::Console - creates the devices and initializes the handlers for input and output.
Console::~Console - frees up console resources.
Console::CheckCharAvail - checks if there is a character to read; if so, reads it and calls the appropriate handler. Also schedules the next interrupt to check for a character.
Console::WriteDone - calls the write handler when a write has completed.
Console::GetChar - processes a character read from the console.
Console::PutChar - sets up a character for output.

3.3.3 Questions

1. Where is the console created? (The answer to this is not Console::Console(). We want to know where the constructor is called from.)

2. What are its initial read and write handlers?

3. Where is the function Read() (used by Console::CheckCharAvail()) defined? Why does the code invoke Read() here, and not ReadPartial()?

4. What are the status flags in the Console class and what do they mean?

3.4 Disk

3.4.1 disk.h

Defines the Disk class and sets disk constants.

3.4.2 disk.cc

Disk::Disk - creates the disk object, and opens and initializes the file that simulates the disk.
Disk::~Disk - frees disk resources.
Disk::PrintSector - used for debugging; prints the contents of a disk sector.
Disk::ReadRequest - performs a read from the disk file to simulate a disk I/O and schedules an interrupt to simulate I/O completion.
Disk::WriteRequest - writes bytes to the disk file to simulate an I/O and schedules an interrupt to indicate completion.
Disk::HandleInterrupt - disk interrupt handler; used to dispatch to the kernel.
Disk::TimeToSeek - used in computing the length of time to perform an I/O.
Disk::ModuloDiff - determines the rotational delay.
Disk::ComputeLatency - computes the total time for an I/O request.
Disk::UpdateLast - records the position of the last I/O.

3.5 Interrupt

3.5.1 interrupt.h

Defines machine states and interrupt types. Declares Interrupt and

Pending-
Interrupt

classes.

3.5.2 interrupt.cc

Maintains structures to represent interrupts, manages simulated time, and defines interrupt levels.

PendingInterrupt::PendingInterrupt - schedules an interrupt.
Interrupt::Interrupt - creates an empty list of pending interrupts and initializes interrupt state variables.
Interrupt::~Interrupt - destroys all interrupt resources.
Interrupt::ChangeLevel - changes the interrupt level.
Interrupt::SetLevel - initiates a new interrupt level.
Interrupt::Enable - turns interrupts on.
Interrupt::OneTick - simulates one tick of machine time.
Interrupt::YieldOnReturn - sets a flag so that the current process is descheduled upon the return of the current interrupt.
Interrupt::Idle - advances time to the next event.
Interrupt::Halt - shuts down the machine.
Interrupt::Schedule - creates a PendingInterrupt and puts it on the queue.
Interrupt::CheckIfDue - checks the queue to see if an interrupt is scheduled to happen.
Auxiliary Functions:
PrintPending - used for debugging; prints all pending interrupts.
DumpState - dumps interrupt state.

3.5.3 Questions

1. When does time advance in the simulated machine?

2. The machine currently has only two interrupt states (on/off). Describe how you could modify the machine to have many different interrupt levels. As you do later assignments, think about places where having different interrupt levels might be useful.

3. Explain the purpose of having both ChangeLevel() and SetLevel().

4. Why is OneTick() a function of Interrupt instead of Machine?

5. What kind of time accounting is performed?

6. When can interrupt levels actually change?

7. When do context switches happen?

8. How is the clock advanced in CheckIfDue()?

9. Why is DelayedLoad() called in CheckIfDue()?

3.6 Network

3.6.1 network.h

Defines the PacketHeader and Network classes which simulate a physical network.

3.6.2 network.cc

Network::Network - creates the network connection and initializes variables like reliability (from 0-1.0) and addr (integer address of this machine), as well as read/write handlers which resemble those of the console device. Also opens a Unix socket.
Network::~Network - closes the Unix socket.
Network::CheckPktAvail - scheduled at fixed intervals to check if a packet has arrived over the network. Divides the packet into a header and data and then signals the PostOffice.
Network::SendDone - indicates that the user can send another packet.
Network::Send - sends a packet over the network (concatenating the header and data). Then, schedules an interrupt by SendDone().
Network::Receive - reads a packet (if there is one) from the inbox.

3.7 Stats

3.7.1 stats.h

Defines the statistics used to measure Nachos performance. Keeps track of ticks (system, user, total), disk/console reads and writes, page faults, etc.

3.7.2 stats.cc

Routines for printing the current values of all statistics.

Statistics::Statistics - initializes all counters to zero.
Statistics::Print - prints the values of all performance metrics.

3.8 Sysdep

3.8.1 sysdep.h

Defines the system-dependent routines that Nachos requires.

3.8.2 sysdep.cc

Code for system-dependent routines. These are merely wrapper functions which make calls to the Unix library.

3.9 Timer

3.9.1 timer.h

Defines the Timer class.

3.9.2 timer.cc

Simulates a hardware timer by generating CPU interrupts every TimerTicks.

Timer::Timer - stores the function and args to call on each interrupt. Also, stores an indicator of whether interrupts should be at random intervals.
Timer::TimerExpired - schedules the next interrupt, and calls the interrupt handler (since the timer has expired).
Timer::TimeOfNextInterrupt - returns either TimerTicks or a random time interval.

3.9.3 Questions

1. Briefly trace through the generation of a timer interrupt.

2. What command-line flag causes the boolean, doRandom, to be set to TRUE?

3. Why isn't TimerHandler() a member function?

3.10 Translate

3.10.1 translate.h

Defines the TranslationEntry class (used for page table and TLB entries).

3.10.2 translate.cc

Functions that translate virtual addresses to physical ones using either a page table or a TLB.

Machine::ReadMem/WriteMem - reads/writes 1, 2, or 4 bytes of memory at a specific address into/from a buffer. The translation from virtual to physical memory is handled by Translate. Also, checks if an exception was raised by the address translation.
Machine::Translate - converts a virtual address to a physical one. Also performs various error and exception checking (alignment, page fault, bus error, etc.). Uses either the page table or the TLB for translation.

4. C++ Programming Excercise

4.1 Introduction

This is a small excercise designed to give you some experience reading and writing in the subset of C++ that we will use for this class.

4.2 Getting Started

In the directory /c/cs422/as0, you will find the source code for a List class, and a small test program. This implementation of lists was copied from the List class used in the Nachos threads system. The source code for the two versions of List are essentially identical; the version you will use here was only modified to allow it to be compiled without the rest of Nachos.

To try out the program, do the following:

Create a working directory, and copy the source files.
```
$ cd ~/cs422
$ mkdir as0
$ cd as0
$ cp /c/cs422/as0/* .
```
These commands create a working directory, ~/cs422/as0 in which you can work on this assignment, and copy the source files from the class directory.
Type 'make'.
This will build a program, test1, from two C++ source files:

list.cc
implementation of List class
test1.cc
simple test of the List class.
Run 'test1':
You should be able to run the program test1, which should give the following output:
```
$ ./test1
this is a test
$
```

4.3 Your Mission

If you read the source code to test1.cc, you will notice that it first adds some data to the list (a bunch of strings), and then prints the contents of the list by removing each element from the list.

If you study the code that prints the contents of the list, you might notice that the design of this List class is somewhat limited, in that the only way to examine the contents of a list is to remove all the elements from the list! That is, there is no way to simply iterate through the contents of the list without destroying the list in the process.

To remedy this deficiency, we can introduce another class, ListIterator. A ListIterator allows code outside of the List class to iterate over the contents of a list without destroying the list. The ListIterator class is defined in the file listiterator.h, and is used in test2.cc. You should start by reading the code in test2.cc to understand how the ListIterator class is used, and how a ListIterator it is obtained from a List.

In the supplied Makefile, there is already a target for test2. If you type make test2, make will attempt to build test2. But this will elicit compilation errors, because iterators have not been implemented yet.

You should do the following:

Modify list.h and list.cc to allow the user to obtain an instance of ListIterator for a list.
Modify the listiterator.h file to add whatever private member variable(s) that are needed.
Write a new source file, listiterator.cc, which contains your implementation of the ListIterator class.
Modify the Makefile so that typing 'make' will automatically build both test1 and test2. Note, too, that the changes you introduce to get test2 working may inadvertently cause test1 to break, because the rules for test1 do not include the 'listiterator.o' object file.

Note: When you modify existing source files, you must mark changes using the commenting convention described in Assignment Mechanics!

4.4 One Last Thing

The whole point of the previous excercise was to implement a non-destructive iterator class, which would not destroy a list in the process of iterating over the elements.

Joe Dimwit isn't a very clever programmer, and doesn't read too closely. He implemented a version of the ListIterator class that simply returns the result of a call to List::Remove() every time that ListIterator::GetNext() is called.

Unfortunately, Joe Dimwit's version of test2 works, and produces the same output as your version! Why?

You should modify the test case test2.cc in such a way that it will fail with Joe Dimwit's implementation of ListIterator, but will work with your version. If you wish, you may change the output that test2 produces. The description of this test, along with sample output, should be placed in your TESTCASES file.

5. What to turn in

Your submission for this assignment should include the following:

Clear, complete and concise answers to all of the code-walkthrough questions in section 3.
Your source code (and documentation) for section 4. You should include a README file and TESTCASES file with your submission, as described in Assignment Mechanics.

You should submit your answers to section 3 along with a printout of your README for section 4 to the TA's mailbox.

You should submit your sources to this assignment using the standard submit script. The easiest way to do this is to submit all source files (including Makefile, README and TESTCASES) in your working directory. I recommend simply doing a 'make clean' to remove all object files, and then submit'ing all files, as follows:

$ make clean
$ /c/cs422/bin/submit 0 *

Don't forget that no late submissions will be accepted for this assignment!