Skip to content

Kernel-mode drivers

The *-ddk.cfg config files build NT kernel-mode drivers (.sys files) with mingw-w64's DDK headers (<ntddk.h>, <wdm.h>, <ntifs.h>, <ndis.h>, ...), which every sysroot has in include/ddk, and its kernel import libraries (-lntoskrnl, -lhal, -lndis, -lusbd, -lks, ...). Like the rest of the sysroots, they hold no Microsoft files.

clang --config=winxp-ddk.cfg -O2 mydriver.c -o mydriver.sys
clang --config=win10-x64-ddk.cfg -O2 mydriver.c -o mydriver.sys
Config For Sysroot
nt4-ddk NT 4.0 (with 2000's kernel API, see below) win9x-msvcrt
win2000-ddk, winxp-ddk 2000, XP win2k-xp
vista-ddk, win7-ddk, win10-ddk Vista, 7, 10 (x86) win-vista
vista-x64-ddk, win7-x64-ddk, win10-x64-ddk Vista, 7, 10 and 11 (x64) win-vista-x64

Each one takes the program config of its Windows version (@winxp.cfg) and adds:

  • the DDK headers, with _WIN32_WINNT (and so NTDDI_VERSION) set to the version;
  • -nostdlib: no C runtime, no start-up code. The kernel exports the C library a driver may use (memcpy, strlen, _snprintf, ...), and compiler-rt's builtins (libgcc.a) supply 64-bit division and __chkstk;
  • the image of a driver: native subsystem, entry point DriverEntry, base address 0x10000, the checksum the kernel checks, not Terminal Server aware;
  • for x86, -mno-sse -mno-mmx: a 32-bit driver must not touch the FPU, MMX or SSE registers without KeSaveFloatingPointState. x64 drivers may use SSE, as Microsoft's compiler does.

Structured exception handling works as with Microsoft's compiler: __try, __except, __finally, __leave, GetExceptionCode() and GetExceptionInformation(), with -fms-extensions -fasync-exceptions (cl /EHa's behaviour: a bad pointer or a division by zero in any instruction of a __try reaches its __except, as drivers expect when they probe user buffers with ProbeForRead). x64 drivers use the kernel's __C_specific_handler. 32-bit ones use _except_handler3, which the 2000 and later kernels export but NT 4.0's and the 98 and ME NTKERN's do not, so the x86 configs link libntseh.a, this SDK's own _except_handler3 (kernel/except3.S, which needs only RtlUnwind from the kernel); build-win9x.sh and build-modern-sysroot.sh build it. The 32-bit configs also pass -fseh-exceptions, the exception model whose tables __try needs on MinGW. This needs the clang of clang-retro's LLVM from November 2026 on: older ones leave 32-bit __try's scope table undefined and ignore -fasync-exceptions for MinGW.

Declare the entry point and dispatch routines NTAPI (stdcall), as mingw-w64's headers do: NTSTATUS NTAPI DriverEntry(PDRIVER_OBJECT, PUNICODE_STRING). The tests are in C; C++ drivers need -fno-exceptions -fno-rtti and get no global constructors, as with Microsoft's kits.

mingw-w64's headers start at Windows 2000 (NTDDI_VERSION 0x05000000), so nt4-ddk declares 2000's kernel API, and some functions it declares are not in NT 4.0's kernel. check-imports.py --nt VERSION checks a 32-bit driver's imports from ntoskrnl.exe, hal.dll, ndis.sys, scsiport.sys, videoprt.sys, tdi.sys, win32k.sys (display drivers) and the class drivers (stream.sys, ks.sys, portcls.sys, usbd.sys, hidclass.sys, hidparse.sys, battc.sys, 1394bus.sys, from the kits that have them) against the exports of each NT version from 3.1 to Server 2003 (tools/kernel-versions.txt, made by tools/gen-kernel-versions.py from the import libraries of the NT 3.1, NT 4.0, 2000, XP and Server 2003 DDKs; NT 3.5 and 3.51 count as 4.0):

python3 tools/check-imports.py --nt 4.0 mydriver.sys

There is no config file for NT 3.x: mingw-w64's IoCompleteRequest and IoCallDriver are the fastcall IofCompleteRequest and IofCallDriver of later kernels, which NT 3.1 does not have. Microsoft's NT 3.1 DDK, imported with import-ms-sdk.py (ms-nt31-ddk.cfg, below), builds drivers for it.

scripts/fix-ddk-headers.sh fixes a mistake in mingw-w64's wdm.h (it tests NTDDI_WINVISTA, which nothing defines, so drivers for 2000 and XP got Vista's IRP layout), adds STREAMAPI to four <strmini.h> functions that lack it, makes <ks.h>'s callbacks NTAPI (KS.SYS calls them stdcall, as the DDK builds them with cl -Gz; mingw-w64 left them cdecl), makes <ndis.h> compile next to <ntddndis.h> and adds a comma its NdisMWanIndicateReceiveComplete lacks. It also copies in the DDK headers mingw-w64 lacks, from kernel/include (share/clang-dos/ddk-include in the package): <hidport.h>, <1394.h>, <ddrawint.h>, <d3dnthal.h>, <dvp.h>, <dxmini.h> and <hdaudio.h>. build-win9x.sh and build-modern-sysroot.sh run it on each sysroot.

Drivers for Windows 95, 98 and ME are mostly VxDs (LE files, below), not PE ones. WDM drivers for 98 and ME are PE .sys files that NTKERN.VXD loads. It gives them only part of the kernel API, the functions of the 98 and ME DDKs' wdm.lib, and runs only drivers with a native subsystem version of 4.x or older. nt4-ddk.cfg builds such drivers, and check-imports.py --wdm 98 (or --wdm 98se, --wdm me) checks both things. The function list is tools/wdm9x-exports.txt, which tools/gen-wdm-exports.py makes from those two libraries. 98 has 336 functions and ME 346. ME has 12 that 98 lacks, such as ExCreateCallback and RtlZeroMemory, and lacks two of 98's. The ms-w98-wdm kit (below) builds with the 98 DDK's own wdm.h.

WDM audio drivers (port class miniports) build the same way, with mingw-w64's <portcls.h> and -lportcls, the import library build-vxd.sh makes of the PORTCLS.SYS functions (tools/portcls9x-exports.txt) that mingw-w64 lacks:

clang --config=nt4-ddk.cfg -O2 mydriver.c -lportcls -o mydriver.sys
python3 share/clang-dos/check-imports.py --wdm 98se mydriver.sys

Port class and kernel streaming (KS.SYS) grew in each version: 98's PORTCLS.SYS has 39 functions, 98 Second Edition's 47 (the event functions, PcAddToEventTable and the rest) and ME's 55 (the DRM ones, PcAddContentHandlers and the rest, and PcRegisterIoTimeout), and wdm9x-exports.txt has each version's, from the 98 DDK's portcls.lib and ks.lib and the drivers of 98 SE and ME. --wdm 98se checks for 98 SE, which has 98's kernel functions. tests/ddk/wdmaudio.c is an adapter driver that makes a topology port when its device starts, in C. scripts/fix-ddk-headers.sh makes ksmedia.h (which <portcls.h> includes) compile in kernel mode, where nothing defines the TCHAR of its TRANSPORTBASICPARMS.

USB drivers import USBD.SYS. Link them with -lusbd9x, which build-vxd.sh makes from tools/usbd9x-exports.txt, not mingw-w64's -lusbd. 98's and 98 SE's USBD.SYS export USBD_CreateConfigurationRequestEx, USBD_ParseConfigurationDescriptorEx and USBD_ParseDescriptors only by their decorated names (_USBD_CreateConfigurationRequestEx@8). The 98 DDK's usbd.lib imports them by those names, and so does -lusbd9x; ME and Windows 2000 and later export them too. mingw-w64's library imports them undecorated, so the driver loads only on ME and later:

clang --config=nt4-ddk.cfg -O2 myusb.c -lusbd9x -o myusb.sys
python3 share/clang-dos/check-imports.py --wdm 98 myusb.sys

HID drivers link mingw-w64's -lhidparse and -lhidclass (include <hidusage.h> before <hidpi.h>). A HID minidriver includes <hidport.h> (after <hidusage.h> and <hidclass.h>, which it includes itself), this SDK's own, which mingw-w64 lacks: HID_MINIDRIVER_REGISTRATION for HidRegisterMinidriver, HID_DEVICE_EXTENSION, the HID descriptor and the internal IOCTL_HID_* requests. tools/gen-vxd-headers.py --wdm made it, and <1394.h>, from the names, values and layouts of the 2000 and XP DDKs; what only XP has is under _WIN32_WINNT >= 0x0501. tests/ddk/wdm-layout/ checks their layouts. wdm9x-exports.txt also has the functions of USBD.SYS, HIDCLASS.SYS and HIDPARSE.SYS, from the 98 DDK's libraries and the drivers of 98 SE and ME. 98 SE added HidP_InitializeReportForID, HidP_GetExtendedAttributes and two more. For these drivers and port class, --wdm 98se goes by 98 SE's own driver: it dropped some of 98's functions, such as KS.SYS's KsQuerySoftwareBusInterface. tests/ddk/usbdrv.c is a USB client driver, tests/ddk/hidparse.c parses HID reports and tests/ddk/hidmini.c is a HID minidriver.

HD Audio function drivers for Windows XP (with the UAA update, KB888111, which brought Microsoft's HD Audio bus driver, HDAUDBUS.SYS), Server 2003 and later include <hdaudio.h>, which mingw-w64 lacks and Microsoft first shipped in the Vista WDK. This SDK's is written from Microsoft's public documentation of the HD Audio DDI: the bus interface (HDAUDIO_BUS_INTERFACE, and HDAUDIO_BUS_INTERFACE_BDL for buffer descriptor lists) that the driver gets from the bus with IRP_MN_QUERY_INTERFACE, codec verbs and responses, stream and converter formats, and the callbacks. The Vista and later V2 and V3 interfaces are not in it. No imported kit has the header, so its layouts are checked only against the sizes the documentation gives. tests/ddk/hdafunc.c queries the interface when its device starts, reads the controller's information and sends the codec a Get Parameter verb.

1394 (FireWire) client drivers send IRBs to the bus driver with IOCTL_1394_CLASS, declared in <1394.h>; 1394BUS.SYS exports nothing a client calls, so they need no import library. tests/ddk/fw1394.c asks for the bus's generation count.

Stream class minidrivers (video capture, TV tuners, <strmini.h>) link -lstream, the import library build-vxd.sh makes from tools/stream9x-exports.txt, as mingw-w64 has none. STREAM.SYS has 19 functions in 98 and 98 SE, and ME's adds StreamClassFilterReenumerateStreams. wdm9x-exports.txt also has USBCAMD.SYS's (for USB cameras) from the 98 DDK; 98 SE and ME have no list for it, so --wdm 98se and --wdm me warn that they do not check it rather than fail. tests/ddk/streammini.c registers a minidriver with StreamClassRegisterAdapter.

AVStream minidrivers (<ks.h>, -lks, KsInitializeDriver with a device descriptor) load on 98 Second Edition and ME, whose KS.SYS brought AVStream; 98's does not have it. ME's KS.SYS added the stream pointer functions (KsPinGetLeadingEdgeStreamPointer, KsStreamPointerAdvanceOffsetsAndUnlock and the rest), so a pin-centric minidriver that uses them loads only on ME; --wdm 98se says which. mingw-w64's <ks.h> has the same layouts as the XP DDK's for the AVStream structures (descriptors, dispatch tables, KSPIN, KSFILTER, KSDEVICE, stream pointers). tests/ddk/avstream.c is a capture filter with one pin-centric output pin.

NDIS 5 miniports (network adapters, <ndis.h> with NDIS50_MINIPORT, -lndis) are .sys files that 98 SE and ME load. 98 SE's NDIS.VXD resolves their imports from a table of 277 names in NDIS.VXD itself, not from an export table; gen-wdm-exports.py reads it from 98 SE's NDIS.VXD (found with NDIS.SYM) into wdm9x-exports.txt, and --wdm 98se checks against it. There is no such list for 98 or ME, so those two only warn. tests/ddk/ndismini.c registers a miniport with NdisMRegisterMiniport.

Display drivers for NT 4.0 and later are DLLs that import WIN32K.SYS (GDI's engine, <winddi.h>, -lwin32k), with DrvEnableDriver as their entry point. check-imports.py --nt checks their imports against NT 4.0's, 2000's and XP's WIN32K.SYS (EngAlphaBlend and the rest of 2000's are not in 4.0's). mingw-w64's <winddi.h> includes <ddrawint.h> and <d3dnthal.h>, the DirectDraw and Direct3D HAL that DrvGetDirectDrawInfo and DrvEnableDirectDraw fill in (DD_HALINFO, DD_CALLBACKS, D3DNTHAL_GLOBALDRIVERDATA, the DD_*DATA each callback gets, the DirectX 6 and later command buffer), and <dvp.h>, video ports, which mingw-w64 lacks. gen-vxd-headers.py --wdm made the three from the 2000 and XP DDKs, and tests/ddk/wdm-layout/ checks their layouts; what only XP's has (DirectX 8 and 9) is under _WIN32_WINNT >= 0x0501:

clang --config=nt4-ddk.cfg -O2 -shared -Wl,--entry,_DrvEnableDriver@12 \
  mydisp.c -lwin32k -o mydisp.dll
python3 share/clang-dos/check-imports.py --nt 4.0 mydisp.dll

Video miniports (<miniport.h>, <video.h>, -lvideoprt) that do DirectDraw in kernel mode (overlay flips, video port fields, capture, for DXAPI.SYS) include <dxmini.h>, which mingw-w64 lacks; gen-vxd-headers.py --wdm made it from the 2000 and XP DDKs, with GUID_DxApi, and the miniport hands out its DXAPI_INTERFACE from HwQueryInterface. tests/ddk/vidmini.c is such a miniport. The generated headers have the DDKs' GUIDs (DEFINE_GUID) too.

tests/ddk/display.c implements DrvBitBlt with EngBitBlt and has a DirectDraw and Direct3D HAL with one callback, WaitForVerticalBlank.

tools/mapsym.py writes a .SYM file (MAPSYM's format), which WDEB386 and SoftICE load. For a driver, it reads the symbols from the image's COFF symbol table, which the linker keeps unless -s strips it. That includes the static functions and variables, listed by section. Built with -g, the driver also gets line numbers from its DWARF line table, in MAPSYM's format: one table of code offsets and source lines for each source file:

clang --config=nt4-ddk.cfg -O2 -g myusb.c -lusbd9x -o myusb.sys
python3 share/clang-dos/mapsym.py myusb.sys      # writes myusb.sym
python3 share/clang-dos/mapsym.py --dump --lines myusb.sym

For WinDbg (and KD) on NT 4.0 and later, build with -g -gcodeview and have the linker write a PDB with -Wl,--pdb=. Add -Wl,--Xlink=-pdbaltpath:%_PDB% so that the image's debug directory names only the PDB, not the folder it was built in, and WinDbg finds it on its symbol path (.sympath) next to the driver. The PDB has the functions, their types, line numbers and the frame data that WinDbg needs to walk the stack through code built without frame pointers. llvm-symbolizer --obj=mydrv.sys --pdb=mydrv.pdb ADDRESS reads it the same way:

clang --config=winxp-ddk.cfg -O2 -g -gcodeview mydrv.c -o mydrv.sys \
  -Wl,--pdb=mydrv.pdb -Wl,--Xlink=-pdbaltpath:%_PDB%

The PDB is version 7.0, which WinDbg 6 and later read; NT 4.0's own 4.0 debuggers read only .DBG files and older PDBs, but WinDbg 6 debugs NT 4.0 targets. With --pdb, the linker leaves out the COFF symbol table and the DWARF that mapsym.py reads; to have both a PDB and a .SYM file from one build, add -gdwarf and -Wl,--Xlink=-debug:symtab -Wl,--Xlink=-debug:dwarf.

tests/ddk/hello.c is a small driver that makes \Device\ClangHello and answers an IOCTL with a 64-bit computation and whether its __except caught a division by zero (with a __finally inside); tests/ddk/client.c talks to it. Wine runs drivers as services, so

CFGDIR=~/clang-dos/bin sh tests/ddk/run-tests.sh

builds it with each *-ddk.cfg at -O0 and -O2, checks it with check-imports.py (the NT 4.0 build also as a WDM driver for 98 and ME, and tests/ddk/notwdm.c, which calls PsGetVersion, must fail that check), loads it in Wine (32-bit drivers in a 32-bit prefix, 64-bit ones in a 64-bit one) and runs the client. Wine's kernel is not Windows', so a real Windows is still the final test.

Signing drivers

64-bit Vista and later load only signed drivers. tools/drvsign.py (share/clang-dos/drvsign.py in the package; Python only, no signtool, makecert, makecat or OpenSSL) signs them for test-signing:

python3 drvsign.py newcert test.pem          # once: test.pem and test.cer
python3 drvsign.py sign --cert test.pem mydriver.sys
python3 drvsign.py catalog --cert test.pem -o mydriver.cat \
    mydriver.inf mydriver.sys
python3 drvsign.py verify --cert test.pem mydriver.sys mydriver.cat
  • newcert makes an RSA key and a self-signed code-signing certificate (test.pem, which stays private, and test.cer, the certificate alone).
  • sign embeds an Authenticode signature (PKCS #7, the hash of the whole image but its checksum and certificate table) and fixes the checksum; signing again replaces the signature.
  • catalog makes the signed catalog an INF's CatalogFile names, with the Authenticode hash of each PE file and the plain hash of the rest.
  • verify checks the hashes and the signatures.

Windows loads such drivers in test mode: bcdedit /set testsigning on (with Secure Boot off) and a restart. To install a package without the unsigned-driver prompt, add the certificate to the Trusted Root and Trusted Publishers stores (certutil -addstore root test.cer, certutil -addstore trustedpublisher test.cer). Windows Vista, 7 and 8 without updates check only SHA-1: give --hash sha1 to newcert and sign for them (catalogs are SHA-1 unless --hash sha256). Release signing needs a certificate from a certificate authority and, for Windows 10 and later, Microsoft's attestation signing, which this does not do. 32-bit Windows and NT 4.0, 2000 and XP do not check drivers' signatures, but XP asks before installing a package without a signed catalog.

tests/ddk/clanghello.inf installs the test driver as a demand-start service (Wine installs, runs and removes it from the INF). osslsigncode verify accepts these signatures and catalogs, and Wine's WinVerifyTrust accepts the signatures and rejects ones whose file or signature was changed. The test driver itself is signed in the tests, and still loads in Wine; real Windows in test mode is still to be tried.

SCSI miniports for Windows 95, 98 and ME

Windows 9x drives SCSI host adapters (and many IDE and RAID ones) with the same kind of miniport as Windows NT. A 9x miniport is a .mpd file:

  • a PE image with the native subsystem, version 4.0;
  • with the entry point DriverEntry;
  • importing only SCSIPORT.SYS, which 9x's SCSIPORT.PDR provides.

SCSIPORT.PDR has the structures of NT 3.51. Its HW_INITIALIZATION_DATA is 76 bytes and its PORT_CONFIGURATION_INFORMATION is 124. mingw-w64's DDK headers have Windows 2000's (80 and 140 bytes), which it refuses. win95-miniport.cfg uses 9x's headers instead:

clang --config=win95-miniport.cfg -O2 myadapter.c -o myadapter.mpd
python3 share/clang-dos/check-imports.py --miniport myadapter.mpd
  • <miniport.h>, <srb.h> and <scsi.h> (in sysroots/win9x-msvcrt/include/miniport9x) have the 95, 98 and ME DDKs' types, constants and structures, and the ScsiPort* prototypes. The three DDKs agree on them. tools/gen-vxd-headers.py --miniport made them from the DDKs' block/inc, as for the VxD headers, and tests/ddk/miniport-layout/*.c checks their layouts.
  • Functions and callbacks are stdcall (-mrtd), as the DDK builds them with cl -Gz. ScsiPortNotification and ScsiDebugPrint take variable arguments, so they are cdecl.
  • libscsiport9x.a imports the 45 functions that SCSIPORT.PDR has (tools/scsiport9x-exports.txt, from the 95 and 98 DDKs' import libraries). libvxd.a has memcpy, memset and the like.
  • check-imports.py --miniport checks the subsystem and that each import is one of those 45.

tests/ddk/miniport.c is a virtual adapter with no hardware: its target 0 answers INQUIRY as a processor device. run-tests.sh builds it at -O0, -O2 and -Os and checks it. A miniport is installed with an INF for the SCSI adapter class, as the DDK's samples are. Nothing loads one in Wine, so real Windows 9x is the test.

VxDs for Windows 3.1, 95, 98 and ME

A VxD is a 32-bit virtual device driver in the LE format, run by the VMM in ring 0. win95-vxd.cfg compiles one (freestanding, no FPU or SSE, no stack protector or unwind tables) and tools/vxd-link.py links it with JWlink:

clang --config=win95-vxd.cfg -O2 -c hello.c -o hello.o
python3 share/clang-dos/vxd-link.py -o HELLO.VXD hello.o
python3 share/clang-dos/vxd-check.py --dynamic HELLO.VXD

<vxd.h> has what a VxD written in C needs, with no Microsoft headers:

  • VXD_DEVICE(NAME, ID, INIT_ORDER, MAJOR, MINOR) defines the device descriptor block NAME_DDB (exported as ordinal 1, as the VMM wants) and an assembly control procedure. That procedure saves the registers and calls int vxd_control(DWORD msg, struct vxd_regs *r). Return 0 for success (carry clear) and nonzero for failure; change r->eax and the other fields to return values in registers.
  • The control messages (SYS_DYNAMIC_DEVICE_INIT, W32_DEVICEIOCONTROL, ...), struct DIOCParams, and DIOC_OPEN and DIOC_CLOSEHANDLE.
  • The services of the VMM and of 40 VxDs of Windows 3.1 to ME (1,391 of them, in <vxdsvc.h>, made from tools/vxd-services.txt). VXDSVC_name is the dword that follows int 20h for each. A service is defined when VXD_WINVER is at least the Windows version that has it: 3.10 (0x030A) for win31-vxd.cfg, 4.00 by default, and -DVXD_WINVER=0x040A for 98 or 0x045A for ME. Each service's version is the first of the 3.1, 95, 98 and ME DDKs that has it (95 OSR2's, 4.03, where the 95 DDK's table says so).
  • VxDCall(name, &regs) calls a register service: it loads EAX to EBP from a struct vxd_regs, calls the service, stores them back and returns 1 if the service set the carry flag. The services called like C functions (_HeapAllocate, _RegOpenKey, _VWIN32_SetWin32Event, the StdCall and FastCall ones) are functions: libvxd.a has a stub for each that jumps to the service. <vxd.h> declares the common ones with their types (the heap, pages, the registry, VWIN32's events and APCs). <vxdsvc.h> declares 383 of the other 496 C services with their types, from tools/vxd-prototypes.txt. tools/gen-vxd-protos.py made that list from the 95, 98 and ME DDKs' C headers and, for the services no header declares, the DDKs' help and the 95 DDK's documents. It keeps only the types and reduces each to BYTE, WORD, DWORD or void *. The other 113 are in neither: Microsoft's internal and obsolete services (_ACPI_Obsolete1 and the like), or ones the help names without a syntax. It declares those with no parameter list (in C before C23), and the StdCall and FastCall ones with their dword parameters.
  • VXD_CALLBACK(name, fn) makes a procedure for the VMM to call with registers (a time-out, an event, an I/O trap, an interrupt): it calls int fn(struct vxd_regs *r) and sets the carry flag if fn returned nonzero. VMMCALL_Set_Global_Time_Out, VMMCALL_Schedule_Global_Event, SHELL_SYSMODAL_Message, VMMCALL_Get_System_Time and a few others wrap common register services, and struct VPICD_IRQ_Descriptor and the HEAP*, PAGE*, PG_*, MB_*, HKEY_* and I/O trap constants go with them.
  • Code and data are locked (always in memory) unless marked: VXD_INIT_CODE and VXD_INIT_DATA put them in _ITEXT and _IDATA, thrown away once the VxD has initialized, and VXD_PAGEABLE_CODE and VXD_PAGEABLE_DATA in _PTEXT and _PDATA, which can be paged out (not for interrupt handlers). JWlink makes an object of each kind, with the flags the VMM's loader tells them by.
  • libvxd.a also provides memcpy, memmove, memset, memcmp and strlen, and libgcc.a the 64-bit arithmetic.

A VxD can provide services of its own, and needs a device ID to do so. Pick one Microsoft didn't assign; the tests use 0x3E5A.

  • VXD_DEVICE_EX(NAME, ID, INIT_ORDER, MAJOR, MINOR, V86, PM, SERVICES) is VXD_DEVICE with more fields filled in. V86 and PM are the entry points a DOS or Windows program finds with int 2Fh AX=1684h BX=ID (two VXD_CALLBACKs, or 0). They get the caller's registers through r->ebp, a struct vxd_client_regs; set or clear VXD_CLIENT_CARRY in its eflags for the caller's carry flag. SERVICES is the service table, or 0.
  • VXD_SERVICES(NAME, a, b, ...) defines NAME_Services, numbered from
  • A service is a VXD_CALLBACK (register) or a C function.
  • Another VxD calls those services with VXD_CALL_ID(&regs, VXD_SERVICE(ID, N)) for a register service. For a C one, it declares VXD_C_SERVICE(Call_Name, ID, N) and a prototype, then calls Call_Name(...).

<vcomm.h> (which includes <vxd.h>) is for VCOMM port drivers, the VxDs that drive a serial or parallel port for VCOMM on Windows 95, 98 and ME. It has PortFunctions, the table of the driver's 23 port functions (PortSetCommState to PortDeviceIOCtl, as typed function pointers), PortData, the state of an open port that PortOpen returns, and the _DCB, _COMMPROP, _COMSTAT, COMMTIMEOUTS and IORequest structures they take, with their constants (IE_*, EV_*, CE_*, MS_*, the DCB's f* masks, BAUD_*, the escape functions and so on). Their layouts and values are the 95, 98 and ME DDKs' (packed, as the DDK builds them). These are VCOMM's versions of the DCB and COMMPROP, not <winbase.h>'s, so a file can't include both. A driver calls _VCOMM_Register_Port_Driver from Sys_Dynamic_Device_Init, and _VCOMM_Add_Port from the function it registered. vxd/portdrv.c is a loopback port driver built that way.

The VMM's other subsystems have headers of their own, in sysroots/win9x-msvcrt/include/vxd, which win95-vxd.cfg searches after any kit's headers (a VxD built with an ms-*-vxd kit still gets the DDK's own). Each includes <vxd.h>, <vxdtypes.h> (the DDK base types they use, ULONG, PVOID and so on) and the headers it needs, and has that subsystem's constants, structures, unions, enumerations and typedefs, under the same names as the DDK's:

Header For
configmg.h, vmmreg.h the Configuration Manager (CONFIGRET, CR_*, CM_*, CMCONFIG, the resource descriptors, the handler types) and the registry
vpicd.h, vdmad.h, vtd.h interrupts, DMA and the timer
vwin32.h, vxdldr.h, shell.h VWIN32, the dynamic VxD loader and the SHELL device
vpowerd.h, pci.h, pccard.h, vcache.h power management, PCI, PC Card and the block cache
ifs.h the installable file system manager (ioreq, IFSFN_*, the handle function tables)
ior.h, blockdev.h, drp.h, ilb.h, sgd.h, med.h, vrp.h, aep.h, isp.h, irs.h, ios.h, dcb.h, iop.h, ida.h, ddb.h, dvt.h, ivt.h IOS and the layered block device drivers (.PDR port drivers and the rest)
ndis.h, netvxd.h NDIS 3.1 network drivers (from the 95 and 98 DDKs; ME's ndis.h is NDIS 5's, for WDM)
minivdd.h display mini-VDDs (the VxD half of a 95, 98 or ME display driver): vxd/minivdd.c gets VDD.VXD's dispatch table with VDD_Get_Mini_Dispatch_Table at Sys_Critical_Init and fills in VXD_CALLBACKs at the function numbers it handles
mmdevldr.h MMDEVLDR, which loads sound cards' VxDs and 16-bit drivers (its services, MMDEVLDR_Register_Device_Driver and _MMDEVLDR_SetDevicePresence and the rest, are in <vxdsvc.h>)
vkd.h, vmd.h the keyboard (SS_* shift states, the hot key flags, Paste_Rec) and the mouse (VMD_Type_*, Mouse_Instance, the cursor drawing VxD structures)

Each declaration is under #if VXD_WINVER >= the first DDK that has it, and one that changed between DDKs (a count of functions that grew, a structure with a new field) has each DDK's version. dcb.h's _DCB is IOS's device control block, not <vcomm.h>'s, so a file can't include both, as with the DDKs. tools/gen-vxd-headers.py made these headers from the 95, 98 and ME DDKs' (with the block device ones from the DDKs' block/inc): it reads the names, values and types from clang's AST and preprocessor, leaving out comments, code and the service wrappers (<vxdsvc.h> has the services), and writes vxd/layout/*.c, which vxd/run-tests.sh compiles to check that each structure's size and offsets are the ones the DDK's compiler gave it. To make them again:

python3 tools/gen-vxd-headers.py --kits ~/kits PACKAGE/bin

with the ms-w95-vxd, ms-w98-vxd and ms-me-vxd kits imported into PACKAGE and ~/kits the folder import-ms-sdk.py read them from.

The DDKs have VKD's, VMOUSE's and MMDEVLDR's only as MASM include files (vkd.inc, vkdpaste.inc, vmd.inc, mmdevldr.inc), so tools/gen-vxd-inc.py PACKAGE/bin makes vkd.h, vmd.h and mmdevldr.h: it evaluates their EQUs, writing each as the number it comes to, and lays out their STRUCs and UNIONs byte-packed as MASM does, for vxd/layout/vkd.c and vmd.c to check.

An IOS port driver (.PDR, which IOS loads from SYSTEM\IOSUBSYS at boot) is a dynamic VxD whose Sys_Dynamic_Device_Init calls IOS_Register with its DRP (<drp.h>): the DRP names its load group (DRP_LGN), its async event routine and the ILB (<ilb.h>) IOS fills in. IOS then calls the routine with each AEP (<aep.h>), and the driver asks IOS for things with ISPs (<isp.h>) through ILB_service_rtn. For example, vxd/iospdr.c is a port driver with no devices that does this and records the events it got in the registry:

clang --config=win95-vxd.cfg -O2 -c iospdr.c -o iospdr.o
python3 share/clang-dos/vxd-link.py --name IOSPDR -o IOSPDR.PDR iospdr.o

vxd-link.py --version 1.2.3.4 adds a VERSIONINFO resource the way Microsoft's VxDs carry one, with --product-version, --description, --company, --product and --copyright for its strings. The resource goes at the end of the file, with LE header fields 0xB8 and 0xBC pointing to it. vxd-check.py validates it and prints the version.

Unloading a VxD that provides services fails with VXDLDR error 9 ("device unloadable") on Windows 98. That happened once another VxD had called its services through int 20h, which the VMM patches into direct calls. A VxD that provides services should expect to stay loaded.

Win32 services are the ones a Win32 program calls with KERNEL32's VxDCall0 to VxDCall8 (exports 1 to 9, by ordinal) and ID << 16 | N. Microsoft never documented how Windows calls them, and vxd/w32svc.c found out on Windows 98. VWIN32 calls a service stdcall with two dwords before the program's parameters: the caller's registers (a struct vxd_client_regs) and the VM handle. VxDCall then returns the caller's EAX from that structure. VXD_WIN32_SERVICE(Name, Fn, N) makes a service from a C function DWORD Fn(struct vxd_client_regs *c, DWORD vm, DWORD a1, ... aN) and stores its return value there. List the services in VXD_WIN32_SERVICES(NAME, VXD_WIN32(Name, N), ...) and call VXD_REGISTER_WIN32_SERVICES(NAME) from Device_Init or Sys_Dynamic_Device_Init. That calls the VMM's _Register_Win32_Services, which fills in the DDB's Win32 service table.

More of what <vxd.h> has, each with a sample in vxd/:

  • DeviceIoControl that finishes later (vxd/async.c, called by vxd/asyncc.c). When a program passes an OVERLAPPED, the VxD can lock the output buffer and the OVERLAPPED with vxd_lock_global (global addresses, valid in any context). It then returns VXD_DIOC_PENDING, so DeviceIoControl fails with ERROR_IO_PENDING. Later, from a time-out, an event or an interrupt, the VxD writes the answer, calls VWIN32_DIOCCompletion(overlapped, bytes) (VWIN32's VWIN32_DIOCCompletionRoutine) and unlocks both with vxd_unlock_global. The program's GetOverlappedResult then returns with the byte count.
  • Hooking a service (vxd/hook.c). vxd_hook_service(VXDSVC_Name, Hook, &prev) makes every call to a VMM or VxD service go to Hook, and vxd_unhook_service undoes that (95 and later; a dynamic VxD must unhook before it unloads). VXD_HOOK_REG(Hook, Fn, prev) makes a hook for a register service. It calls int Fn(struct vxd_regs *), which returns VXD_HOOK_PASS to go on to the previous handler, or VXD_HOOK_DONE or VXD_HOOK_FAIL to return to the caller. VXD_HOOK_C(Hook, Fn, prev) makes a hook for a C service. Both give the hook the prologue the VMM uses to chain hooks (jmp short, then jmp [prev]).
  • Services that take their parameters on the stack, such as IOS_Register. VXD_STACK_SERVICE(fn, Name) defines fn as a stub that jumps to the service (int 20h with the VxDJmp bit), so a prototype and a call are all it needs. vxd/iospdr.c uses it.
  • Calling real-mode code in the current VM (vxd/bios.c). vxd_exec_int(n, &regs) saves the VM's registers, runs software interrupt n there with nested execution, with struct vxd_int_regs in and out, and restores the registers. bios.c reads the base memory size with INT 12h and the tick count with INT 1Ah.
  • Debug output. With -DVXD_DEBUG, Trace_Out("text") and Debug_Printf("fmt", ...) print to the debugger (WDEB386, SoftICE or the debug VMM's terminal). VXD_ASSERT(e) prints the file and line and breaks into the debugger, if one is installed, when e is false. Without -DVXD_DEBUG they compile to nothing.

vxd-link.py --sym HELLO.SYM also writes a .SYM file for WDEB386 and SoftICE. tools/mapsym.py makes it from JWlink's map file, with the public and static symbols of each object. For objects compiled with -g, the file also gets their line numbers. JWlink leaves the DWARF out of the VxD, so mapsym.py reads each object's line table and places it using the map's symbols.

vxd-link.py writes a dynamic VxD by default, the kind Win32 programs load with CreateFile("\\\\.\\C:\\PATH\\HELLO.VXD", ...) and call with DeviceIoControl. --static writes one that SYSTEM.INI loads with device=. --win31 writes a Windows 3.1 VxD; compile it with win31-vxd.cfg, which sets VXD_DDK_VERSION to 3.10. The VxD's name defaults to the output's base name in upper case (at most 8 letters), and it must match the NAME given to VXD_DEVICE. vxd-check.py checks the LE header, each object's kind, the DDB and the control procedure, which must be locked.

vxd/hello.c is a dynamic VxD that answers an IOCTL with a 64-bit computation and the VMM's version, and vxd/client.c is its Win32 client. vxd/services.c allocates from the heap, writes and reads the registry, sets a time-out and an event from init code and answers from pageable code. vxd/provider.c provides services, V86 and PM entry points and two Win32 services. client.c, vxd/apitest.c (a DOS program) and vxd/w32svc.c call it, and all three ran on Windows 98 SE. CFGDIR=~/clang-dos/bin sh vxd/run-tests.sh builds hello.c as a dynamic, static and Windows 3.1 VxD, and services.c, provider.c, async.c, hook.c and bios.c as dynamic ones, at -O0, -O2 and -Os, and checks each build. No emulator runs VxDs, so with WIN9X_RUN set to a command that runs CLIENT.EXE on a real Windows 9x, the dynamic ones are loaded too. hello.c and services.c have run on Windows 98 SE; async.c, hook.c and bios.c have not yet.