965 lines
38 KiB
Plaintext
965 lines
38 KiB
Plaintext
<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 is 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 Wines 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 neeed 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 ingenius: 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 Wines
|
|
own implementations 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 Wines instead of the systems 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 to 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 when 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 threading 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 threading 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:
|
|
-->
|