User tips:

The main user features available from the menu should be fairly obvious,
to anyone who has used bochs -- but here are a few quick explanations, anyway.
These explanations include a few keyboard and mouse shortcuts that you might
not find through experimentation.

Terminology:
The Bochs guys call this interface the CI, to distinguish it from the "VGA window"
that shows the display of the simulated computer. I will call this debugger GUI
interface the "frontend". It's not much better a term, but oh well.

The text debugger interface that you are all familiar with is called the
Bochs Internal Debugger -- or ID for short.

The frontend is organized around 3 main "list-view" windows:

The Register window:
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".

** Doubleclicking a register allows you to change its value. Currently, this
only works for the GP registers. In later versions, more registers may be
modifiable.

The Disassembly window:
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 likely to see big performance problems in windows on
certain occasions -- like minimuzing and then restoring the window. This is
a windows bug/"feature".

Note: 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. The frontend ONLY displays linear breakpoints. It does not bother
trying to figure out the linear->phsical 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.

** If you do a Find command to select a bunch of ASM lines, you can set linear
breakpoints to all of them at once, with the F6/Breakpoint command. However,
there is a limit compiled into bochs on the maximum number number of linear
breakpoints. The typical limit is FIVE. Edit your config.h if you want more.

The MemDump window:

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 phyical 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 Control sets read watchpoints.
** You can use both Shift and Control at the same time.
** 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".


Other windows:

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.

** Hitting Enter on a blank line will cause a Singlestep.

The Button row:

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.

Docking/Resizing:

If you grab one of the two "bars" in the list area, 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 enh_dbg2.h file, for compile-time customization.)

Additional Notes:

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. Additionally, note the "windows feature" listed above --
it is not wise to minimize the display, if one of the lists is really big.

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.


