source: trunk/src/win32k/win32k.txt@ 10366

2.3 Win32k.sys - native OS/2 PE-loader
--------------------------------------

The win32k.sys driver makes PE (Win32) executables equal to native OS/2
executables by implementing a Ring 0 on-the-fly loader / converter.

You may wonder how you may run a Win32 program using a device driver. You
don't have to worry about that, simply treat the Win32 program just as an
another OS/2 program. OS/2 can't tell the difference!
No conversion of dlls or running programs thru Pe.EXE.

For example, if you fancy playing windows solitaire.
    1) Make sure the necessary DLLs (MSVCRT.DLL and CARDS.DLL) are in you
       PATH, current dir, SOL.EXE dir, Odin32 System32 dir, Odin32 System dir,
       Odin32 dir, or LIBPATHs; and that you have SOL.EXE somewhere.

    2) Then start SOL.EXE by simply typing SOL.EXE (with path if necessary).
       It's also possible to start SOL.EXE from the desktop if you like.
       Simply find the SOL.EXE icon (or create it) and double click on it!


2.3.1 WARNING
-------------

The Win32k.sys is quite alpha software and any bugs which haven't been found
yet may crash and/or corrupt you entire system! Make sure you have backed up
important stuff first!

We are not responsible for ANYTHING AT ALL! See Odin32 disclaimer...

Before you install Win32k.sys make sure that you have a backdoor to your system
which works. For example try to boot your system using the Alt+F1 during bootup
and choose Commandline boot (F2). Make sure you have an textmode editor which
works; for example TEDIT.EXE.


2.3.2 Requirements
------------------

Win32k should at least work on OS/2 Warp 3 and above, but I don't get too
surprised if it worked on 2.11 too. DBCS are not supported yet AFAIK.

It no longer requires a kernel file for retail kernels (if you don't know what
kernel you have, you have a retail kernel). Win32k does now contain a
"database" for the most recent retail kernels. Currently this is:
    Warp 4 fp#1 -> fp#14
    Aurora GA, FP1, preFP2
    Warp 3 fp#32-> fp#42

If the running kernel is not found in the "database" or is a debug kernel
wink32.sys will look for symbolfiles as it allways did.
If you use the -s:<symfile> argument the given symbol file will be
investigated before the database is searched.

NOTE! It hasn't been fully verified that all the different national fixpaks
have the same symbols as the us-english ones. Feedback on this issue is
appreciated.

NOTE! A piece of advice for those playing with debug-kernels: Make sure that
c:\OS2KRNL.SYM is matching the running kernel.

2.3.2.1 Warp 3
--------------

Win32k is not tested with Warp 3. It is _supposed_ to work with Warp 3
provided you are running fixpack 32 or later.
(Fixpack 32 + y2kclock.exe is required for Y2K readyness anyway so...)


2.3.3 Installation
------------------

To use Win32k.sys you have to add the following line into your config.sys:
    device=<d:\path\system32>win32k.sys

Where <d:\path\system32> is the path to the win32k.sys, i.e. usually the odin32
system32 directory.

After doing this, you'll have to reboot your machine to load the driver. During
the boot process you will on a successful installation see some lines of
technical info and finally a line saying:
Win32k - Odin32 support driver.
    Build:            14046 - v20.45
    Found symbolfile: Win32k Symbol Database
Win32k.sys succesfully initiated!

If you don't see the last line something is wrong, and some error info will be
shown. In the case of error the 'rc=<value>' is important to remember.


2.3.4 Win32k parameters
-----------------------

The Capitalized letters are the one which is tested for when identifying the
argument.

There are some useful parameters for Win32k:
-Quited         Quiet driver initiation.
                Default: disabled (ie. -V)

-Verbose        Verbose driver initiation.
                Default: enabled

-S:<filename>   Full path to the current OS/2 kernel symbol file.
                When this is specified the given
                Default: symbol "database" and default locations are searched.


Loader parameters:
-SCript:<Y|N>   Enable / disable UNIX script support.
                Default: Enabled.

-REXX:<Y|N>     Enable / disable pure REXX script support.
                Default: Enabled.

-Java:<Y|N>     Enable / disable JAVA loading.

-Pe:<MIXED|PE2LX|PE|NOT>
                Enabled / disable and set mode of the PE loading.
                    MIXED:  Mix of Pe2Lx and Pe.exe. It uses Pe2Lx when
                            possible and backs out to pe.exe if the executables
                            aren't supported by the converter.
                    PE2LX:  Pe2Lx loader only.
                    PE:     Pe.exe only. The program is started using Pe.exe,
                            and the process name will be pe.exe.
                    NOT:    Disable PE loading.


Logging parameters:
-L<:E|:D>       Enables/Disables logging.
                Default: disabled.

-Com:<1|2|3|4>
or
-C<1|2|3|4>     Which com-port to log to.
                Default: -C2

-Warning:<1|2|3|4>
or
-W<1|2|3|4>     Warning/info level for PE loader. (This is warnings and info
                which is published thru the com-port as logging information.)
                Default: -W0


Heap parameters:
-HEAPMax:       Maximum swappable heap size in bytes.
                Default: 512KB

-Heapinit:      Initial heapsize in bytes.
                Default: 16MB

-RESHEAPMax:    Maximum resident heap size in bytes.
                Default: 256KB

-Resheapinit:   Initial resident in bytes.
                Default: 16MB


OS/2 Loader parameter:
-Dllfixes<:E|:D>
                Enables or Disables the long DLL name and non .DLL
                extention fixes. OS/2 DLLs have been limited to 8 chars
                names since version 2.<something>. This is a very bad
                limitation. Also OS/2 forces all DLL loaded to loadtime
                to have the extention '.DLL'.
                Both these retritions are removed if this option is
                enabled.
                For DLL with non .DLL extention the internal name must
                have to the extention included. (If you the experiences
                problems with IMPLIB.EXE, enclose the internal name
                in double-quotes.)
                You should not make a DLL with a name starting with
                DOSCALLS, DOSCALLS1, IBMVGA32, IBMDEV32 or IBMXGA32.
                Current state for this feature is EXPERIMENTAL.
                Default: Enabled


Obsolete:
-K:<filename> Ignored. Win32k scans the kernel image in memory!


2.3.5 PE Loading
----------------

Win32k.sys are able to do PE loading in two different ways.

2.3.5.1 PE2LX
-------------
The first one is called PE2LX and hence uses the original Win32k.sys method
which is similar to Pe2Lx. This only requires that KERNEL32.DLL (ie. Odin32
System32 directory) is present somewhere in the PATH or LIBPATHs. The DLL
search order of PE2LX is now conforming with the Win32 order:
    1. The directory of the executable (.EXE).
    2. The current directory.
    3. The Odin32 System32 directory. (Kernel32.dll directory)
    4. The Odin32 System directory. (sibling of system32)
    5. The Odin32 directory. (parent of system32)
    6. The PATH environment variable. (TODO: quotes are not currently supported)
    7. The BEGINLIBPATH.
    8. The LIBPATH.
    9. The ENDLIBPATH.
(Note that the OS/2 DLLs in the _Odin32_ process are also found using this
search order. This shouldn't matter much as nearly all of the OS/2 DLL are
allready loaded. But if this proves a problem it could be changed.)

2.3.5.2 PE
----------
The second one is called PE and invokes the Pe.EXE to execute the PE (Win32)
programs. This of course requies that PE.EXE is found in the PATH.

2.3.5.3 Modes
--------------
Win32k.sys have three (or four) different ways of combining these two methods,
called modes:
    PE2LX only
    PE only
    PE2LX with fallback on PE.
    (fourth: NOT load any PE executables at all)

The last one is the default one and is probably the best one currently.


2.3.6 UNIX Shell Script Loader
------------------------------

The UNIX Shell Script Loader makes OS/2 able to run UNIX shell scripts as
native executables, just as UNIX does. A unix shell script is a text file
which has a starting line which specifies the interpreter for the script.

For example a perl script:
#!/bin/perl5 -Sx

Or the most common one:
#! /bin/sh

Since Most OS/2 systems don't have a /bin directory or a /usr/bin directory
the executable specified are looked for in these ways:
    1. The exact filename specified.
    2. The filename specified with .EXE extention.
    3. Search the PATH for the filename (with out path of course).
    4. Search the PATH for the filename with .EXE extention (and with out path of course).

So, you could now execute UNIX shell script in OS/2 without even modify the
path of the interpreter!

The UNIX Shell Script Loader is enabled by default.


2.3.6 Pure REXX Loader
----------------------

The Pure REXX Loader is a win32k.sys feature which enables REXX script with
the extentions .RX and .REX to run as native OS/2 executables. These REXX
scripts are executed using kRX.EXE which is found in the Odin32 System32
directory.

When we say "Pure REXX" scripts, that means no use of command line should
occure in the script.

The Pure REXX Loader is enabled by default.


2.3.7 Java Loader/Invoker
-------------------------

Just for fun, I've added some code which detects JAVA class binaries and
executes the class using JAVA.EXE. I first thougth this should be easy, but
it turned out to have several problems.
So please note the following:
    - The classname is case sensitive, you have to write the exact class
      name (with .class extention or what ever extention the file have)
      when trying to execute a class. This could cause some throuble making
      WPS program objects for the classes....
    - To support executing of .class-files which are not in the current
      directory win32k.sys send the directory of the .class-file in to
      java.exe as a '-classpath' option. This option I soon found out had the
      sideeffect of making JAVA.exe ignore the other CLASSPATH and not use
      it's default class path. So now the contents of the CLASSPATH env. var.
      or a generated default classpath is also sent in with the '-classpath'
      option.
    - The CLASSPATH environment variable should not be longer than 639 chars.

When you have successfully installed Win32k.sys try type this at the
commandline:
c:\java11\demo\hello\hello.class

This is then printed at my screen:
Hello, Warped world!

The JAVA Loader/Invoker is enabled by default.


2.3.8 Rings - Ring 0 / Ring 3
-----------------------------

FYI. Ring 0 is the most priveleged level of execution in OS/2. The OS/2 kernel
and device drivers execute at this level, while user applications execute in
Ring 3, the least priveleged executing level.


2.3.9 Win32k Control Center
---------------------------

In your Odin32 System32 directory there is a program called Win32kCC.exe,
this is the Win32k Control Center (Win32kCC). Win32kCC is as the name says
a program controlling Win32k.sys.

Win32kCC allows you to enable, disable and change behaviour of different
parts in Win32k.sys.

For example: You could disable PE loading, or change it from MIXED mode (see
2.3.4, -PE) to PE2LX mode. Or change it from PE2LX mode to PE mode to see
if PE.EXE does a better job loading an executable.

Note that the changes would not effect allready loaded executables.


Win32kCC also displays status info on the running Win32k.sys and OS/2 kernel:
    -Win32k.sys version number
    -Win32k build time/date
    -Path of the symbol file which was used (or Win32k Symbol Database).
    -OS/2 kernel build number fixpack (guess)
    -OS/2 kernel type as win32k has detected it
    -Number of Pe2Lx currently loaded modules
    -Win32k resident and swappable heap stats.

PS. Beside the "PE Loader" area there is an "Elf Loader" area this is for a
future Elf2Lx loader.



2.4 The Ring3 conversion utility (Xx2Lx.exe)
--------------------------------------------

Xx2Lx.exe was the first method of running Win32 programs under
OS/2. It is still provided and also functional but it has been
deprecated. Using it is only sensible for debugging certain
problems as it requires all DLLs and EXEs to be converted into
another file format thus changing the original Win32 files.
(It's only future use will be to convert Win32 executable with
debuginfo to LX with HLL (IPMD/ICSDEBUG) debuginfo for
sourcelevel debugging of Win32 executables under Odin32. This
is not yet implemented but is being worked on.)

Note. The name changed from Pe2Lx to Xx2Lx. It is in prepare for Elf2Lx.