The graphical front-end for the Bochs command line debugger is available for Windows and GTK2/GTK3 hosts.
To use the GUI debugger, you must configure Bochs with the
default debugger switch and the --enable-debugger-gui flag.
For example:
./configure --enable-debugger --enable-debugger-gui
At runtime you need to add the value gui_debug to the
display_library options parameter
in order to use the GUI instead of the command line debugger. This example shows
how to use it with the 'x' GUI:
display_library: x, options="gui_debug"
Note: The wxWidgets port of Bochs always uses this debugger GUI. Passing the option to the display library is not necessary, since the command line interface is not available then.
The GUI debugger consists of a GUI window with a menu bar, a button bar and some child windows for different purposes. Not all windows are visible at the same time.
Register window
Disassembly window
MemDump window
Output window: display internal debugger output / log output
Input window: command prompt for entering debugger commands
Param tree window: show the Bochs parameter tree (CPU / hardware state)
Stack window
Breakpoint / watchpoint window
Command button row
CPU button row: only available for SMP emulation
Typically, all the various registers are grouped by color. If you don't like the colors, they can be turned off, or modified at compile time. There are options to show or hide most register "groups", so that you can focus more strictly on the registers you are interested in (probably just the GP registers).
Yes, the XMM display shows hex in the "decimal" column -- there is more room there. Deal with it.
Doubleclicking a register attempts to change its value. Bochs may not allow you to change most registers. In future versions, more registers may be modifiable.
Disassembly output that is autoloaded, or generated from the menu, ends up here. If the frontend cannot detect the "current instruction" in the list, when it reaches the next instruction -- then it will autoload a new list. Having a big list will reduce the number of autoloads, and allows you to see more. The list can contain up to 2048 lines. However, if you load more than 1000 lines, you are more likely to see performance problems.
There are two kinds of emulated memory in Bochs: Linear and Physical. Emulated Linear memory is mapped onto Physical memory by x86 virtual memory methods (paging and segmentation). If paging and segmenataion are "off", or "identity mapped", then both "types" of memory mean the same thing. But they still work a little differently. With the Internal Debugger, you can set breakpoints to either kind of memory, separately. Normally, you would use the "b" command to set breakpoints in physical mem, and "lb" to set breakpoints in linear mem. This frontend ONLY displays linear breakpoints. It does not bother trying to figure out the linear->physical reverse mapping to show physical breakpoints. (There are also "virtual" breakpoints that are also not shown.) All the types of breakpoints still WORK, it is just that you will not see them marked on the screen.
It will be obvious to you that the current instruction is marked in green, unless it is on a breakpoint, when it turns blue. Breakpoints are red, of course.
You must click a line in the window, before you can use frontend commands to set or clear a linear breakpoint on it. You can doubleclick (which saves steps) to set or clear a linear breakpoint.
As of this version, the MemDump window isn't much more than a display of the contents of memory. In later versions, hopefully it will be expanded into a fairly fully-featured hexeditor. You can dump either physical mem, or linear mem. There are breakpoint-like things (that work with physical memory only, currently), called "watchpoints". A physical memory address can cause a break in the simulation if it is read, or written.
The frontend again does NOT try to calculate out the linear -> physical mapping in any attempt to display the physical watchpoints while viewing linear mem.
You must click a hex byte (on a physical mem dump that shows bytes), in order to set or clear a read and/or write watchpoint on that byte. Read watchpoints are green (on black), write watchpoints are red, watchpoints that are both write and read are blue. There is a hardcoded limit in Bochs of 16 of each type of watchpoint.
The MemDump window loads/shows 4K of memory at a time.
PageUp/Down scrolls the display up or down through mem, 2K at a time
Doubleclicking a line of memory allows you to change the byte values (Works on both linear and physical mem dumps)
Doubleclicking with the Shift key down sets write watchpoints
Doubleclicking with Alt sets read watchpoints
You need to click once on the memory window before you can use its "Find" function. The Find function is pretty limited in scope, currently. It can only find bytes (or strings of bytes) within each 16byte "line"
The Output window shows anything that the Bochs Internal Debugger tries to send to you. The window is scrollable, but only keeps a limited history of output (10K). The ID is always spamming you with "Next at t=" and disassembly lines, that would tend to fill up the Output window with garbage -- so there are options to ignore either of these types of output.
The Input window is for sending user commands directly into the Bochs Internal Debugger -- bypassing the frontend. Results will appear in the Output Window. The Input window has a history feature for commands, using the Up and Down arrows -- it remembers 64 commands, 80 bytes each. No matter where you click on the frontend, you can always type directly into the Input box without clicking on it.
When the Input window is invisible, you should still be able to type into it -- after taking into account the bug listed at the bottom of this file.
Hitting Enter on a blank line will cause a Singlestep.
The Bochs param_tree shows the internal state of most of Bochs. It will be expanded in the future to show even more. You can see the detailed state of all cpu registers -- including the "hidden" parts (look in the "bochs" branch). Or see the current state of most of the emulated hardware.
The MemDump windows do not automatically refresh -- except for the Stack window. If you leave the stack window active, it will update as the stack changes. If you want to update the other MemDump windows with fresh data, hit Refresh.
Doubleclicking will delete a breakpoint or watchpoint.
Just a (hopefully) convenient way of using the mouse, instead of the keyboard. If you don't like them, or they take up too much space, you can turn them off.
This only shows up when you are running a multi-cpu simulation. Click on the CPU that you want to view. All CPUs are always stepped together, and they all stop the first time one hits some sort of breakpoint.
If you grab one of the two vertical "bars" between the lists, you can horizontally resize the lists. The cursor will change, but there will be no animation.
If you grab the middle of one of the lists, and drag it on top of one of the other lists, you can reorder the positions of the lists on the screen. The cursor will change, but there will be no animation. You can set an alternate "docking order" at compile time, also, if you have a permanent preference. (See the top of the wenhdbg_h.h file, for compile-time customization.)
If you have a really big GDT or Paging display in the MemDump window, and you select a different display, it may take several seconds to delete the big display before it can switch.
Uppercase text tends to seem a little annoying, but it really is a lot easier to read, especially on a proportional font. If you change to a fixed font, then you may want to switch the display to lowercase.
Most of the GUI debugger settings are now saved to an INI file on exit and restored at the next run.