Welcome to the second official release of WUSTUB! *
This one is version 0.2.                          *
***************************************************

IMPORTANT NOTE: AS THE VERSION NUMBER MIGHT TELL YOU, THIS SOFTWARE IS UNDER
DEVELOPMENT. IT MAY HAVE (BETTER: IT HAS) BUGS IN IT AND SOME FEATURES YOU
MIGHT EXPECT TO WORK MAY NOT DO SO YET!

To answer a FAQ:

There are no _known_ bugs right now, but I _know_ there are bugs. See the
difference? If I _knew_ of a bug I'd fixed it. Why shouldn't I?

- What it does:
-------------------------------------------------------------------------------

WUSTUB enables you to load a PE executable (the executable format used in 32
bit versions of Windows) from plain DOS and from most DOS- boxes of today's
operating systems. However, it doesn't fully replace the Win32- API.

It has been designed to execute Turbo Pascal (DOS) style programs compiled with
the Borland Delphi 2 compiler.

The system runtime library (SYSTEM.DCU) is calling few Win 32 API functions at
runtime and WUSTUB provides just these. Note that even while running in a DOS-
box under Windows, the WUSTUB- fuctions are called. Even in Windows, WUSTUB-
extended programs will run as true DOS- programs, giving you the advantage
of beeing able to call interrupts and access memory and hardware directly.

YOU SHOULD NEVER CALL WINDOWS API FUNCTIONS FROM WITHIN YOUR PROGRAM EVEN
THOUGH IT'S POSSIBLE!

The reason is, that sometimes they may behave a bit different, and, of course,
you're writing _DOS_ programs, aren't you?

So, let's say: WUSTUB is a DOS extender for "Turbo Pascal 8" a.k.a. "Delphi 2".

More tech stuff later...


- The author:
-------------------------------------------------------------------------------

Michael Tippach
Stockartstrasse 27
04277 Leipzig, Germany
Phone/Fax: +49 341 3028848
                      
email    : tippachm@dialin.deh.de             (preferred)
           tippach@metronet.de                (sometimes actually works)
           heiko.friedel@phil.tu-chemnitz.de  (if anything else fails)



- Legal stuff:
-------------------------------------------------------------------------------

I hate^2 this one but would YOU love it to get sued for giving something
to others for FREE? (OTOH: there's kinda strange fascination going out from
legal stuff like that, isn't it?)

DISCLAIMER:

THIS SOFTWARE IS PROVIDED "AS IS". I, THE AUTOR, SHALL NOT BE LIABLE FOR ANY
KIND OF LOSS OR DAMAGE ARISING OUT OF THE USE, ABUSE OR THE INABILITY TO USE
THIS SOFTWRAE.

ABSOLUTE NO WARRANTY / LIABILITY:

THIS SOFTWARE COMES WITHOUT ANY KIND OF WARRANTY, EITHER EXPRESSED OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO THE IMPLIED WARRANTY OF MERCHANTABILITY OR
FITNESS FOR A PARTICULAR PURPOSE.

IN NO EVENT SHALL I, THE AUTOR, BE LIABLE FOR ANY KIND OF LOSS OR DAMAGE
ARISING OUT OF THE USE, ABUSE OR INABILITY TO USE THE SOFTWARE.

IF YOU DON'T AGREE WITH THIS TERMS OR IF YOUR JURISTDICTION DOES NOT ALLOW THE
EXCLUSION OF WARRANTY AND LIABILITY AS STATED ABOVE :( YOU SHALL NOT USE THIS
SOFWARE!

(Should I add: "RETURN THE PACKAGE TO YOUR DEALER FOR A FULL REFUND"? :-)

This software is freeware. Non- exclusive permission to use this software in
its unmodified form for the purpose of building applications hereby granted.

You may freely distribute this software, but you must keep all files, including
this documentation, together and unaltered.

You may further sell applications build using WUSTUB as described in this
document, but you are not allowed to sell the WUSTUB package as a stand alone
product or as part of a software compilation, except for an usual fee covering
the distribution itself.

THIS SOFTWARE IS COPYRIGHT (C)1996, MICHAEL TIPPACH, ALL RIGHTS NOT EXPLICITELY
GRANTED IN THIS DOCUMENT RESERVED!

ENGLISH: IF YOU MAKE ME WISH I NEVER HAD RELEASED IT, YOU SHOULD ROT IN HELL!


- This Package:
-------------------------------------------------------------------------------

PESTUB.EXE	PE loader and DOS extender stub
CRT.PAS		32 bit CRT- unit sourcecode
CRT.DCU		the latter compiled
README.TXT	you're currently doing it...
WHATSNEW.TXT    Guess!
PMODE.TXT       pmode howto- stuff
WDOSX.TXT       API doc for the DOS extender
TESTALL.PAS	sample program testing a lot of things
MTEST.BAT	hate makefiles, builds TESTALL.EXE
HAVE_FPU.PAS	sample how to detect whether FPU present
PIXEL.PAS       A _working_ version of the mode $13 putpixel
UNIX2DOS.PAS    simple textfile conversion example

- Tech stuff:
-------------------------------------------------------------------------------

Howto:

- compile:               DCC32 -CC YOURPROG.PAS
- make ready for DOS     COPY /B PESTUB.EXE + YOURPROG.EXE FINAL.EXE

FINAL.EXE is now a DOS- program. Easy, isn't it?


- The DOS extender supports almost all DPMI functions as in DPMI 0.9 spec.
  If you like to learn more about the DOS extender, see:

  http://ourworld.compuserve.com/homepages/tippach_krug/wdosx091.htm
  http://www.geocities.com/SiliconValley/Park/4493
  ftp://x2ftp.oulu.fi/pub/msdos/programming/pmode/

  where you can download the most recent version.

  Note that you cannot just take code written for TP 7 16 bit DPMI and
  recompile, 32 bit DPMI API requires 32 bit register passing in several
  places.


- What does not work, anyway?
-------------------------------------------------------------------------------

16 BIT UNITS (TPU) CANNOT BE USED!

Some may recompile as they are, some may need few modifications, some may need
beeing rewritten for 32 bit.

The problem raises if there was no sourcecode along with the TPU. What to do ?
Well, if the author is known and he's a good guy, it may help to write him/her
a few lines explaining the matter so he/she probably would be willing and able
to recompile the unit to .DCU for you.


MEM, PORT... and so on:

Note that this is not a loader thing, merely the compiler doesn't do it
anymore... :(

As of MEM there is a workaround by declaring

mem:  array[0..$7ffffffe] of byte absolute 0; {bug or feature:compiler refuses}
                                              {$7fffffff, but,who actually has}
                                              {2 gigabyte of RAM?             }
memw: array[0..$3ffffffe] of word absolute 0;
meml: array[0..$1ffffffc] of integer absolute 0;

BTW: keep in mind that an integer is 32 bit in Delphi!

address: integer:
value:   byte;
...
value:=mem[address];

but you'll have to modify existing 16 bit code anyway. You're unable to access
video memory directly with MEM, so there is not much use for it.
See PMODE.TXT for a workaround. 


PORT WORKAROUND:

port[$3c7]:=b;  becomes:

asm
  mov edx,3c7h
  mov al,b	{depending on the type of b a formal type casting may}
                {be neccessary.                                      }
  out dx,al
end;


b:=port[$3c7];	becomes:

asm
  mov edx,3c7h
  in al,dx
  mov b,al
end;


What will never work?
-------------------------------------------------------------------------------

The Delphi compiler does not generate FPU emulation code. You need either
a FPU or an (32 bit) emulator to run programs that use REAL types.

See above section about MEM, PORT...


What else can happen?
-------------------------------------------------------------------------------

- At load time you get the message "Unsupported dynalink" or so. This means
  that your program compiles to something that uses a WIN32 API function not
  supported yet.

- At runtime you get a message that looks like the name of a WIN32 API function
  and the program aborts. This means your program called a function I never
  thought it would be called ever.

- You get the classic register dump on screen and the program aborts. This
  means that some sort of a CPU exception occured that has been caught by
  the DOS extender. The reason for this one could be pretty much anything.
  Some Hints:
  exception 00: the well known divide overflow
  exception 0E: most likely an attempt to access memory when there is none
                (invalid pointers and so)
  exception 0D: not very likely unless the program is executing data
                or you messed around with inline assembly (write to CS:...)

- It just bombs. This means that something else went wrong and nobody has
  a clue.

Note: Whatever happens, drop me a note and include as much information as
possible. If you like information about updates and bugfixes and so, let me
also know.

What else should have been said?
-------------------------------------------------------------------------------

Of course you need Delphi 2 from Borland to get all that stuff working.
Yeah, and it seems that you need WIN32 to run the compiler since it uses some
API calls I do not support as of now.

This is not a major loss IMO since who purchased Delphi 2 probably has Windows
too, right?

Yet another one: NEVER try to code things like "CreateWindow" or so.
We're talking about TP/DOS coding here and that is, writing DOS programs.

Last Hint: Delphi 2 supports 32 bit inline assembly, forget about the
"db 66h" 's! The Delphi 2 compiler does some very nice code optimization.
Combined with clever inline assembly I see no reason why a game (or so)
written in "32 bit TP" should run slower than one coded in Watcom C or
whatever.

Have fun!

Wuschel a.k.a. Michael Tippach
