| blob | 05e7cbe58af0421fb66b65a6eaffa35895190536 |
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 However, due to some limitation of the registry installed,
1015 if a previous Wine installation exists, it's safer to
1016 remove the whole
1017 </para>
1018 <programlisting>
1019 [MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug]
1020 </programlisting>
1021 <para>
1023 regenerate this key.
1024 </para>
1025 </note>
1026 </sect2>
1028 <sect2>
1031 <para>
1033 of options. Those options are stored in the registry, on a
1035 </para>
1036 <programlisting>
1037 [eric\\Software\\Wine\\WineDbg]
1038 </programlisting>
1039 <para>
1040 Those options can be read/written while inside
1042 expressions. To refer to one of these options, its name must
1044 </para>
1045 <programlisting>
1046 set $BreakAllThreadsStartup = 1
1047 </programlisting>
1048 <para>
1051 </para>
1052 <para>
1053 All the options are read from the registry when
1055 is found, a default value is used), and are written back to
1057 all modifications to those options are automatically saved
1059 </para>
1060 <para>
1061 Here's the list of all options:
1062 </para>
1064 <sect3>
1067 <variablelist>
1068 <varlistentry>
1070 <listitem>
1071 <para>
1073 start-up the debugger stops set to
1075 startup of a given process the debugger stops.
1077 </para>
1078 </listitem>
1079 </varlistentry>
1080 <varlistentry>
1082 <listitem>
1083 <para>
1085 when a critical section times out (5 minutes);
1087 </para>
1088 </listitem>
1089 </varlistentry>
1090 <varlistentry>
1092 <listitem>
1093 <para>
1096 process after an unhandled exception,
1098 first attach event. Since the attach event is
1099 meaningless in the context of an exception event
1100 (the next event which is the exception event is of
1101 course relevant), that option is likely to be
1103 </para>
1104 </listitem>
1105 </varlistentry>
1106 <varlistentry>
1108 <listitem>
1109 <para>
1110 An exception can generate two debug events. The
1111 first one is passed to the debugger (known as a
1112 first chance) just after the exception. The debugger
1113 can then decides either to resume execution (see
1115 command) or pass the exception up to the exception
1116 handler chain in the program (if it exists)
1119 exception handlers takes care of the exception, the
1120 exception event is sent again to the debugger (known
1121 as last chance exception). You cannot pass on a last
1122 exception. When the
1125 both first and last chance execptions (to
1127 chance exceptions).
1128 </para>
1129 </listitem>
1130 </varlistentry>
1131 <varlistentry>
1133 <listitem>
1134 <para>
1136 when a DLL is loaded into memory; when the debugger
1137 is invoked after a crash, the DLLs already mapped in
1138 memory will not trigger this break.
1140 </para>
1141 </listitem>
1142 </varlistentry>
1143 </variablelist>
1144 </sect3>
1146 <sect3>
1149 <variablelist>
1150 <varlistentry>
1152 <listitem>
1153 <para>
1154 Mask of active debugger output channels on console
1155 </para>
1156 </listitem>
1157 </varlistentry>
1158 <varlistentry>
1160 <listitem>
1161 <para>
1163 </para>
1164 </listitem>
1165 </varlistentry>
1166 <varlistentry>
1168 <listitem>
1169 <para>
1173 the debugger uses the current Unix console for
1174 input/output
1175 </para>
1176 </listitem>
1177 </varlistentry>
1178 </variablelist>
1180 <para>
1181 Those last 3 variables are jointly used in two generic ways:
1182 </para>
1184 <orderedlist>
1185 <listitem>
1187 <programlisting>
1188 ConChannelMask = DBG_CHN_MESG (1)
1189 StdChannelMask = 0
1190 UseXTerm = 1
1191 </programlisting>
1192 <para>
1193 In this case, all input/output goes into a specific
1197 wine is run from).
1198 </para>
1199 </listitem>
1200 <listitem>
1201 <para>
1202 to have all input/output go into the tty where Wine
1203 was started from (to be used in a X11-free
1204 environment)
1205 </para>
1206 <screen>
1207 ConChannelMask = 0
1208 StdChannelMask = DBG_CHN_MESG (1)
1209 UseXTerm = 1
1210 </screen>
1211 </listitem>
1212 </orderedlist>
1213 <para>
1214 Those variables also allow, for example for debugging
1215 purposes, to use:
1216 </para>
1217 <screen>
1218 ConChannelMask = 0xfff
1219 StdChannelMask = 0xfff
1220 UseXTerm = 1
1221 </screen>
1222 <para>
1224 output to both tty Wine was started from, and
1229 example >& shell redirect command), you'll get in that
1230 file both outputs. It may be interesting to look in the
1231 relay trace for specific values which the process segv'ed
1232 on.
1233 </para>
1234 </sect3>
1236 <sect3>
1239 <variablelist>
1240 <varlistentry>
1242 <listitem>
1244 examined by the debugger</para>
1245 </listitem>
1246 </varlistentry>
1247 <varlistentry>
1249 <listitem>
1251 examined by the debugger</para>
1252 </listitem>
1253 </varlistentry>
1254 <varlistentry>
1256 <listitem>
1258 </listitem>
1259 </varlistentry>
1260 </variablelist>
1262 <para>
1265 conditional breakpoints on a given thread or process.
1266 </para>
1267 </sect3>
1268 </sect2>
1269 </sect1>
1275 <sect2>
1278 <screen>
1279 abort aborts the debugger
1280 quit exits the debugger
1282 attach N attach to a W-process (N is its ID). IDs can be
1283 obtained thru walk process command
1284 </screen>
1285 <screen>
1286 help prints some help on the commands
1287 help info prints some help on info commands
1288 </screen>
1289 <screen>
1292 </screen>
1293 </sect2>
1295 <sect2>
1298 <screen>
1299 cont continue execution until next breakpoint or exception.
1300 pass pass the exception event up to the filter chain.
1301 step continue execution until next C line of code (enters
1302 function call)
1303 next continue execution until next C line of code (doesn't
1304 enter function call)
1305 stepi execute next assembly instruction (enters function
1306 call)
1307 nexti execute next assembly instruction (doesn't enter
1308 function call)
1309 finish do nexti commands until current function is exited
1310 </screen>
1311 <para>
1312 cont, step, next, stepi, nexti can be postfixed by a
1313 number (N), meaning that the command must be executed N
1314 times.
1315 </para>
1316 </sect2>
1318 <sect2>
1321 <screen>
1322 enable N enables (break|watch)point #N
1323 disable N disables (break|watch)point #N
1324 delete N deletes (break|watch)point #N
1325 cond N removes any a existing condition to (break|watch)point N
1327 will be evaluated each time the breakpoint is hit. If
1328 the result is a zero value, the breakpoint isn't
1329 triggered
1330 break * N adds a breakpoint at address N
1333 break N adds a breakpoint at line N of current source file
1334 break adds a breakpoint at current $pc address
1335 watch * N adds a watch command (on write) at address N (on 4 bytes)
1338 info break lists all (break|watch)points (with state)
1339 </screen>
1340 </sect2>
1342 <sect2>
1345 <screen>
1346 bt print calling stack of current thread
1347 up goes up one frame in current thread's stack
1348 up N goes up N frames in current thread's stack
1349 dn goes down one frame in current thread's stack
1350 dn N goes down N frames in current thread's stack
1351 frame N set N as the current frame
1352 info local prints information on local variables for current
1353 function
1354 </screen>
1355 </sect2>
1357 <sect2>
1360 <screen>
1361 show dir
1363 dir
1365 </screen>
1366 <screen>
1367 list lists 10 source lines from current position
1368 list - lists 10 source lines before current position
1369 list N lists 10 source lines from line N in current file
1372 list * N lists 10 source lines from address N
1373 </screen>
1374 <para>
1375 You can specify the end target (to change the 10 lines
1376 value) using the ','. For example:
1377 </para>
1378 <screen>
1380 current file
1382 </screen>
1383 </sect2>
1385 <sect2>
1388 <para>
1389 A display is an expression that's evaluated and printed
1391 command.
1392 </para>
1393 <screen>
1394 display lists the active displays
1395 info display (same as above command)
1399 print command for more on formats)
1400 del display N deletes display #N
1401 undisplay N (same as del display)
1402 </screen>
1403 </sect2>
1405 <sect2>
1408 <screen>
1409 disas disassemble from current position
1413 </screen>
1414 </sect2>
1416 <sect2>
1419 <screen>
1421 walk class lists all Windows' class registered in Wine
1422 info share lists all the dynamic libraries loaded the debugged
1423 program (including .so files, NE and PE DLLs)
1424 info module N prints information on module of handle N
1425 walk module lists all modules loaded by debugged program
1426 info queue N prints information on Wine's queue N
1427 walk queue lists all queues allocated in Wine
1428 info regs prints the value of CPU register
1429 info segment N prints information on segment N
1430 info segment lists all allocated segments
1431 info stack prints the values on top of the stack
1432 info map lists all virtual mappings used by the debugged
1433 program
1434 info wnd N prints information of Window of handle N
1435 walk wnd lists all the window hierarchy starting from the
1436 desktop window
1437 walk wnd N lists all the window hierarchy starting from the
1438 window of handle N
1439 walk process lists all w-processes in Wine session
1440 walk thread lists all w-threads in Wine session
1441 walk modref (no longer avail)
1442 </screen>
1443 </sect2>
1445 <sect2>
1448 <screen>
1453 type)
1456 </screen>
1457 <para>
1460 </para>
1461 <screen>
1462 s => an ASCII string
1463 u => an Unicode UTF16 string
1464 i => instructions (disassemble)
1469 printed)
1471 </screen>
1472 </sect2>
1473 </sect1>
1479 <sect2>
1482 <para>
1483 You can also use other debuggers (like
1485 items:
1486 </para>
1487 <para>
1488 You need to attach the unix debugger to the correct unix
1489 process (representing the correct windows thread) (you can
1491 When running the emulator, usually the first two
1493 running the desktop, the first thread of the application is
1495 Winelib program, the first thread of the application is
1497 </para>
1498 <note>
1499 <para>
1501 notion of threads, it won't work with Wine because the
1502 thread abstraction used for implementing Windows' thread
1503 is not 100% mapped onto the linux posix threads
1504 implementation. It means that you'll have to spawn a
1506 thread you wish to debug.
1507 </para>
1508 </note>
1510 <!-- *** Extra content spliced in from article by Andreas Mohr *** -->
1511 <para>
1513 </para>
1514 <para>
1515 Here's how to get info about the current execution status of a
1516 certain Wine process:
1517 </para>
1518 <para>
1519 Change into your Wine source dir and enter:
1520 </para>
1521 <screen>
1522 $ gdb wine
1523 </screen>
1524 <para>
1525 Switch to another console and enter <command>ps ax | grep
1526 wine</command> to find all wine processes. Inside
1528 </para>
1529 <screen>
1531 </screen>
1532 <para>
1534 the Wine processes. Use
1535 </para>
1536 <screen>
1537 (gdb) bt
1538 </screen>
1539 <para>
1540 to get the backtrace of the current Wine process, i.e. the
1541 function call history. That way you can find out what the
1542 current process is doing right now. And then you can use
1543 several times:
1544 </para>
1545 <screen>
1546 (gdb) n
1547 </screen>
1548 <para>
1549 or maybe even
1550 </para>
1551 <screen>
1553 </screen>
1554 <para>
1555 and
1556 </para>
1557 <screen>
1558 (gdb) c
1559 </screen>
1560 <para>
1561 to set a breakpoint at a certain function and continue up to
1562 that function. Finally you can enter
1563 </para>
1564 <screen>
1565 (gdb) detach
1566 </screen>
1567 <para>
1568 to detach from the Wine process.
1569 </para>
1570 <!-- *** End of xtra content *** -->
1571 </sect2>
1573 <sect2>
1576 <para>
1577 You can use any Windows' debugging API compliant debugger
1578 with Wine. Some reports have been made of success with
1579 VisualStudio debugger (in remote mode, only the hub runs
1580 in Wine). GoVest fully runs in Wine.
1581 </para>
1582 </sect2>
1584 <sect2>
1587 <!-- FIXME: convert this into a table -->
1588 <screen>
1589 +----------------------------------+---------------------------------+
1590 | WineDbg | gdb |
1591 +----------------------------------+---------------------------------+
1592 |WineDbg debugs a Windows' process:|gdb debugs a Windows' thread: |
1593 |+ the various threads will be |+ a separate gdb session is |
1594 | handled by the same WineDbg | needed for each thread of |
1595 | session | Windows' process |
1596 |+ a breakpoint will be triggered |+ a breakpoint will be triggered |
1597 | for any thread of the w-process | only for the w-thread debugged |
1598 +----------------------------------+---------------------------------+
1599 |WineDbg supports debug information|gdb supports debug information |
1600 |from: |from: |
1601 |+ stabs (standard Unix format) |+ stabs (standard Unix format) |
1602 |+ Microsoft's C, CodeView, .DBG | |
1603 +----------------------------------+---------------------------------+
1604 </screen>
1605 </sect2>
1606 </sect1>
1612 <para>
1614 in 32 bit applications are).
1615 </para>
1617 </sect1>
1618 </chapter>
1620 <!-- Keep this comment at the end of the file
1621 Local variables:
1622 mode: sgml
1623 sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
1624 End:
1625 -->