NetBSD/share/man/man8/compat_pecoff.8

.\"	$NetBSD: compat_pecoff.8,v 1.1 2000/07/17 14:39:35 minoura 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 July 17, 2000
.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 Win32 application.
This manual page describes how to run Win32 (and hopefully WinCE
in the future) applications on
.Nx .
Note that PE (Portable Executable) is Microsoft extention to COFF
executable file format.

.Sh BRIEF INTRODUCTION TO WIN32 API
Win32 API is an application program interface (API) for 32-bit
applications for Microsoft Windows 9x/NT/2000.  Win32 API is provided
as a set of core DLLs (Dynamically Linked Libraries), including KERNEL32.DLL,
USER32.DLL and 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 this via the core DLLs;
for example, they are different between Windows 98 and Windows 2000.
.Pp
KERNEL32.DLL is used by all Win32 applications; it provides basic
kernel interface such as file access, process control, memory management etc.
.Pp
USER32.DLL is used by most Win32 applications; it provides basic
userland functions such as GUI and messaging.
.Pp
GDI32.DLL provides functions to draw images and characters.
.Pp
SHELL32.DLL is the Windows shell support, including file association.
.Pp
COMCTL32.DLL and COMDLG.32.DLL are GUI components which are commonly
used in many applications.  WSOCK32.DLL provides networking API.
DDRAW.DLL is for DirectDraw.
.Pp
Most of other DLLs are compatible among all the implementations and
therefore can be shared.

.Sh NETBSD SUPPORT FOR WIN32 API
.Nx
support for Win32 application is developed by the PEACE Project, and is
under active development.
Currently it can run some console applications including Windows 2000
CMD.EXE, and very few GUI applications.
.Pp
PEACE system consists of three parts; kernel part, dynamic loader and
core DLLs.
.Pp
The kernel part provides loading and executing PE/COFF format 
executable binaries, i.e. it extends
.Xr execve 2
system call.
It is activated by enabling
.Dv COMPAT_PECOFF
option.
.Pp
The dynamic loader is 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 actual Win32 API functions 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
.Nx
APIs (system calls and standard libraries such as libc and libX11).

.Sh PREPARING PEACE DYNAMIC LOADER AND CORE DLLS
Development snapshot of the dynamic loader can be retrieved from 
.Pa http://chiharu.haun.org/peace/dist/peace-i386-ld.so.dll-*.gz ,
where `*' is replaced with the snapshot date.
Simply
.Xr gunzip 8
the file and copy the resultant as
.Pa /usr/libexec/ld.so.dll .
.Pp
Core DLLs can also be retrieved from
.Pa http://chiharu.haun.org/peace/dist/peace-i386-dll-*.tgz .
The dynamic linker searches required DLLs from the following directories;
.Bl -enum -compact
.It
.Pa /usr/lib
.It
Directories listed in the environment variable DLLPATH (separated by
colons)
.It
Same directory where the executable is located
.El
The core DLLs are required to be installed into
.Pa /usr/lib ,
in order that CMD.EXE (or another Win32 application) is used
as the login shell.
.Pp
Other DLLs can be stored into arbitrary directory.  To use 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 csh).

.Sh SEE ALSO
.Xr config 8 , Xr options 4 ,
.Xr execve 3 , Xr ld.so 1 ,
.Xr mount_ntfs 8 , Xr gunzip 1

.Sh HISTORY
Kernel support for PE/COFF appeared in
.Nx 1.5 .

.Sh AUTHOR
The kernel part is written by Masaru Oki, based on 
.Nx
COFF loader.  The userland functions are implemented by Masaru Oki and
the PEACE Project.

.Sh BUGS
.Bl -hyphen -compact
.It
Currently only i386 platform is supported.
.It
Many functions in Win32 are missing.
.It
Dynamic loader and core DLLs are not provided in the standard
distribution of
.Nx .
This is because the cross-compiler is required to build them.
.El