Lab 3: Multiprogramming in NachOS

CMSC 442
Due: Monday, Nov. 2 by 11:59:59pm

(Note: This lab, and all the other Nachos labs were derived from the original NachOS projects by Tom Anderson at UC
Berkeley. They have been modified to fit our lab environment and changes in the compilation software since NachOS was
originally published.)

Understanding processes and address spaces

The ability to run multiple programs simultaneously is called “multiprogramming”. In the previous
lab, you worked with test cases in which you created multiple threads by hand as part of the operating
system. In this assignment, you will work on code that allows nachos to load and run programs that
have been compiled separately from the operating system.

As in the first assignment, we give you some of the code you need; your job is to complete the system
and enhance it.

The first step is to read and understand the part of the system we have written for you. Our code can
run a single user-level 'C' program at a time. As a test case, we've provided you with a trivial user
program, 'halt'; all halt does is to turn around and ask the operating system to shut the machine down.
This program is located in the test/ folder. The code for the program is in halt.c. To compile it, cd to
that folder and type "make". If it fails to compile, you may need to first run the makefile in the bin/
folder.

Run the program `nachos -x ../test/halt'. As before, trace what happens as the user program gets loaded,
runs, and invokes a system call.

You may find the “road map” to Nachos helpful; it is linked from the course web site. Also, it is OK to
change the definition of the “machine” parameters. For example, the amount of physical memory, if
that helps you design better test cases.

Most of your work on this lab will be done in the userprog/ folder. The files for this assignment are:

progtest.cc – test routines for running user programs.

addrspace.h, addrspace.cc – create an address space in which to run a user program, and load the
program from the disk.

syscall.h – the system call interface: kernel procedures that user programs can invoke.

exception.cc – the handler for system calls and other user-level exceptions, such as page faults. In the
code we supply, only the 'halt' system call is supported.

bitmap.h, bitmap.cc – routines for manipulating bitmaps (this might be useful for keeping track of
physical page frames)

filesys.h, openfile.h (found in the filesys/ directory) – a stub defining the NachOS file system routines.
For this assignment, we have implemented the Nachos file system by directly making the
corresponding calls to the UNIX file system: this is so that you need to debug only one thing at a time.
In the next lab, we'll implement a NachOS file system for real on a simulated disk.

translate.h, translate.cc – translation table routines. In the code we supply, we assume that every virtual
address is the same as its physical address – this restricts us to running one user program at a time. You
will generalize this to allow multiple user programs to be run concurrently. We will not ask you to
implement virtual memory support until the next lab. For now, every page must be in physical
memory.

machine.h, machine.cc – emulates the part of the machine that executes user programs: main memory,
processor registers, etc.

mipssim.cc – emulates the integer instruction set of a MIPS R2/3000 processor.

console.h, console.cc – emulates a terminal device using UNIX files. A terminal is (I) byte oriented,
(ii) incoming bytes can be read and written at the same time, (iii) bytes arrive asynchronously (as a
result of user keystrokes), without being explicitly requested.

So far, all the code you have written for NachOS has been part of the operating system kernel. In a real
operating system, the kernel not only uses its procedures internally, but allows user-level programs to
access some of its routines via “system calls”.

In this assignment we are giving you a simulated CPU that models a real CPU. We cannot just run user
programs as regular UNIX processes, because we want complete control over how many instructions
are executed at a time, how the address spaces work, and how interrupts and exceptions (including
system calls are handled). Instead we use a simulator.

Our simulator can run normal programs compiled from C – see the Makefile in the `test' subdirectory
for an example. The compiled programs must be linked with some special flags, then converted into
Nachos format, using the program “coff2noff” (which we supply). The only caveat is that floating
point operations are not supported.

Step 2. Tasks

Implement each of the following tasks. The first task should be done as a group and you will probably
need to get it working before you can work on the remaining tasks. The next three tasks should be
assigned to a particular member of your group. You can all work on them, but one person in your
group is responsible for THAT task and their grade on the project will largely depend on successful
implementation of that task. I leave it up to you to decide who will take which task – I will not play
referee in your internal group politics.

Task 1 (To be completed by the entire group):

Fix any problems with your Lab 2 implementation. In particular, make sure your Locks and Conditions
work and that Thread::Join and Thread::Finish work properly. I will give you points for fixing
problems in Alarm and Comm, but these aren't used by the rest of the lab, so you should be able to
continue without fixing them unless they cause deadlocks or other major issues.
Task 2 (To be completed by the entire group):

Implement system call and exception handling. You must support ALL of the system calls defined in
syscall.h except for thread fork and yield (which will be implemented as an individual task, below).

To do this, you will need to expand the if statement in userprog/exceptions.cc which currently only
handles the "Halt" system call. You will need to add an "else if" clause for each of the system calls
listed in userprog/syscall.h

Try not to make any changes to syscall.h since it's used both by NachOS and by the programs that will
run in the O.S.

We have provided you an assembly-language routine “syscall” to provide a way of invoking a system
call from a C function (UNIX has something similar – see “man syscall”). You'll need to do parts of
Task 4 before you can implement and test the “exec” and “wait” system calls. The routine
“StartProcess” in progtest.cc may be of use to you in implementing the “exec” system call.

If you read the comments in these files carefully, you will learn two useful things:

1. Arguments to the system calls are passed in registers 4 through 7. Any return value they produce
should be written to register 2. The Machine class has a ReadRegister and a WriteRegister function
you can use for this.

2. Arguments to the system calls are addresses in "user space". That is, they are logical (virtual
memory) addresses, not "physical addresses". This means Nachos can't access them directly -- they
must be translated. To do this, you will need to use the ReadMem and WriteMem functions in
machine/translate.h

For example, if the system call takes a string argument named "str", you might need to do something
like this:

char* kernel_str = new char[256];

This reads one byte at a time from "str" and puts it into kernel_str.

I highly recommend that you create a function to do this translation for you so that you can use it from
ALL of your system calls.

I also recommend that you do the argument processing in exceptions.cc, but handle the rest of the
implementation of each system call in a dedicated function in another file (perhaps named syscall.cc).

Note that you need to “bullet-proof” the NachOS kernel from user program errors – there should
be nothing a user program can do to crash the operating system (with the exception of explicitly
asking the system to halt).
The calls to thread fork and yield are an individual task (Task 7) and require significant changes to the
Thread class.

Probably the easiest systems calls ot implement are Yield and the file handling ones: Create, Open,
Close, Read, and Write.

To implement Create, you should use the "Create" function of the FileSystem class in filesys/filesys.h.

To implement Open, you may use the "Open" function of the FileSystem class.

The Open function returns an OpenFile pointer. You will need to store that pointer in some kind of per-
process data structure (probably in your Addrspace object) and return a unique integer id that can be
used later to retrieve the pointer. The Read and Write functions will use that id number to access the
pointer and call the Read and Write functions in filesys/openfile.h to get input or produce output to a
file.

There is no "Close" function in the OpenFile class, but the destructor performs most of these tasks.
Your close system call should delete the corresponding OpenFile object and remove it from the file
table data structure.

Task 3 (To be completed by the entire group):

In order to test your code, you need to be able to read and write to/from the console. Add if-statements
to your Read and Write functions so that if they are passed the "ConsoleInput" or "ConsoleOutput" ids,
respectively) they will read or write from/to the console instead of from a file.

NachOS provides a Console class which will allow you to read or write a single character at a time
from the console, but access to this console device is currently "Asynchronous", which means that if
two threads print a line, that line can be interrupted, causing a race condition. Also, access to the
Console is a producer/consumer system -- we don't want to read from the console buffer until data is
actually there (otherwise, we'll get garbage) and we don't want to write to the console while the
previous character is still being output (otherwise, we might clobber it and not print everything).

To support Console Read and Write, implement a “SynchConsole” class, that provides the abstraction
of synchronous access to the console. Then create a global SynchConsole object in threads/system.cc
which your system calls can use. The file “progtest.cc” has the beginnings of a “SynchConsole”
implementation for you.

The remaining calls (Exit, Join, Fork, Exec, Yield) mostly involve process control. To implement them
you will need to create a data structure for mapping "Process IDs" to threads and give your AddrSpace
object (which is created for each thread) some way to keep track of its own Process ID. You also need
to track the "exit status" of each thread. This is an integer value which is set by the Exit system call.

When a process calls Exit, you should look up its process id and store its exit stats in the data structure.

When a process calls Join, it will pass in a process id. You should look up that process id to obtain a
thread pointer, use thread->Join to wait until that thread has finished and then return the exit status of
the joined thread.
When a process calls Exec, you should load a program from the disk into memory. This is very similar
to the "StartProcess" function in userprog/progtest.cc.

When a process calls Fork, you must allocate a new Address Space for it and then call Thread::Fork.

The Yield system call simply causes the current thread to yield the CPU.

After processing a system call, your code in exception.cc must also advance the program counter,
which is stored in the PCReg register.

Task 4 (To be implemented by the entire group):

Implement multiprogramming with time-slicing. The code we have given you is restricted to running
one user program at a time. You will need to:

(a) come up with a way of allocating physical memory frames so that multiple programs can be loaded
into memory at once (see bitmap.h),

(b) provide a way of copying data to/from the kernel from/to the user's virtual address space (now that
the addresses the user program sees are not the same as the ones the kernel sees), and

(c) use timer interrupts to force threads to yield after a certain number of ticks. Note that scheduler.cc
saves and restores user machine state on context switches.

To do this, you should use the ReadMem and WriteMem functions in machine/translate.{h,cc}.

Most of the code for this will probably go in your StartProcess function or in the Addrspace
constructor.

Task 5 (To be implemented by a single member of the group):

The “exec” system call does not provide any way for the user program to pass parameters or arguments
to the newly created address space. UNIX does allow this, for instance, to pass in command line
arguments to the new address space. Implement this feature! (Hint: there are two ways to do this. One
is to copy the arguments onto the bottom of the user address space (the stack) and then pass a pointer to
the arguments as a parameter to main, by using r4 to hold the pointer. This is how UNIX does this.

The other approach is to add a new system call, which every address space calls as the first thing in
main, that fetches the arguments to the new program.)

Task 6 (To be implemented by a single member of the group):

Nachos provides a "shell" program that provides you with a simple command prompt, but very little
other functionality. Implement Nachos versions of the `cat` and `cp` commands in the "test" folder.
Task 7 (To be implemented by a single member of the group):
Implement multi-threaded user programs. Implement the thread fork and yield system calls, to allow a
user program to fork a thread to call a routine in the same address space, and then ping-pong between
threads. (Hint: you will need to change the kernel to allocate memory in the user address space for
each thread stack.)

Step 3. Documentation

In your base nachos directory, I would like you to create a file named LAB3-README.TXT that
contains:

Your group submit name

Your description should be detailed, explaining which files you changed and which task they
implemented. If you were unable to get part of a task working, you should be explicit about that and
explain the problem in detail.

Submitting

As usual, create a tarball of the nachos directory and submit it through the course web site.