wine/documentation/winedev-kernel.sgml
2004-11-04 21:06:14 +00:00

964 lines
38 KiB
Text

<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 &amp; user backend</entry>
<entry>Wineconsole &amp; 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:
-->