.\"	$NetBSD: compat_pecoff.8,v 1.12 2005/06/20 13:25:25 peter Exp $
.\"
.\" Copyright (c) 2000 The PEACE Project.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd March 25, 2002
.Dt COMPAT_PECOFF 8
.Os
.Sh NAME
.Nm compat_pecoff
.Nd setup procedure for running Win32 applications (a.k.a. PEACE)
.Sh DESCRIPTION
.Nx
has partial support for running
.Tn Win32
applications.
This manual page describes how to run
.Tn Win32
(and hopefully
.Tn WinCE
in the future) applications on
.Nx .
Note that PE (Portable Executable) is a Microsoft extension to the
.Tn COFF
executable file format.
.Sh BRIEF INTRODUCTION TO THE WIN32 API
The
.Tn Win32
API is an application program interface (API) for 32-bit
applications for Microsoft Windows 9x/Me/NT/2000.  The
.Tn Win32
API is provided
via a set of core DLLs (Dynamically Linked Libraries), including
.Pa KERNEL32.DLL ,
.Pa USER32.DLL
and
.Pa GDI32.DLL .
.Pp
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
.Tn "Windows 98"
and
.Tn "Windows 2000" .
.Pp
.Pa KERNEL32.DLL
is used by all
.Tn Win32
applications; it provides basic
kernel interface such as file access, process control, memory management etc.
.Pp
.Pa USER32.DLL
is used by most
.Tn Win32
applications; it provides basic
userland functions such as GUI and messaging.
.Pp
.Pa GDI32.DLL
provides functions to draw images and characters.
.Pp
.Pa SHELL32.DLL
is the Windows shell support, including file association.
.Pp
.Pa COMCTL32.DLL
and
.Pa COMDLG32.DLL
are GUI components which are commonly used in many applications.
.Pa WSOCK32.DLL
provides the networking API.
.Pa DDRAW.DLL ,
.Pa DSOUND.DLL ,
and
.Pa DINPUT.DLL
are for
.Tn DirectX .
.Pp
Most other DLLs are compatible among all the implementations and
therefore can be shared.
.Sh NETBSD SUPPORT FOR THE WIN32 API
.Nx
support for
.Tn Win32
applications is developed by the PEACE Project, and is
under active development.
Currently it can run some console applications including the
.Tn "Windows 2000"
.Pa CMD.EXE
as well as a small number of GUI applications.
.Pp
The PEACE system consists of three parts: the kernel part, the dynamic
loader and the core DLLs.
.Pp
The kernel part provides loading and executing
.Tn PE/COFF
format executable binaries; i.e. it extends the
.Xr execve 2
system call, just like other binary compatibility options.
It is activated by enabling the
.Dv COMPAT_PECOFF
kernel option (see
.Xr options 4 ) ,
or enabling
.Pa /usr/lkm/compat_pecoff.o
and
.Pa /usr/lkm/exec_pecoff.o
with
.Xr modload 8 .
.Pp
The dynamic loader is the
.Tn PE/COFF
version of
.Xr ld.so 1 .
It reads the file header of the executable binary, and
loads required DLLs.
.Pp
The core DLLs implement the actual
.Tn 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
.Tn Win32
API functions are implemented on top of the existing
.Nx
APIs (system calls and standard libraries such as
.Pa libc
and
.Pa libX11 ) .
.Sh PREPARING THE PEACE DYNAMIC LOADER AND CORE DLLS
Development snapshots of the dynamic loader can be retrieved from
.Pa http://sourceforge.net/project/showfiles.php?group_id=21711 .
The file name of snapshot is
.Pa peace-i386-ld.so.dll-*.gz ,
where `*' is replaced with the snapshot date.
Simply
.Xr gunzip 1
the file and copy the resulting file to
.Pa /usr/libexec/ld.so.dll .
.Pp
The core DLLs archives can also be retrieved from
.Pa http://sourceforge.net/project/showfiles.php?group_id=21711
as
.Pa peace-i386-sysdll-*.tgz
and
.Pa peace-i386-dll-*.tgz .
The dynamic loader searches for required DLLs from the following directories:
.Bl -enum -compact
.It
directories listed in the environment variable
.Ev DLLPATH
(separated by colons)
.It
.Pa /usr/lib
.It
the directory where the executable is located
.El
The core DLLs are required to be installed into
.Pa /usr/lib ,
in order to use
.Pa CMD.EXE
(or another
.Tn Win32
application) as the login shell.
.Pp
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.
.Pp
Other DLLs can be stored in arbitrary directories specified by the
environment variable
.Ev DLLPATH .
To use
.Tn "Windows NT/2000"
DLLs installed on a separate partition of the local disk directly
for
.Nx ,
type:
.Bd -literal -compact -offset indent
mount -t ntfs -o ro /dev/wd0h /nthd
setenv DLLPATH /nthd/WINNT/SYSTEM32:/nthd/WINNT
.Ed
(assuming
.Xr csh 1 ) .
.Sh SEE ALSO
.Xr config 1 ,
.Xr gunzip 1 ,
.Xr ld.so 1 ,
.Xr execve 2 ,
.Xr options 4 ,
.Xr modload 8 ,
.Xr mount_ntfs 8 ,
.Pa http://chiharu.hauN.org/peace/
.Sh HISTORY
Kernel support for
.Tn PE/COFF
appeared in
.Nx 1.5 .
.Sh AUTHORS
Implementation of
.Tn Win32
binary compatibility support for
.Nx
was started by Masaru OKI.
The PEACE Project is founded by him to implement the enormous number
of functions in the
.Tn Win32/WinCE
API.
.Sh BUGS
.Bl -hyphen -compact
.It
Currently only the i386 platform is supported.
.It
Most functions in
.Tn Win32
are missing.
.It
The dynamic loader and core DLLs are not provided in the standard
distribution of
.Nx .
This is because a cross-compiler is required to build them.
.El