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) ret=01e7:2ce7 ds=0227
  55       ^^^^^^^^^  ^       ^^^^^^^^^      ^^^^^^^^^    ^^^^
  56       |          |       |              |            |Datasegment on entry
  57       |          |       |              |Return address.
  58       |          |       |
  59       |          |       |Argument(s). This one is a win16 segmented pointer.
  60       |          |Function called.
  61       |The module, the function is called in. In this case it is KERNEL.
  62
  63 |Ret  KERNEL.90: LSTRLEN() retval=0x0007 ret=01e7:2ce7 ds=0227
  64                                   ^^^^^^
  65                                   |Returnvalue is 16 bit and has the value 7.
  66
  67
  68  3. If you have found a misbehaving function, try to find out why it
  69     misbehaves. Find the function in the source code. Try to make sense of
  70     the arguments passed. Usually there is a
  71     "dprintf_xyz(stddeb,"Function(...)"...);" at the beginning of the
  72     function. Rerun wine with "-debugmsg +xyz,+relay" added to the
  73     commandline.
  74
  75  4. Additional information on how to debug using the internal debugger can be
  76     found in debugger/README.
  77
  78  5. If those information isn't clear enough or if you want to know more about
  79     what's happening in the function itself, try running wine with "-debugmsg
  80     +all", which dumps ALL included debug information in wine.
  81
  82  6. If that isn't enough add more debug output for yourself into the
  83     functions you find relevant.
  84     You might also try to run the program in gdb instead of using the
  85     WINE-debugger.
  86
  87  7. You can also set a breakpoint for that function. Start wine with the
  88     "-debug" option added to the commandline. After loading the executable
  89     wine will enter the internal debugger. Use "break KERNEL_LSTRLEN"
  90     (replace by function you want to debug, CASE IS RELEVANT.) to set a
  91     breakpoint.  Then use "continue" to start normal program-execution. Wine
  92     will stop if it reaches the breakpoint. If the program isn't yet at the
  93     crashing call of that function, use "continue" again until you are about
  94     to enter that function. You may now proceed with single-stepping the
  95     function until you reach the point of crash. Use the other debugger
  96     commands to print registers and the like.
  97
  98
  99 Program hangs, nothing happens
 100 ==============================
 101
 102   Switch to UNIX shell, get the process-ID using "ps -a|grep wine", and do a
 103   "kill -HUP <pid>" (without " and <>). Wine will then enter its internal
 104   debugger and you can proceed as explained above.
 105
 106 Program reports an error with a Messagebox
 107 ==========================================
 108
 109   Sometimes programs are reporting failure using a more or less nondescript
 110   messageboxes. We can debug this using the same method as Crashes, but there
 111   is one problem... For setting up a message box the program also calls Wine
 112   producing huge chunks of debug code.
 113
 114   Since the failure happens usually directly before setting up the Messagebox
 115   you can start wine with "-debug" added to the commandline, set a breakpoint
 116   at "MessageBox32A" (called by win16 and win32 programs) and proceed with
 117   "continue". With "-debugmsg +all" Wine will now stop directly directly
 118   before setting up the Messagebox.  Proceed as explained above.
 119
 120
 121 Disassembling programs:
 122 =======================
 123   You may also try to disassemble the offending program to check for
 124   undocumented features and/or use of them.
 125   The best, freely available, disassembler for win16 programs is
 126   Windows Codeback, archivename wcbxxx.zip, which usually can be found
 127   in the Cica-Mirror subdirectory on the WINE ftpsites. (See ANNOUNCE).
 128   Disassembling win32 programs is currenty only possible using
 129   Windows Disassembler 32, archivename something like wdasm32x.zip on
 130   ftp.winsite.com and mirrors.
 131   Understanding disassembled code is just a question of exercise.
 132   Most code out there uses standard C function entries (for it is usually
 133   written in C). Win16 function entries usually look like that:
 134 |       push bp
 135 |       mov bp, sp
 136 |       ... function code ..
 137 |       retf XXXX       <--------- XXXX is number of bytes of arguments
 138
 139   This is a FAR function with no local storage. The arguments usually start
 140   at [bp+6] with increasing offsets. Note, that [bp+6] belongs to the RIGHTMOST
 141   argument, for exported win16 functions use the PASCAL calling convention.
 142   So, if we use strcmp(a,b) with a and b both 32 bit variables b would be at
 143   [bp+6] and a at [bp+10].
 144   Most functions make also use of local storage in the stackframe:
 145 |       enter 0086, 00
 146 |       ... function code ...
 147 |       leave
 148 |       retf XXXX
 149   This does mostly the same as above, but also adds 0x86 bytes of
 150   stackstorage, which is accessed using [bp-xx].
 151   Before calling a function, arguments are pushed on the stack using something
 152   like this:
 153 |       push word ptr [bp-02]   <- will be at [bp+8]
 154 |       push di                 <- will be at [bp+6]
 155 |       call KERNEL.LSTRLEN
 156   Here first the selector and then the offset to the passed string are pushed.
 157
 158
 159 Sample debugging session:
 160 =========================
 161
 162   Let's debug the infamous Word SHARE.EXE messagebox:
 163
 164 |marcus@jet $ wine winword.exe
 165 |            +---------------------------------------------+
 166 |            | !  You must leave Windows and load SHARE.EXE|
 167 |            |    before starting Word.                    |
 168 |            +---------------------------------------------+
 169
 170
 171 |marcus@jet $ wine winword.exe -debugmsg +relay -debug
 172 |CallTo32(func=08007e00,000001c4,00000081,00000000,00000000)
 173 |CallTo32(func=08007e00,000001c4,00000014,000006d0,00000000)
 174 |Win16 task 'winword': Breakpoint 1 at 0x0157:0x001a
 175 |CallTo16(func=0097:0130,ds=0000)
 176 |Call WPROCS.24: TASK_RESCHEDULE() ret=003f:0759 ds=0000
 177 |Ret  WPROCS.24: TASK_RESCHEDULE() retval=0x0000 ret=003f:0759 ds=08a7
 178 |CallTo16(func=0157:001a,ds=08a7,0x11d7,0x0000,0x0000,0x3cb4,0x1f40,0x0000,0x0000,0x08a7)
 179 |Loading symbols from ELF file /home/marcus/wine/wine...
 180 |...more Loading symbols ...
 181 |Stopped on breakpoint 1 at 0x0157:0x001a (WPROCS_VXD_PAGEFILE+0xffffeeea)
 182 |In 16 bit mode.
 183 |Wine-dbg>break MessageBox32A                          <---- Set Breakpoint
 184 |Breakpoint 2 at 0x080e792c (MessageBox32A [msgbox.c:198])
 185 |Wine-dbg>c                                            <---- Continue
 186 |Call KERNEL.91: INITTASK() ret=0157:0022 ds=08a7
 187 |     AX=0000 BX=3cb4 CX=1f40 DX=0000 SI=0000 DI=08a7 ES=11d7 EFL=00000286
 188 |CallTo16(func=090f:085c,ds=0dcf,0x0000,0x0000,0x0000,0x0000,0x0800,0x0000,0x0000,0x0dcf)
 189 |...                                                   <----- Much debugoutput
 190 |Call KERNEL.97: GETTEMPFILENAME(0x00c3,08a7:8350,0x0000,08a7:8234) ret=058f:09b1 ds=08a7
 191                                  ^      ^         ^      ^
 192                                  |      |         |      |LPSTR buffer
 193                                  |      |         |UINT16 unique
 194                                  |      |LPCSTR prefix
 195                                  |BYTE drive
 196
 197 |Ret  KERNEL.97: GETTEMPFILENAME() retval=0xce3f ret=058f:09b1 ds=08a7
 198                                           ^
 199                                           |new unique number
 200
 201 |Call KERNEL.74: OPENFILE(08a7:8234,08a7:82c6,0x1012) ret=058f:09d8 ds=08a7
 202                           ^         ^         ^
 203                           |         |         |UINT32 mode
 204                           |         |OFSTRUCT *ofs
 205                           |LPCSTR name
 206
 207 |Ret  KERNEL.74: OPENFILE() retval=0xffff ret=058f:09d8 ds=08a7
 208                                    ^
 209                                    | -1 aka. HFILE_ERROR
 210
 211 |Call USER.1: MESSAGEBOX(0x0000,08ef:8362,0000:0000,0x1030) ret=05d7:084f ds=08efStopped on breakpoint 2 at 0x080e792c (MessageBox32A [msgbox.c:198])
 212 |198     {
 213 |In 32 bit mode.
 214 |Wine-dbg> _
 215
 216     Now, we see that OPENFILE seem to have returned 0xFFFF (or -1). Checking
 217     the implementation of OpenFile in files/file.c, this signals an error.
 218     The mode flags (OF_READWRITE|OF_SHARE_EXCLUSIVE|OF_CREATE) seems to
 219     indicate, that WinWord wants to open the file for writing, so we check
 220     the filename. Since we don't see the filename in this debugoutput, we use
 221     the dprintf_file() in OpenFile to print out more information by adding
 222     "-debugmsg +relay" to the commandline.
 223
 224     (In fact, we see that the filename has been returned by the GetTempFileName
 225      function above, but we check it anyway.)
 226
 227 |marcus@jet $ wine winword.exe -debugmsg +relay,+file -debug
 228 |.....much more debugoutput .....
 229 |
 230
 231 |Call KERNEL.97: GETTEMPFILENAME(0x00c3,08ef:8350,0x0000,08ef:8234) ret=05d7:09b1 ds=08ef
 232 |FILE_Create: 'C:\~doc8b93.tmp' 01b6 1
 233 |FILE_SetDosError: errno = 13
 234
 235 |Warning: GetTempFileName returns 'C:\~doc8b93.tmp', which doesn't seem to be writeable.
 236 |Please check your configuration file if this generates a failure.
 237  ^ Warning message
 238
 239 |GetTempFileName: returning C:\~doc8b93.tmp
 240 |Ret  KERNEL.97: GETTEMPFILENAME() retval=0x8b93 ret=05d7:09b1 ds=08ef
 241 |Call KERNEL.74: OPENFILE(08ef:8234,08ef:82c6,0x1012) ret=05d7:09d8 ds=08ef
 242 |OpenFile: C:\~doc8b93.tmp 1012
 243 |FILE_Create: 'C:\~doc8b93.tmp' 01b6 0
 244 |FILE_SetDosError: errno = 13
 245 |OpenFile(C:\~doc8b93.tmp): return = HFILE_ERROR
 246 |Ret  KERNEL.74: OPENFILE() retval=0xffff ret=05d7:09d8 ds=08ef
 247
 248
 249     The filename is "C:\~docd03d.tmp". Of course, C:\ is writeable for the
 250     superuser only, so the open fails for a normal user and OpenFile returns
 251     -1, which in turn generates this messagebox. (As said by the warning
 252     message.)
 253
 254
 255 Written by Marcus Meissner <msmeissn@cip.informatik.uni-erlangen.de>,
 256 additions welcome.