WinDriver/CLAUDE.md

Win31drv Project Memory

Build Environment

• DJGPP cross-compiler: ~/djgpp/djgpp/bin/i586-pc-msdosdjgpp-gcc (GCC 12.2.0)
• DJGPP binutils need libfl.so.2: stored in tools/lib/ (Makefiles set LD_LIBRARY_PATH)
• CWSDPMI zip stored in tools/cwsdpmi.zip (extracted to bin/ during build)
• DOSBox-X: flatpak run com.dosbox_x.DOSBox-X (installed as user flatpak)
• CWSDPMI.EXE in bin/ directory for DPMI support under DOSBox-X
• Config: dosbox-x.conf with S3 Trio64 machine type, 64MB RAM

Project Structure

windriver/
├── Makefile          # Top-level: builds demo, calls win31drv/Makefile
├── demo.c            # Demo program
├── dosbox-x.conf     # DOSBox-X config (S3 SVGA)
├── obj/              # Demo object files
├── bin/              # Executables + CWSDPMI.EXE
└── win31drv/         # Library
    ├── Makefile      # Builds libwindrv.a
    ├── obj/          # Library objects
    ├── neload.c/h    # NE format loader
    ├── neformat.h    # NE structures
    ├── thunk.c/h     # 32→16 bit thunking
    ├── windrv.c/h    # Main API
    ├── winstub.c/h   # Windows API stubs
    ├── winddi.h      # DDI structures
    └── wintypes.h    # Win16 types

DJGPP Portability Notes

• uint32_t is unsigned long (not unsigned int) in DJGPP — use PRIu32/PRIX32 from <inttypes.h>
• Always include <stdarg.h> explicitly for va_list/va_start/va_end
• Headers must be self-contained (include their own dependencies)

Thunking Architecture Notes

• SS == DS == DGROUP: Win3.x drivers assume SS == DS == DGROUP. VBESVGA's BBLT.ASM does PrestoChangeoSelector(SS, WorkSelector) to create a code alias for compiled blit code. thunkCall16 uses dgroupSel as SS (SP=0xFFF0) when available. Without this, the code alias has the wrong base and the CPU executes garbage.
• Register corruption with -O2 inlining: When demo.c's demoDrawing is inlined into main, DJGPP GCC 12.2.0 mishandles callee-saved registers across thunk calls in long functions. Fix: __attribute__((noinline)) on demoDrawing. Symptom: handle pointer corrupted to a ColorInfo return value (e.g. 0xFF0001F6) between Demo 2 and Demo 3.

DOSBox-X Driver Notes

• waitForEngine(): GP_STAT port 0x9AE8 bit 9 polling — S3 only (gIsS3 guard)
• S3 detection: Probe CR30 chip ID register. S3 chips: 0x81-0xE1. ET4000: 0x00. Only apply S3-specific setup (cursor disable, dispYOffset, setDisplayStart) when isS3=true AND driver is not VGA-class (1bpp/4planes).
• Pattern scratch artifact: S3 driver writes 8x8 dithered brush pattern to VRAM at fixed position (~(144,1)-(151,8)) during accelerated pattern fills. Fixed by shifting CRTC display start down 10 scanlines (dispYOffset) so the scratch area is off-screen. All drawing Y coordinates are offset by dispYOffset. The full dpVertRes (600) is reported and usable — the shift just consumes slightly more VRAM.
• S3TRIO BitBlt source corruption: S3TRIO's accelerated BitBlt corrupts source VRAM during source-dependent ROP operations (SRCINVERT, NOTSRCCOPY, SRCAND, SRCPAINT). In Windows 3.1, GDI uses intermediate off-screen bitmaps. Our direct DDI calls must work around this by redrawing source rects after the ROP, or using separate source areas. Off-screen VRAM (y >= screenH) is NOT usable — the driver clips to screen dimensions.
• -fno-gcse required for windrv.c: With -O2 GCSE, stack layout causes issues during 16-bit driver calls. Only windrv.c needs this. See WINDRV_CFLAGS in win31drv/Makefile.
• Output DDI (polylines/rectangles) requires a physical pen from RealizeObject, not a raw LogPen16T. The pen must be in DGROUP (same as brush, drawMode, PDEVICE).
• Curve primitives removed: Ellipses, polygons, roundrects, arcs, and pies were removed because DIB engine drivers (VBESVGA/ET4000) hang (expect GDI curve decomposition callback) and S3TRIO only partially renders them. Only polyline is reliable via Output DDI.
• OS_RECTANGLE crashes DIB engine drivers: VBESVGA/ET4000 Output(OS_RECTANGLE) crashes like curve primitives. wdrvRectangleEx draws rectangles as two 3-point polylines instead.
• Output DDI lpClipRect: DIB engine drivers (VBESVGA) dereference lpClipRect unconditionally in polyline paths too. Always pass a valid clip rect (0,0,0x7FFF,0x7FFF).
• wdrvUnloadDriver does NOT auto-call Disable — caller must handle text mode restore
• sleep() hangs under DOSBox-X because BIOS timer ticks don't advance without I/O
• Debug output: -d flag enables verbose logging in neload, winstub, thunk, and windrv
• SetPalette DDI vs VGA DAC: VBESVGA's SetPalette DDI updates the driver's internal color table (used by ColorInfo for RGB→index matching) but does NOT program the VGA DAC hardware. In real Windows 3.1, GDI programs the DAC separately. wdrvSetPalette works around this by also writing DAC registers directly (ports 0x3C8/0x3C9) after the DDI call. This is idempotent on drivers like S3TRIO that already program the DAC.
• DAC width: S3TRIO uses 6-bit DAC (values 0-63), VBESVGA uses 8-bit DAC (values 0-255). Detected at Enable via VBE 4F08 subfunc 01. Both wdrvSetPalette (port write) and readDacPalette (screenshot) use the detected width for correct shift amounts. Wrong shift causes dark display (6-bit values in 8-bit DAC = 1/4 brightness).
• Known issue: mode mismatch HW=800x600 vs GDIINFO=640x480

DGROUP Stack Management

• VGA.DRV ships with DGROUP[0x0A]=0xFFFF (stack bottom = top of segment → no stack). Its BitBlt prolog calls a stack check function at 0x18CA that compares available stack against [SS:0x0A]. With 0xFFFF, ALL functions fail immediately (return 0).
• Fix: patch [0x0A] to objBase after extending DGROUP. Only done when original = 0xFFFF.
• S3TRIO.DRV and VBESVGA.DRV have [0x0A]=0x0000 — no patching needed.
• Do NOT unconditionally overwrite DGROUP offsets 0x00-0x0F — VBESVGA.DRV stores driver-specific data there (0x030A at offset 0, 0x01 at offset 4).

BitBlt Source Device Rules

• For pattern-only ROPs (PATCOPY=0xF0, BLACKNESS=0x00, WHITENESS=0xFF, etc.), lpSrcDev must be NULL (0:0) per DDI spec. VGA.DRV rejects non-NULL source for pattern-only ROPs. S3TRIO.DRV tolerates it but correct behavior is NULL.
• Source dependency check: ropNeedsSrc = (((rop8 >> 2) ^ rop8) & 0x33) != 0

ExtTextOut DDI Notes

• Font format: VBESVGA.DRV requires .FNT v3 (fsVersion=0x0300) when BigFontFlags is set (386 protected mode with WF_PMODE + WF_CPU386). v2 (0x0200) is rejected at runtime.
• v3 char table: at file offset 0x94 (fs30CharOffset), 6-byte entries {WORD width, DWORD offset}. The DWORD offset is absolute from the font segment base. Use FntCharEntry30T.
• Bitmap layout: per-character contiguous, column-major byte order. For each character, all pixHeight rows of byte-column 0 come first, then all rows of byte-column 1, etc. Address formula: (byteCol * pixHeight) + row. For 8px-wide chars (1 byte column), this is identical to row-major. VGA BIOS 8x16 font is already in this format — no transpose needed.
• lpClipRect must NOT be NULL: VBESVGA's get_clip unconditionally dereferences lpClipRect (STRBLT.ASM:1008 "We assume that we will never get passed a null rectangle"). Pass a RECT covering the full screen (0, 0, 0x7FFF, 0x7FFF).
• lpTextXForm: declared but never read by VBESVGA — pass NULL.
• lp_font offset: passed as fontSel:0x42 (points to fsType within the .FNT block).
• Return value: DX bit 15 = error. AX=0 is NOT necessarily failure.

INT 10h ES Translation

• Different INT 10h function families use different ES:offset registers: VBE 4Fxx → ES:DI, AH=10h (palette) → ES:DX, AH=11h (fonts) → ES:BP, AH=1Bh → ES:DI
• Only specific AL subfunctions use ES as a buffer pointer; most don't
• Copy sizes must be exact (17 bytes for palette, CX*3 for DAC blocks, etc.)
• Copy direction matters: "Set" = copy-in only, "Read/Get" = copy-out only

WINFLAGS Handling

• WF_80x87 NOT used: We don't save/restore FPU state across thunk boundaries
• VGA-class drivers need WF_STANDARD: VGA.DRV's physical_enable hangs in Enhanced mode (polls VDD that doesn't exist). Auto-detected after Enable(style=1) returns 1bpp/4planes GDIINFO → repatch __WINFLAGS in all segments (0x0025→0x0015).
• SVGA drivers (S3TRIO, VBESVGA) use WF_ENHANCED normally

ET4000 Driver Notes

• ET4000.DRV from Win 3.x distribution is SZDD-compressed; decompress with msexpand (rename to .DR_ first, output is .DR without the V — rename to .DRV)
• DOSBox-X machine type: svga_et4000 for ET4000 hardware emulation
• ET4000 is 640x480 8bpp, software-rendered (no accelerator engine in DOSBox-X)
• CR30=0x00 on ET4000 → isS3=false → no S3 engine wait, no display start shift
• GetPixel breaks ScanLR on ET4000: The Pixel DDI with color=-1 (get mode) leaves VGA hardware state (likely GR5 read mode) that causes ScanLR to not match the pixel just read. GetPixel itself returns correct values; only the ScanLR interaction is broken. Flood fill software path avoids GetPixel entirely, using ScanLR for all pixel-color queries.

Font Loading Notes

• .FON files are NE containers with RT_FONT (type 8) resources; each resource is raw .FNT data
• All Win 3.x .FON files contain v2 fonts (0x0200); VBESVGA.DRV requires v3 (0x0300)
• v2→v3 conversion: insert 30-byte extension at 0x76, expand 4-byte char table to 6-byte entries
• v2 char table offsets are absolute from segment base, not relative to fsBitsOffset. Correct v3 offset = v2offset + shift (where shift = newBitmapOff - origBitsOff)
• wdrvLoadFontFon(path, index) loads from .FON; wdrvLoadFontFnt(path) loads raw .FNT
• wdrvLoadFontBuiltin() returns the VGA ROM 8x16 singleton; must NOT be passed to wdrvUnloadFont
• wdrvLoadFontTtf(path, pointSize) loads TrueType via stb_truetype, rasterizes to 1-bit v3 FNT
• wdrvExtTextOut takes a WdrvFontT font parameter (NULL = built-in)
• Available test fonts in fon/: COURE.FON (8x13, 9x16, 12x20), SSERIFE.FON, SERIFE.FON, VGASYS.FON, etc.
• Available TTF fonts in ttf/: LIBMONO.TTF, LIBSANS.TTF, LIBSERIF.TTF (Liberation family)

Current Demo Status

• S3TRIO.DRV, VBESVGA.DRV, VGA.DRV, ET4000.DRV all work: Load → Enable → Draw → Disable → Unload
• Demo 1: Fill rectangles (BitBlt) — works
• Demo 2: Pixel patterns (Pixel) — works
• Demo 3: Lines/starburst (Output/Polyline) — works
• Demo 4: Screen-to-screen blit (BitBlt SRCCOPY) — works
• Demo 5: ExtTextOut text rendering — works (VBESVGA.DRV)
• Demo 7: TrueType font rendering at multiple sizes — works
• Demo 8: Color text showcase (fg/bg colors, opaque/transparent, palette grid) — works
• Demo 9: ROP3 operations (DSTINVERT, SRCINVERT, NOTSRCCOPY, SRCAND, SRCPAINT) — works
• Demo 10: ScanLR + Flood Fill (FB or software fallback) — works on all drivers
• Demo 11: Text measurement (GetCharWidth DDI, wdrvMeasureText) — works
• Demo 12: Styled pen lines (software Bresenham, all drivers) — works
• Demo 13: Pixel buffer blit (FB or software fallback) — works on all drivers
• Demo 14: Hardware cursor (arrow, crosshair, ibeam, hand; animated circle) — works
• Demo 15: Screen save/restore (screen-to-screen BitBlt stash/restore) — works
• VGA.DRV: 640x480 4-plane 16-color mode; limited color palette but functional
• ET4000.DRV: 640x480 8bpp on svga_et4000; software-only, no hw acceleration
• Drivers stored in drivers/ directory, copied to bin/ during build

Software Rendering Fallbacks

• Styled pens: Always software-rendered via Bresenham + Pixel DDI (PS_SOLID uses HW Output DDI). S3TRIO silently accepts styled pens but doesn't render them; software path gives identical output everywhere.
• Flood fill: Uses direct FB when available, falls back to ScanLR DDI + FillRect. Cannot use GetPixel — ET4000 DIB engine's Pixel DDI (color=-1) corrupts VRAM, causing subsequent ScanLR to not match the read pixel. Seed color is determined by probing ScanLR with each palette index until a match is found.
• Pixel blit: Uses direct FB memcpy when available, falls back to per-pixel SetPixel with PALETTEINDEX.
• All four drivers (S3TRIO, VBESVGA, ET4000, VGA) now have identical feature sets.

New API Functions (added with demos 9-15)

• wdrvScanLR(handle, x, y, color, style) — ScanLR DDI wrapper (ordinal 12)
• wdrvFloodFill(handle, x, y, fillColor) — scanline flood fill (FB or software)
• wdrvGetCharWidths(handle, font, firstChar, lastChar, widths) — GetCharWidth DDI
• wdrvMeasureText(handle, font, text, length) — sum char widths for string
• wdrvPolylineEx(handle, points, count, color, penStyle) — polyline with pen style
• wdrvRectangleEx(handle, x, y, w, h, color, penStyle) — rectangle with pen style
• wdrvBlitPixels(handle, x, y, w, h, pixels, srcPitch) — pixel blit (FB or software)
• wdrvBlitBmp(handle, x, y, bmpPath, setPalette) — load+display 8bpp BMP
• wdrvSetCursor(handle, shape) — built-in cursor shapes (arrow/crosshair/ibeam/hand/none)
• wdrvSetCursorCustom(handle, hotX, hotY, andMask, xorMask) — custom 32x32 mono cursor
• wdrvMoveCursor(handle, x, y) — move hardware cursor
• wdrvCreateBitmap(handle, width, height) — CreateBitmap DDI
• wdrvDeleteBitmap(handle, bitmap) — DeleteBitmap DDI
• wdrvBitmapSetPixels/GetPixels(handle, bitmap, data, size) — BitmapBits DDI
• wdrvBitBltFromBitmap/ToBitmap(handle, bitmap, ...) — BitBlt with bitmap PDEVICE
• wdrvScreenshot(handle, filename) — capture screen to PNG (FB or DDI fallback)