Tools Used in CS372H

Public CS Linux Machines

If you use the CS department machines that run Linux (run "cshosts publinux" to get a list), then all the software tools you will need for this course are installed. You just need to set up your paths and such to get convenient access to them. The standard gnu compilers and tools (make, etc.) should already be in your path (in /usr/bin and /lusr/bin). GNU's make (gmake) may work better than plain-vanilla make for some of the projects; gmake is in /u/dahlin/bin/gmake. Finally, Bochs has been installed in /u/dahlin/bochs/bochs-2.2.6-6.828r2/bochs Depending on your setup, you may want to modify your .login, .cshrc, or other files. I added the following to my .login:

  setenv PATH /u/dahlin/bochs/bochs-2.2.6-6.828r2/:/u/dahlin/bin:$PATH

Bochs makes use ROM images stored in /u/dahlin/bochs/bochs-2.2.6-6.828r2/bios. You may also want to update your .login or .cshrc to set BXSHARE to refer to that directory:

  setenv BXSHARE /u/dahlin/bochs/bochs-2.2.6-6.828r2/bios

Also note that I have installed another copy of bochs, this one with gdb support turned on, in /u/dahlin/bochs/bochs-2.2.6-6.828-gdb/bochs and added a sym-link to it from /u/dahlin/bin/bochs-gdb, so if you set your paths as just described and run "bochs-gdb" you should see that version run. Here is a description of how to use bochs with a remote GDB process.

Finally, depending on how your X environment is set up, Bochs may have trouble finding the font it wants for the console it displays. You may want to add the following to your .xinitrc

      xset fp+ /u/dahlin/bochs/bochs-2.2.6-6.828r2/font

Personal Machines

If you would like to compile and run the tools on your own machine, however, here is the information you need. Of course, we cannot guarantee that these tools will be portable to every possible machine you might want to run them on; they should at least compile easily on most recent versions of Linux. If you are on MacOS X or BSD or Solaris, it should also be possible to get the environment set up with a bit more work. If you run Windows, it should be possible to get this development environment running 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). Note that we will not be able to provide much additional help in setting up or debugging your home environment. Also note that all grading will be done on the CS Linux machines and it is your responsiblity to port and test your solutions in this environment before you turn in your code. "It works on my home machine" is not a factor we will consider in grading.

Compiler Toolchain

Most modern Linuxes and BSDs have an ELF toolchain compatible with the 372H 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:

GCCPREFIX=

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 known-to-work versions via these 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 GNUMakefile used in the labs to use i386-jos-elf-gcc instead of gcc. There are instructions for how to do this inside of GNUMakefile.

Bochs Emulator

Bochs version 2.2.6 is set up on CS for x86 machines. If you want to use the same version on your home machine, you have two options.

Copy the binaries from cs. Run the following commands from your home machine where <bochs-dir> is where you want to install bochs:
```
cd <bochs-dir>
scp -r <username>@linux.cs.utexas.edu:/u/dahlin/bochs/bochs-2.2.6-6.828r2 .
```

The other option is to download, compile, and install bochs from the source archive. This is the only option if you want to run bochs under a different OS or on a different architecture. 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.

# cd /some/tmp/build/dir
# wget http://www.cs.utexas.edu/users/dahlin/Classes/UGOS/labs/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-x \
            --with-x11 \
            --with-nogui
make
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 \
             --with-carbon

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 CS372H-specific changes are in the bx_dbg_stepN_command function, in bx_debug/dbg_main.cc. The new function body looks like:

  void bx_dbg_stepN_command(bx_dbg_icount_t count)
  {
    if (count == 0) {
      dbg_printf("Error: stepN: count=0\n");
      return;
    }
  
    // use simulation mode while executing instructions.  When the prompt
    // is printed, we will return to config mode.
    SIM->set_display_mode(DISP_MODE_SIM);
  
    // 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)->cpu_loop(1);
        BX_CPU(cpu)->mode_break = old_mode_break;
      }
  #if BX_SUPPORT_SMP == 0
      // ticks are handled inside the cpu loop
  #else
      BX_TICK1();
  #endif
    }
  
    BX_INSTR_DEBUG_PROMPT();
    bx_dbg_print_guard_results();
    bx_guard.guard_for = old_guard;
  }

If you do build your own environment for your home machine, please report your experience (successes and difficulties) to the newsgroup so that others can benefit from your experience and vice versa.