share/man/man8/compat_pecoff.8

   1 .\"     $NetBSD: compat_pecoff.8,v 1.12 2005/06/20 13:25:25 peter Exp $
   2 .\"
   3 .\" Copyright (c) 2000 The PEACE Project.
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. The name of the author may not be used to endorse or promote products
  15 .\"    derived from this software without specific prior written permission.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  18 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  19 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  20 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  21 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  22 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  23 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  24 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  25 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  26 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27 .\"
  28 .Dd March 25, 2002
  29 .Dt COMPAT_PECOFF 8
  30 .Os
  31 .Sh NAME
  32 .Nm compat_pecoff
  33 .Nd setup procedure for running Win32 applications (a.k.a. PEACE)
  34 .Sh DESCRIPTION
  35 .Nx
  36 has partial support for running
  37 .Tn Win32
  38 applications.
  39 This manual page describes how to run
  40 .Tn Win32
  41 (and hopefully
  42 .Tn WinCE
  43 in the future) applications on
  44 .Nx .
  45 Note that PE (Portable Executable) is a Microsoft extension to the
  46 .Tn COFF
  47 executable file format.
  48 .Sh BRIEF INTRODUCTION TO THE WIN32 API
  49 The
  50 .Tn Win32
  51 API is an application program interface (API) for 32-bit
  52 applications for Microsoft Windows 9x/Me/NT/2000.  The
  53 .Tn Win32
  54 API is provided
  55 via a set of core DLLs (Dynamically Linked Libraries), including
  56 .Pa KERNEL32.DLL ,
  57 .Pa USER32.DLL
  58 and
  59 .Pa GDI32.DLL .
  60 .Pp
  61 The structure of these core DLLs and the interface between the
  62 operating system kernel and userland is implementation-dependent.
  63 Each implementation must provide its own core DLLs.
  64 Therefore, these DLLs are different for
  65 .Tn "Windows 98"
  66 and
  67 .Tn "Windows 2000" .
  68 .Pp
  69 .Pa KERNEL32.DLL
  70 is used by all
  71 .Tn Win32
  72 applications; it provides basic
  73 kernel interface such as file access, process control, memory management etc.
  74 .Pp
  75 .Pa USER32.DLL
  76 is used by most
  77 .Tn Win32
  78 applications; it provides basic
  79 userland functions such as GUI and messaging.
  80 .Pp
  81 .Pa GDI32.DLL
  82 provides functions to draw images and characters.
  83 .Pp
  84 .Pa SHELL32.DLL
  85 is the Windows shell support, including file association.
  86 .Pp
  87 .Pa COMCTL32.DLL
  88 and
  89 .Pa COMDLG32.DLL
  90 are GUI components which are commonly used in many applications.
  91 .Pa WSOCK32.DLL
  92 provides the networking API.
  93 .Pa DDRAW.DLL ,
  94 .Pa DSOUND.DLL ,
  95 and
  96 .Pa DINPUT.DLL
  97 are for
  98 .Tn DirectX .
  99 .Pp
 100 Most other DLLs are compatible among all the implementations and
 101 therefore can be shared.
 102 .Sh NETBSD SUPPORT FOR THE WIN32 API
 103 .Nx
 104 support for
 105 .Tn Win32
 106 applications is developed by the PEACE Project, and is
 107 under active development.
 108 Currently it can run some console applications including the
 109 .Tn "Windows 2000"
 110 .Pa CMD.EXE
 111 as well as a small number of GUI applications.
 112 .Pp
 113 The PEACE system consists of three parts: the kernel part, the dynamic
 114 loader and the core DLLs.
 115 .Pp
 116 The kernel part provides loading and executing
 117 .Tn PE/COFF
 118 format executable binaries; i.e. it extends the
 119 .Xr execve 2
 120 system call, just like other binary compatibility options.
 121 It is activated by enabling the
 122 .Dv COMPAT_PECOFF
 123 kernel option (see
 124 .Xr options 4 ) .
 125 The dynamic loader is the
 126 .Tn PE/COFF
 127 version of
 128 .Xr ld.so 1 .
 129 It reads the file header of the executable binary, and
 130 loads required DLLs.
 131 .Pp
 132 The core DLLs implement the actual
 133 .Tn Win32
 134 API functions as described in the
 135 previous section.  Since the kernel part does not provide
 136 any additional system calls and other kernel interface,
 137 all
 138 .Tn Win32
 139 API functions are implemented on top of the existing
 140 .Nx
 141 APIs (system calls and standard libraries such as
 142 .Pa libc
 143 and
 144 .Pa libX11 ) .
 145 .Sh PREPARING THE PEACE DYNAMIC LOADER AND CORE DLLS
 146 Development snapshots of the dynamic loader can be retrieved from
 147 .Pa http://sourceforge.net/project/showfiles.php?group_id=21711 .
 148 The file name of snapshot is
 149 .Pa peace-i386-ld.so.dll-*.gz ,
 150 where `*' is replaced with the snapshot date.
 151 Simply
 152 .Xr gunzip 1
 153 the file and copy the resulting file to
 154 .Pa /usr/libexec/ld.so.dll .
 155 .Pp
 156 The core DLLs archives can also be retrieved from
 157 .Pa http://sourceforge.net/project/showfiles.php?group_id=21711
 158 as
 159 .Pa peace-i386-sysdll-*.tgz
 160 and
 161 .Pa peace-i386-dll-*.tgz .
 162 The dynamic loader searches for required DLLs from the following directories:
 163 .Bl -enum -compact
 164 .It
 165 directories listed in the environment variable
 166 .Ev DLLPATH
 167 (separated by colons)
 168 .It
 169 .Pa /usr/lib
 170 .It
 171 the directory where the executable is located
 172 .El
 173 The core DLLs are required to be installed into
 174 .Pa /usr/lib ,
 175 in order to use
 176 .Pa CMD.EXE
 177 (or another
 178 .Tn Win32
 179 application) as the login shell.
 180 .Pp
 181 According to the development phase, some other PEACE-specific DLLs
 182 might be distributed separately.  Please check the announcements
 183 on the Web or the mailing list.
 184 .Pp
 185 Other DLLs can be stored in arbitrary directories specified by the
 186 environment variable
 187 .Ev DLLPATH .
 188 To use
 189 .Tn "Windows NT/2000"
 190 DLLs installed on a separate partition of the local disk directly
 191 for
 192 .Nx ,
 193 type:
 194 .Bd -literal -compact -offset indent
 195 mount -t ntfs -o ro /dev/wd0h /nthd
 196 setenv DLLPATH /nthd/WINNT/SYSTEM32:/nthd/WINNT
 197 .Ed
 198 (assuming
 199 .Xr csh 1 ) .
 200 .Sh SEE ALSO
 201 .Xr config 1 ,
 202 .Xr gunzip 1 ,
 203 .Xr ld.so 1 ,
 204 .Xr execve 2 ,
 205 .Xr options 4 ,
 206 .Xr modload 8 ,
 207 .Xr mount_ntfs 8 ,
 208 .Pa http://chiharu.hauN.org/peace/
 209 .Sh HISTORY
 210 Kernel support for
 211 .Tn PE/COFF
 212 appeared in
 213 .Nx 1.5 .
 214 .Sh AUTHORS
 215 Implementation of
 216 .Tn Win32
 217 binary compatibility support for
 218 .Nx
 219 was started by Masaru OKI.
 220 The PEACE Project is founded by him to implement the enormous number
 221 of functions in the
 222 .Tn Win32/WinCE
 223 API.
 224 .Sh BUGS
 225 .Bl -hyphen -compact
 226 .It
 227 Currently only the i386 platform is supported.
 228 .It
 229 Most functions in
 230 .Tn Win32
 231 are missing.
 232 .It
 233 The dynamic loader and core DLLs are not provided in the standard
 234 distribution of
 235 .Nx .
 236 This is because a cross-compiler is required to build them.
 237 .El