DOS-debug

1

2
 1. About Debug/X
3

4
    Debug/X is a package of debuggers. The most important ones are:
5
    
6
    - Debug: is a clone of the MS-DOS DEBUG command - although, "clone"
7
      isn't the correct name, because it has many features not available in
8
      the original MS DEBUG. For details see below. 
9

10
    - DebugX: is an extended version of Debug that allows to debug both
11
      real-mode and protected-mode (DPMI) DOS programs.
12

13
    - additional variants like DebugXv, DebugXg, DebugB or DebugR that are
14
      useful for special cases. For details see below.
15

16

17
 2. Added/Missing Features
18

19
  a. Debug extends MS-Debug in the following ways:
20

21
   - The assembler and disassembler support all publicly documented
22
     instructions for Intel chips through the Pentium Pro (P6), except for
23
     the MMX instructions (as for DebugX, MMX is partially supported since
24
     v1.18). The assembler and disassembler inform you if any instruction is 
25
     inappropriate for the current processor.
26

27
   - FPU Opcodes are supported.
28

29
   - The current processor (for the purposes of assembler and disassembler
30
     warnings, above) can be declared to be something else via the following
31
     commands:
32

33
        m [x] set current processor.
34
              x=0 current processor is 8088.
35
              x=1..6 current processor is 80x86. 80586 is a Pentium and
36
              80686 is a Pentium Pro.
37
              no argument = print current CPU/FPU types.
38
        mc [2|N] set math coprocessor. 
39
             2 = math coprocessor is a 287 (only valid if current
40
                 processor is a 386).
41
             N = math coprocessor is absent
42
             no argument = math coprocessor is present
43

44
   - 'r register [value]' accepts 32-bit register names (for cpu 80386+).
45

46
   - You can do `r cx 1234' instead of having to put the `1234' on a
47
     separate line.
48

49
   - 'rn' displays FPU register status.
50
      Just the raw hex values of the registers are displayed, though.
51

52
   - 'rx' switches among 8086 and 80386 register display (for cpu 80386+).
53

54
   - When doing `debug < file', debug will not hang if it reaches an end of
55
     file before encountering a `q' command.
56

57
   - This debugger saves and restores the program's Control-C and critical
58
     error interrupts, providing for better isolation between the debugger
59
     and the program being debugged.
60

61
   - 'tm 0|1' sets trace command mode, 0 = process INTs (default),
62
     1 = single-step INTs (the MS-DOS Debug compatible mode).
63

64
   - 'xr' allows to reallocate an EMS handle and 'xa' allows to allocate
65
     an "empty" EMS handle (with zero pages) - but only if an EMM v4.0
66
     is present.  
67

68
   - Besides 'i' and 'o' exist the variations 'iw', 'id', 'ow' and 'od'
69
     to read/write a WORD or DWORD value from/to a port [DWORD values
70
     require a 80386+ cpu].
71

72
   - 'h' can handle dword values.
73

74
   - register names can be used anywhere where a number is expected as
75
     input. That is, things like "u cs:ip" do work.
76

77
   - 'dm' displays the DOS memory control block (MCB) chain and the
78
     current PSP.
79

80
   - if DOS has set its InDOS flag, Debug will avoid to use int 21h
81
     internally, which allows to single-step through DOS code.
82

83
   - 'd', 't' and 'u' are automatically repeated if a blank line is
84
     entered.
85

86
  b. DebugX has the following additional features:
87

88
   - besides real-mode applications it can debug both 16-bit and 32-bit
89
     DPMI clients.
90
     [To debug DPMI clients a DPMI host has to be installed. Tested with
91
      cwsdpmi, hdpmi, WinXP NTVDM, 32rtm. In DosEmu and Windows 95/98/ME
92
      DOS boxes it is required to single-step through the initial switch
93
      to protected-mode, else DebugX will loose control of the debuggee.]
94

95
   - 'dl': display LDT descriptor(s) (in protected-mode only)
96

97
   - 'di': display interrupt vector(s)
98

99
   - 'dx': display extended memory (read via Int 15h, ah=87h). Requires a
100
     80386 cpu. 'dx' is automatically repeated if a blank line is entered.
101
     Be aware that Int 15h, ah=87h most likely will disable "unreal"-mode
102
     if it was enabled. This may be an unwanted side effect during debugging.
103

104
   - 'g','p','t': the 80386+ debug registers may be used if breakpoints are
105
     to be set. This allows setting breakpoints in code that is read-only.
106
     The feature may be switched off by cmdline option /s. It's never active
107
     if DebugX runs on NTVDM or DosEmu, since the debug registers aren't
108
     accessible there.
109

110
   - 'rn' displays FPU registers in "readable" format.
111

112
   - when running in a Windows XP DOS bos, DebugX will try to load and use
113
     DEBXXVDD.DLL. This DLL will allow DebugX to successfully execute its
114
     low-level disk access commands L and W in this OS - if the user has
115
     administrator rights. DEBXXVDD.DLL is public domain, the source can
116
     be found at http://github.com/Baron-von-Riedesel/debxxf. Please
117
     be aware that you can do severe damage to your disk data if you use
118
     those low-level functions without knowing what you are doing.
119

120
   - 'rm' displays MMX registers.
121

122
   - commandline option /2 may direct DebugX's output to a monochrome video
123
     adapter if one is available. Useful for emulators that support this
124
     feature ( DosBox-x or 86Box, for example ). Needs at least a VGA
125
     compatible card, and there's no guarantee that it works as expected.
126

127

128
  c. Optionally, one may create special-purpose variants of Debug.
129
     Run file makex.bat to create them; you'll need the JWasm assembler
130
     for a successful run. The many variants may be confusing, basically
131
     there are 3 branches:
132

133
     - debugger without protected-mode support ( Debug, DebugB )
134
     - debugger with DPMI protected-mode support ( DebugX variants )
135
     - debugger running in protected-mode ring 0 ( DebugR variants )
136
  
137
   - DebugB.BIN: a version that is supposed to be loaded during the
138
     boot process, before DOS is loaded. Has to be installed in "free"
139
     disk space ( for example, in the "reserved" sectors of a FAT partition
140
     or behind the disk's MBR ) and must be initialized before it becomes
141
     active. Definitely not for beginners. See "Installing and Initializing
142
     DebugB" in DEBUG.TXT for details.
143

144
   - DebugX variants:
145

146
     + DebugXd.COM: a version that doesn't hook int 01 and int 03. This
147
       allows to debug this variant with a "normal" version of Debug(X).
148

149
     + DebugXe.COM: a version which hooks interrupts 06, 0Ch and 0Dh in
150
       real-mode. This is for - rare - cases when such exceptions may
151
       occur in real-mode applications.
152

153
     + DebugXf.COM: a version which hooks interrupt 31h in protected-mode
154
       and then rejects any attempt to modify exception vectors 01, 03,
155
       0Dh and 0Eh. This allows to debug DOS-extended applications that
156
       modify these vectors.
157

158
     + DebugXg.EXE: a version that is in DOS device driver format. This
159
       variant can be used to debug other device drivers. There are a
160
       few peculiarities:
161
       - commands N and Q are rejected;
162
       - commands R and W can't be used to read/write files;
163
       - interrupt 06 (invalid opcode exception) is hooked;
164
       - commands BP/BC to manage permanent breakpoints are activated.
165

166
     + DebugXu.COM: a version that uses "unreal" mode to access extended
167
       memory for the DX command. This is useful to debug applications
168
       that set/use "unreal" mode themselves, because DebugXU will not
169
       change the current "unreal" state by its DX command.
170

171
     + DebugXv.COM: a variant that has a few nice features activated
172
       compared to the standard DebugX:
173
       - takes care that screen output of debuggee and debugger are strictly
174
         separated; the 'v' command may be used to watch the debuggee screen
175
         while the debugger is active.
176
       - the SysReq key is detected and will activate the debugger.
177
       - the BP/BC commands are active, allowing permanent breakpoints.
178
       DebugXv is intended to help debugging fullscreen text mode programs.
179

180
   - DebugR variants. These variants run in ring0 protected-mode. The
181
     binaries need additional software a) to be loaded and b) to handle the
182
     i/o requests. No DOS API is used ( actually, not even the BIOS is used )
183
     and hence these are not really "DOS debuggers" anymore.
184
     See "DebugR Basics" in DEBUG.TXT for more details.
185
   
186
     + DebugR.BIN: variant for legacy mode, no support for V86 mode.
187
     + DebugRV.BIN: variant for legacy mode with support for V86 mode.
188
     + DebugRL.BIN: variant for long mode.
189

190
  d. The following features of MS Debug are not implemented:
191

192
   - Loading of .HEX files.
193

194

195
 3. How to (re)build the Debug.COM/DebugX.COM Binaries
196

197
    MAKE.BAT is intended for rebuilding the debugger binaries. The
198
    recommended tool for this step is to use the JWasm assembler.
199
    Alternatively, one can use MS Masm, but then a 16-bit OMF linker 
200
    will be needed as well (Open Watcom's WLink might do the job). Also,
201
    the DebugRL variant cannot be created with Masm, since it contains
202
    a 64-bit segment.
203

204

205
 4. Files Overview
206

207
    The files in this distribution are:
208

209
    debug.com     the executable binary.
210
    debugx.com    a DPMI aware version of Debug.
211
    debxxvdd.dll  a Win32 dll (VDD) loaded if debugx runs in a Windows XP 
212
                  NTVDM "DOS box". Makes debugx's L and W command work with
213
                  sectors on this platform.
214
    readme.txt    this file.
215
    history.txt   list of changes.
216
    debug.txt     a MS-Debug tutorial originally written by Michael Webster,
217
                  extended to describe all additional features of Debug(X).
218
    SAMPLES       contains samples of 16 and 32-bit DPMI clients in Masm
219
                  syntax.
220

221
    The following files, which may be distributed separately, are needed if 
222
    debug.com or debugx.com is to be rebuilt:
223

224
    debug.asm     Assembler source code for both debug.com and debugx.com.
225
                  Assemble with JWasm or Masm (see Make.bat).
226
    *.inc         several assembly include files, two of them (asmtbl.inc
227
                  and distbl.inc) generated by tool mktables.
228
    instr.*       input data for mktables.
229
    mktables.c    C program to compile the internal instruction-set
230
                  tables into files asmtbl.inc/distbl.inc. It's supposed to
231
                  be translated with Open Watcom's 16bit compiler WCC.
232
    make.bat      batch file to (re)create debug.com and debugx.com.
233
    makecm.bat    batch file to (re)create mktables.exe with MS C.
234
    makecw.bat    batch file to (re)create mktables.exe with OW C.
235
    makex.bat     batch file to create special versions of Debugx.
236

237

238
 5. Copyright
239

240
    This program is copyrighted, but feel free to distribute and use it
241
    as you wish.  For full copyright conditions, see the file debug.asm.
242

243
    Paul Vojta
244
    vojta@math.berkeley.edu
245

246