HX DOS Extender
A. About HX DOS-Extender
HX DOS-Extender is a free DOS extender with built-in Win32 PE file format
support. Usually the purpose of a DOS extender is to make protected-mode
features available for DOS applications. HX fully supports this goal, but
goes some steps further. A Win32 API emulation layer is part of HX which
allows many Win32 console applications to run in DOS. This emulation goes
far beyond similiar approaches in other extenders (Borland's PowerPack, WDOSX
or Phar Lab TNT). Furthermore HX implements - limited - support for windows,
DirectDraw, GDI and even OpenGL graphics. This allows to run "simple" Win32
GUI apps in DOS as well.
Many development environments which support creating Win32 console
applications are compatible with HX, among them are:
Since HX's built-in Win32 emulation is pretty mature, most of these
compilers/assemblers will run with HX in plain DOS as well.
- Open Watcom C++
- Digital Mars C++
- MinGW (uses GCC)
- CygWin (uses GCC)
- MS Visual C++, including the free version of MS Visual C++ Toolkit 2003
- Borland C++, including the free version of C++ Builder Command Line Tools
- LADSoft CC386
- Pelles C
- LCC-Win32 (C compiler)
- Borland Delphi
- Free Pascal (Win32)
- Pascal Pro
- Virtual Pascal (Win32)
- FreeBasic (Win32)
- MicroFocus Object Cobol
- XDS Modula II
- JWasm, Masm, Tasm, Poasm, Wasm, Fasm, Lzasm, Nasm, Goasm, ...
Other tools suitable to create HX PE binaries are:
HX consists of
- HXRT, HX DOS extender runtime
- HXGUI, HX DOS extender GUI extension
- HXDEV, HX DOS extender developer support
- HXSRC, HX DOS extender source
B. HX Runtime
The extender runtime includes all files needed to execute 32bit DOS extended apps.
If you just want to run some Win32 console applications in DOS you don't need
to care much about these binaries, because most of them are loaded automatically
just when they are needed. The one thing one has to do to activate HX's Win32
support in pure DOS is to run HXLdr32, which is a tiny DOS TSR.
- DPMI server HDPMI. Used in plain DOS only.
- PE file loader DPMILD32
- Win32 API emulation dlls (DKRNL32, DUSER32, DADVAPI, ...)
- Helper tools HXLdr32 and PEStub
HDPMI is a free DPMI server. Its features are:
See HDPMI's Readme for more details.
- fully supports DPMI V0.9
- most of DPMI V1.0 functions are implemented as well
- client address space may be up to 4088 MB
- no limit for physical memory usage, 4 GB supported
- full DOS API translation services included
- both 32bit and 16bit clients are supported
- the server's DOS memory usage is below 13 kB, including an 8 kB translation buffer
- is compatible with Bochs, Qemu, DosBox, VMWare and VirtualBox.
Virtual PC 2007 needs a modified HDPMI version, can be downloaded here
DPMILD32 is a PE file loader required to load binaries into memory.
It is not restricted to HX extended applications, but may also be used to
load standard Win32 console apps as DPMI clients, provided that all
Win32 functions called by the application are included in the emulation layer.
View dpmild32.txt for more details.
Win32 API Emulation
The Win32 API Emulation included in the HX runtime package consists of:
DPMILD32 will provide for the translation of the module names, so if a PE
executable has references to KERNEL32.DLL, DPMILD32 will try to resolve
these imports by loading DKRNL32.DLL, for example. This means that any
development tool being able to create Win32 console applications will most
likely be compatible with HX DOS extender. While running under a Win32
OS like win9x or winxp, such console apps are executed as true Win32 apps
and neither DPMILD32 nor the Win32 API emulation dlls are loaded.
These will only be needed in Non-Win32 environments (that is, plain DOS,
DOSEmu, Windows 3.1 or OS/2 Dos boxes) and there exist 2 ways to activate
the Win32 emulation:
- DKRNL32.DLL: emulates KERNEL32.DLL
- DADVAPI.DLL: emulates ADVAPI32.DLL
- DUSER32.DLL: emulates USER32.DLL
- DGDI32.DLL: emulates GDI32.DLL
- DDDRAW.DLL: emulates DDRAW.DLL
- OLE32.DLL and OLEAUT32.DLL
As already mentioned HX supports simple graphics (GUI) applications.
These may use Win32 GDI or DirectDraw for their output, both is possible with
HX. As with Win32 console applications the GUI apps will run as Win32
processes in Win32 environments, only in DOS they will run as DPMI clients
and the GDI/DirectDraw emulation dlls will be used. The emulation
requires a VESA 2.0 BIOS to work. Because in DOS there is no acceleration
available the emulation may be a bit slow. Some applications may run sufficiently
fast, however, and it may be a way to overcome the non-existent support of VESA LFB
in Windows NT/2K/XP.
HXLdr32: this is a TSR program which will hook DOS interrupt 21h and check
all programs to be launched if they are PE binaries. If this is true, DPMILD32 will be
started to run the program. This approach is the recommended one because no binaries
have to be modified. HXLdr32 will refuse to install itself if there is already support for
PE file loading, as it is the case in win9x/winxp DOS boxes.
PEStub: this tool can be used to change the MZ stub of PE applications
which under plain DOS displays a message like "This program requires Windows"
or something similiar. The new stub, which will gain control in plain DOS only, will
load DPMILD32 to run the binary as DPMI client. The stub's size is only 512 bytes,
so the total size of the binary won't increase too much.
View compat.txt for a list of Win32 console apps successfully tested to run with the Win32 emulation.
C. HX GUI Extension
Running GUI Applications
With the HXGUI extension it is possible to run simple GUI applications with HX in DOS.
"Simple" in this context means applications which use just one window as user
interface. Such apps usually are based on SDL, DirectDraw and/or OpenGl.
To use HXGUI a VESA V2.0 BIOS with support for linear frame buffer access (LFB) is required.
The Win32 API Emulation is enhanced by HX GUI and consists of:
Some more dlls are included just as dummies:
- DINPUT.DLL: emulates DINPUT.DLL
- DSOUND.DLL: emulates DSOUND.DLL
- WINMM.DLL: emulates WINMM.DLL
- DCIMAN32.DLL: emulates DCIMAN32.DLL
- WSOCK32.DLL: emulates WSOCK32.DLL
Running OpenGL Applications
With the help of the Windows 9x binaries OPENGL32.DLL and GLU32.DLL is is
possible to run OpenGL applications on DOS with HXGUI. However, this OpenGL
implementation is pure software without hardware acceleration, so don't
expect it to be too fast.
Screenshot from an OpenGL Win32 sample written by Frank Charlet, running in DOS, 256 colors.
If you don't own a copy of Windows 9x: there should be a redistributable version
of OpenGL for Windows 95 available. Search for OPENGL95.EXE in the Web. Or download
the plain binaries from either the
MS FTP Server
SDL (Simple Directmedia Layer) is an Open Source effort to provide a
multi-platform API for games, emulators, .... There are ports for various
platforms available. As far as HXGUI is concerned, support for video, (wave) audio,
keyboard, mouse, timer and threads is implemented.
Please be aware that there is no special version of SDL for HX (or DOS)
available. It is the
Win32 port of SDL which can be used with HX. The SDL
site is at http://www.libsdl.org/index.php,
where the source code of all ports can be found.
Running QEMU with HX
QEMU is a PC emulator application available for many platforms.
The Win32 ports of QEMU 0.7, 0.8 and 0.9, which are based on SDL, were
successfully tested to run with HXGUI. The main advantage of QEMU running
in DOS with HX is that one can try all kinds of operating systems without the
need to install them on the physical HD. Here FreeDOS is booting inside a MS-DOS session:
Some notes about running QEMU under HX
- please be aware that QEMU requires huge
amounts of virtual memory. Since HX doesn't support a swapfile, virtual
memory is identical to physical memory. For example, running QEMU with a
128 MB guest requires about 170 MB of RAM.
- don't expect any performance boosts running QEMU on
HX/DOS. If there is a gain by avoiding the overhead of a multitasking environment like windows,
this gain is -more than - lost by the simple fact that in DOS there is no 2D graphics acceleration available.
Running DOSBox with HX
Another interesting SDL application is DOSBox. Running DOSBox in DOS with
HX is not that senseless as it might seem at first glance. There are many
old DOS games which will not run on modern machines, or they will run too fast.
There are also some old games known to have caused lots of trouble even
on older machines, which now run flawless in DOSBox. This is one of those:
D. HX 32-Bit Developer Support
The HXDEV developer support package contains all files required to create 32bit extended DOS apps.
Two file formats are supported by the extender:
- PE file format
- MZ file format
32bit DOS Applications in Win32-PE Format
This is the standard format for HX DOS extender. Since such binaries are
in fact true Win32 applications, all the work to create these apps will be
done by your standard development tool. For HX there isn't much left to do.
So the only things included are
The C runtime libraries are intended to be used by ASM programs, but
of course may be used by C/C++ apps as well if no other C runtime is
- PatchPE, used to convert binaries from Win32-PE to DOS-PE ("PX") format
- Vesa32(s).lib, to simplify using VESA functions in DOS-extended apps
- CrtDll.lib, a static library to link against CRTDLL.DLL (COFF format)
- DCrt32s.lib, a simple static C runtime library (COFF format)
- OWSupp, some files helping to create and debug HX extended apps with Open Watcom
- Samples in ASM, C, Pascal, (Power)Basic and Cobol
32bit DOS Applications in DOS-PE Format
With tool PatchPE one can change a Win32-PE file to a DOS-PE file.
This may be necessary if the application uses features usually not available for
Win32 applications, i.e. it calls DOS INT 21h or it directly accesses I/O ports.
The tool will change just one byte, which ensures that the binary is not loaded in the Win32 subsystem
when launched inside Windows.
32bit DOS Apps in MZ Format
This format is also supported by HX and consists of
Win32 emulation is provided for this format as well, but of course exists on the
source code level only. For this OMF libraries (DKRNL32S.LIB, DUSER32S.LIB and DADVAPIS.LIB)
The MZ format compared to the PE format has some limitations, though.
- JMPPM32.OBJ to prepare app for 32bit protected mode execution
- some helper functions in library JMPPM32.LIB
- some libraries in OMF format for Win32 emulation (see below for more details)
- Libc32.lib, a simple static C runtime library (OMF format)
- TestOMF, a program to test 32bit MZ format support of various OMF linkers.
- Samples in ASM and C.
- + has the least overhead and loads pretty fast
- - applications cannot run in a true flat (=zero-based) memory model
- - doesn't support dll dynamic linking
- - size of image is limited to available DOS memory
- - some popular OMF linkers have problems with 32bit segments > 64 kB.
I recommend to use either Digital Mars' LINK.EXE (supplied with their C++ compiler) or LADSoft's VALX.EXE.
Both linkers have no problems with HX MZ format.
- - No support for 32bit apps in MZ format by most development tools.
The Digital Mars C++ compiler and Watcom C++ will support this format, though.
And of course assemblers don't have any problems with it either.
E. HX 16-Bit Developer Support
Although most of HX is 32-bit, it still supports 16-bit protected-mode
applications. The support consists of
HDPMI16, DPMI server to run 16-bit DPMI clients. It is included
in the HX runtime.
DPMILD16, Loader for 16-Bit NE binaries. It is included in the
HXD16, Developer package.
Basically the following tools are able to create HX compatible 16-bit
Samples in ASM, C, Pascal and Cobol are included and will show how to create,
run and debug the binaries.
- Open Watcom C
- Digital Mars C++ v8.4
- MS C 6.0 and MS VC++ v1.52
- Borland C++ v3.1 and v4
- JWasm, Masm, Tasm, Wasm, Nasm, Yasm, Fasm
- Borland Pascal 7.0
- MS Cobol v4.5
F. HX Source Code
The HXSRC package contains the HX DOS extender source code.
This consists of:
HX's source code is about 100.000 lines of code.
- DPMI host HDPMI32.EXE / HDPMI16 (MASM)
- DPMI loader DPMILD32.EXE / DPMILD16.EXE (MASM)
- Win32 emulation dlls DKRNL32, DADVAPI, DGDI32, DUSER32, OLE32, OLEAUT32, WINMM, DDDRAW, DINPUT, DSOUND (MASM)
- GUI helper dll HXGuiHlp.dll
- Tools HXLdr32.exe, PEStub.exe, PatchPE.exe, PatchNE.exe(MASM)
- MZ stubs DPMIST32.BIN / DPMIST16.BIN (MASM)
- HX's MZ/NE file format support (MASM)
- WD debugger trap helper files HXHELP.EXE / HXHP16.EXE (MASM)
- VESA support dll VESA32 (MASM)
G. Debugging HX DOS Extended Applications
1. Debugging 32-bit DPMI Applications
WD: Standard debugger of Open Watcom. This is a full-screen debugger
which allows debugging on source code level. Support for Open Watcom and WD
is included in HX. WD will be able to debug all types of HX binaries.
If you don't want to download and install the Open Watcom package, here's just the
DOS version of WD (slightly improved).
A debugger with a line-oriented interface like the good, old DOS debug,
intended to be used by real men only.
Recent versions of LadSoft's GRDB are able to debug DPMI clients, so this debugger
might also be used to debug HX applications. However, there seems to be
a severe problem with GRDB running on Win9x systems, better don't try this
A free debugger from Qualitas Inc. It runs at the highest privilege level
and can therefore debug DPMI and VCPI clients. Since HDPMI runs as a VCPI client if a
memory manager has been loaded, 386SWAT can debug any part of HX. But there also are
- cannot debug on source level (support for using symbol tables is implemented)
- has a strange user interface
- is not always as stable as it could be
- to debug graphics applications it needs a second monitor
- cannot be loaded from the command line, must be installed as device driver
these are various versions of a ring 0 debugger from Microsoft which is included in Win9x DDKs (and possibly SDKs,
if I remember correctly).
This debugger's user interface - like the one of DEB32F - isn't for the faint of heart.
You may get it for virtually free, or at least you got it with the Win9x DDKs.
HX's DPMI host HDPMI supports debugger APIs int 68h (real mode) and int 41h (protected mode)
and so supports debugging with WDEB386, on user level (ring 3) and system level (ring 0).
You will need a second computer and a terminal program for debugging
(see WDEB386 help for more details).
2. Debugging 16-bit DPMI Applications
WD: The Open Watcom debugger may now be used to debug 16 bit DPMI apps
in any format. All files needed are included in HXD16.ZIP.
- DEB16F: A a line oriented debugger similiar to DEB32F.
- TD/TDX: 16-bit debugger from Borland.
DPMI support is implemented in newer versions of TD.EXE (version > 4).
Previously there existed a special version for DPMI, TDX.EXE, which is
included in Borland Pascal 7.0. This debugger will accept the Borland
binary format only, but HX's 16-bit developer support package includes
examples how to create a compatible NE format.
TD is not free, but possibly you have an old version of BP or BC available.
H. Running HX under Linux/Unix
Running HX with Emulators
Virtual PC emulators (VMWare, Qemu, Bochs, ...) should have no problem running
HX. HX's DPMI server HDPMI, which must run in ring 0, has been verified
to be compatible with current versions of VMWare, Qemu and Bochs. Since the 80386's
hardware debugging registers usually are not supported by the emulators,
debuggers that would like to use them may not always work as expected. This is true
for DEB32F, DEB16F and DEB16FW.
Running HX with DosEmu (x86 Linux only)
DosEmu doesn't allow a ring 0 application like HDPMI to run under its control.
That's not that bad, because DosEmu installs its own DPMI host, and most
of the features required by HX are implemented. If you're running a DosEmu
version < 1.3.1, you will have to upgrade (the current release version is 1.4.0).
For developers it might also be interesting that DosEmu supports using the
80386 hardware debug registers.
Some issues concerning Dosemu are
- DosEmu's DPMI host is currently unable
to support multiple address spaces, a feature which may be required by some
commercial Win32 applications.
Some distributions (RedHat) do have a very sophisticated feature which,
IIRC, is called "address space randomization". This conflicts with DosEmu's
DPMI V1.0 implementation and may cause errors when HX's DPMILD32 is running.
Below are the features which are currently missing in HX.
Feel free to contact me if you think there is something missing or if you want
to contribute to HX in any way.
- ASPI support currently requires WNASPI32.DLL from Windows 9x to work.
This should be changed so this external (and unfree) dll is no longer required.
- 2D (and OpenGl) Graphics acceleration in DOS. I'm not sure if something
like SciTech's SNAP could be used to implement these features. Hints are welcome.
- a VDD to be loaded when HX is running in WinXP DOS boxes and which
emulates VESA LFB by using fullscreen DirectDraw.
- Sound support when running in a WinXP DOS box. Currently a WinXP DOS
box provides SB 2 emulation only, but HX requires at least a SB Pro for
stereo wave output. Installing
VDMSound may allow to emulate a SB 16, but
this software has its problems and may not work as expected. There exist
other emulators which work better, but they are not free AFAIK.
- AC97 support in DOS.
- support of a GUI/widget library, possibly FLTK
The DosX Forum
is intended as a place to ask questions concerning HX.
Important Note: HXRT217.zip has to be made password-protected, because some anti-virus programs
don't like file DKRNL32.DLL (a Win32 emulation dll), which is contained in the package.
List of all versions available for download