CS460 Lab #4 (JOS #1)

Jim Plank, Rich Wolski

JOS -- An operating system for a simulated MIPS machine

The labwork in the class is going to focus on writing JOS -- an operating system for a simulated MIPS machine. Obviously we don't have the machinery to let you write a real OS for a real machine, so we're doing the next best thing: we will be writing the operating system for a simulated machine.

One of the problems with this project is that students often get confused concerning which parts of the code are the simulated machine, and which parts are the OS. Students will try to either change or circumnavigate the simulator to fix problems instead of accepting the simulator as a given and working around it in the OS. We will try to keep this from being a problem. To do so, you should try to adopt the following model. The simulator calls the code you write in exactly three situations: when the machine starts running (initialization time), when a user program running in the simulator causes an exception (system call, page fault, etc.) and when a device interrupts. Each time this happens, your code can see the user program's register set and main memory, as well as any data structures you have defined in your code. So your job is to

Initialize the system.
Respond to explicit exceptions (software interrupts, system calls) raised by the program.
Respond to device interrupts.

And that's it. Nothing more. We'll talk about the best way to organize your code for these three cases as we go along but you should try to keep in mind what the simulator is doing and what the OS (you) is (are) doing.

Basically, things will work as follows. There are two object files for the simulator:

main_lab1.o
libsim.a

There is also a header file /home/cs560/labs/lab4/simulator.h which contains constants and simulator procedure definitions that you will need in your JOS code. The TA's lab 4 page will tell you where to find these files, and how to compile your executable.

When you run the executable, your operating system gains control. This happens in a subroutine called JOS() (no arguments), that you have to write. This state of affairs is not so different from an actual operating system. If you were implementing JOS for an actual machine, you'd need to define an initial entry point for the hardware to "jump through" at start-up. In fact, the "boot up" process is when the hardware loads and executes a pre-defined routine that it finds in a place the hardware specifies (e.g. the boot record). You will link your code to the two object files, and an executable file will be created. When you run the executable, it starts the simulator. Upon instantiation, the simulator calls JOS() and your operating system gains control. From then on, the interaction between the operating system and the simulator is acheived through well defined communication points. The simulator program will call you when the program requires service (which it tells you through an exception) or when a device requires service (through an interrupt). You, however, do not return once called. Instead, you have two ways to return to the simulator after you are finished doing that thing you do. You can call run_user_code() if you want to run (or go back to running) a user program or noop() if you want to "idle" the machine. All exceptions call exceptionHandler() passing in an exception type as an argument, and interruptHandler()) which gets an interrupt type as an argument.

Basically, a computer is a collection of resources (memory, CPU, screen, keyboard, etc) that interact in a specific way. It is the job of the operating system to manage these resources in such a way that enables the user make use of the resources with paradigms that are familiar to him/her (like writing programs and executing them). Typically, each resource exports a low-level hardware interface that consists of control registers, data transfer locations, and a set of interrupt response codes. The resources that the simulator provides are as follows:

A CPU with NumTotalRegs registers that uses the MIPS instruction set (although it doesn't allow floating-point operations). The operating system interacts with the CPU as follows. Obviously while the operating system is executing, the CPU cannot be used to run user programs. This is because the CPU is busy running the operating system. That is, the CPU executes in one of two modes: user mode, and "supervisor" (operating system) mode.
The operating system makes the procedure call run_user_code(int registers[NumTotalRegs]) to get back to running user code. This procedure call tells the simulator to load the specified set of registers into the CPU registers and set the execution mode to user mode. Thus constitutes an exit from the OS. By setting the PC to point to a user address and switching modes to user-mode, the next instruction executed is in the user program. The CPU will then run (starting with the instruction in the PC register) until an exception or interrupt occurs, which switches it back into supervisor mode.
Exceptions and interrupts put the operating system back in control of the CPU in the procedures exceptionHandler (ExceptionType which) and interruptHandler (IntType which) respectively. The argument which specifies the type of exception or interrupt (e.g. system call, arithmetic error, timer interrupt, console ready, etc). The registers are saved by the simulator at the time of the interrupt. Their contents may be examined using the examine_registers(int buf[NumTotalRegs]) procedure. You may not return from exceptionHandler() or interruptHandler() to give CPU control back to the user program that had it when the interrupt occurred. Instead, you use run_user_code() with the correct set of registers (or you call noop() when you want to idle the machine).
Finally, there is a simulator procedure called noop() which tells the simulator to make the CPU do nothing until the next interrupt occurs. In the event that no user code can be run when an interrupt is finished, noop() should be used so JOS can do nothing until the next interrupt occurs. When the interrupt does occur, the state of the registers is meaningless.
A memory consisting of MemorySize bytes for user programs. (This is a megabyte). The operating system can access this memory starting with the external variable main_memory. User programs access this memory starting with address zero. This is very unsophisticated and will be made more realistic as the semester goes on, but for the first lab, it will suffice.
For the first few labs, you will load user programs into memory using the subroutine load_user_program(char *filename). Note that this does not execute the program -- it simply loads it into memory.
Big Endian / Little Endian

There is an unfortunate quirk between the SPARC's and the MIPs -- in the inimitable words of Professor Wolski, ``they are endians from different tribes.'' In both machines, integers and pointers are 4 bytes each, however their byte order is reversed. Thus, the integer 1 (0x00000001 -- big endian format) on the SPARC is the integer 16777216 (i.e. 0x01000000 -- little endian format) on the MIPS. Only integer, pointer, and short types are reversed -- not single byte types like char. You are, undoubtedly asking "why" with respect to big or little endians (big is typically more intuitive for people). The answer is steeped in the lore and hardware design machismo exhibited by early pioneers on the mini- and micro- computer frontiers. Worse, it turns out that the MIPS can run in either big or little endian mode. Why the implementers chose little endian mode for their simulator is something we'll never know -- we simply have to accept it as a given.
Be that as it may, what looks like the integer 1 in JOS will look like 16777216 to the user running his MIPs code. The procedures examine_registers() and run_user_code() actually perform conversion from one to another, so you don't have to worry about byte-swapping in registers. However, in memory you do have to worry about this. So when you are writing a value into the user program's memory that will be accessed when the program runs, and that value is an integer, pointer, or short, you need to convert it to little-endian format.
In other words, if you are in JOS and you set 4 bytes starting with memory location main_memory+8 to be the integer 1, then if the user code tries to read an integer (or pointer) in memory location 8, it will read the value 16777216. Thus, you have to perfrom byte swapping when you write integers and pointers into memory from JOS that is going to be read by user code. One example of this is setting argc -- when you set argc in JOS, you'll have to byte-swap it so that the user code reads the correct value. The following procedures perform byte-swapping (convert from big to little endian and back):
- int WordToMachine(int i) returns a byte-swapped integer (4 bytes) i.
- int ShortToMachine(short i) returns a byte-swapped short (2 bytes) i.
A console. In all computers, the screen and keyboard are separate devices that interact with the CPU through interrupts. In JOS, there is a console that performs these functions. When JOS starts up, it waits to attach to a console. If you start JOS with the arguments ``-c num'' then it waits to attach to a console which you will start in another window with ``jconsole num.'' (jconsole may currently be found in the directory /home/cs560/bin/sparc-sun-solaris2.7, so it only works under Solaris -- maybe this will change soon...) Num must be a number between 5000 and 30000 (if you care, it's a socket port number). Then all console I/O will come from and go to the jconsole program. This is nice way to structure things because user I/O goes through the console, and you can print out debugging messages on JOS's standard output.
If you don't specify a jconsole program with -c, then JOS uses its own standard input/output as the console. This makes life easier if you are using a windowless terminal. However, if you are in an Xwindows environment, you should use jconsole because it will help clarify things.
JOS communicates with the console through two procedures and two interrupts.
- The procedure console_write(char c), which asks the console to write the character c to the console. When it is done, it will cause an interrupt of the type ConsoleWriteInt. This interaction is typical of "synchronous" devices -- the OS makes a request to the device (to write a character in this case) and then waits for an interrupt telling it that the device has completed the operation. I.e., the console is ready for another character to be written to it after the interrupt hits. After calling console_write(), you may not call it again until the ConsoleWriteInt signals that the console is ready to write another character.
- When there is a character to read on the console, an interrupt of the type ConsoleReadInt is generated. After this interrupt occurs, you may call console_read() to read this character. When another character is ready to be read, ConsoleReadInt will be generated again. If you do not call console_read() between two ConsoleReadInt interrupts, the first character will be lost. We term this interaction as "fielding an unsolicited interrupt." Console_read() returns -1 when the user types CNTL-D.
To try to make for a realistic interface, the console is able to read/write a character around every 100 user operations.
There is no timer interrupt in the simulator for the first lab.

User Programs for JOS

User programs for JOS must be compiled in such a way that the simulator may run them. This is done using a special C compiler. You may use the application programs that are in the directory /home/cs560/test_execs, which are compiled into executable files in the same directory.

Note that the protection of these executables is not r-x. That is because these are not executable on our machines. They are only executable by the simulator of JOS -- in other words, you can only execute them by loading them into JOS.

Loading User Programs in JOS

The basic steps for loading a user program in JOS is:

Load the program's executable file into memory.
Zero all the registers except for the register StackReg, which should be set to at least 40 bytes from the highest memory address for the program.
Call run_user_code() with these registers.

When you start initializing the stack, you need to follow a few rules. The stack will grow toward lower memory addresses. Thus, when you want to initialize the stack with certain values (like argv and envp), you should put those values in memory locations at the top end of the user's memory, and then set StackReg to be just below these memory locations. As a convention, the user program will look for argc in main_memory[StackReg+12], argv in main_memory[StackReg+16], and envp in main_memory[StackReg+20]. It will not make use of any memory values greater than main_memory[StackReg] for allocating call frames on the stack.

There is a quirk of the simulator that causes bizarre behavior if you use the top 8 bytes of memory. Thus, do not use them. When you start stuffing stuff into the stack, do not stuff anything into these eight bytes.

Alignment

As with all computers, the MIPs simulator assumes that all 4-byte quantities like integers and pointers are aligned. This will be an issue when you are setting up argc and argv.

The Assignment

Look at /home/cs560/labs/lab4/start/jos.c. This is a rudimentary JOS implementation that loads the file a.out into user memory and executes it. The a.out program must be very restricted -- the only external procedure that it may call is _exit(). It does not have to call _exit() however, because _exit() is called automatically whenever main() returns.

Copy /home/cs560/labs/lab4/start/* into your own area, and compile it so that you can run it. Test it on some a.out files that you copy from the test_execs directory (try halt and cpu).

Now, you are to make the following changes to jos.c:

Implement restricted versions of the system calls read() and write(). The syntax of read() and write() are exactly like Unix's read() and write(). Read their man pages if you are not familiar with read() and write() already. Now, implement read() so that it reads from the console whenever the first argument is zero, and implement write() so that it writes to the console whenever the first argument is one or two. Any other first argument should return with an error. The way that the system call driver is written in the simulator is that if you return a negative value to a system call, it will return -1 to the user program, and set the errno value to be the returned value times -1. This is how you can return different errors from system calls. See /usr/include/sys/errno.h for standard errno's.
Remember that if the user specifies an address of x, that is not address x in JOS. It is the user's address x.
An important fact of OS design is that users can do incorrect things, but the operating system can't. Thus, JOS should be ready for any arguments to read() and write(), and if the arguments are incorrect, it must deal with that gracefully (i.e. return with an error) and not abort or dump core or leave JOS in such a state that future system calls will break.
Change JOS further so that it will call a given file with a given set of arguments. These can be compiled into the program, but in an easy-to-change place (i.e. as global variables in jos.c). Now, not only should JOS load the file and execute it, but it should set up memory so that the program sees the arguments as argc and argv.

You do not need to hand this assignment in two different parts --- simply hand in a new version of JOS with all of these changes implemented.

Structuring your code

You are going to want to use the kthreads library to structure your code. There are two files whose purpose is to help you with this:

First is the file: WHAT_DR_PLANK_DID. This is a step-by-step guide to doing this lab, and getting all of the structural details correct. In the words of Professor Wolski: ``It is not required that you do things this way, but it is in your best interest to follow this set of guidelines -- it shows the design and development philosophy used by an expert programmer -- it will relieve you of a lot of design stress, and will position you well for the future labs.''
Second is the file ``Heloise's hints,'' which contains Professor Wolski's advice concerning this lab. You'll note that this gives you the advice of two expert programmers, so take advantage of this information.

The code for step 5 of WHAT_DR_PLANK_DID is in the directory /home/cs560/labs/lab4/Step5. When you get to step 5, it will be a good idea to look at my code, and perhaps copy it and start from there. (More priceless advice from Professor Wolski: ``For those of you tempted to begin your enjoyment of Lab #4 by redefining the counting numbers to start with 5 and simply starting here, realize that you may be asked to expound upon steps 1 through 4 at some future social gathering. It would be gauche not to be prepared, would it not?'')

Appendix -- Various Things

Simulator Subtleties

The simulator is built so that when you do something incorrect it will quit. However, some of the error messages will not be very helpful. For example, you are not allowed to return from an interrupt or exception and let the simulator pick up where it left off. An error message will be printed if you try to do so. Instead of returning, you must call run_user_code() or noop(). The former will cause the machine to switch to user mode, load the registers, and begin executing code. The noop() function will put the machine into idle mode and wait for an interrupt to occur. Another example of something else you are not allowed to do is write a character to the console while it is already trying to write one out (that is before the interrupt occurs). For example the following code will not work:

        console_write('H');
        console_write('i');

It will stop the program with the following message:

        Assertion failed: line 107, file "machine/console.c"
        Abort

Hopefully the file name will clue you in on where you made an error.

The end of the user's address space

Do not use the last 8 bytes of the user's address space. Start the stack at least 8 bytes from the limit. I don't know why -- just do it.

Debug Flags

There are various flags that you can use when invoking jos. You can list them out by executing jos help. The only one of these that might be of any help is the -d e option. This causes a debug message to be printed out when an exception or interrupt occurs.

Miscellaneous

Don't copy over any of the executables or object files. Rather just keep soft links to them. In case bugs are found, they can be fixed and you will always be referencing the latest versions of the code.