Unofficial DOS/4G(W) documentation.

Contents:
1Description
2Executable formats
3Memory management
4Interrupt services and APIs
5Int21h extensions
6Int31h functions
7Additional Int21h functions
8DOS/4G API
9DOS/4G(W) api packages
10Dynamic-Link Libraries
11Configuration

1) Description

DOS/4G, DOS/4GW, DOS/4GW Professional and DOS/16M are dos extenders from Tenberry Software (old name Rational Systems). DOS/4GW is most common because it is supply with WATCOM C/C++, so it is very popular among programmers. DOS/16M is a 16-bit dos extender, DOS/4G(W) based on it. Unlike DOS/4G it can not load DLLs and run TSR programs (since version 1.9). DOS/4GW does not support INT 31h subfunctions 301h, 302h, 303h, 304h, 305h, 306h, 504h, 505h, 506h, 507h, 508h, 509h, 50Ah, 702h, 703h. DOS/4GW can not be bound in executable file. DOS/4GW Professional does not support INT 31h subfunctions such as 305h, 306h, 504h, 505h, 506h, 507h, 508h, 509h, 50Ah. It can not run TSR program and can not load DLLs. But it can be bound in executable file. And unlike DOS/4GW its Virtual Memory Manager permits more than 32Mb virtual memory. Both DOS/4GW and DOS/4GW Professional supports auto passup interrupt range 08h-2Eh (except 21h). Unlike them DOS/4G allow specify additional interrupt for auto passup. It can also load DLLs, run TSR programs. It support all DPMI 0.9 specification and some subfunction from DPMI 1.0 like 504h and 505h. It can be bound in executable or run standalone.

2) Executable Formats

Initial DOS/16M supports EXP(BW) file format. It is 16-bit segmented executable file format. It can be created with special "GLU linker" from Tenberry software. Later versions of DOS/16M can load NE-exe file format which is used in Microsoft Windows 3.x and IBM OS/2 v1. It is also segmented executable file format. DOS/4G is a 32-bit dos extender so it can load 32-bit executables in LE-exe and LX-exe file formats. Such executables used in IBM OS/2 v2 and Microsoft Windows 3.x and 9.x (device drivers). Support for LX-exe is not documented for DOS/4GW, but it can load LX executable. To build LX-executable for DOS/4G(W) set 'system' in WATCOM linker for 'dos4gnz'. See file 'wlsystem.lnk' in '%WATCOM%\BINW' or '%WATCOM%\BINW' directory for details. DOS/4G(W) can not load most LX executables created for IBM OS/2 v2 propertly cause of absense of relocation table in file. Such files must be loaded at specific linear address and DOS/4G(W) can not load them without its own virtual memory manager. Since version 2.60 DOS/4G supports PE-exe file format which is used in Microsoft Windows NT and Microsoft Windows 9x. It is 32-bit flat model executables as LE or LX. But DOS/4G(W) still sipports EXP(BW) file format. DOS/4G can load any EXP(BW) application but DOS/4GW and DOS/4GW Professional can load on there EXP(BW) application: Watcom Debugger Trap File (RSIHELP.EXP), Watcom Execution Sampler (WSAMPRSI.EXE) and Tenberry 32-bit Debugger (D32.EXE). Some DOS/4G can load NE-exe file like later versions of DOS/16M and probably some exclusive versions of DOS/4G can load file formats not mentioned here. DOS/4GW and DOS/4GW Professional does not support DLLs since version 1.9. DOS/4GW Professional supports compressed Linear Executables since version 2.61.

3) Memory management

One of main dos extender tasks - memory management. DOS/4G(W) was originaly designed to run 32-bit flat model applications. So by default it load application in flat linear address space. Bases of CS and DS are equal and are zero, so address space 00000000h- 00100000h covers DOS memory under first megabyte. Typicaly without external dpmi DOS/4G (W) loads programs at address greater than 400000h. DOS/4G(W) provides memory management functions via INT 21h (AH = 48h, AH = 49h) and INT 31h (100h, 101h, 102h, 500h, 501, 502h, 503h, 504h-50Ah (DOS/4G), 702h-703h(DOS/4G and DOS/4GW Professional), 800h, 801h). Memory management includes free memory memory, virtual memory support (if enabled) DOS memory management, physical memory mapping. DOS/4G(W) provides standart memory menagement according DPMI specification and own memory management via INT 21h extension. Via INT 21h AH=48 it allocates free memory and selector for that memory block. Address of allocated memory depends on DOS/4G(W) memory allocation strategy. DOS/4G(W) has own virtual memory manager which can be enabled or disabled. In bound application it is enabled by default or just stripped from application. DOS/4G(W) virtual memory manager works with memory pages and it's provides memory locking (INT 31h 600h, 601h) and fine virtual memory control (INT 31h 702h, 703h). Virtual memory manager (but not DOS/4G(W)) enables memory paging (sets bit 31 in CR0 register), i.e. in absense of EMM386 or any external DPMI paging disabled.

4) Interrupt services and APIs

DOS/4G(W) provides interrupt management and extends BIOS,DOS,MOUSE interrupt api. Also it provides INT 31h API if there is no external dpmi. DOS/4(W) has auto passup range for interrupts 08h-2Eh, i.e. if any of that interrupt occured in real mode, extender reflects it to protected mode. For interrupts occured in protected mode externder searches interrupt handler in protected and if none found pass interrupt down to real mode. DOS/4G allow any interrupt to reflected from real to protected mode. DOS/4G(W) extends INT 10h (BIOS), INT 21h (DOS), INT 33h (MOUSE) interrupt APIs. It translates protected mode pointers given in DS:EDX, ES:EBX and other registers to real mode adresses and transfer memory buffers above 1 Mb to DOS memory making possible to access them from real mode. It also support mouse callbacks which mouse driver does. DOS/4G(W) reflect mouse driver calls to protected mode. Beside of this DOS/4G(W) supports additional INT 21h functions like DOS/16M. To generate some interrupt in real mode, INT 31h function 300h provided.

5) INT 21h extensions

[will be added later]

6) INT 31h functions

[will be added later]

7) Additional INT 21h functions

1. Identification.

IN:

EAX = 0FF00h

EDX = 078h

OUT:

EAX = 04734FFFFh (if DOS/4G(W), DOS/16M seems returns AX = 0FFFFh)

Notes:

this function supported by some other dos extenders like CAUSEWAY, PMODEW, DOS/32A and ZRDX 0.47 return 0FFFF3447h instead of 04734FFFFh, WDOSX 0.96 returns 0FFFFh instead of 04734FFFFh

2. Set Memory Allocation Strategy.

IN:

EAX = 0FFFFh

EDX = [strategy]

OUT:

AL = [old strategy]

Known strategies:

0 - prefer extended memory

1 - prefers convertional memory

2 - force extended memory

3 - force convertional memory

4 - force convertional, allocate selectors for transparent addressing

5 - transparent, but aligned for use as stack

Notes:

Memory allocation strategy used for memory allocation via INT 21h interface. If strategy forces some type of memory, allocation will be issued with this type of memory and if no memory function fails. If strategy prefers some type of memory, allocation will be issued with this type of memory and if no such memory allocation will be issue with another type of memory. This often makes memory allocation via INT 21h (AH=48h) more conveniet than via INT 31h (AX=100h, AX=501h).

8) DOS/4G API

DOS/4G api available only in DOS/4G (and DOS/4GW prior version 1.9). This is an api called vendor specific api. To obtain entry point set EAX = A00h, DS:EDX = address of "RATIONAL DOS/4G" and call INT 31h. On return ES:EDI will contain address of entry point (32-bit far function).

Get package function entry.

IN:

EAX = 000000000h

EDX = address of function name

EBX = address of package name

OUT:

EAX = 16:16 far ptr to entry point

Stub function.

IN:

EAX = 000000001h

OUT:

EAX = 0ABCD1234h

Call 16-bit function.
IN:

EAX = 000000002h

ECX = number of dwords in the stack (only for DOS/4G 2.00 and later, older versions of DOS/4G(W) ignore this value)

EDX = 16:16 far ptr to function

EBX = address of stack parameters

OUT:

EAX = function return value in DX:AX

Stub function.

IN:

EAX = 000000003h

OUT:

EAX = 16:16 far ptr to function:

"mov ax, 666h"
"retf"

Interrupt control api. (available since version 1.8)

IN:

EAX = 000000004h

EDX = interrupt number

EBX = subfunction number

OUT:

EAX = return value

Subfunctions:

00h - Set 'AutoPassup' for specified interrupt.
Retuns: 1 - if success and 0 - if failed

01h - Unknown function.

02h - Unknown, calls "D32SetCookedPassdn" in 1.8, just returns 1 since DOS/4G 1.97

03h - Unknown, calls "D32GetIntState" in 1.8, just returns 1 since DOS/4G 1.97

04h - Unknown, calls "D32SetIntDefault" in 1.8, just returns 1 since DOS/4G 1.97

05h - Unknown function, it just compares interrupt number with 20h and returns 1 or 0

9) DOS/4G(W) api packages

Package is a set of functions and(or) variables which can be used by other module or program so they are "exported" from module where they were implemented. Since EXP(BW) executable doesn't support any export technique, packages available through DOS/4G(W) kernel data selector. Usually this selector is 20h (without external DPMI hosts). When program starts GS register contatain that selector (for DLL startup see FS register). Watcom C/C++ startup code its value to __D16InfoSeg valriable. Pointer to first package located at __D16InfoSeg:42h, that is 16-bit far pointer. Package can be described as following structure (all pointers are 16-bit):

typedef struct package
{
struct package far *next_package; /* Pointer to next package in chain */
char far *package_title; /* Optional pointer to ascii name */
unsigned char major_rev; /* Optional revision levels */
unsigned char minor_rev;
int system_action_count; /* System action count */
ACTION_PACK far *system_action; /* Pointer to vector of pre-defined */
int user_action_count; /* Optional user count */
ACTION_PACK far *user_action; / * Pointer to vector of user_defined*/
} PACKAGE;

Program must examinate all packages from the begining to find required package by "package_title" than search entry point in "system_action" and "user_action". Fields "system_action" and "user_action" are pointers to arrays of ACTION_PACK structures. Size of that arrays defined by according variables "system_action_count" and "user_action_count".

Remark: Such technique can be used in 16-bit programs and DOS/4GW 32-bit programs. DOS/4G provides api support for packages so entrypoints can be easialy found via api call (EAX = 0). See: DOS/4G API.

Remark: To take advantages of flat memory model 32-bit appliation can translate 16-bit far pointers to 32-flat near pointers using INT 31h function 0006h (get selector base).

typedef struct action_pack
{
char far *action_name;
ACTION far *action;
} ACTION_PACK;

Standart DOS/4GW 1.4 - 1.97 contains 7 packages:

1) "DOS16PKG" - Api of DOS/16M kernel

2) "EXPLOAD" - Api of EXP(BW) loader module

3) "LINEXE" - Api of LE/LX exe loader

4) "INT31" - Api of INT31W module (obsolette, only system calls are valid)

5) "VMM4G" - Api of virtual memory manager (present only when 'WVMM' enabled)

6) "ERROUT" - Api for writing error messages (built in DOS/4GW kernel)

7) "D32_KERNEL" - Api of DOS/4GW kernel

DOS/4G contain variable number of package depending on its version:

1) "DOS16PKG" - Api of DOS/16M kernel (standart)

2) "EXPLOAD" - Api EXP(BW) loader (this loader can be removed from bound DOS/4G and DOS/4GW Professional)

3) "VMM4G" - Api of virtual memory manager ('VMM4G' also can be removed from bound DOS/4G and DOS/4GW Professional)

4) "LINEXE" - Api of linear executable loader (nowdays built in DOS/4G kernel)

5) "INT31" - Api of INT31 module (nowdays also built in DOS/4G kernel and also it is only for system calls)

6) "CONFIG4G" - Api of DOS/4G confing program CONFIG4G (introduced in DOS/4G 1.9 and DOS/4GW Professional 2.00)

7) "SEGEXE" - Api of segmented executable(usually NE) loader (present in some versions of DOS/4G)

6) "ERROUT" - Api for writing error messages (built in DOS/4G kernel)

9) "PELOAD" - Api of PE-exe loader (introduced in DOS/4G 2.60)

10) "D32_KERNEL" Api of DOS/4G kernel (Standart)

Standart DOS/4GW Professional 1.95 - 2.61 packages:

1) "DOS16PKG" - Api of DOS/16M kernel (standart)

2) "EXPLOAD" - Api of EXP(BW) loader (removed from bound DOS/4GW Professional)

3) "VMM4G" - Api virtual memory manager ('VMM4G' also can be removed from bound DOS/4GW Professional)

4) "LINEXE" - Api of linear executable loader (nowdays built in DOS/4GW kernel)

5) "INT31" - Api of INT31 module (nowdays also built in DOS/4GW kernel, supports only system calls "INIT" and "DEINIT")

6) "ERROUT" - Api for writing error messages (build in DOS/4GW Professional kernel)

7) "D32_KERNEL" - Api of DOS/4GW Professional kernel (Standart)

Other packages:

1) "USERERR" - User-created module for error message localization (ONLY DOS/4G)

2) "DVX_Process_Manager" - Unknown package, never seen

3) "REX_LOADER" - It seems api of REX-loader, never seen

4) "DBGAGENT" - Api of some debugger, never seen

10) Dynamic-Link Libraries

[will be added later]

11) Configuration

[will be added later]

Send any questions to rgmroman@narod.ru

Hosted by uCoz