HX DOS Extender (original) (raw)
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:
- 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)
- PowerBasic
- MicroFocus Object Cobol
- XDS Modula II
- JWasm, Masm, Tasm, Poasm, Wasm, Fasm, Lzasm, Nasm, Goasm, ... Since HX's built-in Win32 emulation is pretty mature, most of these compilers/assemblers will run with HX in plain DOS as well.
Other tools suitable to create HX PE binaries are:
- DJGPP (uses GCC) 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. These are:
- DPMI server HDPMI. Used in plain DOS only.
- PE file loader DPMILD32
- Win32 API emulation dlls (DKRNL32, DUSER32, DADVAPI, ...)
- Helper tools HXLdr32 and PEStub 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.
About HDPMI
HDPMI is a free DPMI server. Its features are:
- 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 See HDPMI's Readme for more details.
About DPMILD32
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:
- 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 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:
- 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. 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.
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:
- 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 Some more dlls are included just as dummies:
- IPHLPAPI.DLL
- MSACM32.DLL
- SHELL32.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 theMS FTP Server or here.
About SDL
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 https://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
- 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 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 available.
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
- 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 . 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) are included. The MZ format compared to the PE format has some limitations, though. Advantages/disadvantages are:
- + 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 HX runtime.
- HXD16, Developer package. Basically the following tools are able to create HX compatible 16-bit 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
Samples in ASM, C, Pascal and Cobol are included and will show how to create, run and debug the binaries.
F. HX Source Code
The HXSRC package contains the HX DOS extender source code. This consists of:
- 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) HX's source code is about 100.000 lines of code.
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.
- Screenshot of WD debugging a HX "hello world" in C on Source Code Level
- Screenshot of WD debugging a HX "hello world" in MASM on Source Code Level
If you don't want to download and install the Open Watcom package, here's just the DOS version of WD (slightly improved).
- DEB32F: A debugger with a line-oriented interface like the good, old DOS debug, intended to be used by real men only.
- GRDB: 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 combination.
- 386SWAT: 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 some disadvantages:
- 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
- WDEB386/WDEB98/DEBUGGER: 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.
I. Roadmap
Below are the features which are currently missing in HX.
- 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 or GTK+. Feel free to contact me if you think there is something missing or if you want to contribute to HX in any way.
K. Support
The DosX Forumis intended as a place to ask questions concerning HX.
L. Download
| Runtime | GUI extension | Develop. 32-bit | Develop. 16-bit | Source | ||
|---|---|---|---|---|---|---|
| v2.16, stable | 11/16/2009 | HXRT | HXGUI | HXDEV | HXD16 | HXSRC |
| v2.17, release candidate | 05/01/2014 | HXRTPassword: japheth | HXGUI | HXDEV | HXD16 | HXSRC |
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.