
-------------------------------------------------------------------------------
                                WDOSX V.0.92
-------------------------------------------------------------------------------

Hi everybody out there!

Even if I would like writing docs, it would not look any better since it
isn't one of my strenghts anyway.

OTOH: If I didn't write at least a few lines, nobody would know what to do
with this stuff, right?

So here we go, but don't expect too much :)

0. INTRODUCTION

This is not my first DOS- extender, but it's the first one I release to the
public. You may ask yourself: Hmm... yet another DOS- extender, aren't there
already >1.000.000 out there?
First of all: I do not encourage anyone to use exactly _this_ one, but for
me it is a fun project and now it came to a point where it could be useful
for someone else. Then again, it may be a waste. Who really cares? 
The intention was to write a DOS- extender that is pretty small sized and handy
to use, so we can do all our quick hacks in 32bit too.

This is the second release. V.0.90 has been nuked by myself, though it
wasn't all that bad.

IF YOU ARE NEW TO 32 BIT ASM PROGRAMMING:

   There are other DOS extender packages out, some of them also for free,
   all of them w/ or w/o some features you'd like to have.

   Before starting you should check out at least the free ones to find
   the one that fits best.

   BTW: Note that I haven't any $$$ losses if you decide to not use WDOSX!

   A must_have_seen_before is TRAN's PMODE. This is some sort of a classic,
   so most people know it and you will get a lot of help on usenet if you
   encounter problems.

   You should also consider the fact that this DOC is not an introduction into
   DPMI and/or 32 bit programming, so you'll be unable to use WDOSX without
   some basic knowledge on the subject.


IF YOU ARE NOT SO NEW TO 32 BIT ASM PROGRAMMING:

   C'mon, give it a try!

WHOAMI (the author):

Michael Tippach
Stockartstrasse 27
04277 Leipzig, Germany
Phone/Fax: 49 341 3028848
                 
email    : tippachm@dialin.deh.de               (preferred)
           tippach@metronet.de                  (very buggy provider)
           heiko.friedel@phil.tu-chemnitz.de    (if above don't work)


WHATISTHISSTUFFABOUT:

WDOSX is just another DOS- extender for 32 bit ASM programming. It supports
DPMI/VCPI/XMS/RAW memory allocation, hardware interrupt autopassup and other
nice features.

WDOSX can easyly be incorporated into the final .EXE - file, increasing its
size by somewhat around 8k.

The archive should contain the following files:

WDOSX.TXT    -  THIS FILE
WHATSNEW.TXT -  MAINLY A PRESENTATION OF MY VERY OWN STUPIDITY (BUGFIXES)
WDOSX.DX     -  THE DOS-EXTENDER STUB (RENAMED EXECUTABLE)
EXAMPLE.ASM  -  ASM EXAMPLE, DOES SOMETHING BUT DON'T TAKE IT TOO SERIOUS!
MAKEEXAM.BAT -  MAKE EXAMPLE (TASM + TLINK REQ'D)
MOUSE.ASM    -  SAMPLE CODE FOR MOUSE EVENT HANDLER
HEADER.ASM   -  SAMPLE STARTUP CODE FOR MIXING C AND ASM (BC4)
HELLO.C      -  AS THE FILENAME IS TELLING YOU
C.BAT        -  GET HELLO.C RUNNING WITH WDOSX
FILE_ID.DIZ  -  GUESS WHAT!

Even though there've been a lot of bugfixes since version 0.90 this one
is far from beeing perfect!

1. 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 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 protected mode 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 WDOSX as a DOS extender stub, but
you are not allowed to sell this software 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!

BTW:
            ________
     CLICK |__HERE__| TO DOWNLOAD THE SOURCECODE NOW!

     There's no reason why I shouldn't release the sourcecode, but, if you
     read this DOC you probably imagine how messy the source may look like :)
     Another reason: I wanted to keep the package size as small as possible,
     -> actually not _everyone_ is _really_ interested in that mess and some
     people with slow and/or unreliable connections will thank me for the idea.
     If you're _born ready_ to read my sources, hmm...  mail me.

     But note: I'll never ever comment every line you didn't understand
     (maybe I _will_ do though, but pleeaaase, don't check that out!)

     And YES: just another reason is that I want feedback!

     Anyway: I do not want people to distribute modified versions of the source
     code. If you think you're better in writing DOS extenders than me, hmm...
     write your own from scratch! If you have suggestions how to make it a
     better piece of code, send me a mail and you're welcome to join the party.
           

2.   THE FUN STUFF
2.1. HOWTO BUILD YOUR 32 BIT PM- APPLICATION?

     COPY /B WDOSX.DX + 32_BIT_EXE.EXE FINAL_EXE.EXE

That's it! WDOSX.DX is basically a stub that will load your 32 bit program
into extended memory and execute it there.

Ahemm... example given:

----- test.asm -----------------------
.386
myseg		segment use32
assume cs:myseg,ds:myseg

bla bla bla bla

start:

init bla bla

further bla bla bla, using huge amount of memory

outtahere:
                mov     ax,4c00h
                int     21h

myseg           ends
end             start
--------------------------------------

This one (of course not _this_ one) can be compiled:

TASM TEST.ASM
TLINK /3 TEST

Now we have a TEST.EXE file that will crash the machine if we try to run it.
So we say:

COPY /B WDOSX.DX+TEST.EXE MYDEMO.EXE

MYDEMO.EXE should run then. Isn't it easy?


2.2. HOWTO CODE THE 32 BIT STUFF

Do it as you usually would do it. If your code runs with this DOS extender,
I see no reason why it should not run with _every_ generic DPMI 0.9 compliant
DOS- extender (except some minor modifications, not worth considering).
WDOSX checks for a DPMI host and, if it found one,almost all of the WDOSX stuff
is bypassed, else WDOSX emulates the DPMI- host (hmm... a subset of DPMI 0.9,
as of today, see below).

Some restrictions:

1. the initial EIP must be less then 64k
2. the flatmode overlay size is limited to 1Mb
   (this does not prohibit the use of another overlay behind)
3. Fixups are EVIL! WDOSX does not process fixups in your flatmode overlay.
   Hey, we're in 32 bit protected mode here, so why say stupid things like:

          mov ax,@data
          mov ds,ax
   ??????????????????????????
   Don't hardcode selectors, store them in variables instead and everything
   will be fine!

Note that restrictions 1+2 are results of the overlay technique I use.
TLINK will crash (yeah, really!) if you try to push the limits 1+2.


Entry conditions on start:

cs:                     guess what!
ds,ss:                  alias(cs)
es:                     selector(PSP)
esp:                    size of flatmode ovelay + 1k = initial segment size
                        dword aligned
anything else:          garbage
virtual interrupts:	disabled


Not supported so far:

- GET/SET EXCEPTION HANDLER:

             This is because I didn't need that.

             WDOSX, if running without DPMI, will report most exceptions by
             throwing out registers and stuff and terminate the program then
             (as we all know and enjoy :)

             As usual, exceptions occuring in real- or V86- mode are not
             reported.

             Since the build-in exception handler is called via an interrupt
             gate, the stack has to be intact for proper exception handling.          
             (C'mon, this is a DOS- extender, not an operating system!)
 
             This works as well that I tended to insert a "mov cs:[0],al"
             as some sort of a breakpoint in my app code for debugging.
             You don't use debugging techniques like that, do you?

- RAW MODE SWITCH, SAVE/RESTORE STATE AND STUFF

             Hate to say that again, but: I didn't need that as of today.
             There are, of course, raw mode switch procedures in the kernel
             and it wouldn't be a big deal to write the interface for them...
             Hmm... maybe next release.


- ALLOCATE SPECIFIC LDT DESCRIPTOR:

             Err... hmmm... this one will never get into WDOSX, because while
             running in RAW/XMS/VCPI mode, we do not have a LDT, everything
             is in the GDT, thus the selectors specified for this function to
             be free actually aren't.

             Who cares?


-------------------------------------------------------------------------------
DPMI- 0.9- functions supported so far...
-------------------------------------------------------------------------------

LDT- MANAGEMENT:

0000	ALLOC LDT DESCRIPTORS
0001	FREE LDT DESKRIPTORS
0002	SEGMENT -> SELECTOR
0003	GET SELECTOR INCRMENT
0006	GET SEGMENT BASE
0007	SET SEGMENT BASE
0008	SET SEGMENT LIMIT
0009	SET ACCESS RIGHTS
000A	CREATE ALIAS
000B	GET DESCRIPTOR
000C	SET DESCRIPTOR

DOS- MEM:

0100	ALLOC DOS- MEM
0101	FREE DOS- MEM
0102	MODIFY DOS- MEM

INTERRUPTS:

0200	GET REALMODE INTERRUPT VECTOR
0201	SET REALMODE INTERRUPT VECTOR
0204	GET PM INTERRUPT VECTOR
0205	SET PM INTERRUPT VECTOR

TRANSLATION SERVICES:

0300	SIMULATE REAL MODE INTERRUPT
0301	CALL REALMODE PROCEDURE (RETF)
0302	CALL REALMODE PROCEDURE (IRET)
0303	ALLOCATE REALMODE CALLBACK
0304	FREE REALMODE CALLBACK

VERSION:

0400	GET DPMI VERSION

MEMORY MANAGEMENT:

0500	GET FREE MEM
0501	ALLOC MEM
0502	FREE MEM
0503	RESIZE MEM

VIRTUAL MEMORY MANAGEMENT:

0600	LOCK LINEAR REGION
0601	UNLOCK LINEAR REGION
0602	UNLOCK REALMODE REGION
0603	RELOCK REALMODE REGION
0604	GET PHYSICAL PAGE SIZE

DEMAND PAGING:

0702	MARK PAGE PAGEABLE
0703	DISCARD PAGE

PHYSICAL MEMORY:

0800	MAP PHYSICAL REGION

VIRTUAL ITERRUPTS:

0900	GET AND DISABLE VI STATE
0901	GET AND ENABLE VI STATE
0902	GET STATE

-------------------------------------------------------------------------------
Flatmode support API			
-------------------------------------------------------------------------------

To make things _really_ easy to code, I started to implement some sort of
an API. All functions are called via INT 21H and (except 21/FFFFH) are
the 32 bit representation of their respective DOS pendants.
This is not very complete, but it will be extended as soon as I need some other
DOS- functions frequently OR you send me mail that I should incorporate a
specific function ASAP, cause you desperatly neeeed it.

A couple of functions are new in v 0.91 and in v 0.92 I added yet another two.

Note that this stuff can also be hand- coded using DPMI functions, but
IMO this is quite a pain to do over and over again.

OTOH: Using this API will make it more difficult to port your code to other
DOS- extenders, using DPMI functions usually wont!

Supported so far:

-------------------------------------------------------------------------------
21/09 - DOS- write string to console
-------------------------------------------------------------------------------

DIFFERENCES WDOSX/DOS:

- DOS uses DS:DX, WDOSX uses DS:EDX

-------------------------------------------------------------------------------
21/39 - DOS- MKDIR
-------------------------------------------------------------------------------

DIFFERENCES WDOSX/DOS:

- DOS uses DS:DX, WDOSX uses DS:EDX

-------------------------------------------------------------------------------
21/3A - DOS- RMDIR
-------------------------------------------------------------------------------

DIFFERENCES WDOSX/DOS:

- DOS uses DS:DX, WDOSX uses DS:EDX

-------------------------------------------------------------------------------
21/3B - DOS- CHDIR
-------------------------------------------------------------------------------

DIFFERENCES WDOSX/DOS:

- DOS uses DS:DX, WDOSX uses DS:EDX

-------------------------------------------------------------------------------
21/3C - DOS- create
-------------------------------------------------------------------------------

DIFFERENCES WDOSX/DOS:

- DOS uses DS:DX, WDOSX uses DS:EDX

-------------------------------------------------------------------------------
21/3D - DOS- open
-------------------------------------------------------------------------------

DIFFERENCES WDOSX/DOS:

- DOS uses DS:DX, WDOSX uses DS:EDX

-------------------------------------------------------------------------------
21/3F - DOS- read
-------------------------------------------------------------------------------

DIFFERENCES WDOSX/DOS:

- DOS uses DS:DX, WDOSX uses DS:EDX
- DOS uses CX = bytes to read, WDOSX uses ECX
- DOS returns AX = bytes read, WDOSX returns EAX = bytes read

This means: YES! You _can_ read more than 64k at once!

-------------------------------------------------------------------------------
21/40 - DOS- write
-------------------------------------------------------------------------------

DIFFERENCES WDOSX/DOS:

- DOS uses DS:DX, WDOSX uses DS:EDX
- DOS uses CX = bytes to write, WDOSX uses ECX
- DOS returns AX = bytes written, WDOSX returns EAX = bytes written

This means: YES! You _can_ write more than 64k at once!

-------------------------------------------------------------------------------
21/41 - DOS- delete
-------------------------------------------------------------------------------

DIFFERENCES WDOSX/DOS:

- DOS uses DS:DX, WDOSX uses DS:EDX


-------------------------------------------------------------------------------
21/43 - DOS- get/set file attribute
-------------------------------------------------------------------------------

DIFFERENCES WDOSX/DOS:

- DOS uses DS:DX, WDOSX uses DS:EDX

-------------------------------------------------------------------------------
21/47 - DOS- get current directory
-------------------------------------------------------------------------------

DIFFERENCES WDOSX/DOS:

- DOS uses DS:SI, WDOSX uses DS:ESI

-------------------------------------------------------------------------------
21/56 - DOS- rename
-------------------------------------------------------------------------------

DIFFERENCES WDOSX/DOS:

- DOS uses DS:DX, WDOSX uses DS:EDX
- DOS uses ES:DI, WDOSX uses ES:EDI

-------------------------------------------------------------------------------
21/5B - DOS- create new file
-------------------------------------------------------------------------------

DIFFERENCES WDOSX/DOS:

- DOS uses DS:DX, WDOSX uses DS:EDX

;------------------------------------------------------------------------------

EXAMPLE:

;This sample code copies a file 'interrup.lst' (THANKS AGAIN AND AGAIN AND
;                                                AGAIN AND..., RALF BROWN!!!)
;into another file 'interrup.2nd', because only _one_ copy of this wonderful
;DOC is _not_ enough :) ------> This is _my_ way of giving credit, hope you
;get it right!
;(Another reason is just that while testing I needed a file that
; -was huge enough 
; -fitted into memory
; -was an ASCII file, so we could easily verify results)
;
;As of version 50 this file is somewhat around 4.5 MB

.386p
code    segment use32
assume  cs:code,ds:code

infile  db 'interrup.lst',0
outfile db 'interrup.2nd',0
errmsg  db 'some sort of error!',0dh,0ah,'$'

start:
;------ enable interrupts ------

        mov ax,0901h
        int 31h

;------ alloc memory (see below)

        mov ax,-1
        mov edx,500000h   ;5 MB is a good choice :)
        int 21h
        jc some_sort_of_error
        mov esp,edx       ;adjust stackpointer
       
;------ open input file --------

        mov edx,offset infile
        mov ax,3d00h
        int 21h
        jc some_sort_of_error
        mov bx,ax

;------ read input file --------

        mov edx,offset filebuffer
        mov ecx,-1	;read until eof
        mov ah,3fh
        int 21h         ;this could take a while depending on your hardware
        jc some_sort_of_error
        push eax        ;store bytes read, should be filesize

;------ create output file -----

        mov edx,offset outfile
        mov ax,3c00h
        sub cx,cx
        int 21h
        jc some_sort_of_error
        mov bx,ax

;------ write output file ------

        pop ecx         ;get bytes to write
        mov edx,offset filebuffer
        mov ah,40h
        int 21h         ;could also take a few seconds
        jnc copy_ok

;------ simplex error handler --

some_sort_of_error:
        mov edx,offset errmsg
        mov ah,9
        int 21h
        mov ax,4cffh
        int 21h

;------ terminate --------------

copy_ok:
        mov ax,4c00h
        int 21h

align dword     ;hint: the API will do REP MOVSD whenever possible!

filebuffer label near

code    ends
end     start

Yeah, and that's all. Try to write the same piece of code for 16 bit DOS!

-------------------------------------------------------------------------------
INT21H     AX = FFFFH: RESIZE FLAT SEGMENT
-------------------------------------------------------------------------------

THIS IS A PROPRIETARY FUNCTION, NOT A DOS- FUNCTION!

ON ENTRY: EDX = NEW SIZE
RETURNS : CF CLEAR ON SUCCESS, CF SET: ERROR, NOTHING DONE

This one is needed because with INT 31H you cannot resize the segment you're
currently running in. Using this call, you can. But NOTE: This call assumes
to get called from your initial flat segment, don't call from anywhere else!

USAGE:

 mov ax,0ffffh
 mov edx,400000h           ;new size = 4 MB
 int 21h
 jc what_the_hell_happened ;should only occur if there's not enough memory
 mov esp,edx               ;adjust stack pointer on top of segment

_______________________________________________________________________________

3. IF YOU ENCOUNTER PROBLEMS

There _are_ bugs in WDOSX (I know,'cause I already caught+fixed a lot of them).

Before you report any bugs to me, please try to collect as much information as
possible.

Further try to make sure that the strange behaviour _really_ is a result of a
possible bug in WDOSX. (IOW: look at your source code again and again and...)

Include the sourcecode that made the bug show up (if you could), or at least,
write a sample piece of code that will reproduce the error.
(from my own experience I know that the latter is a good method to make 99.9%
 sure the source code is clean)

Include a short description of the circumstances (hardware, software). If the
bug only shows up in some configurations, also report the configurations
where everything is fine.

In short: Give me a chance to fix it!(You're programmers, you know what I mean)

Thank you for supporting free software!
_______________________________________________________________________________

What comes next? Hmm...how about interface libraries for several C/C++
compilers? Interested?
I already made up an interface for Borland Delphi 2 with this extender.


That's all folks. Comments and suggestions welcome!

HAVE FUN!

(Deutsche Dokumentation erhaeltlich, Mehl schicken!)

Leipzig, Germany, october '96
Wuschel a.k.a Michael Tippach
