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