15-410 Software Setup Guide

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 addresses to run the simulator. If you have a non-128.2 IP, you may request a personal academic license from Virtutech. This will work on one machine only, and will be good for one year. Obtaining a license involves a processing delay, typically one to three days.

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 Linux via a simple script we will provide in your project tarball. If you want to use a Solaris machine, you can ssh into linux.andrew.cmu.edu and compile and run there.
• Non-AFS-connected machine, you will need to get our Simics tarball (simics.tar.gz) from /afs/cs.cmu.edu/academic/class/15410-s04/files or by downloading it here and untar (tar -zxvf) it on your own linux 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.

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 to the instructions above for Non-AFS-connected machines).

B. 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. Follow the link above.

2. For each project

The project tarball will contain the following items:

• Skeleton Makefile
• update.pl - our updating script (already run by the Makefile)
• bootfd.img - raw disk image file
• simics-linux.sh - script to run Simics on Linux
• lib/ - directory containing headers, C standard library functions, and more.
• Some other source files depending on the project

A. Makefile

There are different methods for making depending on where you are working. This is because we use checksums to determine if we must update the versions of any of our provided files, and the method for obtaining the checksums and files depends on the possible type of connection:

• AFS-connected machine should use make.
• Non-AFS-connected machine with a Web connection should use make web.
• Non-AFS-connected machine with no Web connection: Though you can work on your own machine without a web connection, this is highly not recommended. First, while you have a connection, you must make offline and then you can work offline. However, any changes we might have to make in our provided files will not propagate to your files unless you make from an AFS machine or make web from a non-AFS machine. In addition, you should make deepclean between any make offline and using any of the other make rules.

• make html_doc - generates the doxygen documentation from your files.
• make print - creates a single postscript document containing all files listed in the SRCS make variable. Good for printing.
• make clean - normal clean rule
• make deepclean - cleans out object files in the lib directory in addition to a normal clean.

B. update.pl

This script takes care of updating the files we provide to you when necessary. It is already included in some of the makefile rules.

If you are on a Non-AFS-connected machines, you may need to change the #! at the beginning of the file to point to the location of your perl program.

C. simics-linux.sh

This is the script that runs simics.

If you are on a Non-AFS-connected machines, you will need to change SIMICS_PATH in simics-linux.sh (provided in your project tarball) to point to the top level of your simics-1.4.7 installation directory. In addition, you will need to download another tarball with each project (except for the first project) containing some additional files that will need to be unzipped in the home subdirectory within your simics directory.

3. Other Important Information

A. gcc

If you are working on a non-AFS-connected 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.

4. Questions?