| 1 | 
 | 
|---|
| 2 |                 O D I N  Public Alpha 5 - 1999/11/16
 | 
|---|
| 3 |                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 | 
|---|
| 4 | 
 | 
|---|
| 5 | WANTED: We are still looking for talented developers that want to
 | 
|---|
| 6 |         contribute! Please take a look at the last section!
 | 
|---|
| 7 | 
 | 
|---|
| 8 | NOTE:   LICENSE.TXT describes the Project Odin Software License.
 | 
|---|
| 9 | 
 | 
|---|
| 10 | 
 | 
|---|
| 11 | Project Odin Information
 | 
|---|
| 12 | ========================
 | 
|---|
| 13 | 
 | 
|---|
| 14 | 1.0 Introduction
 | 
|---|
| 15 | ----------------
 | 
|---|
| 16 | 
 | 
|---|
| 17 | This readme is intended for end users that have downloaded the
 | 
|---|
| 18 | latest public alpha release and want to give it a try. For more
 | 
|---|
| 19 | information, be sure to regularly check http://www.netlabs.org/odin.
 | 
|---|
| 20 | 
 | 
|---|
| 21 | 1.1 Purpose
 | 
|---|
| 22 | -----------
 | 
|---|
| 23 | 
 | 
|---|
| 24 | Odin is a free Open Source project with the goal to eventually
 | 
|---|
| 25 | provide a fully working Win32 (Win 95/98/NT/2000) runtime environment,
 | 
|---|
| 26 | making it possible to run your favorite Windows programs under OS/2,
 | 
|---|
| 27 | as if they were native OS/2 programs. The second goal of Odin is to
 | 
|---|
| 28 | provide the full Win32 application programming interface (API) so
 | 
|---|
| 29 | that it is possible to build OS/2 programs using Windows source
 | 
|---|
| 30 | code. This is also refered to as Odin32 whereas Odin is the name
 | 
|---|
| 31 | of the Win32 binary emulator.
 | 
|---|
| 32 | 
 | 
|---|
| 33 | 1.2 Current Status
 | 
|---|
| 34 | ------------------
 | 
|---|
| 35 | 
 | 
|---|
| 36 | Odin is still in the early alpha state so that it is very far from
 | 
|---|
| 37 | being widely usable. Most programs will not work or show many
 | 
|---|
| 38 | problems. Even though it is not usable for most programs, we have
 | 
|---|
| 39 | decided to do a public release in order to show how much progress
 | 
|---|
| 40 | the project has been made. A second goal is to attract more developers
 | 
|---|
| 41 | in order to speedup development. Our job includes rewriting most
 | 
|---|
| 42 | parts of Windows 95/NT without having the original source code so
 | 
|---|
| 43 | the more developers we have the more progess will be seen. The
 | 
|---|
| 44 | last public release (Alpha 0.004) has been in 1997 and the project
 | 
|---|
| 45 | has changed much since then. Everything is free and Open Source now
 | 
|---|
| 46 | and the base architecture has been improved quite a lot. We are now
 | 
|---|
| 47 | in a position where we can expect the first bigger applications to
 | 
|---|
| 48 | run well and to make much more visible progress.
 | 
|---|
| 49 | 
 | 
|---|
| 50 | 1.3 Changes and additions in alpha 5
 | 
|---|
| 51 | ------------------------------------
 | 
|---|
| 52 | - Removed Open32 dependacy in User32 code: windows, dialogs, buttons and
 | 
|---|
| 53 |   other controls creation and manipulation is now implemented fully in Odin32.
 | 
|---|
| 54 |   Applications have Win32 look: Win32 specific controls are also supported
 | 
|---|
| 55 |   (Open32 is still a requirement as other Odin32 functions use it!)
 | 
|---|
| 56 | - New and improved PE2LX converter
 | 
|---|
| 57 | - New Portable Executable Loader (PE) that overcomes some differences
 | 
|---|
| 58 |   between OS/2 and Win32 memory models (this does not include 512MB
 | 
|---|
| 59 |   per-process memory limitation in OS/2, you still need the Aurora-level
 | 
|---|
| 60 |   kernel for that)
 | 
|---|
| 61 | - New WIN32K32k.SYS driver that automates loading of Win32 binaries (no
 | 
|---|
| 62 |   conversion or invocation through PE.EXE loader is needed), now
 | 
|---|
| 63 |   compatible with WSeB (Aurora) and no longer dependant of code under
 | 
|---|
| 64 |   GNU license
 | 
|---|
| 65 | - Wine ports of common controls (comctl32), shell extensions (shell32) and
 | 
|---|
| 66 |   OLE
 | 
|---|
| 67 | - Full implementation of memory mapped files
 | 
|---|
| 68 | - Joystick support (winmm)
 | 
|---|
| 69 | - Direct Input (DirectX keyboard & mouse) added (Wine Port)
 | 
|---|
| 70 | - Rewrite of DirectDraw. More complete implementation.
 | 
|---|
| 71 | - Couple of (not core Win32 API, but often used) new DLLs (winasp32, lz32,
 | 
|---|
| 72 |   avifil32...), so users don't have to have Windows license at all to run
 | 
|---|
| 73 |   Windows programs
 | 
|---|
| 74 | - Many new API functions implemented or ported from Wine, allows
 | 
|---|
| 75 |   developers to port Win32 apps directly to OS/2 with little to no rewriting
 | 
|---|
| 76 | - Many bugfixes and enhancements
 | 
|---|
| 77 | - Many new programs that load and/or work with Odin
 | 
|---|
| 78 | - Full source code available
 | 
|---|
| 79 | 
 | 
|---|
| 80 | 
 | 
|---|
| 81 | 2.0 Installing Odin (UPDATED)
 | 
|---|
| 82 | -----------------------------
 | 
|---|
| 83 | 
 | 
|---|
| 84 | Daily builds of Odin are available at ftp://ftp.os2.org/odin/daily.
 | 
|---|
| 85 | For people that do not have a suitable development setup for ODIN,
 | 
|---|
| 86 | we provide the latest binary code that way.
 | 
|---|
| 87 | 
 | 
|---|
| 88 | Odin daily builds are now also distributed as WarpIn archives.
 | 
|---|
| 89 | WarpIn is a generic OS/2 installation application that can be
 | 
|---|
| 90 | downloaded from warpin.netlabs.org.
 | 
|---|
| 91 | 
 | 
|---|
| 92 | Requirements for installing Odin:
 | 
|---|
| 93 | - You must install Odin on a partition that supports long filenames (e.g.
 | 
|---|
| 94 |   HPFS/JFS). Odin will not work on FAT!
 | 
|---|
| 95 | - OS/2 Warp 4, eComStation or Warp Server for e-Business (WSeB)
 | 
|---|
| 96 |   When using Warp 4, we recommend you apply fixpack 13 or higher.
 | 
|---|
| 97 |   * Warp 3 is not officially supported, but is reported to work by using
 | 
|---|
| 98 |     Warp 4 open32 dlls and patching them.
 | 
|---|
| 99 | 
 | 
|---|
| 100 | Manual installation without WarpIn is not recommended. If you don't use WarpIn,
 | 
|---|
| 101 | then you *must* execute odininst.exe in the Odin system32 directory. (the first
 | 
|---|
| 102 | time Odin is installed or when the ChangeLog mentions fixes/changes in the
 | 
|---|
| 103 | installer)
 | 
|---|
| 104 | 
 | 
|---|
| 105 | NOTE: You must install Odin on a partition that supports long filenames (e.g.
 | 
|---|
| 106 |       HPFS/JFS). Odin will not work on FAT!
 | 
|---|
| 107 | 
 | 
|---|
| 108 | To install Odin, run warpin.exe with the name of the daily build archive
 | 
|---|
| 109 | as parameter.
 | 
|---|
| 110 | Follow the instructions to complete the installation.
 | 
|---|
| 111 | The Odin installation consists of:
 | 
|---|
| 112 |   - creating an Odin directory and copying the included files to
 | 
|---|
| 113 |     x:\odin and x:\odin\system32
 | 
|---|
| 114 |   - creating empty directories in x:\odin (to create a similar directory
 | 
|---|
| 115 |     structure as found in Windows)
 | 
|---|
| 116 |   - creating a basic registry for executing win32 applications in OS/2
 | 
|---|
| 117 |   - adds x:\odin\system32 to the path and libpath settings in your config.sys
 | 
|---|
| 118 | 
 | 
|---|
| 119 | NOTE: You MUST install Odin at least once using WarpIn (unless you know
 | 
|---|
| 120 |       what you're doing). Afterwards you can use the daily build zipfiles
 | 
|---|
| 121 |       to upgrade to a newer version.
 | 
|---|
| 122 | 
 | 
|---|
| 123 | To run DirectDraw games or Quake 2 in Voodoo mode, you must install Holger
 | 
|---|
| 124 | Veit's XFree86/2 support driver (XF86SUP.SYS).
 | 
|---|
| 125 | Visit http://ais.gmd.de/~veit/os2/xf86sup.html to download it.
 | 
|---|
| 126 | 
 | 
|---|
| 127 | NOTE: The Glide and 3Dfx Opengl dll are no longer part of the basic Odin
 | 
|---|
| 128 |       installation package. It's available as opengl3dfx.zip on ftp.os2.org.
 | 
|---|
| 129 | 
 | 
|---|
| 130 | 
 | 
|---|
| 131 | 2.0.1 Log files
 | 
|---|
| 132 | ---------------
 | 
|---|
| 133 | The alpha 5 binaries and daily build zipfiles can generate logfiles to show
 | 
|---|
| 134 | what a win32 application is doing. This can be very useful to determine
 | 
|---|
| 135 | why certain applications don't run correctly.
 | 
|---|
| 136 | 
 | 
|---|
| 137 | The major disadvantage of loggging is the overhead. Therefor it has been
 | 
|---|
| 138 | disabled by default in the alpha 5 release and daily builds.
 | 
|---|
| 139 | To enable logging set the environment variable WIN32LOG_ENABLED:
 | 
|---|
| 140 |    SET WIN32LOG_ENABLED=1
 | 
|---|
| 141 | 
 | 
|---|
| 142 | To disable logging again, you must clear this variable:
 | 
|---|
| 143 |    SET WIN32LOG_ENABLED=
 | 
|---|
| 144 | 
 | 
|---|
| 145 | 
 | 
|---|
| 146 | 2.1 Using Odin to run your Windows applications
 | 
|---|
| 147 | -----------------------------------------------
 | 
|---|
| 148 | 
 | 
|---|
| 149 | Odin still has several ways to execute Win32 programs.
 | 
|---|
| 150 | 
 | 
|---|
| 151 | 
 | 
|---|
| 152 | 2.2 The Ring3 Win32 Loader (PE.EXE)
 | 
|---|
| 153 | ----------------------------------
 | 
|---|
| 154 | 
 | 
|---|
| 155 | This is the new and also recommended method for loading programs.
 | 
|---|
| 156 | Unlike with the previous alphas, it is not required to convert or
 | 
|---|
| 157 | anyhow change the original files. Installing a device driver is
 | 
|---|
| 158 | also not necessary. Be sure to put the Odin binary directory into
 | 
|---|
| 159 | both the PATH and LIBPATH (alternatively you can use a batch file
 | 
|---|
| 160 | with SET PATH=C:\Odin;%PATH% and SET BEGINLIBPATH=C:\Odin;)
 | 
|---|
| 161 | and then call pe.exe winprog.exe param1 param2 ... If you wanted
 | 
|---|
| 162 | to start the Windows calculator, you would type
 | 
|---|
| 163 | 
 | 
|---|
| 164 | pe calc
 | 
|---|
| 165 | 
 | 
|---|
| 166 | The PE (Portable Executable, the Win32 executable format) loader
 | 
|---|
| 167 | will now try to load the application into memory and execute it.
 | 
|---|
| 168 | This will either work or fail with a loader message. If you get
 | 
|---|
| 169 | such a loader message, it is very likely that a required DLL is
 | 
|---|
| 170 | missing. To correct that problem, take a look at pe_0.log (or
 | 
|---|
| 171 | pe_1.log for the second program running at this time and so on).
 | 
|---|
| 172 | At the bottom of the file you will see the DLLs and the functions
 | 
|---|
| 173 | that the loader imports. It will tell you if it couldn't find a
 | 
|---|
| 174 | DLL and you can correct the problem and try it again.
 | 
|---|
| 175 | 
 | 
|---|
| 176 | 
 | 
|---|
| 177 | 2.2.1 PE loader issues
 | 
|---|
| 178 | ----------------------
 | 
|---|
| 179 | 
 | 
|---|
| 180 | As the PE loader will create the process and load the program,
 | 
|---|
| 181 | a process utility such as pstat will always show PE.EXE as the
 | 
|---|
| 182 | executable file.
 | 
|---|
| 183 | It is also possible that a certain Win32 application becomes
 | 
|---|
| 184 | a zombie (that is when it does certain things the OS/2 kernel
 | 
|---|
| 185 | cannot recover such as die when waiting on a semaphore). Then
 | 
|---|
| 186 | it will not be possible to kill the application - only a system
 | 
|---|
| 187 | restart will help.
 | 
|---|
| 188 | Certain programs do use fixed memory addresses where they need
 | 
|---|
| 189 | to be loaded (i.e. they won't use fixups). You can notice this
 | 
|---|
| 190 | at the top of the loader log file (pe_0.log). If the fixed address
 | 
|---|
| 191 | is above the 512MB barrier present in Warp 4 and Warp 3, the
 | 
|---|
| 192 | program can not be run under these system. On Aurora (Warp Server
 | 
|---|
| 193 | for e-business) this limitation has been removed. Programs known
 | 
|---|
| 194 | to fall under this category are Microsoft Office (also the
 | 
|---|
| 195 | Office viewers) and other mainly Microsoft programs.
 | 
|---|
| 196 | 
 | 
|---|
| 197 | 
 | 
|---|
| 198 | 2.3 Win32k.sys - native OS/2 PE-loader
 | 
|---|
| 199 | --------------------------------------
 | 
|---|
| 200 | 
 | 
|---|
| 201 | The win32k.sys driver makes PE (Win32) executables equal to native OS/2
 | 
|---|
| 202 | executables by implementing a Ring 0 on-the-fly loader / converter.
 | 
|---|
| 203 | 
 | 
|---|
| 204 | You may wonder how you may run a Win32 program using a device driver. You
 | 
|---|
| 205 | don't have to worry about that, simply treat the Win32 program just as an
 | 
|---|
| 206 | another OS/2 program. OS/2 can't tell the difference!
 | 
|---|
| 207 | No conversion of dlls or running programs thru Pe.EXE.
 | 
|---|
| 208 | 
 | 
|---|
| 209 | For example, if you fancy playing windows solitaire.
 | 
|---|
| 210 |     1) Make sure the necessary DLLs (MSVCRT.DLL and CARDS.DLL) are in you
 | 
|---|
| 211 |        PATH, current dir, SOL.EXE dir, Odin32 System32 dir, Odin32 System dir,
 | 
|---|
| 212 |        Odin32 dir, or LIBPATHs; and that you have SOL.EXE somewhere.
 | 
|---|
| 213 | 
 | 
|---|
| 214 |     2) Then start SOL.EXE by simply typing SOL.EXE (with path if necessary).
 | 
|---|
| 215 |        It's also possible to start SOL.EXE from the desktop if you like.
 | 
|---|
| 216 |        Simply find the SOL.EXE icon (or create it) and double click on it!
 | 
|---|
| 217 | 
 | 
|---|
| 218 | 
 | 
|---|
| 219 | 2.3.1 WARNING
 | 
|---|
| 220 | -------------
 | 
|---|
| 221 | 
 | 
|---|
| 222 | The Win32k.sys is quite alpha software and any bugs which haven't been found
 | 
|---|
| 223 | yet may crash and/or corrupt you entire system! Make sure you have backed up
 | 
|---|
| 224 | important stuff first!
 | 
|---|
| 225 | 
 | 
|---|
| 226 | We are not responsible for ANYTHING AT ALL! See Odin32 disclaimer...
 | 
|---|
| 227 | 
 | 
|---|
| 228 | Before you install Win32k.sys make sure that you have a backdoor to your system
 | 
|---|
| 229 | which works. For example try to boot your system using the Alt+F1 during bootup
 | 
|---|
| 230 | and choose Commandline boot (F2). Make sure you have an textmode editor which
 | 
|---|
| 231 | works; for example TEDIT.EXE.
 | 
|---|
| 232 | 
 | 
|---|
| 233 | 
 | 
|---|
| 234 | 2.3.2 Requirements
 | 
|---|
| 235 | ------------------
 | 
|---|
| 236 | 
 | 
|---|
| 237 | Win32k should at least work on OS/2 Warp 3 and above, but I don't get too
 | 
|---|
| 238 | surprised if it worked on 2.11 too. DBCS are not supported yet AFAIK.
 | 
|---|
| 239 | 
 | 
|---|
| 240 | It no longer requires a kernel file for retail kernels (if you don't know what
 | 
|---|
| 241 | kernel you have, you have a retail kernel). Win32k does now contain a
 | 
|---|
| 242 | "database" for the most recent retail kernels. Currently this is:
 | 
|---|
| 243 |     Warp 4 fp#1 -> fp#14
 | 
|---|
| 244 |     Aurora GA, FP1, preFP2
 | 
|---|
| 245 |     Warp 3 fp#32-> fp#42
 | 
|---|
| 246 | 
 | 
|---|
| 247 | If the running kernel is not found in the "database" or is a debug kernel
 | 
|---|
| 248 | wink32.sys will look for symbolfiles as it allways did.
 | 
|---|
| 249 | If you use the -s:<symfile> argument the given symbol file will be
 | 
|---|
| 250 | investigated before the database is searched.
 | 
|---|
| 251 | 
 | 
|---|
| 252 | NOTE! It hasn't been fully verified that all the different national fixpaks
 | 
|---|
| 253 | have the same symbols as the us-english ones. Feedback on this issue is
 | 
|---|
| 254 | appreciated.
 | 
|---|
| 255 | 
 | 
|---|
| 256 | NOTE! A piece of advice for those playing with debug-kernels: Make sure that
 | 
|---|
| 257 | c:\OS2KRNL.SYM is matching the running kernel.
 | 
|---|
| 258 | 
 | 
|---|
| 259 | 2.3.2.1 Warp 3
 | 
|---|
| 260 | --------------
 | 
|---|
| 261 | 
 | 
|---|
| 262 | Win32k is not tested with Warp 3. It is _supposed_ to work with Warp 3
 | 
|---|
| 263 | provided you are running fixpack 32 or later.
 | 
|---|
| 264 | (Fixpack 32 + y2kclock.exe is required for Y2K readyness anyway so...)
 | 
|---|
| 265 | 
 | 
|---|
| 266 | 
 | 
|---|
| 267 | 2.3.3 Installation
 | 
|---|
| 268 | ------------------
 | 
|---|
| 269 | 
 | 
|---|
| 270 | To use Win32k.sys you have to add the following line into your config.sys:
 | 
|---|
| 271 |     device=<d:\path\system32>win32k.sys
 | 
|---|
| 272 | 
 | 
|---|
| 273 | Where <d:\path\system32> is the path to the win32k.sys, i.e. usually the odin32
 | 
|---|
| 274 | system32 directory.
 | 
|---|
| 275 | 
 | 
|---|
| 276 | After doing this, you'll have to reboot your machine to load the driver. During
 | 
|---|
| 277 | the boot process you will on a successful installation see some lines of
 | 
|---|
| 278 | technical info and finally a line saying:
 | 
|---|
| 279 | Win32k - Odin32 support driver.
 | 
|---|
| 280 |     Build:            14046 - v20.45
 | 
|---|
| 281 |     Found symbolfile: Win32k Symbol Database
 | 
|---|
| 282 | Win32k.sys succesfully initiated!
 | 
|---|
| 283 | 
 | 
|---|
| 284 | If you don't see the last line something is wrong, and some error info will be
 | 
|---|
| 285 | shown. In the case of error the 'rc=<value>' is important to remember.
 | 
|---|
| 286 | 
 | 
|---|
| 287 | 
 | 
|---|
| 288 | 2.3.4 Win32k parameters
 | 
|---|
| 289 | -----------------------
 | 
|---|
| 290 | 
 | 
|---|
| 291 | The Capitalized letters are the one which is tested for when identifying the
 | 
|---|
| 292 | argument.
 | 
|---|
| 293 | 
 | 
|---|
| 294 | There are some useful parameters for Win32k:
 | 
|---|
| 295 | -Quited         Quiet driver initiation.
 | 
|---|
| 296 |                 Default: disabled (ie. -V)
 | 
|---|
| 297 | 
 | 
|---|
| 298 | -Verbose        Verbose driver initiation.
 | 
|---|
| 299 |                 Default: enabled
 | 
|---|
| 300 | 
 | 
|---|
| 301 | -S:<filename>   Full path to the current OS/2 kernel symbol file.
 | 
|---|
| 302 |                 When this is specified the given
 | 
|---|
| 303 |                 Default: symbol "database" and default locations are searched.
 | 
|---|
| 304 | 
 | 
|---|
| 305 | 
 | 
|---|
| 306 | Loader parameters:
 | 
|---|
| 307 | -SCript:<Y|N>   Enable / disable UNIX script support.
 | 
|---|
| 308 |                 Default: Enabled.
 | 
|---|
| 309 | 
 | 
|---|
| 310 | -REXX:<Y|N>     Enable / disable pure REXX script support.
 | 
|---|
| 311 |                 Default: Enabled.
 | 
|---|
| 312 | 
 | 
|---|
| 313 | -Java:<Y|N>     Enable / disable JAVA loading.
 | 
|---|
| 314 | 
 | 
|---|
| 315 | -Pe:<MIXED|PE2LX|PE|NOT>
 | 
|---|
| 316 |                 Enabled / disable and set mode of the PE loading.
 | 
|---|
| 317 |                     MIXED:  Mix of Pe2Lx and Pe.exe. It uses Pe2Lx when
 | 
|---|
| 318 |                             possible and backs out to pe.exe if the executables
 | 
|---|
| 319 |                             aren't supported by the converter.
 | 
|---|
| 320 |                     PE2LX:  Pe2Lx loader only.
 | 
|---|
| 321 |                     PE:     Pe.exe only. The program is started using Pe.exe,
 | 
|---|
| 322 |                             and the process name will be pe.exe.
 | 
|---|
| 323 |                     NOT:    Disable PE loading.
 | 
|---|
| 324 | 
 | 
|---|
| 325 | 
 | 
|---|
| 326 | Logging parameters:
 | 
|---|
| 327 | -L<:E|:D>       Enables/Disables logging.
 | 
|---|
| 328 |                 Default: disabled.
 | 
|---|
| 329 | 
 | 
|---|
| 330 | -Com:<1|2|3|4>
 | 
|---|
| 331 | or
 | 
|---|
| 332 | -C<1|2|3|4>     Which com-port to log to.
 | 
|---|
| 333 |                 Default: -C2
 | 
|---|
| 334 | 
 | 
|---|
| 335 | -Warning:<1|2|3|4>
 | 
|---|
| 336 | or
 | 
|---|
| 337 | -W<1|2|3|4>     Warning/info level for PE loader. (This is warnings and info
 | 
|---|
| 338 |                 which is published thru the com-port as logging information.)
 | 
|---|
| 339 |                 Default: -W0
 | 
|---|
| 340 | 
 | 
|---|
| 341 | 
 | 
|---|
| 342 | Heap parameters:
 | 
|---|
| 343 | -HEAPMax:       Maximum swappable heap size in bytes.
 | 
|---|
| 344 |                 Default: 512KB
 | 
|---|
| 345 | 
 | 
|---|
| 346 | -Heapinit:      Initial heapsize in bytes.
 | 
|---|
| 347 |                 Default: 16MB
 | 
|---|
| 348 | 
 | 
|---|
| 349 | -RESHEAPMax:    Maximum resident heap size in bytes.
 | 
|---|
| 350 |                 Default: 256KB
 | 
|---|
| 351 | 
 | 
|---|
| 352 | -Resheapinit:   Initial resident in bytes.
 | 
|---|
| 353 |                 Default: 16MB
 | 
|---|
| 354 | 
 | 
|---|
| 355 | 
 | 
|---|
| 356 | OS/2 Loader parameter:
 | 
|---|
| 357 | -Dllfixes<:E|:D>
 | 
|---|
| 358 |                 Enables or Disables the long DLL name and non .DLL
 | 
|---|
| 359 |                 extention fixes. OS/2 DLLs have been limited to 8 chars
 | 
|---|
| 360 |                 names since version 2.<something>. This is a very bad
 | 
|---|
| 361 |                 limitation. Also OS/2 forces all DLL loaded to loadtime
 | 
|---|
| 362 |                 to have the extention '.DLL'.
 | 
|---|
| 363 |                 Both these retritions are removed if this option is
 | 
|---|
| 364 |                 enabled.
 | 
|---|
| 365 |                 For DLL with non .DLL extention the internal name must
 | 
|---|
| 366 |                 have to the extention included. (If you the experiences
 | 
|---|
| 367 |                 problems with IMPLIB.EXE, enclose the internal name
 | 
|---|
| 368 |                 in double-quotes.)
 | 
|---|
| 369 |                 You should not make a DLL with a name starting with
 | 
|---|
| 370 |                 DOSCALLS, DOSCALLS1, IBMVGA32, IBMDEV32 or IBMXGA32.
 | 
|---|
| 371 |                 Current state for this feature is EXPERIMENTAL.
 | 
|---|
| 372 |                 Default: Enabled
 | 
|---|
| 373 | 
 | 
|---|
| 374 | 
 | 
|---|
| 375 | Obsolete:
 | 
|---|
| 376 | -K:<filename> Ignored. Win32k scans the kernel image in memory!
 | 
|---|
| 377 | 
 | 
|---|
| 378 | 
 | 
|---|
| 379 | 2.3.5 PE Loading
 | 
|---|
| 380 | ----------------
 | 
|---|
| 381 | 
 | 
|---|
| 382 | Win32k.sys are able to do PE loading in two different ways.
 | 
|---|
| 383 | 
 | 
|---|
| 384 | 2.3.5.1 PE2LX
 | 
|---|
| 385 | -------------
 | 
|---|
| 386 | The first one is called PE2LX and hence uses the original Win32k.sys method
 | 
|---|
| 387 | which is similar to Pe2Lx. This only requires that KERNEL32.DLL (ie. Odin32
 | 
|---|
| 388 | System32 directory) is present somewhere in the PATH or LIBPATHs. The DLL
 | 
|---|
| 389 | search order of PE2LX is now conforming with the Win32 order:
 | 
|---|
| 390 |     1. The directory of the executable (.EXE).
 | 
|---|
| 391 |     2. The current directory.
 | 
|---|
| 392 |     3. The Odin32 System32 directory. (Kernel32.dll directory)
 | 
|---|
| 393 |     4. The Odin32 System directory. (sibling of system32)
 | 
|---|
| 394 |     5. The Odin32 directory. (parent of system32)
 | 
|---|
| 395 |     6. The PATH environment variable. (TODO: quotes are not currently supported)
 | 
|---|
| 396 |     7. The BEGINLIBPATH.
 | 
|---|
| 397 |     8. The LIBPATH.
 | 
|---|
| 398 |     9. The ENDLIBPATH.
 | 
|---|
| 399 | (Note that the OS/2 DLLs in the _Odin32_ process are also found using this
 | 
|---|
| 400 | search order. This shouldn't matter much as nearly all of the OS/2 DLL are
 | 
|---|
| 401 | allready loaded. But if this proves a problem it could be changed.)
 | 
|---|
| 402 | 
 | 
|---|
| 403 | 2.3.5.2 PE
 | 
|---|
| 404 | ----------
 | 
|---|
| 405 | The second one is called PE and invokes the Pe.EXE to execute the PE (Win32)
 | 
|---|
| 406 | programs. This of course requies that PE.EXE is found in the PATH.
 | 
|---|
| 407 | 
 | 
|---|
| 408 | 2.3.5.3 Modes
 | 
|---|
| 409 | --------------
 | 
|---|
| 410 | Win32k.sys have three (or four) different ways of combining these two methods,
 | 
|---|
| 411 | called modes:
 | 
|---|
| 412 |     PE2LX only
 | 
|---|
| 413 |     PE only
 | 
|---|
| 414 |     PE2LX with fallback on PE.
 | 
|---|
| 415 |     (fourth: NOT load any PE executables at all)
 | 
|---|
| 416 | 
 | 
|---|
| 417 | The last one is the default one and is probably the best one currently.
 | 
|---|
| 418 | 
 | 
|---|
| 419 | 
 | 
|---|
| 420 | 2.3.6 UNIX Shell Script Loader
 | 
|---|
| 421 | ------------------------------
 | 
|---|
| 422 | 
 | 
|---|
| 423 | The UNIX Shell Script Loader makes OS/2 able to run UNIX shell scripts as
 | 
|---|
| 424 | native executables, just as UNIX does. A unix shell script is a text file
 | 
|---|
| 425 | which has a starting line which specifies the interpreter for the script.
 | 
|---|
| 426 | 
 | 
|---|
| 427 | For example a perl script:
 | 
|---|
| 428 | #!/bin/perl5 -Sx
 | 
|---|
| 429 | 
 | 
|---|
| 430 | Or the most common one:
 | 
|---|
| 431 | #! /bin/sh
 | 
|---|
| 432 | 
 | 
|---|
| 433 | Since Most OS/2 systems don't have a /bin directory or a /usr/bin directory
 | 
|---|
| 434 | the executable specified are looked for in these ways:
 | 
|---|
| 435 |     1. The exact filename specified.
 | 
|---|
| 436 |     2. The filename specified with .EXE extention.
 | 
|---|
| 437 |     3. Search the PATH for the filename (with out path of course).
 | 
|---|
| 438 |     4. Search the PATH for the filename with .EXE extention (and with out path of course).
 | 
|---|
| 439 | 
 | 
|---|
| 440 | So, you could now execute UNIX shell script in OS/2 without even modify the
 | 
|---|
| 441 | path of the interpreter!
 | 
|---|
| 442 | 
 | 
|---|
| 443 | The UNIX Shell Script Loader is enabled by default.
 | 
|---|
| 444 | 
 | 
|---|
| 445 | 
 | 
|---|
| 446 | 2.3.6 Pure REXX Loader
 | 
|---|
| 447 | ----------------------
 | 
|---|
| 448 | 
 | 
|---|
| 449 | The Pure REXX Loader is a win32k.sys feature which enables REXX script with
 | 
|---|
| 450 | the extentions .RX and .REX to run as native OS/2 executables. These REXX
 | 
|---|
| 451 | scripts are executed using kRX.EXE which is found in the Odin32 System32
 | 
|---|
| 452 | directory.
 | 
|---|
| 453 | 
 | 
|---|
| 454 | When we say "Pure REXX" scripts, that means no use of command line should
 | 
|---|
| 455 | occure in the script.
 | 
|---|
| 456 | 
 | 
|---|
| 457 | The Pure REXX Loader is enabled by default.
 | 
|---|
| 458 | 
 | 
|---|
| 459 | 
 | 
|---|
| 460 | 2.3.7 Java Loader/Invoker
 | 
|---|
| 461 | -------------------------
 | 
|---|
| 462 | 
 | 
|---|
| 463 | Just for fun, I've added some code which detects JAVA class binaries and
 | 
|---|
| 464 | executes the class using JAVA.EXE. I first thougth this should be easy, but
 | 
|---|
| 465 | it turned out to have several problems.
 | 
|---|
| 466 | So please note the following:
 | 
|---|
| 467 |     - The classname is case sensitive, you have to write the exact class
 | 
|---|
| 468 |       name (with .class extention or what ever extention the file have)
 | 
|---|
| 469 |       when trying to execute a class. This could cause some throuble making
 | 
|---|
| 470 |       WPS program objects for the classes....
 | 
|---|
| 471 |     - To support executing of .class-files which are not in the current
 | 
|---|
| 472 |       directory win32k.sys send the directory of the .class-file in to
 | 
|---|
| 473 |       java.exe as a '-classpath' option. This option I soon found out had the
 | 
|---|
| 474 |       sideeffect of making JAVA.exe ignore the other CLASSPATH and not use
 | 
|---|
| 475 |       it's default class path. So now the contents of the CLASSPATH env. var.
 | 
|---|
| 476 |       or a generated default classpath is also sent in with the '-classpath'
 | 
|---|
| 477 |       option.
 | 
|---|
| 478 |     - The CLASSPATH environment variable should not be longer than 639 chars.
 | 
|---|
| 479 | 
 | 
|---|
| 480 | When you have successfully installed Win32k.sys try type this at the
 | 
|---|
| 481 | commandline:
 | 
|---|
| 482 | c:\java11\demo\hello\hello.class
 | 
|---|
| 483 | 
 | 
|---|
| 484 | This is then printed at my screen:
 | 
|---|
| 485 | Hello, Warped world!
 | 
|---|
| 486 | 
 | 
|---|
| 487 | The JAVA Loader/Invoker is enabled by default.
 | 
|---|
| 488 | 
 | 
|---|
| 489 | 
 | 
|---|
| 490 | 2.3.8 Rings - Ring 0 / Ring 3
 | 
|---|
| 491 | -----------------------------
 | 
|---|
| 492 | 
 | 
|---|
| 493 | FYI. Ring 0 is the most priveleged level of execution in OS/2. The OS/2 kernel
 | 
|---|
| 494 | and device drivers execute at this level, while user applications execute in
 | 
|---|
| 495 | Ring 3, the least priveleged executing level.
 | 
|---|
| 496 | 
 | 
|---|
| 497 | 
 | 
|---|
| 498 | 2.3.9 Win32k Control Center
 | 
|---|
| 499 | ---------------------------
 | 
|---|
| 500 | 
 | 
|---|
| 501 | In your Odin32 System32 directory there is a program called Win32kCC.exe,
 | 
|---|
| 502 | this is the Win32k Control Center (Win32kCC). Win32kCC is as the name says
 | 
|---|
| 503 | a program controlling Win32k.sys.
 | 
|---|
| 504 | 
 | 
|---|
| 505 | Win32kCC allows you to enable, disable and change behaviour of different
 | 
|---|
| 506 | parts in Win32k.sys.
 | 
|---|
| 507 | 
 | 
|---|
| 508 | For example: You could disable PE loading, or change it from MIXED mode (see
 | 
|---|
| 509 | 2.3.4, -PE) to PE2LX mode. Or change it from PE2LX mode to PE mode to see
 | 
|---|
| 510 | if PE.EXE does a better job loading an executable.
 | 
|---|
| 511 | 
 | 
|---|
| 512 | Note that the changes would not effect allready loaded executables.
 | 
|---|
| 513 | 
 | 
|---|
| 514 | 
 | 
|---|
| 515 | Win32kCC also displays status info on the running Win32k.sys and OS/2 kernel:
 | 
|---|
| 516 |     -Win32k.sys version number
 | 
|---|
| 517 |     -Win32k build time/date
 | 
|---|
| 518 |     -Path of the symbol file which was used (or Win32k Symbol Database).
 | 
|---|
| 519 |     -OS/2 kernel build number fixpack (guess)
 | 
|---|
| 520 |     -OS/2 kernel type as win32k has detected it
 | 
|---|
| 521 |     -Number of Pe2Lx currently loaded modules
 | 
|---|
| 522 |     -Win32k resident and swappable heap stats.
 | 
|---|
| 523 | 
 | 
|---|
| 524 | PS. Beside the "PE Loader" area there is an "Elf Loader" area this is for a
 | 
|---|
| 525 | future Elf2Lx loader.
 | 
|---|
| 526 | 
 | 
|---|
| 527 | 
 | 
|---|
| 528 | 
 | 
|---|
| 529 | 2.4 The Ring3 conversion utility (Xx2Lx.exe)
 | 
|---|
| 530 | --------------------------------------------
 | 
|---|
| 531 | 
 | 
|---|
| 532 | Xx2Lx.exe was the first method of running Win32 programs under
 | 
|---|
| 533 | OS/2. It is still provided and also functional but it has been
 | 
|---|
| 534 | deprecated. Using it is only sensible for debugging certain
 | 
|---|
| 535 | problems as it requires all DLLs and EXEs to be converted into
 | 
|---|
| 536 | another file format thus changing the original Win32 files.
 | 
|---|
| 537 | (It's only future use will be to convert Win32 executable with
 | 
|---|
| 538 | debuginfo to LX with HLL (IPMD/ICSDEBUG) debuginfo for
 | 
|---|
| 539 | sourcelevel debugging of Win32 executables under Odin32. This
 | 
|---|
| 540 | is not yet implemented but is being worked on.)
 | 
|---|
| 541 | 
 | 
|---|
| 542 | Note. The name changed from Pe2Lx to Xx2Lx. It is in prepare for Elf2Lx.
 | 
|---|
| 543 | 
 | 
|---|
| 544 | 
 | 
|---|
| 545 | 3.0 Applications known to be working
 | 
|---|
| 546 | ------------------------------------
 | 
|---|
| 547 | 
 | 
|---|
| 548 | - Windows 95/NT Help Viewer (winhlp32.exe)
 | 
|---|
| 549 | - Windows 95/NT Registry Editor
 | 
|---|
| 550 | - Windows NT Solitaire (not the one from Windows 95)
 | 
|---|
| 551 | - Windows NT Freecell (not the one from Windows 95)
 | 
|---|
| 552 | - Windows 95/NT Calculator
 | 
|---|
| 553 | - Windows NT Pinball
 | 
|---|
| 554 | - Windows NT Minesweeper
 | 
|---|
| 555 | - Quake II
 | 
|---|
| 556 | - Red Alert
 | 
|---|
| 557 | - Professional Minesweeper
 | 
|---|
| 558 | - Windiff (part of Win32 SDK)
 | 
|---|
| 559 | - RealPlayer 7/8
 | 
|---|
| 560 | - Lotus Notes 5.0 (partly anyway)
 | 
|---|
| 561 | - Acrobat Distiller 3.0
 | 
|---|
| 562 | 
 | 
|---|
| 563 | Note that many other applications load and/or partly work.
 | 
|---|
| 564 | 
 | 
|---|
| 565 | 
 | 
|---|
| 566 | 4.0 Reporting Problems and Successes
 | 
|---|
| 567 | ------------------------------------
 | 
|---|
| 568 | 
 | 
|---|
| 569 | Bug reports can be sent to the Odin users mailinglist (odinusers@egroups.com;
 | 
|---|
| 570 | visit www.egroups.com for information about joining).
 | 
|---|
| 571 | The file ReportingBugs.txt explains how to send in a proper bug report.
 | 
|---|
| 572 | 
 | 
|---|
| 573 | An application compatibility database has been created at Netlabs
 | 
|---|
| 574 | where you can share your experiences with Odin.
 | 
|---|
| 575 | The application compatibility database can be found at
 | 
|---|
| 576 | 
 | 
|---|
| 577 | http://www.netlabs.org/odin/appdatabase
 | 
|---|
| 578 | 
 | 
|---|
| 579 | NOTE: The application database is not meant for bug reports.
 | 
|---|
| 580 | 
 | 
|---|
| 581 | 
 | 
|---|
| 582 | 5.0 Project Odin Source Code Notes
 | 
|---|
| 583 | ----------------------------------
 | 
|---|
| 584 | 
 | 
|---|
| 585 | 5.1.0 Introduction
 | 
|---|
| 586 | ------------------
 | 
|---|
| 587 | 
 | 
|---|
| 588 | This chapter is intended for people more familiar with ODIN. It describes
 | 
|---|
| 589 | the various aspects of the project such as accessing the latest sources via
 | 
|---|
| 590 | cvs, building the binaries, running win32 applications, how to identify and
 | 
|---|
| 591 | report problems and bugs, as well as how to participate in this very
 | 
|---|
| 592 | promising project.
 | 
|---|
| 593 | 
 | 
|---|
| 594 | 
 | 
|---|
| 595 | 5.1.1 Prerequisites:
 | 
|---|
| 596 | --------------------
 | 
|---|
| 597 | 
 | 
|---|
| 598 | Required compilers/tools:
 | 
|---|
| 599 |         - IBM VisualAge 3.0 (CTx8 fixpack applied)
 | 
|---|
| 600 |           (version 3.6 might also work; version 4 is not recommended)
 | 
|---|
| 601 |         - OS/2 Warp 4 Toolkit (project apparently doesn't compile with
 | 
|---|
| 602 |           VAC's OS/2 headers)
 | 
|---|
| 603 |           Might also work with EMX headers. (haven't tried this!)
 | 
|---|
| 604 |         - ALP 4.0 (IBM Assembly Language Processor)
 | 
|---|
| 605 |           Download the tools zipfile from http://service.boulder.ibm.com/ddk/
 | 
|---|
| 606 |           (you need to register, but it's free)
 | 
|---|
| 607 |         - Unix-like rm.exe (nmake clean)
 | 
|---|
| 608 | 
 | 
|---|
| 609 | Changes from last source code release:
 | 
|---|
| 610 |         - Uses Wine headers and a stripped down version of os2win.h (Open32
 | 
|---|
| 611 |           header)
 | 
|---|
| 612 |         - All Open32 apis have the 'O32_' prefix.
 | 
|---|
| 613 |         - All Open32 declarations are appended with '_O32' (mostly due to
 | 
|---|
| 614 |           calling convention differences)
 | 
|---|
| 615 |         - nmake DEBUG=1 builds the debug version
 | 
|---|
| 616 |           nmake         builds the release version
 | 
|---|
| 617 |         - Several dlls (i.e. USER32, KERNEL32, ADVAPI32) contain extra .def
 | 
|---|
| 618 |           files that are used to create libraries that contain the api names
 | 
|---|
| 619 |           as required by the linker when you use them. (_apiname@nrparameterbytes)
 | 
|---|
| 620 | 
 | 
|---|
| 621 | Wine header notes:
 | 
|---|
| 622 |         - Several header files have been changed to make them usable for VAC
 | 
|---|
| 623 |         - Several header files contain bugfixes (mostly parameter type changes)
 | 
|---|
| 624 |         - Several header files include additional declarations
 | 
|---|
| 625 |         - At this time we don't intend to have our changes included in the
 | 
|---|
| 626 |           Wine codebase as header files are not likely to change often.
 | 
|---|
| 627 | 
 | 
|---|
| 628 | Coding conventions:
 | 
|---|
| 629 |         - Do NOT directly call the Open32 apis unless you're writing
 | 
|---|
| 630 |           a wrapper for it.
 | 
|---|
| 631 |         - Do NOT include os2.h directly. Use os2wrap.h instead.
 | 
|---|
| 632 |           os2wrap.h contains all the OS/2 apis with a wrapper around it to save
 | 
|---|
| 633 |           and restore the selector in FS. (some OS/2 apis set it back to the
 | 
|---|
| 634 |           default value (150b))
 | 
|---|
| 635 |         - Use the correct Win32 api when there are two version (ascii & unicode)
 | 
|---|
| 636 |           Calling the standard one (SendMessage) causes a error during
 | 
|---|
| 637 |           compilation.
 | 
|---|
| 638 |           Use SendMessageA instead.
 | 
|---|
| 639 |         - Source code style will be decided on in the near future.
 | 
|---|
| 640 | 
 | 
|---|
| 641 | 
 | 
|---|
| 642 | 5.2.0 Accessing ODIN source code via CVS
 | 
|---|
| 643 | ----------------------------------------
 | 
|---|
| 644 | 
 | 
|---|
| 645 | Please check out http://www.netlabs.org/ and http://www.netlabs.org/odin.
 | 
|---|
| 646 | 
 | 
|---|
| 647 | 
 | 
|---|
| 648 | 5.3.0 Building the binaries
 | 
|---|
| 649 | ---------------------------
 | 
|---|
| 650 | 
 | 
|---|
| 651 | The first time you want to build Odin, you must first run configure.cmd.
 | 
|---|
| 652 | This REXX script creates the file makefile.inc, which contains the absolute
 | 
|---|
| 653 | paths of important build directories.
 | 
|---|
| 654 | 
 | 
|---|
| 655 | If your system setup meets above stated requirements, everything you
 | 
|---|
| 656 | need to do next for a binary build is:
 | 
|---|
| 657 | 
 | 
|---|
| 658 |   nmake DEBUG=1
 | 
|---|
| 659 | 
 | 
|---|
| 660 | or alternatively
 | 
|---|
| 661 | 
 | 
|---|
| 662 |   nmake release (not working right now!)
 | 
|---|
| 663 | 
 | 
|---|
| 664 | As the current state of the project is still known to be alpha level, one should
 | 
|---|
| 665 | expect some functions not to work properly. Therefore, we recommend the use of
 | 
|---|
| 666 | the debug-version which creates long logfiles for problem determination purpose
 | 
|---|
| 667 | and to allow active debugging with debuggers such as IPMD, ICAT, KDB, etc.
 | 
|---|
| 668 | 
 | 
|---|
| 669 | Please note if you do not want to suffer from the performance loss of writing
 | 
|---|
| 670 | logfiles, you can disable logging even with the debug binaries of ODIN by
 | 
|---|
| 671 | setting:
 | 
|---|
| 672 | 
 | 
|---|
| 673 |   SET NOWIN32LOG=YES
 | 
|---|
| 674 | 
 | 
|---|
| 675 | To enable logging again, clear this environment variable by typing:
 | 
|---|
| 676 | 
 | 
|---|
| 677 |   SET NOWIN32LOG=
 | 
|---|
| 678 | 
 | 
|---|
| 679 | Logging is enabled by default in the debug build, but disabled by default
 | 
|---|
| 680 | in the nodebuginfo build and not present in the release build.
 | 
|---|
| 681 | 
 | 
|---|
| 682 | 5.3.1 Build problems
 | 
|---|
| 683 | --------------------
 | 
|---|
| 684 | 
 | 
|---|
| 685 | ODIN is moving at a fast pace. Sometimes side effects of source dependencies may
 | 
|---|
| 686 | require you to do a full rebuild of the binaries instead of an incremental build.
 | 
|---|
| 687 | 
 | 
|---|
| 688 | However, rarely it also happens the sources contained in the CVS repository do
 | 
|---|
| 689 | not build completely due to erroneous source code. Usually, this is fixed within
 | 
|---|
| 690 | two days at maximum.
 | 
|---|
| 691 | In such event, one can normally stick with the previous version of the particular
 | 
|---|
| 692 | module to further test win32 applications on ODIN.
 | 
|---|
| 693 | 
 | 
|---|
| 694 | Please report such build problems through the appropriate channel.
 | 
|---|
| 695 | 
 | 
|---|
| 696 | 
 | 
|---|
| 697 | 5.3.2 Downloading daily built binaries
 | 
|---|
| 698 | --------------------------------------
 | 
|---|
| 699 | 
 | 
|---|
| 700 | http://www.os2.org/ has setup an ftp server that hosts the automatically
 | 
|---|
| 701 | built binaries on daily basis. For people that do not have a suitable
 | 
|---|
| 702 | development setup for ODIN, we provide the latest binary code that way.
 | 
|---|
| 703 | 
 | 
|---|
| 704 | 
 | 
|---|
| 705 | 5.4.0 Project participation
 | 
|---|
| 706 | ---------------------------
 | 
|---|
| 707 | 
 | 
|---|
| 708 | As ODIN became an open source project, everybody is kindly invited to
 | 
|---|
| 709 | contribute his/her share to the progress of the project. May it be
 | 
|---|
| 710 | active coding, fixing bugs or just providing detailed information about
 | 
|---|
| 711 | examined problems.
 | 
|---|
| 712 | 
 | 
|---|
| 713 | We suggest you subscribe to win32os2-wai and the corresponding mailing lists
 | 
|---|
| 714 | on http://www.egroups.com.
 | 
|---|
| 715 | In case you are interested in participating, every member of the project will
 | 
|---|
| 716 | be happy to give you direction to the right places and to give a personal
 | 
|---|
| 717 | introduction to further development of the particular modules.
 | 
|---|
| 718 | 
 | 
|---|
| 719 | 
 | 
|---|
| 720 | 6.0 Warranty
 | 
|---|
| 721 | ------------
 | 
|---|
| 722 | 
 | 
|---|
| 723 | EXCEPT AS OTHERWISE RESTRICTED BY LAW, THIS WORK IS PROVIDED
 | 
|---|
| 724 | WITHOUT ANY EXPRESSED OR IMPLIED WARRANTIES OF ANY KIND, INCLUDING
 | 
|---|
| 725 | BUT NOT LIMITED TO, ANY IMPLIED WARRANTIES OF FITNESS FOR A
 | 
|---|
| 726 | PARTICULAR PURPOSE, MERCHANTABILITY OR TITLE.  EXCEPT AS
 | 
|---|
| 727 | OTHERWISE PROVIDED BY LAW, NO AUTHOR, COPYRIGHT HOLDER OR
 | 
|---|
| 728 | LICENSOR SHALL BE LIABLE TO YOU FOR DAMAGES OF ANY KIND, EVEN IF
 | 
|---|
| 729 | THEY HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
 | 
|---|