wine/documentation/winedev-kernel.sgml

  <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:
-->