1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
Information about the DOSBox-X Debugger
Debugger interface
------------------
In builds where it is enabled, DOSBox-X supports breaking into the debugger
interface, which is shown on the console.
A mapper shortcut is provided to break into the debugger on demand. Normally
this shortcut is set to Alt+Pause (Mac: Alt+F12).
In Windows, DOSBox-X can create a console and show the debugger interface
on it.
On other systems including Linux and Mac OS X, DOSBox-X must be started
from a terminal in order to enable the debugger.
The debugger interface should scale and respond to resizing of the
terminal window.
WARNING: Fitting to the window was added in DOSBox-X. The debugger
interface in DOSBox SVN requires a minimum terminal window
size to function, and may segfault if the terminal is too
small.
The debugger interface is written against the "ncurses" library.
The window regions of the debugger interface are:
- Register Overview
- Data view
- Code Overview
- Variable (not shown by default)
- Output
The register window will show at all times the contents of the CPU
registers and segment registers as well as other important CPU
state.
Data view allows viewing the contents of memory while debugging.
The location shown is controlled by a segment:offset pair.
In DOSBox-X, the Data view also permits viewing data as a linear
(pageable) offset and as a physical memory view (outside the
CPU's paging control).
The code overview/disassembly window shows the contents of a
memory location as disassembled x86 instructions. Normally, this
is set to the instruction pointer, but it can be set anywhere.
Decoding is based on the CPU mode.
The variable list is used when the debugger is given variables
to debug by.
The output window allows you to scroll through the last 1000
or so log messages written from within the codebase by LOG()
or LOG_MSG(). If the window is scrolled to the bottom, new
messages will appear by default.
The lowest row of the terminal is reserved for a line where
the user can enter debugger commands. An underscore shows
where the cursor is positioned.
The code and data views have been fixed in DOSBox-X to indicate
when data is not available to view for a specific segment:offset
or linear address.
If the CPU is in protected mode, and the segment portion refers
to a segment that does not exist, or the offset extends past
the limit of that segment, the code or data view will show
'na' instead of a byte value.
If 80386 paging is enabled, and the segment:offset or linear
address refers to a page that is not present, then the data
view will show 'pf' to indicate this.
na = segment does not exist, or offset exceeds segment limit
pf = segment:offset or linear address is paged out or
not present according to page tables.
Debugging a program and breaking on start
-----------------------------------------
DOSBox-X includes a built-in command to launch a program and
break at the entry point.
DEBUGBOX [command] [options]
You can also type DEBUGBOX without a parameter to start the
debugger.
Debugger keyboard shortcuts
---------------------------
Tab/Shift+Tab Switch to the next/previous window
F3/F6 Previous command in history
F4/F7 Next command in history
F5 Resume emulation
F8 Toggle printable characters display in data view
F9 Set/clear breakpoint
F10 Single step (over)
F11 Single step (into)
Up arrow Scroll up one line (if applicable)
Down arrow Scroll down one line (if applicable)
Left arrow Move cursor left in command line
Right arrow Move cursor right in command line
Page Up/Fn+Up Scroll up by window height (if applicable)
Page Down/Fn+Down Scroll down by window height (if applicable)
Home/Fn+Left Scroll to top (in Output window)
End/Fn+Right Scroll to bottom (in Output window)
Insert Toggle insert/overwrite mode in command line
Alt+D Set data view to DS:SI
Alt+E Set data view to ES:DI
Alt+X Set data view to DS:DX
Alt+B Set data view to ES:BX
Alt+S Set data view to SS:SP
Debugger commands
-----------------
MOVEWINDN Move current window down
MOVEWINDU Move current window up
SHOWWIN <winname> Show window (by name)
HIDEWIN <winname> Hide window (by name)
MEMDUMP <seg> <off> <bytecount> Dump memory to file (MEMDUMP.TXT)
MEMDUMPBIN <seg> <off> <bytecount> Dump memory to file (MEMDUMP.BIN)
IV <seg> <off> <name> Insert variable
SV <name> Save variables to <name>
LV <name> Load variables from <name>
SR <reg> <value> Set register <reg> value to <value>
SM <seg> <off> [bytes in hex] Set memory at <seg>:<off> to byte values given
BP <seg> <off> Add breakpoint (real mode)
BPM <seg> <off> Add breakpoint (protected mode)
BPLM <offset> Add breakpoint (linear/virtual address)
BPINT <intnum> Add breakpoint on interrupt
BPINT <intnum> <value> Add breakpoint on interrupt and AH=<value>
BPLIST List breakpoints
BPDEL <breakpoint number> Delete breakpoint
RUN Resume emulation
RUNWATCH Resume emulation, but show state while running
A20 Show A20 gate state
A20 ON Turn on A20 gate
A20 OFF Turn off A20 gate
PIC Show interrupt controller state
PIC MASKIRQ <irq> Mask IRQ at interrupt controller
PIC UNMASKIRQ <irq> Unmask IRQ at interrupt controller
PIC ACKIRQ <irq> Acknowledge IRQ at interrupt controller
PIC LOWERIRQ <irq> Manually lower interrupt signal
PIC RAISEIRQ <irq> Manually raise interrupt signal
C <seg> <off> Set code view to address
D <seg> <off> Set data view to address (segment:offset)
DV <offset> Set data view to address (linear/virtual address)
DP <offset> Set data view to address (physical)
LOG <hexadecimal count> Log CPU state, for the specified number of instructions, to LOGCPU.TXT
LOGS <hexadecimal count> Log CPU state, short log, to LOGCPU.TXT
LOGL <hexadecimal count> Log CPU state, long log, to LOGCPU.TXT
INTT <intnum> Trace interrupt
INT <intnum> Start interrupt
CALLBACKS Show callbacks of interrupts.
SELINFO <n> Show selector information
DOS MCBS Dump DOS kernel MCB chain (conventional memory allocation chain)
DOS KERN Dump DOS kernel memory allocation list
DOS XMS Dump XMS (extended memory) allocation list
DOS EMS Dump EMS (expanded memory) allocation list
BIOS MEM Dump BIOS allocation and layout list
GDT Dump GDT (global descriptor table)
LDT Dump LDT (local descriptor table)
IDT Dump IDT (interrupt descriptor table)
PAGING Dump page table information
CPU Dump additional CPU information
VGA cmd VGA related debugging commands.
PC98 cmd PC98 related debugging commands.
EMU MEM/MACHINE Show emulator memory or machine info.
INTVEC <file> Dump interrupt vector table to <file>
INTHAND <intnum> Set code view to start of interrupt handler
EXTEND Toggle additional information
TIMERIRQ Start timer IRQ
TIME <time> Display or change the internal time
DATE <date> Display or change the internal date
HEAVYLOG Toggle heavy CPU logging
ZEROPROTECT Toggle zero protection
HELP Show some debugger commands for reference
|
