mirror of https://github.com/bochs-emu/Bochs
379 lines
12 KiB
HTML
379 lines
12 KiB
HTML
<HTML>
|
|
|
|
<HEAD>
|
|
<META NAME="resource-type" CONTENT="document">
|
|
<META NAME="distribution" CONTENT="GLOBAL">
|
|
<META NAME="description" CONTENT="Bochs command line debugger">
|
|
<META NAME="copyright" CONTENT="Copyright 2001 by MandrakeSoft S.A.">
|
|
<META NAME="keywords" CONTENT="pc emulation, x86 emulation, emulator">
|
|
<META NAME="Author" CONTENT="Kevin Lawton">
|
|
<META HTTP-EQUIV="Content-Type" CONTENT="text/html;CHARSET=iso-8859-1">
|
|
<TITLE>Bochs Debugger</TITLE>
|
|
</HEAD>
|
|
|
|
<BODY TEXT="#000000" BGCOLOR="#ececec" LINK="#3333cc" VLINK="#666666">
|
|
|
|
<CENTER><H1>Debugger</H1></CENTER>
|
|
|
|
<P>
|
|
Note, if you are looking for a graphical front-end for the
|
|
bochs debugger, you may want to check out
|
|
<a href="http://www.qzx.com/bfe/">BFE</a>. This is a
|
|
package written by a bochs user which can interface with
|
|
the text based bochs debugger. No linking is necessary.
|
|
It's not part of bochs, but you may find it useful.
|
|
|
|
<P>
|
|
You can now conditionally compile in a GDB like command line debugger, that
|
|
allows you to set breakpoints, step through instructions, and other
|
|
useful functions. If there isn't a command for something you believe
|
|
is generally useful for the debugger, let me know and I'll implement
|
|
it if possible.
|
|
<P>
|
|
To use the debugger, you must configure bochs with the
|
|
'--enable-debugger' and '--enable-disasm' flags. For example:
|
|
|
|
<PRE>
|
|
./configure --enable-debugger --enable-disasm
|
|
</PRE>
|
|
|
|
NOTE: You must use flex version 2.5.4 or greater. I have heard that
|
|
version 2.5.2 will not work.
|
|
<P>
|
|
When you first start up bochs, you will see the command line prompt
|
|
|
|
<PRE>
|
|
bochs:1>
|
|
</PRE>
|
|
|
|
From here, you may use the following commands:
|
|
|
|
<H3>Execution Control</H3>
|
|
<PRE>
|
|
c Continue executing
|
|
stepi [count] execute count instructions, default is 1
|
|
si [count] execute count instructions, default is 1
|
|
step [count] execute count instructions, default is 1
|
|
s [count] execute count instructions, default is 1
|
|
Ctrl-C stop execution, and return to command line prompt
|
|
Ctrl-D if at empty line on command line, exit
|
|
quit quit debugger and execution
|
|
q quit debugger and execution
|
|
</PRE>
|
|
<H3>BreakPoints</H3>
|
|
<PRE>
|
|
NOTE: The format of 'seg', 'off', and 'addr' in these descriptions,
|
|
are as follows. I don't have any way to set the current radix.
|
|
|
|
hexidecimal: 0xcdef0123
|
|
decimal: 123456789
|
|
octal: 01234567
|
|
|
|
vbreak seg:off Set a virtual address instruction breakpoint
|
|
vb seg:off
|
|
|
|
lbreak addr Set a linear address instruction breakpoint
|
|
lb addr
|
|
|
|
pbreak [*] addr Set a physical address instruction breakpoint
|
|
pb [*] addr (the '*' is optional for GDB compatibility)
|
|
break [*] addr
|
|
b [*] addr
|
|
|
|
info break Display state of all current breakpoints
|
|
delete n Delete a breakpoint
|
|
del n
|
|
d n
|
|
</PRE>
|
|
|
|
<H3>Manipulating Memory</H3>
|
|
<PRE>
|
|
x /nuf addr Examine memory at linear address addr
|
|
xp /nuf addr Examine memory at physical address addr
|
|
n Count of how many units to display
|
|
u Unit size; one of
|
|
b Individual bytes
|
|
h Halfwords (2 bytes)
|
|
w Words (4 bytes)
|
|
g Giant words (8 bytes)
|
|
NOTE: these are *not* typical Intel nomenclature sizes,
|
|
but they are consistent with GDB convention.
|
|
f Printing format. one of
|
|
x Print in hexadecimal
|
|
d Print in decimal
|
|
u Print in unsigned decimal
|
|
o Print in octal
|
|
t Print in binary
|
|
|
|
n, f, and u are optional parameters. u and f default to the last values
|
|
you used, or to w(words) and x(hex) if none have been supplied.
|
|
n currently defaults to 1. If none of these optional parameters are
|
|
used, no slash should be typed. addr is also optional. If you don't
|
|
specify it, it will be the value the next address (as if you had
|
|
specified n+1 in the last x command).
|
|
|
|
setpmem addr datasize val Set physical memory location of size
|
|
datasize to value val.
|
|
|
|
crc addr1 addr2 Show CRC for physical memory range addr1..addr2
|
|
info dirty Show physical pages dirtied (written to) since last display
|
|
Values displayed are the top 20 bits only (page addresses)
|
|
|
|
</PRE>
|
|
|
|
<H3>Info</H3>
|
|
<PRE>
|
|
info program Execution status of the program
|
|
info registers List of CPU integer registers and their contents
|
|
info break Information about current breakpoint status
|
|
</PRE>
|
|
|
|
<H3>Manipulating CPU Registers</H3>
|
|
<PRE>
|
|
set $reg = val Change a CPU register to value val. Registers may be one of:
|
|
eax, ecx, edx, ebx, esp, ebp, esi, edi.
|
|
Currently, you may not change:
|
|
eflags, cs, ss, ds, es, fs, gs.
|
|
|
|
Examples: set $eax = 0x01234567
|
|
set $edx = 25
|
|
|
|
info registers See Info section
|
|
dump_cpu Dump complete CPU state
|
|
set_cpu Set complete CPU state
|
|
|
|
Format of "dump_cpu" and "set_cpu":
|
|
"eax:0x%x\n"
|
|
"ebx:0x%x\n"
|
|
"ecx:0x%x\n"
|
|
"edx:0x%x\n"
|
|
"ebp:0x%x\n"
|
|
"esi:0x%x\n"
|
|
"edi:0x%x\n"
|
|
"esp:0x%x\n"
|
|
"eflags:0x%x\n"
|
|
"eip:0x%x\n"
|
|
"cs:s=0x%x, dl=0x%x, dh=0x%x, valid=%u\n"
|
|
"ss:s=0x%x, dl=0x%x, dh=0x%x, valid=%u\n"
|
|
"ds:s=0x%x, dl=0x%x, dh=0x%x, valid=%u\n"
|
|
"es:s=0x%x, dl=0x%x, dh=0x%x, valid=%u\n"
|
|
"fs:s=0x%x, dl=0x%x, dh=0x%x, valid=%u\n"
|
|
"gs:s=0x%x, dl=0x%x, dh=0x%x, valid=%u\n"
|
|
"ldtr:s=0x%x, dl=0x%x, dh=0x%x, valid=%u\n"
|
|
"tr:s=0x%x, dl=0x%x, dh=0x%x, valid=%u\n"
|
|
"gdtr:base=0x%x, limit=0x%x\n"
|
|
"idtr:base=0x%x, limit=0x%x\n"
|
|
"dr0:0x%x\n"
|
|
"dr1:0x%x\n"
|
|
"dr2:0x%x\n"
|
|
"dr3:0x%x\n"
|
|
"dr4:0x%x\n"
|
|
"dr5:0x%x\n"
|
|
"dr6:0x%x\n"
|
|
"dr7:0x%x\n"
|
|
"tr3:0x%x\n"
|
|
"tr4:0x%x\n"
|
|
"tr5:0x%x\n"
|
|
"tr6:0x%x\n"
|
|
"tr7:0x%x\n"
|
|
"cr0:0x%x\n"
|
|
"cr1:0x%x\n"
|
|
"cr2:0x%x\n"
|
|
"cr3:0x%x\n"
|
|
"cr4:0x%x\n"
|
|
"inhibit_int:%u\n"
|
|
"done\n"
|
|
|
|
Notes:
|
|
- s is the selector
|
|
- dl is the shadow descriptor low dword (4 byte quantitiy)
|
|
- dh is the shadow descriptor high dword (4 byte quantitiy)
|
|
- valid denotes if the segment register holds a validated shadow descriptor
|
|
- inhibit_int is set if the previous instruction was one which delays the
|
|
acceptance of interrupts by one instruction (STI, MOV SS)
|
|
- any errors encountered by the set_cpu command, are reported by
|
|
"Error: ...". They may be reported after any of the input lines,
|
|
or after the "done" line, during limit checks.
|
|
- A successful set_cpu command ends with the separate line:
|
|
"OK".
|
|
|
|
</PRE>
|
|
|
|
<H3>Disassembly commands</H3>
|
|
<PRE>
|
|
disassemble start end Disassemble instructions in given linear address
|
|
range, inclusive of start, exclusive of end.
|
|
Use "set $disassemble_size =" to tell
|
|
debugger desired segment size. Use a value for
|
|
end of less than start (or zero) if you only
|
|
want the first instruction disassembled.
|
|
set $disassemble_size = n Tell debugger what segment size to use when
|
|
the "disassemble" command is used. Use values
|
|
of 16 or 32 for n. Default is 32.
|
|
|
|
set $auto_disassemble = n Cause debugger to disassemble current instruction
|
|
every time execution stops if n=1. Default is 0.
|
|
Segment size of current CPU context is used for
|
|
disassembly, so variable "$disassemble_size" is
|
|
ignored.
|
|
</PRE>
|
|
|
|
<H3>Instrumentation</H3>
|
|
<PRE>
|
|
|
|
To use instrumentation features in bochs, you must compile in support for it.
|
|
You should build a custom instrumentation library in a separate directory in
|
|
the "instrument/" directory. To tell configure which instrumentation library
|
|
you want to use, use the "--enable-instrumentation" option.
|
|
|
|
The default library consists of a set of stubs, and the following are
|
|
equivalent:
|
|
|
|
./configure [...] --enable-instrumentation
|
|
./configure [...] --enable-instrumentation="instrument/stubs"
|
|
|
|
You could make a separate directory with your custom library,
|
|
for example "instrument/myinstrument", copy the contents of
|
|
the "instrument/stubs" directory to it, then customize it. Use:
|
|
|
|
./configure [...] --enable-instrumentation="instrument/myinstrument"
|
|
</PRE>
|
|
|
|
<H3>Instrumentation commands</H3>
|
|
<PRE>
|
|
instrument start calls bx_instr_start()
|
|
instrument stop calls bx_instr_stop()
|
|
instrument reset calls bx_instr_reset()
|
|
instrument print calls bx_instr_print()
|
|
</PRE>
|
|
|
|
|
|
<HR>
|
|
<h2>New Commands</h2>
|
|
|
|
<h3>trace-on</h3>
|
|
|
|
Disassemble every executed instruction. Note that instructions that
|
|
cause exceptions are not really executed, and therefore not traced.
|
|
|
|
<h3>trace-off</h3>
|
|
|
|
Disable tracing.
|
|
|
|
<h3>ptime</h3>
|
|
|
|
Print the current time (number of ticks since start of simulation
|
|
(modulo 2^32)).
|
|
|
|
<h3>sb <i>delta</i></h3>
|
|
|
|
Insert a time break point <i>delta</i> instructions into the future.
|
|
|
|
<h3>sba <i>time</i></h3>
|
|
|
|
Insert a time break point at <i>time</i>.
|
|
|
|
<h3>record <i>filename</i></h3>
|
|
|
|
Record console input to file <i>filename</i>. The file consists of
|
|
zero or more lines of the form "%s %d %x", where the first word is the
|
|
event type, the second is a time stamp and the third is event specific
|
|
data.
|
|
|
|
<h3>playback <i>filename</i></h3>
|
|
|
|
Playback console input from file <i>filename</i>. Additional input can
|
|
be given directly in the console window. Events in the file will be
|
|
played back at times relative to the time when the playback command
|
|
was executed.
|
|
|
|
<h3>print-stack [<i>num words</i>]</h3>
|
|
|
|
Print the <i>num words</i> top 16-bit words on the stack. <i>Num
|
|
words</i> defaults to 16. Only works reliably in protected mode when
|
|
the base address of the stack segment is zero.
|
|
|
|
<h3>watch stop</h3>
|
|
|
|
Stop the simulation (and return to prompt) when a watch point is
|
|
encountered.
|
|
|
|
<h3>watch continue</h3>
|
|
|
|
Do not stop the simulation when watch points are encountered. They will
|
|
still be logged.
|
|
|
|
<h3>watch</h3>
|
|
|
|
Print current watch point status.
|
|
|
|
<h3>unwatch</h3>
|
|
|
|
Remove all watch points.
|
|
|
|
<h3>watch read <i>address</i></h3>
|
|
|
|
Insert a read watch point at physical address <i>address</i>.
|
|
|
|
<h3>watch write address</h3>
|
|
|
|
Insert a write watch point at physical address <i>address</i>.
|
|
|
|
<h3>unwatch read <i>address</i></h3>
|
|
|
|
Remove read watch point from physical address <i>address</i>.
|
|
|
|
<h3>unwatch write <i>address</i></h3>
|
|
|
|
Remove write watch point from physical address <i>address</i>.
|
|
|
|
<h3>modebp [<i>string</i>]</h3>
|
|
|
|
Insert documentation here.
|
|
|
|
<h3>load-symbols [global] <i>filename</i> [<i>offset</i>]</h3>
|
|
|
|
Load symbols from file <i>filename</i>. If the global keyword is
|
|
added, then the the symbols will be visible in all contexts for which
|
|
symbols have not been loaded. <i>Offset</i> (default is 0) is added to
|
|
every symbol entry. The symbols are loaded in the current (executing)
|
|
context.<p>
|
|
|
|
The symbol file consists of zero or more lines of the format <tt>"%x
|
|
%s"</tt>.
|
|
|
|
<h3>show [<i>string</i>]</h3>
|
|
|
|
Insert documentation here.
|
|
|
|
<p>
|
|
<p>
|
|
<p>
|
|
|
|
<h2>Resource file extensions</h2>
|
|
|
|
<h3>time0: <i>time</i></h3>
|
|
|
|
Specifies the start (boot) time of the virtual machine. Use a
|
|
<i>time</i> value as returned by the time(2) system call. <i>Time</i>
|
|
equal to 1 is a special case which starts the virtual machine at the
|
|
current time of the simulator host.
|
|
|
|
<h3>cdromd: dev=<i>device</i>, status=(inserted|ejected)</h3>
|
|
|
|
LoseNT needs a CD in order to boot properly. Our simulated CD-ROM unit
|
|
communicates directly with the CD-ROM driver in Linux. <i>Device</i>
|
|
is a device special file to which the CD-ROM driver is connected
|
|
(typically /dev/hdc). <i>Device</i> is ignored if status=ejected.
|
|
|
|
<HR>
|
|
<P>
|
|
Related Links:
|
|
<UL>
|
|
<LI><A HREF="cosimulation.html">Cosimulation</A>
|
|
<LI><A HREF="instrumentation.html">Instrumentation</A>
|
|
</UL>
|
|
|
|
</BODY>
|
|
</HTML>
|