| <chapter> |
| <title>Kernel modules</title> |
| <para> |
| This section cover the kernel modules. As already stated, Wine |
| implements the NT architecture, hence provides NTDLL for the |
| core kernel functions, and KERNEL32, which is the |
| implementation of the basis of the Win32 subsystem, on top of |
| NTDLL. |
| </para> |
| <sect1 id="ntdll"> |
| <title>NTDLL</title> |
| <para> |
| NTDLL provides most of the services you'd expect from a |
| kernel. |
| </para> |
| <para> |
| Process and thread management are part of them (even if |
| process management is still mainly done in KERNEL32, unlike |
| NT). A Windows process runs as a Unix process, and a Windows |
| thread runs as a Unix thread. |
| </para> |
| <para> |
| Wine also provide fibers (which is the Windows name of |
| co-routines). |
| </para> |
| <para> |
| Most of the Windows memory handling (Heap, Global and Local |
| functions, virtual memory...) are easily mapped upon their |
| Unix equivalents. Note the NTDLL doesn't know about 16 bit |
| memory, which is only handled in KERNEL32/KRNL386.EXE (and |
| also the DOS routines). |
| </para> |
| |
| <sect2> |
| <title>File management</title> |
| <para> |
| Wine uses some configuration in order to map Windows |
| filenames (either defined with drive letters, or as UNC |
| names) to the unix filenames. Wine also uses some |
| incantation so that most of file related APIs can also |
| take full unix names. This is handy when passing filenames |
| on the command line. |
| </para> |
| <para> |
| File handles can be waitable objects, as Windows define |
| them. |
| </para> |
| <para> |
| Asynchronous I/O is implemented on file handles by |
| queueing pseudo APC. They are not real APC in the sense |
| that they have the same priority as the threads in the |
| considered process (while APCs on NT have normally a |
| higher priority). These APCs get called when invoking |
| Wine server (which should lead to correct behavior when the |
| program ends up waiting on some object - waiting always |
| implies calling Wine server). |
| </para> |
| <para> |
| FIXME: this should be enhanced and updated to latest work |
| on FS. |
| </para> |
| </sect2> |
| |
| <sect2> |
| <title>Synchronization</title> |
| <para> |
| Most of the synchronization (between threads or processes) |
| is done in Wine server, which handles both the waiting |
| operation (on a single object or a set of objects) and the |
| signaling of objects. |
| </para> |
| </sect2> |
| |
| <sect2> |
| <title>Module (DLL) loading</title> |
| <para> |
| Wine is able to load any NE and PE module. In all cases, |
| the module's binary code is directly executed by the |
| processor. |
| </para> |
| </sect2> |
| |
| <sect2> |
| <title>Device management</title> |
| <para> |
| Wine allows usage a wide variety of devices: |
| <itemizedlist> |
| <listitem> |
| <para> |
| Communication ports are mapped to Unix |
| communication ports (if they have sufficient |
| permissions). |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| Parallel ports are mapped to Unix parallel ports (if |
| they have sufficient permissions). |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| CDROM: the Windows device I/O control calls are |
| mapped onto Unix <function>ioctl()</function>. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| Some Win9x VxDs are supported, by rewriting some of |
| their internal behavior. But this support is |
| limited. Portable programs to Windows NT shouldn't |
| need them. |
| </para> |
| <para> |
| Wine will not support native VxD. |
| </para> |
| </listitem> |
| </itemizedlist> |
| </para> |
| </sect2> |
| <sect2 id="threading"> |
| <title>Multi-threading in Wine</title> |
| |
| <para> |
| This section will assume you understand the basics of |
| multithreading. If not there are plenty of good tutorials |
| available on the net to get you started. |
| </para> |
| |
| <para> |
| Threading in Wine is somewhat complex due to several |
| factors. The first is the advanced level of multithreading |
| support provided by Windows - there are far more threading |
| related constructs available in Win32 than the Linux |
| equivalent (pthreads). The second is the need to be able to |
| map Win32 threads to native Linux threads which provides us |
| with benefits like having the kernel schedule them without |
| our intervention. While it's possible to implement threading |
| entirely without kernel support, doing so is not desirable |
| on most platforms that Wine runs on. |
| </para> |
| |
| <sect3> |
| <title> Threading support in Win32 </title> |
| |
| <para> |
| Win32 is an unusually thread friendly API. Not only is it |
| entirely thread safe, but it provides many different |
| facilities for working with threads. These range from the |
| basics such as starting and stopping threads, to the |
| extremely complex such as injecting threads into other |
| processes and COM inter-thread marshalling. |
| </para> |
| |
| <para> |
| One of the primary challenges of writing Wine code |
| therefore is ensuring that all our DLLs are thread safe, |
| free of race conditions and so on. This isn't simple - |
| don't be afraid to ask if you aren't sure whether a piece |
| of code is thread safe or not! |
| </para> |
| |
| <para> |
| Win32 provides many different ways you can make your code |
| thread safe however the most common are <emphasis>critical |
| section</emphasis> and the <emphasis>interlocked |
| functions</emphasis>. Critical sections are a type of |
| mutex designed to protect a geographic area of code. If |
| you don't want multiple threads running in a piece of code |
| at once, you can protect them with calls to |
| <function>EnterCriticalSection</function> and |
| <function>LeaveCriticalSection</function>. The first call |
| to <function>EnterCriticalSection</function> by a thread |
| will lock the section and continue without stopping. If |
| another thread calls it then it will block until the |
| original thread calls |
| <function>LeaveCriticalSection</function> again. |
| </para> |
| |
| <para> |
| It is therefore vitally important that if you use critical |
| sections to make some code thread-safe, that you check |
| every possible codepath out of the code to ensure that any |
| held sections are left. Code like this: |
| </para> |
| |
| <programlisting> |
| if (res != ERROR_SUCCESS) return res; |
| </programlisting> |
| |
| <para> |
| is extremely suspect in a function that also contains a |
| call to <function>EnterCriticalSection</function>. Be |
| careful. |
| </para> |
| |
| <para> |
| If a thread blocks while waiting for another thread to |
| leave a critical section, you will see an error from the |
| <function>RtlpWaitForCriticalSection</function> function, |
| along with a note of which thread is holding the |
| lock. This only appears after a certain timeout, normally |
| a few seconds. It's possible the thread holding the lock |
| is just being really slow which is why Wine won't |
| terminate the app like a non-checked build of Windows |
| would, but the most common cause is that for some reason a |
| thread forgot to call |
| <function>LeaveCriticalSection</function>, or died while |
| holding the lock (perhaps because it was in turn waiting |
| for another lock). This doesn't just happen in Wine code: |
| a deadlock while waiting for a critical section could be |
| due to a bug in the app triggered by a slight difference |
| in the emulation. |
| </para> |
| |
| <para> |
| Another popular mechanism available is the use of |
| functions like <function>InterlockedIncrement</function> |
| and <function>InterlockedExchange</function>. These make |
| use of native CPU abilities to execute a single |
| instruction while ensuring any other processors on the |
| system cannot access memory, and allow you to do common |
| operations like add/remove/check a variable in thread-safe |
| code without holding a mutex. These are useful for |
| reference counting especially in free-threaded (thread |
| safe) COM objects. |
| </para> |
| |
| <para> |
| Finally, the usage of TLS slots are also popular. TLS |
| stands for thread-local storage, and is a set of slots |
| scoped local to a thread which you can store pointers |
| in. Look on MSDN for the <function>TlsAlloc</function> |
| function to learn more about the Win32 implementation of |
| this. Essentially, the contents of a given slot will be |
| different in each thread, so you can use this to store |
| data that is only meaningful in the context of a single |
| thread. On recent versions of Linux the __thread keyword |
| provides a convenient interface to this functionality - a |
| more portable API is exposed in the pthread |
| library. However, these facilities are not used by Wine, |
| rather, we implement Win32 TLS entirely ourselves. |
| </para> |
| </sect3> |
| |
| <sect3> |
| <title> SysLevels </title> |
| |
| <para> |
| SysLevels are an undocumented Windows-internal |
| thread-safety system. They are basically critical sections |
| which must be taken in a particular order. The mechanism |
| is generic but there are always three syslevels: level 1 |
| is the Win16 mutex, level 2 is the USER mutex and level 3 |
| is the GDI mutex. |
| </para> |
| |
| <para> |
| When entering a syslevel, the code (in |
| <filename>dlls/kernel/syslevel.c</filename>) will check |
| that a higher syslevel is not already held and produce an |
| error if so. This is because it's not legal to enter level |
| 2 while holding level 3 - first, you must leave level 3. |
| </para> |
| |
| <para> |
| Throughout the code you may see calls to |
| <function>_ConfirmSysLevel()</function> and |
| <function>_CheckNotSysLevel()</function>. These functions |
| are essentially assertions about the syslevel states and |
| can be used to check that the rules have not been |
| accidentally violated. In particular, |
| <function>_CheckNotSysLevel()</function> will break |
| (probably into the debugger) if the check fails. If this |
| happens the solution is to get a backtrace and find out, |
| by reading the source of the wine functions called along |
| the way, how Wine got into the invalid state. |
| </para> |
| |
| </sect3> |
| |
| <sect3> |
| <title> POSIX threading vs kernel threading </title> |
| |
| <para> |
| Wine runs in one of two modes: either pthreads (posix |
| threading) or kthreads (kernel threading). This section |
| explains the differences between them. The one that is |
| used is automatically selected on startup by a small test |
| program which then execs the correct binary, either |
| wine-kthread or wine-pthread. On NPTL-enabled systems |
| pthreads will be used, and on older non-NPTL systems |
| kthreads is selected. |
| </para> |
| |
| <para> |
| Let's start with a bit of history. Back in the dark ages |
| when Wine's threading support was first implemented a |
| problem was faced - Windows had much more capable |
| threading APIs than Linux did. This presented a problem - |
| Wine works either by reimplementing an API entirely or by |
| mapping it onto the underlying systems equivalent. How |
| could Win32 threading be implemented using a library which |
| did not have all the needed features? The answer, of |
| course, was that it couldn't be. |
| </para> |
| |
| <para> |
| On Linux the pthreads interface is used to start, stop and |
| control threads. The pthreads library in turn is based on |
| top of so-called "kernel threads" which are created using |
| the <function>clone(2)</function> syscall. Pthreads |
| provides a nicer (more portable) interface to this |
| functionality and also provides APIs for controlling |
| mutexes. There is a <ulink |
| url="http://www.llnl.gov/computing/tutorials/pthreads/"> |
| good tutorial on pthreads </ulink> available if you want |
| to learn more. |
| </para> |
| |
| <para> |
| As pthreads did not provide the necessary semantics to |
| implement Win32 threading, the decision was made to |
| implement Win32 threading on top of the underlying kernel |
| threads by using syscalls like <function>clone</function> |
| directly. This provided maximum flexibility and allowed a |
| correct implementation but caused some bad side |
| effects. Most notably, all the userland Linux APIs assumed |
| that the user was utilising the pthreads library. Some |
| only enabled thread safety when they detected that |
| pthreads was in use - this is true of glibc, for |
| instance. Worse, pthreads and pure kernel threads had |
| strange interactions when run in the same process yet some |
| libraries used by Wine used pthreads internally. Throw in |
| source code porting using WineLib - where you have both |
| UNIX and Win32 code in the same process - and chaos was |
| the result. |
| </para> |
| |
| <para> |
| The solution was simple yet ingenious: Wine would provide |
| its own implementation of the pthread library |
| <emphasis>inside</emphasis> its own binary. Due to the |
| semantics of ELF symbol scoping, this would cause Wine's |
| own implementation to override any implementation loaded |
| later on (like the real libpthread.so). Therefore, any |
| calls to the pthread APIs in external libraries would be |
| linked to Wine's instead of the system's pthreads library, |
| and Wine implemented pthreads by using the standard |
| Windows threading APIs it in turn implemented itself. |
| </para> |
| |
| <para> |
| As a result, libraries that only became thread-safe in the |
| presence of a loaded pthreads implementation would now do |
| so, and any external code that used pthreads would |
| actually end up creating Win32 threads that Wine was aware |
| of and controlled. This worked quite nicely for a long |
| time, even though it required doing some extremely |
| un-kosher things like overriding internal libc structures |
| and functions. That is, it worked until NPTL was developed |
| at which point the underlying thread implementation on |
| Linux changed dramatically. |
| </para> |
| |
| <para> |
| The fake pthread implementation can be found in |
| <filename>loader/kthread.c</filename>, which is used to |
| produce the wine-kthread binary. In contrast, |
| loader/pthread.c produces the wine-pthread binary which is |
| used on newer NPTL systems. |
| </para> |
| |
| <para> |
| NPTL is a new threading subsystem for Linux that hugely |
| improves its performance and flexibility. By allowing |
| threads to become much more scalable and adding new |
| pthread APIs, NPTL made Linux competitive with Windows in |
| the multi-threaded world. Unfortunately it also broke many |
| assumptions made by Wine (as well as other applications |
| such as the Sun JVM and RealPlayer) in the process. |
| </para> |
| |
| <para> |
| There was, however, some good news. NPTL made Linux |
| threading powerful enough that Win32 threads could now be |
| implemented on top of pthreads like any other normal |
| application. There would no longer be problems with mixing |
| win32-kthreads and pthreads created by external libraries, |
| and no need to override glibc internals. As you can see |
| from the relative sizes of the |
| <filename>loader/kthread.c</filename> and |
| <filename>loader/pthread.c</filename> files, the |
| difference in code complexity is considerable. NPTL also |
| made several other semantic changes to things such as |
| signal delivery so changes were required in many different |
| places in Wine. |
| </para> |
| |
| <para> |
| On non-Linux systems the threading interface is typically |
| not powerful enough to replicate the semantics Win32 |
| applications expect and so kthreads with the pthread |
| overrides are used. |
| </para> |
| </sect3> |
| |
| <sect3> |
| <title> The Win32 thread environment </title> |
| |
| <para> |
| All Win32 code, whether from a native EXE/DLL or in Wine |
| itself, expects certain constructs to be present in its |
| environment. This section explores what those constructs |
| are and how Wine sets them up. The lack of this |
| environment is one thing that makes it hard to use Wine |
| code directly from standard Linux applications - in order |
| to interact with Win32 code a thread must first be |
| "adopted" by Wine. |
| </para> |
| |
| <para> |
| The first thing Win32 code requires is the |
| <emphasis>TEB</emphasis> or "Thread Environment |
| Block". This is an internal (undocumented) Windows |
| structure associated with every thread which stores a |
| variety of things such as TLS slots, a pointer to the |
| threads message queue, the last error code and so on. You |
| can see the definition of the TEB in |
| <filename>include/thread.h</filename>, or at least what we |
| know of it so far. Being internal and subject to change, |
| the layout of the TEB has had to be reverse engineered |
| from scratch. |
| </para> |
| |
| <para> |
| A pointer to the TEB is stored in the %fs register and can |
| be accessed using <function>NtCurrentTeb()</function> from |
| within Wine code. %fs actually stores a selector, and |
| setting it therefore requires modifying the processes |
| local descriptor table (LDT) - the code to do this is in |
| <filename>lib/wine/ldt.c</filename>. |
| </para> |
| |
| <para> |
| The TEB is required by nearly all Win32 code run in the |
| Wine environment, as any wineserver RPC will use it, which |
| in turn implies that any code which could possibly block |
| (for instance by using a critical section) needs it. The |
| TEB also holds the SEH exception handler chain as the |
| first element, so if disassembling you see code like this: |
| </para> |
| |
| <programlisting> movl %esp, %fs:0 </programlisting> |
| |
| <para> |
| ... then you are seeing the program set up an SEH handler |
| frame. All threads must have at least one SEH entry, which |
| normally points to the backstop handler which is |
| ultimately responsible for popping up the all-too-familiar |
| "This program has performed an illegal operation and will |
| be terminated" message. On Wine we just drop straight into |
| the debugger. A full description of SEH is out of the |
| scope of this section, however there are some good |
| articles in MSJ if you are interested. |
| </para> |
| |
| <para> |
| All Win32-aware threads must have a wineserver |
| connection. Many different APIs require the ability to |
| communicate with the wineserver. In turn, the wineserver |
| must be aware of Win32 threads in order to be able to |
| accurately report information to other parts of the program |
| and do things like route inter-thread messages, dispatch |
| APCs (asynchronous procedure calls) and so on. Therefore a |
| part of thread initialization is initializing the thread |
| serverside. The result is not only correct information in |
| the server, but a set of file descriptors the thread can use |
| to communicate with the server - the request fd, reply fd |
| and wait fd (used for blocking). |
| </para> |
| </sect3> |
| </sect2> |
| </sect1> |
| |
| <sect1> |
| <title>KERNEL Module</title> |
| |
| <para> |
| FIXME: Needs some content... |
| </para> |
| <sect2 id="consoles"> |
| <title>Consoles in Wine</title> |
| <para> |
| As described in the Wine User Guide's CUI section, Wine |
| manipulates three kinds of "consoles" in order to support |
| properly the Win32 CUI API. |
| </para> |
| <para> |
| The following table describes the main implementation |
| differences between the three approaches. |
| <table> |
| <title>Function consoles implementation comparison</title> |
| <tgroup cols="4" align="left"> |
| <thead> |
| <row> |
| <entry>Function</entry> |
| <entry>Bare streams</entry> |
| <entry>Wineconsole & user backend</entry> |
| <entry>Wineconsole & curses backend</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row> |
| <entry> |
| Console as a Win32 Object (and associated |
| handles) |
| </entry> |
| <entry> |
| No specific Win32 object is used in this |
| case. The handles manipulated for the standard |
| Win32 streams are in fact "bare handles" to |
| their corresponding Unix streams. The mode |
| manipulation functions |
| (<function>GetConsoleMode</function> / |
| <function>SetConsoleMode</function>) are not |
| supported. |
| </entry> |
| <entry> |
| Implemented in server, and a specific Winelib |
| program (wineconsole) is in charge of the |
| rendering and user input. The mode manipulation |
| functions behave as expected. |
| </entry> |
| <entry> |
| Implemented in server, and a specific Winelib |
| program (wineconsole) is in charge of the |
| rendering and user input. The mode manipulation |
| functions behave as expected. |
| </entry> |
| </row> |
| <row> |
| <entry> |
| Inheritance (including handling in |
| <function>CreateProcess</function> of |
| <constant>CREATE_DETACHED</constant>, |
| <constant>CREATE_NEW_CONSOLE</constant> flags). |
| </entry> |
| <entry> |
| Not supported. Every process child of a process |
| will inherit the Unix streams, so will also |
| inherit the Win32 standard streams. |
| </entry> |
| <entry> |
| Fully supported (each new console creation will |
| be handled by the creation of a new USER32 |
| window) |
| </entry> |
| <entry> |
| Fully supported, except for the creation of a |
| new console, which will be rendered on the same |
| Unix terminal as the previous one, leading to |
| unpredictable results. |
| </entry> |
| </row> |
| <row> |
| <entry> |
| <function>ReadFile</function> / |
| <function>WriteFile</function> |
| operations |
| </entry> |
| <entry>Fully supported</entry> |
| <entry>Fully supported</entry> |
| <entry>Fully supported</entry> |
| </row> |
| <row> |
| <entry> |
| Screen-buffer manipulation (creation, deletion, |
| resizing...) |
| </entry> |
| <entry>Not supported</entry> |
| <entry>Fully supported</entry> |
| <entry> |
| Partly supported (this won't work too well as we |
| don't control (so far) the size of underlying |
| Unix terminal |
| </entry> |
| </row> |
| <row> |
| <entry> |
| APIs for reading/writing screen-buffer content, |
| cursor position |
| </entry> |
| <entry>Not supported</entry> |
| <entry>Fully supported</entry> |
| <entry>Fully supported</entry> |
| </row> |
| <row> |
| <entry> |
| APIs for manipulating the rendering window size |
| </entry> |
| <entry>Not supported</entry> |
| <entry>Fully supported</entry> |
| <entry> |
| Partly supported (this won't work too well as we |
| don't control (so far) the size of underlying |
| Unix terminal |
| </entry> |
| </row> |
| <row> |
| <entry> |
| Signaling (in particular, Ctrl-C handling) |
| </entry> |
| <entry> |
| Nothing is done, which means that Ctrl-C will |
| generate (as usual) a |
| <constant>SIGINT</constant> which will terminate |
| the program. |
| </entry> |
| <entry> |
| Partly supported (Ctrl-C behaves as expected, |
| however the other Win32 CUI signaling isn't |
| properly implemented). |
| </entry> |
| <entry> |
| Partly supported (Ctrl-C behaves as expected, |
| however the other Win32 CUI signaling isn't |
| properly implemented). |
| </entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| </para> |
| |
| <para> |
| The Win32 objects behind a console can be created in |
| several occasions: |
| <itemizedlist> |
| <listitem> |
| <para> |
| When the program is started from wineconsole, a new |
| console object is created and will be used |
| (inherited) by the process launched from |
| wineconsole. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| When a program, which isn't attached to a console, |
| calls <function>AllocConsole</function>, Wine then |
| launches wineconsole, and attaches the current |
| program to this console. In this mode, the USER32 |
| mode is always selected as Wine cannot tell the |
| current state of the Unix console. |
| </para> |
| </listitem> |
| </itemizedlist> |
| </para> |
| <para> |
| Please also note, that starting a child process with the |
| <constant>CREATE_NEW_CONSOLE</constant> flag, will end-up |
| calling <function>AllocConsole</function> in the child |
| process, hence creating a wineconsole with the USER32 |
| backend. |
| </para> |
| </sect2> |
| </sect1> |
| |
| <sect1 id="initialization"> |
| |
| <title> The Wine initialization process </title> |
| |
| <para> |
| Wine has a rather complex startup procedure, so unlike many |
| programs the best place to begin exploring the code-base is |
| <emphasis>not</emphasis> in fact at the |
| <function>main()</function> function but instead at some of the |
| more straightforward DLLs that exist on the periphery such as |
| MSI, the widget library (in USER and COMCTL32) etc. The purpose |
| of this section is to document and explain how Wine starts up |
| from the moment the user runs "wine myprogram.exe" to the point |
| at which myprogram gets control. |
| </para> |
| |
| <sect2> |
| <title> First Steps </title> |
| |
| <para> |
| The actual wine binary that the user runs does not do very much, in fact it is only |
| responsible for checking the threading model in use (NPTL vs LinuxThreads) and then invoking |
| a new binary which performs the next stage in the startup sequence. See the beginning of this chapter |
| for more information on this check and why it's necessary. You can find this code in |
| <filename>loader/glibc.c</filename>. The result of this check is an exec of either |
| wine-pthread or wine-kthread, potentially (on Linux) via |
| the <emphasis>preloader</emphasis>. We need to use separate binaries here because overriding |
| the native pthreads library requires us to exploit a property of ELF symbol fixup semantics: |
| it's not possible to do this without starting a new process. |
| </para> |
| |
| <para> |
| The Wine preloader is found in <filename>loader/preloader.c</filename>, and is required in |
| order to impose a Win32 style address space layout upon the newly created Win32 process. The |
| details of what this does is covered in the address space layout chapter. The preloader is a |
| statically linked ELF binary which is passed the name of the actual Wine binary to run (either |
| wine-kthread or wine-pthread) along with the arguments the user passed in from the command |
| line. The preloader is an unusual program: it does not have a main() function. In standard ELF |
| applications, the entry point is actually at a symbol named _start: this is provided by the |
| standard gcc infrastructure and normally jumps to <function>__libc_start_main</function> which |
| initializes glibc before passing control to the main function as defined by the programmer. |
| </para> |
| |
| <para> |
| The preloader takes control direct from the entry point for a few reasons. Firstly, it is |
| required that glibc is not initialized twice: the result of such behaviour is undefined and |
| subject to change without notice. Secondly, it's possible that as part of initializing glibc, |
| the address space layout could be changed - for instance, any call to malloc will initialize a |
| heap arena which modifies the VM mappings. Finally, glibc does not return to _start at any |
| point, so by reusing it we avoid the need to recreate the ELF bootstrap stack (env, argv, |
| auxiliary array etc). |
| </para> |
| |
| <para> |
| The preloader is responsible for two things: protecting important regions of the address |
| space so the dynamic linker does not map shared libraries into them, and once that is done |
| loading the real Wine binary off disk, linking it and starting it up. Normally all this is |
| done automatically by glibc and the kernel but as we intercepted this process by using a |
| static binary it's up to us to restart the process. The bulk of the code in the preloader is |
| about loading wine-[pk]thread and ld-linux.so.2 off disk, linking them together, then |
| starting the dynamic linking process. |
| </para> |
| |
| <para> |
| One of the last things the preloader does before jumping into the dynamic linker is scan the |
| symbol table of the loaded Wine binary and set the value of a global variable directly: this |
| is a more efficient way of passing information to the main Wine program than flattening the |
| data structures into an environment variable or command line parameter then unpacking it on |
| the other side, but it achieves pretty much the same thing. The global variable set points to |
| the preload descriptor table, which contains the VMA regions protected by the preloader. This |
| allows Wine to unmap them once the dynamic linker has been run, so leaving gaps we can |
| initialize properly later on. |
| </para> |
| |
| </sect2> |
| |
| <sect2> |
| <title> Starting the emulator </title> |
| |
| <para> |
| The process of starting up the emulator itself is mostly one of chaining through various |
| initializer functions defined in the core libraries and DLLs: libwine, then NTDLL, then kernel32. |
| </para> |
| |
| <para> |
| Both the wine-pthread and wine-kthread binaries share a common <function>main</function> |
| function, defined in <filename>loader/main.c</filename>, so no matter which binary is selected |
| after the preloader has run we start here. This passes the information provided by the |
| preloader into libwine and then calls wine_init, defined |
| in <filename>libs/wine/loader.c</filename>. This is where the emulation really starts: |
| <function>wine_init</function> can, with the correct preparation, |
| be called from programs other than the wine loader itself. |
| </para> |
| |
| <para> |
| <function>wine_init</function> does some very basic setup tasks such as initializing the |
| debugging infrastructure, yet more address space manipulation (see the information on the |
| 4G/4G VM split in the address space chapter), before loading NTDLL - the core of both Wine and |
| the Windows NT series - and jumping to the <function>__wine_process_init</function> function defined |
| in <filename>dlls/ntdll/loader.c</filename> |
| </para> |
| |
| <para> |
| This function is responsible for initializing the primary Win32 environment. In thread_init(), |
| it sets up the TEB, the wineserver connection for the main thread and the process heap. See |
| the beginning of this chapter for more information on this. |
| </para> |
| |
| <para> |
| Finally, it loads and jumps to <function>__wine_kernel_init</function> in kernel32.dll: this |
| is defined in <filename>dlls/kernel32/process.c</filename>. This is where the bulk of the work |
| is done. The kernel32 initialization code retrieves the startup info for the process from the |
| server, initializes the registry, sets up the drive mapping system and locale data, then |
| begins loading the requested application itself. Each process has a STARTUPINFO block that can |
| be passed into <function>CreateProcess</function> specifying various things like how the first |
| window should be displayed: this is sent to the new process via the wineserver. |
| </para> |
| |
| <para> |
| After determining the type of file given to Wine by the user (a Win32 EXE file, a Win16 EXE, a |
| Winelib app etc), the program is loaded into memory (which may involve loading and |
| initializing other DLLs, the bulk of Wines startup code), before control reaches the end of |
| <function>__wine_kernel_init</function>. This function ends with the new process stack being |
| initialized, and start_process being called on the new stack. Nearly there! |
| </para> |
| |
| <para> |
| The final element of initializing Wine is starting the newly loaded program |
| itself. <function>start_process</function> sets up the SEH backstop handler, calls |
| <function>LdrInitializeThunk</function> which performs the last part of the process |
| initialization (such as performing relocations and calling the DllMains with PROCESS_ATTACH), |
| grabs the entry point of the executable and then on this line: |
| </para> |
| |
| <programlisting> |
| ExitProcess( entry( peb ) ); |
| </programlisting> |
| |
| <para> |
| ... jumps to the entry point of the program. At this point the users program is running and |
| the API provided by Wine is ready to be used. When entry returns, |
| the <function>ExitProcess</function> API will be used to initialize a graceful shutdown. |
| </para> |
| </sect2> |
| </sect1> |
| |
| <sect1 id="seh"> |
| <title>Structured Exception Handling</title> |
| |
| <para> |
| Structured Exception Handling (or SEH) is an implementation of |
| exceptions inside the Windows core. It allows code written in |
| different languages to throw exceptions across DLL boundaries, and |
| Windows reports various errors like access violations by throwing |
| them. This section looks at how it works, and how it's implemented |
| in Wine. |
| </para> |
| |
| <sect2> |
| <title> How SEH works </title> |
| |
| <para> |
| SEH is based on embedding EXCEPTION_REGISTRATION_RECORD |
| structures in the stack. Together they form a linked list rooted |
| at offset zero in the TEB (see the threading section if you |
| don't know what this is). A registration record points to a |
| handler function, and when an exception is thrown the handlers |
| are executed in turn. Each handler returns a code, and they can |
| elect to either continue through the handler chain or it can |
| handle the exception and then restart the program. This is |
| referred to as unwinding the stack. After each handler is called |
| it's popped off the chain. |
| </para> |
| |
| <para> |
| Before the system begins unwinding the stack, it runs vectored |
| handlers. This is an extension to SEH available in Windows XP, |
| and allows registered functions to get a first chance to watch |
| or deal with any exceptions thrown in the entire program, from |
| any thread. |
| </para> |
| |
| <para> |
| A thrown exception is represented by an EXCEPTION_RECORD |
| structure. It consists of a code, flags, an address and an |
| arbitrary number of DWORD parameters. Language runtimes can use |
| these parameters to associate language-specific information with |
| the exception. |
| </para> |
| |
| <para> |
| Exceptions can be triggered by many things. They can be thrown |
| explicitly by using the RaiseException API, or they can be |
| triggered by a crash (ie, translated from a signal). They may be |
| used internally by a language runtime to implement |
| language-specific exceptions. They can also be thrown across |
| DCOM connections. |
| </para> |
| |
| <para> |
| Visual C++ has various extensions to SEH which it uses to |
| implement, eg, object destruction on stack unwind as well as the |
| ability to throw arbitrary types. The code for this is in dlls/msvcrt/except.c |
| </para> |
| |
| </sect2> |
| |
| <sect2> |
| <title> Translating signals to exceptions </title> |
| |
| <para> |
| In Windows, compilers are expected to use the system exception |
| interface, and the kernel itself uses the same interface to |
| dynamically insert exceptions into a running program. By contrast |
| on Linux the exception ABI is implemented at the compiler level |
| (inside GCC and the linker) and the kernel tells a thread of |
| exceptional events by sending <emphasis>signals</emphasis>. The |
| language runtime may or may not translate these signals into |
| native exceptions, but whatever happens the kernel does not care. |
| </para> |
| |
| <para> |
| You may think that if an app crashes, it's game over and it |
| really shouldn't matter how Wine handles this. It's what you might |
| intuitively guess, but you'd be wrong. In fact some Windows |
| programs expect to be able to crash themselves and recover later |
| without the user noticing, some contain buggy binary-only |
| components from third parties and use SEH to swallow crashes, and |
| still others execute priviledged (kernel-level) instructions and |
| expect it to work. In fact, at least one set of APIs (the |
| IsBad*Ptr series) can only be implemented by performing an |
| operation that may crash and returning TRUE if it does, and FALSE |
| if it doesn't! So, Wine needs to not only implement the SEH |
| infrastructure but also translate Unix signals into SEH |
| exceptions. |
| </para> |
| |
| <para> |
| The code to translate signals into exceptions is a part of NTDLL, |
| and can be found in dlls/ntdll/signal_i386.c. This file sets up |
| handlers for various signals during Wine startup, and for the ones |
| that indicate exceptional conditions translates them into |
| exceptions. Some signals are used by Wine internally and have |
| nothing to do with SEH. |
| </para> |
| |
| <para> |
| Signal handlers in Wine run on their own stack. Each thread has |
| its own signal stack which resides 4k after the TEB. This is |
| important for a couple of reasons. Firstly, because there's no |
| guarantee that the app thread which triggered the signal has |
| enough stack space for the Wine signal handling code. In |
| Windows, if a thread hits the limits of its stack it triggers a |
| fault on the stack guard page. The language runtime can use this |
| to grow the stack if it wants to. |
| |
| <!-- fixme: is it really the language runtime that does this? i |
| can't find any code in Wine to reallocate the stack on |
| STATUS_GUARD_PAGE_VIOLATION --> |
| |
| However, because a guard page violation is just a regular |
| segfault to the kernel, that would lead to a nested signal |
| handler and that gets messy really quick so we disallow that in |
| Wine. Secondly, setting up the exception to throw requires |
| modifying the stack of the thread which triggered it, which is |
| quite hard to do when you're still running on it. |
| </para> |
| |
| <para> |
| Windows exceptions typically contain more information than the |
| Unix standard APIs provide. For instance, a |
| STATUS_ACCESS_VIOLATION exception (0xC0000005) structure |
| contains the faulting address, whereas a standard Unix SIGSEGV |
| just tells the app that it crashed. Usually this information is |
| passed as an extra parameter to the signal handler, however its |
| location and contents vary between kernels (BSD, Solaris, |
| etc). This data is provided in a SIGCONTEXT structure, and on |
| entry to the signal handler it contains the register state of |
| the CPU before the signal was sent. Modifying it will cause the |
| kernel to adjust the context before restarting the thread. |
| </para> |
| |
| </sect2> |
| |
| </sect1> |
| |
| </chapter> |
| |
| <!-- Keep this comment at the end of the file |
| Local variables: |
| mode: sgml |
| sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "") |
| End: |
| --> |
