docs-html/win32_enh_dbg_user_man.txt

   1 User tips: (ver 1.0)
   2
   3 The main user features available from the menus should be fairly obvious
   4 to anyone who has used bochs -- but here are a few quick explanations, anyway.
   5 These explanations include a few keyboard and mouse shortcuts that you might
   6 not find through experimentation.
   7
   8 Terminology:
   9 The Bochs guys call this GUI debugger interface the CI, to distinguish it
  10 for themselves from the "VGA window" that shows the display of the simulated
  11 computer. I will call this debugger GUI interface the "frontend". It's not
  12 much better of a term, but oh well.
  13
  14 The text debugger interface that you are all familiar with is called the
  15 Bochs Internal Debugger ("ID" for short).
  16
  17 The frontend is organized around 3 main "list-view" windows:
  18
  19 The Register window:
  20 Typically, all the various registers are grouped by color. If you don't like the
  21 colors, they can be turned off, or modified at compile time. There are options
  22 to show or hide most register "groups", so that you can focus more strictly on
  23 the registers you are interested in (probably just the GP registers).
  24
  25 Notes: Sometimes (on CPU mode changes, or when windows are being moved), the
  26 System Registers (GDTR, IDTR, LDTR, TR) will appear on the Register list for
  27 one "step". This is not a bug -- it is a kludge to get the columns to be the
  28 right width.
  29
  30 Yes, the XMM display shows hex in the "decimal" column -- there is more
  31 room there. Deal with it.
  32
  33 ** Doubleclicking a register attempts to change its value. Bochs may not
  34 allow you to change most registers. In future versions, more registers may
  35 be modifiable.
  36
  37 The Disassembly window:
  38 Disassembly output that is autoloaded, or generated from the menu, ends up
  39 here. If the frontend cannot detect the "current instruction" in the list,
  40 when it reaches the next instruction -- then it will autoload a new list.
  41 Having a big list will reduce the number of autoloads, and allows you to see
  42 more. The list can contain up to 2048 lines. However, if you load more than
  43 1000 lines, you are likely to see big performance problems in Windows on
  44 certain occasions -- like minimizing and then restoring the window. This is
  45 a Windows bug/"feature".
  46
  47 Note: There are two kinds of emulated memory in bochs: Linear and Physical.
  48 Emulated Linear memory is mapped onto Physical memory by x86 virtual memory
  49 methods (paging and segmentation). If paging and segmenataion are "off", or
  50 "identity mapped", then both "types" of memory mean the same thing. But they
  51 still work a little differently. With the Internal Debugger, you can set
  52 breakpoints to either kind of memory, separately. Normally, you would use
  53 the "b" command to set breakpoints in physical mem, and "lb" to set breakpoints
  54 in linear mem. This frontend ONLY displays linear breakpoints. It does not
  55 bother trying to figure out the linear->phsical reverse mapping to show
  56 physical breakpoints. (There are also "virtual" breakpoints that are also
  57 not shown.) All the types of breakpoints still WORK, it is just that you
  58 will not see them marked on the screen.
  59
  60 It will be obvious to you that the current instruction is marked in green,
  61 unless it is on a breakpoint, when it turns blue. Breakpoints are red, of
  62 course.
  63
  64 ** You must click a line in the window, before you can use frontend commands
  65 to set or clear a linear breakpoint on it.
  66 ** You can doubleclick (which saves steps) to set or clear a linear breakpoint.
  67
  68 ** If you do a Find command to select a bunch of ASM lines, you can set linear
  69 breakpoints to all of them at once, with the F6/Breakpoint command. However,
  70 there is a limit compiled into bochs on the maximum number number of linear
  71 breakpoints. The typical limit is TEN. Edit your config.h if you want more.
  72
  73 The MemDump window:
  74
  75 As of this version, the MemDump window isn't much more than a display of the
  76 contents of memory. In later versions, hopefully it will be expanded into a
  77 fairly fully-featured hexeditor. You can dump either phyical mem, or linear
  78 mem. There are breakpoint-like things (that work with physical memory only,
  79 currently), called "watchpoints". A physical memory address can cause a break
  80 in the simulation if it is read, or written.
  81
  82 The frontend again does NOT try to calculate out the linear -> physical mapping
  83 in any attempt to display the physical watchpoints while viewing linear mem.
  84
  85 You must click a hex byte (on a physical mem dump that shows bytes), in order to
  86 set or clear a read and/or write watchpoint on that byte. Read watchpoints are
  87 green (on black), write watchpoints are red, watchpoints that are both write
  88 and read are blue. There is a hardcoded limit in bochs of 16 of each type of
  89 watchpoint.
  90
  91 The MemDump window loads/shows 4K of memory at a time.
  92
  93 ** PageUp/Down scrolls the display up or down through mem, 2K at a time.
  94 ** Doubleclicking a line of memory allows you to change the byte values.
  95 (Works on both linear and physical mem dumps.)
  96 ** Doubleclicking with the Shift key down sets write watchpoints.
  97 ** Doubleclicking with Control sets read watchpoints.
  98 ** You can use both Shift and Control at the same time.
  99 ** You need to click once on the memory window before you can use its "Find"
 100 function. The Find function is pretty limited in scope, currently. It can
 101 only find bytes (or strings of bytes) within each 16byte "line".
 102
 103
 104 Other windows:
 105
 106 The Output window shows anything that the Bochs Internal Debugger tries to send
 107 to you. The window is scrollable, but only keeps a limited history of output (10K).
 108 The ID is always spamming you with "Next at t=" and disassembly lines, that would
 109 tend to fill up the Output window with garbage -- so there are options to ignore
 110 either of these types of output.
 111
 112 The Input window is for sending user commands directly into the Bochs Internal
 113 Debugger -- bypassing the frontend. Results will appear in the Output Window.
 114 The Input window has a history feature for commands, using the Up and Down arrows --
 115 it remembers 64 commands, 80 bytes each. No matter where you click on the frontend,
 116 you can always type directly into the Input box without clicking on it.
 117
 118 When the Input window is invisible, you should still be able to type into it --
 119 after taking into account the bug listed at the bottom of this file.
 120
 121 ** Hitting Enter on a blank line will cause a Singlestep.
 122
 123 The Param Tree:
 124
 125 The bochs param_tree shows the internal state of most of bochs. It will be
 126 expanded in the future to show even more. You can see the detailed state of
 127 all cpu registers -- including the "hidden" parts (look in the "bochs" branch).
 128 Or see the current state of most of the emulated hardware.
 129
 130 The Stack window:
 131
 132 The MemDump windows do not automatically refresh -- except for the Stack
 133 window. If you leave the stack window active, it will update as the stack
 134 changes. If you want to update the other MemDump windows with fresh data,
 135 hit Refresh.
 136
 137 The Command Button row:
 138
 139 Just a (hopefully) convenient way of using the mouse, instead of the keyboard.
 140 If you don't like them, or they take up too much space, you can turn them off.
 141
 142 The CPU Button row:
 143
 144 This only shows up when you are running a multi-cpu simulation. Click on the
 145 CPU that you want to view. All CPUs are always stepped together, and they all
 146 stop the first time one hits some sort of breakpoint.
 147
 148 Docking/Resizing:
 149
 150 If you grab one of the two vertical "bars" between the lists, you can horizontally
 151 resize the lists. The cursor will change, but there will be no animation.
 152
 153 If you grab the middle of one of the lists, and drag it on top of one of the
 154 other lists, you can reorder the positions of the lists on the screen. The
 155 cursor will change, but there will be no animation. You can set an alternate
 156 "docking order" at compile time, also, if you have a permanent preference.
 157 (See the top of the wenhdbg_h.h file, for compile-time customization.)
 158
 159 Additional Notes:
 160
 161 If you have a really big GDT or Paging display in the MemDump window, and you
 162 select a different display, it may take several seconds to delete the big display
 163 before it can switch. Additionally, note the "windows feature" listed above --
 164 it is not wise to minimize the display, if one of the lists is really big.
 165
 166 Uppercase text tends to seem a little annoying, but it really is a lot easier to
 167 read, especially on a proportional font. If you change to a fixed font, then you
 168 may want to switch the display to lowercase.
 169
 170 ############
 171 Known bug: if the frontend window is hidden or minimized, then restored -- you
 172 will not be able to type into the Input window until you click somewhere.
 173