A Quick Bochs Tutorial for COS318
Wei Dong
This tutorial will teach you the minimal knowledge to install and run Bochs on the fishbowl machines.  For further information about Bochs, please go to the Bochs homepage.
1. Installation

Open http://bochs.sourceforge.net/getcurrent.html. At the end of the page you will find a link to the tar file containing the current CVS snapshot. Download it to a local directory at your comfort.  The filename may vary depending on the current date.  For the time this tutorial is created, it's bochs-20060912.tar.gz.  I will use this filename in the rest of the page.  You should change the filename part of the commands appropriately so that it point to the file you downloaded.

Once you have the tarball downloaded to a directory, say ~/tmp, type the following command to unpack the file:

$ cd ~/tmp
$ tar zxvf bochs-20060912.tar.gz

By default, Linux software are installed to /usr/local when built from source code.  You don't have write permission at /usr/local, so you have to create a directory under $HOME (or ~ for short) for installing software.  Let's say the directory is foo.

$ mkdir ~/foo

Then we can continue to build and install Bochs.

$ cd ~/tmp/bochs-20060912
$ ./configure --prefix=$HOME/foo --enable-debugger --enable-disasm
$ make
$ make install

By now, Bochs should have been successfully installed into ~/foo.  Try the command

$ ~/foo/bin/bochs

If Bochs is correctly installed, you should see a menu.  For now, type 6 to quit.

You may also add the directory ~/foo/bin to the PATH environment variable so you can run "bochs" directly without typing the path "~/foo/bin/bochs".  Add the following line

export PATH=~/foo/bin:$PATH

to the file ~/.bash_profile .

2. Running Bochs

You have to correctly configure Bochs in order to run for the first time.  Start Bochs by typing the command "bochs" and you'll see a start up menu.  Run "bochs --help" to see more options.  Bochs will search configuration file in the following order:
  1. .bochsrc in the current directory
  2. bochsrc in the current directory
  3. bochsrc.txt in the current directory
  4. (win32 only) bochsrc.bxrc in the current directory
  5. (Unix only) .bochsrc in the user's home directory
  6. (Unix only) bochsrc in the /etc directory
For the first time, you'll have to edit the configuration by choosing menu item 3.  Make sure the following items are correctly set:

    5. Memory options
                1. Memory size (megabytes): 32
                2. Name of ROM BIOS image: /home/YOUR_USER_NAME/foo/share/bochs/BIOS-bochs-latest
                3. Name of VGA BIOS image: /home/YOUR_USER_NAME/foo/share/bochs/VGABIOS-lgpl-latest
    10. Disk options
                1. Floppy Disk 0: DISK_IMAGE_FILE
                        Bochs will ask what type the floppy is.  You could answer 1.44M, but other values might also work.  Set the floppy status to "inserted".
                15. Boot Options
                        Make sure Boot drive #1 is set to floppy.

The DISK_IMAGE_FILE is the image you will use to boot Bochs.  It is basically what is written to the memory stick.  You can create a 1.44M floppy image by using the following command:

$dd if=/dev/zero of=bochs.img bs=1024 count=10240
$dd if=image of=bochs.img conv=notrunc

And use bochs.img created as DISK_IMAGE_FILE.  But it seems also working to use image directly as the DISK_IMAGE_FILE.

By now Bochs should be able to boot from the boot image you provide.  You may want to save the configuration to some file, like bochsrc in the current directory so that it gets automatically loaded when the next time Bochs runs.

3. Debugging with Bochs
We have configured Bochs so that it can be used as a debugger.   After dumping out much diagnostic information, Bochs will stop at a command line like the following:

00000000000i[     ] reset of 'parallel' plugin device by virtual method
00000000000i[     ] reset of 'extfpuirq' plugin device by virtual method
00000000000i[     ] reset of 'speaker' plugin device by virtual method
00000000000i[XGUI ] [x] Mouse off
00000000000i[     ] Warning: no rc file specified.
00000000000i[     ] set SIGINT handler to bx_debug_ctrlc_handler
Next at t=0
(0) [0xfffffff0] f000:fff0 (unk. ctxt): jmp far f000:e05b         ; ea5be000f0

Here you can start enter debug command.  Following are some of the commands that might be useful.  Read the Bochs User Manual for more information.

c                continue executing
s [count]    execute count instructions, default is 1
Ctrl-C        stop execution, and return to command line prompt
Ctrl-D        if at empty line on command line, exit
q                quit debugger and execution
b addr        set a breakpoint at given address
xp addr      examine memory at given address
info reg        list all cpu registers

For example, you probably would like to set

<bochs:1> b 0x7c00

before continue so that Bochs will stop at the first instruction of the boot block.
You can type "help" at the command line to get more information about the debugging commands.