documentation/debugging

   1 This file describes where to start debugging Wine and how to write
   2 useful bug reports.
   3
   4 To avoid debugging
   5 ==================
   6
   7 Sometimes you can bring applications to run by using some of the
   8 native Windows DLL's, together with Wine. Here are some Tips by
   9 Juergen Schmied on how to proceed. This assumes that your C:\windows
  10 directory in the configuration file does not point to a native Windows
  11 installation but is in a separate Unix file system. (For instance,
  12 C:\windows is really /home/ego/wine/drives/c).
  13
  14 - Create empty C:\windows and C:\windows\system directories.
  15   Do not point Wine to a Windows directory full of old installations
  16   and a messy registry. (Wine creates a special registry in your home
  17   directory, in $HOME/.wine/*.reg. Perhaps you have to remove these
  18   files).
  19 - Run the application with   -debugmsg +module,+file   to find out
  20   which files are needed. Copy the required DLL's one by one to the
  21   C:\windows\system directory.
  22 - Note that some network DLL's are not needed even though Wine is
  23   looking for them. Do not copy the MPR.DLL into the directory,
  24   use the internal implementation.
  25 - Copy SHELL/SHELL32 and COMDLG/COMDLG32 COMMCTRL/COMCTL32
  26   only as pairs to your Wine directory (these DLL's are
  27   "clean" to use)
  28 - Be consistent: Use only DLLS from the same Windows version
  29   together.
  30 - Put regedit.exe in the C:\windows directory (office95 imports
  31   a *.reg file when it runs with a empty registry, don't know
  32   about office97).
  33
  34
  35 Crashes
  36 =======
  37
  38   These usually show up like this:
  39
  40 |Unexpected Windows program segfault - opcode = 8b
  41 |Segmentation fault in Windows program 1b7:c41.
  42 |Loading symbols from ELF file /root/wine/wine...
  43 |....more Loading symbols from ...
  44 |In 16 bit mode.
  45 |Register dump:
  46 | CS:01b7 SS:016f DS:0287 ES:0000
  47 | IP:0c41 SP:878a BP:8796 FLAGS:0246
  48 | AX:811e BX:0000 CX:0000 DX:0000 SI:0001 DI:ffff
  49 |Stack dump:
  50 |0x016f:0x878a:  0001 016f ffed 0000 0000 0287 890b 1e5b
  51 |0x016f:0x879a:  01b7 0001 000d 1050 08b7 016f 0001 000d
  52 |0x016f:0x87aa:  000a 0003 0004 0000 0007 0007 0190 0000
  53 |0x016f:0x87ba:
  54 |
  55 |0050: sel=0287 base=40211d30 limit=0b93f (bytes) 16-bit rw-
  56 |Backtrace:
  57 |0 0x01b7:0x0c41 (PXSRV_FONGETFACENAME+0x7c)
  58 |1 0x01b7:0x1e5b (PXSRV_FONPUTCATFONT+0x2cd)
  59 |2 0x01a7:0x05aa
  60 |3 0x01b7:0x0768 (PXSRV_FONINITFONTS+0x81)
  61 |4 0x014f:0x03ed (PDOXWIN_@SQLCURCB$Q6CBTYPEULN8CBSCTYPE+0x1b1)
  62 |5 0x013f:0x00ac
  63 |
  64 |0x01b7:0x0c41 (PXSRV_FONGETFACENAME+0x7c):  movw        %es:0x38(%bx),%dx
  65
  66 Steps to debug a crash. You may stop at any step, but please report the bug
  67 and provide as much of the information gathered to the newsgroup or the
  68 relevant developer as feasonable.
  69
  70  1. Get the reason for the crash. This is usually an access to an invalid
  71     selector, an access to an out of range address in a valid selector,
  72     popping a segmentregister from the stack or the like. When reporting a
  73     crash, report this WHOLE crashdump even if it doesn't make sense to you.
  74
  75     (In this case it is access to an invalid selector, for %es is 0000, as
  76     seen in the register dump).
  77
  78  2. Determine where the reason came from.
  79     Since this is usually a primary/secondary reaction to a failed or
  80     misbehaving Wine function, rerun Wine with "-debugmsg +relay" (without ")
  81     added to the commandline. This will get rather much output, but usually
  82     the reason is located in the last call(s).  Those lines usually look like
  83     this:
  84
  85 |Call KERNEL.90: LSTRLEN(0227:0692 "text") ret=01e7:2ce7 ds=0227
  86       ^^^^^^^^^  ^       ^^^^^^^^^ ^^^^^^      ^^^^^^^^^    ^^^^
  87       |          |       |         |           |            |Datasegment
  88       |          |       |         |           |Return address
  89       |          |       |         |textual parameter
  90       |          |       |
  91       |          |       |Argument(s). This one is a win16 segmented pointer.
  92       |          |Function called.
  93       |The module, the function is called in. In this case it is KERNEL.
  94
  95 |Ret  KERNEL.90: LSTRLEN() retval=0x0004 ret=01e7:2ce7 ds=0227
  96                                   ^^^^^^
  97                                   |Returnvalue is 16 bit and has the value 4.
  98
  99
 100  3. If you have found a misbehaving function, try to find out why it
 101     misbehaves. Find the function in the source code. Try to make sense of
 102     the arguments passed. Usually there is a 'TRACE(<channel>,"(...)\n");'
 103     at the beginning of the function. Rerun wine with
 104     "-debugmsg +xyz,+relay" added to the commandline.
 105
 106  4. Additional information on how to debug using the internal debugger can be
 107     found in debugger/README.
 108
 109  5. If those information isn't clear enough or if you want to know more about
 110     what's happening in the function itself, try running wine with "-debugmsg
 111     +all", which dumps ALL included debug information in wine.
 112
 113  6. If that isn't enough add more debug output for yourself into the
 114     functions you find relevant.  See documentation/debug-msgs.
 115     You might also try to run the program in gdb instead of using the
 116     WINE-debugger. If you don't use the "-desktop" or "-managed" option,
 117     start the WINE process with "-sync", or chances are good to get X into
 118     an unusable state.
 119
 120  7. You can also set a breakpoint for that function. Start wine with the
 121     "-debug" option added to the commandline. After loading the executable
 122     wine will enter the internal debugger. Use "break KERNEL_LSTRLEN"
 123     (replace by function you want to debug, CASE IS RELEVANT.) to set a
 124     breakpoint.  Then use "continue" to start normal program-execution. Wine
 125     will stop if it reaches the breakpoint. If the program isn't yet at the
 126     crashing call of that function, use "continue" again until you are about
 127     to enter that function. You may now proceed with single-stepping the
 128     function until you reach the point of crash. Use the other debugger
 129     commands to print registers and the like.
 130
 131
 132 Program hangs, nothing happens
 133 ==============================
 134
 135   Switch to UNIX shell, get the process-ID using "ps -a|grep wine", and do a
 136   "kill -HUP <pid>" (without " and <>). Wine will then enter its internal
 137   debugger and you can proceed as explained above. Also, you can use -debug
 138   switch and then you can get into internal debugger by pressing Ctrl-C in
 139   the terminal where you run Wine.
 140
 141 Program reports an error with a Messagebox
 142 ==========================================
 143
 144   Sometimes programs are reporting failure using a more or less nondescript
 145   messageboxes. We can debug this using the same method as Crashes, but there
 146   is one problem... For setting up a message box the program also calls Wine
 147   producing huge chunks of debug code.
 148
 149   Since the failure happens usually directly before setting up the Messagebox
 150   you can start wine with "-debug" added to the commandline, set a breakpoint
 151   at "MessageBox32A" (called by win16 and win32 programs) and proceed with
 152   "continue". With "-debugmsg +all" Wine will now stop directly before
 153   setting up the Messagebox.  Proceed as explained above.
 154
 155   You can also run wine using "wine -debugmsg +relay program.exe 2>&1|less -i"
 156   and in less search for messagebox.
 157
 158 Disassembling programs:
 159 =======================
 160   You may also try to disassemble the offending program to check for
 161   undocumented features and/or use of them.
 162
 163   The best, freely available, disassembler for Win16 programs is
 164   Windows Codeback, archivename wcbxxx.zip, which usually can be found
 165   in the Cica-Mirror subdirectory on the WINE ftpsites. (See ANNOUNCE).
 166   Disassembling win32 programs is possible using the Windows Disassembler 32,
 167   archivename something like w32dasm.zip on ftp.winsite.com and mirrors.
 168   The shareware version does not allow saving of disassembly listings.
 169
 170   [It also has a bug, it disassembles the dll and immediately after that
 171    crashes, leaving a very large file caled 'winsys' in the directory of the
 172    disassembled file. This file contains nothing of value (just the disassembly)
 173    and can be safely deleted.]
 174
 175   Understanding disassembled code is just a question of exercise.
 176
 177   Most code out there uses standard C function entries (for it is usually
 178   written in C). Win16 function entries usually look like that:
 179 |       push bp
 180 |       mov bp, sp
 181 |       ... function code ..
 182 |       retf XXXX       <--------- XXXX is number of bytes of arguments
 183
 184   This is a FAR function with no local storage. The arguments usually start
 185   at [bp+6] with increasing offsets. Note, that [bp+6] belongs to the RIGHTMOST
 186   argument, for exported win16 functions use the PASCAL calling convention.
 187   So, if we use strcmp(a,b) with a and b both 32 bit variables b would be at
 188   [bp+6] and a at [bp+10].
 189   Most functions make also use of local storage in the stackframe:
 190 |       enter 0086, 00
 191 |       ... function code ...
 192 |       leave
 193 |       retf XXXX
 194   This does mostly the same as above, but also adds 0x86 bytes of
 195   stackstorage, which is accessed using [bp-xx].
 196   Before calling a function, arguments are pushed on the stack using something
 197   like this:
 198 |       push word ptr [bp-02]   <- will be at [bp+8]
 199 |       push di                 <- will be at [bp+6]
 200 |       call KERNEL.LSTRLEN
 201   Here first the selector and then the offset to the passed string are pushed.
 202
 203 Sample debugging session:
 204 =========================
 205
 206   Let's debug the infamous Word SHARE.EXE messagebox:
 207
 208 |marcus@jet $ wine winword.exe
 209 |            +---------------------------------------------+
 210 |            | !  You must leave Windows and load SHARE.EXE|
 211 |            |    before starting Word.                    |
 212 |            +---------------------------------------------+
 213
 214
 215 |marcus@jet $ wine winword.exe -debugmsg +relay -debug
 216 |CallTo32(wndproc=0x40065bc0,hwnd=000001ac,msg=00000081,wp=00000000,lp=00000000)
 217 |Win16 task 'winword': Breakpoint 1 at 0x01d7:0x001a
 218 |CallTo16(func=0127:0070,ds=0927)
 219 |Call WPROCS.24: TASK_RESCHEDULE() ret=00b7:1456 ds=0927
 220 |Ret  WPROCS.24: TASK_RESCHEDULE() retval=0x8672 ret=00b7:1456 ds=0927
 221 |CallTo16(func=01d7:001a,ds=0927)
 222 |     AX=0000 BX=3cb4 CX=1f40 DX=0000 SI=0000 DI=0927 BP=0000 ES=11f7
 223 |Loading symbols: /home/marcus/wine/wine...
 224 |Stopped on breakpoint 1 at 0x01d7:0x001a
 225 |In 16 bit mode.
 226 |Wine-dbg>break MessageBox32A                          <---- Set Breakpoint
 227 |Breakpoint 2 at 0x40189100 (MessageBox32A [msgbox.c:190])
 228 |Wine-dbg>c                                            <---- Continue
 229 |Call KERNEL.91: INITTASK() ret=0157:0022 ds=08a7
 230 |     AX=0000 BX=3cb4 CX=1f40 DX=0000 SI=0000 DI=08a7 ES=11d7 EFL=00000286
 231 |CallTo16(func=090f:085c,ds=0dcf,0x0000,0x0000,0x0000,0x0000,0x0800,0x0000,0x0000,0x0dcf)
 232 |...                                                   <----- Much debugoutput
 233 |Call KERNEL.136: GETDRIVETYPE(0x0000) ret=060f:097b ds=0927
 234                                ^^^^^^ Drive 0 (A:)
 235 |Ret  KERNEL.136: GETDRIVETYPE() retval=0x0002 ret=060f:097b ds=0927
 236                                         ^^^^^^  DRIVE_REMOVEABLE
 237                                                 (It is a floppy diskdrive.)
 238
 239 |Call KERNEL.136: GETDRIVETYPE(0x0001) ret=060f:097b ds=0927
 240                                ^^^^^^ Drive 1 (B:)
 241 |Ret  KERNEL.136: GETDRIVETYPE() retval=0x0000 ret=060f:097b ds=0927
 242                                         ^^^^^^  DRIVE_CANNOTDETERMINE
 243                                                 (I don't have drive B: assigned)
 244
 245 |Call KERNEL.136: GETDRIVETYPE(0x0002) ret=060f:097b ds=0927
 246                                ^^^^^^^ Drive 2 (C:)
 247 |Ret  KERNEL.136: GETDRIVETYPE() retval=0x0003 ret=060f:097b ds=0927
 248                                         ^^^^^^ DRIVE_FIXED
 249                                                (specified as a harddisk)
 250
 251 |Call KERNEL.97: GETTEMPFILENAME(0x00c3,0x09278364"doc",0x0000,0927:8248) ret=060f:09b1 ds=0927
 252                                  ^^^^^^           ^^^^^        ^^^^^^^^^
 253                                  |                |            |buffer for fname
 254                                  |                |temporary name ~docXXXX.tmp
 255                                  |Force use of Drive C:.
 256
 257 |Warning: GetTempFileName returns 'C:~doc9281.tmp', which doesn't seem to be writeable.
 258 |Please check your configuration file if this generates a failure.
 259
 260 Whoops, it even detects that something is wrong!
 261
 262 |Ret  KERNEL.97: GETTEMPFILENAME() retval=0x9281 ret=060f:09b1 ds=0927
 263                                           ^^^^^^ Temporary storage ID
 264
 265 |Call KERNEL.74: OPENFILE(0x09278248"C:~doc9281.tmp",0927:82da,0x1012) ret=060f:09d8 ds=0927
 266                                     ^^^^^^^^^^^^^^^^ ^^^^^^^^^ ^^^^^^^
 267                                     |filename        |OFSTRUCT |open mode:
 268
 269                                        OF_CREATE|OF_SHARE_EXCLUSIVE|OF_READWRITE
 270
 271 This fails, since my C: drive is in this case mounted readonly.
 272
 273 |Ret  KERNEL.74: OPENFILE() retval=0xffff ret=060f:09d8 ds=0927
 274                                    ^^^^^^ HFILE_ERROR16, yes, it failed.
 275
 276 |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
 277
 278 And MessageBox'ed.
 279
 280 |Stopped on breakpoint 2 at 0x40189100 (MessageBox32A [msgbox.c:190])
 281 |190     {              <- the sourceline
 282 In 32 bit mode.
 283 Wine-dbg>
 284
 285         The code seems to find a writeable harddisk and tries to create a file
 286         there. To work around this bug, you can define C: as a networkdrive,
 287         which is ignored by the code above.
 288
 289 Written by Marcus Meissner <msmeissn@cip.informatik.uni-erlangen.de>,
 290 additions welcome.
 291 -------
 292
 293 Here are some useful debugging tips, added by Andreas Mohr:
 294
 295
 296 a) If you have a program crashing at such an early loader phase that you can't
 297 use the Wine debugger normally, but Wine already executes the program's
 298 start code, then you may use a special trick:
 299 You should do a
 300 wine -debugmsg +relay program
 301 to get a listing of the functions the program calls in its start function.
 302 Now you do a
 303 wine -debug winfile.exe
 304 This way, you get into Wine-dbg. Now you can set a breakpoint on any
 305 function the program calls in the start function and just type "c" to bypass
 306 the eventual calls of Winfile to this function until you are finally at the
 307 place where this function gets called by the crashing start function.
 308 Now you can proceed with your debugging as usual.
 309
 310
 311 b) If you try to run a program and it quits after showing an error messagebox,
 312 the problem can usually be identified in the return value of one of the
 313 functions executed before MessageBox().
 314 That's why you should re-run the program with e.g.
 315 wine -debugmsg +relay <program name> &>relmsg
 316 Then do a "more relmsg" and search for the last occurrence of a call to the string "MESSAGEBOX".
 317 This is a line like
 318 Call USER.1: MESSAGEBOX(0x0000,0x01ff1246 "Runtime error 219 at 0004:1056.",0x00000000,0x1010) ret=01f7:2160 ds=01ff
 319
 320 In my example the lines before the call to MessageBox() look like that:
 321
 322 Call KERNEL.96: FREELIBRARY(0x0347) ret=01cf:1033 ds=01ff
 323 CallTo16(func=033f:0072,ds=01ff,0x0000)
 324 Ret  KERNEL.96: FREELIBRARY() retval=0x0001 ret=01cf:1033 ds=01ff
 325 Call KERNEL.96: FREELIBRARY(0x036f) ret=01cf:1043 ds=01ff
 326 CallTo16(func=0367:0072,ds=01ff,0x0000)
 327 Ret  KERNEL.96: FREELIBRARY() retval=0x0001 ret=01cf:1043 ds=01ff
 328 Call KERNEL.96: FREELIBRARY(0x031f) ret=01cf:105c ds=01ff
 329 CallTo16(func=0317:0072,ds=01ff,0x0000)
 330 Ret  KERNEL.96: FREELIBRARY() retval=0x0001 ret=01cf:105c ds=01ff
 331 Call USER.171: WINHELP(0x02ac,0x01ff05b4 "COMET.HLP",0x0002,0x00000000) ret=01cf:1070 ds=01ff
 332 CallTo16(func=0117:0080,ds=01ff)
 333 Call WPROCS.24: TASK_RESCHEDULE() ret=00a7:0a2d ds=002b
 334 Ret  WPROCS.24: TASK_RESCHEDULE() retval=0x0000 ret=00a7:0a2d ds=002b
 335 Ret  USER.171: WINHELP() retval=0x0001 ret=01cf:1070 ds=01ff
 336 Call KERNEL.96: FREELIBRARY(0x01be) ret=01df:3e29 ds=01ff
 337 Ret  KERNEL.96: FREELIBRARY() retval=0x0000 ret=01df:3e29 ds=01ff
 338 Call KERNEL.52: FREEPROCINSTANCE(0x02cf00ba) ret=01f7:1460 ds=01ff
 339 Ret  KERNEL.52: FREEPROCINSTANCE() retval=0x0001 ret=01f7:1460 ds=01ff
 340 Call USER.1: MESSAGEBOX(0x0000,0x01ff1246 "Runtime error 219 at 0004:1056.",0x00000000,0x1010) ret=01f7:2160 ds=01ff
 341
 342 I think that the call to MessageBox() in this example is _not_ caused by a wrong result value of some previously executed function (it's happening quite often like that), but instead the messagebox complains about a runtime error at 0x0004:0x1056.
 343 As the segment value of the address is only "4", I think that that is only an internal program value. But the offset address reveals something quite interesting:
 344 Offset 1056 is _very_ close to the return address of FREELIBRARY():
 345
 346 Call KERNEL.96: FREELIBRARY(0x031f) ret=01cf:105c ds=01ff
 347                                              ^^^^
 348 Provided that segment 0x0004 is indeed segment 0x1cf, we now we can use IDA (available at ftp://ftp.uni-koeln.de/pc/msdos/programming/assembler/ida35bx.zip) to
 349 disassemble the part that caused the error. We just have to find the address of
 350 the call to FreeLibrary(). Some lines before that the runtime error occurred.
 351 But be careful ! In some cases you don't have to disassemble the main program, but instead some DLL called by it in order to find the correct place where the runtime error occurred. That can be determined by finding the origin of the segment value (in this case 0x1cf).
 352
 353 c) If you have created a relay file of some crashing program and want to set a
 354 breakpoint at a certain location which is not yet available as the
 355 program loads the breakpoint's segment during execution,
 356 you may set a breakpoint to GetVersion16/32 as those functions are called
 357 very often.
 358 Then do a "c" until you are able to set this breakpoint without error message.
 359
 360 d) Some useful programs:
 361 IDA: ftp://ftp.uni-koeln.de/pc/msdos/programming/assembler/ida35bx.zip
 362 *Very* good DOS disassembler ! It's badly needed for debugging Wine sometimes.
 363
 364 XRAY: ftp://ftp.th-darmstadt.de/pub/machines/ms-dos/SimTel/msdos/asmutil/xray15.zip
 365 Traces DOS calls (Int 21h, DPMI, ...). Use it with Windows to correct
 366 file management problems etc.
 367
 368 pedump: http://oak.oakland.edu/pub/simtelnet/win95/prog/pedump.zip
 369 Dumps the imports and exports of a PE (Portable Executable) DLL.
 370
 371
 372 Some basic debugger usages:
 373 ===========================
 374
 375 After starting you program with
 376   wine -debug myprog.exe
 377 the program loads and you get a prompt at the program starting point.
 378 Then you can set breakpoints:
 379   b RoutineName      (by outine name) OR
 380   b *0x812575        (by address)
 381 Then you hit 'c' (continue) to run the program. It stops at
 382 the breakpoint. You can type
 383   step               (to step one line) OR
 384   stepi              (to step one machine instruction at a time;
 385                       here, it helps to know the basic 386
 386                       instruction set)
 387   info reg           (to see registers)
 388   info stack         (to see hex values in the stack)
 389   info local         (to see local variables)
 390   list <line number> (to list source code)
 391   x <variable name>  (to examine a variable; only works if code
 392                       is not compiled with optimization)
 393   x 0x4269978        (to examine a memory location)
 394   ?                  (help)
 395   q                  (quit)
 396 By hitting Enter, you repeat the last command.