/usr/share/doc/wine-doc/html/winedev/c2768.htm

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Kernel modules</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="Wine Developer's Guide"
HREF="index.htm"><LINK
REL="UP"
TITLE="Wine Architecture"
HREF="part-two.htm"><LINK
REL="PREVIOUS"
TITLE="Wine architecture"
HREF="x2584.htm"><LINK
REL="NEXT"
TITLE="Detailed memory management"
HREF="x2853.htm"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="winedoc.css"></HEAD
><BODY
CLASS="CHAPTER"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>Wine Developer's Guide</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="x2584.htm"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="x2853.htm"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="CHAPTER"
><H1
><A
NAME="AEN2768"
></A
>Chapter 8. Kernel modules</H1
><DIV
CLASS="TOC"
><DL
><DT
><B
>Table of Contents</B
></DT
><DT
>8.1. <A
HREF="c2768.htm#INITIALIZATION"
>The Wine initialization process</A
></DT
><DT
>8.2. <A
HREF="x2853.htm"
>Detailed memory management</A
></DT
><DT
>8.3. <A
HREF="x2884.htm"
>Multi-processing in Wine</A
></DT
><DT
>8.4. <A
HREF="threading.htm"
>Multi-threading in Wine</A
></DT
><DT
>8.5. <A
HREF="seh.htm"
>Structured Exception Handling</A
></DT
><DT
>8.6. <A
HREF="x3062.htm"
>File management</A
></DT
><DT
>8.7. <A
HREF="ntdll.htm"
><TT
CLASS="FILENAME"
>NTDLL</TT
> module</A
></DT
><DT
>8.8. <A
HREF="x3500.htm"
><TT
CLASS="FILENAME"
>KERNEL32</TT
> Module</A
></DT
></DL
></DIV
><P
>      This section covers the kernel modules.  As already stated, Wine
      implements the NT architecture, hence provides <TT
CLASS="FILENAME"
>NTDLL</TT
>
      for the core kernel functions, and <TT
CLASS="FILENAME"
>KERNEL32</TT
>, which is
      the implementation of the basis of the Win32 subsystem, on top of
      <TT
CLASS="FILENAME"
>NTDLL</TT
>.
    </P
><P
>      This chapter is made of two types of material (depending of their point of
      view).  Some items will be tackled from a global point of view and then,
      when needed, explaining the split of work between
      <TT
CLASS="FILENAME"
>NTDLL</TT
> and <TT
CLASS="FILENAME"
>KERNEL32</TT
>; some others
      will be tackled from a DLL point of view (<TT
CLASS="FILENAME"
>NTDLL</TT
> or
      <TT
CLASS="FILENAME"
>KERNEL32</TT
>).  The choice is made so that the output is
      more readable and understantable.  At least, that's the intend (sigh).
    </P
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="INITIALIZATION"
>8.1. The Wine initialization process</A
></H1
><P
>	Wine has a rather complex startup procedure, so unlike many programs the
	best place to begin exploring the code-base is
	<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>not</I
></SPAN
> in fact at the	<CODE
CLASS="FUNCTION"
>main()</CODE
>
	function but instead at some of the  more straightforward DLLs that
	exist on the periphery such as MSI, the widget library (in
	<TT
CLASS="FILENAME"
>USER</TT
> and <TT
CLASS="FILENAME"
>COMCTL32</TT
>) etc. The
	purpose of this section is to document and explain how Wine starts up
	from the moment the user runs "<B
CLASS="COMMAND"
>wine myprogram.exe</B
>" to
	the point at which <TT
CLASS="FILENAME"
>myprogram</TT
> gets control.
      </P
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN2788"
>8.1.1. First Steps</A
></H2
><P
>	  The actual wine binary that the user runs does not do very much, in
	  fact it is only responsible for checking the threading model in use
	  (NPTL vs LinuxThreads) and then invoking a new binary which performs
	  the next stage in the startup sequence. See the beginning of this
	  chapter for more information on this check and why it's necessary. You
	  can find this code in <TT
CLASS="FILENAME"
>loader/glibc.c</TT
>. The result
	  of this check is an exec of either <B
CLASS="COMMAND"
>wine-pthread</B
> or
	  <B
CLASS="COMMAND"
>wine-kthread</B
>, potentially (on Linux) via the
	  <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>preloader</I
></SPAN
>. 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.
	</P
><P
>	  The Wine preloader is found in
	  <TT
CLASS="FILENAME"
>loader/preloader.c</TT
>, 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
	  <B
CLASS="COMMAND"
>wine-kthread</B
> or <B
CLASS="COMMAND"
>wine-pthread</B
>)
	  along with the arguments the user passed in from the command line. The
	  preloader is an unusual program: it does not have a
	  <CODE
CLASS="FUNCTION"
>main()</CODE
> function. In standard ELF applications,
	  the entry point is actually at a symbol named
	  <CODE
CLASS="FUNCTION"
>_start()</CODE
>: this is provided  by the
	  standard <B
CLASS="COMMAND"
>gcc</B
> infrastructure and normally jumps to
	  <CODE
CLASS="FUNCTION"
>__libc_start_main()</CODE
> which initializes glibc before
	  passing control to the main function as defined by the programmer.
	</P
><P
>	  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 <CODE
CLASS="FUNCTION"
>malloc()</CODE
> will initialize a heap arena
	  which modifies the VM mappings. Finally, glibc does not return to
	  <CODE
CLASS="FUNCTION"
>_start()</CODE
> at any point, so by reusing it we avoid
	  the need to recreate the ELF bootstrap stack
	  (<CODE
CLASS="VARNAME"
>env</CODE
>, <CODE
CLASS="VARNAME"
>argv</CODE
>, auxiliary array etc).
	</P
><P
>	  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 
	  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
	  <B
CLASS="COMMAND"
>wine-[pk]thread</B
> and
	  <TT
CLASS="FILENAME"
>ld-linux.so.2</TT
> off disk, linking them together,
	  then starting the dynamic linking process.
	</P
><P
>	  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.
	</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN2812"
>8.1.2. Starting the emulator</A
></H2
><P
>	  The process of starting up the emulator itself is mostly one of
	  chaining through various initializer functions defined in the core
	  libraries and DLLs: <TT
CLASS="FILENAME"
>libwine</TT
>, then
	  <TT
CLASS="FILENAME"
>NTDLL</TT
>, then <TT
CLASS="FILENAME"
>KERNEL32</TT
>.
	</P
><P
>	  Both the <B
CLASS="COMMAND"
>wine-pthread</B
> and
	  <B
CLASS="COMMAND"
>wine-kthread</B
> binaries share a common
	  <CODE
CLASS="FUNCTION"
>main()</CODE
> function, defined in
	  <TT
CLASS="FILENAME"
>loader/main.c</TT
>, so no matter which binary is
	  selected after the preloader has run we start here. This passes the
	  information provided by the preloader into
	  <TT
CLASS="FILENAME"
>libwine</TT
> and then calls
	  <CODE
CLASS="FUNCTION"
>wine_init()</CODE
>, defined in
	  <TT
CLASS="FILENAME"
>libs/wine/loader.c</TT
>. This is where the emulation
	  really starts: 
	  <CODE
CLASS="FUNCTION"
>wine_init()</CODE
> can, with the correct preparation,
	  be called from programs other than the wine loader itself.
	</P
><P
>	  <CODE
CLASS="FUNCTION"
>wine_init()</CODE
> 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 <TT
CLASS="FILENAME"
>NTDLL</TT
> - the core
	  of both Wine and the Windows NT series - and jumping to the
	  <CODE
CLASS="FUNCTION"
>__wine_process_init()</CODE
> function defined
	  in <TT
CLASS="FILENAME"
>dlls/ntdll/loader.c</TT
>
	</P
><P
>	  This function is responsible for initializing the primary Win32
	  environment. In <CODE
CLASS="FUNCTION"
>thread_init()</CODE
>, it sets up the
	  TEB, the <B
CLASS="COMMAND"
>wineserver</B
> connection for the main thread
	  and the process heap. See the beginning of this chapter for more
	  information on this.

	</P
><P
>	  Finally, it loads and jumps to
	  <CODE
CLASS="FUNCTION"
>__wine_kernel_init()</CODE
> in
	  <TT
CLASS="FILENAME"
>KERNEL32.DLL</TT
>: this is defined in
	  <TT
CLASS="FILENAME"
>dlls/kernel32/process.c</TT
>. This is where the bulk
	  of the work is done. The <TT
CLASS="FILENAME"
>KERNEL32</TT
> 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 <CODE
CLASS="STRUCTNAME"
>STARTUPINFO</CODE
> block that can be
	  passed into <CODE
CLASS="FUNCTION"
>CreateProcess</CODE
> specifying various
	  things like how the first window should be displayed: this is sent to
	  the new process via the <B
CLASS="COMMAND"
>wineserver</B
>.
	</P
><P
>	  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
	  <CODE
CLASS="FUNCTION"
>__wine_kernel_init()</CODE
>. This function ends with the
	  new process stack being initialized, and start_process being called on
	  the new stack. Nearly there!
	</P
><P
>	  The final element of initializing Wine is starting the newly loaded
	  program itself. <CODE
CLASS="FUNCTION"
>start_process()</CODE
> sets up the SEH
	  backstop handler, calls <CODE
CLASS="FUNCTION"
>LdrInitializeThunk()</CODE
>
	  which performs the last part of the process initialization (such as
	  performing relocations and calling the <CODE
CLASS="FUNCTION"
>DllMain()</CODE
>
	  with <CODE
CLASS="CONSTANT"
>PROCESS_ATTACH</CODE
>), grabs the entry point of
	  the executable and then on this line:
	</P
><PRE
CLASS="PROGRAMLISTING"
>ExitProcess( entry( peb ) );
	</PRE
><P
>	  ... 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 <CODE
CLASS="FUNCTION"
>ExitProcess()</CODE
> API
	  will be used to initialize a graceful shutdown.
	</P
></DIV
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="x2584.htm"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.htm"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="x2853.htm"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Wine architecture</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="part-two.htm"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Detailed memory management</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
wine-doc 1.0.0-1 / usr / share / doc / wine-doc / html / winedev / c2768.htm
