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 410/bin. 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-s06/pub 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)
• config.mk - what you should have to edit to build
• bootfd.img - raw disk image file
• 410kern/lib/ - directory containing headers, C standard library functions, and more.
• Some other source files depending on the project

A. Makefile

There are a few make rules we have provided for you.

• 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 - delete all the .o files and executables

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. config.mk

This is the file that contains information on what should be compiled into you executables

• UPDATE_METHOD must be set according to where you will be working:
  AFS-connected machines should use the afs method
  NON-AFS-connected machines with a web connection should use the web method
  NON-AFS, NON-web connected machines should use offline
• 410COMMON_OBJS shouldn't have to be changed
• COMMON_OBJS should list any object files from kern/ which should be included in both executables
• SOKOBAN_OBJS should list game-specific objects from kern/

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?