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 applications 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 implementation 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 therefore 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 additional 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 environment 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.