documentation/debugging

   1 This file describes where to start debugging Wine and how to write
   2 useful bug reports.
   3
   4 Crashes
   5 =======
   6
   7   These usually show up like this:
   8
   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 ...
  13 |In 16 bit mode.
  14 |Register dump:
  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
  18 |Stack dump:
  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
  22 |0x016f:0x87ba:
  23 |
  24 |0050: sel=0287 base=40211d30 limit=0b93f (bytes) 16-bit rw-
  25 |Backtrace:
  26 |0 0x01b7:0x0c41 (PXSRV_FONGETFACENAME+0x7c)
  27 |1 0x01b7:0x1e5b (PXSRV_FONPUTCATFONT+0x2cd)
  28 |2 0x01a7:0x05aa
  29 |3 0x01b7:0x0768 (PXSRV_FONINITFONTS+0x81)
  30 |4 0x014f:0x03ed (PDOXWIN_@SQLCURCB$Q6CBTYPEULN8CBSCTYPE+0x1b1)
  31 |5 0x013f:0x00ac
  32 |
  33 |0x01b7:0x0c41 (PXSRV_FONGETFACENAME+0x7c):  movw        %es:0x38(%bx),%dx
  34
  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.
  38
  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.
  43
  44     (In this case it is access to an invalid selector, for %es is 0000, as
  45     seen in the register dump).
  46
  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
  52     this:
  53
  54 |Call KERNEL.90: LSTRLEN(0227:0692 "text") ret=01e7:2ce7 ds=0227
  55       ^^^^^^^^^  ^       ^^^^^^^^^ ^^^^^^      ^^^^^^^^^    ^^^^
  56       |          |       |         |           |            |Datasegment
  57       |          |       |         |           |Return address
  58       |          |       |         |textual parameter
  59       |          |       |
  60       |          |       |Argument(s). This one is a win16 segmented pointer.
  61       |          |Function called.
  62       |The module, the function is called in. In this case it is KERNEL.
  63
  64 |Ret  KERNEL.90: LSTRLEN() retval=0x0004 ret=01e7:2ce7 ds=0227
  65                                   ^^^^^^
  66                                   |Returnvalue is 16 bit and has the value 4.
  67
  68
  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
  74     commandline.
  75
  76  4. Additional information on how to debug using the internal debugger can be
  77     found in debugger/README.
  78
  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.
  82
  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
  86     WINE-debugger. If you don't use the "-desktop" or "-managed" option,
  87     start the WINE process with "-sync", or chances are good to get X into
  88     an unusable state.
  89
  90  7. You can also set a breakpoint for that function. Start wine with the
  91     "-debug" option added to the commandline. After loading the executable
  92     wine will enter the internal debugger. Use "break KERNEL_LSTRLEN"
  93     (replace by function you want to debug, CASE IS RELEVANT.) to set a
  94     breakpoint.  Then use "continue" to start normal program-execution. Wine
  95     will stop if it reaches the breakpoint. If the program isn't yet at the
  96     crashing call of that function, use "continue" again until you are about
  97     to enter that function. You may now proceed with single-stepping the
  98     function until you reach the point of crash. Use the other debugger
  99     commands to print registers and the like.
 100
 101
 102 Program hangs, nothing happens
 103 ==============================
 104
 105   Switch to UNIX shell, get the process-ID using "ps -a|grep wine", and do a
 106   "kill -HUP <pid>" (without " and <>). Wine will then enter its internal
 107   debugger and you can proceed as explained above. Also, you can use -debug
 108   switch and then you can get into internal debugger by pressing Ctrl-C in
 109   the terminal where you run Wine.
 110
 111 Program reports an error with a Messagebox
 112 ==========================================
 113
 114   Sometimes programs are reporting failure using a more or less nondescript
 115   messageboxes. We can debug this using the same method as Crashes, but there
 116   is one problem... For setting up a message box the program also calls Wine
 117   producing huge chunks of debug code.
 118
 119   Since the failure happens usually directly before setting up the Messagebox
 120   you can start wine with "-debug" added to the commandline, set a breakpoint
 121   at "MessageBox32A" (called by win16 and win32 programs) and proceed with
 122   "continue". With "-debugmsg +all" Wine will now stop directly before
 123   setting up the Messagebox.  Proceed as explained above.
 124
 125   You can also run wine using "wine -debugmsg +relay program.exe 2>&1|less -i"
 126   and in less search for messagebox.
 127
 128 Disassembling programs:
 129 =======================
 130   You may also try to disassemble the offending program to check for
 131   undocumented features and/or use of them.
 132
 133   The best, freely available, disassembler for Win16 programs is
 134   Windows Codeback, archivename wcbxxx.zip, which usually can be found
 135   in the Cica-Mirror subdirectory on the WINE ftpsites. (See ANNOUNCE).
 136   Disassembling win32 programs is possible using the Windows Disassembler 32,
 137   archivename something like w32dasm.zip on ftp.winsite.com and mirrors.
 138   The shareware version does not allow saving of disassembly listings.
 139
 140   [It also has a bug, it disassembles the dll and immediately after that
 141    crashes, leaving a very large file caled 'winsys' in the directory of the
 142    disassembled file. This file contains nothing of value (just the disassembly)
 143    and can be safely deleted.]
 144
 145   Understanding disassembled code is just a question of exercise.
 146
 147   Most code out there uses standard C function entries (for it is usually
 148   written in C). Win16 function entries usually look like that:
 149 |       push bp
 150 |       mov bp, sp
 151 |       ... function code ..
 152 |       retf XXXX       <--------- XXXX is number of bytes of arguments
 153
 154   This is a FAR function with no local storage. The arguments usually start
 155   at [bp+6] with increasing offsets. Note, that [bp+6] belongs to the RIGHTMOST
 156   argument, for exported win16 functions use the PASCAL calling convention.
 157   So, if we use strcmp(a,b) with a and b both 32 bit variables b would be at
 158   [bp+6] and a at [bp+10].
 159   Most functions make also use of local storage in the stackframe:
 160 |       enter 0086, 00
 161 |       ... function code ...
 162 |       leave
 163 |       retf XXXX
 164   This does mostly the same as above, but also adds 0x86 bytes of
 165   stackstorage, which is accessed using [bp-xx].
 166   Before calling a function, arguments are pushed on the stack using something
 167   like this:
 168 |       push word ptr [bp-02]   <- will be at [bp+8]
 169 |       push di                 <- will be at [bp+6]
 170 |       call KERNEL.LSTRLEN
 171   Here first the selector and then the offset to the passed string are pushed.
 172
 173 Sample debugging session:
 174 =========================
 175
 176   Let's debug the infamous Word SHARE.EXE messagebox:
 177
 178 |marcus@jet $ wine winword.exe
 179 |            +---------------------------------------------+
 180 |            | !  You must leave Windows and load SHARE.EXE|
 181 |            |    before starting Word.                    |
 182 |            +---------------------------------------------+
 183
 184
 185 |marcus@jet $ wine winword.exe -debugmsg +relay -debug
 186 |CallTo32(wndproc=0x40065bc0,hwnd=000001ac,msg=00000081,wp=00000000,lp=00000000)
 187 |Win16 task 'winword': Breakpoint 1 at 0x01d7:0x001a
 188 |CallTo16(func=0127:0070,ds=0927)
 189 |Call WPROCS.24: TASK_RESCHEDULE() ret=00b7:1456 ds=0927
 190 |Ret  WPROCS.24: TASK_RESCHEDULE() retval=0x8672 ret=00b7:1456 ds=0927
 191 |CallTo16(func=01d7:001a,ds=0927)
 192 |     AX=0000 BX=3cb4 CX=1f40 DX=0000 SI=0000 DI=0927 BP=0000 ES=11f7
 193 |Loading symbols: /home/marcus/wine/wine...
 194 |Stopped on breakpoint 1 at 0x01d7:0x001a
 195 |In 16 bit mode.
 196 |Wine-dbg>break MessageBox32A                          <---- Set Breakpoint
 197 |Breakpoint 2 at 0x40189100 (MessageBox32A [msgbox.c:190])
 198 |Wine-dbg>c                                            <---- Continue
 199 |Call KERNEL.91: INITTASK() ret=0157:0022 ds=08a7
 200 |     AX=0000 BX=3cb4 CX=1f40 DX=0000 SI=0000 DI=08a7 ES=11d7 EFL=00000286
 201 |CallTo16(func=090f:085c,ds=0dcf,0x0000,0x0000,0x0000,0x0000,0x0800,0x0000,0x0000,0x0dcf)
 202 |...                                                   <----- Much debugoutput
 203 |Call KERNEL.136: GETDRIVETYPE(0x0000) ret=060f:097b ds=0927
 204                                ^^^^^^ Drive 0 (A:)
 205 |Ret  KERNEL.136: GETDRIVETYPE() retval=0x0002 ret=060f:097b ds=0927
 206                                         ^^^^^^  DRIVE_REMOVEABLE
 207                                                 (It is a floppy diskdrive.)
 208
 209 |Call KERNEL.136: GETDRIVETYPE(0x0001) ret=060f:097b ds=0927
 210                                ^^^^^^ Drive 1 (B:)
 211 |Ret  KERNEL.136: GETDRIVETYPE() retval=0x0000 ret=060f:097b ds=0927
 212                                         ^^^^^^  DRIVE_CANNOTDETERMINE
 213                                                 (I don't have drive B: assigned)
 214
 215 |Call KERNEL.136: GETDRIVETYPE(0x0002) ret=060f:097b ds=0927
 216                                ^^^^^^^ Drive 2 (C:)
 217 |Ret  KERNEL.136: GETDRIVETYPE() retval=0x0003 ret=060f:097b ds=0927
 218                                         ^^^^^^ DRIVE_FIXED
 219                                                (specified as a harddisk)
 220
 221 |Call KERNEL.97: GETTEMPFILENAME(0x00c3,0x09278364"doc",0x0000,0927:8248) ret=060f:09b1 ds=0927
 222                                  ^^^^^^           ^^^^^        ^^^^^^^^^
 223                                  |                |            |buffer for fname
 224                                  |                |temporary name ~docXXXX.tmp
 225                                  |Force use of Drive C:.
 226
 227 |Warning: GetTempFileName returns 'C:~doc9281.tmp', which doesn't seem to be writeable.
 228 |Please check your configuration file if this generates a failure.
 229
 230 Whoops, it even detects that something is wrong!
 231
 232 |Ret  KERNEL.97: GETTEMPFILENAME() retval=0x9281 ret=060f:09b1 ds=0927
 233                                           ^^^^^^ Temporary storage ID
 234
 235 |Call KERNEL.74: OPENFILE(0x09278248"C:~doc9281.tmp",0927:82da,0x1012) ret=060f:09d8 ds=0927
 236                                     ^^^^^^^^^^^^^^^^ ^^^^^^^^^ ^^^^^^^
 237                                     |filename        |OFSTRUCT |open mode:
 238
 239                                        OF_CREATE|OF_SHARE_EXCLUSIVE|OF_READWRITE
 240
 241 This fails, since my C: drive is in this case mounted readonly.
 242
 243 |Ret  KERNEL.74: OPENFILE() retval=0xffff ret=060f:09d8 ds=0927
 244                                    ^^^^^^ HFILE_ERROR16, yes, it failed.
 245
 246 |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
 247
 248 And MessageBox'ed.
 249
 250 |Stopped on breakpoint 2 at 0x40189100 (MessageBox32A [msgbox.c:190])
 251 |190     {              <- the sourceline
 252 In 32 bit mode.
 253 Wine-dbg>
 254
 255         The code seems to find a writeable harddisk and tries to create a file
 256         there. To work around this bug, you can define C: as a networkdrive,
 257         which is ignored by the code above.
 258
 259 Written by Marcus Meissner <msmeissn@cip.informatik.uni-erlangen.de>,
 260 additions welcome.