1 This file describes where to start debugging Wine and how to write
7 These usually show up like this:
9 |Unexpected Windows program segfault - opcode = 8b
10 |Segmentation fault in Windows program 1b7:c41.
11 |Loading symbols from ELF file /root/wine/wine...
12 |....more Loading symbols from ...
15 | CS:01b7 SS:016f DS:0287 ES:0000
16 | IP:0c41 SP:878a BP:8796 FLAGS:0246
17 | AX:811e BX:0000 CX:0000 DX:0000 SI:0001 DI:ffff
19 |0x016f:0x878a: 0001 016f ffed 0000 0000 0287 890b 1e5b
20 |0x016f:0x879a: 01b7 0001 000d 1050 08b7 016f 0001 000d
21 |0x016f:0x87aa: 000a 0003 0004 0000 0007 0007 0190 0000
24 |0050: sel=0287 base=40211d30 limit=0b93f (bytes) 16-bit rw-
26 |0 0x01b7:0x0c41 (PXSRV_FONGETFACENAME+0x7c)
27 |1 0x01b7:0x1e5b (PXSRV_FONPUTCATFONT+0x2cd)
29 |3 0x01b7:0x0768 (PXSRV_FONINITFONTS+0x81)
30 |4 0x014f:0x03ed (PDOXWIN_@SQLCURCB$Q6CBTYPEULN8CBSCTYPE+0x1b1)
33 |0x01b7:0x0c41 (PXSRV_FONGETFACENAME+0x7c): movw %es:0x38(%bx),%dx
35 Steps to debug a crash. You may stop at any step, but please report the bug
36 and provide as much of the information gathered to the newsgroup or the
37 relevant developer as feasonable.
39 1. Get the reason for the crash. This is usually an access to an invalid
40 selector, an access to an out of range address in a valid selector,
41 popping a segmentregister from the stack or the like. When reporting a
42 crash, report this WHOLE crashdump even if it doesn't make sense to you.
44 (In this case it is access to an invalid selector, for %es is 0000, as
45 seen in the register dump).
47 2. Determine where the reason came from.
48 Since this is usually a primary/secondary reaction to a failed or
49 misbehaving Wine function, rerun Wine with "-debugmsg +relay" (without ")
50 added to the commandline. This will get rather much output, but usually
51 the reason is located in the last call(s). Those lines usually look like
54 |Call KERNEL.90: LSTRLEN(0227:0692 "text") ret=01e7:2ce7 ds=0227
55 ^^^^^^^^^ ^ ^^^^^^^^^ ^^^^^^ ^^^^^^^^^ ^^^^
56 | | | | | |Datasegment
57 | | | | |Return address
58 | | | |textual parameter
60 | | |Argument(s). This one is a win16 segmented pointer.
62 |The module, the function is called in. In this case it is KERNEL.
64 |Ret KERNEL.90: LSTRLEN() retval=0x0004 ret=01e7:2ce7 ds=0227
66 |Returnvalue is 16 bit and has the value 4.
69 3. If you have found a misbehaving function, try to find out why it
70 misbehaves. Find the function in the source code. Try to make sense of
71 the arguments passed. Usually there is a
72 "dprintf_xyz(stddeb,"Function(...)"...);" at the beginning of the
73 function. Rerun wine with "-debugmsg +xyz,+relay" added to the
76 4. Additional information on how to debug using the internal debugger can be
77 found in debugger/README.
79 5. If those information isn't clear enough or if you want to know more about
80 what's happening in the function itself, try running wine with "-debugmsg
81 +all", which dumps ALL included debug information in wine.
83 6. If that isn't enough add more debug output for yourself into the
84 functions you find relevant.
85 You might also try to run the program in gdb instead of using the
88 7. You can also set a breakpoint for that function. Start wine with the
89 "-debug" option added to the commandline. After loading the executable
90 wine will enter the internal debugger. Use "break KERNEL_LSTRLEN"
91 (replace by function you want to debug, CASE IS RELEVANT.) to set a
92 breakpoint. Then use "continue" to start normal program-execution. Wine
93 will stop if it reaches the breakpoint. If the program isn't yet at the
94 crashing call of that function, use "continue" again until you are about
95 to enter that function. You may now proceed with single-stepping the
96 function until you reach the point of crash. Use the other debugger
97 commands to print registers and the like.
100 Program hangs, nothing happens
101 ==============================
103 Switch to UNIX shell, get the process-ID using "ps -a|grep wine", and do a
104 "kill -HUP <pid>" (without " and <>). Wine will then enter its internal
105 debugger and you can proceed as explained above. Also, you can use -debug
106 switch and then you can get into internal debugger by pressing Ctrl-C in
107 the terminal where you run Wine.
109 Program reports an error with a Messagebox
110 ==========================================
112 Sometimes programs are reporting failure using a more or less nondescript
113 messageboxes. We can debug this using the same method as Crashes, but there
114 is one problem... For setting up a message box the program also calls Wine
115 producing huge chunks of debug code.
117 Since the failure happens usually directly before setting up the Messagebox
118 you can start wine with "-debug" added to the commandline, set a breakpoint
119 at "MessageBox32A" (called by win16 and win32 programs) and proceed with
120 "continue". With "-debugmsg +all" Wine will now stop directly directly
121 before setting up the Messagebox. Proceed as explained above.
123 You can also run wine using "wine -debugmsg +relay program.exe 2>&1|less -i"
124 and in less search for messagebox.
126 Disassembling programs:
127 =======================
128 You may also try to disassemble the offending program to check for
129 undocumented features and/or use of them.
131 The best, freely available, disassembler for Win16 programs is
132 Windows Codeback, archivename wcbxxx.zip, which usually can be found
133 in the Cica-Mirror subdirectory on the WINE ftpsites. (See ANNOUNCE).
134 Disassembling win32 programs is possible using the Windows Disassembler 32,
135 archivename something like w32dasm.zip on ftp.winsite.com and mirrors.
136 The shareware version does not allow saving of disassembly listings.
138 [It also has a bug, it disassembles the dll and immediately after that
139 crashes, leaving a very large file caled 'winsys' in the directory of the
140 disassembled file. This file contains nothing of value (just the disassembly)
141 and can be safely deleted.]
143 Understanding disassembled code is just a question of exercise.
145 Most code out there uses standard C function entries (for it is usually
146 written in C). Win16 function entries usually look like that:
149 | ... function code ..
150 | retf XXXX <--------- XXXX is number of bytes of arguments
152 This is a FAR function with no local storage. The arguments usually start
153 at [bp+6] with increasing offsets. Note, that [bp+6] belongs to the RIGHTMOST
154 argument, for exported win16 functions use the PASCAL calling convention.
155 So, if we use strcmp(a,b) with a and b both 32 bit variables b would be at
156 [bp+6] and a at [bp+10].
157 Most functions make also use of local storage in the stackframe:
159 | ... function code ...
162 This does mostly the same as above, but also adds 0x86 bytes of
163 stackstorage, which is accessed using [bp-xx].
164 Before calling a function, arguments are pushed on the stack using something
166 | push word ptr [bp-02] <- will be at [bp+8]
167 | push di <- will be at [bp+6]
168 | call KERNEL.LSTRLEN
169 Here first the selector and then the offset to the passed string are pushed.
171 Sample debugging session:
172 =========================
174 Let's debug the infamous Word SHARE.EXE messagebox:
176 |marcus@jet $ wine winword.exe
177 | +---------------------------------------------+
178 | | ! You must leave Windows and load SHARE.EXE|
179 | | before starting Word. |
180 | +---------------------------------------------+
183 |marcus@jet $ wine winword.exe -debugmsg +relay -debug
184 |CallTo32(wndproc=0x40065bc0,hwnd=000001ac,msg=00000081,wp=00000000,lp=00000000)
185 |Win16 task 'winword': Breakpoint 1 at 0x01d7:0x001a
186 |CallTo16(func=0127:0070,ds=0927)
187 |Call WPROCS.24: TASK_RESCHEDULE() ret=00b7:1456 ds=0927
188 |Ret WPROCS.24: TASK_RESCHEDULE() retval=0x8672 ret=00b7:1456 ds=0927
189 |CallTo16(func=01d7:001a,ds=0927)
190 | AX=0000 BX=3cb4 CX=1f40 DX=0000 SI=0000 DI=0927 BP=0000 ES=11f7
191 |Loading symbols: /home/marcus/wine/wine...
192 |Stopped on breakpoint 1 at 0x01d7:0x001a
194 |Wine-dbg>break MessageBox32A <---- Set Breakpoint
195 |Breakpoint 2 at 0x40189100 (MessageBox32A [msgbox.c:190])
196 |Wine-dbg>c <---- Continue
197 |Call KERNEL.91: INITTASK() ret=0157:0022 ds=08a7
198 | AX=0000 BX=3cb4 CX=1f40 DX=0000 SI=0000 DI=08a7 ES=11d7 EFL=00000286
199 |CallTo16(func=090f:085c,ds=0dcf,0x0000,0x0000,0x0000,0x0000,0x0800,0x0000,0x0000,0x0dcf)
200 |... <----- Much debugoutput
201 |Call KERNEL.136: GETDRIVETYPE(0x0000) ret=060f:097b ds=0927
203 |Ret KERNEL.136: GETDRIVETYPE() retval=0x0002 ret=060f:097b ds=0927
204 ^^^^^^ DRIVE_REMOVEABLE
205 (It is a floppy diskdrive.)
207 |Call KERNEL.136: GETDRIVETYPE(0x0001) ret=060f:097b ds=0927
209 |Ret KERNEL.136: GETDRIVETYPE() retval=0x0000 ret=060f:097b ds=0927
210 ^^^^^^ DRIVE_CANNOTDETERMINE
211 (I don't have drive B: assigned)
213 |Call KERNEL.136: GETDRIVETYPE(0x0002) ret=060f:097b ds=0927
215 |Ret KERNEL.136: GETDRIVETYPE() retval=0x0003 ret=060f:097b ds=0927
217 (specified as a harddisk)
219 |Call KERNEL.97: GETTEMPFILENAME(0x00c3,0x09278364"doc",0x0000,0927:8248) ret=060f:09b1 ds=0927
220 ^^^^^^ ^^^^^ ^^^^^^^^^
221 | | |buffer for fname
222 | |temporary name ~docXXXX.tmp
223 |Force use of Drive C:.
225 |Warning: GetTempFileName returns 'C:~doc9281.tmp', which doesn't seem to be writeable.
226 |Please check your configuration file if this generates a failure.
228 Whoops, it even detects that something is wrong!
230 |Ret KERNEL.97: GETTEMPFILENAME() retval=0x9281 ret=060f:09b1 ds=0927
231 ^^^^^^ Temporary storage ID
233 |Call KERNEL.74: OPENFILE(0x09278248"C:~doc9281.tmp",0927:82da,0x1012) ret=060f:09d8 ds=0927
234 ^^^^^^^^^^^^^^^^ ^^^^^^^^^ ^^^^^^^
235 |filename |OFSTRUCT |open mode:
237 OF_CREATE|OF_SHARE_EXCLUSIVE|OF_READWRITE
239 This fails, since my C: drive is in this case mounted readonly.
241 |Ret KERNEL.74: OPENFILE() retval=0xffff ret=060f:09d8 ds=0927
242 ^^^^^^ HFILE_ERROR16, yes, it failed.
244 |Call USER.1: MESSAGEBOX(0x0000,0x09278376"Sie müssen Windows verlassen und SHARE.EXE laden bevor Sie Word starten.",0x00000000,0x1030) ret=060f:084f ds=0927
248 |Stopped on breakpoint 2 at 0x40189100 (MessageBox32A [msgbox.c:190])
249 |190 { <- the sourceline
253 The code seems to find a writeable harddisk and tries to create a file
254 there. To work around this bug, you can define C: as a networkdrive,
255 which is ignored by the code above.
257 Written by Marcus Meissner <msmeissn@cip.informatik.uni-erlangen.de>,