CS 372H: Tools

All of the tools that you need to execute and complete the labs are on the Linux CS department machines.

If you wish to compile and run the tools on your own machine, the information that you need is as follows. Note that we cannot guarantee that these tools will run on your computer, and we cannot support these tools on your own computer. However, the tools should run on recent versions of Linux. The tools should also run under Windows with the help of Cygwin. Install cygwin, and be sure to install the flex and bison packages (they are under the development header).

Compiler Toolchain

Most modern Linuxes and BSDs have an ELF toolchain compatible with the JOS labs. That is, the system-standard gcc, as, ld and objdump should just work. If your machine is in this camp, disable the i386-jos-elf- tool prefix in your make setup by adding the following line to conf/env.mk:


If you are using something other than standard x86 linux or BSD, you will need the GNU C compiler toolchain, configured and built as a cross-compiler for the target 'i386-jos-elf'. You can download versions that are known to work with JOS via the following links, although more recent versions of gcc and binutils should work too:

Once you've unpacked these archives, run the following commands as root:

$ cd binutils-2.15
$ ./configure --target=i386-jos-elf
$ make
$ make install
$ cd ../gcc-3.4.1
$ ./configure --target=i386-jos-elf
$ make
$ make install

If there are errors compiling gcc when it gets to libstdc++, don't worry about it.

Then you'll have in /usr/local/bin a bunch of binaries with names like i386-jos-elf-gcc. It will also be necessary to change the Makefile used in the labs to use i386-jos-elf-gcc instead of gcc. There are instructions for how to do this inside of the Makefile.

Bochs Emulator

Bochs version 2.2.6 is set up on the Linux UTCS hosts. If you want to use the same version on your home machine, then you must download, compile, and install bochs from the source archive. Note that if you download a prebuilt version of bochs, it will not be compiled with the same options as we use for the class. Also, the Bochs version for the class contains a bug fix to make single-stepping work.

The MIT folks have prepared an automated, self-updating script to assist in installing Bochs and potentially upgrading to new versions of Bochs. As root:

# cd /some/tmp/build/dir
# wget http://pdos.lcs.mit.edu/6.828/2008/src/bochs-install.sh
# sh bochs-install.sh
If they issue future updates to the Bochs-for-JOS tar file, it would only be necessary to run:
# cd /some/tmp/build/dir
# sh bochs-install.sh
the reason being that the MIT script asks the server what the most current version of the Bochs tar file is.

To do things manually, fetch the modified Bochs 2.2.6 source as follows:

$ wget http://pdos.lcs.mit.edu/6.828/2008/src/bochs-2.2.6-6.828r2.tar.gz

You may want to run ./configure --help and look at the available options, particularly --prefix= which determines where Bochs will be installed.

tar xzvf bochs-2.2.6-6.828r2.tar.gz
cd bochs-2.2.6-6.828r2
./configure --enable-disasm \
            --enable-smp \
            --enable-debugger \
            --enable-new-pit \
            --enable-all-optimizations \
            --enable-4meg-pages \
            --enable-global-pages \
            --enable-pae \
            --disable-reset-on-triple-fault \
            --with-all-libs \
            --with-x \
            --with-x11 \
make install
For Mac OS X Tiger:
 ./configure --disable-cdrom \
             --enable-smp \
             --enable-disasm \
             --enable-debugger \
             --enable-new-pit \
             --enable-all-optimizations \
             --enable-4meg-pages \
             --enable-global-pages \
             --enable-pae \
             --disable-reset-on-triple-fault \
             --with-nogui \
             --with-x11 \
             --with-x \

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. If the make install step fails, it is probably possible to install it manually by copying ./bochs to /usr/bin/bochs and setting the environment variable BXSHARE to the path to the bochs-2.2.6 directory.

If you want to use a different version of bochs (not recommended!), the JOS-specific changes are in the bx_dbg_stepN_command function, in bx_debug/dbg_main.cc. The new function body looks like this:

  void bx_dbg_stepN_command(bx_dbg_icount_t count)
    if (count == 0) {
      dbg_printf("Error: stepN: count=0\n");
    // use simulation mode while executing instructions.  When the prompt
    // is printed, we will return to config mode.
    // single CPU
    int old_guard = bx_guard.guard_for;
    bx_guard.guard_for |= BX_DBG_GUARD_ICOUNT; // looking for icount
    bx_guard.guard_for |= BX_DBG_GUARD_CTRL_C; // or Ctrl-C
    bx_guard.guard_for &= ~BX_DBG_GUARD_IADDR_ALL;
    // for now, step each CPU one instruction at a time
    for (unsigned cycle=0; cycle < count; cycle++) {
      for (unsigned cpu=0; cpu < BX_SMP_PROCESSORS; cpu++) {
	    bx_guard.icount = 1;
        bx_guard.interrupt_requested = 0;
        int old_mode_break = BX_CPU(cpu)->mode_break;
        BX_CPU(cpu)->guard_found.guard_found = 0;
		BX_CPU(cpu)->guard_found.icount = 0;
        BX_CPU(cpu)->mode_break = old_mode_break;
  #if BX_SUPPORT_SMP == 0
      // ticks are handled inside the cpu loop
    bx_guard.guard_for = old_guard;

QEMU Emulator

QEMU is a modern and fast PC emulator. QEMU version 0.10.6 is set up on the x86 UTCS machines.

Unfortunately, QEMU's debugging facilities, while powerful, are somewhat immature, so we highly recommend you use our patched version of QEMU instead of the stock version that may come with your distribution. The version installed on the UTCS machines is already patched. To build your own patched version of QEMU:

  1. Download and unpack the pre-patched 0.10.6 source tarball.
  2. On Linux, you may need to install the SDL development libraries to get a graphical VGA window. On Debian/Ubuntu, this is the libsdl1.2-dev package.
  3. Configure the source code
    Linux: ./configure [--prefix=PFX] [--target-list="i386-softmmu x86_64-softmmu"]
    OS X: ./configure --disable-sdl [--prefix=PFX] [--target-list="i386-softmmu x86_64-softmmu"]
    The prefix argument specifies where to install QEMU; without it QEMU will install to /usr/local by default. The target-list argument simply slims down the architectures QEMU will build support for.
  4. Run make && make install

Alternatively, you can download the official 0.10.6 source tarball from the QEMU homepage and apply the following patches:

i386-debug Use DS-relative virtual addresses instead of linear addresses in the GDB stub.
info-mem Fix "info mem" in the QEMU monitor to not skip the last mapped memory range.
info-pg Add "info pg" to the QEMU monitor that prints the page table.
e100 Fixes bugs in QEMU's simulated E100 and adds E100 debugging.
pcap Adds packet capture support.
option Adds the -pcap and -debug-e100 command line options used by e100 and pcap.

Last updated: Mon Mar 01 15:52:33 -0600 2010 [validate xhtml]