documentation/debugging.sgml

   1   <chapter id="debugging">
   2     <title>Debugging Wine</title>
   3
   4     <sect1 id="debug-msg">
   5       <title>Debug Messages</title>
   6
   7       <para>
   8         written by Dimitrie O. Paun <email>dimi@cs.toronto.edu</email>, 28 Mar 1998
   9       </para>
  10       <para>
  11         (Extracted from <filename>wine/documentation/debug-msgs</filename>)
  12       </para>
  13
  14       <note>
  15         <para>
  16           The new debugging interface can be considered to be
  17           stable, with the exception of the in-memory message
  18           construction functions. However, there is still a lot of
  19           work to be done to polish things up. To make my life
  20           easier, please follow the guidelines described in this
  21           document.
  22         </para>
  23       </note>
  24
  25       <important>
  26         <para>
  27           Read this document before writing new code. DO NOT USE
  28           <function>fprintf</function>  (or
  29           <function>printf</function>) to output things. Also, instead
  30           of writing  FIXMEs in the source, output a FIXME message if
  31           you can.
  32         </para>
  33         <para>
  34           At the end of the document, there is a "Style Guide" for
  35           debugging messages. Please read it.
  36         </para>
  37       </important>
  38
  39       <sect2>
  40         <title>Debugging classes</title>
  41
  42         <para>
  43           There are 4 types (or classes) of debugging messages:
  44         </para>
  45         <variablelist>
  46           <varlistentry>
  47             <term><literal>FIXME</literal></term>
  48             <listitem>
  49               <para>
  50                 Messages in this class relate to behavior of Wine that
  51                 does not correspond to standard Windows behavior and
  52                 that should be fixed.
  53               </para>
  54               <para>Examples: stubs, semi-implemented features, etc.</para>
  55             </listitem>
  56           </varlistentry>
  57           <varlistentry>
  58             <term><literal>ERR</literal></term>
  59             <listitem>
  60               <para>
  61                 Messages in this class relate to serious errors in
  62                 Wine. This sort of messages are close to asserts --
  63                 that is, you should output an error message when the
  64                 code detects a condition which should not happen. In
  65                 other words, important things that are not warnings
  66                 (see below), are errors.
  67               </para>
  68               <para>
  69                 Examples: unexpected change in internal state, etc.
  70               </para>
  71             </listitem>
  72           </varlistentry>
  73           <varlistentry>
  74             <term><literal>WARN</literal></term>
  75             <listitem>
  76               <para>
  77                 These are warning messages. You should report a
  78                 warning when something unwanted happen but the
  79                 function behaves properly. That is, output a warning
  80                 when you encounter something unexpected (ex: could not
  81                 open a file) but the function deals correctly with the
  82                 situation (that is, according to the docs). If you do
  83                 not deal correctly with it, output a fixme.
  84               </para>
  85               <para>
  86                 Examples: fail to access a resource required by the
  87                 app, etc.
  88               </para>
  89             </listitem>
  90           </varlistentry>
  91           <varlistentry>
  92             <term><literal>TRACE</literal></term>
  93             <listitem>
  94               <para>
  95                 These are detailed debugging messages that are mainly
  96                 useful  to debug a component. These are usually turned
  97                 off.
  98               </para>
  99               <para>
 100                 Examples: everything else that does not fall in one of
 101                 the above mentioned categories and the user does not
 102                 need to know about it.
 103               </para>
 104             </listitem>
 105           </varlistentry>
 106         </variablelist>
 107
 108         <para>
 109           The user has the capability to turn on or off messages of a
 110           particular type. You can expect the following patterns of
 111           usage (but note that  any combination is possible):
 112         </para>
 113         <itemizedlist>
 114           <listitem>
 115             <para>
 116               when you debug a component, all types
 117               (<literal>TRACE</literal>, <literal>WARN</literal>,
 118               <literal>ERR</literal>, <literal>FIXME</literal>) will
 119               be enabled.
 120             </para>
 121           </listitem>
 122           <listitem>
 123             <para>
 124               during the pre-alpha (maybe alpha) stage of Wine, most
 125               likely the <literal>TRACE</literal> class will be
 126               disabled by default, but all others
 127               (<literal>WARN</literal>, <literal>ERR</literal>,
 128               <literal>FIXME</literal>) will be enabled by default.
 129             </para>
 130           </listitem>
 131           <listitem>
 132             <para>
 133               when Wine will become stable, most likely the
 134               <literal>TRACE</literal> and <literal>WARN</literal>
 135               classes will be disabled by default, but all
 136               <literal>ERR</literal>s and <literal>FIXME</literal>s
 137               will be enabled.
 138             </para>
 139           </listitem>
 140           <listitem>
 141             <para>
 142               in some installations that want the smallest footprint
 143               and where the debug information is of no interest,  all
 144               classes may be disabled by default.
 145             </para>
 146           </listitem>
 147         </itemizedlist>
 148         <para>
 149           Of course, the user will have the runtime ability to
 150           override these defaults. However, this ability may be turned
 151           off and certain classes of messages may be completely
 152           disabled at compile time to reduce the  size of Wine.
 153         </para>
 154       </sect2>
 155
 156       <sect2>
 157         <title>Debugging channels</title>
 158
 159         <para>
 160           Also, we divide the debugging messages on a component basis.
 161           Each component is assigned a debugging channel. The
 162           identifier of the channel must be a valid C identifier but
 163           note that it may also be a reserved word like
 164           <type>int</type> or <type>static</type>.
 165         </para>
 166         <para>
 167           Examples of debugging channels:
 168           <simplelist type="inline">
 169             <member><literal>reg</literal></member>
 170             <member><literal>updown</literal></member>
 171             <member><literal>string</literal></member>
 172           </simplelist>
 173         </para>
 174         <para>
 175           We will refer to a generic channel as <literal>xxx</literal>.
 176         </para>
 177         <note>
 178           <para>
 179             for those who know the old interface, the channel/type is
 180             what followed the _ in the
 181             <function>dprintf_xxx</function> statements. For example,
 182             to output a message on the debugging channel
 183             <literal>reg</literal> in the old interface you would had
 184             to write:
 185           </para>
 186           <programlisting>
 187 dprintf_reg(stddeb, "Could not access key!\n");
 188           </programlisting>
 189           <para>
 190             In the new interface, we drop the
 191             <literal>stddeb</literal> as it is implicit. However, we
 192             add an orthogonal piece of information to the message: its
 193             class. This is very important as it will allow us to
 194             selectively turn on or off certain messages based on the
 195             type of information they report. For this reason it is
 196             essential to choose the right class for the message.
 197             Anyhow, suppose we figured that this message should belong
 198             in the <literal>WARN</literal> class, so in the new
 199             interface, you write:
 200           </para>
 201           <programlisting>
 202 WARN(reg, "Could not access key!\n");
 203           </programlisting>
 204         </note>
 205       </sect2>
 206
 207       <sect2>
 208         <title>How to use it</title>
 209
 210         <para>
 211           So, to output a message (class <literal>YYY</literal>) on
 212           channel <literal>xxx</literal>, do:
 213         </para>
 214         <programlisting>
 215 #include "debug.h"
 216
 217 ....
 218
 219 YYY(xxx, "&lt;message&gt;", ...);
 220         </programlisting>
 221         <para>
 222           Some examples from the code:
 223         </para>
 224         <programlisting>
 225 #include "debug.h"
 226
 227 ...
 228
 229   TRACE(crtdll, "CRTDLL_setbuf(file %p buf %p)", file, buf);
 230
 231   WARN(aspi, "Error opening device errno=%d", save_error);
 232         </programlisting>
 233         <para>
 234           If you need to declare a new debugging channel, use it in
 235           your code and then do:
 236         </para>
 237         <screen>
 238 %tools/make_debug
 239         </screen>
 240         <para>
 241           in the root directory of Wine. Note that this will result in
 242           almost complete recompilation of Wine.
 243         </para>
 244
 245         <note>
 246           <orderedlist>
 247             <listitem>
 248               <para>
 249                 Please pay attention to which class you assign the
 250                 message. There are only 4 classes, so it is not hard.
 251                 The reason it is important to get it right is that too
 252                 much information is no information. For example, if
 253                 you put things into the <literal>WARN</literal> class
 254                 that should really be in the <literal>TRACE</literal>
 255                 class, the  output will be too big and this will force
 256                 the user to  turn warnings off. But this way he will
 257                 fail to see the important ones. Also, if you put
 258                 warnings into the <literal>TRACE</literal> class lets
 259                 say, he will most likely miss those because usually
 260                 the <literal>TRACE</literal> class is turned off. A
 261                 similar argument can be made if you mix any other two
 262                 classes.
 263               </para>
 264             </listitem>
 265             <listitem>
 266               <para>
 267                 All lines should end with a newline. If you can NOT
 268                 output everything that you want in the line with only
 269                 one statement, then you need to build the string in
 270                 memory. Please read the section below "In-memory
 271                 messages" on the preferred way to do it. PLEASE USE
 272                 THAT INTERFACE TO BUILD MESSAGES IN MEMORY. The reason
 273                 is that we are not sure that we like it and having
 274                 everything in one format will facilitate the
 275                 (automatic) translation to a better interface.
 276               </para>
 277             </listitem>
 278           </orderedlist>
 279         </note>
 280       </sect2>
 281
 282       <sect2>
 283         <title>Are we debugging?</title>
 284
 285         <para>
 286           To test whether the debugging output of class
 287           <literal>yyy</literal> on channel <literal>xxx</literal> is
 288           enabled, use:
 289         </para>
 290         <screen>
 291 TRACE_ON  to test if TRACE is enabled
 292 WARN_ON   to test if WARN is enabled
 293 FIXME_ON  to test if FIXME is enabled
 294 ERR_ON    to test if ERR is enabled
 295         </screen>
 296         <para>
 297           Examples:
 298         </para>
 299         <programlisting>
 300 if(TRACE_ON(atom)){
 301   ...blah...
 302 }
 303         </programlisting>
 304
 305         <note>
 306           <para>
 307             You should normally need to test only if
 308             <literal>TRACE_ON</literal>. At present, none of the other
 309             3 tests (except for <literal>ERR_ON</literal> which is
 310             used only once!) are used in Wine.
 311           </para>
 312         </note>
 313       </sect2>
 314
 315       <sect2>
 316         <title>In-memory messages</title>
 317
 318         <para>
 319           If you NEED to build the message from multiple calls, you
 320           need to  build it in memory. To do that, you should use the
 321           following interface:
 322         </para>
 323
 324         <orderedlist>
 325           <listitem>
 326             <para>
 327               declare a string (where you are allowed to declare C
 328               variables) as follows:
 329             <programlisting>
 330 dbg_decl_str(name, len);
 331             </programlisting>
 332               where <parameter>name</parameter> is the name of the
 333               string (you should use the channel name on which you
 334               are going to output it)
 335             </para>
 336           </listitem>
 337           <listitem>
 338             <para>
 339               print in it with:
 340             <programlisting>
 341 dsprintf(name, "&lt;message&gt;", ...);
 342             </programlisting>
 343               which is just like a <function>sprintf</function>
 344               function but instead of a C string as first parameter it
 345               takes the name you used to declare it.
 346             </para>
 347           </listitem>
 348           <listitem>
 349             <para>
 350               obtain a pointer to the string with: <function>dbg_str(name)</function>
 351             </para>
 352           </listitem>
 353           <listitem>
 354             <para>
 355               reset the string (if you want to reuse it with):
 356               <programlisting>
 357 dbg_reset_str(name);
 358               </programlisting>
 359             </para>
 360           </listitem>
 361         </orderedlist>
 362
 363         <para>
 364           Example (modified from the code):
 365         </para>
 366         <programlisting>
 367 void some_func(tabs)
 368 {
 369   INT32 i;
 370   LPINT16 p = (LPINT16)tabs;
 371   dbg_decl_str(listbox, 256);                   /* declare the string */
 372
 373   for (i = 0; i &lt; descr-&gt;nb_tabs; i++) {
 374     descr-&gt;tabs[i] = *p++&lt;&lt;1;
 375     if(TRACING(listbox))                         /* write in it only if
 376       dsprintf(listbox, "%hd ", descr-&gt;tabs[i]); /* we are gonna output it */
 377   }
 378   TRACE(listbox, "Listbox %04x: settabstops %s",
 379         wnd-&gt;hwndSelf, dbg_str(listbox));        /* output the whole thing */
 380 }
 381         </programlisting>
 382         <para>
 383           If you need to use it two times in the same scope do like
 384           this:
 385         </para>
 386         <programlisting>
 387 void some_func(tabs)
 388 {
 389   INT32 i;
 390   LPINT16 p = (LPINT16)tabs;
 391   dbg_decl_str(listbox, 256);                   /* declare the string      */
 392
 393   for (i = 0; i &lt; descr-&gt;nb_tabs; i++) {
 394     descr-&gt;tabs[i] = *p++&lt;&lt;1;
 395     if(TRACING(listbox))                         /* write in it only if
 396       dsprintf(listbox, "%hd ", descr-&gt;tabs[i]); /* we are gonna output it */
 397   }
 398   TRACE(listbox, "Listbox %04x: settabstops %s\n",
 399         wnd-&gt;hwndSelf, dbg_str(listbox));        /* output the whole thing */
 400
 401   dbg_reset_str(listbox);                        /* !!!reset the string!!! */
 402   for (i = 0; i &lt; descr-&gt;extrainfo_nr; i++) {
 403     descr-&gt;extrainfo = *p+1;
 404     if(TRACING(listbox))                         /* write in it only if
 405       dsprintf(listbox,"%3d ",descr-&gt;extrainfo); /* we are gonna output it */
 406   }
 407
 408   TRACE(listbox, "Listbox %04x: extrainfo %s\n",
 409         wnd-&gt;hwndSelf, dbg_str(listbox));        /* output the whole thing */
 410
 411 }
 412         </programlisting>
 413
 414         <important>
 415           <para>
 416             As I already stated, I do not think this will be the
 417             ultimate interface for building in-memory debugging
 418             messages. In fact, I do have better ideas which I hope to
 419             have time to implement for the next release. For this
 420             reason, please try not to use it. However, if you need to
 421             output a line in more than one
 422             <function>dprintf_xxx</function> calls, then USE THIS
 423             INTERFACE. DO NOT use other methods. This way, I will
 424             easily translate everything to the new interface (when it
 425             will become available). So, if you need to use it, then
 426             follow the following guidelines:
 427           </para>
 428           <itemizedlist>
 429             <listitem>
 430               <para>wrap calls to <function>dsprintf</function> with a
 431               </para>
 432               <programlisting>
 433 if(YYY(xxx))
 434   dsprintf(xxx,...);
 435               </programlisting>
 436               <para>
 437                 Of course, if the call to
 438                 <function>dsprintf</function> is made from within a
 439                 function  which you know is called only if
 440                 <function>YYY(xxx)</function> is true, for example if
 441                 you call it only like this:
 442               </para>
 443               <programlisting>
 444 if(YYY(xxx))
 445   print_some_debug_info();
 446               </programlisting>
 447               <para>
 448                 then you need not (and should not) wrap calls to
 449                 <function>dsprintf</function> with the before
 450                 mentioned <function>if</function>.
 451               </para>
 452             </listitem>
 453             <listitem>
 454               <para>
 455                 name the string EXACTLY like the debugging channel on
 456                 which is going to be output. Please see the above
 457                 example.
 458               </para>
 459             </listitem>
 460           </itemizedlist>
 461         </important>
 462       </sect2>
 463
 464       <sect2>
 465         <title>Resource identifiers</title>
 466
 467         <para>
 468           Resource identifiers can be either strings or numbers. To
 469           make life a bit easier for outputting these beasts (and to
 470           help you avoid the need to build the message in memory), I
 471           introduced a new function called <function>debugres</function>.
 472         </para>
 473         <para>
 474           The function is defined in <filename>debugstr.h</filename>
 475           and has the following prototype:
 476         </para>
 477         <programlisting>
 478 LPSTR debugres(const void *id);
 479         </programlisting>
 480         <para>
 481           It takes a pointer to the resource id and returns a nicely
 482           formatted string of the identifier. If the high word of the
 483           pointer is <literal>0</literal>, then it assumes that the
 484           identifier is a number and thus returns a string of the
 485           form:
 486         </para>
 487         <programlisting>
 488 #xxxx
 489         </programlisting>
 490         <para>
 491           where <literal>xxxx</literal> are 4 hex-digits representing
 492           the low word of <parameter>id</parameter>.
 493         </para>
 494         <para>
 495           If the high word of the pointer is not <literal>0</literal>,
 496           then it assumes that the identifier is a string and thus
 497           returns a string of the form:
 498         </para>
 499         <programlisting>
 500 '&lt;identifier&gt;'
 501         </programlisting>
 502         <para>
 503           Thus, to use it, do something on the following lines:
 504         </para>
 505         <programlisting>
 506 #include "debug.h"
 507
 508 ...
 509
 510    YYY(xxx, "resource is %s", debugres(myresource));
 511         </programlisting>
 512       </sect2>
 513
 514       <sect2>
 515         <title>The <parameter>--debugmsg</parameter> command line option</title>
 516
 517         <para>
 518           So, the <parameter>--debugmsg</parameter> command line
 519           option has been changed as follows:
 520         </para>
 521         <itemizedlist>
 522           <listitem>
 523             <para>
 524               the new syntax is: <parameter>--debugmsg
 525                 [yyy]#xxx[,[yyy1]#xxx1]*</parameter> where
 526               <literal>#</literal> is either <literal>+</literal> or
 527               <literal>-</literal>
 528             </para>
 529           </listitem>
 530           <listitem>
 531             <para>
 532               when the optional class argument (<literal>yyy</literal>)
 533               is not present, then the statement will
 534               enable(<literal>+</literal>)/disable(<literal>-</literal>)
 535               all messages for the given channel (<literal>xxx</literal>)
 536               on all classes. For example:
 537             </para>
 538             <programlisting>
 539 --debugmsg +reg,-file
 540             </programlisting>
 541             <para>
 542               enables all messages on the <literal>reg</literal>
 543               channel and disables all messages on the
 544               <literal>file</literal> channel. This is same as the old
 545               semantics.
 546             </para>
 547           </listitem>
 548           <listitem>
 549             <para>
 550               when the optional class argument (<literal>yyy</literal>)
 551               is present,  then the statement will enable
 552               (<literal>+</literal>)/disable(<literal>-</literal>)
 553               messages for the given channel (<literal>xxx</literal>)
 554               only on the given class. For example:
 555             </para>
 556             <programlisting>
 557 --debugmsg trace+reg,warn-file
 558             </programlisting>
 559             <para>
 560               enables trace messages on the <literal>reg</literal>
 561               channel and disables warning messages on the
 562               <literal>file</literal> channel.
 563             </para>
 564           </listitem>
 565           <listitem>
 566             <para>
 567               also, the pseudo-channel all is also supported and it
 568               has the  intuitive semantics:
 569             </para>
 570             <screen>
 571     --debugmsg +all      -- enables all debug messages
 572     --debugmsg -all      -- disables all debug messages
 573     --debugmsg yyy+all   -- enables debug messages for class yyy on all
 574                            channels.
 575     --debugmsg yyy-all   -- disables debug messages for class yyy on all
 576                            channels.
 577             </screen>
 578             <para>
 579               So, for example:
 580             </para>
 581             <screen>
 582     --debugmsg warn-all  -- disables all warning messages.
 583             </screen>
 584           </listitem>
 585         </itemizedlist>
 586
 587         <para>
 588           Also, note that at the moment:
 589         </para>
 590         <itemizedlist>
 591           <listitem>
 592             <para>the <literal>FIXME</literal> and <literal>ERR</literal>
 593               classes are enabled by default</para>
 594           </listitem>
 595           <listitem>
 596             <para>the <literal>TRACE</literal> and
 597               <literal>WARN</literal> classes are disabled by
 598               default</para>
 599           </listitem>
 600         </itemizedlist>
 601       </sect2>
 602
 603       <sect2>
 604         <title>Compiling Out Debugging Messages</title>
 605
 606         <para>
 607           To compile out the debugging messages, provide
 608           <command>configure</command> with the following options:
 609         </para>
 610         <screen>
 611     --disable-debug      -- turns off TRACE, WARN, and FIXME (and DUMP).
 612     --disable-trace      -- turns off TRACE only.
 613         </screen>
 614         <para>
 615           This will result in an executable that, when stripped, is
 616           about 15%-20% smaller.  Note, however, that you will not be
 617           able to effectively debug Wine without these messages.
 618         </para>
 619         <para>
 620           This feature has not been extensively tested--it may subtly
 621           break some things.
 622         </para>
 623       </sect2>
 624
 625       <sect2>
 626         <title>A Few Notes on Style</title>
 627
 628         <para>
 629           This new scheme makes certain things more consistent but
 630           there is still room for improvement by using a common style
 631           of debug messages. Before I continue, let me note that the
 632           output format is the following:
 633         </para>
 634         <screen>
 635 yyy:xxx:fff &lt;message&gt;
 636
 637 where:
 638   yyy = the class (fixme, err, warn, trace)
 639   xxx = the channel (atom, win, font, etc)
 640   fff = the function name
 641         </screen>
 642         <para>
 643           these fields are output automatically. All you have to
 644           provide is the &lt;message&gt; part.
 645         </para>
 646         <para>
 647           So here are some ideas:
 648         </para>
 649
 650         <itemizedlist>
 651           <listitem>
 652             <para>do NOT include the name of the function: it is included automatically</para>
 653           </listitem>
 654           <listitem>
 655             <para>
 656               if you want to output the parameters of the function, do
 657               it as the first thing and include them in parentheses,
 658               like this:
 659               <programlisting>
 660 YYY(xxx, "(%d,%p,etc)...\n", par1, par2, ...);
 661               </programlisting>
 662             </para>
 663           </listitem>
 664           <listitem>
 665             <para>
 666               for stubs, you should output a <literal>FIXME</literal>
 667               message. I suggest this style:
 668               <programlisting>
 669    FIXME(xxx, "(%x,%d...): stub\n", par1, par2, ...);
 670               </programlisting>
 671               That is, you output the parameters, then a : and then a string
 672               containing the word "stub". I've seen "empty stub", and others, but I
 673               think that just "stub" suffices.
 674             </para>
 675           </listitem>
 676           <listitem>
 677             <para>
 678               output 1 and ONLY 1 line per message. That is, the format
 679               string should contain only 1 <literal>\n</literal> and it
 680               should always appear at the end of the string. (there are
 681               many reasons  for this requirement, one of them is that
 682               each debug macro adds things to the beginning of the line)
 683             </para>
 684           </listitem>
 685           <listitem>
 686             <para>
 687               if you want to name a value, use <literal>=</literal> and
 688               NOT <literal>:</literal>. That is, instead of saying:
 689               <programlisting>
 690 FIXME(xxx, "(fd: %d, file: %s): stub\n", fd, name);
 691               </programlisting>
 692               say:
 693               <programlisting>
 694 FIXME(xxx, "(fd=%d, file=%s): stub\n", fd, name);
 695               </programlisting>
 696               use <literal>:</literal> to separate categories.
 697             </para>
 698           </listitem>
 699           <listitem>
 700             <para>
 701               try to avoid the style:
 702               <programlisting>
 703 FIXME(xxx, "(fd=%d, file=%s): stub\n", fd, name);
 704               </programlisting>
 705               but use:
 706               <programlisting>
 707 FIXME(xxx, "(fd=%d, file=%s): stub\n", fd, name);
 708               </programlisting>
 709               The reason is that if you want to <command>grep</command>
 710               for things, you would search for <literal>FIXME</literal>
 711               but in the first case there is no additional information
 712               available, where in the second one, there is (e.g. the word
 713               stub)
 714             </para>
 715           </listitem>
 716           <listitem>
 717             <para>
 718               if you output a string s that might contain control
 719               characters, or if <parameter>s</parameter> may be
 720               <literal>NULL</literal>, use
 721               <function>debugstr_a</function> (for ASCII strings, or
 722               <function>debugstr_w</function> for Unicode strings) to
 723               convert <parameter>s</parameter> to a C string, like  this:
 724               <programlisting>
 725 HANDLE32 WINAPI YourFunc(LPCSTR s)
 726 {
 727     FIXME(xxx, "(%s): stub\n", debugstr_a(s));
 728 }
 729               </programlisting>
 730             </para>
 731           </listitem>
 732           <listitem>
 733             <para>
 734               if you want to output a resource identifier, use debugres to
 735               convert it to a string first, like this:
 736               <programlisting>
 737 HANDLE32 WINAPI YourFunc(LPCSTR res)
 738 {
 739     FIXME(xxx, "(res=%s): stub\n", debugres(s));
 740 }
 741               </programlisting>
 742               if the resource identifier is a <type>SEGPTR</type>, use
 743               <function>PTR_SEG_TO_LIN</function> to get a
 744               liner pointer first:
 745               <programlisting>
 746 HRSRC16 WINAPI FindResource16( HMODULE16 hModule, SEGPTR name, SEGPTR type )
 747 {
 748 [...]
 749     TRACE(resource, "module=%04x name=%s type=%s\n",
 750                  hModule, debugres(PTR_SEG_TO_LIN(name)),
 751                  debugres(PTR_SEG_TO_LIN(type)) );
 752 [...]
 753 }
 754               </programlisting>
 755             </para>
 756           </listitem>
 757           <listitem>
 758             <para>
 759               for messages intended for the user (specifically those that
 760               report errors in <filename>wine.conf</filename>), use the
 761               <literal>MSG</literal> macro. Use it like a
 762               <function>printf</function>:
 763               <programlisting>
 764 MSG( "Definition of drive %d is incorrect!\n", drive );
 765               </programlisting>
 766               However, note that there are <emphasis>very</emphasis> few
 767               valid uses of this macro. Most messages are debugging
 768               messages, so chances are you will not need to use this
 769               macro. Grep the source to get an idea where it is
 770               appropriate to use it.
 771             </para>
 772           </listitem>
 773           <listitem>
 774             <para>
 775               For structure dumps, use the <function>DUMP</function>
 776               macro. Use it like a <function>printf</function>, just like
 777               the <literal>MSG</literal> macro. Similarly, there are only
 778               a few valid uses of this macro. Grep the source to see when
 779               to use it.
 780             </para>
 781           </listitem>
 782         </itemizedlist>
 783       </sect2>
 784     </sect1>
 785
 786     <sect1 id="wine-debugger">
 787       <title>Using the Wine Debugger</title>
 788
 789       <para>
 790         written by Marcus Meissner <email>msmeissn@cip.informatik.uni-erlangen.de</email>,
 791         additions welcome.
 792       </para>
 793       <para>
 794         (Extracted from <filename>wine/documentation/debugging</filename>)
 795       </para>
 796
 797       <para>
 798         This file describes where to start debugging Wine. If at any
 799         point you get stuck and want to ask for help, please read the
 800         file <filename>documentation/bugreports</filename> for
 801         information on how to write useful bug reports.
 802       </para>
 803
 804       <sect2>
 805         <title>Crashes</title>
 806
 807         <para>
 808           These usually show up like this:
 809         </para>
 810         <screen>
 811 |Unexpected Windows program segfault - opcode = 8b
 812 |Segmentation fault in Windows program 1b7:c41.
 813 |Loading symbols from ELF file /root/wine/wine...
 814 |....more Loading symbols from ...
 815 |In 16 bit mode.
 816 |Register dump:
 817 | CS:01b7 SS:016f DS:0287 ES:0000
 818 | IP:0c41 SP:878a BP:8796 FLAGS:0246
 819 | AX:811e BX:0000 CX:0000 DX:0000 SI:0001 DI:ffff
 820 |Stack dump:
 821 |0x016f:0x878a:  0001 016f ffed 0000 0000 0287 890b 1e5b
 822 |0x016f:0x879a:  01b7 0001 000d 1050 08b7 016f 0001 000d
 823 |0x016f:0x87aa:  000a 0003 0004 0000 0007 0007 0190 0000
 824 |0x016f:0x87ba:
 825 |
 826 |0050: sel=0287 base=40211d30 limit=0b93f (bytes) 16-bit rw-
 827 |Backtrace:
 828 |0 0x01b7:0x0c41 (PXSRV_FONGETFACENAME+0x7c)
 829 |1 0x01b7:0x1e5b (PXSRV_FONPUTCATFONT+0x2cd)
 830 |2 0x01a7:0x05aa
 831 |3 0x01b7:0x0768 (PXSRV_FONINITFONTS+0x81)
 832 |4 0x014f:0x03ed (PDOXWIN_@SQLCURCB$Q6CBTYPEULN8CBSCTYPE+0x1b1)
 833 |5 0x013f:0x00ac
 834 |
 835 |0x01b7:0x0c41 (PXSRV_FONGETFACENAME+0x7c):  movw        %es:0x38(%bx),%dx
 836         </screen>
 837         <para>
 838           Steps to debug a crash. You may stop at any step, but please
 839           report the bug and provide as much of the information
 840           gathered to the newsgroup or the relevant developer as
 841           feasible.
 842         </para>
 843
 844         <orderedlist>
 845           <listitem>
 846             <para>
 847               Get the reason for the crash. This is usually an access to
 848               an invalid selector, an access to an out of range address
 849               in a valid selector, popping a segmentregister from the
 850               stack or the like. When reporting a crash, report this
 851               <emphasis>whole</emphasis> crashdump even if it doesn't
 852               make sense to you.
 853             </para>
 854             <para>
 855               (In this case it is access to an invalid selector, for
 856               <systemitem>%es</systemitem> is <literal>0000</literal>, as
 857               seen in the register dump).
 858             </para>
 859           </listitem>
 860           <listitem>
 861             <para>
 862               Determine the cause of the crash. Since this is usually
 863               a primary/secondary reaction to a failed or misbehaving
 864               Wine function, rerun Wine with <parameter>-debugmsg
 865                 +relay</parameter> added to the commandline. This will
 866               generate quite a lot of output, but usually the reason is
 867               located in the last call(s).  Those lines usually look like
 868               this:
 869             </para>
 870             <screen>
 871 |Call KERNEL.90: LSTRLEN(0227:0692 "text") ret=01e7:2ce7 ds=0227
 872       ^^^^^^^^^  ^       ^^^^^^^^^ ^^^^^^      ^^^^^^^^^    ^^^^
 873       |          |       |         |           |            |Datasegment
 874       |          |       |         |           |Return address
 875       |          |       |         |textual parameter
 876       |          |       |
 877       |          |       |Argument(s). This one is a win16 segmented pointer.
 878       |          |Function called.
 879       |The module, the function is called in. In this case it is KERNEL.
 880
 881 |Ret  KERNEL.90: LSTRLEN() retval=0x0004 ret=01e7:2ce7 ds=0227
 882                                   ^^^^^^
 883                                   |Returnvalue is 16 bit and has the value 4.
 884             </screen>
 885           </listitem>
 886           <listitem>
 887             <para>
 888               If you have found a misbehaving function, try to find out
 889               why it misbehaves. Find the function in the source code.
 890               Try to make sense of the arguments passed. Usually there is
 891               a <function>TRACE(&lt;channel&gt;,"(...)\n");</function> at
 892               the beginning of the function. Rerun wine with
 893               <parameter>-debugmsg +xyz,+relay</parameter> added to the
 894               commandline.
 895             </para>
 896           </listitem>
 897           <listitem>
 898             <para>
 899               Additional information on how to debug using the internal
 900               debugger can be  found in
 901               <filename>debugger/README</filename>.
 902             </para>
 903           </listitem>
 904           <listitem>
 905             <para>
 906               If this information isn't clear enough or if you want to
 907               know more about what's happening in the function itself,
 908               try running wine with <parameter>-debugmsg
 909                 +all</parameter>, which dumps ALL included debug
 910               information in wine.
 911             </para>
 912           </listitem>
 913           <listitem>
 914             <para>
 915               If even that isn't enough, add more debug output for
 916               yourself into the functions you find relevant.  See
 917               <filename>documentation/debug-msgs</filename>. You might
 918               also try to run the program in <command>gdb</command>
 919               instead of using the WINE-debugger. If you do that, use
 920               <parameter>handle SIGSEGV nostop noprint</parameter> to
 921               disable the handling of seg faults inside
 922               <command>gdb</command> (needed for Win16). If you don't use
 923               the <parameter>--desktop</parameter> or
 924               <parameter>--managed</parameter> option, start the WINE
 925               process with <parameter>--sync</parameter>, or chances are
 926               good to get X into an unusable state.
 927             </para>
 928           </listitem>
 929           <listitem>
 930             <para>
 931               You can also set a breakpoint for that function. Start wine
 932               with the <parameter>--debug</parameter> option added to the
 933               commandline. After loading the executable wine will enter
 934               the internal debugger. Use <parameter>break
 935                 KERNEL_LSTRLEN</parameter> (replace by function you want
 936               to debug, CASE IS RELEVANT) to set a breakpoint.  Then use
 937               <command>continue</command> to start normal
 938               program-execution. Wine will stop if it reaches the
 939               breakpoint. If the program isn't yet at the crashing call
 940               of that function, use <command>continue</command> again
 941               until you are about to enter that function. You may now
 942               proceed with single-stepping the function until you reach
 943               the point of crash. Use the other debugger commands to
 944               print registers and the like.
 945             </para>
 946           </listitem>
 947         </orderedlist>
 948       </sect2>
 949
 950       <sect2>
 951         <title>Program hangs, nothing happens</title>
 952
 953         <para>
 954           Switch to UNIX shell, get the process-ID using <command>ps -a |
 955             grep wine</command>, and do a <command>kill -HUP
 956             &lt;pid&gt;</command> (without the &lt; and &gt;). Wine will
 957           then enter its internal debugger and you can proceed as
 958           explained above. Also, you can use
 959           <parameter>--debug</parameter> switch and then you can get into
 960           internal debugger by pressing
 961           <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> in
 962           the terminal where you run Wine.
 963         </para>
 964       </sect2>
 965
 966       <sect2>
 967         <title>Program reports an error with a Messagebox</title>
 968
 969         <para>
 970           Sometimes programs are reporting failure using more or
 971           less nondescript messageboxes. We can debug this using the
 972           same method as Crashes, but there is one problem... For
 973           setting up a message box the program also calls Wine
 974           producing huge chunks of debug code.
 975         </para>
 976         <para>
 977           Since the failure happens usually directly before setting up
 978           the Messagebox you can start wine with
 979           <parameter>--debug</parameter> added to the commandline, set a
 980           breakpoint at <function>MessageBoxA</function> (called by win16
 981           and win32 programs) and proceed with
 982           <command>continue</command>. With <parameter>--debugmsg
 983             +all</parameter> Wine will now stop directly before setting
 984           up the Messagebox. Proceed as explained above.
 985         </para>
 986         <para>
 987           You can also run wine using <command>wine -debugmsg +relay
 988             program.exe 2&gt;&1 | less -i</command> and in
 989           <command>less</command> search for <quote>MessageBox</quote>.
 990         </para>
 991       </sect2>
 992
 993       <sect2>
 994         <title>Disassembling programs:</title>
 995
 996         <para>
 997           You may also try to disassemble the offending program to
 998           check for undocumented features and/or use of them.
 999         </para>
1000         <para>
1001           The best, freely available, disassembler for Win16 programs is
1002           <application>Windows Codeback</application>, archivename
1003           <filename>wcbxxx.zip</filename>, which usually can be found in
1004           the <filename>Cica-Mirror</filename> subdirectory on the WINE
1005           ftpsites. (See <filename>ANNOUNCE</filename>).
1006         </para>
1007         <para>
1008           Disassembling win32 programs is possible using
1009           <application>Windows Disassembler 32</application>, archivename
1010           something like <filename>w32dsm87.zip</filename> (or similar)
1011           on <systemitem class="systemname">ftp.winsite.com</systemitem>
1012           and mirrors.  The shareware version does not allow saving of
1013           disassembly listings. You can also use the newer (and in the
1014           full version better) <application>Interactive
1015             Disassembler</application> (IDA) from the ftp sites mentioned
1016           at the end of the document. Understanding disassembled code is
1017           mostly a question of exercise.
1018         </para>
1019         <para>
1020           Most code out there uses standard C function entries (for it
1021           is usually  written in C). Win16 function entries usually
1022           look like that:
1023         </para>
1024         <programlisting>
1025 push bp
1026 mov bp, sp
1027 ... function code ..
1028 retf XXXX       &lt;--------- XXXX is number of bytes of arguments
1029         </programlisting>
1030         <para>
1031           This is a <function>FAR</function> function with no local
1032           storage. The arguments usually start at
1033           <literal>[bp+6]</literal> with increasing offsets. Note, that
1034           <literal>[bp+6]</literal> belongs to the
1035           <emphasis>rightmost</emphasis> argument, for exported win16
1036           functions use the PASCAL calling convention. So, if we use
1037           <function>strcmp(a,b)</function> with <parameter>a</parameter>
1038           and <parameter>b</parameter> both 32 bit variables
1039           <parameter>b</parameter> would be at <literal>[bp+6]</literal>
1040           and <parameter>a</parameter> at <literal>[bp+10]</literal>.
1041         </para>
1042         <para>
1043           Most functions make also use of local storage in the stackframe:
1044         </para>
1045         <programlisting>
1046 enter 0086, 00
1047 ... function code ...
1048 leave
1049 retf XXXX
1050         </programlisting>
1051         <para>
1052           This does mostly the same as above, but also adds
1053           <literal>0x86</literal> bytes of stackstorage, which is
1054           accessed using <literal>[bp-xx]</literal>. Before calling a
1055           function, arguments are pushed on the stack using something
1056           like this:
1057         </para>
1058         <programlisting>
1059 push word ptr [bp-02]   &lt;- will be at [bp+8]
1060 push di                 &lt;- will be at [bp+6]
1061 call KERNEL.LSTRLEN
1062         </programlisting>
1063         <para>
1064           Here first the selector and then the offset to the passed
1065           string are pushed.
1066         </para>
1067       </sect2>
1068
1069       <sect2>
1070         <title>Sample debugging session:</title>
1071
1072         <para>
1073           Let's debug the infamous Word <filename>SHARE.EXE</filename>
1074           messagebox:
1075         </para>
1076         <screen>
1077 |marcus@jet $ wine winword.exe
1078 |            +---------------------------------------------+
1079 |            | !  You must leave Windows and load SHARE.EXE|
1080 |            |    before starting Word.                    |
1081 |            +---------------------------------------------+
1082         </screen>
1083         <screen>
1084 |marcus@jet $ wine winword.exe -debugmsg +relay -debug
1085 |CallTo32(wndproc=0x40065bc0,hwnd=000001ac,msg=00000081,wp=00000000,lp=00000000)
1086 |Win16 task 'winword': Breakpoint 1 at 0x01d7:0x001a
1087 |CallTo16(func=0127:0070,ds=0927)
1088 |Call WPROCS.24: TASK_RESCHEDULE() ret=00b7:1456 ds=0927
1089 |Ret  WPROCS.24: TASK_RESCHEDULE() retval=0x8672 ret=00b7:1456 ds=0927
1090 |CallTo16(func=01d7:001a,ds=0927)
1091 |     AX=0000 BX=3cb4 CX=1f40 DX=0000 SI=0000 DI=0927 BP=0000 ES=11f7
1092 |Loading symbols: /home/marcus/wine/wine...
1093 |Stopped on breakpoint 1 at 0x01d7:0x001a
1094 |In 16 bit mode.
1095 |Wine-dbg&gt;break MessageBoxA                          &lt;---- Set Breakpoint
1096 |Breakpoint 2 at 0x40189100 (MessageBoxA [msgbox.c:190])
1097 |Wine-dbg&gt;c                                            &lt;---- Continue
1098 |Call KERNEL.91: INITTASK() ret=0157:0022 ds=08a7
1099 |     AX=0000 BX=3cb4 CX=1f40 DX=0000 SI=0000 DI=08a7 ES=11d7 EFL=00000286
1100 |CallTo16(func=090f:085c,ds=0dcf,0x0000,0x0000,0x0000,0x0000,0x0800,0x0000,0x0000,0x0dcf)
1101 |...                                                   &lt;----- Much debugoutput
1102 |Call KERNEL.136: GETDRIVETYPE(0x0000) ret=060f:097b ds=0927
1103                                ^^^^^^ Drive 0 (A:)
1104 |Ret  KERNEL.136: GETDRIVETYPE() retval=0x0002 ret=060f:097b ds=0927
1105                                         ^^^^^^  DRIVE_REMOVEABLE
1106                                                 (It is a floppy diskdrive.)
1107
1108 |Call KERNEL.136: GETDRIVETYPE(0x0001) ret=060f:097b ds=0927
1109                                ^^^^^^ Drive 1 (B:)
1110 |Ret  KERNEL.136: GETDRIVETYPE() retval=0x0000 ret=060f:097b ds=0927
1111                                         ^^^^^^  DRIVE_CANNOTDETERMINE
1112                                                 (I don't have drive B: assigned)
1113
1114 |Call KERNEL.136: GETDRIVETYPE(0x0002) ret=060f:097b ds=0927
1115                                ^^^^^^^ Drive 2 (C:)
1116 |Ret  KERNEL.136: GETDRIVETYPE() retval=0x0003 ret=060f:097b ds=0927
1117                                         ^^^^^^ DRIVE_FIXED
1118                                                (specified as a harddisk)
1119
1120 |Call KERNEL.97: GETTEMPFILENAME(0x00c3,0x09278364"doc",0x0000,0927:8248) ret=060f:09b1 ds=0927
1121                                  ^^^^^^           ^^^^^        ^^^^^^^^^
1122                                  |                |            |buffer for fname
1123                                  |                |temporary name ~docXXXX.tmp
1124                                  |Force use of Drive C:.
1125
1126 |Warning: GetTempFileName returns 'C:~doc9281.tmp', which doesn't seem to be writeable.
1127 |Please check your configuration file if this generates a failure.
1128         </screen>
1129         <para>
1130           Whoops, it even detects that something is wrong!
1131         </para>
1132         <screen>
1133 |Ret  KERNEL.97: GETTEMPFILENAME() retval=0x9281 ret=060f:09b1 ds=0927
1134                                           ^^^^^^ Temporary storage ID
1135
1136 |Call KERNEL.74: OPENFILE(0x09278248"C:~doc9281.tmp",0927:82da,0x1012) ret=060f:09d8 ds=0927
1137                                     ^^^^^^^^^^^^^^^^ ^^^^^^^^^ ^^^^^^^
1138                                     |filename        |OFSTRUCT |open mode:
1139
1140                                        OF_CREATE|OF_SHARE_EXCLUSIVE|OF_READWRITE
1141         </screen>
1142         <para>
1143           This fails, since my <medialabel>C:</medialabel> drive is in
1144           this case mounted readonly.
1145         </para>
1146         <screen>
1147 |Ret  KERNEL.74: OPENFILE() retval=0xffff ret=060f:09d8 ds=0927
1148                                    ^^^^^^ HFILE_ERROR16, yes, it failed.
1149
1150 |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
1151         </screen>
1152         <para>
1153           And MessageBox'ed.
1154         </para>
1155         <screen>
1156 |Stopped on breakpoint 2 at 0x40189100 (MessageBoxA [msgbox.c:190])
1157 |190     {              &lt;- the sourceline
1158 In 32 bit mode.
1159 Wine-dbg&gt;
1160         </screen>
1161         <para>
1162           The code seems to find a writeable harddisk and tries to create
1163           a file there. To work around this bug, you can define
1164           <medialabel>C:</medialabel> as a networkdrive, which is ignored
1165           by the code above.
1166         </para>
1167       </sect2>
1168
1169       <sect2>
1170         <title>Debugging Tips</title>
1171
1172         <para>
1173           Here are some useful debugging tips, added by Andreas Mohr:
1174         </para>
1175
1176         <itemizedlist>
1177           <listitem>
1178             <para>
1179               If you have a program crashing at such an early loader phase that you can't
1180               use the Wine debugger normally, but Wine already executes the program's
1181               start code, then you may use a special trick. You should do a
1182               <programlisting>
1183 wine --debugmsg +relay program
1184               </programlisting>
1185               to get a listing of the functions the program calls in its start function.
1186               Now you do a
1187               <programlisting>
1188 wine --debug winfile.exe
1189               </programlisting>
1190             </para>
1191             <para>
1192               This way, you get into <command>Wine-dbg</command>. Now you
1193               can set a breakpoint on any function the program calls in
1194               the start function and just type <userinput>c</userinput>
1195               to bypass the eventual calls of Winfile to this function
1196               until you are finally at the place where this function gets
1197               called by the crashing start function. Now you can proceed
1198               with your debugging as usual.
1199             </para>
1200           </listitem>
1201           <listitem>
1202             <para>
1203               If you try to run a program and it quits after showing an error messagebox,
1204               the problem can usually be identified in the return value of one of the
1205               functions executed before <function>MessageBox()</function>.
1206               That's why you should re-run the program with e.g.
1207               <programlisting>
1208 wine --debugmsg +relay &lt;program name&gt; &&gt;relmsg
1209               </programlisting>
1210               Then do a <command>more relmsg</command> and search for the
1211               last occurrence of a call to the string "MESSAGEBOX". This is a line like
1212               <programlisting>
1213 Call USER.1: MESSAGEBOX(0x0000,0x01ff1246 "Runtime error 219 at 0004:1056.",0x00000000,0x1010) ret=01f7:2160 ds=01ff
1214               </programlisting>
1215               In my example the lines before the call to
1216               <function>MessageBox()</function> look like that:
1217               <programlisting>
1218 Call KERNEL.96: FREELIBRARY(0x0347) ret=01cf:1033 ds=01ff
1219 CallTo16(func=033f:0072,ds=01ff,0x0000)
1220 Ret  KERNEL.96: FREELIBRARY() retval=0x0001 ret=01cf:1033 ds=01ff
1221 Call KERNEL.96: FREELIBRARY(0x036f) ret=01cf:1043 ds=01ff
1222 CallTo16(func=0367:0072,ds=01ff,0x0000)
1223 Ret  KERNEL.96: FREELIBRARY() retval=0x0001 ret=01cf:1043 ds=01ff
1224 Call KERNEL.96: FREELIBRARY(0x031f) ret=01cf:105c ds=01ff
1225 CallTo16(func=0317:0072,ds=01ff,0x0000)
1226 Ret  KERNEL.96: FREELIBRARY() retval=0x0001 ret=01cf:105c ds=01ff
1227 Call USER.171: WINHELP(0x02ac,0x01ff05b4 "COMET.HLP",0x0002,0x00000000) ret=01cf:1070 ds=01ff
1228 CallTo16(func=0117:0080,ds=01ff)
1229 Call WPROCS.24: TASK_RESCHEDULE() ret=00a7:0a2d ds=002b
1230 Ret  WPROCS.24: TASK_RESCHEDULE() retval=0x0000 ret=00a7:0a2d ds=002b
1231 Ret  USER.171: WINHELP() retval=0x0001 ret=01cf:1070 ds=01ff
1232 Call KERNEL.96: FREELIBRARY(0x01be) ret=01df:3e29 ds=01ff
1233 Ret  KERNEL.96: FREELIBRARY() retval=0x0000 ret=01df:3e29 ds=01ff
1234 Call KERNEL.52: FREEPROCINSTANCE(0x02cf00ba) ret=01f7:1460 ds=01ff
1235 Ret  KERNEL.52: FREEPROCINSTANCE() retval=0x0001 ret=01f7:1460 ds=01ff
1236 Call USER.1: MESSAGEBOX(0x0000,0x01ff1246 "Runtime error 219 at 0004:1056.",0x00000000,0x1010) ret=01f7:2160 ds=01ff
1237               </programlisting>
1238             </para>
1239             <para>
1240               I think that the call to <function>MessageBox()</function>
1241               in this example is <emphasis>not</emphasis> caused by a
1242               wrong result value of some previously executed function
1243               (it's happening quite often like that), but instead the
1244               messagebox complains about a runtime error at
1245               <literal>0x0004:0x1056</literal>.
1246             </para>
1247             <para>
1248               As the segment value of the address is only
1249               <literal>4</literal>, I think that that is only an internal
1250               program value. But the offset address reveals something
1251               quite interesting: Offset <literal>1056</literal> is
1252               <emphasis>very</emphasis> close to the return address of
1253               <function>FREELIBRARY()</function>:
1254               <programlisting>
1255 Call KERNEL.96: FREELIBRARY(0x031f) ret=01cf:105c ds=01ff
1256                                              ^^^^
1257               </programlisting>
1258             </para>
1259             <para>
1260               Provided that segment <literal>0x0004</literal> is indeed segment
1261               <literal>0x1cf</literal>, we now we can use IDA                 (available at
1262               <ulink url="ftp://ftp.uni-koeln.de/pc/msdos/programming/assembler/ida35bx.zip">
1263                 ftp://ftp.uni-koeln.de/pc/msdos/programming/assembler/ida35bx.zip</ulink>) to
1264               disassemble the part that caused the error. We just have to find the address of
1265               the call to <function>FreeLibrary()</function>. Some lines before that the
1266               runtime error occurred. But be careful! In some cases you don't have to
1267               disassemble the main program, but instead some DLL called by it in order to find
1268               the correct place where the runtime error occurred. That can be determined by
1269               finding the origin of the segment value (in this case <literal>0x1cf</literal>).
1270             </para>
1271           </listitem>
1272           <listitem>
1273             <para>
1274               If you have created a relay file of some crashing
1275               program and want to set a breakpoint at a certain
1276               location which is not yet available as the program loads
1277               the breakpoint's segment during execution, you may set a
1278               breakpoint to <function>GetVersion16/32</function> as
1279               those functions are called very often.
1280             </para>
1281             <para>
1282               Then do a <userinput>c</userinput> until you are able to
1283               set this breakpoint without error message.
1284             </para>
1285           </listitem>
1286           <listitem>
1287             <para>
1288               Some useful programs:
1289             </para>
1290             <variablelist>
1291               <varlistentry>
1292                 <term>
1293                   <application>IDA</application>:
1294                   <filename>
1295                     <ulink url="ftp://ftp.uni-koeln.de/pc/msdos/programming/assembler/ida35bx.zip">
1296                       ftp://ftp.uni-koeln.de/pc/msdos/programming/assembler/ida35bx.zip</ulink>
1297                   </filename>
1298                 </term>
1299                 <listitem>
1300                   <para>
1301                     *Very* good DOS disassembler ! It's badly needed
1302                     for debugging Wine sometimes.
1303                   </para>
1304                 </listitem>
1305               </varlistentry>
1306               <varlistentry>
1307                 <term>
1308                   <application>XRAY</application>:
1309                   <filename>
1310                     <ulink url="ftp://ftp.th-darmstadt.de/pub/machines/ms-dos/SimTel/msdos/asmutil/xray15.zip">
1311                       ftp://ftp.th-darmstadt.de/pub/machines/ms-dos/SimTel/msdos/asmutil/xray15.zip</ulink>
1312                   </filename>
1313                 </term>
1314                 <listitem>
1315                   <para>
1316                     Traces DOS calls (Int 21h, DPMI, ...). Use it with
1317                     Windows to correct file management problems etc.
1318                   </para>
1319                 </listitem>
1320               </varlistentry>
1321               <varlistentry>
1322                 <term>
1323                   <application>pedump</application>:
1324                   <filename>
1325                     <ulink url="http://oak.oakland.edu/pub/simtelnet/win95/prog/pedump.zip">
1326                       http://oak.oakland.edu/pub/simtelnet/win95/prog/pedump.zip</ulink>
1327                   </filename>
1328                 </term>
1329                 <listitem>
1330                   <para>
1331                     Dumps the imports and exports of a PE (Portable
1332                     Executable) DLL.
1333                   </para>
1334                 </listitem>
1335               </varlistentry>
1336             </variablelist>
1337           </listitem>
1338         </itemizedlist>
1339       </sect2>
1340
1341       <sect2>
1342     <title>Some basic debugger usages:</title>
1343
1344         <para>
1345           After starting your program with
1346         </para>
1347         <screen>
1348 wine -debug myprog.exe
1349         </screen>
1350         <para>
1351           the program loads and you get a prompt at the program
1352           starting point. Then you can set breakpoints:
1353         </para>
1354         <screen>
1355   b RoutineName      (by outine name) OR
1356   b *0x812575        (by address)
1357         </screen>
1358         <para>
1359           Then you hit <command>c</command> (continue) to run the
1360           program. It stops at the breakpoint. You can type
1361         </para>
1362         <screen>
1363   step               (to step one line) OR
1364   stepi              (to step one machine instruction at a time;
1365                       here, it helps to know the basic 386
1366                       instruction set)
1367   info reg           (to see registers)
1368   info stack         (to see hex values in the stack)
1369   info local         (to see local variables)
1370   list &lt;line number&gt; (to list source code)
1371   x &lt;variable name&gt;  (to examine a variable; only works if code
1372                       is not compiled with optimization)
1373   x 0x4269978        (to examine a memory location)
1374   ?                  (help)
1375   q                  (quit)
1376         </screen>
1377         <para>
1378           By hitting <keycap>Enter</keycap>, you repeat the last
1379           command.
1380         </para>
1381       </sect2>
1382     </sect1>
1383
1384     <sect1 id="cvs-regression">
1385       <title>How to do regression testing using Cvs</title>
1386
1387       <para>
1388         written by Gerard Patel (???)
1389       </para>
1390       <para>
1391         (Extracted from <filename>wine/documentation/bugreports</filename>)
1392       </para>
1393
1394       <para>
1395         A problem that can happen sometimes is 'it used to work
1396         before, now it doesn't anymore...'. Here is a step by step
1397         procedure to try to pinpoint when the problem occured. This is
1398         *NOT* for casual users.
1399       </para>
1400
1401       <orderedlist>
1402         <listitem>
1403           <para>
1404             Get the 'full cvs' archive from winehq. This archive is
1405             the cvs tree but with the tags controling the versioning
1406             system. It's a big file (> 15 meg) with a name like
1407             full-cvs-&lt;last update date&gt; (it's more than 100mb
1408             when uncompressed, you can't very well do this with
1409             small, old computers or slow Internet connections).
1410           </para>
1411         </listitem>
1412         <listitem>
1413           <para>
1414             untar it into a repository directory:
1415             <screen>
1416 cd /home/gerard
1417 tar -zxffull-cvs-2000-05-20.tar.gz
1418 mv wine repository
1419             </screen>
1420           </para>
1421         </listitem>
1422         <listitem>
1423           <para>
1424             extract a new destination directory. This directory must
1425             not be in a subdirectory of the repository else
1426             <command>cvs</command> will think it's part of the
1427             repository and deny you an extraction in the repository:
1428           <screen>
1429 cd /home/gerard
1430 mv wine wine_current (-> this protects your current wine sandbox, if any)
1431 export CVSROOT=/home/gerard/repository
1432 cd /home/gerard
1433 cvs -d $CVSROOT checkout wine
1434           </screen>
1435           </para>
1436           <para>
1437             Note that it's not possible to do a checkout at a given
1438             date; you always do the checkout for the last date where
1439             the full-cvs-xxx snapshot was generated.
1440           </para>
1441         </listitem>
1442         <listitem>
1443           <para>
1444             you will have now in the <filename>~/wine</filename>
1445             directory an image of the cvs tree, on the client side.
1446             Now update this image to the date you want:
1447           <screen>
1448 cd /home/gerard/wine
1449 cvs -d $CVSROOT update -D "1999-06-01"
1450           </screen>
1451           </para>
1452           <para>
1453             The date format is <literal>YYYY-MM-DD</literal>.
1454           </para>
1455           <para>
1456             Many messages will inform you that more recent files have
1457             been deleted to set back the client cvs tree to the date
1458             you asked, for example:
1459           <screen>
1460 cvs update: tsx11/ts_xf86dga2.c is no longer in the repository
1461           </screen>
1462           </para>
1463           <para>
1464             <command>cvs update</command> is not limited to upgrade to
1465             a *newer* version as I have believed for far too long :-(
1466           </para>
1467         </listitem>
1468         <listitem>
1469           <para>
1470             Now proceed as for a normal update:
1471           </para>
1472           <screen>
1473 ./configure
1474 make depend && make
1475           </screen>
1476           <para>
1477             When you have found the exact date when a bug was added to
1478             the cvs tree, use something like :
1479           <screen>
1480 cvs -d $CVSROOT diff -D "1999-07-10" -D "1999-07-12"
1481           </screen>
1482             to get all the differences between the last cvs tree
1483             version known to work and code that first displayed the
1484             misbehavior.
1485           </para>
1486           <note>
1487             <para>
1488               I did not include flags for <command>diff</command>
1489               since they are in my <filename>.cvsrc</filename> file:
1490             </para>
1491             <screen>
1492 cvs -z 3
1493 update -dPA
1494 diff -u
1495             </screen>
1496           </note>
1497           <para>
1498             From this diff file, particularly the file names, and the
1499             <filename>ChangeLog</filename>, it's usually possible to
1500             find the different individual patches that were done at
1501             this time.
1502           </para>
1503           <para>
1504             If any non-programmer reads this, the fastest method to get
1505             at the point where the problem occured is to use a binary
1506             search, that is, if the problem occured in 1999, start at
1507             mid-year, then is the problem is already here, back to 1st
1508             April, if not, to 1st October, and so on.
1509           </para>
1510         </listitem>
1511         <listitem>
1512           <para>
1513             The next step is to start from the last working version
1514             and to dig the individual contributions from
1515             <ulink url="http://www.integrita.com/cgi-local/lwgate.pl/WINE-PATCHES/">
1516               http://www.integrita.com/cgi-local/lwgate.pl/WINE-PATCHES/</ulink>
1517             (where the Wine patches mailing list is archived)
1518           </para>
1519           <para>
1520             If the patch was done by the Wine maintainer or if it was
1521             sent directly to his mail address without going first through
1522            <ulink url="mailto:wine-patches@winehq.com">wine-patches</ulink>,
1523             you are out of luck as you will never find the patch in
1524             the archive. If it is, it's often possible to apply the
1525             patches one by one to last working cvs snapshot, compile and test.
1526             If you have saved the next candidate as
1527             <filename>/home/gerard/buggedpatch1.txt</filename>:
1528           </para>
1529           <screen>
1530 cd /home/gerard/wine
1531 patch -p 0 &lt; /home/gerard/buggedpatch1.txt
1532           </screen>
1533           <para>
1534             Beware that the committed patch is not always identical to
1535             the patch that the author sent to wine-patches, as
1536             sometimes the Wine maintainer changes things a bit.
1537           </para>
1538           <para>
1539             If you find one patch that is getting the cvs source tree to
1540             reproduce the problem, you have almost won; post the problem on
1541             <systemitem>comp.emulators.windows.wine</systemitem> and there
1542             is a chance that the author will jump in to suggest a fix; or
1543             there is always the possibility to look hard at the patch until
1544             it is coerced to reveal where is the bug :-)
1545           </para>
1546         </listitem>
1547       </orderedlist>
1548     </sect1>
1549   </chapter>
1550
1551 <!-- Keep this comment at the end of the file
1552 Local variables:
1553 mode: sgml
1554 sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
1555 End:
1556 -->