Before you begin...
(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
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
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
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).
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
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
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
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
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.
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
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 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