-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathDeb386.txt
148 lines (111 loc) · 6.94 KB
/
Deb386.txt
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
1. About Deb386
Deb386 is a PL0 debugger. It's using DebugR.bin, a variant of Debug/X,
as the debugger core. Once installed, the debugger may be activated by a
protected-mode program running at privilege level 0 ( also called "ring 0" ).
Once being activated, the debugger prompt will appear if an exception has
been detected.
Deb386 may be used to debug HDPMI (the HX DPMI host), JemmEx/Jemm386
( v86-mode monitor programs ) or even Windows 3.1 or 9X.
2. Usage
Deb386 understands the following cmdline options:
-2 displays on secondary monitor ( if KBDIN/VIOOUT is active )
-i[:arg] install
-b stop at init
-c:n COM port to use ( if AUXIN/AUXOUT is active )
-h use HDPMI mode switches for I/O ( if KBDIN/VIOOUT is active )
-n make debugger invisible to Int 41h
-u uninstall
The optional parameter 'arg' behind option -I will be passed to the debugger
core DebugR. DebugR understands arguments:
/m: assume exceptions vectors don't overlap with IRQs 0-7
/s: use soft breakpoints only
Deb386 has to be loaded *before* the ring0 host ( DPMI host, JemmEx, ... )
is loaded.
3. Run386
Run386 is a very simple ring0 "host" that allows Deb386 to run in ring0,
without paging. May be used to view and enter the full 4 GB physical address
space of the machine.
Usage: just install Deb386 with "deb386 -i", then launch Run386.exe. It
will stop at a breakpoint. Using the debugger's G(o) command will make Run386
to quit protected-mode and return to the DOS prompt.
Run386 refuses to run in v86-mode.
4. Details/Hints
- The debugger uses the interrupt 68h real-mode API for ring0-debugger
detection and initialization ( the same API is used by MS WDEB386 and
386SWAT ). It stays in conventional memory and so doesn't have to fiddle
with paging so far as the ring0 host "identity-maps" this part of memory.
Note that if WDEB386 or 386SWAT are running, Deb386 will detect that and
not install itself.
- Regarding I/O there are currently two possibilities: it's either done
through a serial line or using low-level video/keyboard code:
a) I/O through a serial connection (COMx). This requires to assemble Deb386
with options -DAUXOUT=1 and -DAUXIN=1 ( see Makefile for details ). The
default for the COM port is COM1, may be changed with option /C.
As an example, if DOS is running in the Qemu emulator, one may connect the
emulated COM port to the terminal, using Qemu cmdline options:
-chardev stdio,id=char0,signal=off -serial chardev:char0
b) I/O through low-level video/keyboard code. This requires to assemble
Deb386 with options -DVIOOUT=1 and -DKBDIN=1. The output may be directed
to a secondary ( monochrome ) adapter with cmdline option /2. The input
is a slight problem, since key translations have to be done by the
debugger; there exist 2 translation tables, for US or GR keyboards, default
is GR ( see below how to set US ).
- The exceptions that may wake up the debugger are 0, 1, 3, 6, 0Dh and 0Eh,
in protected-mode only. No other events are handled. The debugger core
DebugR does ignore all exceptions coming from v86-mode. So it's not possible
to debug DOS "real-mode" applications with Deb386.
- As default, Deb386 is visible to protected-mode Int 41h. So it will be
detected by protected-mode programs, including the HX program loaders
( which will then emit a breakpoint at program start ). If this is to be
avoided, add the /n option.
- Deb386's T and P commands may implicitely set a breakpoint. As default, this
breakpoint is set by using the 80386+ debug registers. This also applies to
breakpoints set by the G command. If there are no more free breakpoints - or
if the usage of the debug registers has been switched off by cmdline option
/s -, "soft" breakpoints are used by writing INT3 instructions into code.
Breakpoints of the "INT3 type" have limitations. A page fault may occur
if the memory to write to is readonly and the CR0 WP bit is set; or if the
memory is ROM, the write may silently fail. To avoid page faults, the WP bit
may be cleared before the debug session; see tool ResWP.exe.
To disable usage of debug register breakpoints Deb386 must be installed
with command line option -i:/s. This may be useful if the debugger runs in
an emulated environment ( i.e. 86box ), that don't implement support for the
hardware debug features of the cpu.
- If the DPMI host runs clients with IOPL 0 ( there exists HDPMI variants that
do that ), the clients will trigger an exception 0Dh if instructions CLI/STI
or IN/INS/OUT/OUTS for trapped ports are executed. The debugger core DebugR
does ignore such exceptions.
- The debugger core DebugR has absolutely no knowledge about Windows or DOS
peculiarities. So, for example, it cannot distinguish "invalid page faults"
from "valid" ones. If this causes troubles because too many "valid" page
faults do occur, one may (temporarily) make Deb386 ignore page faults with
the VC/VT commands.
- HDPMI ring0 code runs with interrupts disabled. There may be some places
that are untraceable, assuming that the code isn't interrupted. Also,
mode-switching code cannot be single-stepped - so stop single-stepping
if instructions like LIDT or LTR appear in the disassembly.
- When using option -u to uninstall Deb386, it might refuse to do so because
there's a still active "client" running ( with an IDT that has been modified
by Deb386 ). So first the debugged program has to be terminated, then Deb386.
- Using option /b the debugger will stop immediately after initialization.
HDPMI at this stage is still located in conventional memory.
- There's a device driver variant of Deb386, Deb386.sys. It's meant to debug
Jemm386/JemmEx. Note that the standard versions of Jemm386/JemmEx aren't
kernel debugger aware, they won't activate it. So to make the debugger stop
in Jemm during its initialization, you'll have to create a version that
communicates with the kernel debugger.
- Since Deb386 uses the same interface that WDEB386 does, it might be used as
a ( rather restricted ) Win3x/Win9x kernel debugger. These Windows variants
do reprogram the PIC - hardware interrupts are mapped to INT 50h-5Fh. That's
why you have to feed DebugR with the /m option ( set as argument for -i ) to
tell it that the master PIC vectors don't overlap with exception vectors.
5. Requirements to create the Binaries
- JWasm.
- DebugR - this Debug/X variant is included as a binary.
- if debug displays are to be activated, JWasm v2.17+ is needed.
- make utility.
"nmake aux=1" will create Deb386.exe with AUXIN/AUXOUT enabled.
"nmake kbd=us" will create Deb386.exe with US kbd layout support.
6. License
Deb386 is released under the MIT license. See license.txt for details.
Andreas Grech