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 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
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)
- 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
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
There are also some other make rules we have provided for you.
- 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.
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 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
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