Documentation updates (e.g. improved gui debugger section).
File docs-html/enh_dbg_user_man.txt no longer needed.
This commit is contained in:
Volker Ruppert
parent
0dd9d7b33e
commit
6422fe32b6
@ -114,9 +114,8 @@ interesting to know how much Bochs sources used to cost and what it was used for
|
||||
I thought I saw an interview out there somewhere where Kevin says why he started
|
||||
it and some more background information.
|
||||
</para>
|
||||
</footnote> Finally, in March 2000, MandrakeSoft (now called
|
||||
<ulink url="http://www.mandriva.com/">Mandriva</ulink>) bought Bochs
|
||||
and made it open source under the GNU LGPL.
|
||||
</footnote> Finally, in March 2000, MandrakeSoft (2005 to 2015 called Mandriva)
|
||||
bought Bochs and made it open source under the GNU LGPL.
|
||||
|
||||
<!--
|
||||
we should make it clear that Kevin is not the primary maintainer of Bochs,
|
||||
@ -264,13 +263,7 @@ guest platform have been tried by other Bochs users. -->
|
||||
|
||||
<section id="license"><title>Bochs License</title>
|
||||
<para>
|
||||
Bochs is copyrighted by MandrakeSoft S.A.<footnote>
|
||||
<para>
|
||||
Mandriva has a web site at
|
||||
<ulink url="http://mandriva.com">http://mandriva.com</ulink>
|
||||
</para>
|
||||
</footnote>
|
||||
and distributed under the
|
||||
Bochs is copyrighted by "The Bochs Project" team and distributed under the
|
||||
GNU Lesser General Public License<footnote>
|
||||
<para>
|
||||
Complete text of the GNU LGPL is included with the source code in a file
|
||||
@ -310,8 +303,8 @@ Before you install or use any Operating System, BIOS, or other software package
|
||||
within the Bochs PC emulation environment, make sure you are and will be in
|
||||
compliance with all the software licenses pertaining to the software you wish
|
||||
to install. It is completely your responsibility to provide licenses and records
|
||||
on all software that you install and/or use. It is also completely your responsibility to
|
||||
maintain total compliance with all Software Licenses involved.
|
||||
on all software that you install and/or use. It is also completely your responsibility
|
||||
to maintain total compliance with all software licenses involved.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -373,8 +366,9 @@ currently work with.
|
||||
<row>
|
||||
<entry>GUI Debugger</entry>
|
||||
<entry>Yes</entry>
|
||||
<entry>Chourdakis Michael and Bruce Ewing contributed very powerful GUI frontend for Bochs internal debugger.
|
||||
GUI debugger frontend is supported for Win32 and GTK2 hosts.
|
||||
<entry>Chourdakis Michael and Bruce Ewing contributed very powerful GUI
|
||||
frontend for Bochs internal debugger. GUI debugger frontend is supported for
|
||||
Win32 and GTK2/GTK3 hosts.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
@ -424,9 +418,9 @@ currently work with.
|
||||
<entry>Plug&play monitor</entry>
|
||||
<entry>Yes</entry>
|
||||
<entry>VESA DDC is now supported by all VGA compatible display adapters.
|
||||
The LGPL'd VGABIOS has been updated use this feature for both the VBE and
|
||||
Cirrus version. The interface reports a plug&play monitor called
|
||||
"Bochs Screen".
|
||||
The LGPL'd VGABIOS has been updated use this feature for the Bochs VBE,
|
||||
Voodoo Banshee and Cirrus versions. The interface reports a plug&play
|
||||
monitor called "Bochs Screen".
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
@ -468,10 +462,10 @@ currently work with.
|
||||
<row>
|
||||
<entry>Keyboard</entry>
|
||||
<entry>Yes</entry>
|
||||
<entry>Emulates a PS/2 keyboard with North American key mappings. Optional keyboard layout
|
||||
remapping files are provided to support localized keyboard in X11 (Belgian, Danish, French,
|
||||
German, Italian, Russian, Slovenian, Spanish, Swedish, U.K.) and SDL/SDL2
|
||||
(German).
|
||||
<entry>Emulates a PS/2 keyboard with North American key mappings. Optional
|
||||
keyboard layout remapping files are provided to support localized keyboard
|
||||
in X11 (12 layouts, e.g. French, German, Italian, Russian, Spanish, U.K.)
|
||||
and SDL/SDL2 (German).
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
@ -591,9 +585,10 @@ currently work with.
|
||||
<row>
|
||||
<entry>Take advantage of your SMP box</entry>
|
||||
<entry>Minimal</entry>
|
||||
<entry>At present, Bochs only uses threads in the lowlevel sound output
|
||||
code. The simulation itself uses only one thread, so it will not run any
|
||||
faster on multiprocessor hardware.
|
||||
<entry>At present, Bochs only uses threads in some guis, in the lowlevel
|
||||
sound output code and in the Voodoo graphics adapter code. The simulation
|
||||
core itself uses only one thread, so it will not run any faster on
|
||||
multiprocessor hardware.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
@ -694,8 +689,7 @@ code that displays the Bochs VGA screen and handles keyboard and mouse events.
|
||||
</question>
|
||||
<answer>
|
||||
<para>
|
||||
Yes! Bochs is released under the <ulink url="http://www.gnu.org/copyleft/lesser.html">GNU LGPL</ulink>,
|
||||
much thanks to MandrakeSoft (now called <ulink url="http://www.mandriva.com">Mandriva</ulink>).
|
||||
Yes! Bochs is released under the <ulink url="http://www.gnu.org/copyleft/lesser.html">GNU LGPL</ulink>.
|
||||
</para>
|
||||
</answer>
|
||||
</qandaentry>
|
||||
@ -2164,7 +2158,7 @@ SMP, x86_64 support) and the devices options (e.g. PCI, USB, Cirrus graphics).
|
||||
<entry>yes if debugger is on</entry>
|
||||
<entry>
|
||||
Enable support for the gui frontend of the Bochs debugger. This feature
|
||||
is supported on Windows hosts and on hosts with GTK2 installed.
|
||||
is supported on Windows hosts and on hosts with GTK2/GTK3 installed.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
@ -3310,7 +3304,8 @@ is always compiled in, unless Bochs is compiled for wx only. The choice
|
||||
"win32config" is only available on win32 and it is the default there.
|
||||
The choice "wx" is only available when Bochs is compiled with wxWidgets support,
|
||||
see <xref linkend="compile-wx">. If you do not write a config_interface line,
|
||||
Bochs will choose a default for you (usually textconfig).
|
||||
Bochs will choose a default for you (win32config on win32/win64 otherwise
|
||||
textconfig).
|
||||
</para>
|
||||
|
||||
<note><para>
|
||||
@ -6841,6 +6836,7 @@ display_library: x, options="gui_debug"
|
||||
the option to the display library is not necessary, since the command line
|
||||
interface is not available then.
|
||||
</para></note>
|
||||
<section><title>Overview</title>
|
||||
<para>
|
||||
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.
|
||||
@ -6857,14 +6853,176 @@ child windows for different purposes. Not all windows are visible at the same ti
|
||||
<listitem><para>Command button row</para></listitem>
|
||||
<listitem><para>CPU button row: only available for SMP emulation</para></listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
<section><title>The register window</title>
|
||||
<para>
|
||||
&FIXME; List the features here.
|
||||
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).
|
||||
</para>
|
||||
<para>Yes, the XMM display shows hex in the "decimal" column -- there is more
|
||||
room there. Deal with it.</para>
|
||||
<para>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.</para>
|
||||
</section>
|
||||
<section><title>The disassembly window</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>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->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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</section>
|
||||
<section><title>The MemDump window</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
The MemDump window loads/shows 4K of memory at a time.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem><para>PageUp/Down scrolls the display up or down through mem, 2K at a time</para></listitem>
|
||||
<listitem><para>Doubleclicking a line of memory allows you to change the byte values
|
||||
(Works on both linear and physical mem dumps)</para></listitem>
|
||||
<listitem><para>Doubleclicking with the Shift key down sets write watchpoints</para></listitem>
|
||||
<listitem><para>Doubleclicking with Alt sets read watchpoints</para></listitem>
|
||||
<listitem><para>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"</para></listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
<section><title>The output window</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</section>
|
||||
<section><title>The input window</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
Hitting Enter on a blank line will cause a Singlestep.
|
||||
</para>
|
||||
</section>
|
||||
<section><title>The param tree</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</section>
|
||||
<section><title>The stack window</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</section>
|
||||
<section><title>The breakpoint/watchpoint window</title>
|
||||
<para>
|
||||
Doubleclicking will delete a breakpoint or watchpoint.
|
||||
</para>
|
||||
</section>
|
||||
<section><title>The command button row</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</section>
|
||||
<section><title>The CPU button row</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</section>
|
||||
<section><title>Docking / Resizing</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.)
|
||||
</para>
|
||||
</section>
|
||||
<section><title>Additional Notes</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
Most of the gui debugger settings are now saved to an INI file on exit and
|
||||
restored at the next run.
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
</chapter><!-- end: Using Bochs internal debugger -->
|
||||
|
||||
<chapter id="howto"><title>Tips and Techniques</title>
|
||||
|
||||
@ -1,163 +0,0 @@
|
||||
User tips: (ver 1.2)
|
||||
|
||||
The main user features available from the menus 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 GUI debugger interface the CI, to distinguish it
|
||||
for themselves 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 of a term, but oh well.
|
||||
|
||||
The text debugger interface that you are all familiar with is called the
|
||||
Bochs Internal Debugger ("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", so that you can focus more strictly on
|
||||
the registers you are interested in (probably just the GP registers).
|
||||
|
||||
Notes:
|
||||
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.
|
||||
|
||||
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 more likely to see performance problems.
|
||||
|
||||
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. This 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.
|
||||
|
||||
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 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".
|
||||
|
||||
|
||||
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.
|
||||
|
||||
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 Param Tree:
|
||||
|
||||
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 Stack window:
|
||||
|
||||
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.
|
||||
|
||||
The Breakpoint/Watchpoint window:
|
||||
|
||||
Doubleclicking will delete a breakpoint or watchpoint.
|
||||
|
||||
The Command 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.
|
||||
|
||||
The CPU Button row:
|
||||
|
||||
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.
|
||||
|
||||
Docking/Resizing
|
||||
|
||||
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.)
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
KDE Users: The gtk-qt-engine drawing functions of Ver 0.71 (or anything earlier
|
||||
than 1.0?) draw all text as black, instead of in the correct foreground colors.
|
||||
Fix: Upgrade to 1.1.
|
||||
Loading…
Reference in New Issue
Block a user