This document describes the procedures you may follow to update your development environment for working on the projects in this course. Besides the tools described below, you will need access to the standard set of x86 C development tools (gcc, ld, etc.).

1. One-time Setup

A. Simics

Simics is the instruction set simulator inside which your projects will run. From your perspective, it is a full-fledged x86 machine whose display appears as an X application on your desktop. Although Simics runs on a variety of platforms, we recommend you work with it on Linux.

Simics is a commercial product with special license restrictions. CMU has obtained a number of academic licenses which allow hosts with 128.2. IP's to run the simulator. If you have a non-128.2. IP, you may still request a personal academic license allowing you to run Simics by sending mail to de0u+licenses@cs.cmu.edu.

If you will be developing on a

• AFS-connected machine (dorms, clusters, etc.), no special steps are necessary. Simics is already fully set up on AFS and will run smoothly on both Linux and Solaris via a simple script we will provide in your project tarball.
• Non-AFS-connected machine, you will need to get our Simics tarball (simics-linux.tar.gz) from /afs/andrew/scs/cs/15-412b/ and untar (tar -zxvf) it on your own machine. No compilation is necessary -- the tarball contains a good-to-go binary. The Simics installation contained in it is fully self-contained; if you wish to uninstall it at any time, simply remove the entire directory. You would want to change SIMICS_PATH in simics-linux.sh or simics-solaris.sh (provided in your project tarball) to point to the top level of your simics-1.4.7 installation directory.

NOTE: Simics appears to perform very poorly on slow (less than campus Ethernet) links. If you experience this, you may want to consider installing Simics locally (refer instructions above for Non-AFS-connected machines).

B. OSKit

OSKit is a set of libraries designed to ease the development of OS-related code. We will be using it for the basic functionality it provides such as bootstrapping, performing CPU initializations, etc.

If you will be developing on a

• AFS-connected machine, no special steps are necessary. The OSKit libraries and headers you will need are already installed on AFS and included in the basic Makefile we will provide in your project tarball.
• Non-AFS-connected machine, you will need to obtain the OSKit libraries from here and the OSKit headers from here. You may extract these anywhere on your development machine, but common locations are /usr/local/lib for the libraries and /usr/local/include for the headers. After extracting, modify your Makefile to reflect the locations for these files.

C. Mtools

Simics simulates a real IDE hard drive using a disk image (.img) file. It will boot and run your kernel off a FAT-formatted "disk" represented by such a file. We will provide you with a raw disk image, but to test your code, your compiled kernel will need to be copied onto it using a utility called mcopy that is provided by the Mtools package. This copying process is automated in the Makefile provided to you in the project tarball.

If you do not have mtools installed, source and binaries are available here.

NOTE: Mtools is installed on most Linux machines, but if it is not present on your's, you will need to obtain it. Binary and source packages can be obtained from links on the project section of the course website.

2. For each project

The project tarball will contain the following items:

• Skeleton Makefile
• Usual source files
• c.img - raw disk image file
• simics-linux.sh - script to run Simics on Linux
• simics-solaris.sh - script to run Simics on Solaris
• personal.simics - user-supplied Simics initializations (optional)

3. Basic Simics Commands

Here is a brief listing of useful Simics commands. A more detailed reference is the Simics User Guide.

r
Starts the simulation. Once a simulation has been started, it may not be restarted. To give up on a simulation and start anew, quit the simulation and restart Simics.

c
Continues the simulation after a breakpoint or error has occurred. Note that you may not be able to continue reliably after some types of errors.

q
Exits Simics.

ctrl-c (control + c)
Interrupts the currently running simulation so that commands may be entered (debugging commands, quit, etc).

psym varname
Prints the value of a variable. Note that the symbols must have been loaded for this command to work properly. It is also possible to use print to get hex values - to do this, you must do print (sym varname).

break (sym function name)
Breaks when a function is executed. Note that it breaks before the stack has been set up, so printing the arguments may not work until a few more instructions have been executed.

break mem_loc -[rwx]
Breaks when the memory location mem_loc (eg: 0x2000) is read, written or executed.

help command
Returns information about the command (similar to the UNIX man command).

4. Questions?

staff-412@cs.cmu.edu