Bochs User Manual | ||
---|---|---|
<<< Previous | Next >>> |
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.
![]() | This section describes how to enable and use the Bochs command line debugger. For its builtin graphical front-end please see the debugger gui section how to enable it. |
To use the debugger, you must configure Bochs with the
--enable-debugger
flag.
For example:
./configure --enable-debugger |
![]() | You must use flex version 2.5.4 or greater. I have heard that version 2.5.2 will not work. |
When you first start up Bochs, you will see the command line prompt
bochs:1> |
c continue executing cont continue s [count] execute count instructions, default is 1 step [count] s [cpu] [count] for SMP simulation, execute count instructions on cpu, default is 1 step [cpu] [count] s all [count] for SMP simulation, execute count instructions on all cpus step all [count] Ctrl-C stop execution, and return to command line prompt Ctrl-D if at empty line on command line, exit q quit debugger and execution quit exit |
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 vbreak seg:off if "expr" Set a conditional virtual address instruction breakpoint vb seg:off if "expr" lbreak addr Set a linear address instruction breakpoint lb addr lbreak addr if "expr" Set a conditional linear address instruction breakpoint lb addr if "expr" pbreak [*] addr Set a physical address instruction breakpoint pb [*] addr (the '*' is optional for GDB compatibility) break [*] addr b [*] addr pbreak [*] addr if "expr" Set a conditional physical address instruction breakpoint pb [*] addr if "expr" (the '*' is optional for GDB compatibility) break [*] addr if "expr" b [*] addr if "expr" info break Display state of all current breakpoints bpe n Enable a breakpoint bpd n Disable a breakpoint delete n Delete a breakpoint del n d n |
watch read addr Insert a read watch point at physical address |
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. writemem filename addr len dump a number of bytes of virtual memory starting from the specified linear address into a file loadmem filename addr initialize virtual memory starting from the specified linear address from a file deref addr deep pointer dereference. For example: get value of [[[rax]]] or ***rax: deref rax 3 crc addr1 addr2 Show CRC32 for physical memory range addr1..addr2 |
r|reg|regs|registers List of CPU integer registers and their contents fp|fpu List of all FPU registers and their contents mmx List of all MMX registers and their contents sse|xmm List of all SSE registers and their contents ymm|zmm List of all AVX registers and their contents amx|tile n Show AMX state and TILE register contents sreg Show segment registers and their contents dreg Show debug registers and their contents creg Show control registers and their contents info cpu List of all CPU registers and their contents info eflags Show decoded EFLAGS register info break Information about current breakpoint status info tab Show paging address translation info idt Show contents of the IDT info gdt Show contents of the GDT info ldt Show contents of the LDT info device Show state of the specified device |
set reg = expr Change a CPU register to value of expression. Currently only general purpose registers and instruction pointer are supported. You may not change eflags, segment registers, floating point or SIMD registers. Examples: set eax = 2+2/2 set esi = 2*eax+ebx registers List of CPU registers and their contents regs reg r calc|? expr Evaluate an expression and display the result. 'expr' can reference any general-purpose, opmask and segment registers, use any arithmetic and logic operations, and also special ':' operator which computes the linear address of a segment:offset (in real and v86 mode) or of a selector:offset (in protected mode) pair. Use $ operator for dereference, for example, get value of [[[rax]]] or ***rax: rax$3. |
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. disassemble switch-mode Switch between Intel and AT&T disassembly styles for debugger disassembler. disassemble size = n Tell debugger what segment size to use when the "disassemble" command is used. Use values of 0, 16 or 32 for n. Value of 0 means "use segment size specified by current CS segment". Default is 0. 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 the "disassemble size" variable is ignored. set disassemble on The same as 'set $auto_disassemble = 1' set disassemble off The same as 'set $auto_disassemble = 0' |
trace on Disassemble every executed instruction. Note that instructions which caused exceptions are not really executed, and therefore not traced. trace off Disable instruction tracing. trace-mem on/off Enable/Disable memory access tracing. |
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" |
./configure [...] --enable-instrumentation="instrument/myinstrument" |
instrument [command] calls BX_INSTR_DEBUG_CMD instrumentation callback with [command] instrument "[command string]" calls BX_INSTR_DEBUG_CMD instrumentation callback with [command string] |
ptime |
sb |
sba |
print-stack [ |
num words
top 16-bit words on the stack. Num
words
defaults to 16. Only works reliably in protected mode when
the base address of the stack segment is zero.
print-string addr |
bt [num_entries] |
source file |
addlyt file |
Example of use:
Create a script file (script.txt) with the following content
regs print-stack 7 u /10 (*EMPTY NEW LINE) |
Execute addlyt
addlyt "script.txt" |
Then, when you execute a step/DebugBreak... you will see: registers, stack and disasm.
remlyt |
lyt |
modebp |
ldsym [global] |
filename
. If the global keyword is
added, then the the symbols will be visible in all contexts for which
symbols have not been loaded. Offset
(default is 0) is added to
every symbol entry. The symbols are loaded in the current (executing)
context.The symbol file consists of zero or more lines of the format
"%x %s" |
setmagicbps "cx dx bx sp bp si di" |
setmagicbps "di sp" |
clrmagicbps "cx dx bx sp bp si di" |
clrmagicbps "di sp" |
show [ |
Toggles show symbolic info (calls to begin with). show - shows current show mode show mode - show, when processor switch mode show int - show, when interrupt is happens show call - show, when call is happens show ret - show, when iret is happens show off - toggles off symbolic info show dbg-all - turn on all show flags show dbg-none - turn off all show flags |
For information on advanced debugger usage see the developer documentation
(under construction).
<<< Previous | Home | Next >>> |
Mailing Lists | The Bochs debugger GUI |