[Kernel, courtesy IowaFarmer.com CornCam]

CS 235 Advanced Operating Systems, Fall 2006


You'll use two sets of tools in this class: an x86 emulator, Bochs, for running your kernel; and a compiler toolchain, including assembler, linker, C compiler, and so forth, for compiling your kernel. Here's the information you'll need to use the versions on our class compute server, or to download and install your own copies. This class assumes familiarity with Unix commands throughout.

Using Cygwin on a Windows Machine

If you have a Windows machine, the easiest way to work on labs from home is to use the Cygwin system to log in to a class machine. Cygwin is quite popular, so it is unlikely that you will mess up your computer by installing it. But if you don't want to go through this procedure, you can use any on-campus SEASnet computer lab (even the Windows labs) to complete the labs, since those computers already have X already set up; you can log in to a class machine from there.

Here's how to install Cygwin on your Windows machine.

  1. Install Cygwin/X. Follow this procedure. Make sure you select the "xorg-x11-base" package and the "openssh" package. Also select the "flex" and "bison" packages from the development header. This sets up a Unix-like environment on your Windows machine, including an X server. X is the protocol used by the Solaris machines to display images, such as the Bochs window, on remote computers.
  2. Start the Cygwin X server by running startxwin.bat. "Run /usr/X11R6/bin/startxwin.bat by double-clicking it in Windows Explorer." http://x.cygwin.com/docs/ug/using.html
  3. Follow these instructions to log in to a remote machine using ssh. You will do something like "ssh -Y -l yourusername seek.cs.ucla.edu" from the X terminal you started up on your machine.
  4. Work on the lab on the remote machine; it will display the Bochs information on your machine.

You should also be able to compile the class tools and the labs on your Windows machine, once Cygwin has been installed. Let us know if you have success with this.

Using the Class Compute Server

We have set up a compute server for your use. This compute server may be faster than SEASnet (assuming it doesn't get overused). Request a username from the instructor. Once you have a username, you should be able to log in to the compute server with "ssh -Y -l yourusername seek.cs.ucla.edu" (if you are using OpenSSH), or (on Windows) using PuTTY's X forwarding support. You need X forwarding in order to see the Bochs window that shows you the emulated computer. All of the class tools -- GCC, linkers and so forth, and bochs -- should be in your PATH already.

We need your SSH public key to give you an account on the compute server. The SSH public key is a way to log in to a machine without using a password. If you are already using ssh-agent or an equivalent, you know what to do: send us your public key in OpenSSH format. Otherwise, there are some sites on the web that explain how to set up an SSH public key: a tutorial for OpenSSH, and a tutorial for PuTTY. (Here is some more detailed documentation for PuTTY.) Send us your public key after you have created one. You can do this with ssh-add -L on an OpenSSH/ssh-agent setup; on PuTTY, send us the contents of the "Public key for pasting into OpenSSH authorized_keys file".

Using SEASnet

The class tools are available in a shared directory. Add /u/cs/class/cs235/cbin/bin to your PATH, and /u/cs/class/cs235/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/cs235/cbin/bin 
% setenv MANPATH ${MANPATH}:/u/cs/class/cs235/cbin/man 

If you use the bash shell, or a similar Bourne-derived shell, do this:

$ export PATH=${PATH}:/u/cs/class/cs235/cbin/bin 
$ export MANPATH=${MANPATH}:/u/cs/class/cs235/cbin/man 

Of course, it will be slightly easier if you add these commands to your login shell script (~/.tcshrc or ~/.bashrc), so they are run whenever you log in.

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.

Downloading Your Own Copies

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, as described above. 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.

Compiler Toolchain

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 other 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.17
./configure --target=i386-jos-elf --prefix=PFX
make install
cd ../gcc-4.1.1
./configure --target=i386-jos-elf --prefix=PFX --enable-languages=c --disable-libssp
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-4.1.1 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:

    noconfigdirs="$noconfigdirs target-libstdc++-v3"

Bochs Emulator

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.)

Download Bochs 2.3 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 ~/bxdebug.patch . Configure and install as follows:

gzcat bochs-2.3.tar.gz | tar xf -
cd bochs-2.3
patch -p0 < ~/bxdebug.patch
./configure --enable-cpu-level=6 --enable-disasm \
    --enable-debugger --enable-x86-debugger \
    --enable-iodebug --enable-instrumentation \
    --enable-new-pit --enable-4meg-pages \
    --enable-pae --enable-global-pages \
    --enable-all-optimizations --with-all-libs \
make install

You may also want to run ./configure --help and look at the available options.

Mac OS X note: Make sure you have installed the Xcode package with support for X11. Try the following ./configure line instead:
./configure --with-x11 --with-nogui --disable-cdrom \
    --enable-cpu-level=6 --enable-disasm \
    --enable-debugger --enable-x86-debugger \
    --enable-iodebug --enable-instrumentation \
    --enable-new-pit --enable-4meg-pages \
    --enable-pae --enable-global-pages \
    --enable-all-optimizations \

Other ./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.

QEMU Emulator

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.

Back to CS 235 Advanced Operating Systems, Fall 2006