| blob | 5c0e48031a165d2202e0b6be25314f0b455066e1 |
7 <para>
10 </para>
11 <para>
13 </para>
15 <sect2>
18 <para>
19 Before going into the depths of debugging in Wine, here's
20 a small overview of process and thread handling in Wine.
21 It has to be clear that there are two different beasts:
22 processes/threads from the Unix point of view and
23 processes/threads from a Windows point of view.
24 </para>
25 <para>
26 Each Windows' thread is implemented as a Unix process (under
28 that all threads of a same Windows' process share the same
29 (unix) address space.
30 </para>
31 <para>
32 In the following:
33 </para>
34 <itemizedlist>
35 <listitem>
37 </listitem>
38 <listitem>
40 </listitem>
41 <listitem>
43 </listitem>
44 </itemizedlist>
45 <para>
52 </para>
53 <para>
54 Each Unix process can be identified by two values:
55 </para>
56 <itemizedlist>
57 <listitem>
59 </listitem>
60 <listitem>
62 </listitem>
63 </itemizedlist>
64 <para>
65 Each Windows' process has also a Windows' process id
68 different and shall not be used instead of the other.
69 </para>
70 <para>
72 defined (Windows) system wide. They must not be confused
73 with process or thread handles which, as any handle, is an
74 indirection to a system object (in this case process or
75 thread). A same process can have several different handles
76 on the same kernel object. The handles can be defined as
77 local (the values is only valid in a process), or system
78 wide (the same handle can be used by any
80 </para>
81 </sect2>
83 <sect2>
86 <para>
87 When talking of debugging in Wine, there are at least two
88 levels to think of:
89 </para>
90 <itemizedlist>
91 <listitem>
93 </listitem>
94 <listitem>
95 <para>the Wine integrated debugger, dubbed
97 </listitem>
98 </itemizedlist>
99 <para>
100 Wine implements most of the Windows' debugging API (the
101 part in KERNEL32, not the one in
103 (emulated or Winelib) using that API to debug a
105 </para>
106 <para>
108 use of this API to allow debugging both any Wine or Winelib
109 applications as well as Wine itself (kernel and all DLLs).
110 </para>
111 </sect2>
112 </sect1>
118 <sect2>
121 <para>
122 Any application (either a Windows' native executable, or a
123 Winelib application) can be run through
125 are the same as for wine:
126 </para>
127 <screen>
128 winedbg telnet.exe
129 winedbg "hl.exe -windowed"
130 </screen>
131 </sect2>
133 <sect2>
136 <para>
139 without any attached process. You can get a list of running
142 process</command> command, and then, with the
145 you want to debug. This is (for now) a neat feature for the
146 following reasons:
147 </para>
148 <itemizedlist>
149 <listitem>
151 </listitem>
152 </itemizedlist>
153 </sect2>
158 <para>
159 When something goes wrong, Windows tracks this as an
160 exception. Exceptions exist for segmentation violation,
161 stack overflow, division by zero...
162 </para>
163 <para>
165 debugged. If so, the exception event is sent to the
166 debugger, which takes care of it: end of the story. This
167 mechanism is part of the standard Windows' debugging API.
168 </para>
169 <para>
171 tries to launch a debugger. This debugger (normally
173 details), at startup, attaches to the
175 event. In this case, you are able to look at the causes of
176 the exception, and either fix the causes (and continue
177 further the execution) or dig deeper to understand what went
178 wrong.
179 </para>
180 <para>
183 are the two ways to let the process go further for the
184 handling of the exception event.
185 </para>
186 <para>
187 To be more precise on the way Wine (and Windows) generates
188 exception events, when a fault occurs (segmentation
189 violation, stack overflow...), the event is first sent to
190 the debugger (this is known as a first chance exception).
191 The debugger can give two answers:
192 </para>
194 <variablelist>
195 <varlistentry>
197 <listitem>
198 <para>
199 the debugger had the ability to correct what's
200 generated the exception, and is now able to continue
201 process execution.
202 </para>
203 </listitem>
204 </varlistentry>
205 <varlistentry>
207 <listitem>
208 <para>
209 the debugger couldn't correct the cause of the
210 first chance exception. Wine will now try to walk
211 the list of exception handlers to see if one of them
212 can handle the exception. If no exception handler is
213 found, the exception is sent once again to the
214 debugger to indicate the failure of the exception
215 handling.
216 </para>
217 </listitem>
218 </varlistentry>
219 </variablelist>
220 <note>
221 <para>
222 since some of Wine's code uses exceptions and
225 in such cases with segv exceptions. This happens, for
228 used, to let the handling of the exception to be done by
231 </para>
232 </note>
233 </sect2>
235 <sect2>
238 <para>
239 Unfortunately, Windows doesn't provide a detach kind of API,
240 meaning that once you started debugging a process, you must
241 do so until the process dies. Killing (or stopping/aborting)
242 the debugger will also kill the debugged process. This will
243 be true for any Windows' debugging API compliant debugger,
245 </para>
246 </sect2>
247 </sect1>
253 <para>
255 additions welcome.
256 </para>
257 <para>
259 </para>
261 <para>
262 This file describes where to start debugging Wine. If at any
263 point you get stuck and want to ask for help, please read the
265 information on how to write useful bug reports.
266 </para>
268 <sect2>
271 <para>
272 These usually show up like this:
273 </para>
274 <screen>
275 |Unexpected Windows program segfault - opcode = 8b
276 |Segmentation fault in Windows program 1b7:c41.
277 |Loading symbols from ELF file /root/wine/wine...
278 |....more Loading symbols from ...
279 |In 16 bit mode.
280 |Register dump:
284 |Stack dump:
289 |
291 |Backtrace:
298 |
300 </screen>
301 <para>
302 Steps to debug a crash. You may stop at any step, but please
303 report the bug and provide as much of the information
304 gathered to the newsgroup or the relevant developer as
305 feasible.
306 </para>
308 <orderedlist>
309 <listitem>
310 <para>
311 Get the reason for the crash. This is usually an access to
312 an invalid selector, an access to an out of range address
313 in a valid selector, popping a segmentregister from the
314 stack or the like. When reporting a crash, report this
316 make sense to you.
317 </para>
318 <para>
319 (In this case it is access to an invalid selector, for
321 seen in the register dump).
322 </para>
323 </listitem>
324 <listitem>
325 <para>
326 Determine the cause of the crash. Since this is usually
327 a primary/secondary reaction to a failed or misbehaving
328 Wine function, rerun Wine with <parameter>-debugmsg
329 +relay</parameter> added to the commandline. This will
330 generate quite a lot of output, but usually the reason is
331 located in the last call(s). Those lines usually look like
332 this:
333 </para>
334 <screen>
336 ^^^^^^^^^ ^ ^^^^^^^^^ ^^^^^^ ^^^^^^^^^ ^^^^
337 | | | | | |Datasegment
338 | | | | |Return address
339 | | | |textual parameter
340 | | |
341 | | |Argument(s). This one is a win16 segmented pointer.
342 | |Function called.
343 |The module, the function is called in. In this case it is KERNEL.
346 ^^^^^^
348 </screen>
349 </listitem>
350 <listitem>
351 <para>
352 If you have found a misbehaving function, try to find out
353 why it misbehaves. Find the function in the source code.
354 Try to make sense of the arguments passed. Usually there is
356 the beginning of the function. Rerun wine with
358 commandline.
359 </para>
360 </listitem>
361 <listitem>
362 <para>
363 Additional information on how to debug using the internal
364 debugger can be found in
366 </para>
367 </listitem>
368 <listitem>
369 <para>
370 If this information isn't clear enough or if you want to
371 know more about what's happening in the function itself,
372 try running wine with <parameter>-debugmsg
373 +all</parameter>, which dumps ALL included debug
374 information in wine.
375 </para>
376 </listitem>
377 <listitem>
378 <para>
379 If even that isn't enough, add more debug output for
380 yourself into the functions you find relevant. See
383 instead of using the WINE-debugger. If you do that, use
385 disable the handling of seg faults inside
390 good to get X into an unusable state.
391 </para>
392 </listitem>
393 <listitem>
394 <para>
395 You can also set a breakpoint for that function. Start wine
397 commandline. After loading the executable wine will enter
398 the internal debugger. Use <parameter>break
399 KERNEL_LSTRLEN</parameter> (replace by function you want
400 to debug, CASE IS RELEVANT) to set a breakpoint. Then use
402 program-execution. Wine will stop if it reaches the
403 breakpoint. If the program isn't yet at the crashing call
405 until you are about to enter that function. You may now
406 proceed with single-stepping the function until you reach
407 the point of crash. Use the other debugger commands to
408 print registers and the like.
409 </para>
410 </listitem>
411 </orderedlist>
412 </sect2>
414 <sect2>
417 <para>
418 Switch to UNIX shell, get the process-ID using <command>ps -a |
421 then enter its internal debugger and you can proceed as
422 explained above. Also, you can use
424 internal debugger by pressing
426 the terminal where you run Wine.
427 </para>
428 </sect2>
430 <sect2>
433 <para>
434 Sometimes programs are reporting failure using more or
435 less nondescript messageboxes. We can debug this using the
436 same method as Crashes, but there is one problem... For
437 setting up a message box the program also calls Wine
438 producing huge chunks of debug code.
439 </para>
440 <para>
441 Since the failure happens usually directly before setting up
442 the Messagebox you can start wine with
445 and win32 programs) and proceed with
447 +all</parameter> Wine will now stop directly before setting
448 up the Messagebox. Proceed as explained above.
449 </para>
450 <para>
451 You can also run wine using <command>wine -debugmsg +relay
454 </para>
455 </sect2>
457 <sect2>
460 <para>
461 You may also try to disassemble the offending program to
462 check for undocumented features and/or use of them.
463 </para>
464 <para>
465 The best, freely available, disassembler for Win16 programs is
470 </para>
471 <para>
472 Disassembling win32 programs is possible using
476 and mirrors. The shareware version does not allow saving of
477 disassembly listings. You can also use the newer (and in the
478 full version better) <application>Interactive
479 Disassembler</application> (IDA) from the ftp sites mentioned
480 at the end of the document. Understanding disassembled code is
481 mostly a question of exercise.
482 </para>
483 <para>
484 Most code out there uses standard C function entries (for it
485 is usually written in C). Win16 function entries usually
486 look like that:
487 </para>
488 <programlisting>
489 push bp
490 mov bp, sp
491 ... function code ..
492 retf XXXX <--------- XXXX is number of bytes of arguments
493 </programlisting>
494 <para>
496 storage. The arguments usually start at
500 functions use the PASCAL calling convention. So, if we use
505 </para>
506 <para>
507 Most functions make also use of local storage in the stackframe:
508 </para>
509 <programlisting>
511 ... function code ...
512 leave
513 retf XXXX
514 </programlisting>
515 <para>
516 This does mostly the same as above, but also adds
519 function, arguments are pushed on the stack using something
520 like this:
521 </para>
522 <programlisting>
525 call KERNEL.LSTRLEN
526 </programlisting>
527 <para>
528 Here first the selector and then the offset to the passed
529 string are pushed.
530 </para>
531 </sect2>
533 <sect2>
536 <para>
538 messagebox:
539 </para>
540 <screen>
541 |marcus@jet $ wine winword.exe
542 | +---------------------------------------------+
543 | | ! You must leave Windows and load SHARE.EXE|
544 | | before starting Word. |
545 | +---------------------------------------------+
546 </screen>
547 <screen>
548 |marcus@jet $ wine winword.exe -debugmsg +relay -debug
556 |Loading symbols: /home/marcus/wine/wine...
558 |In 16 bit mode.
565 |... <----- Much debugoutput
567 ^^^^^^ Drive 0 (A:)
569 ^^^^^^ DRIVE_REMOVEABLE
570 (It is a floppy diskdrive.)
573 ^^^^^^ Drive 1 (B:)
575 ^^^^^^ DRIVE_CANNOTDETERMINE
576 (I don't have drive B: assigned)
579 ^^^^^^^ Drive 2 (C:)
581 ^^^^^^ DRIVE_FIXED
582 (specified as a harddisk)
585 ^^^^^^ ^^^^^ ^^^^^^^^^
586 | | |buffer for fname
587 | |temporary name ~docXXXX.tmp
588 |Force use of Drive C:.
590 |Warning: GetTempFileName returns 'C:~doc9281.tmp', which doesn't seem to be writeable.
591 |Please check your configuration file if this generates a failure.
592 </screen>
593 <para>
594 Whoops, it even detects that something is wrong!
595 </para>
596 <screen>
598 ^^^^^^ Temporary storage ID
601 ^^^^^^^^^^^^^^^^ ^^^^^^^^^ ^^^^^^^
602 |filename |OFSTRUCT |open mode:
604 OF_CREATE|OF_SHARE_EXCLUSIVE|OF_READWRITE
605 </screen>
606 <para>
608 this case mounted readonly.
609 </para>
610 <screen>
612 ^^^^^^ HFILE_ERROR16, yes, it failed.
614 |Call USER.1: MESSAGEBOX(0x0000,0x09278376"Sie mussen Windows verlassen und SHARE.EXE laden bevor Sie Word starten.",0x00000000,0x1030) ret=060f:084f ds=0927
615 </screen>
616 <para>
617 And MessageBox'ed.
618 </para>
619 <screen>
622 In 32 bit mode.
623 Wine-dbg>
624 </screen>
625 <para>
626 The code seems to find a writeable harddisk and tries to create
627 a file there. To work around this bug, you can define
629 by the code above.
630 </para>
631 </sect2>
633 <sect2>
636 <para>
637 Here are some useful debugging tips, added by Andreas Mohr:
638 </para>
640 <itemizedlist>
641 <listitem>
642 <para>
643 If you have a program crashing at such an early loader phase that you can't
644 use the Wine debugger normally, but Wine already executes the program's
645 start code, then you may use a special trick. You should do a
646 <programlisting>
647 wine --debugmsg +relay program
648 </programlisting>
649 to get a listing of the functions the program calls in its start function.
650 Now you do a
651 <programlisting>
652 wine --debug winfile.exe
653 </programlisting>
654 </para>
655 <para>
657 can set a breakpoint on any function the program calls in
659 to bypass the eventual calls of Winfile to this function
660 until you are finally at the place where this function gets
661 called by the crashing start function. Now you can proceed
662 with your debugging as usual.
663 </para>
664 </listitem>
665 <listitem>
666 <para>
667 If you try to run a program and it quits after showing an error messagebox,
668 the problem can usually be identified in the return value of one of the
670 That's why you should re-run the program with e.g.
671 <programlisting>
673 </programlisting>
675 last occurrence of a call to the string "MESSAGEBOX". This is a line like
676 <programlisting>
677 Call USER.1: MESSAGEBOX(0x0000,0x01ff1246 "Runtime error 219 at 0004:1056.",0x00000000,0x1010) ret=01f7:2160 ds=01ff
678 </programlisting>
679 In my example the lines before the call to
681 <programlisting>
700 Call USER.1: MESSAGEBOX(0x0000,0x01ff1246 "Runtime error 219 at 0004:1056.",0x00000000,0x1010) ret=01f7:2160 ds=01ff
701 </programlisting>
702 </para>
703 <para>
706 wrong result value of some previously executed function
707 (it's happening quite often like that), but instead the
708 messagebox complains about a runtime error at
710 </para>
711 <para>
712 As the segment value of the address is only
714 program value. But the offset address reveals something
718 <programlisting>
720 ^^^^
721 </programlisting>
722 </para>
723 <para>
727 ftp://ftp.uni-koeln.de/pc/msdos/programming/assembler/ida35bx.zip</ulink>) to
728 disassemble the part that caused the error. We just have to find the address of
730 runtime error occurred. But be careful! In some cases you don't have to
731 disassemble the main program, but instead some DLL called by it in order to find
732 the correct place where the runtime error occurred. That can be determined by
734 </para>
735 </listitem>
736 <listitem>
737 <para>
738 If you have created a relay file of some crashing
739 program and want to set a breakpoint at a certain
740 location which is not yet available as the program loads
741 the breakpoint's segment during execution, you may set a
743 those functions are called very often.
744 </para>
745 <para>
747 set this breakpoint without error message.
748 </para>
749 </listitem>
750 <listitem>
751 <para>
752 Some useful programs:
753 </para>
754 <variablelist>
755 <varlistentry>
756 <term>
758 <filename>
760 ftp://ftp.uni-koeln.de/pc/msdos/programming/assembler/ida35bx.zip</ulink>
761 </filename>
762 </term>
763 <listitem>
764 <para>
766 for debugging Wine sometimes.
767 </para>
768 </listitem>
769 </varlistentry>
770 <varlistentry>
771 <term>
773 <filename>
775 ftp://ftp.th-darmstadt.de/pub/machines/ms-dos/SimTel/msdos/asmutil/xray15.zip</ulink>
776 </filename>
777 </term>
778 <listitem>
779 <para>
780 Traces DOS calls (Int 21h, DPMI, ...). Use it with
781 Windows to correct file management problems etc.
782 </para>
783 </listitem>
784 </varlistentry>
785 <varlistentry>
786 <term>
788 <filename>
790 http://oak.oakland.edu/pub/simtelnet/win95/prog/pedump.zip</ulink>
791 </filename>
792 </term>
793 <listitem>
794 <para>
795 Dumps the imports and exports of a PE (Portable
796 Executable) DLL.
797 </para>
798 </listitem>
799 </varlistentry>
800 </variablelist>
801 </listitem>
802 </itemizedlist>
803 </sect2>
805 <sect2>
808 <para>
809 After starting your program with
810 </para>
811 <screen>
812 wine -debug myprog.exe
813 </screen>
814 <para>
815 the program loads and you get a prompt at the program
816 starting point. Then you can set breakpoints:
817 </para>
818 <screen>
819 b RoutineName (by outine name) OR
820 b *0x812575 (by address)
821 </screen>
822 <para>
824 program. It stops at the breakpoint. You can type
825 </para>
826 <screen>
827 step (to step one line) OR
828 stepi (to step one machine instruction at a time;
829 here, it helps to know the basic 386
830 instruction set)
831 info reg (to see registers)
832 info stack (to see hex values in the stack)
833 info local (to see local variables)
836 is not compiled with optimization)
837 x 0x4269978 (to examine a memory location)
838 ? (help)
839 q (quit)
840 </screen>
841 <para>
843 command.
844 </para>
845 </sect2>
846 </sect1>
851 <para>
853 </para>
854 <para>
855 Wine uses several different kinds of memory addresses.
856 </para>
857 <variablelist>
858 <varlistentry>
859 <term>
860 Win32/"normal" Wine addresses/Linux: linear addresses.
861 </term>
862 <listitem>
863 <para>
864 Linear addresses can be everything from 0x0 up to
865 0xffffffff. In Wine on Linux they are often around
867 address), 0x40000000. Every Win32 process has its own
869 0xffffffff).
870 </para>
871 </listitem>
872 </varlistentry>
873 <varlistentry>
874 <term>
875 Win16 "enhanced mode": segmented addresses.
876 </term>
877 <listitem>
878 <para>
879 These are the "normal" Win16 addresses, called SEGPTR.
881 The segment part usually is a "selector", which *always*
882 has the lowest 3 bits set. Some sample selectors are
884 the lowest bit, as e.g. with 0x1f6,xi then it might be a
885 handle to global memory. Just set the lowest bit to get
886 the selector in these cases. A selector kind of
887 "points" to a certain linear (see above) base address.
888 It has more or less three important attributes: segment
889 base address, segment limit, segment access rights.
890 </para>
891 <para>
892 Example:
893 </para>
894 <para>
896 has a base address of 0x40320000, the segment's last
899 the linear address of 0x40322300.
900 </para>
901 </listitem>
902 </varlistentry>
903 <varlistentry>
904 <term>
905 DOS/Win16 "standard mode"
906 </term>
907 <listitem>
908 <para>
909 They, too, have a segment:offset notation. But they are
910 completely different from "normal" Win16 addresses, as
911 they just represent at most 1MB of memory: The segment
913 with the offset part.
914 </para>
915 <para>
916 Now the strange thing is the calculation that's behind
917 these addresses: Just calculate segment*16 + offset in
918 order to get a "linear DOS" address. So
922 has to be added to the linear base address of the
923 corresponding DOS memory allocated for dosmod in order
924 to get the true linear address of a DOS seg:offs
925 address. And make sure that you're doing this in the
926 correct process with the correct linear address space,
927 of course ;-)
928 </para>
929 </listitem>
930 </varlistentry>
931 </variablelist>
932 </sect1>
937 <sect2>
940 <para>
941 The Windows' debugging API uses a registry entry to know
942 which debugger to invoke when an unhandled exception occurs
945 values in key
946 </para>
947 <programlisting>
948 "MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug"
949 </programlisting>
950 <para>
951 Determine the behavior:
952 </para>
953 <variablelist>
954 <varlistentry>
956 <listitem>
957 <para>
958 this is the command line used to launch the debugger
961 information to the debugger). You should put here a
962 complete path to your debugger
964 any other Windows' debugging API aware debugger will
965 do).
966 The path to the debugger you chose to use must be reachable
967 via a DOS drive in the Wine config file !
968 </para>
969 <para>
970 You can also set a shell script to launch the debugger. In
971 this case, you need to be sure that the invocation in
972 this shell script is of the form:
973 <programlisting>
975 </programlisting>
976 (Shell script must use exec, and the debugger .so file must
977 be preloaded to override the shell script information).
978 </para>
979 </listitem>
980 </varlistentry>
981 <varlistentry>
983 <listitem>
984 <para>
985 if this value is zero, a message box will ask the
986 user if he/she wishes to launch the debugger when an
987 unhandled exception occurs. Otherwise, the debugger
988 is automatically started.
989 </para>
990 </listitem>
991 </varlistentry>
992 </variablelist>
994 <para>
995 A regular Wine registry looks like:
996 </para>
997 <programlisting>
998 [MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug] 957636538
1001 </programlisting>
1003 <note>
1005 <para>
1006 creating this key is mandatory. Not doing so will not
1007 fire the debugger when an exception occurs.
1008 </para>
1009 </note>
1010 <note>
1012 <para>
1014 sets up this correctly.
1015 However, due to some limitation of the registry installed,
1016 if a previous Wine installation exists, it's safer to
1017 remove the whole
1018 </para>
1019 <programlisting>
1020 [MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug]
1021 </programlisting>
1022 <para>
1024 regenerate this key.
1025 </para>
1026 </note>
1027 </sect2>
1029 <sect2>
1032 <para>
1034 of options. Those options are stored in the registry, on a
1036 </para>
1037 <programlisting>
1038 [eric\\Software\\Wine\\WineDbg]
1039 </programlisting>
1040 <para>
1041 Those options can be read/written while inside
1043 expressions. To refer to one of these options, its name must
1045 </para>
1046 <programlisting>
1047 set $BreakAllThreadsStartup = 1
1048 </programlisting>
1049 <para>
1052 </para>
1053 <para>
1054 All the options are read from the registry when
1056 is found, a default value is used), and are written back to
1058 all modifications to those options are automatically saved
1060 </para>
1061 <para>
1062 Here's the list of all options:
1063 </para>
1065 <sect3>
1068 <variablelist>
1069 <varlistentry>
1071 <listitem>
1072 <para>
1074 start-up the debugger stops set to
1076 startup of a given process the debugger stops.
1078 </para>
1079 </listitem>
1080 </varlistentry>
1081 <varlistentry>
1083 <listitem>
1084 <para>
1086 when a critical section times out (5 minutes);
1088 </para>
1089 </listitem>
1090 </varlistentry>
1091 <varlistentry>
1093 <listitem>
1094 <para>
1097 process after an unhandled exception,
1099 first attach event. Since the attach event is
1100 meaningless in the context of an exception event
1101 (the next event which is the exception event is of
1102 course relevant), that option is likely to be
1104 </para>
1105 </listitem>
1106 </varlistentry>
1107 <varlistentry>
1109 <listitem>
1110 <para>
1111 An exception can generate two debug events. The
1112 first one is passed to the debugger (known as a
1113 first chance) just after the exception. The debugger
1114 can then decides either to resume execution (see
1116 command) or pass the exception up to the exception
1117 handler chain in the program (if it exists)
1120 exception handlers takes care of the exception, the
1121 exception event is sent again to the debugger (known
1122 as last chance exception). You cannot pass on a last
1123 exception. When the
1126 both first and last chance execptions (to
1128 chance exceptions).
1129 </para>
1130 </listitem>
1131 </varlistentry>
1132 <varlistentry>
1134 <listitem>
1135 <para>
1137 when a DLL is loaded into memory; when the debugger
1138 is invoked after a crash, the DLLs already mapped in
1139 memory will not trigger this break.
1141 </para>
1142 </listitem>
1143 </varlistentry>
1144 </variablelist>
1145 </sect3>
1147 <sect3>
1150 <variablelist>
1151 <varlistentry>
1153 <listitem>
1154 <para>
1155 Mask of active debugger output channels on console
1156 </para>
1157 </listitem>
1158 </varlistentry>
1159 <varlistentry>
1161 <listitem>
1162 <para>
1164 </para>
1165 </listitem>
1166 </varlistentry>
1167 <varlistentry>
1169 <listitem>
1170 <para>
1174 the debugger uses the current Unix console for
1175 input/output
1176 </para>
1177 </listitem>
1178 </varlistentry>
1179 </variablelist>
1181 <para>
1182 Those last 3 variables are jointly used in two generic ways:
1183 </para>
1185 <orderedlist>
1186 <listitem>
1188 <programlisting>
1189 ConChannelMask = DBG_CHN_MESG (1)
1190 StdChannelMask = 0
1191 UseXTerm = 1
1192 </programlisting>
1193 <para>
1194 In this case, all input/output goes into a specific
1198 wine is run from).
1199 </para>
1200 </listitem>
1201 <listitem>
1202 <para>
1203 to have all input/output go into the tty where Wine
1204 was started from (to be used in a X11-free
1205 environment)
1206 </para>
1207 <screen>
1208 ConChannelMask = 0
1209 StdChannelMask = DBG_CHN_MESG (1)
1210 UseXTerm = 1
1211 </screen>
1212 </listitem>
1213 </orderedlist>
1214 <para>
1215 Those variables also allow, for example for debugging
1216 purposes, to use:
1217 </para>
1218 <screen>
1219 ConChannelMask = 0xfff
1220 StdChannelMask = 0xfff
1221 UseXTerm = 1
1222 </screen>
1223 <para>
1225 output to both tty Wine was started from, and
1230 example >& shell redirect command), you'll get in that
1231 file both outputs. It may be interesting to look in the
1232 relay trace for specific values which the process segv'ed
1233 on.
1234 </para>
1235 </sect3>
1237 <sect3>
1240 <variablelist>
1241 <varlistentry>
1243 <listitem>
1245 examined by the debugger</para>
1246 </listitem>
1247 </varlistentry>
1248 <varlistentry>
1250 <listitem>
1252 examined by the debugger</para>
1253 </listitem>
1254 </varlistentry>
1255 <varlistentry>
1257 <listitem>
1259 </listitem>
1260 </varlistentry>
1261 </variablelist>
1263 <para>
1266 conditional breakpoints on a given thread or process.
1267 </para>
1268 </sect3>
1269 </sect2>
1270 </sect1>
1276 <sect2>
1279 <screen>
1280 abort aborts the debugger
1281 quit exits the debugger
1283 attach N attach to a W-process (N is its ID). IDs can be
1284 obtained using the walk process command
1285 detach detach from a W-process. WineDbg will exit (this may
1286 be changed later on)
1287 </screen>
1288 <screen>
1289 help prints some help on the commands
1290 help info prints some help on info commands
1291 </screen>
1292 <screen>
1295 </screen>
1296 </sect2>
1298 <sect2>
1301 <screen>
1302 cont continue execution until next breakpoint or exception.
1303 pass pass the exception event up to the filter chain.
1304 step continue execution until next C line of code (enters
1305 function call)
1306 next continue execution until next C line of code (doesn't
1307 enter function call)
1308 stepi execute next assembly instruction (enters function
1309 call)
1310 nexti execute next assembly instruction (doesn't enter
1311 function call)
1312 finish do nexti commands until current function is exited
1313 </screen>
1314 <para>
1315 cont, step, next, stepi, nexti can be postfixed by a
1316 number (N), meaning that the command must be executed N
1317 times.
1318 </para>
1319 </sect2>
1321 <sect2>
1324 <screen>
1325 enable N enables (break|watch)point #N
1326 disable N disables (break|watch)point #N
1327 delete N deletes (break|watch)point #N
1328 cond N removes any a existing condition to (break|watch)point N
1330 will be evaluated each time the breakpoint is hit. If
1331 the result is a zero value, the breakpoint isn't
1332 triggered
1333 break * N adds a breakpoint at address N
1336 break N adds a breakpoint at line N of current source file
1337 break adds a breakpoint at current $pc address
1338 watch * N adds a watch command (on write) at address N (on 4 bytes)
1341 info break lists all (break|watch)points (with state)
1342 </screen>
1343 <para>
1346 Pick up the one you want from its number.
1347 </para>
1348 <para>
1350 MYDLL.DLL.myFunc for function myFunc of
1352 </para>
1353 <para>
1355 the entry point of the Dll.
1356 </para>
1357 </sect2>
1359 <sect2>
1362 <screen>
1363 bt print calling stack of current thread
1364 bt N print calling stack of thread of ID N (note: this
1365 doesn't change the position of the current frame as
1366 manipulated by the up & dn commands)
1367 up goes up one frame in current thread's stack
1368 up N goes up N frames in current thread's stack
1369 dn goes down one frame in current thread's stack
1370 dn N goes down N frames in current thread's stack
1371 frame N set N as the current frame for current thread's stack
1372 info local prints information on local variables for current
1373 function
1374 </screen>
1375 </sect2>
1377 <sect2>
1380 <screen>
1381 show dir
1383 dir
1385 </screen>
1386 <screen>
1387 list lists 10 source lines from current position
1388 list - lists 10 source lines before current position
1389 list N lists 10 source lines from line N in current file
1392 list * N lists 10 source lines from address N
1393 </screen>
1394 <para>
1395 You can specify the end target (to change the 10 lines
1396 value) using the ','. For example:
1397 </para>
1398 <screen>
1400 current file
1402 </screen>
1403 </sect2>
1405 <sect2>
1408 <para>
1409 A display is an expression that's evaluated and printed
1411 command.
1412 </para>
1413 <screen>
1414 display lists the active displays
1415 info display (same as above command)
1419 print command for more on formats)
1420 del display N deletes display #N
1421 undisplay N (same as del display)
1422 </screen>
1423 </sect2>
1425 <sect2>
1428 <screen>
1429 disas disassemble from current position
1433 </screen>
1434 </sect2>
1436 <sect2>
1439 <screen>
1441 walk class lists all Windows' class registered in Wine
1442 info share lists all the dynamic libraries loaded the debugged
1443 program (including .so files, NE and PE DLLs)
1444 info module N prints information on module of handle N
1445 walk module lists all modules loaded by debugged program
1446 info queue N prints information on Wine's queue N
1447 walk queue lists all queues allocated in Wine
1448 info regs prints the value of CPU register
1449 info segment N prints information on segment N
1450 info segment lists all allocated segments
1451 info stack prints the values on top of the stack
1452 info map lists all virtual mappings used by the debugged
1453 program
1454 info wnd N prints information of Window of handle N
1455 walk wnd lists all the window hierarchy starting from the
1456 desktop window
1457 walk wnd N lists all the window hierarchy starting from the
1458 window of handle N
1459 walk process lists all w-processes in Wine session
1460 walk thread lists all w-threads in Wine session
1461 walk modref (no longer avail)
1462 </screen>
1463 </sect2>
1465 <sect2>
1468 <screen>
1473 type)
1476 </screen>
1477 <para>
1480 </para>
1481 <screen>
1482 s => an ASCII string
1483 u => an Unicode UTF16 string
1484 i => instructions (disassemble)
1489 printed)
1491 </screen>
1492 </sect2>
1494 <sect2>
1497 <para>
1498 Expressions in Wine Debugger are mostly written in a C form. However, there
1499 are a few discrepancies:
1500 <itemizedlist>
1501 <listitem>
1502 <para>
1503 Identifiers can take a '.' in their names. This allow mainly to access symbols
1504 from different DLLs like USER32.DLL.CreateWindowA
1505 </para>
1506 </listitem>
1507 <listitem>
1508 <para>
1509 The debugger will try to distinguish this writing with structure operations.
1510 Therefore, you can only use the previous writing in operations manipulating
1511 symbols ({break|watch}points, type information command...).
1512 </para>
1513 </listitem>
1514 </itemizedlist>
1515 </para>
1516 </sect2>
1518 </sect1>
1524 <sect2>
1527 <para>
1528 You can also use other debuggers (like
1530 items:
1531 </para>
1532 <para>
1533 You need to attach the unix debugger to the correct unix
1534 process (representing the correct windows thread) (you can
1536 When running the emulator, usually the first two
1538 running the desktop, the first thread of the application is
1540 Winelib program, the first thread of the application is
1542 </para>
1543 <note>
1544 <para>
1546 notion of threads, it won't work with Wine because the
1547 thread abstraction used for implementing Windows' thread
1548 is not 100% mapped onto the linux posix threads
1549 implementation. It means that you'll have to spawn a
1551 thread you wish to debug.
1552 </para>
1553 </note>
1555 <!-- *** Extra content spliced in from article by Andreas Mohr *** -->
1556 <para>
1558 </para>
1559 <para>
1560 Here's how to get info about the current execution status of a
1561 certain Wine process:
1562 </para>
1563 <para>
1564 Change into your Wine source dir and enter:
1565 </para>
1566 <screen>
1567 $ gdb wine
1568 </screen>
1569 <para>
1570 Switch to another console and enter <command>ps ax | grep
1571 wine</command> to find all wine processes. Inside
1573 </para>
1574 <screen>
1576 </screen>
1577 <para>
1579 the Wine processes. Use
1580 </para>
1581 <screen>
1582 (gdb) bt
1583 </screen>
1584 <para>
1585 to get the backtrace of the current Wine process, i.e. the
1586 function call history. That way you can find out what the
1587 current process is doing right now. And then you can use
1588 several times:
1589 </para>
1590 <screen>
1591 (gdb) n
1592 </screen>
1593 <para>
1594 or maybe even
1595 </para>
1596 <screen>
1598 </screen>
1599 <para>
1600 and
1601 </para>
1602 <screen>
1603 (gdb) c
1604 </screen>
1605 <para>
1606 to set a breakpoint at a certain function and continue up to
1607 that function. Finally you can enter
1608 </para>
1609 <screen>
1610 (gdb) detach
1611 </screen>
1612 <para>
1613 to detach from the Wine process.
1614 </para>
1615 <!-- *** End of xtra content *** -->
1616 </sect2>
1618 <sect2>
1621 <para>
1622 You can use any Windows' debugging API compliant debugger
1623 with Wine. Some reports have been made of success with
1624 VisualStudio debugger (in remote mode, only the hub runs
1625 in Wine). GoVest fully runs in Wine.
1626 </para>
1627 </sect2>
1629 <sect2>
1632 <!-- FIXME: convert this into a table -->
1633 <screen>
1634 +----------------------------------+---------------------------------+
1635 | WineDbg | gdb |
1636 +----------------------------------+---------------------------------+
1637 |WineDbg debugs a Windows' process:|gdb debugs a Windows' thread: |
1638 |+ the various threads will be |+ a separate gdb session is |
1639 | handled by the same WineDbg | needed for each thread of |
1640 | session | Windows' process |
1641 |+ a breakpoint will be triggered |+ a breakpoint will be triggered |
1642 | for any thread of the w-process | only for the w-thread debugged |
1643 +----------------------------------+---------------------------------+
1644 |WineDbg supports debug information|gdb supports debug information |
1645 |from: |from: |
1646 |+ stabs (standard Unix format) |+ stabs (standard Unix format) |
1647 |+ Microsoft's C, CodeView, .DBG | |
1648 +----------------------------------+---------------------------------+
1649 </screen>
1650 </sect2>
1651 </sect1>
1657 <para>
1659 in 32 bit applications are).
1660 </para>
1662 </sect1>
1663 </chapter>
1665 <!-- Keep this comment at the end of the file
1666 Local variables:
1667 mode: sgml
1668 sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
1669 End:
1670 -->