TeslaRel410/emulator/VDB-NOTES.md

The VDB — VWE Video Display/Splitter Board

Reverse-engineered from the shared MUNGA_L4 driver (CODE/RP/MUNGA_L4/ L4SVGA16.ASM + L4VB16.CPP/.HPP) and the pod emulator's HLE (emulator/vpx-device/vpxlog.cpp). A physical VDB sample + its companion Cirrus Logic SVGA card exist (operator, 2026-07-10) — see the hardware verification checklist at the end. This board is IDENTICAL between BattleTech and Red Planet (shared driver); only the game-side display layout differs.

What it is

An ISA card that taps the companion Cirrus Logic SVGA card's pixel output off the VGA feature connector and fans that ONE framebuffer out to the six secondary cockpit displays (5 mono MFDs + 1 color radar) via three RAMDAC-like palette groups. It is a DUMB splitter: no framebuffer of its own, no compute — it re-clocks the SVGA pixel stream and routes byte-lanes through palette CLUTs to separate VGA heads. "Adam's port decoder design" (Adam G., VWE hardware) per the driver comments.

The game renders cockpit gauges to the Cirrus SVGA in a 640x480x16bpp mode (VBE mode 0x111; L4GAUGE=640x480x16). The Division/VPX card is separate (the out-the-window 3D). So the SVGA framebuffer the VDB taps = GAUGES ONLY.

Register map (definitive, from L4SVGA16.ASM)

I/O 0x300-0x31A. Three palette groups, each a 6-bit VGA-DAC-style CLUT. The driver's port table (L4VB16.CPP ~3685) passes the group base as base+2:

Group           base(+2)   mask   read-addr  write-addr  data
NativePalette    0x3C6     (the Cirrus's own VGA DAC — 0x3C6/0x3C8/0x3C9)
SecondaryPalette 0x302     0x302    0x303      0x304      0x305
AuxiliaryPal1    0x30A     0x30A    0x30B      0x30C      0x30D
AuxiliaryPal2    0x312     0x312    0x313      0x314      0x315

Clock divider:  0x319 write = high-color divider OFF (VWE_HC_OFF)
                0x31A write = high-color divider ON  (VWE_HC_ON)  (any value)

Per-group offsets (VGA-DAC layout): +0 pixel-mask, +1 read-address, +2 write-address, +3 data (auto-incrementing R,G,B triplets). DAC is 6-bit: SVGAWriteFullPalette does shr al,2 (8→6) on write, SVGAReadFullPalette does shl al,2 (6→8) on read. Palette load = set write-addr to 0, then rep outsb 256*3 bytes. Mask write = one out to base+0. The game only WRITES the VDB (fire-and-forget, no status/ACK); reads return DAC read-back.

How the split works (the dumb part)

High-color clock divider (0x31A on): in 16bpp mode each pixel is two bytes. The divider clocks the LOW byte and HIGH byte of each pixel into SEPARATE palette lanes → separate heads. So:

• LOW byte (bits 0-7) -> Secondary palette (0x302 group) -> one head
• HIGH byte (bits 8-15) -> Aux1/Aux2 palettes -> the other heads

Each head is a physical VGA output off the splitter; an "octopus" cable fans the (up to) three head signals to the six cockpit displays. Decode confirmed live for BT: radar = low byte via Secondary; the 5 mono MFDs = high byte via Aux1/Aux2 color channels. vdb-three-vga-head-decode

How the game packs multiple displays into one framebuffer

The card is dumb, but the DRIVER is clever about loading the CLUTs so several displays share the same pixels. Each cockpit display (L4GraphicsPort) has:

• bitMask — which framebuffer pixel BITS belong to this display.
• channelEnable — which DAC color channel it drives: Red / Green / Blue / AllChannels (+ ...TransparentZero variants that leave index 0 undefined).

BuildSecondaryPalette (low byte = bitMask & 0xFF) and BuildAuxiliaryPalette (high byte = (bitMask>>8) & 0xFF) walk the display's bits with a BitWrangler and write that display's color/ramp into its channel of the shared 256-entry CLUT. So N mono displays coexist in one byte-lane by owning disjoint bit groups and different color channels; the CLUT decodes each combination back to the right per-display brightness. BuildAuxiliaryPalette generates a linear brightness RAMP across the display's bit values (mono MFD = beam intensity); BuildSecondaryPalette copies source colors (color radar).

Palette flash + fade (the pixel-mask cycling)

SVGA16::UpdatePalette (L4VB16.CPP ~4196): each palette can FLASH by cycling its pixel-mask through mask[] states at flashRate (this is the 0x302 mask writes seen cycling e.g. 0x3F/0x7F/0xBF/0xFF — a blink, NOT index decode). Only the Secondary palette is allowed to FADE (its RGB scaled over time). So the pixel-mask register is used as a per-display blink control, not (usually) as a decode gate.

Our emulation (vpxlog.cpp)

vdb_write/vdb_read mirror the register map (VDB_BASE=0x300, vdb_group_of/vdb_group_base); vdb_pal[0/1/2] = Secondary/Aux1/Aux2. pal_draw reads the live Cirrus framebuffer (vga.mem.linear at vga.config.real_start, 640x480, stride 1280) and for each pixel looks up the low byte via pal0 and high byte via pal1/pal2 (one color channel per mono head, pentapus split). 6-bit DAC expanded to 8-bit. VDB_PALDUMP=<prefix> dumps each group's 768-byte CLUT; pixel-mask writes now log their value; masks default 0xFF; VDB_APPLYMASK=1 ANDs the index with the mask (correct DAC emulation, default off = BT-identical).

RP vs BT — the OPEN decode problem (2026-07-10)

Same board, same driver. Captured live for RP (VDB_PALDUMP): framebuffer identical (mode 0x111, 640x480); Secondary/pal0 loads ALL ZEROS (BT drives it as the dynamic color radar) -> our radar head is black; Aux1=green, Aux2=RGB are driven; the RP MFD heads decode as SPARSE fragments in the top strip. So under the shared mechanism, RP simply puts NO display in the low byte (Secondary empty is legitimate), and its high-byte MFD content is not landing where our BT-tuned head/channel split expects.

Operator's steer: the card is dumb, so the fix is glaringly simple — not a driver-logic difference. Leading suspects to check next (empirically, like the first BT pass): (a) the framebuffer PAGE/real_start — is RP double- buffering so we read a stale/wrong SVGA page? (SVGASetPage exists); (b) the device DUMP path stopped writing win*.bmp for RP (fires in pal_draw) — worth finding why, it may reveal the head-render path isn't running the same; (c) which bit groups/channels RP's displays actually claim (dump a BT vs RP Aux palette side-by-side; the ramp/channel structure shows the bit layout); (d) confirm the low/high byte order and the 640x480 vs a smaller gauge region (top-strip content hints RP may draw gauges in fewer rows).

Physical hardware (documented from the operator's sample, 2026-07-10)

CONFIRMS the reverse-engineering below the chip level:

• Companion video card: Jaton KY2-JAX-CVGA54PCI — a legacy PCI Local Bus VGA card, Cirrus Logic CL-GD5434 chipset. Renders the cockpit gauges (640x480x16, VBE 0x111) and feeds the pixel stream to the VDB via a 26-pin ribbon off the VGA Feature Connector.
• The splitter brain: AMD/Lattice MACH130-15JC CPLD — EE-CMOS, 64 macrocells, 15 ns max prop delay, 84-pin PLCC (2nd-sourced by Rochester Electronics). This is "Adam's port decoder": it CONSUMES the feature-connector video stream AND takes instructions from the ISA bus (the 0x300-0x31A register file — palette loads, masks, and the 0x319/0x31A high-color clock divider). It does the byte-lane split in hardwired logic (same for BT and RP).
• The three DACs: 3x Brooktree Bt477KPJ80 RAMDACs (256-entry, 6-bit/ channel, 80 MHz) = the three palette groups Secondary/Aux1/Aux2. The Bt477's 6-bit DAC is exactly why the driver does shr al,2 (8->6) on palette writes. Output routing (confirms the head map): one Bt477 -> a VGA stream to the color RADAR display (= Secondary/0x302); the other two Bt477s -> a DB25 connector that fans out to the 5 monochrome MFDs (= Aux1/0x30A R,G = 2 lower MFDs, Aux2/0x312 R,G,B = 3 upper MFDs; 5 mono wires total, one channel unused). The DB25 fan-out is the "octopus/pentapus" cable.
• Reset-tie component: a part wired in PARALLEL with the PC's front-panel RESET switch — either a remote-reboot path OR a means to force the VDB into a known state when the PC is reset (so the CPLD/DACs re-init cleanly). OPERATOR RESEARCHING. (Plausible: the CPLD needs a hard reset synchronized with the host, since it has no software reset in the 0x300-0x31A map -- only clock on/off; a reset tie guarantees the splitter isn't left mid-state.)

Still worth capturing for the archive

• Photos of each chip + the board silkscreen; the DB25 pinout (which pin -> which MFD) and the 26-pin feature-connector ribbon pinout.
• Whether the MACH130 JEDEC fuse-map is readable (a MACH130 can often be read back unless secured) -- that IS the splitter logic, the ultimate ground truth, and preservable like the RIO EPROM.
• The reset-tie circuit trace (operator's follow-up).

Related: vdb-three-vga-head-decode, tesla-cockpit-emulator-state.