How to DEBUG System Code
using The Bochs Emulator
on a Windows™ PC

Copyright©2013 by Daniel B. Sedory

If you need any help in setting up the Bochs Debugger, please email us.

Executing The Bochs Debugger

First, navigate to your "C:\Program Files\Bochs-2.6.2\dlxlinux\" folder, then make a copy of the run.bat file and rename it debug.bat. Edit the file in NOTEPAD by changing the line "..\bochs -q -f bochsrc.bxrc" to: "..\bochsdbg -q -f bochsrc.bxrc" so it will execute the bochsdbg.EXE program. Now run debug.bat.

The Bochs "Display" window will remain empty at this time, but you will see the following in the Bochs "Console" as it always pauses (technically, it's called a BREAK) at the first instruction of its own BIOS code; the same exact instruction can be found in virtually every PC's BIOS:

NOTE: In order to pause the execution of a disk image file under Bochs at its very first assembly instruction (as shown in the picture below), you need to set a "breakpoint" in Memory at that linear location of 7c00 (Enter: lb 0x7c00); which is where the BIOS loads the Master Boot Record from Sector 0 of the first hard disk.

After entering the appropriate commands ("lb 0x7c00" and "c" to continue), the Bochs Debugger stops just before executing the first instruction of the DLX Linux image file. Following that we entered an "s" command to begin single-stepping through the code. (Note: All subsequent presses of the ENTER key will do the same thing as the previous command that was entered, so you only need to ENTER the 's' command one time, then simply press the ENTER key each time after that to keep executing a single Assembly instruction each time.) Here we executed two more instructions; arriving at Linear Memory Location 0x7c72:

Commands which can be used in both the Console and GUI Debuggers can be found in the documentation (see 8.12. Using Bochs internal debugger) which comes with the Bochs download. We've highlighted some of the most important commands to get you started here:

cContinue executing
s [count](Step): execute count instructions; default is 1.
qQuit debugger and execution.
Ctrl-Cstop execution, and return to command line prompt
lb addrSet a linear address instruction breakpoint
info breakDisplay state of all current breakpoints
bpe nEnable a breakpoint
bpd nDisable a breakpoint
del nDelete a breakpoint


The Bochs (GUI) Enhanced Debugger

In order to use the GUI form of the Bochs Debugger, first open the bochsrc.bxrc file in your "C:\Program Files\Bochs-2.6.2\dlxlinux\" folder in NOTEPAD (right-clicking on this file name might give you an "Edit" choice), and search for these two lines inside the file:

#display_library: x
# other choices: win32 sdl wx carbon amigaos beos macintosh nogui rfb term svga

NOTE: Any line that begins with a # symbol is inactive and taken only as a comment.
Then underneath those two commented lines, add this required un-commented line:

display_library: win32, options="gui_debug"

(The quote marks must be included.) Now when you run debug.bat, the Enhanced Debugger will appear!

When you add other operating system folders under your Bochs install, we'd advise you to make copies of the fully commented sample bochsrc.bxrc file (which is found here: "C:\Program Files\Bochs-2.6.2\bochsrc-sample.txt"), and rename each copy as appropriate to the OS or project you're working with/on.

[ Note: If you setup the environment variable "$BXSHARE" as being equal to the path where Bochs is installed, and use that variable in your configuration file, then you could setup image file folders anywhere else on your PC; not just under the Bochs install directory. If you're using the install folder we are for version 2.6.2, you would open a Command Line prompt and ENTER: set $BXSHARE="C:\Program Files\Bochs-2.6.2\" (Note: The quote marks are required here, and do not put any spaces before or after the '=' sign!) Then inside your .BAT and configuration files in those other folders, you could use "$BXSHARE" instead of writing out the path to where the Bochs executables are located, or using '..'. For example: "romimage: file=$BXSHARE/BIOS-bochs-latest" If you do not do this, then be sure to change any line in copies of the 'bochsrc-sample.txt' file that use '$BXSHARE/'. ]

This next view shows the "Bochs Enhanced Debugger" about to step through the DLX Linux's LILO Master Boot Record code (located on the first sector of a PC's hard disk; or in this case, in the DLX Linux image file running under Bochs):

You can also use the BOCHS (GUI) Debugger on the Windows 7/8 MBR code; see our Windows 7 MBR Pathways for step-by-step comments on the execution of each instruction.

Setting Up a New OS under Bochs

First, you need to understand that just like any hardware PC, for which it would be highly unlikely that moving its disk drive into a completely different type of PC would result in its OS booting-up inside that PC, so too, the chances would very small that making an image file of that PC's disk drive would result in a Bootable OS under Bochs, since Bochs also uses 'drivers' that are specific to its own emulated hardware BIOS code. However, if we go back in time and use an image file of an operating system whose only user interface was a command line, on a black screen, with very few peripherals, you'll find image files of some early DOS versions will run quite nicely under Bochs without any changes. Here at the Starman's Realm, we not only tested almost every possible DOS available, but also took the time to install and run at least Windows 95, 98SE and even XP under Bochs. [Note: For XP, it took all weekend (we had to leave the PC running most of two days and all night long), since its emulation speed is so slow compared to real hardware!]

What about the Windows 7 MBR code? Well, if that's all you want to test, you can easily copy the CODE section (skipping the Partition Table) from the first sector of any Windows 7 OS boot drive into the first 446 bytes of some old DOS or early Windows HDD image that runs under Bochs, and it will boot-up into that OS. Like all other PC MBR code, it runs in Real Mode, and needs no special 'drivers' nor expects a specific OS to be installed on its HDD. [Note: If you attempt to do this with the DLX Linux image file that comes with Bochs, the Win 7, or any other DOS or Windows, MBR code will fail to boot it, because the Linux file system (ext2 in this case) does not require there be any VBR code in the first sector of its partition. It's possible for Linux to have boot code there, but Linux doesn't require it, since most installs place its Boot Loader/Manager at the beginning of an HDD. If you 'dual-boot' a Linux OS on a Windows PC, you can often ask a Linux install to put the Boot Loader into the Partition; which then gives you the option to revert back to a Windows MBR and Boot Manager and be able to boot up Linux from its Manager.]

(NOTE: You can use the free HxD Disk Editor to copy the Win 7 MBR code; we've written a tutorial for doing just that here).

As a first step, before using the bximage program that comes with Bochs, you can simply copy the hd10meg.img file in the Bochs dlxlinux folder to a new folder and rename it to something like dos10meg.img, then install some DOS in that 10 MiB file; for which you can then use the same Bochsrc.bxrc configuration file (with a few modifications).

Date Page Added: May 16, 2012 (16.05.2012).
Updated: May 20, 2013 (20.05.2013); May 25, 2013 (25.05.2013); May 29, 2013 (29.05.2013).
Last Updated: July 15, 2013 (15.07.2013).

You can write to me using this: online reply form. (It opens in a new window.)

The Starman's x86 ASSEMBLY Pages

The Starman's Realm Index Page