The minilabs require two sets of tools: a compiler toolchain, including assembler, linker, C compiler, and so forth, for compiling your minilab kernels, and an x86 emulator, Bochs, for running them. Here's the information you'll need to use the versions on SEASnet, or to download and install your own copies.
No special preparation should be necessary.
The class tools are available in a shared directory. Add
/u/cs/class/cs111/cbin/bin
to your PATH
, and
/u/cs/class/cs111/cbin/man
to your MANPATH
. The
exact commands necessary depend on your shell. If you use the
tcsh
shell (this is the default), do this:
% setenv PATH ${PATH}:/u/cs/class/cs111/cbin/bin % setenv MANPATH ${MANPATH}:/u/cs/class/cs111/cbin/man
If you use the bash
shell, or a similar Bourne-derived
shell, do this:
$ export PATH=${PATH}:/u/cs/class/cs111/cbin/bin $ export MANPATH=${MANPATH}:/u/cs/class/cs111/cbin/man
If you ssh
in to a SEASnet machine, use
ssh -Y
(or ssh -X
, if that doesn't work), since
Bochs displays its results in an X window.
The process is pretty easy if you have access to a Unix or Mac OS X machine. It should be possible under Windows, too, with the help of Cygwin. Install cygwin, and be sure to install the flex and bison packages (they are under the development header).
First, choose a prefix, or directory, you'll use for storing the tools.
Good choices include $HOME
(your home directory),
/usr/local
, and /usr/local/jos
. Call your
prefix PFX
; then executables will be stored in
PFX/bin
, libraries in PFX/lib
,
shared files in PFX/share
, and so forth.
Before you go any further, make sure that your PATH
environment variable includes PFX/bin
! Without this,
GCC will fail to build. You may want to change your MANPATH
environment variable while you're at it.
The class tools are pretty large. You'll need around 500 MB of space to compile all the tools, but after deleting the sources, the installed executables and libraries take up less than 100 MB. Your mileage may vary.
First, check whether you need to build a GNU C compiler toolchain. If
your native GNU binutils and GCC compiler build for an i386 ELF target
(like most standard Linux and BSD systems), and your GCC is version 3.0 or
higher, you should be able to use the native compiler. To check, run objdump -i
. If the second line is
elf32-i386
, and gcc -v
reports a
high enough version, you're all set, and can skip the rest of this
section.
Otherwise, configure and build the GNU C compiler toolchain as a
cross-compiler for the target 'i386-jos-elf
'. You can
download the specific versions we used via these links, although more
recent versions of gcc and binutils should work too:
Unpack these archives using "bzcat FILE | tar
xf -
". Then run the following commands. (Supply your prefix for
PFX
.)
cd binutils-2.16.1 ./configure --target=i386-jos-elf --prefix=PFX make make install cd ../gcc-3.4.4 ./configure --target=i386-jos-elf --enable-languages=c --prefix=PFX make make install
Depending on the prefix, you may need to be root to run 'make
install
'. Then you'll have in PFX/bin a bunch
of binaries with names like i386-jos-elf-gcc. As long as
PFX/bin
is in your PATH
, the labs should
automatically find and use the i386-jos-elf-
binaries.
You can also download and configure the full gcc-3.4.4
release, which has support for C++ and Java as well as C. The C++
standard library does not support JOS, however, so you'll need to change
GCC's ./configure
script to disable it. Edit
./configure
, search for the line that says 'case
"${target}" in
', and add the following text immediately after that
line:
i*86-jos-*) noconfigdirs="$noconfigdirs target-libstdc++-v3" ;;
Next, download, compile, and install Bochs from the source archive. (If you download a prebuilt version of Bochs, it will not be compiled with the same options as we use for the class. For the minilabs, this should probably be fine! Nevertheless, we provide complete instructions.)
Download Bochs 2.2.1 from the Bochs download page; a copy is also available here. Also download this patch file, which will let you set memory watch points in device memory. Save the patch file as ~/bochs-watch.patch . Configure and install as follows:
gzcat bochs-2.2.1.tar.gz | tar xf - cd bochs-2.2.1 patch -p0 < ~/bochs-watch.patch ./configure --enable-disasm \ --enable-debugger --enable-x86-debugger \ --enable-iodebug --enable-instrumentation \ --enable-new-pit --disable-reset-on-triple-fault \ --enable-4meg-pages --enable-pae --enable-global-pages \ --enable-all-optimizations --with-all-libs \ --prefix=PFX make make install
You may also want to run ./configure --help and look at the available options.
./configure --with-x11 --with-nogui --disable-cdrom \ --enable-disasm \ --enable-debugger --enable-x86-debugger \ --enable-iodebug --enable-instrumentation \ --enable-new-pit --disable-reset-on-triple-fault \ --enable-4meg-pages --enable-pae --enable-global-pages \ --enable-all-optimizations --with-all-libs \ --prefix=PFXI had problems getting Bochs to compile. If you see many errors in a file like wx.cc or wxdialogs.cc, then you must edit the configure script. Look for a line that says "with_wx=yes", and change it to say "with_wx=no". Then run ./config.status --recheck, ./config.status, and make clean, and try again to make.
./configure
flags: Some of our
challenge problems may require adding other flags to Bochs's
./configure
line. For instance, to add VGA support, configure
with --enable-vbe
.If you wish to use a different UI than the default one, modify your .bochsrc file accordingly. See the bochsrc documentation. It should also be possible to just run man bochsrc.
If you are compiling on a non-x86 platform or on Windows, it may be necessary to remove the --enable-all-optimizations flag.
The QEMU Emulator is much, much faster than bochs, and has a slightly slicker GUI. However, it is not quite as mature, and may have problems with our kernel depending on your platform. The QEMU command line that most resembles our bochs setup is this:
qemu -hda obj/kernel.img -parallel stdio
(In later labs, you'll add an -hdb obj/fs.img argument.) The QEMU monitor, which is like the Bochs internal debugger, is accessible by pressing Ctrl-Alt-2 inside the QEMU window; return to normal display with Ctrl-Alt-1. QEMU tends to take control of your mouse given any opportunity. If you can't find a mouse pointer, check the QEMU title bar for text like "Press Ctrl-Alt to exit grab"; if it's there, press Ctrl-Alt to regain control.