Eliminate HeapAlloc casts.
[wine] / 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>Wine 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>Foreword</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>"Emulator"</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>Executables</title>
50         <para>
51           Wine's main task is to run Windows executables under non
52           Windows operating systems. It supports different types of
53           executables:
54           <itemizedlist>
55             <listitem>
56               <para>
57                 DOS executable. Those are even older programs, using
58                 the DOS format (either <filename>.com</filename> or
59                 <filename>.exe</filename> (the later being also called
60                 MZ)).
61               </para>
62             </listitem>
63             <listitem>
64               <para>
65                 Windows NE executable, also called 16 bit. They were
66                 the native processes run by Windows 2.x and 3.x. NE
67                 stands for New Executable &lt;g&gt;.
68               </para>
69             </listitem>
70             <listitem>
71               <para>
72                 Windows PE executable. These are programs were
73                 introduced in Windows 95 (and became the native
74                 formats for all later Windows version), even if 16 bit
75                 applications were still supported. PE stands for
76                 Portable Executable, in a sense where the format of
77                 the executable (as a file) is independent of the CPU
78                 (even if the content of the file - the code - is CPU
79                 dependent). 
80               </para>
81             </listitem>
82             <listitem>
83               <para>
84                 WineLib executable. These are applications, written
85                 using the Windows API, but compiled as a Unix
86                 executable. Wine provides the tools to create such
87                 executables.
88               </para>
89             </listitem>
90           </itemizedlist>
91         </para>
92         <para>
93           Let's quickly review the main differences for the supported
94           executables:
95           <table>
96             <title>Wine executables</title>
97             <tgroup cols="5" align="left" colsep="1" rowsep="1">
98               <thead>
99                 <row>
100                   <entry></entry>
101                   <entry>DOS (.COM or .EXE)</entry>
102                   <entry>Win16 (NE)</entry>
103                   <entry>Win32 (PE)</entry>
104                   <entry>WineLib</entry>
105                 </row>
106               </thead>
107               <tbody>
108                 <row>
109                   <entry>Multitasking</entry>
110                   <entry>Only one application at a time (except for TSR)</entry>
111                   <entry>Cooperative</entry>
112                   <entry>Preemptive</entry>
113                   <entry>Preemptive</entry>
114                 </row>
115                 <row>
116                   <entry>Address space</entry>
117                   <entry>
118                     One MB of memory, where each application is loaded
119                     and unloaded.
120                   </entry>
121                   <entry>
122                     All 16 bit applications share a single address
123                     space, protected mode.
124                   </entry>
125                   <entry>
126                     Each application has it's own address
127                     space. Requires MMU support from CPU. 
128                   </entry>
129                   <entry>
130                     Each application has it's own address
131                     space. Requires MMU support from CPU. 
132                   </entry>
133                 </row>
134                 <row>
135                   <entry>Windows API</entry>
136                   <entry>
137                     No Windows API but the DOS API (like <function>Int
138                       21h</function> traps).
139                   </entry>
140                   <entry>
141                     Will call the 16 bit Windows API.
142                   </entry>
143                   <entry>
144                     Will call the 32 bit Windows API.
145                   </entry>
146                   <entry>
147                     Will call the 32 bit Windows API, and possibly
148                     also the Unix APIs.
149                   </entry>
150                 </row>
151                 <row>
152                   <entry>Code (CPU level)</entry>
153                   <entry>
154                     Only available on x86 in real mode. Code and data
155                     are in segmented forms, with 16 bit
156                     offsets. Processor is in real mode.
157                   </entry>
158                   <entry>
159                     Only available on IA-32 architectures, code and
160                     data are in segmented forms, with 16 bit offsets
161                     (hence the 16 bit name). Processor is in protected
162                     mode.
163                   </entry>
164                   <entry>
165                     Available (with NT) on several CPUs, including
166                     IA-32. On this CPU, uses a flat memory model with
167                     32 bit offsets (hence the 32 bit name).
168                   </entry>
169                   <entry>
170                     Flat model, with 32 bit addresses.
171                   </entry>
172                 </row>
173                 <row>
174                   <entry>Multi-threading</entry>
175                   <entry>Not available.</entry>
176                   <entry>Not available.</entry>
177                   <entry>
178                     Available.
179                   </entry>
180                   <entry>
181                     Available, but must use the Win32 APIs for
182                     threading and synchronization, not the Unix ones.
183                   </entry>
184                 </row>
185               </tbody>
186             </tgroup>
187           </table>
188         </para>
189
190         <para>
191           Wine deals with this issue by launching a separate Wine
192           process (which is in fact a Unix process) for each Win32
193           process, but not for Win16 tasks. Win16 tasks (as well as
194           DOS programs) are run as different intersynchronized
195           Unix-threads in the same dedicated Wine process; this Wine
196           process is commonly known as a <firstterm>WOW</firstterm>
197           process (Windows on Windows), referring to a similar
198           mechanism used by Windows NT.
199         </para>
200         <para>
201           Synchronization between the Win16 tasks running in the WOW
202           process is normally done through the Win16 mutex - whenever
203           one of them is running, it holds the Win16 mutex, keeping
204           the others from running. When the task wishes to let the
205           other tasks run, the thread releases the Win16 mutex, and
206           one of the waiting threads will then acquire it and let its
207           task run.
208         </para>
209       </sect2>
210     </sect1>
211
212     <sect1>
213       <title>Standard Windows Architectures</title>
214
215       <sect2>
216         <title>Windows 9x architecture</title>
217
218         <para>
219           The windows architecture (Win 9x way) looks like this:
220           <screen>
221 +---------------------+        \
222 |     Windows EXE     |         } application
223 +---------------------+        /
224
225 +---------+ +---------+        \
226 | Windows | | Windows |         \ application & system DLLs
227 |   DLL   | |   DLL   |         /
228 +---------+ +---------+        /
229
230 +---------+ +---------+      \
231 |  GDI32  | | USER32  |       \
232 |   DLL   | |   DLL   |        \
233 +---------+ +---------+         } core system DLLs
234 +---------------------+        /
235 |     Kernel32 DLL    |       /
236 +---------------------+      / 
237
238 +---------------------+        \
239 |     Win9x kernel    |         } kernel space
240 +---------------------+        /
241
242 +---------------------+       \
243 |  Windows low-level  |        \ drivers (kernel space)
244 |       drivers       |        /
245 +---------------------+       /
246           </screen>
247         </para>
248       </sect2>
249       <sect2>
250         <title>Windows NT architecture</title>
251
252         <para>
253           The windows architecture (Windows NT way) looks like the
254           following drawing. Note the new DLL (NTDLL) which allows
255           implementing different subsystems (as win32); kernel32 in NT
256           architecture implements the Win32 subsystem on top of NTDLL.
257           <screen>
258 +---------------------+                      \
259 |     Windows EXE     |                       } application
260 +---------------------+                      /
261
262 +---------+ +---------+                      \
263 | Windows | | Windows |                       \ application & system DLLs
264 |   DLL   | |   DLL   |                       /
265 +---------+ +---------+                      /
266
267 +---------+ +---------+     +-----------+   \
268 |  GDI32  | |  USER32 |     |           |    \
269 |   DLL   | |   DLL   |     |           |     \
270 +---------+ +---------+     |           |      \ core system DLLs
271 +---------------------+     |           |      / (on the left side)
272 |    Kernel32 DLL     |     | Subsystem |     /
273 |  (Win32 subsystem)  |     |Posix, OS/2|    /
274 +---------------------+     +-----------+   / 
275
276 +---------------------------------------+
277 |               NTDLL.DLL               |
278 +---------------------------------------+
279
280 +---------------------------------------+     \
281 |               NT kernel               |      } NT kernel (kernel space)
282 +---------------------------------------+     /
283 +---------------------------------------+     \
284 |       Windows low-level drivers       |      } drivers (kernel space)
285 +---------------------------------------+     /
286           </screen>
287         </para>
288         <para>
289           Note also (not depicted in schema above) that the 16 bit
290           applications are supported in a specific subsystem.
291           Some basic differences between the Win9x and the NT
292           architectures include:
293           <itemizedlist>
294             <listitem>
295               <para>
296                 Several subsystems (Win32, Posix...) can be run on NT,
297                 while not on Win 9x
298               </para>
299             </listitem>
300             <listitem>
301               <para>
302                 Win 9x roots its architecture in 16 bit systems, while
303                 NT is truly a 32 bit system.
304               </para>
305             </listitem>
306             <listitem>
307               <para>
308                 The drivers model and interfaces in Win 9x and NT are
309                 different (even if Microsoft tried to bridge the gap
310                 with some support of WDM drivers in Win 98 and above).
311               </para>
312             </listitem>
313           </itemizedlist>
314         </para>
315       </sect2>
316     </sect1>
317
318     <sect1>
319       <title>Wine architecture</title>
320
321       <sect2>
322         <title>Global picture</title>
323
324         <para>
325           Wine implementation is closer to the Windows NT
326           architecture, even if several subsystems are not implemented
327           yet (remind also that 16bit support is implemented in a 32-bit
328           Windows EXE, not as a subsystem). Here's the overall picture:
329           <screen>
330 +---------------------+                                  \
331 |     Windows EXE     |                                   } application
332 +---------------------+                                  /
333
334 +---------+ +---------+                                  \
335 | Windows | | Windows |                                   \ application & system DLLs
336 |   DLL   | |   DLL   |                                   /
337 +---------+ +---------+                                  /
338
339 +---------+ +---------+     +-----------+  +--------+  \
340 |  GDI32  | |  USER32 |     |           |  |        |   \
341 |   DLL   | |   DLL   |     |           |  |  Wine  |    \
342 +---------+ +---------+     |           |  | Server |     \ core system DLLs
343 +---------------------+     |           |  |        |     / (on the left side)
344 |    Kernel32 DLL     |     | Subsystem |  | NT-like|    /
345 |  (Win32 subsystem)  |     |Posix, OS/2|  | Kernel |   /
346 +---------------------+     +-----------+  |        |  / 
347                                            |        |
348 +---------------------------------------+  |        |
349 |                 NTDLL                 |  |        |
350 +---------------------------------------+  +--------+
351
352 +---------------------------------------+               \
353 |   Wine executable (wine-?thread)      |                } unix executable
354 +---------------------------------------+               /
355 +---------------------------------------------------+   \
356 |                   Wine drivers                    |    } Wine specific DLLs
357 +---------------------------------------------------+   /
358
359 +------------+    +------------+     +--------------+   \
360 |    libc    |    |   libX11   |     |  other libs  |    } unix shared libraries
361 +------------+    +------------+     +--------------+   /  (user space)
362
363 +---------------------------------------------------+   \
364 |         Unix kernel (Linux,*BSD,Solaris,OS/X)     |    } (Unix) kernel space
365 +---------------------------------------------------+   /
366 +---------------------------------------------------+   \
367 |                 Unix device drivers               |    } Unix drivers (kernel space)
368 +---------------------------------------------------+   /
369           </screen>
370         </para>
371
372         <para>
373           Wine must at least completely replace the "Big Three" DLLs
374           (KERNEL/KERNEL32, GDI/GDI32, and USER/USER32), which all
375           other DLLs are layered on top of. But since Wine is (for
376           various reasons) leaning towards the NT way of implementing
377           things, the NTDLL is another core DLL to be implemented in
378           Wine, and many KERNEL32 and ADVAPI32 features will be
379           implemented through the NTDLL.
380         </para>
381         <para>
382           As of today, no real subsystem (apart the Win32 one) has
383           been implemented in Wine. 
384         </para>
385         <para>
386           The Wine server provides the backbone for the implementation
387           of the core DLLs. It mainly implementents inter-process
388           synchronization and object sharing. It can be seen, from a
389           functional point of view, as a NT kernel (even if the APIs
390           and protocols used between Wine's DLL and the Wine server
391           are Wine specific).
392         </para>
393         <para>
394           Wine uses the Unix drivers to access the various hardware
395           pieces on the box. However, in some cases, Wine will
396           provide a driver (in Windows sense) to a physical hardware
397           device. This driver will be a proxy to the Unix driver
398           (this is the case, for example, for the graphical part
399           with X11 or SDL drivers, audio with OSS or ALSA drivers...).
400         </para>
401         <para>
402           All DLLs provided by Wine try to stick as much as possible
403           to the exported APIs from the Windows platforms. There are
404           rare cases where this is not the case, and have been
405           propertly documented (Wine DLLs export some Wine specific
406           APIs). Usually, those are prefixed with
407           <function>__wine</function>.
408         </para>
409         <para>
410           Let's now review in greater details all of those components.
411         </para>
412       </sect2>
413
414       <sect2>
415         <title>The Wine server</title>
416         <para>
417           The Wine server is among the most confusing concepts in
418           Wine. What is its function in Wine? Well, to be brief, it
419           provides Inter-Process Communication (IPC),
420           synchronization, and process/thread management. When the
421           Wine server launches, it creates a Unix socket for the
422           current host based on (see below) your home directory's
423           <filename>.wine</filename> subdirectory (or wherever the
424           <constant>WINEPREFIX</constant> environment variable
425           points to) - all Wine processes launched later connects to
426           the Wine server using this socket. (If a Wine server was
427           not already running, the first Wine process will start up
428           the Wine server in auto-terminate mode (i.e. the Wine
429           server will then terminate itself once the last Wine
430           process has terminated).)
431         </para>
432         <para>
433           In earlier versions of Wine the master socket mentioned
434           above was actually created in the configuration directory;
435           either your home directory's <filename>/wine</filename>
436           subdirectory or wherever the
437           <constant>WINEPREFIX</constant> environment variable
438           points>. Since that might not be possible the socket is
439           actually created within the <filename>/tmp</filename>
440           directory with a name that reflects the configuration
441           directory. This means that there can actually be several
442           separate copies of the Wine server running; one per
443           combination of user and configuration directory. Note that
444           you should not have several users using the same
445           configuration directory at the same time; they will have
446           different copies of the Wine server running and this could
447           well lead to problems with the registry information that
448           they are sharing.
449         </para>
450         <para>
451           Every thread in each Wine process has its own request
452           buffer, which is shared with the Wine server. When a
453           thread needs to synchronize or communicate with any other
454           thread or process, it fills out its request buffer, then
455           writes a command code through the socket. The Wine server
456           handles the command as appropriate, while the client
457           thread waits for a reply. In some cases, like with the
458           various <function>WaitFor???</function> synchronization
459           primitives, the server handles it by marking the client
460           thread as waiting and does not send it a reply before the
461           wait condition has been satisfied.
462         </para>
463         <para>
464           The Wine server itself is a single and separate Unix
465           process and does not have its own threading - instead, it
466           is built on top of a large <function>poll()</function>
467           loop that alerts the Wine server whenever anything
468           happens, such as a client having sent a command, or a wait
469           condition having been satisfied. There is thus no danger
470           of race conditions inside the Wine server itself - it is
471           often called upon to do operations that look completely
472           atomic to its clients.
473         </para>
474         <para>
475           Because the Wine server needs to manage processes,
476           threads, shared handles, synchronization, and any related
477           issues, all the clients' Win32 objects are also managed by
478           the Wine server, and the clients must send requests to the
479           Wine server whenever they need to know any Win32 object
480           handle's associated Unix file descriptor (in which case
481           the Wine server duplicates the file descriptor, transmits
482           it back to the client, and leaves it to the client to
483           close the duplicate when the client has finished with
484           it).
485         </para>
486       </sect2>
487
488       <sect2>
489         <title>
490           Wine builtin DLLs: about Relays, Thunks, and DLL
491           descriptors
492         </title>
493         <para>
494           This section mainly applies to builtin DLLs (DLLs provided
495           by Wine). See section <xref linkend="arch-dlls"> for the
496           details on native vs. builtin DLL handling.
497         </para>
498         <para>
499           Loading a Windows binary into memory isn't that hard by
500           itself, the hard part is all those various DLLs and entry
501           points it imports and expects to be there and function as
502           expected; this is, obviously, what the entire Wine
503           implementation is all about. Wine contains a range of DLL
504           implementations. You can find the DLLs implementation in the
505           <filename>dlls/</filename> directory. 
506         </para>
507         <para>
508           Each DLL (at least, the 32 bit version, see below) is
509           implemented in a Unix shared library. The file name of this
510           shared library is the module name of the DLL with a
511           <filename>.dll.so</filename> suffix (or
512           <filename>.drv.so</filename> or any other relevant extension
513           depending on the DLL type). This shared library contains the
514           code itself for the DLL, as well as some more information,
515           as the DLL resources and a Wine specific DLL descriptor.
516         </para>
517         <para>
518           The DLL descriptor, when the DLL is instanciated, is used to
519           create an in-memory PE header, which will provide access to
520           various information about the DLL, including but not limited
521           to its entry point, its resources, its sections, its debug
522           information...
523         </para>
524         <para>
525           The DLL descriptor and entry point table is generated by
526           the <command>winebuild</command> tool (previously just
527           named <command>build</command>), taking DLL specification
528           files with the extension <filename>.spec</filename> as
529           input. Resources (after compilation by
530           <command>wrc</command>) or message tables (after
531           compilation by <command>wmc</command>) are also added to
532           the descriptor by <command>winebuild</command>.
533         </para>
534         <para>
535           Once an application module wants to import a DLL, Wine
536           will look at:
537           <itemizedlist>
538             <listitem>
539               <para>
540                 through its list of registered DLLs (in fact, both
541                 the already loaded DLLs, and the already loaded
542                 shared libraries which has registered a DLL
543                 descriptor). Since, the DLL descriptor is
544                 automatically registered when the shared library is
545                 loaded - remember, registration call is put inside a
546                 shared library constructor - using the
547                 <constant>PRELOAD</constant> environment variable
548                 when running a Wine process can force the
549                 registration of some DLL descriptors.
550               </para>
551             </listitem>
552             <listitem>
553               <para>
554                 If it's not registered, Wine will look for it on
555                 disk, building the shared library name from the DLL
556                 module name. Directory searched for are specified by
557                 the <constant>WINEDLLPATH</constant> environment
558                 variable.
559               </para>
560             </listitem>
561             <listitem>
562               <para>
563                 Failing that, it will look for a real Windows
564                 <filename>.DLL</filename> file to use, and look
565                 through its imports, etc) and use the loading of
566                 native DLLs.
567               </para>
568             </listitem>
569           </itemizedlist>
570         </para>
571         <para>
572           After the DLL has been identified (assuming it's still a
573           native one), it's mapped into memory using a
574           <function>dlopen()</function> call. Note, that Wine doesn't
575           use the shared library mechanisms for resolving and/or
576           importing functions between two shared libraries (for two
577           DLLs). The shared library is only used for providing a way
578           to load a piece of code on demand. This piece of code,
579           thanks the DLL descriptor, will provide the same type of
580           information a native DLL would. Wine can then use the same
581           code for native and builtin DLL to handle imports/exports.
582         </para>
583         <para>
584           Wine also relies on the dynamic loading features of the Unix
585           shared libraries to relocate the DLLs if needed (the same
586           DLL can be loaded at different address in two different
587           processes, and even in two consecutive run of the same
588           executable if the order of loading the DLLs differ). 
589         </para>
590         <para>
591           The DLL descriptor is registered in the Wine realm using
592           some tricks. The <command>winebuild</command> tool, while
593           creating the code for DLL descriptor, also creates a
594           constructor, that will be called when the shared library is
595           loaded into memory. This constructor will actually register
596           the descriptor to the Wine DLL loader. Hence, before the
597           <function>dlopen</function> call returns, the DLL descriptor
598           will be known and registered. This also helps to deal with
599           the cases where there's still dependencies (at the ELF
600           shared lib level, not at the embedded DLL level) between
601           different shared libraries: the embedded DLLs will be
602           properly registered, and even loaded (from a Windows point
603           of view).
604         </para>
605         <para>
606           Since Wine is 32-bit code itself, and if the compiler
607           supports Windows' calling convention, <type>stdcall</type>
608           (<command>gcc</command> does), Wine can resolve imports
609           into Win32 code by substituting the addresses of the Wine
610           handlers directly without any thunking layer in
611           between. This eliminates the overhead most people
612           associate with "emulation", and is what the applications
613           expect anyway.
614         </para>
615         <para>
616           However, if the user specified <parameter>WINEDEBUG=+relay
617           </parameter>, a thunk layer is inserted between the
618           application imports and the Wine handlers (actually the
619           export table of the DLL is modified, and a thunk is
620           inserted in the table); this layer is known as "relay"
621           because all it does is print out the arguments/return
622           values (by using the argument lists in the DLL
623           descriptor's entry point table), then pass the call on,
624           but it's invaluable for debugging misbehaving calls into
625           Wine code. A similar mechanism also exists between Windows
626           DLLs - Wine can optionally insert thunk layers between
627           them, by using <parameter>WINEDEBUG=+snoop</parameter>,
628           but since no DLL descriptor information exists for
629           non-Wine DLLs, this is less reliable and may lead to
630           crashes.
631         </para>
632         <para>
633           For Win16 code, there is no way around thunking - Wine
634           needs to relay between 16-bit and 32-bit code. These
635           thunks switch between the app's 16-bit stack and Wine's
636           32-bit stack, copies and converts arguments as appropriate
637           (an int is 16 bit 16-bit and 32 bits in 32-bit, pointers
638           are segmented in 16 bit (and also near or far) but are 32
639           bit linear values in 32 bit), and handles the Win16
640           mutex. Some finer control can be obtained on the
641           conversion, see <command>winebuild</command> reference
642           manual for the details. Suffice to say that the kind of
643           intricate stack content juggling this results in, is not
644           exactly suitable study material for beginners.
645         </para>
646         <para>
647           A DLL descriptor is also created for every 16 bit
648           DLL. However, this DLL normally paired with a 32 bit
649           DLL. Either, it's the 16 bit counterpart of the 16 bit DLL
650           (KRNL386.EXE for KERNEL32, USER for USER32...), or a 16
651           bit DLL directly linked to a 32 bit DLL (like SYSTEM for
652           KERNEL32, or DDEML for USER32). In those cases, the 16 bit
653           descriptor(s) is (are) inserted in the same shared library
654           as the the corresponding 32 bit DLL. Wine will also create
655           symbolic links between kernel32.dll.so and system.dll.so
656           so that loading of either
657           <filename>kernel32.dll</filename> or
658           <filename>system.dll</filename> will end up on the same
659           shared library.
660         </para>
661       </sect2>
662       <sect2 id="arch-dlls">
663         <title>Wine/Windows DLLs</title>
664
665         <para>
666           This document mainly deals with the status of current DLL
667           support by Wine.  The Wine ini file currently supports
668           settings to change the load order of DLLs.  The load order
669           depends on several issues, which results in different settings
670           for various DLLs.
671         </para>
672
673         <sect3>
674           <title>Pros of Native DLLs</title>
675
676           <para>
677             Native DLLs of course guarantee 100% compatibility for
678             routines they implement. For example, using the native USER
679             DLL would maintain a virtually perfect and Windows 95-like
680             look for window borders, dialog controls, and so on. Using
681             the built-in Wine version of this library, on the other
682             hand, would produce a display that does not precisely mimic
683             that of Windows 95.  Such subtle differences can be
684             engendered in other important DLLs, such as the common
685             controls library COMMCTRL or the common dialogs library
686             COMMDLG, when built-in Wine DLLs outrank other types in load
687             order.
688           </para>
689           <para>
690             More significant, less aesthetically-oriented problems can
691             result if the built-in Wine version of the SHELL DLL is
692             loaded before the native version of this library. SHELL
693             contains routines such as those used by installer utilities
694             to create desktop shortcuts. Some installers might fail when
695             using Wine's built-in SHELL.
696           </para>
697         </sect3>
698
699         <sect3>
700           <title>Cons of Native DLLs</title>
701
702           <para>
703             Not every application performs better under native DLLs. If
704             a library tries to access features of the rest of the system
705             that are not fully implemented in Wine, the native DLL might
706             work much worse than the corresponding built-in one, if at
707             all. For example, the native Windows GDI library must be
708             paired with a Windows display driver, which of course is not
709             present under Intel Unix and Wine.
710           </para>
711           <para>
712             Finally, occasionally built-in Wine DLLs implement more
713             features than the corresponding native Windows DLLs.
714             Probably the most important example of such behavior is the
715             integration of Wine with X provided by Wine's built-in USER
716             DLL. Should the native Windows USER library take load-order
717             precedence, such features as the ability to use the
718             clipboard or drag-and-drop between Wine windows and X
719             windows will be lost.
720           </para>
721         </sect3>
722
723         <sect3>
724           <title>Deciding Between Native and Built-In DLLs</title>
725
726           <para>
727             Clearly, there is no one rule-of-thumb regarding which
728             load-order to use. So, you must become familiar with
729             what specific DLLs do and which other DLLs or features 
730             a given library interacts with, and use this information 
731             to make a case-by-case decision.
732           </para>
733         </sect3>
734
735         <sect3>
736           <title>Load Order for DLLs</title>
737
738           <para>
739             Using the DLL sections from the wine configuration file, the
740             load order can be tweaked to a high degree. In general it is
741             advised not to change the settings of the configuration
742             file. The default configuration specifies the right load
743             order for the most important DLLs.
744           </para>
745           <para>
746             The default load order follows this algorithm: for all DLLs
747             which have a fully-functional Wine implementation, or where
748             the native DLL is known not to work, the built-in library
749             will be loaded first. In all other cases, the native DLL
750             takes load-order precedence.
751           </para>
752           <para>
753             The <varname>DefaultLoadOrder</varname> from the
754             [DllDefaults] section specifies for all DLLs which version
755             to try first. See manpage for explanation of the arguments.
756           </para>
757           <para>
758             The [DllOverrides] section deals with DLLs, which need a
759             different-from-default treatment. 
760           </para>
761           <para>
762             The [DllPairs] section is for DLLs, which must be loaded in
763             pairs. In general, these are DLLs for either 16-bit or
764             32-bit applications. In most cases in Windows, the 32-bit
765             version cannot be used without its 16-bit counterpart. For
766             Wine, it is customary that the 16-bit implementations rely
767             on the 32-bit implementations and cast the results back to
768             16-bit arguments. Changing anything in this section is bound
769             to result in errors.
770           </para>
771           <para>
772             For the future, the Wine implementation of Windows DLL seems
773             to head towards unifying the 16 and 32 bit DLLs wherever
774             possible, resulting in larger DLLs.  They are stored in the
775             <filename>dlls/</filename> subdirectory using the 32-bit
776             name.
777           </para>
778         </sect3>
779       </sect2>
780
781       <sect2 id="arch-mem">
782         <title>Memory management</title>
783         <para>
784           Every Win32 process in Wine has its own dedicated native
785           process on the host system, and therefore its own address
786           space. This section explores the layout of the Windows
787           address space and how it is emulated.
788         </para>
789
790         <para>
791           Firstly, a quick recap of how virtual memory works. Physical
792           memory in RAM chips is split into
793           <emphasis>frames</emphasis>, and the memory that each
794           process sees is split into <emphasis>pages</emphasis>. Each
795           process has its own 4 gigabytes of address space (4gig being
796           the maximum space addressable with a 32 bit pointer). Pages
797           can be mapped or unmapped: attempts to access an unmapped
798           page cause an
799           <constant>EXCEPTION_ACCESS_VIOLATION</constant> which has
800           the easily recognizable code of
801           <constant>0xC0000005</constant>. Any page can be mapped to
802           any frame, therefore you can have multiple addresses which
803           actually "contain" the same memory. Pages can also be mapped
804           to things like files or swap space, in which case accessing
805           that page will cause a disk access to read the contents into
806           a free frame.
807         </para>
808
809         <sect3>
810           <title>Initial layout (in Windows)</title>
811           <para>
812             When a Win32 process starts, it does not have a clear
813             address space to use as it pleases. Many pages are already
814             mapped by the operating system. In particular, the EXE
815             file itself and any DLLs it needs are mapped into memory,
816             and space has been reserved for the stack and a couple of
817             heaps (zones used to allocate memory to the app
818             from). Some of these things need to be at a fixed address,
819             and others can be placed anywhere.
820           </para>
821
822           <para>
823             The EXE file itself is usually mapped at address 0x400000
824             and up: indeed, most EXEs have their relocation records
825             stripped which means they must be loaded at their base
826             address and cannot be loaded at any other address.
827           </para>
828
829           <para>
830             DLLs are internally much the same as EXE files but they
831             have relocation records, which means that they can be
832             mapped at any address in the address space. Remember we
833             are not dealing with physical memory here, but rather
834             virtual memory which is different for each
835             process. Therefore <filename>OLEAUT32.DLL</filename> may
836             be loaded at one address in one process, and a totally
837             different one in another. Ensuring all the functions
838             loaded into memory can find each other is the job of the
839             Windows dynamic linker, which is a part of NTDLL.
840           </para>
841           <para>
842             So, we have the EXE and its DLLs mapped into memory. Two
843             other very important regions also exist: the stack and the
844             process heap. The process heap is simply the equivalent of
845             the libc <function>malloc</function> arena on UNIX: it's a
846             region of memory managed by the OS which
847             <function>malloc</function>/<function>HeapAlloc</function>
848             partitions and hands out to the application. Windows
849             applications can create several heaps but the process heap
850             always exists.
851           </para>
852           <para>
853             Windows 9x also implements another kind of heap: the
854             shared heap. The shared heap is unusual in that
855             anything allocated from it will be visible in every other
856             process.
857           </para>
858         </sect3>
859
860         <sect3>
861           <title>Comparison</title>
862           <para>
863             So far we've assumed the entire 4 gigs of address space is
864             available for the application. In fact that's not so: only
865             the lower 2 gigs are available, the upper 2 gigs are on
866             Windows NT used by the operating system and hold the
867             kernel (from 0x80000000). Why is the kernel mapped into
868             every address space?  Mostly for performance: while it's
869             possible to give the kernel its own address space too -
870             this is what Ingo Molnars 4G/4G VM split patch does for
871             Linux - it requires that every system call into the kernel
872             switches address space. As that is a fairly expensive
873             operation (requires flushing the translation lookaside
874             buffers etc) and syscalls are made frequently it's best
875             avoided by keeping the kernel mapped at a constant
876             position in every processes address space.
877           </para>
878           
879           <para>
880             Basically, the comparison of memory mappings looks as
881             follows:
882             <table>
883               <title>Memory layout (Windows and Wine)</title>
884               <tgroup cols="4" align="left" colsep="1" rowsep="1">
885                 <thead>
886                   <row>
887                     <entry>Address</entry>
888                     <entry>Windows 9x</entry>
889                     <entry>Windows NT</entry>
890                     <entry>Linux</entry>
891                   </row>
892                 </thead>
893                 <tbody>
894                   <row>
895                     <entry>00000000-7fffffff</entry>
896                     <entry>User</entry>
897                     <entry>User</entry>
898                     <entry>User</entry>
899                   </row>
900                   <row>
901                     <entry>80000000-bfffffff</entry>
902                     <entry>Shared</entry>
903                     <entry>User</entry>
904                     <entry>User</entry>
905                   </row>
906                   <row>
907                     <entry>c0000000-ffffffff</entry>
908                     <entry>Kernel</entry>
909                     <entry>Kernel</entry>
910                     <entry>Kernel</entry>
911                   </row>
912                 </tbody>
913               </tgroup>
914             </table>
915           </para>
916
917           <para>
918             On Windows 9x, in fact only the upper gigabyte
919             (<constant>0xC0000000</constant> and up) is used by the
920             kernel, the region from 2 to 3 gigs is a shared area used
921             for loading system DLLs and for file mappings. The bottom
922             2 gigs on both NT and 9x are available for the programs
923             memory allocation and stack.
924           </para>
925         </sect3>
926
927         <sect3>
928           <title>Implementation</title>
929           <para>
930             Wine (with a bit of black magic) is able to map all items
931             at the correct locations as depicted above.
932           </para>
933           <para>
934             Wine also implements the shared heap so native win9x DLLs
935             can be used. This heap is always created at the
936             <constant>SYSTEM_HEAP_BASE</constant> address or
937             <constant>0x80000000</constant> and defaults to 16
938             megabytes in size.
939           </para>
940           <para>
941             There are a few other magic locations. The bottom 64k of
942             memory is deliberately left unmapped to catch null pointer
943             dereferences. The region from 64k to 1mb+64k are reserved
944             for DOS compatibility and contain various DOS data
945             structures. Finally, the address space also contains
946             mappings for the Wine binary itself, any native libaries
947             Wine is using, the glibc malloc arena and so on.
948           </para>
949         </sect3>
950
951         <sect3 id="address-space">
952           <title>Laying out the address space</title>
953
954           <para>
955             Up until about the start of 2004, the Linux address space
956             very much resembled the Windows 9x layout: the kernel sat
957             in the top gigabyte, the bottom pages were unmapped to
958             catch null pointer dereferences, and the rest was
959             free. The kernels mmap algorithm was predictable: it would
960             start by mapping files at low addresses and work up from
961             there.
962           </para>
963
964           <para>
965             The development of a series of new low level patches
966             violated many of these assumptions, and resulted in Wine
967             needing to force the Win32 address space layout upon the
968             system. This section looks at why and how this is done.
969           </para>
970
971           <para>
972             The exec-shield patch increases security by randomizing
973             the kernels mmap algorithms. Rather than consistently
974             choosing the same addresses given the same sequence of
975             requests, the kernel will now choose randomized
976             addresses. Because the Linux dynamic linker
977             (ld-linux.so.2) loads DSOs into memory by using mmap, this
978             means that DSOs are no longer loaded at predictable
979             addresses, so making it harder to attack software by using
980             buffer overflows. It also attempts to relocate certain
981             binaries into a special low area of memory known as the
982             ASCII armor so making it harder to jump into them when
983             using string based attacks.
984           </para>
985
986           <para>
987             Prelink is a technology that enhances startup times by
988             precalculating ELF global offset tables then saving the
989             results inside the native binaries themselves. By grid
990             fitting each DSO into the address space, the dynamic
991             linker does not have to perform as many relocations so
992             allowing applications that heavily rely on dynamic linkage
993             to be loaded into memory much quicker. Complex C++
994             applications such as Mozilla, OpenOffice and KDE can
995             especially benefit from this technique.
996           </para>
997
998           <para>
999             The 4G VM split patch was developed by Ingo Molnar. It
1000             gives the Linux kernel its own address space, thereby
1001             allowing processes to access the maximum addressable
1002             amount of memory on a 32-bit machine: 4 gigabytes. It
1003             allows people with lots of RAM to fully utilise that in
1004             any given process at the cost of performance: the reason
1005             behind giving the kernel a part of each processes address
1006             space was to avoid the overhead of switching on each
1007             syscall.
1008           </para>
1009
1010           <para>
1011             Each of these changes alter the address space in a way
1012             incompatible with Windows. Prelink and exec-shield mean
1013             that the libraries Wine uses can be placed at any point in
1014             the address space: typically this meant that a library was
1015             sitting in the region that the EXE you wanted to run had
1016             to be loaded (remember that unlike DLLs, EXE files cannot
1017             be moved around in memory). The 4G VM split means that
1018             programs could receive pointers to the top gigabyte of
1019             address space which some are not prepared for (they may
1020             store extra information in the high bits of a pointer, for
1021             instance). In particular, in combination with exec-shield
1022             this one is especially deadly as it's possible the process
1023             heap could be allocated beyond ADDRESS_SPACE_LIMIT which
1024             causes Wine initialization to fail.
1025           </para>
1026
1027           <para>
1028             The solution to these problems is for Wine to reserve
1029             particular parts of the address space so that areas that
1030             we don't want the system to use will be avoided. We later
1031             on (re/de)allocate those areas as needed. One problem is
1032             that some of these mappings are put in place automatically
1033             by the dynamic linker: for instance any libraries that
1034             Wine is linked to (like libc, libwine, libpthread etc)
1035             will be mapped into memory before Wine even gets
1036             control. In order to solve that, Wine overrides the
1037             default ELF initialization sequence at a low level and
1038             reserves the needed areas by using direct syscalls into
1039             the kernel (ie without linking against any other code to
1040             do it) before restarting the standard initialization and
1041             letting the dynamic linker continue. This is referred to
1042             as the preloader and is found in loader/preloader.c.
1043           </para>
1044
1045           <para>
1046             Once the usual ELF boot sequence has been completed, some
1047             native libraries may well have been mapped above the 3gig
1048             limit: however, this doesn't matter as 3G is a Windows
1049             limit, not a Linux limit. We still have to prevent the
1050             system from allocating anything else above there (like the
1051             heap or other DLLs) though so Wine performs a binary
1052             search over the upper gig of address space in order to
1053             iteratively fill in the holes with MAP_NORESERVE mappings
1054             so the address space is allocated but the memory to
1055             actually back it is not. This code can be found in libs/wine/mmap.c:reserve_area.
1056           </para>
1057         </sect3>
1058       </sect2>
1059
1060       <sect2>
1061         <title>Processes</title>
1062         <para>
1063           Let's take a closer look at the way Wine loads and run
1064           processes in memory.
1065         </para>
1066         <sect3>
1067           <title>Starting a process from command line</title>
1068           <para>
1069             When starting a Wine process from command line (we'll get
1070             later on to the differences between NE, PE and Winelib
1071             executables), there are a couple of things Wine need to do
1072             first. A first executable is run to check the threading
1073             model of the underlying OS (see <xref linkend="threading">
1074             for the details) and will start the real Wine loader
1075             corresponding to the choosen threading model.
1076           </para>
1077           <para>
1078             Then Wine graps a few elements from the Unix world: the
1079             environment, the program arguments. Then the
1080             <filename>ntdll.dll.so</filename> is loaded into memory
1081             using the standard shared library dynamic loader. When
1082             loaded, NTDLL will mainly first create a decent Windows
1083             environment:
1084             <itemizedlist>
1085               <listitem>
1086                 <para>create a PEB and a TEB</para>
1087               </listitem>
1088               <listitem>
1089                 <para>
1090                   set up the connection to the Wine server - and
1091                   eventually launching the Wine server if none runs
1092                 </para>
1093               </listitem>
1094               <listitem>
1095                 <para>create the process heap</para>
1096               </listitem>
1097             </itemizedlist>
1098           </para>
1099           <para>
1100             Then <filename>Kernel32</filename> is loaded (but now
1101             using the Windows dynamic loading capabilities) and a Wine
1102             specific entry point is called
1103             <function>__wine_kernel_init</function>. This function
1104             will actually handle all the logic of the process loading
1105             and execution, and will never return from it's call.
1106           </para>
1107           <para>
1108             <function>__wine_kernel_init</function> will undergo the
1109             following tasks:
1110             <itemizedlist>
1111               <listitem>
1112                 <para>
1113                   initialization of program arguments from Unix
1114                   program arguments
1115                 </para>
1116               </listitem>
1117               <listitem>
1118                 <para>
1119                   lookup of executable in the file system
1120                 </para>
1121               </listitem>
1122               <listitem>
1123                 <para>
1124                   If the file is not found, then an error is printed
1125                   and the Wine loader stops.
1126                 </para>
1127               </listitem>
1128               <listitem>
1129                 <para>
1130                   We'll cover the non-PE file type later on, so assume
1131                   for now it's a PE file. The PE module is loaded in
1132                   memory using the Windows shared library
1133                   mechanism. Note that the dependencies on the module
1134                   are not resolved at this point.
1135                 </para>
1136               </listitem>
1137               <listitem>
1138                 <para>
1139                   A new stack is created, which size is given in the
1140                   PE header, and this stack is made the one of the
1141                   running thread (which is still the only one in the
1142                   process). The stack used at startup will no longer
1143                   be used.
1144                 </para>
1145               </listitem>
1146               <listitem>
1147                 <para>
1148                   Which this new stack,
1149                   <function>ntdll.LdrInitializeThunk</function> is
1150                   called which performs the remaining initialization
1151                   parts, including resolving all the DLL imports on
1152                   the PE module, and doing the init of the TLS slots.
1153                 </para>
1154               </listitem>
1155               <listitem>
1156                 <para>
1157                   Control can now be passed to the
1158                   <function>EntryPoint</function> of the PE module,
1159                   which will let the executable run.
1160                 </para>
1161               </listitem>
1162             </itemizedlist>
1163           </para>
1164         </sect3>
1165         <sect3>
1166           <title>Creating a child process from a running process</title>
1167           <para>
1168             The steps used are closely link to what is done in the
1169             previous case.
1170           </para>
1171           <para>
1172             There are however a few points to look at a bit more
1173             closely. The inner implementation creates the child
1174             process using the <function>fork()</function> and
1175             <function>exec()</function> calls. This means that we
1176             don't need to check again for the threading model, we can
1177             use what the parent (or the grand-parent process...)
1178             started from command line has found.
1179           </para>
1180           <para>
1181             The Win32 process creation allows to pass a lot of
1182             information between the parent and the child. This
1183             includes object handles, windows title, console
1184             parameters, environment strings... Wine makes use of both
1185             the standard Unix inheritance mechanisms (for environment
1186             for example) and the Wine server (to pass from parent to
1187             child a chunk of data containing the relevant information).
1188           </para>
1189           <para>
1190             The previously described loading mechanism will check in
1191             the Wine server if such a chunk exists, and, if so, will
1192             perform the relevant initialization.
1193           </para>
1194           <para>
1195             Some further synchronization is also put in place: a
1196             parent will wait until the child has started, or has
1197             failed. The Wine server is also used to perform those
1198             tasks.
1199           </para>
1200         </sect3>
1201         <sect3>
1202           <title>Starting a Winelib process</title>
1203           <para>
1204             Before going into the gory details, let's first go back to
1205             what a Winelib application is. It can be either a regular
1206             Unix executable, or a more specific Wine beast. This later
1207             form in fact creates two files for a given executable (say
1208             <filename>foo.exe</filename>). The first one, named
1209             <filename>foo</filename> will be a symbolic link to the
1210             Wine loader (<filename>wine</filename>). The second one,
1211             named <filename>foo.exe.so</filename>, is the equivalent
1212             of the <filename>.dll.so</filename> files we've already
1213             described for DLLs. As in Windows, an executable is, among
1214             other things, a module with its import and export
1215             information, as any DLL, it makes sense Wine uses the same
1216             mechanisms for loading native executables and DLLs.
1217           </para>
1218           <para>
1219             When starting a Winelib application from the command line
1220             (say with <command>foo arg1 arg2</command>), the Unix
1221             shell will execute <command>foo</command> as a Unix
1222             executable. Since this is in fact the Wine loader, Wine
1223             will fire up. However, will notice that it hasn't been
1224             started as <command>wine</command> but as
1225             <command>foo</command>, and hence, will try to load (using
1226             Unix shared library mechanism) the second file
1227             <filename>foo.exe.so</filename>. Wine will recognize a 32
1228             bit module (with its descriptor) embedded in the shared
1229             library, and once the shared library loaded, it will
1230             proceed the same path as when loading a standard native PE
1231             executable.
1232           </para>
1233           <para>
1234             Wine needs to implement this second form of executable in
1235             order to maintain the order of initialization of some
1236             elements in the executable. One particular issue is when
1237             dealing with global C++ objects. In standard Unix
1238             executable, the call of the constructor to such objects is
1239             stored in the specific section of the executable
1240             (<function>.init</function> not to name it). All
1241             constructors in this section are called before the
1242             <function>main</function> function is called. Creating a
1243             Wine executable using the first form mentionned above will
1244             let those constructors being called before Wine gets a
1245             chance to initialize itself. So, any constructor using a
1246             Windows API will fail, because Wine infrastructure isn't
1247             in place. The use of the second form for Winelib
1248             executables ensures that we do the initialization using
1249             the following steps:
1250             <itemizedlist>
1251               <listitem>
1252                 <para>
1253                   initialize the Wine infrastructure
1254                 </para>
1255               </listitem>
1256               <listitem>
1257                 <para>
1258                   load the executable into memory
1259                 </para>
1260               </listitem>
1261               <listitem>
1262                 <para>
1263                   handle the import sections for the executable
1264                 </para>
1265               </listitem>
1266               <listitem>
1267                 <para>
1268                   call the global object constructors (if any). They
1269                   now can properly call the Windows APIs
1270                 </para>
1271               </listitem>
1272               <listitem>
1273                 <para>
1274                   call the executable entry point
1275                 </para>
1276               </listitem>
1277             </itemizedlist>
1278           </para>
1279           <para>
1280             The attentive reader would have noted that the resolution
1281             of imports for the executable is done, as for a DLL, when
1282             the executable/DLL descriptor is registered. However, this
1283             is done also by adding a specific constructor in the
1284             <function>.init</function> section. For the above describe
1285             scheme to function properly, this constructor must be the
1286             first constructor to be called, before all the other
1287             constructors, generated by the executable itself. The Wine
1288             build chain takes care of that, and also generating the
1289             executable/DLL descriptor for the Winelib executable.
1290           </para>
1291         </sect3>
1292         <sect3>
1293           <title>Starting a NE (Win16) process</title>
1294           <para>
1295             When Wine is requested to run a NE (Win 16 process), it
1296             will in fact hand over the execution of it to a specific
1297             executable <filename>winevdm</filename>. VDM stands for
1298             Virtual DOS Machine. This <filename>winevdm</filename>
1299             will in fact set up the correct 16 bit environment to run
1300             the executable. Any new 16 bit process created by this
1301             executable (or its children) will run into the same
1302             <filename>winevdm</filename> instance. Among one instance,
1303             several functionalities will be provided to those 16 bit
1304             processes, including the cooperative multitasking, sharing
1305             the same address space, managing the selectors for the 16
1306             bit segments needed for code, data and stack.
1307           </para>
1308           <para>
1309             Note that several <filename>winevdm</filename> instances
1310             can run in the same Wine session, but the functionalities
1311             described above are only shared among a given instance,
1312             not among all the instances. <filename>winevdm</filename>
1313             is built as Winelib application, and hence has access to
1314             any facility a 32 bit application has.
1315           </para>
1316           <para>
1317             The behaviour we just described also applies to DOS
1318             executables, which are handled the same way by
1319             <filename>winevdm</filename>.
1320           </para>
1321         </sect3>
1322       </sect2>
1323       <sect2>
1324         <title>Wine drivers</title>
1325         <para>
1326           Wine will not allow running native Windows drivers under
1327           Unix. This comes mainly because (look at the generic
1328           architecture schemas) Wine doesn't implement the kernel
1329           features of Windows (kernel here really means the kernel,
1330           not the KERNEL32 DLL), but rather sets up a proxy layer on
1331           top of the Unix kernel to provide the NTDLL and KERNEL32
1332           features. This means that Wine doesn't provide the inner
1333           infrastructure to run native drivers, either from the Win9x
1334           family or from the NT family.
1335         </para>
1336         <para>
1337           In other words, Wine will only be able to provide access to
1338           a specific device, if and only if, 1/ this device is
1339           supported in Unix (there is Unix-driver to talk to it), 2/
1340           Wine has implemented the proxy code to make the glue between
1341           the API of a Windows driver, and the Unix interface of the
1342           Unix driver.
1343         </para>
1344         <para>
1345           Wine, however, tries to implement in the various DLLs
1346           needing to access devices to do it through the standard
1347           Windows APIs for device drivers in user space. This is for
1348           example the case for the multimedia drivers, where Wine
1349           loads Wine builtin DLLs to talk to the OSS interface, or the
1350           ALSA interface. Those DLLs implement the same interface as
1351           any user space audio driver in Windows.
1352         </para>
1353       </sect2>
1354     </sect1>
1355   </chapter>
1356
1357
1358 <!-- Keep this comment at the end of the file
1359 Local variables:
1360 mode: sgml
1361 sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")
1362 End:
1363 -->