CERBERUS

> Three heads. One machine. Zero pretending.

A DOS-native tool that detects, diagnoses, and benchmarks vintage PC hardware — and then cross-checks the three heads against each other.

CERBERUS is named after the three-headed dog of Greek myth that guarded the gates of the underworld. Each head is one of the three analysis domains:

• Detect — identifies CPU, FPU, memory, cache, bus, video, audio, and BIOS using layered probes and a community-editable hardware database
• Diagnose — walks memory with test patterns, validates ALU correctness, runs bit-exact FPU ops, probes VRAM
• Benchmark — integer / FPU / memory-bandwidth passes, calibrated multi-pass mode for thermal analysis

The three heads share a common body of timing, display, and reporting infrastructure. Their results feed a consistency engine that flags disagreements — this is the project’s reason to exist.

The consistency engine

Most DOS diagnostic tools tell you what your hardware says it is. CERBERUS tells you when what your hardware says it is disagrees with how it behaves.

Seven rules in force today:

• A 486DX must report an integrated FPU. If it doesn’t, that’s a counterfeit 486SX with a faked silkscreen — a real thing, documented in the VOGONS archives.
• A 486SX must NOT report an integrated FPU. If it does, your detection is confused or someone sold you a remarked chip.
• A 386SX cannot be on an ISA-8 bus. It has a 16-bit external bus by design; the combination is electrically impossible.
• FPU diagnostic PASS and FPU benchmark result must agree. One head saying “it works” while the other couldn’t exercise it means something is wrong.
• Extended memory reported on an 8088 is physically impossible. 8088-class CPUs cannot address memory above 1MB.
• PIT Channel 2 timing must agree with BIOS-tick timing within 15% over a fixed interval. The two PIT channels share the 1.193182 MHz crystal but run independently. Disagreement catches 16-bit integer overflow bugs in the tool’s own timing code — the runtime backstop against a recurring bug class.
• 8086-class CPUs must be on an ISA-8 bus. PCI on a 4.77 MHz 8088 is not a thing.
• Mann-Kendall rank trend test on per-pass benchmark timings. Monotonic upward drift at α=0.05 flags thermal throttling — dusty heatsink, dying voltage regulator, failing capacitor.

Every rule documents what it catches AND what it structurally cannot. A rule that only catches asymmetric failures says so explicitly. Opacity is the anti-pattern.

Output

CERBERUS writes a machine-parseable INI file with every detected property, diagnostic verdict, benchmark result, and consistency-rule outcome. Each row carries a confidence indicator — HIGH when the probe is authoritative, MEDIUM when inferred, LOW when emulated or guessed. Running inside DOSBox-X automatically caps all confidence at MEDIUM because emulated hardware isn’t ground truth.

Two signatures land in every INI:

• signature — SHA-1 over the seven canonical hardware-identity keys (CPU, FPU, memory, video, bus). Stable across tool versions on the same machine. Same hardware, different run → same signature.
• run_signature — SHA-1 over the full INI. Differs between runs even on the same machine. Two runs of the same machine with divergent run_signatures under the same signature is the project’s planned counterfeit-CPU detection mechanism.

Target hardware

8088 support is a hard requirement, not an aspiration. Anything that breaks it is out.

Technical

121 seed entries across five identification databases (CPU 34, FPU 14, video 28, audio 24, BIOS 21). Every DB is a human-editable CSV with a Python build script that generates the C lookup tables. If CERBERUS can’t identify your chip, the raw probe data gets captured to CERBERUS.UNK and the summary tells you how to submit a GitHub issue that grows the database.

Hardware-identity hash vs counterfeit detection

The dual-signature scheme is designed so that when two runs of the same machine produce different run_signature values under the same signature, CERBERUS has evidence that the hardware’s behavior changed even though its claimed identity didn’t. That’s the fingerprint of a remarked CPU, a thermal fault, a BIOS setting change, or some other shift in actual behavior without a corresponding change in reported identity.

During the 7-round adversarial quality gate, a systemic bug was caught across twelve files: stack-local sprintf buffers were passed to the result-table builder, which stores the pointer without copying. After each function returned, the hash was being computed over dangling stack bytes. Hardware signatures varied run-to-run on the same machine — exactly the opposite of the design contract. Fix was a cross-codebase sweep promoting every site to file-scope static storage with documented lifetime contracts. The bug had been invisible to CI because host tests only checked verdict, never display. Test suite now includes coverage for the display-string-readback case too.

Download

There is no public release yet. The v0.2.0 tag ships after Task 1.10 — real-hardware validation on 486 / 386 / 8088 class machines — completes. Watch the releases page or the build log.

Links

• GitHub: tonyuatkins-afk/CERBERUS (source, hardware databases, consistency rule docs)
• Consistency engine methodology (what each rule catches and what it structurally cannot)
• Design document (the full architecture write-up)
• NetISA project page (the hardware side — CERBERUS uses /U to upload INIs over NetISA when that ships)
• Build log (milestones and progress)