git.oblomov.eu Git - wine/blob - 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 |Reading symbols from file /root/wine/wine.sym
  12 |In 16 bit mode.
  13 |Register dump:
  14 | CS:01b7 SS:016f DS:0287 ES:0000
  15 | IP:0c41 SP:878a BP:8796 FLAGS:0246
  16 | AX:811e BX:0000 CX:0000 DX:0000 SI:0001 DI:ffff
  17 |Stack dump:
  18 |0x016f:0x878a:  0001 016f ffed 0000 0000 0287 890b 1e5b
  19 |0x016f:0x879a:  01b7 0001 000d 1050 08b7 016f 0001 000d
  20 |0x016f:0x87aa:  000a 0003 0004 0000 0007 0007 0190 0000
  21 |0x016f:0x87ba:
  22 |
  23 |0050: sel=0287 base=40211d30 limit=0b93f (bytes) 16-bit rw-
  24 |Backtrace:
  25 |0 0x01b7:0x0c41 (PXSRV.FONGETFACENAME+0x7c)
  26 |1 0x01b7:0x1e5b (PXSRV.FONPUTCATFONT+0x2cd)
  27 |2 0x01a7:0x05aa
  28 |3 0x01b7:0x0768 (PXSRV.FONINITFONTS+0x81)
  29 |4 0x014f:0x03ed (PDOXWIN.@SQLCURCB$Q6CBTYPEULN8CBSCTYPE+0x1b1)
  30 |5 0x013f:0x00ac
  31 |
  32 |0x01b7:0x0c41 (PXSRV.FONGETFACENAME+0x7c):  movw        %es:0x38(%bx),%dx
  33
  34 Steps to debug a crash. You may stop at any step, but please report the bug
  35 and provide as much of the information gathered to the newsgroup or the
  36 relevant developer as feasonable.
  37
  38  1. Get the reason for the crash. This is usually an access to an invalid
  39     selector, an access to an out of range address in a valid selector,
  40     popping a segmentregister from the stack or the like. When reporting a
  41     crash, report this WHOLE crashdump even if it doesn't make sense to you.
  42
  43     (In this case it is access to an invalid selector, for %es is 0000, as
  44     seen in the register dump).
  45
  46  2. Determine where the reason came from.
  47     Since this is usually a primary/secondary reaction to a failed or
  48     misbehaving Wine function, rerun Wine with "-debugmsg +relay" (without ")
  49     added to the commandline. This will get rather much output, but usually
  50     the reason is located in the last call(s).  Those lines usually look like
  51     this:
  52
  53 |Call KERNEL.90: LSTRLEN(0227:0692) ret=01e7:2ce7 ds=0227
  54       ^^^^^^^^^  ^       ^^^^^^^^^      ^^^^^^^^^    ^^^^
  55       |          |       |              |            |Datasegment on entry
  56       |          |       |              |Return address.
  57       |          |       |
  58       |          |       |Argument(s). This one is a win16 segmented pointer.
  59       |          |Function called.
  60       |The module, the function is called in. In this case it is KERNEL.
  61
  62 |Ret  KERNEL.90: LSTRLEN() retval=0x0007 ret=01e7:2ce7 ds=0227
  63                                   ^^^^^^
  64                                   |Returnvalue is 16 bit and has the value 7.
  65
  66  3. If you have found a misbehaving function, try to find out why it
  67     misbehaves. Find the function in the source code. Try to make sense of
  68     the arguments passed. Usually there is a
  69     "dprintf_xyz(stddeb,"Fnction(...)"...);" at the beginning of the
  70     function. Rerun wine with "-debugmsg +xyz,+relay" added to the
  71     commandline.
  72
  73
  74  4. If those information isn't clear enough or if you want to know more about
  75     what's happening in the function itself, try running wine with "-debugmsg
  76     +all", which dumps ALL included debug information in wine.
  77
  78  5. If that isn't enough add more debug output for yourself into the
  79     functions you find relevant.
  80
  81  6. You can also set a breakpoint for that function. Start wine with the
  82     "-debug" option added to the commandline. After loading the executable
  83     wine will enter the internal debugger. Use "break KERNEL.LSTRLEN"
  84     (replace by function you want to debug, CASE IS RELEVANT.) to set a
  85     breakpoint.  Then use "continue" to start normal program-execution. Wine
  86     will stop if it reaches the breakpoint. If the program isn't yet at the
  87     crashing call of that function, use "continue" again until you are about
  88     to enter that function. You may now proceed with single-stepping the
  89     function until you reach the point of crash. Use the other debugger
  90     commands to print registers and the like.
  91
  92
  93 Program hangs, nothing happens
  94 ==============================
  95
  96   Switch to UNIX shell, get the process-ID using "ps -a|grep wine", and do a
  97   "kill -HUP <pid>" (without " and <>). Wine will then enter its internal
  98   debugger and you can procede as explained above.
  99
 100 Program reports an error with a Messagebox
 101 ==========================================
 102
 103   Sometimes programs are reporting failure using a more or less nondescript
 104   messageboxes. We can debug this using the same method as Crashes, but there
 105   is one problem... For setting up a message box the program also calls Wine
 106   producing huge chunks of debug code.
 107
 108   Since the failure happens usually directly before setting up the Messagebox
 109   you can start wine with "-debug" added to the commandline, set a breakpoint
 110   at "USER.MESSAGEBOX" (win16 programs) "USER32.MessageBox" (win32 Programs)
 111   and proceed with "continue". With "-debugmsg +all" Wine will now stop
 112   directly directly before setting up the Messagebox.  Proceed as explained
 113   above.
 114
 115
 116 Sample debugging session:
 117 =========================
 118
 119   Let's debug the infamous Word SHARE.EXE messagebox:
 120
 121 |marcus@jet $ wine winword.exe
 122 |            +---------------------------------------------+
 123 |            | !  You must leave Windows and load SHARE.EXE|
 124 |            |    before starting Word.                    |
 125 |            +---------------------------------------------+
 126
 127
 128 |marcus@jet $ wine winword.exe -debugmsg +relay -debug
 129 |CallTo32(func=08007e00,000001c4,00000081,00000000,00000000)
 130 |CallTo32(func=08007e00,000001c4,00000014,000006d0,00000000)
 131 |Win16 task 'winword': Breakpoint 1 at 0x0157:0x001a
 132 |CallTo16(func=0097:0130,ds=0000)
 133 |Call WPROCS.24: TASK_RESCHEDULE() ret=003f:0759 ds=0000
 134 |Ret  WPROCS.24: TASK_RESCHEDULE() retval=0x0000 ret=003f:0759 ds=08a7
 135 |CallTo16(func=0157:001a,ds=08a7,0x11d7,0x0000,0x0000,0x3cb4,0x1f40,0x0000,0x0000,0x08a7)
 136 |Reading symbols from file /root/wine/wine.sym
 137 |Stopped on breakpoint 1 at 0x0157:0x001a
 138 |In 16 bit mode.
 139 |0x0157:0x001a:  xorw   %bp,%bp
 140 |Wine-dbg> break USER.MESSAGEBOX                       <---- Set Breakpoint
 141 |Breakpoint 2 at 0x0067:0x00000000 (USER.MESSAGEBOX)
 142 |Wine-dbg>c                                            <---- Continue
 143 |Call KERNEL.91: INITTASK() ret=0157:0022 ds=08a7
 144 |     AX=0000 BX=3cb4 CX=1f40 DX=0000 SI=0000 DI=08a7 ES=11d7 EFL=00000286
 145 |CallTo16(func=090f:085c,ds=0dcf,0x0000,0x0000,0x0000,0x0000,0x0800,0x0000,0x0000,0x0dcf)
 146 |...                                                   <----- Much debugoutput
 147 |Call KERNEL.97: GETTEMPFILENAME(0x00c3,08a7:8350,0x0000,08a7:8234) ret=058f:09b1 ds=08a7
 148                                  ^      ^         ^      ^
 149                                  |      |         |      |LPSTR buffer
 150                                  |      |         |UINT16 unique
 151                                  |      |LPCSTR prefix
 152                                  |BYTE drive
 153
 154 |Ret  KERNEL.97: GETTEMPFILENAME() retval=0xce3f ret=058f:09b1 ds=08a7
 155                                           ^
 156                                           |new unique number
 157
 158 |Call KERNEL.74: OPENFILE(08a7:8234,08a7:82c6,0x1012) ret=058f:09d8 ds=08a7
 159                           ^         ^         ^
 160                           |         |         |UINT32 mode
 161                           |         |OFSTRUCT *ofs
 162                           |LPCSTR name
 163
 164 |Ret  KERNEL.74: OPENFILE() retval=0xffff ret=058f:09d8 ds=08a7
 165                                    ^
 166                                    | -1 aka. HFILE_ERROR
 167
 168 |Stopped on breakpoint 2 at 0x0067:0x00000000 (USER.MESSAGEBOX)
 169 |In 32 bit mode.
 170 |0x0067:0x00000000 (USER.MESSAGEBOX):  pushw    %bp
 171
 172     Now, we see that OPENFILE seem to have returned 0xFFFF (or -1). Checking
 173     the implementation of OpenFile in files/file.c, this signals an error.
 174     The mode flags (OF_READWRITE|OF_SHARE_EXCLUSIVE|OF_CREATE) seems to
 175     indicate, that WinWord wants to open the file for writing, so we check
 176     the filename. Since we don't see the filename in this debugoutput, we use
 177     the dprintf_file() in OpenFile to print out more information by adding
 178     "-debugmsg +relay" to the commandline.
 179
 180     (In fact, we see that the filename has been returned by the GetTempFileName
 181      function above, but we check it anyway.)
 182
 183 |marcus@jet $ wine winword.exe -debugmsg +relay,+file -debug
 184 |.....much more debugoutput .....
 185 |
 186 |Call KERNEL.97: GETTEMPFILENAME(0x00c3,08a7:8350,0x0000,08a7:8234) ret=058f:09b1 ds=08a7
 187 |FILE_Create: 'C:~docd03d.tmp' 01b6 1
 188 |FILE_SetDosError: errno = 13
 189 |GetTempFileName: returning C:\~DOCD03D.TMP
 190 |Ret  KERNEL.97: GETTEMPFILENAME() retval=0xd03d ret=058f:09b1 ds=08a7
 191 |Call KERNEL.74: OPENFILE(08a7:8234,08a7:82c6,0x1012) ret=058f:09d8 ds=08a7
 192 |OpenFile: C:\~DOCD03D.TMP 1012
 193 |FILE_AllocTaskHandle: returning task handle 1, dos_file 0, file 1 of 254
 194 |FILE_Create: 'C:\~DOCD03D.TMP' 01b6 0
 195 |FILE_SetDosError: errno = 13
 196 |OpenFile(C:\~DOCD03D.TMP): return = HFILE_ERROR
 197 |FILE_FreeTaskHandle: dos=1 file=0
 198 |Ret  KERNEL.74: OPENFILE() retval=0xffff ret=058f:09d8 ds=08a7
 199
 200     The filename is "C:\~DOCD03D.TMP". Of course, C:\ is writeable for the
 201     superuser only, so the open fails for a normal user and OpenFile returns
 202     -1, which in turn generates this messagebox.
 203
 204
 205 Written by Marcus Meissner <msmeissn@cip.informatik.uni-erlangen.de>,
 206 additions welcome.