15-410 Project 1: Student Teaches Teaching Typing

Table of Contents

• Project Overview
• Goals
• Technical Disclaimer
• Header Files
• Important Dates
• Welcome to x86 Kernel Programming
• Kernel Programming: Always Assuming the Worst
• Privilege Levels
• Segmentation
• Communicating with Devices
• Hardware Interrupts
• Software Interrupts and Exceptions
• Configuring Interrupts
• Writing an Interrupt Handler
• Console Device Driver Specification
• Writing a Character to the Console
• Communicating with the CRTC
• Console Device Driver Interface
• Timer Device Driver Specification
• Configuring the Timer
• Timer Device Driver Interface
• Keyboard Device Driver Specification
• Interacting with the Keyboard
• Keyboard Device Driver Interface
• Skeleton Kernel
• Provided C Functions
• Testing
• Tying it All Together
• Documenting
• Other Important Notes
• Testing and Debugging with Simics
• Getting Started with Simics
• The BIOS and Bootloader
• A Note on "Triple Faults"
• Grading Makefile and Dual Images
• Hand-in Instructions

The first is the console device driver. The console device driver is responsible for taking characters and printing them on the screen. Without it, it would be rather difficult to obtain any feedback as to what is going on in your operating system or user applications.

The second device driver you will write is the keyboard device driver. Whenever the user presses a key, the keyboard device driver needs to find out what key it is, whether it was pushed or released, and then make that information available to the operating system. An important aspect of the keyboard device driver is that it is interrupt driven. We will take a closer look at what this means later.

The third "device driver" is the timer handler. While we do not often think of the on board PC timer as a device, it generates interrupts just like the keyboard. The timer is a critical device that is used in context switching between processes.

It is not possible to test these device drivers on their own. In order to develop and test them, you will be provided with a skeleton kernel. The kernel performs some very basic machine initialization such as transitioning to protected mode. Once this initialization is complete, it transfers control to the main() function, which is where you can put your initialization and test routines. There is no virtual memory and no file system.

Once you have implemented the three device drivers, you will use the three of them to implement a simple typing tutor program, which will determine your average typing speed in words-per-minute (WPM). A detailed explanation of the desired behavior is presented later in this handout.

Goals

1. Writing clean code in C. Many people like the C programming language because it gives the programmer a lot of freedom (pointers, casting, etc). It is very easy to hang yourself with this rope. Developing (and sticking with) a consistent system of variable definitions, commenting, and separation of functionality is essential.
   People have asked about using C++ in this class. This is probably much harder than you think, since you would need to begin by implementing your own thread-safe (or, at least, interrupt-aware) versions of new and delete. In addition, you would probably find yourself implementing other pieces of C++ runtime code; this could turn into quite a hobby. As a result, we cannot help you with C++ and will not be able to provide you with extra time to complete the assignments.
   If you really would like to use an alternative language, you may do so, but at your own risk. We will not answer any questions regarding other languages or integrating the support code with another language. If you use another language and do not complete the project, you will not be given any sympathy because you used something other than C.
2. Writing psuedocode. For systems programming, it is very important to think out crucial data structures and algorithms ahead of time since they become important primitives for the rest of the system.
3. Commenting. Though you will not be working with a partner for the first project, you will be on all subsequent projects. It is important to include comments so someone else looking at or maintaining your code can quickly understand what your code is doing without having to look at its internals. We will be using a system called doxygen, which creates documents similar to javadoc.
4. Debugging/testing operating system code. We will be using Simics, an instruction set simulator with a built-in debugger to debug and test; it is similar to gdb, but has some important differences and will take some getting used to.
5. Using common development tools (gcc, ld).
6. Understanding device drivers: their role in the system, and their requirements.
7. Communicating with the TAs using various channels of communication (zephyr, bulletin board, , Q&A archive, course web page, office hours).

The goal of this project set is certainly not to teach the idiosyncrasies of the x86 architecture (or Intel's documentation). That said, it will be necessary to become accustomed to the x86 way of doing things, and the Intel nomenclature, for the purposes of completing this project set. Just keep in mind that the x86 way of doing things is not the only way of doing things. It is the price to be paid for learning the principles of operating systems on a real world system instead of a simulated architecture.

Header Files

*(char*)0x0 = 0x1badd00d;

Wild pointer accesses are much more dangerous in kernel mode because valuable kernel data structures are not protected by the user mode/kernel mode protection schemes of the processor (discussed here shortly). Dereferencing and writing to a bad pointer like this within the kernel can overwrite crucial kernel data.

Privilege Levels

The processor checks the privilege level (PL) in a number of circumstances, such as when an attempt is made to execute a privileged instruction. These are instructions that modify control registers or change how the processor is running (a list of these instructions can be found in section 4.9 of intel-sys.pdf). These are instructions we would want only the kernel to be able to execute, so they are only allowed while the processor is running in lower privilege levels (such as 0). If you try to execute such instructions at other privilege levels, a fault occurs. Fun thought experiment: If privileged instructions cause a fault, how does one then change privilege levels?.

Segmentation

A segment is simply a portion of the address space. Once defined, we can associate important characteristics with the segment, like the priority level required to access the segment or whether it contains code or data. A segment does not need to represent memory that actually exists - for example, we could define a segment ranging from 0 to 4GB (the entire 32 bit address space), even though we might only have 128MB of physical memory.

Because your kernels are going to be complicated enough as it is, we will steer clear of segmentation by using only four segments. These four segments all span the entire 32 bit address space (overlapping each other completely). Two of them require privilege level 0 to be accessed, and two of them only require privilege level 3. Of each privilege level pair, one segment represents code and the other data. We have set up these segments for you. In this project, we have no user processes, so the only segments that will be used are those requiring PL 0 to be accessed. To refer to these segments when configuring kernel data structures (like IDT entries), use the #defines in lib/inc/x86/seg.h (KERNEL_CS_SEGSEL and KERNEL_DS_SEGSEL for this project). These numbers are segment selectors, which are simply indices into another processor data structure, the global descriptor table (GDT). The GDT is the place we have defined our segments. You do not have to reconfigure it or know its format, however.

Please refer to our segmentation document for a more detail explanation of segmentation. Do not worry if parts of it do not make sense at the moment as they will become clearer later in the course.

Communicating with Devices

Most devices in the x86 architecture are accessed through I/O ports. These ports are controlled by special system hardware that has access to the data, address, and control lines on the processor. By using special hardware instructions to read and write from these ports, we can use I/O ports without infringing upon the normal address space of the kernel or user applications. This is because these special instructions tell the hardware that this memory reference is actually an I/O port, not a traditional memory location. For more information on I/O ports, consult chapter 10 of intel-arch.pdf. Both the timer and the keyboard use I/O ports. For convenience, an assortment of C wrapper functions are provided to you to save you from having to break into assembly language to read or write I/O ports. These are located in lib/inc/x86/pio.h. The various in functions read from an I/O port while the out functions write to an I/O port. The letter after the name indicates the size of the data being sent (b - byte, w - word/short, l - long/int). You should only need to use outb and inb.

There are also some devices which are accessed by reading and writing special addresses in traditional memory (memory-mapped I/O). This part of memory is part of the regular address space and therefore needs to be carefully managed. The console uses memory-mapped I/O (along with some I/O ports for things like cursor position).

Hardware Interrupts

When a device wants to raise a hardware interrupt, it communicates this desire to one of two programmable interrupt controllers (PICs) by asserting some control signals on interrupt request lines. The PICs are responsible for serializing the interrupts (taking possibly simultaneous interrupts and ordering them), and then communicating the interrupts to the processor through special control lines. The PICs tell the processor that a hardware interrupt has occurred, as well as which request line the interrupt occurred on so the processor knows how to handle the interrupt. There are some PC conventions describing what devices are associated with what interrupt request lines.

PIC 1 0 Timer 1 Keyboard 2 Second PIC 3 COM2 4 COM1 5 LPT2 6 Floppy Disk 7 LPT1

PIC 2 8 Real Time Clock 9 General I/O 10 General I/O 11 General I/O 12 General I/O 13 Coprocessor 14 IDE Bus 15 IDE Bus

The PIC chip used in old IBM compatibles only had 8 interrupt request (IRQ) lines. This proved to be limiting, so a second PIC was daisy chained off of the first one. When an interrupt is triggered on the second PIC, it in turn triggers an interrupt on the first PIC (on IRQ 2). The interrupt is then communicated to the processor.

Once the processor receives an interrupt from the PIC, it needs to know how to respond. The processor reads a data structure called the interrupt descriptor table (IDT). There is a descriptor in this table for each interrupt. A descriptor contains information about how to resolve the interrupt, most importantly where the interrupt handler is located. The interrupt handler is a piece of code that the author of the device driver writes that gets executed when that device issues an interrupt. The IDT also stores the privilege level that is required to call the handler (DPL) and the segment to use while running the handler (which determines the privilege level to run under). Once the processor locates the appropriate entry in the IDT, it saves some information about what it was doing before the interrupt occurred, then starts executing at the address of the interrupt handler. Once the interrupt handler has run to completion, the processor uses the saved information to resume its previous task. Note that IRQ numbers do not necessarily correspond to matching indices into the IDT. The PICs have the ability to map their IRQ lines to any entry in the IDT. You will be given information on which IDT entries correspond to interrupts pertaining to your projects. For Project 1, the IDT entries will correspond to the timer interrupt and the keyboard interrupt. These IDT entries are further discussed in their respective sections.

Interrupt handlers typically need to execute as quickly as possible so that the processor is free to accept future interrupts. When an interrupt is sent by the PIC, the PIC will not send another interrupt from that same source until it gets acknowledged through an I/O port. This is because interrupt handlers usually manipulate critical data structures and would not withstand being interrupted by new invocations of themselves (i.e. they are not reentrant). In particular, an interrupt handler must never block on anything. Most interrupt handlers simply make a note of work that must be done as a result of the interrupt, clear the interrupt, then terminate, leaving the work to be done at a more convenient time. Note that it may be possible for one interrupt handler to be interrupted by a different interrupt handler, so long as they do not share data structures.

Software Interrupts and Exceptions

In addition to hardware and software interrupt handlers, the IDT also contains information about exception handlers. Exceptions are conditions in the processor that are usually unintended and need to be addressed. Page faults, divide-by-zero, and segmentation faults are all types of exceptions. We will cover both software interrupts and exceptions in more detail later, especially in Project 3. For now, we just need to look at how to install an interrupt handler.

Configuring Interrupts

An entry in the IDT can be one of three different types: a task gate, an interrupt gate, or a trap gate (a "gate" is just a descriptor that contains information about a transition to a different piece of code - think "gate to new procedure"). We will not be using task gates because they make use of the processor's hardware task switching functionality (which we also will not use for reasons that will become clear later in the course). The difference between an interrupt gate and a trap gate is that when the processor accesses an interrupt handler through an interrupt gate, it disables all further interrupts by clearing a flag in one of the processor's registers. Handling interrupts through trap gates does not do this. For the interrupts in this project, we will be using trap gates, because the timer and keyboard interrupts do not interfere with each other and therefore we need not disable interrupts (aside from interrupts from the same source, which is done automatically) when executing their handlers. Also, it is generally not a good idea to have interrupts disabled for long periods of time.

The format of the trap gate is given on page 151 of intel-sys.pdf. Note that regardless of the type of the gate, the descriptor is 64 bits long. You can use this fact to index into the IDT without knowing the type of the other gates in the table. To get the base address of the IDT, we use an instruction called sidt. We have provided a C wrapper function for this instruction so you do not have to break into assembly. This is supplied in lib/inc/interrupts.h.

Initially, the PICs are programmed so that they call entries in the IDT that conflict with processor exceptions. The pic_init function in lib/inc/x86/pic.h remaps the PICs to higher IDT entries. We have already taken care of calling this for you in kernel.c

Some of the fields in the trap gate are self-explanatory, however others are not so they are summarized here:

DPL	The privilege level required to call the handler. If it is set to 3, then user processes can call the handler directly. For hardware interrupts (like the keyboard and timer), it should be set to 0.
Offset	The offset into the segment of the interrupt handler. Since all of our segments take up the whole address space, this is simply the address of your function handler. This can be obtained in C by typing the name of the function (without any parenthesis or arguments).
Present (P)	Must be set to 1 for a working interrupt handler.
Segment Selector	The segment selector for the target code segment. This defines the privilege level the handler will run at. The interrupt handler is going to be executed at PL0 and it is code, so this needs to be set to KERNEL_CS_SEGSEL (defined in lib/inc/x86/seg.h).
D	Size of the gate. All our gates are 32 bits (D = 1).

Writing an Interrupt Handler

This information is indeed enough to resume executing whatever code was running when the interrupt first arrived. However, in order to service the interrupt we need to execute some code; this code will clobber the values in the general purpose registers. When we resume executing normal code, that code will expect to see the same values in the register, as if no interrupt had ever occurred. So the first thing an interrupt handler must do is save all the general purpose registers, plus %ebp. We need not save the stack pointer because if there is no stack change (as is the case in this project since we have no user processes), the stack pointer will be correct once we pop off all of our interrupt-related information. If there is a stack change (as there will be in Project 3 when you do have user processes), the interrupt saves the stack pointer for us. So, to recap, the registers you need to save are %eax, %ebx, %ecx, %edx, %esi, %edi, and %ebp.

The easiest way to save these registers is to just save them on the stack. This is easily done with the pusha and popa instructions (more information on these can be found on pages 624 and 576 of intel-isr.pdf). To be sure that you save the registers before anything else occurs, you should at least write a wrapper for your interrupt handler in assembly. All you must do in assembly is save the registers, call your C handler (try the call instruction), then restore the registers. To return from an interrupt, use the iret instruction. It uses the information initially saved on the stack (EFLAGS, code segment, instruction pointer) by the interrupt to return to the code executing when the interrupt occurred.

A final note about writing assembly. Comment your assembly profusely. One comment per instruction is not a bad rule of thumb. Keep your assembly in separate files, and to export a symbol (like asm_timer_wrapper) so you can refer to it elsewhere, use the directive .globl, like this:

.globl asm_timer_wrapper

For those of you who have not written assembly before, here is the expected form:

.globl function_name
function_name:
     assembly_instruction1 #comment
     assembly_instruction2 #comment
     assembly_instruction3 #comment
     ...

Assembly files normally have a .s or .S extension. The two extensions have different meanings to gcc; gcc will run the preprocessor on assembly files named with .S, while it passes files ending in .s to the assembler unaltered. Since you'll probably want to use #defines and other preprocessor statements within your assembly code, we strongly suggest naming your assembly with the .S extension. Note that the C preprocessor will swallow C-style comments in your .S files so they won't annnoy the assembler. To use your assembly functions elsewhere, you'll also want to make a header file (.h) for it. This .h file is the same as any other. You should document your assembly functions using doxygen comments attached to function declarations in the headers.

Console Device Driver Specification

Writing a character to the console is as simple as writing a byte pair to video memory. Assuming the top left corner is (0,0), to write the character 'M' on the 2nd character of the 1st line, you would do something like this:

*(char *)(CONSOLE_MEM_BASE + 2*(CONSOLE_WIDTH + 2)) = 'M';
*(char *)(CONSOLE_MEM_BASE + 2*(CONSOLE_WIDTH + 2) + 1) = console_color;

where CONSOLE_MEM_BASE is the start location of the console memory, CONSOLE_WIDTH is the width of the console in characters (defined to be 80), and console_color is a variable containing the current foreground and background color specification of your choice.

When the bare-bones kernel initializes the hardware, it will do the dirty work of setting up the console in 80x25 format. However, you will also need to reposition or hide the hardware cursor. The hardware cursor is controlled by the Cathode Ray Tube Controller (CRTC), an important device on the video card. Communication with the CRTC is accomplished with a special pair of registers. Accessing these registers is a little different from writing to console memory as they use the I/O ports (discussed earlier).

Communicating with the CRTC

int putbyte( char ch );
Description: Prints character ch at the current location of the cursor. If the character is a newline ('\n'), the cursor should be moved to the first column of the next line (scrolling if necessary). If the character is a carriage return ('\r'), the cursor should be immediately reset to the beginning of the current line, causing any future output to overwrite any existing output on the line. If backsapce ('\b') is encountered, the previous character should be erased (write a space over it and move the cursor back one column). It is up to you how you want to handle a backspace occurring at the beginning of a line.
Returns: The input character.

void putbytes(const char* s, int len);
Description: Prints the string s, starting at the current location of the cursor. If the string is longer than the current line, the string should fill up the current line and then continue on the next line. If the string exceeds available space on the entire console, the screen should scroll up one line, and then the string should continue on the new line. If '\n', '\r', and '\b' are encountered within the string, they should be handled as per putbyte. If len is not a positive integer or s is null, the function has no effect. When you scroll the screen, you are not required to remember characters which are "pushed off" of the screen.
const char* s: The string to be printed.
int len: The length of the string s.
Returns: Void.

void draw_char(int row, int col, int ch, int color);
Description: Prints character ch with the specified color at position (row, col). If any argument is invalid, the function has no effect.
int row: The row in which to display the character.
int col: The column in which to display the character.
int ch: The character to display.
int color: The color to use to display the character.
Returns: Void.

char get_char(int row, int col);
Description: Returns the character displayed at position (row, col).
int row: Row of the character.
int col: Column of the character.
Returns: The character at (row, col)

void set_term_color(int color);
Description: Changes the foreground and background color of future characters printed on the console. If the color code is invalid, the function has no effect.
int color: The new color code.
Returns: Void.

void get_term_color(int* color);
Description: Writes the current foreground and background color of characters printed on the console into the argument color.
int* color: The address to which the current color information will be written.
Returns: Void.

void set_cursor(int row, int col);
Description: Sets the position of the cursor to the position (row, col). Subsequent calls to putbyte or putbytes should cause the console output to begin at the new position. If the cursor is currently hidden, a call to set_cursor() must not show the cursor.
int row: The new row for the cursor.
int col: The new column for the cursor.
Returns: Void.

void get_cursor(int* row, int* col);
Description: Writes the current position of the cursor into the arguments row and col.
int* row: The address to which the current cursor row will be written.
int* col: The address to which the current cursor column will be written.
Returns: Void.

void hide_cursor();
Description: Causes the cursor to become invisible, without changing its location. Subsequent calls to putbyte or putbytes must not cause the cursor to become visible again.
Returns: Void.

void show_cursor();
Description: Shows the cursor. If the cursor is already shown, the function has no effect.
Returns: Void.

void clear_console();
Description: Clears the entire console.
Returns: Void.

Timer Device Driver Specification

The actual timer interrupt handler in this project is quite simple, although you will be using the timer interrupt to trigger your scheduler in Project 3. For this project, you'll be using the timer interrupt to determine how rapidly the user is typing.

Configuring the Timer

To initialize the timer, first set its mode by sending TIMER_SQUARE_WAVE (defined in lib/inc/timer_defines.h) to TIMER_MODE_IO_PORT (also defined in lib/inc/timer_defines.h). The timer will then expect you to send it the number of timer cycles between interrupts. This rate is a two byte quantity, so first send it the least significant byte, then the most significant byte. These bytes should be sent to TIMER_PERIOD_IO_PORT (defined in lib/inc/timer_defines.h).

When the timer interrupt occurs the processor consults the IDT to find out where the timer handler is. The index into the IDT for the timer is TIMER_IDT_ENTRY, defined in lib/inc/timer_defines.h. You will need to complete this entry for your timer handler to execute properly.

Your timer interrupt handler should save and restore the general purpose registers. You also need to tell the PIC that you have processed the most recent interrupt that the PIC delivered. This is done by sending an INT_CTL_DONE to one of the PIC's I/O ports, INT_CTL_REG. These are defined in lib/inc/interrupts.h.

Note: You will be testing this on an instruction set simulator. Even though you are simulating an older processor on relatively fast machine, Simics does not make an effort to exactly correlate the simulation to real wall clock time. If you have it set up properly, it will run in real time on real hardware.

Timer Device Driver Interface

Conversely to the above, you should not put any code specific to your typing tutor in the timer interrupt handler. Just as your timer handler should work if tick() is an empty function, your program should not display anything related to your typing tutor on the screen (or do any other typing-tutor processing) if someone removes calls to tick() from your timer interrupt.

Keyboard Device Driver Specification

The index into the IDT for the keyboard is KEY_IDT_ENTRY (defined in lib/inc/keyhelp.h). When you receive a keyboard interrupt, your keyboard handler needs to read the scancode from the keyboard by reading a byte from the keyboard's I/O port (KEYBOARD_PORT defined in lib/inc/keyhelp.h). You also need to tell the PIC that you have processed the keyboard interrupt. This is done by sending a INT_CTL_DONE to one of the PIC's I/O ports, INT_CTL_REG. In the interest of making the interrupt handler as short as possible, you should postpone processing the scan code until you are no longer inside an interrupt handler. The process_scancode function is expensive timewise, and you may miss keyboard interrupts if you attempt to process scancodes within the keyboard interrupt handler.

Do not forget that your keyboard interrupt handler needs to save and restore the general purpose registers! Also, we have included functions that enable and disable interrupts in lib/inc/x86/proc_reg.h (namely enable_interrupts() and disable_interrupts() respectively). You will most likely need to use them once in your keyboard driver to ensure there are no interrupt-related concurrency problems. Certain implementations may not need them. If you believe this is the case for your implementation, please add a comment explaining why this is so.

Keyboard Device Driver Interface

char readchar();
Description: Returns the next character in the keyboard buffer. This function does not block if there are no characters in the keyboard buffer.
Returns: The next character in the keyboard buffer, or -1 if the keyboard buffer is currently empty.

Skeleton Kernel

Before handing in your project, you should make certain that your drivers work with our test code, provided in 410test.c To test your drivers against the provided test code, build your project using the 410test make directive using "make 410test". Please note that this make directive does not update the project's support files automatically; you should run make (or make afs or make web), followed by make clean, before running make 410test.

Provided C Functions

Although various printing functions are provided in stdio.h (namely printf, putchar, and puts) they will not work until you implement putbyte and putbytes.

Also, we have provided a function called lprintf_kern (in lib/inc/stdio.h) and a MAGIC_BREAK macro (in lib/inc/kerndebug.h) that you may find useful for debugging purposes. lprintf_kern works like printf, but will send its output to Simics (not to the console you're writing) and to the kernel.log file. Unlike printf, lprintf_kern does not depend on any of your functions. Whenever a MAGIC_BREAK is encountered within your code, Simics will act as if it has reached a set breakpoint and enter debugging mode.

Testing

1. When your kernel boots, it should begin selecting strings of 80 characters or less to display on the screen. We have provided several phrases for you in a null-terminated array of strings called TYPING_STRINGS. You may not modify this array (it is declared constant), but you may add more strings to the pool from which the program selects if you wish. How you do this is up to you.
2. After displaying a string, your program should await user input. You should record and display keyboard input until the user presses return. Once return is pressed, the program should verify that the entered string matches the string displayed; if not, an error message should be shown and the program should wait for the user to correct the mistake. The user should be able to undo mistakes using the backarrow key.
3. After the process described above is repeated five times, the program should calculate the user's typing words-per-minute by determining how much time was required to type all five strings. To determine the number of "words" typed, a useful rule-of-thumb is to equate a word to every five characters typed.
4. The program should display the words-per-minute, and instructions to strike any key to continue. Once a key is pressed, the program should repeat the proces from the beginning.

The above description is a bare-minimum requirement for the project. Feel free to be more creative: add extra strings, use color, or do whatever you think would be fun. If an idea seems to unusual, feel free to check with a TA before implementing it.

Note on randomness: In general you need two things, namely a random seed and a pseudo-random-number generation process. Probably the easiest way for you to get a random seed involves timing one or more keypress events. There are other options as well. For further reading on randomness within the machine, see EGD: The Entropy Gathering Daemon.

Documenting

Other Important Notes

• Since we will be running and testing your code on Andrew linux machines, your code will be compiled, linked, and run under gcc 3.2.1. If you are working on AFS, then you don't have to worry about anything. If you are working on a non-AFS machine, you can check the version of gcc you are using by running gcc --version on the command line. If your version is not 3.2.1, you must make sure that your code compiles, links, and runs fine under 3.2.1.
• Please do not change any of the provided files in the lib/ subdirectory. We will run your code using our versions of the files, so any changes you make will be lost.
• After writing putbyte in the console driver, if you have not already implemented the timer interrupt handler, you may see the message Unexpected Interrupt 0 appear on the console (multiple times). This is because the timer is sending interrupts which you are not yet handling. The default handler just prints a message, which uses a function that calls your putbyte function. Since you have finished this function, you are now seeing this message. When you write and install your timer handler, this message will disappear. However, until then, to make it go away you can either write and install a timer handler which does nothing, or you can make a call to disable_interrupts() right after our pic_init call in the kernel. Don't forget to remove that call later when you want to actually receive the timer and keyboard interrupts.
• Be sure to put your driver initialization and installation code—and only your driver init and install code—into driver_init.c. We need this code in a consolidated place to be able to test your drivers independently of your typing tutor.
• You should read the Software Setup Guide for more information on the software setup for this class and for information on files commonly found in the project tarballs.

Because Simics simulates every instruction executed, it has some powerful debugging capabilities. It allows, for example, breakpoints to be set on memory accesses to certain locations (specifically reads, writes, executes, or any combination thereof). It also allows temporal breakpoints - breakpoints that occur after a certain number of instructions have been executed. Like the popular debugger GDB (which most of you should be familiar with from 15-213) it has some symbolic debugger capabilities as well.

Simics has been installed on AFS and thus may be used from any Linux machine connected to AFS, subject to licensing restrictions. If you have added the 15-410 bin directory to your path, you can execute simics on your kernel by executing simics-linux.sh You may also use a Solaris machine, but your code still must be compiled and run on a Linux machine (you can ssh into linux.andrew.cmu.edu and compile and run there).

Instructions on getting Simics to work within your development environment are on the Projects section of the course website.

A Note on "Triple Faults"

Triple faults are easy to run into in Project 1. Since you are not installing many fault handlers, most IDT entries are invalid. If, for example, your Project 1 code makes an invalid memory reference, a protection fault could be raised. Since you have not installed a protection fault handler, there is a good chance that referencing the nonexistent handler will cause a "segment not present" exception to be raised. Since you have not installed a "segment not present" handler...

The meaning of each fault condition is described in Chapter 5 of intel-sys.pdf.

Grading Makefile and Dual Images

The 410test program provides a different kernel_main() function which will link against the same $OBJS list and will call your console and keyboard API functions. Before it does that, however, it will call handler_install() so you can set up your interrupt handlers and initialize global variables your drivers might need.

Hand-in Instructions

See http://www.cs.cmu.edu/~410-s04/p1/handinP1.html for details.

[Last modified Friday January 23, 2004]