s3ctl v1.0.0 — first stable release

Runtime control utility for S3 ViRGE and S3 Trio graphics chips on DOS.
Fixes the "grey blacks" pedestal bug at boot, reads and writes MCLK,
detects chip family through a four-tier strategy, and does all of it
without ever touching the video BIOS. All changes are volatile and
reset on reboot — which is the design, not a limitation.

Quick start

Add a single line to your AUTOEXEC.BAT:

S3CTL.EXE -q pedestal off

And the grey-blacks bug is fixed at every boot.

What's in this release

Pedestal fix (the original motivation):

• Read-modify-write of only the pedestal bit (bit 5 on ViRGE SR1A,
  bit 3 on Trio 3D SR27) — leaves the other 7 bits as the BIOS
  programmed them
• pedestal on / pedestal off semantics (plus 0 / 1 aliases
  for AUTOEXEC.BAT compatibility)
• pedestal raw <byte> escape hatch for experimentation with
  warning about touching non-pedestal bits

Chip detection (four tiers, falls through on failure):

1. --chip=NAME override (virge / trio3d / trio / auto)
2. PCI BIOS scan via INT 1Ah AX=B101h/B102h, vendor 0x5333
3. CRTC extended register probe (CR2D / CR2E)
4. SR1A sequencer probe (last resort, assumes ViRGE on match)

Recognizes PCI device IDs 0x8810, 0x8811, 0x883D, 0x8904, 0x8A01,
0x8A10, 0x8C01. Detection tier and PCI device ID are shown by
s3ctl info.

MCLK read/write:

• Reads SR10 / SR11, decodes PLL state with the corrected VCO
  formula VCO = ((M+2)/(N+2)) * 14.318
• Writes new PLL values within a 30–60 MHz safety range
• Compares overclock target against current MCLK (not a fixed
  reference), so the >5 MHz jump warning works correctly on
  OEM-integrated parts that ship at non-reference values (e.g.
  Toshiba Infinia ships at ~60 MHz, not the S3 reference 45)

Diagnostics (s3ctl -v info):

• Full clock-synth dump: SR10/SR11 (MCLK), SR12/SR13 (DCLK),
  SR0E/SR0F (PLL ext bits), SR15 (load ctrl), SR18 (clock source)
• Both MCLK and DCLK decoded to MHz so you can cross-validate
  what each register pair actually means on your silicon
• VRAM size, color mode, chip revision (where readable)
• Raw CR register dump

Quality of life:

• Case-insensitive arguments per DOS convention (S3CTL INFO,
  s3ctl info, S3CTL --Chip=Virge all work)
• -q quiet mode for AUTOEXEC.BAT
• -v verbose mode for diagnostics
• Per-command help, error messages name the failing register

Verified hardware

S3 ViRGE/DX (86C375) integrated on a Toshiba Infinia desktop
(Intel TC430HX, AMI BIOS 1.00.08.DH08, 32 KB video BIOS dated
12/05/96). Pedestal fix and MCLK read/write confirmed working.

Known gaps

• Trio 3D pedestal path UNTESTED on hardware. The SR27 bit 3
  mapping comes from documentation by Bits Und Bolts; the code
  follows the published spec but nobody has yet verified it
  empirically. If you have a Trio 3D card, please try
  s3ctl pedestal off and report results.
• Legacy Trio (32 / 64 / 64V+ / 64V2) pedestal unsupported.
  Neither the datasheets nor any open-source driver document
  which register controls the pedestal on these chips. The
  utility detects them but refuses pedestal on/off. Contributions
  welcome — see "Pedestal register contributions" in the README.
• CRTC extended registers inaccessible on some OEM systems.
  When CR2D / CR2E return 0x80, s3ctl info shows n/a for
  revision / VRAM / color mode. The pedestal and MCLK paths
  still work via the sequencer.
• See README "Known issues & testing wanted" for the full list
  and how to contribute reports.

Documentation

• README.md — user-facing usage, install, examples
• s3ctl_handoff.md — technical deep dive:
  chip detection strategy, register reference, pedestal research
  history, MCLK overclocking notes, video BIOS analysis
• Docs/ — S3 ViRGE and Trio datasheet PDFs for reference

Credits

Huge thanks to Bits Und Bolts (BuB) at
bitsundbolts.com for the research
this utility is built on:

• Fixing the S3 brightness bug — pedestal bit deep dive
• S3 ViRGE BIOS Toolkit
  (source of the corrected VCO formula)

The Linux kernel
drivers/video/fbdev/s3fb.c
provided the PCI device ID table and CR-register detection logic.

Build

Open Watcom 1.9 or 2.0:

C:\WATCOM\OWSETENV.BAT
wmake

Produces a single 16-bit real-mode DOS executable, small memory
model, no external dependencies.

License

GPL v3. See LICENSE.