COMPAT_PECOFF(8)        NetBSD System Manager's Manual        COMPAT_PECOFF(8)

NAME
     compat_pecoff -- setup procedure for running Win32 applications (a.k.a.
     PEACE)

DESCRIPTION
     NetBSD has partial support for running Win32 applications.  This manual
     page describes how to run Win32 (and hopefully WinCE in the future)
     applications on NetBSD.  Note that PE (Portable Executable) is a
     Microsoft extension to the COFF executable file format.

BRIEF INTRODUCTION TO THE WIN32 API
     The Win32 API is an application program interface (API) for 32-bit appli-
     cations for Microsoft Windows 9x/Me/NT/2000.  The Win32 API is provided
     via a set of core DLLs (Dynamically Linked Libraries), including
     KERNEL32.DLL, USER32.DLL and GDI32.DLL.

     The structure of these core DLLs and the interface between the operating
     system kernel and userland is implementation-dependent.  Each implementa-
     tion must provide its own core DLLs.  Therefore, these DLLs are different
     for Windows 98 and Windows 2000.

     KERNEL32.DLL is used by all Win32 applications; it provides basic kernel
     interface such as file access, process control, memory management etc.

     USER32.DLL is used by most Win32 applications; it provides basic userland
     functions such as GUI and messaging.

     GDI32.DLL provides functions to draw images and characters.

     SHELL32.DLL is the Windows shell support, including file association.

     COMCTL32.DLL and COMDLG32.DLL are GUI components which are commonly used
     in many applications.  WSOCK32.DLL provides the networking API.
     DDRAW.DLL, DSOUND.DLL, and DINPUT.DLL are for DirectX.

     Most other DLLs are compatible among all the implementations and there-
     fore can be shared.

NETBSD SUPPORT FOR THE WIN32 API
     NetBSD support for Win32 applications is developed by the PEACE Project,
     and is under active development.  Currently it can run some console
     applications including the Windows 2000 CMD.EXE as well as a small number
     of GUI applications.

     The PEACE system consists of three parts: the kernel part, the dynamic
     loader and the core DLLs.

     The kernel part provides loading and executing PE/COFF format executable
     binaries; i.e. it extends the execve(2) system call, just like other
     binary compatibility options.  It is activated by enabling the
     COMPAT_PECOFF kernel option (see options(4)), or enabling
     /usr/lkm/compat_pecoff.o and /usr/lkm/exec_pecoff.o with modload(8).

     The dynamic loader is the PE/COFF version of ld.so(1).  It reads the file
     header of the executable binary, and loads required DLLs.

     The core DLLs implement the actual Win32 API functions as described in
     the previous section.  Since the kernel part does not provide any addi-
     tional system calls and other kernel interface, all Win32 API functions
     are implemented on top of the existing NetBSD APIs (system calls and
     standard libraries such as libc and libX11).

PREPARING THE PEACE DYNAMIC LOADER AND CORE DLLS
     Development snapshots of the dynamic loader can be retrieved from
     http://sourceforge.net/project/showfiles.php?group_id=21711.  The file
     name of snapshot is peace-i386-ld.so.dll-*.gz, where `*' is replaced with
     the snapshot date.  Simply gunzip(1) the file and copy the resulting file
     to /usr/libexec/ld.so.dll.

     The core DLLs archives can also be retrieved from
     http://sourceforge.net/project/showfiles.php?group_id=21711 as
     peace-i386-sysdll-*.tgz and peace-i386-dll-*.tgz.  The dynamic loader
     searches for required DLLs from the following directories:
     1.   directories listed in the environment variable DLLPATH (separated by
          colons)
     2.   /usr/lib
     3.   the directory where the executable is located
     The core DLLs are required to be installed into /usr/lib, in order to use
     CMD.EXE (or another Win32 application) as the login shell.

     According to the development phase, some other PEACE-specific DLLs might
     be distributed separately.  Please check the announcements on the Web or
     the mailing list.

     Other DLLs can be stored in arbitrary directories specified by the envi-
     ronment variable DLLPATH.  To use Windows NT/2000 DLLs installed on a
     separate partition of the local disk directly for NetBSD, type:
           mount -t ntfs -o ro /dev/wd0h /nthd
           setenv DLLPATH /nthd/WINNT/SYSTEM32:/nthd/WINNT
     (assuming csh(1)).

SEE ALSO
     config(1), gunzip(1), ld.so(1), execve(2), options(4), modload(8),
     mount_ntfs(8), http://chiharu.hauN.org/peace/

HISTORY
     Kernel support for PE/COFF appeared in NetBSD 1.5.

AUTHORS
     Implementation of Win32 binary compatibility support for NetBSD was
     started by Masaru OKI.  The PEACE Project is founded by him to implement
     the enormous number of functions in the Win32/WinCE API.

BUGS
     -   Currently only the i386 platform is supported.
     -   Most functions in Win32 are missing.
     -   The dynamic loader and core DLLs are not provided in the standard
         distribution of NetBSD.  This is because a cross-compiler is required
         to build them.

NetBSD 5.0_STABLE               March 25, 2002               NetBSD 5.0_STABLE
