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