------------------------------------------------------------------------------- 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