March 25, 2002 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 NetBSD1.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.