documentation/architecture.sgml

   1   <chapter id="architecture">
   2     <title>Overview</title>
   3     <para>Brief overview of Wine's architecture...</para>
   4
   5     <sect1 id="basic-overview">
   6       <title>Basic Overview</title>
   7
   8       <para>
   9         With the fundamental architecture of Wine stabilizing, and
  10         people starting to think that we might soon be ready to
  11         actually release this thing, it may be time to take a look at
  12         how Wine actually works and operates.
  13       </para>
  14
  15       <sect2>
  16         <title>Wine Overview</title>
  17         <para>
  18           Wine is often used as a recursive acronym, standing for
  19           "Wine Is Not an Emulator". Sometimes it is also known to be
  20           used for "Windows Emulator". In a way, both meanings are
  21           correct, only seen from different perspectives. The first
  22           meaning says that Wine is not a virtual machine, it does not
  23           emulate a CPU, and you are not supposed to install
  24           Windows nor any Windows device drivers on top of it; rather,
  25           Wine is an implementation of the Windows API, and can be
  26           used as a library to port Windows applications to Unix. The
  27           second meaning, obviously, is that to Windows binaries
  28           (<filename>.exe</filename> files), Wine does look like
  29           Windows, and emulates its behaviour and quirks rather
  30           closely.
  31         </para>
  32         <note>
  33           <title>Note</title>
  34           <para>
  35             The "Emulator" perspective should not be thought of as if
  36             Wine is a typical inefficient emulation layer that means
  37             Wine can't be anything but slow - the faithfulness to the
  38             badly designed Windows API may of course impose a minor
  39             overhead in some cases, but this is both balanced out by
  40             the higher efficiency of the Unix platforms Wine runs on,
  41             and that other possible abstraction libraries (like Motif,
  42             GTK+, CORBA, etc) has a runtime overhead typically
  43             comparable to Wine's.
  44           </para>
  45         </note>
  46       </sect2>
  47
  48       <sect2>
  49         <title>Win16 and Win32</title>
  50         <para>
  51           Win16 and Win32 applications have different requirements;
  52           for example, Win16 apps expect cooperative multitasking
  53           among themselves, and to exist in the same address space,
  54           while Win32 apps expect the complete opposite, i.e.
  55           preemptive multitasking, and separate address spaces.
  56         </para>
  57         <para>
  58           Wine now deals with this issue by launching a separate Wine
  59           process for each Win32 process, but not for Win16 tasks.
  60           Win16 tasks are now run as different intersynchronized
  61           threads in the same Wine process; this Wine process is
  62           commonly known as a <firstterm>WOW</firstterm> process,
  63           referring to a similar mechanism used by Windows NT.
  64           Synchronization between the Win16 tasks running in the WOW
  65           process is normally done through the Win16 mutex - whenever
  66           one of them is running, it holds the Win16 mutex, keeping
  67           the others from running. When the task wishes to let the
  68           other tasks run, the thread releases the Win16 mutex, and
  69           one of the waiting threads will then acquire it and let its
  70           task run.
  71         </para>
  72       </sect2>
  73
  74       <sect2>
  75         <title>The Wine server</title>
  76         <para>
  77           The Wine server is among the most confusing concepts in Wine.
  78           What is its function in Wine? Well, to be brief, it provides
  79           Inter-Process Communication (IPC), synchronization, and
  80           process/thread management. When the wineserver launches, it
  81           creates a Unix socket for the current host based on (see below)
  82           your home directory's <filename>.wine</filename> subdirectory (or
  83           wherever the <constant>WINEPREFIX</constant> environment
  84           variable points) - all Wine processes launched later
  85           connects to the wineserver using this socket. (If a
  86           wineserver was not already running, the first Wine process
  87           will start up the wineserver in auto-terminate mode (i.e.
  88           the wineserver will then terminate itself once the last Wine
  89           process has terminated).)
  90         </para>
  91         <para>
  92           In earlier versions of Wine the master socket mentioned
  93           above was actually created in the configuration directory;
  94           either your home directory's <filename>/wine</filename>
  95           subdirectory or wherever the <constant>WINEPREFIX</constant>
  96           environment variable points>.  Since that might not be possible
  97           the socket is actually created within the <filename>/tmp</filename>
  98           directory with a name that reflects the configuration directory.
  99           This means that there can actually be several separate copies of
 100           the wineserver running; one per combination of user and
 101           configuration directory.  Note that you should not have several
 102           users using the same configuration directory at the same time;
 103           they will have different copies of the wineserver running and
 104           this could well lead to problems with the registry information
 105           that they are sharing.
 106         </para>
 107         <para>
 108           Every thread in each Wine process has its own request
 109           buffer, which is shared with the wineserver. When a thread
 110           needs to synchronize or communicate with any other thread or
 111           process, it fills out its request buffer, then writes a
 112           command code through the socket. The wineserver handles the
 113           command as appropriate, while the client thread waits for a
 114           reply. In some cases, like with the various
 115           <function>WaitFor</function> synchronization primitives, the
 116           server handles it by marking the client thread as waiting
 117           and does not send it a reply before the wait condition has
 118           been satisfied.
 119         </para>
 120         <para>
 121           The wineserver itself is a single and separate process and
 122           does not have its own threading - instead, it is built on
 123           top of a large <function>poll()</function> loop that alerts
 124           the wineserver whenever anything happens, such as a client
 125           having sent a command, or a wait condition having been satisfied.
 126           There is thus no danger of race conditions inside the
 127           wineserver itself - it is often called upon to do operations
 128           that look completely atomic to its clients.
 129         </para>
 130         <para>
 131           Because the wineserver needs to manage processes, threads,
 132           shared handles, synchronization, and any related issues, all
 133           the clients' Win32 objects are also managed by the
 134           wineserver, and the clients must send requests to the
 135           wineserver whenever they need to know any Win32 object
 136           handle's associated Unix file descriptor (in which case the
 137           wineserver duplicates the file descriptor, transmits it to
 138           the client, and leaves it to the client to close the duplicate
 139           when the client has finished with it).
 140         </para>
 141       </sect2>
 142
 143       <sect2>
 144         <title>Relays, Thunks, and DLL descriptors</title>
 145         <para>
 146           Loading a Windows binary into memory isn't that hard by
 147           itself, the hard part is all those various DLLs and entry
 148           points it imports and expects to be there and function as
 149           expected; this is, obviously, what the entire Wine
 150           implementation is all about. Wine contains a range of DLL
 151           implementations. Each of the implemented (or
 152           half-implemented) DLLs (which can be found in the
 153           <filename>dlls/</filename> directory) need to make
 154           themselves known to the Wine core through a DLL descriptor.
 155           These descriptors point to such things as the DLL's
 156           resources and the entry point table.
 157         </para>
 158         <para>
 159           The DLL descriptor and entry point table is generated by the
 160           <command>winebuild</command> tool (previously just named
 161           <command>build</command>), taking DLL specification files
 162           with the extension <filename>.spec</filename> as input. The
 163           output file contains a global constructor that automatically
 164           registers the DLL's descriptor with the Wine core at
 165           runtime.
 166         </para>
 167         <para>
 168           Once an application module wants to import a DLL, Wine will
 169           look through its list of registered DLLs (if it's not
 170           registered, it will look for it on disk). (Failing that, it
 171           will look for a real Windows <filename>.DLL</filename> file
 172           to use, and look through its imports, etc.) To resolve the
 173           module's imports, Wine looks through the entry point table
 174           and finds if it's defined there. (If not, it'll emit the
 175           error "No handler for ...", which, if the application called
 176           the entry point, is a fatal error.)
 177         </para>
 178         <para>
 179           Since Wine is 32-bit code itself, and if the compiler
 180           supports Windows' calling convention, <type>stdcall</type>
 181           (<command>gcc</command> does), Wine can resolve imports into
 182           Win32 code by substituting the addresses of the Wine
 183           handlers directly without any thunking layer in between.
 184           This eliminates the overhead most people associate with
 185           "emulation", and is what the applications expect anyway.
 186         </para>
 187         <para>
 188           However, if the user specified <parameter>--debugmsg
 189             +relay</parameter>, a thunk layer is inserted between the
 190           application imports and the Wine handlers; this layer is
 191           known as "relay" because all it does is print out the
 192           arguments/return values (by using the argument lists in the
 193           DLL descriptor's entry point table), then pass the call on,
 194           but it's invaluable for debugging misbehaving calls into
 195           Wine code. A similar mechanism also exists between Windows
 196           DLLs - Wine can optionally insert thunk layers between them,
 197           by using <parameter>--debugmsg +snoop</parameter>, but since
 198           no DLL descriptor information exists for non-Wine DLLs, this
 199           is less reliable and may lead to crashes.
 200         </para>
 201         <para>
 202           For Win16 code, there is no way around thunking - Wine needs
 203           to relay between 16-bit and 32-bit code. These thunks switch
 204           between the app's 16-bit stack and Wine's 32-bit stack,
 205           copies and converts arguments as appropriate, and handles
 206           the Win16 mutex. Suffice to say that the kind of intricate
 207           stack content juggling this results in, is not exactly
 208           suitable study material for beginners.
 209         </para>
 210       </sect2>
 211
 212       <sect2>
 213         <title>Core and non-core DLLs</title>
 214
 215 <!-- FIXME: Should do this without the .jpg (AJ)
 216         <para>
 217           This slide (by Marcus Meissner of Caldera Systems, shown at
 218           the Comdex 99) shows how Wine is meant to fit into the
 219           Windows DLL model.
 220           <mediaobject>
 221             <imageobject>
 222               <imagedata fileref="arch-layout.jpg" format="jpg">
 223             </imageobject>
 224           </mediaobject>
 225         </para>
 226 FIXME -->
 227
 228         <para>
 229           Wine must at least completely replace the "Big Three" DLLs
 230           (KERNEL/KERNEL32, GDI/GDI32, and USER/USER32), which all
 231           other DLLs are layered on top of. But since Wine is (for
 232           various reasons) leaning towards the NT way of implementing
 233           things, the NTDLL is another core DLL to be implemented in
 234           Wine, and many KERNEL32 and ADVAPI32 features will be
 235           implemented through the NTDLL. The wineserver and the
 236           service thread provide the backbone for the implementation
 237           of these core DLLs, and integration with the X11 driver
 238           (which provides GDI/GDI32 and USER/USER32 functionality
 239           along with the Windows standard controls). All non-core
 240           DLLs, on the other hand, are expected to only use routines
 241           exported by other DLLs (and none of these backbone services
 242           directly), to keep the code base as tidy as possible. An
 243           example of this is COMCTL32 (Common Controls), which should
 244           only use standard GDI32- and USER32-exported routines.
 245         </para>
 246       </sect2>
 247     </sect1>
 248
 249     <sect1 id="module-overview">
 250       <title>Module Overview</title>
 251
 252       <sect2>
 253         <title>KERNEL Module</title>
 254
 255         <para>Needs some content...</para>
 256       </sect2>
 257
 258       <sect2>
 259         <title>GDI Module</title>
 260
 261         <sect3>
 262           <title>X Windows System interface</title>
 263
 264           <para>
 265             The X libraries used to implement X clients (such as Wine)
 266             do not work properly if multiple threads access the same
 267             display concurrently. It is possible to compile the X
 268             libraries to perform their own synchronization (initiated
 269             by calling <function>XInitThreads()</function>). However,
 270             Wine does not use this approach. Instead Wine performs its
 271             own synchronization using the
 272             <function>wine_tsx11_lock()</function> / <function>wine_tsx11_unlock()</function>
 273             functions.  This locking protects library access
 274             with a critical section, and also arranges things so that
 275             X libraries compiled without <option>-D_REENTRANT</option>
 276             (eg. with global <varname>errno</varname> variable) will
 277             work with Wine.
 278           </para>
 279           <para>
 280             In the past, all calls to X used to go through a wrapper called
 281              <function>TSX...()</function> (for "Thread Safe X ...").
 282             While it is still being used in the code, it's inefficient
 283             as the lock is potentially aquired and released unnecessarily.
 284             New code should explicitly aquire the lock.
 285           </para>
 286         </sect3>
 287       </sect2>
 288
 289       <sect2>
 290         <title>USER Module</title>
 291
 292         <para>
 293           USER implements windowing and messaging subsystems. It also
 294           contains code for common controls and for other
 295           miscellaneous  stuff (rectangles, clipboard, WNet, etc).
 296           Wine USER code is  located in <filename>windows/</filename>,
 297           <filename>controls/</filename>, and
 298           <filename>misc/</filename> directories.
 299         </para>
 300
 301         <sect3>
 302           <title>Windowing subsystem</title>
 303
 304           <para><filename>windows/win.c</filename></para>
 305           <para><filename>windows/winpos.c</filename></para>
 306           <para>
 307             Windows are arranged into parent/child hierarchy with one
 308             common ancestor for all windows (desktop window). Each
 309             window structure contains a pointer to the immediate
 310             ancestor (parent window if <constant>WS_CHILD</constant>
 311             style bit is set), a pointer to the sibling (returned by
 312             <function>GetWindow(..., GW_NEXT)</function>), a pointer
 313             to the owner  window (set only for popup window if it was
 314             created with valid  <varname>hwndParent</varname>
 315             parameter), and a pointer to the first child window
 316             (<function>GetWindow(.., GW_CHILD)</function>). All popup
 317             and non-child windows are therefore placed in the first
 318             level of this hierarchy and their ancestor link
 319             (<varname>wnd-&gt;parent</varname>) points to the desktop
 320             window.
 321           </para>
 322           <screen>
 323    Desktop window                       - root window
 324     |     \      `-.
 325     |      \        `-.
 326    popup -&gt; wnd1  -&gt;  wnd2                - top level windows
 327     |       \   `-.      `-.
 328     |        \     `-.      `-.
 329    child1  child2 -&gt; child3  child4     - child windows
 330           </screen>
 331           <para>
 332             Horizontal arrows denote sibling relationship, vertical
 333             lines - ancestor/child. To summarize, all windows with the
 334             same immediate ancestor are sibling windows, all windows
 335             which do not have desktop as their immediate ancestor are
 336             child windows. Popup windows behave as topmost top-level
 337             windows unless they are owned. In this case the only
 338             requirement is that they must precede their owners in the
 339             top-level sibling list (they are not topmost). Child
 340             windows are confined to the client area of their parent
 341             windows (client area is where window gets to do its own
 342             drawing, non-client area consists of caption, menu,
 343             borders, intrinsic scrollbars, and
 344             minimize/maximize/close/help buttons).
 345           </para>
 346           <para>
 347             Another fairly important concept is
 348             <firstterm>z-order</firstterm>. It is derived from the
 349             ancestor/child hierarchy and is used to determine
 350             "above/below" relationship. For instance, in the example
 351             above, z-order is
 352           </para>
 353           <screen>
 354 child1-&gt;popup-&gt;child2-&gt;child3-&gt;wnd1-&gt;child4-&gt;wnd2-&gt;desktop.
 355           </screen>
 356           <para>
 357             Current  active window ("foreground window" in Win32) is
 358             moved to the front of z-order unless its top-level
 359             ancestor owns popup windows.
 360           </para>
 361           <para>
 362             All these issues are dealt with (or supposed to be) in
 363             <filename>windows/winpos.c</filename> with
 364             <function>SetWindowPos()</function> being the primary
 365             interface to the window manager.
 366           </para>
 367           <para>
 368             Wine specifics: in default and managed mode each top-level
 369             window gets its own X counterpart with desktop window
 370             being basically a fake stub. In desktop mode, however,
 371             only desktop window has an X window associated with it.
 372             Also, <function>SetWindowPos()</function> should
 373             eventually be implemented via
 374             <function>Begin/End/DeferWindowPos()</function> calls and
 375             not the other way around.
 376           </para>
 377
 378           <sect4>
 379             <title>Visible region, clipping region and update region</title>
 380
 381             <para><filename>windows/dce.c</filename></para>
 382             <para><filename>windows/winpos.c</filename></para>
 383             <para><filename>windows/painting.c</filename></para>
 384
 385             <screen>
 386     ________________________
 387    |_________               |  A and B are child windows of C
 388    |    A    |______        |
 389    |         |      |       |
 390    |---------'      |       |
 391    |   |      B     |       |
 392    |   |            |       |
 393    |   `------------'       |
 394    |                   C    |
 395    `------------------------'
 396             </screen>
 397             <para>
 398               Visible region determines which part of the window is
 399               not obscured by other windows. If a window has the
 400               <constant>WS_CLIPCHILDREN</constant> style then all
 401               areas below its children are considered invisible.
 402               Similarly, if the <constant>WS_CLIPSIBLINGS</constant>
 403               bit is in effect then all areas obscured by its siblings
 404               are invisible. Child windows are always clipped by the
 405               boundaries of their parent windows.
 406             </para>
 407             <para>
 408               B has a <constant>WS_CLIPSIBLINGS</constant> style:
 409             </para>
 410             <screen>
 411    .          ______
 412    :         |      |
 413    |   ,-----'      |
 414    |   |      B     | - visible region of B
 415    |   |            |
 416    :   `------------'
 417             </screen>
 418             <para>
 419               When the program requests a <firstterm>display
 420                 context</firstterm> (DC) for a window it  can specify
 421               an optional clipping region that further restricts the
 422               area where the graphics output can appear. This area is
 423               calculated as an intersection of the visible region and
 424               a clipping region.
 425             </para>
 426             <para>
 427               Program asked for a DC with a clipping region:
 428             </para>
 429             <screen>
 430           ______
 431       ,--|--.   |     .    ,--.
 432    ,--+--'  |   |     :   _:  |
 433    |  |   B |   |  =&gt; |  |    | - DC region where the painting will
 434    |  |     |   |     |  |    |   be visible
 435    `--|-----|---'     :  `----'
 436       `-----'
 437             </screen>
 438             <para>
 439               When the window manager detects that some part of the window
 440               became visible it adds this area to the update region of this
 441               window and then generates <constant>WM_ERASEBKGND</constant> and
 442               <constant>WM_PAINT</constant> messages.  In addition,
 443               <constant>WM_NCPAINT</constant> message is sent when the
 444               uncovered area  intersects a nonclient part of the window.
 445               Application must reply to the <constant>WM_PAINT</constant>
 446               message by calling the
 447               <function>BeginPaint()</function>/<function>EndPaint()</function>
 448               pair of functions. <function>BeginPaint()</function> returns a DC
 449               that uses accumulated update region as a clipping region. This
 450               operation cleans up invalidated area and the window will not
 451               receive another <constant>WM_PAINT</constant> until the window
 452               manager creates a new update region.
 453             </para>
 454             <para>
 455               A was moved to the left:
 456             </para>
 457             <screen>
 458     ________________________       ...          / C update region
 459    |______                  |     :      .___ /
 460    | A    |_________        |  =&gt; |   ...|___|..
 461    |      |         |       |     |   :  |   |
 462    |------'         |       |     |   :  '---'
 463    |   |      B     |       |     |   :      \
 464    |   |            |       |     :            \
 465    |   `------------'       |                    B update region
 466    |                   C    |
 467    `------------------------'
 468             </screen>
 469             <para>
 470               Windows maintains a display context cache consisting of
 471               entries that include the DC itself, the window to which
 472               it belongs, and an optional clipping region (visible
 473               region is stored in the DC itself). When an API call
 474               changes the state of the window tree, window manager has
 475               to go through the DC cache to recalculate visible
 476               regions for entries whose windows were involved in the
 477               operation. DC entries (DCE) can be either private to the
 478               window, or private to the window class, or shared
 479               between all windows (Windows 3.1 limits the number of
 480               shared DCEs to 5).
 481             </para>
 482           </sect4>
 483         </sect3>
 484
 485         <sect3>
 486           <title>Messaging subsystem</title>
 487
 488           <para><filename>windows/queue.c</filename></para>
 489           <para><filename>windows/message.c</filename></para>
 490
 491           <para>
 492             Each Windows task/thread has its own message queue - this
 493             is where it gets messages from. Messages can be:
 494             <orderedlist>
 495               <listitem>
 496                 <para>
 497                   generated on the fly (<constant>WM_PAINT</constant>,
 498                   <constant>WM_NCPAINT</constant>,
 499                   <constant>WM_TIMER</constant>)
 500                 </para>
 501               </listitem>
 502               <listitem>
 503                 <para>
 504                   created by the system (hardware messages)
 505                 </para>
 506               </listitem>
 507               <listitem>
 508                 <para>
 509                   posted by other tasks/threads (<function>PostMessage</function>)
 510                 </para>
 511               </listitem>
 512               <listitem>
 513                 <para>
 514                   sent by other tasks/threads (<function>SendMessage</function>)
 515                 </para>
 516               </listitem>
 517             </orderedlist>
 518           </para>
 519           <para>
 520             Message priority:
 521           </para>
 522           <para>
 523             First the system looks for sent messages, then for posted
 524             messages, then for hardware messages, then it checks if
 525             the queue has the "dirty window" bit set, and, finally, it
 526             checks for expired timers. See
 527             <filename>windows/message.c</filename>.
 528           </para>
 529           <para>
 530             From all these different types of messages, only posted
 531             messages go directly into the private message queue.
 532             System messages (even in Win95) are first collected in the
 533             system message queue and then they either sit there until
 534             <function>Get/PeekMessage</function> gets to process them
 535             or, as in Win95, if system queue is getting clobbered, a
 536             special thread ("raw input thread") assigns them to the
 537             private queues. Sent messages are queued separately and
 538             the sender sleeps until it gets a reply. Special messages
 539             are generated on the fly depending on the window/queue
 540             state. If the window update region is not empty, the
 541             system sets the <constant>QS_PAINT</constant> bit in the
 542             owning queue and eventually this window receives a
 543             <constant>WM_PAINT</constant> message
 544             (<constant>WM_NCPAINT</constant> too if the update region
 545             intersects with the non-client area). A timer event is
 546             raised when one of the queue timers expire. Depending on
 547             the timer parameters <function>DispatchMessage</function>
 548             either calls the callback function or the window
 549             procedure. If there are no messages pending the
 550             task/thread sleeps until messages appear.
 551           </para>
 552           <para>
 553             There are several tricky moments (open for discussion) -
 554           </para>
 555
 556           <itemizedlist>
 557             <listitem>
 558               <para>
 559                 System message order has to be honored and messages
 560                 should be processed within correct task/thread
 561                 context. Therefore when <function>Get/PeekMessage</function> encounters
 562                 unassigned system message and this message appears not
 563                 to be for the current task/thread it should either
 564                 skip it (or get rid of it by moving it into the
 565                 private message queue of the target task/thread -
 566                 Win95, AFAIK) and look further or roll back and then
 567                 yield until this message gets processed when system
 568                 switches to the correct context (Win16). In the first
 569                 case we lose correct message ordering, in the second
 570                 case we have the infamous synchronous system message
 571                 queue. Here is a post to one of the OS/2 newsgroup I
 572                 found to be relevant:
 573               </para>
 574               <blockquote>
 575                 <attribution>by David Charlap</attribution>
 576                 <para>
 577                   " Here's the problem in a nutshell, and there is no
 578                   good solution. Every possible solution creates a
 579                   different problem.
 580                 </para>
 581                 <para>
 582                   With a windowing system, events can go to many
 583                   different windows. Most are sent by applications or
 584                   by the OS when things relating to that window happen
 585                   (like repainting, timers, etc.)
 586                 </para>
 587                 <para>
 588                   Mouse input events go to the window you click on
 589                   (unless some window captures the mouse).
 590                 </para>
 591                 <para>
 592                   So far, no problem.  Whenever an event happens, you
 593                   put a message on the target window's message queue.
 594                   Every process has a message queue.  If the process
 595                   queue fills up, the messages back up onto the system
 596                   queue.
 597                 </para>
 598                 <para>
 599                   This is the first cause of apps hanging the GUI.  If
 600                   an app doesn't handle messages and they back up into
 601                   the system queue, other apps can't get any more
 602                   messages.  The reason is that the next message in
 603                   line can't go anywhere, and the system won't skip
 604                   over it.
 605                 </para>
 606                 <para>
 607                   This can be fixed by making apps have bigger private
 608                   message queues. The SIQ fix does this.  PMQSIZE does
 609                   this for systems without the SIQ fix.  Applications
 610                   can also request large queues on their own.
 611                 </para>
 612                 <para>
 613                   Another source of the problem, however, happens when
 614                   you include keyboard events.  When you press a key,
 615                   there's no easy way to know what window the
 616                   keystroke message should be delivered to.
 617                 </para>
 618                 <para>
 619                   Most windowing systems use a concept known as
 620                   "focus".  The window with focus gets all incoming
 621                   keyboard messages.  Focus can be changed from window
 622                   to window by apps or by users clicking on windows.
 623                 </para>
 624                 <para>
 625                   This is the second source of the problem.  Suppose
 626                   window A has focus. You click on window B and start
 627                   typing before the window gets focus. Where should
 628                   the keystrokes go?  On the one hand, they should go
 629                   to A until the focus actually changes to B.  On the
 630                   other hand, you probably want the keystrokes to go
 631                   to B, since you clicked there first.
 632                 </para>
 633                 <para>
 634                   OS/2's solution is that when a focus-changing event
 635                   happens (like clicking on a window), OS/2 holds all
 636                   messages in the system queue until the focus change
 637                   actually happens.  This way, subsequent keystrokes
 638                   go to the window you clicked on, even if it takes a
 639                   while for that window to get focus.
 640                 </para>
 641                 <para>
 642                   The downside is that if the window takes a real long
 643                   time to get focus (maybe it's not handling events,
 644                   or maybe the window losing focus isn't handling
 645                   events), everything backs up in the system queue and
 646                   the system appears hung.
 647                 </para>
 648                 <para>
 649                   There are a few solutions to this problem.
 650                 </para>
 651                 <para>
 652                   One is to make focus policy asynchronous.  That is,
 653                   focus changing has absolutely nothing to do with the
 654                   keyboard.  If you click on a window and start typing
 655                   before the focus actually changes, the keystrokes go
 656                   to the first window until focus changes, then they
 657                   go to the second. This is what X-windows does.
 658                 </para>
 659                 <para>
 660                   Another is what NT does.  When focus changes,
 661                   keyboard events are held in the system message
 662                   queue, but other events are allowed through. This is
 663                   "asynchronous" because the messages in the system
 664                   queue are delivered to the application queues in a
 665                   different order from that with which they were
 666                   posted.  If a bad app won't handle the "lose focus"
 667                   message, it's of no consequence - the app receiving
 668                   focus will get its "gain focus" message, and the
 669                   keystrokes will go to it.
 670                 </para>
 671                 <para>
 672                   The NT solution also takes care of the application
 673                   queue filling up problem.  Since the system delivers
 674                   messages asynchronously, messages waiting in the
 675                   system queue will just sit there and the rest of the
 676                   messages will be delivered to their apps.
 677                 </para>
 678                 <para>
 679                   The OS/2 SIQ solution is this:  When a
 680                   focus-changing event happens, in addition to
 681                   blocking further messages from the application
 682                   queues, a timer is started.  When the timer goes
 683                   off, if the focus change has not yet happened, the
 684                   bad app has its focus taken away and all messages
 685                   targeted at that window are skipped.  When the bad
 686                   app finally handles the focus change message, OS/2
 687                   will detect this and stop skipping its messages.
 688                 </para>
 689
 690                 <para>
 691                   As for the pros and cons:
 692                 </para>
 693                 <para>
 694                   The X-windows solution is probably the easiest.  The
 695                   problem is that users generally don't like having to
 696                   wait for the focus to change before they start
 697                   typing.  On many occasions, you can type and the
 698                   characters end up in the wrong window because
 699                   something (usually heavy system load) is preventing
 700                   the focus change from happening in a timely manner.
 701                 </para>
 702                 <para>
 703                   The NT solution seems pretty nice, but making the
 704                   system message queue asynchronous can cause similar
 705                   problems to the X-windows problem. Since messages
 706                   can be delivered out of order, programs must not
 707                   assume that two messages posted in a particular
 708                   order will be delivered in that same order.  This
 709                   can break legacy apps, but since Win32 always had an
 710                   asynchronous queue, it is fair to simply tell app
 711                   designers "don't do that".  It's harder to tell app
 712                   designers something like that on OS/2 - they'll
 713                   complain "you changed the rules and our apps are
 714                   breaking."
 715                 </para>
 716                 <para>
 717                   The OS/2 solution's problem is that nothing happens
 718                   until you try to change window focus, and then wait
 719                   for the timeout.  Until then, the bad app is not
 720                   detected and nothing is done."
 721                 </para>
 722               </blockquote>
 723             </listitem>
 724
 725             <listitem>
 726               <para>
 727                 Intertask/interthread
 728                 <function>SendMessage</function>. The system has to
 729                 inform the target queue about the forthcoming message,
 730                 then it has to carry out the context switch and wait
 731                 until the result is available.  Win16 stores necessary
 732                 parameters in the queue structure and then calls
 733                 <function>DirectedYield()</function> function.
 734                 However, in Win32 there could be  several messages
 735                 pending sent by preemptively executing threads, and in
 736                 this case <function>SendMessage</function> has to
 737                 build some sort of message queue for sent messages.
 738                 Another issue is what to do with messages sent to the
 739                 sender when it is blocked inside its own
 740                 <function>SendMessage</function>.
 741               </para>
 742             </listitem>
 743           </itemizedlist>
 744         </sect3>
 745       </sect2>
 746     </sect1>
 747
 748     <sect1 id="arch-dlls">
 749       <title>Wine/Windows DLLs</title>
 750
 751       <para>
 752         This document mainly deals with the status of current DLL
 753         support by Wine.  The Wine ini file currently supports
 754         settings to change the load order of DLLs.  The load order
 755         depends on several issues, which results in different settings
 756         for various DLLs.
 757       </para>
 758
 759       <sect2>
 760         <title>Pros of Native DLLs</title>
 761
 762         <para>
 763           Native DLLs of course guarantee 100% compatibility for
 764           routines they implement. For example, using the native USER
 765           DLL would maintain a virtually perfect and Windows 95-like
 766           look for window borders, dialog controls, and so on. Using
 767           the built-in Wine version of this library, on the other
 768           hand, would produce a display that does not precisely mimic
 769           that of Windows 95.  Such subtle differences can be
 770           engendered in other important DLLs, such as the common
 771           controls library COMMCTRL or the common dialogs library
 772           COMMDLG, when built-in Wine DLLs outrank other types in load
 773           order.
 774         </para>
 775         <para>
 776           More significant, less aesthetically-oriented problems can
 777           result if the built-in Wine version of the SHELL DLL is
 778           loaded before the native version of this library. SHELL
 779           contains routines such as those used by installer utilities
 780           to create desktop shortcuts. Some installers might fail when
 781           using Wine's built-in SHELL.
 782         </para>
 783       </sect2>
 784
 785       <sect2>
 786         <title>Cons of Native DLLs</title>
 787
 788         <para>
 789           Not every application performs better under native DLLs. If
 790           a library tries to access features of the rest of the system
 791           that are not fully implemented in Wine, the native DLL might
 792           work much worse than the corresponding built-in one, if at
 793           all. For example, the native Windows GDI library must be
 794           paired with a Windows display driver, which of course is not
 795           present under Intel Unix and Wine.
 796         </para>
 797         <para>
 798           Finally, occasionally built-in Wine DLLs implement more
 799           features than the corresponding native Windows DLLs.
 800           Probably the most important example of such behavior is the
 801           integration of Wine with X provided by Wine's built-in USER
 802           DLL. Should the native Windows USER library take load-order
 803           precedence, such features as the ability to use the
 804           clipboard or drag-and-drop between Wine windows and X
 805           windows will be lost.
 806         </para>
 807       </sect2>
 808
 809       <sect2>
 810         <title>Deciding Between Native and Built-In DLLs</title>
 811
 812         <para>
 813           Clearly, there is no one rule-of-thumb regarding which
 814           load-order to use. So, you must become familiar with
 815           what specific DLLs do and which other DLLs or features
 816           a given library interacts with, and use this information
 817           to make a case-by-case decision.
 818         </para>
 819
 820       </sect2>
 821
 822       <sect2>
 823         <title>Load Order for DLLs</title>
 824
 825         <para>
 826           Using the DLL sections from the wine configuration file, the
 827           load order can be tweaked to a high degree. In general it is
 828           advised not to change the settings of the configuration
 829           file. The default configuration specifies the right load
 830           order for the most important DLLs.
 831         </para>
 832         <para>
 833           The default load order follows this algorithm: for all DLLs
 834           which have a fully-functional Wine implementation, or where
 835           the native DLL is known not to work, the built-in library
 836           will be loaded first. In all other cases, the native DLL
 837           takes load-order precedence.
 838         </para>
 839         <para>
 840           The <varname>DefaultLoadOrder</varname> from the
 841           [DllDefaults] section specifies for all DLLs which version
 842           to try first. See manpage for explanation of the arguments.
 843         </para>
 844         <para>
 845           The [DllOverrides] section deals with DLLs, which need a
 846           different-from-default treatment.
 847         </para>
 848         <para>
 849           The [DllPairs] section is for DLLs, which must be loaded in
 850           pairs. In general, these are DLLs for either 16-bit or
 851           32-bit applications. In most cases in Windows, the 32-bit
 852           version cannot be used without its 16-bit counterpart. For
 853           Wine, it is customary that the 16-bit implementations rely
 854           on the 32-bit implementations and cast the results back to
 855           16-bit arguments. Changing anything in this section is bound
 856           to result in errors.
 857         </para>
 858         <para>
 859           For the future, the Wine implementation of Windows DLL seems
 860           to head towards unifying the 16 and 32 bit DLLs wherever
 861           possible, resulting in larger DLLs.  They are stored in the
 862           <filename>dlls/</filename> subdirectory using the 32-bit
 863           name.
 864         </para>
 865       </sect2>
 866
 867       <sect2>
 868         <title>Understanding What DLLs Do</title>
 869
 870         <para>
 871           The following list briefly describes each of the DLLs
 872           commonly found in Windows whose load order may be modified
 873           during the configuration and compilation of Wine.
 874         </para>
 875         <para>
 876           (See also <filename>./DEVELOPER-HINTS</filename> or the
 877           <filename>dlls/</filename> subdirectory to see which DLLs
 878           are currently being rewritten for Wine)
 879         </para>
 880
 881 <!-- FIXME: Should convert this table into a VariableList element -->
 882         <screen>
 883 ADVAPI32.DLL:      32-bit application advanced programming interfaces
 884                    like crypto, systeminfo, security and event logging
 885 AVIFILE.DLL:       32-bit application programming interfaces for the
 886                    Audio Video Interleave (AVI) Windows-specific
 887                    Microsoft audio-video standard
 888 COMMCTRL.DLL:      16-bit common controls
 889 COMCTL32.DLL:      32-bit common controls
 890 COMDLG32.DLL:      32-bit common dialogs
 891 COMMDLG.DLL:       16-bit common dialogs
 892 COMPOBJ.DLL:       OLE 16- and 32-bit compatibility libraries
 893 CRTDLL.DLL:        Microsoft C runtime
 894 DCIMAN.DLL:        16-bit
 895 DCIMAN32.DLL:      32-bit display controls
 896 DDEML.DLL:         DDE messaging
 897 D3D*.DLL           DirectX/Direct3D drawing libraries
 898 DDRAW.DLL:         DirectX drawing libraries
 899 DINPUT.DLL:        DirectX input libraries
 900 DISPLAY.DLL:       Display libraries
 901 DPLAY.DLL, DPLAYX.DLL:  DirectX playback libraries
 902 DSOUND.DLL:        DirectX audio libraries
 903 GDI.DLL:           16-bit graphics driver interface
 904 GDI32.DLL:         32-bit graphics driver interface
 905 IMAGEHLP.DLL:      32-bit IMM API helper libraries (for PE-executables)
 906 IMM32.DLL:         32-bit IMM API
 907 IMGUTIL.DLL:
 908 KERNEL32.DLL       32-bit kernel DLL
 909 KEYBOARD.DLL:      Keyboard drivers
 910 LZ32.DLL:          32-bit Lempel-Ziv or LZ file compression
 911                    used by the installshield installers (???).
 912 LZEXPAND.DLL:      LZ file expansion; needed for Windows Setup
 913 MMSYSTEM.DLL:      Core of the Windows multimedia system
 914 MOUSE.DLL:         Mouse drivers
 915 MPR.DLL:           32-bit Windows network interface
 916 MSACM.DLL:         Core of the Addressed Call Mode or ACM system
 917 MSACM32.DLL:       Core of the 32-bit ACM system
 918                    Audio Compression Manager ???
 919 MSNET32.DLL        32-bit network APIs
 920 MSVFW32.DLL:       32-bit Windows video system
 921 MSVIDEO.DLL:       16-bit Windows video system
 922 OLE2.DLL:          OLE 2.0 libraries
 923 OLE32.DLL:         32-bit OLE 2.0 components
 924 OLE2CONV.DLL:      Import filter for graphics files
 925 OLE2DISP.DLL, OLE2NLS.DLL: OLE 2.1 16- and 32-bit interoperability
 926 OLE2PROX.DLL:      Proxy server for OLE 2.0
 927 OLE2THK.DLL:       Thunking for OLE 2.0
 928 OLEAUT32.DLL       32-bit OLE 2.0 automation
 929 OLECLI.DLL:        16-bit OLE client
 930 OLECLI32.DLL:      32-bit OLE client
 931 OLEDLG.DLL:        OLE 2.0 user interface support
 932 OLESVR.DLL:        16-bit OLE server libraries
 933 OLESVR32.DLL:      32-bit OLE server libraries
 934 PSAPI.DLL:         Proces Status API libraries
 935 RASAPI16.DLL:      16-bit Remote Access Services libraries
 936 RASAPI32.DLL:      32-bit Remote Access Services libraries
 937 SHELL.DLL:         16-bit Windows shell used by Setup
 938 SHELL32.DLL:       32-bit Windows shell (COM object?)
 939 TAPI/TAPI32/TAPIADDR:  Telephone API (for Modems)
 940 W32SKRNL:          Win32s Kernel ? (not in use for Win95 and up!)
 941 WIN32S16.DLL:      Application compatibility for Win32s
 942 WIN87EM.DLL:       80387 math-emulation libraries
 943 WINASPI.DLL:       Advanced SCSI Peripheral Interface or ASPI libraries
 944 WINDEBUG.DLL       Windows debugger
 945 WINMM.DLL:         Libraries for multimedia thunking
 946 WING.DLL:          Libraries required to "draw" graphics
 947 WINSOCK.DLL:       Sockets APIs
 948 WINSPOOL.DLL:      Print spooler libraries
 949 WNASPI32.DLL:      32-bit ASPI libraries
 950 WSOCK32.DLL:       32-bit sockets APIs
 951         </screen>
 952       </sect2>
 953     </sect1>
 954   </chapter>
 955
 956 <!-- Keep this comment at the end of the file
 957 Local variables:
 958 mode: sgml
 959 sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")
 960 End:
 961 -->