A4091 Zorro III SCSI controller: board, 53C710 register model, minimal SCRIPTS engine

[codewiz]

Adds the Commodore A4091 as a Zorro III device board, staged bring-up guided by the open-source A4091 boot ROM and its ncr7xx hardware validation tool (https://github.com/A4091/a4091-software).

What's done

• Board scaffolding ([a4091] config section: rom + unit0..6): Z3 autoconfig identity (mfg 514 / product 84 / 16M window / DiagArea vector $0200), nibble-wide autoboot ROM serving with 32K-image mirroring, DIP-switch byte at $8C0003, debugger peeks for the ROM region. First Z3 device board on the Zorro chain -- the existing routing handled it with no changes.
• 53C710 register file: 64-byte register file mirrored across the whole $800000+ IO window (the board decodes only the low address bits; the driver's +$40 TEMP/SCRATCH write shadows depend on this), QEMU-matched reset values, CTEST8 chip revision, CTEST5 ADCK/BBCK strobes.
• DMA FIFO (4 lanes x 16 deep, 9-bit entries via CTEST6/CTEST4.FBL2, parity through CTEST7/CTEST2, live CTEST1 and DSTAT.DFE) and SCSI FIFO (8 deep via SODL/CTEST4.SFWR and CTEST3, generated odd/even parity per SCNTL1.AESP, count in SSTAT2).
• Interrupt plumbing: ISTAT.ABRT/RST strobes, computed DIP/SIP, read-to-clear DSTAT/SSTAT0, DIEN/SIEN gating, level-sensitive INT2 (semantics from Amiberry's qemuvga lsi53c710 core).
• Minimal SCRIPTS engine: DSP-triggered execution, instruction fetch by bus-master DMA (works for chip/slow/Z2/Z3 RAM -- the existing decode is address-width agnostic), MOVE-immediate-to-register (native register numbering), Memory Move (including moves targeting the board's own register window, via a new DeviceHost::for_slot self-window lookup), RETURN, INT; undecodable fetches raise DSTAT.IID like real silicon on a garbage fetch. COPPERLINE_DIAG_A4091=1 logs fetches and moves.
• Serial TCP sink (also split out as serial: bidirectional TCP sink (mode = "tcp") #121; this branch carries the same commit and will lose it on rebase once serial: bidirectional TCP sink (mode = "tcp") #121 merges): bridges Paula's serial port to a host TCP listener so an AUX: shell gives a scriptable remote console -- that is how this branch was tested.

How it was tested

• 20 unit tests covering the ROM nibble encoding, register file, shadows, strobes, both FIFOs, interrupts, and the SCRIPTS engine (including the self-window Memory Move).
• The ncr7xx validation tool from a4091-software, run on the emulated machine over the serial console after every increment. Current score, in suite order: Device access PASS, Register test PASS, DMA FIFO PASS, SCSI FIFO PASS, Bus access (interrupts + SCRIPTS fetch address-pin walk, incl. Z3 addresses) PASS, DMA test PASS, DMA copy PASS, DMA copy perf PASS. Only the SCSI pin test still fails (see below).
• The ROM's DiagArea boots end to end: expansion.library reassembles it from the nibble-wide window, a4091.device loads, passes its walking-bits hardware self-test, and starts issuing SCSI SELECT scripts (which the engine currently answers with an illegal-instruction stop, so the driver times out cleanly and the machine boots normally).

Still missing

• SCSI bus model / pin test: SBDL/SBCL must reflect the driven SODL/SOCL values (the 53C710 maps several read and write registers to different addresses; today they alias one storage cell), plus SCSI bus reset behavior.
• The SCSI phase engine: block moves, SELECT/WAIT DISCONNECT/table-indirect addressing, bridging to the existing scsi.rs target layer so a4091.device can actually scan the bus and mount [a4091] drive images (currently parsed but ignored, with a warning).
• Timing: SCRIPTS run synchronously inside the triggering register write; no bus arbitration is modelled (same simplification as the A2091's DMA).

Not caused by this branch, but found with it: ncr7xx's DMA test fails when MuForce+MuGuardianAngel trap the buffer writes (the AllocMem/FreeMem/AllocAbs alignment trick makes MuGA treat the buffer as free memory) -- the first trapped write loses its data somewhere in the 68040 access-error writeback path. Real hardware and Amiberry survive the same sequence. Will be reproduced and fixed separately.

🤖 Generated with Claude Code

[codewiz]

@reinauer , wanna review?

[LinuxJedi]

Oh wow! That kills one todo list item that has been in the back of my head. I won’t be able to review this one until I’m at a computer in a couple of days.

[Copilot]

Pull request overview

Adds initial emulation support for the Commodore A4091 Zorro III SCSI-2 controller (board identity + nibble-wide ROM + NCR 53C710 register model and a minimal SCRIPTS subset) and introduces a new bidirectional TCP-backed serial sink for remote console workflows.

Changes:

• Add new A4091 Zorro III device board, config surface ([a4091]), and machine wiring to place it on the Zorro chain.
• Implement an initial 53C710 register window model (mirroring, reset values, FIFOs, interrupt plumbing) plus a minimal SCRIPTS engine sufficient for ROM self-tests.
• Add SerialMode::Tcp and a TcpSerialSink implementation (plus launcher UI integration when built with midi feature).

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/zorro.rs	Adds BoardSpec::a4091() identity/config for the new Zorro III device board.
src/zorro_device.rs	Adds DeviceHost::for_slot() + self-window lookup, and wires BoardDevice::A4091.
src/video/launcher.rs	Extends launcher serial mode cycling to include TCP (in midi builds).
src/serial.rs	Implements TcpSerialSink and adds a unit test for basic round-trip behavior.
src/lib.rs	Exposes the new a4091 module.
src/emulator.rs	Wires SerialMode::Tcp and adds A4091 board creation/config validation at runtime.
src/cpu.rs	Constructs DeviceHost with slot awareness for Zorro device accesses.
src/config.rs	Adds [a4091] config parsing and introduces SerialMode::Tcp + [serial] listen.
src/bus.rs	Passes slot-aware DeviceHost into per-device ticking.
src/a4091.rs	New A4091 implementation: ROM nibble serving, 53C710 register/FIFO/IRQ behavior, minimal SCRIPTS engine, and unit tests.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.