Skip to content

Using the SDK

--target=i8086-pc-win16 makes Windows 3.x programs and DLLs (NE executables) in the small, medium, compact and large models. Windows runs them in protected mode, where segment arithmetic is invalid, so there is no tiny or huge model.

clang --target=i8086-pc-win16 --sysroot=<sysroot> -Os hello.c -o hello.exe
clang --target=i8086-pc-win16 -mcmodel=large --sysroot=<sysroot> -Os \
    -shared mylib.c -o MYLIB.DLL
  • A program has WinMain (from <windows.h>) or main. The C library is the DOS one: printf and files go through DOS, which Windows provides to programs (standard output is wherever Windows sends it; under Wine, the terminal). malloc takes memory from Windows (GlobalAlloc in compact and large, LocalAlloc in DGROUP otherwise).
  • The headers (see Headers) declare the Windows 3.1 API. Every function of the Windows 3.1 DLLs is in lib/win16/windows.lnk (generated from Wine's .spec files by tools/gen-win16-imports.py, with the functions Wine has only as stubs), which clang passes to the linker, so declaring a function with WINAPI (__far __pascal) is enough to call it.
  • The driver passes -mwindows-prologue=exported, so __export functions (window procedures, DLL entry points) get the Windows entry sequence.
  • -shared makes a DLL. Its startup code (libentry.obj) sets up the local heap and runs constructors, then calls int __far __pascal LibMain(HINSTANCE, WORD ds, WORD heapsize, LPSTR cmdline) if the DLL has one; WEP runs destructors when it is unloaded. Export functions with __export __far __pascal. To link a program with a DLL, python3 tools/win16-imports.py MYLIB.DLL > mylib.lnk lists its exports as linker directives; pass them with -Wl,@mylib.lnk.
  • Drivers: an installable driver (.DRV, as OpenDriver and MMSYSTEM load) is a DLL that exports LRESULT __export WINAPI DriverProc(DWORD, HDRVR, UINT, LPARAM, LPARAM) and passes what it doesn't handle to DefDriverProc. Build it with -shared -o MYDRV.DRV; tests/win16/hellodrv.c is one. Wine's OpenDriver does nothing for 16-bit programs, so the test calls DriverProc the way USER would. Windows 3.1 virtual device drivers (VxDs, 32-bit LE files) are made with win32-sdk's win31-vxd.cfg.
  • Display drivers for Windows 95, 98 and Me: a minidriver is a DLL named DISPLAY.DRV that exports the GDI display driver functions at fixed ordinals, sets the mode in Enable and passes the drawing to the DIB engine (DIBENG.DLL). <gdidefs.h> has the GDI driver interface (GDIINFO, its capability bits, DRAWMODE), <dibeng.h> the DIB engine's (DIBENGINE, DIB_Enable, CreateDIBPDevice) and DIBENG_LINK, which makes the stubs that jump to the engine. lib/win16/dibeng.lnk imports the engine by ordinal (its 46 functions are the same in 95, 98 and Me). tests/win16/display.c is a minidriver for the VGA's 320x200 256-colour mode, a starting point rather than a driver to install; build it with
clang --target=i8086-pc-win164.00 --sysroot=<sysroot> -shared \
  -mwindows-prologue=all display.c -o DISPLAY.DRV \
  -Wl,@<sysroot>/lib/win16/dibeng.lnk -Wl,@display.lnk

where display.lnk (next to the test) exports the functions at their ordinals and makes the segments fixed. -mwindows-prologue=all gives every far function the DLL entry sequence without __export, which would export it a second time, by name. The display VxD's half, the mini-VDD, is made with win32-sdk (vxd/minivdd.c). - A DLL runs on the stack of the program that calls it, so SS is not DS. The compiler reaches locals through SS: far pointers to locals (all data pointers in compact and large) carry SS, structures are returned through far pointers, va_list is a far pointer, and copies and fills of locals are done inline. These hold in programs too, so the same libraries serve both. In the small and medium models a near pointer means DS, so DLL code (-shared, or -mwindows-dll when compiling with -c) keeps every local whose address escapes the function in a frame in DGROUP instead, and near pointers to locals, and C++ objects on the stack, work as in a program. Each task that calls the DLL gets its own 4 KiB region for these frames, from the DLL's heap; a DLL that needs more defines unsigned short __win16_dll_frame_size = 8192;. The C and C++ libraries for this are in lib/win16/<model>/dll, which clang links with -shared. Compact and large DLLs need none of it. - __near, __far and __huge after the parameter list of a member function qualify this, as in Microsoft C++ 7: int get() __far takes a far this, so it works on an object anywhere, and S() __far constructs one. Before the name they choose the call, as for other functions (int __far f() is called with CALL FAR). A virtual function, or a member function that a pointer to member points to, uses the memory model's call, since vtables and member pointers hold code pointers of that kind. A later declaration without __near or __far keeps the first one's. - Resources: llvm-rc -win16 compiles a resource script to a 16-bit .res file (menus, dialogs, string tables, accelerators, icons, cursors, bitmaps, version information and raw data; not the 32-bit MENUEX and DIALOGEX). Strings are 8-bit, in the script's code page. windows.h can be included in the script (it defines the constants only when RC_INVOKED is set, as llvm-rc does). Give the .res file to clang with the objects, and the linker puts the resources in the NE file:

llvm-rc -win16 -I <sysroot>/include -FO app.res app.rc
clang --target=i8086-pc-win16 --sysroot=<sysroot> app.c app.res -o app.exe

llvm-windres --target=i8086-pc-win16 app.rc app.res does the same. - C++ works as on DOS, without exceptions or RTTI by default. -fexceptions works in programs, and in compact and large DLLs; an exception must not cross from a DLL to its caller or back. - Wine reports 0 as the exit code of every 16-bit program.