A4091 Zorro III SCSI controller: 53C710 model, SCRIPTS phase engine, drives scan and mount

[codewiz]

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

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).
• SCSI pin loopback / bus reset: in loopback (CTEST4.SLBE) with the data bus asserted (SCNTL1.ADB), SODL mirrors onto SBDL and SOCL onto SBCL, with ACK/REQ gated on target mode (SCNTL0.TRG); SSTAT1.PAR reports generated data parity and SSTAT1.RST reflects a SCNTL1.RST bus-reset request.
• SCRIPTS phase engine: the full driver I/O script (the NetBSD siop 53c710 script). SELECT with table-indirect target lookup (one-hot ID in the ds_Device entry), table-indirect block moves through the SCSI phases, conditional JUMP/CALL/RETURN/INT (SCSI-phase and SFBR data compares, relative addressing), the SET/CLEAR handshake ops, WAIT DISCONNECT, plus the self-test's MOVE-immediate-to-register and Memory Move (including moves targeting the board's own register window, via DeviceHost::for_slot). COPPERLINE_DIAG_A4091=1 logs fetches, moves and the live phase.
• Target layer bridge: a per-nexus state machine sequences MSG_OUT (IDENTIFY) -> COMMAND -> DATA_IN/OUT -> STATUS -> MSG_IN (command complete) -> disconnect, handing each CDB to the existing scsi.rs ScsiDisk. Sync-transfer negotiation is declined with MESSAGE REJECT (async only); an empty SCSI ID raises a selection timeout (SSTAT0.STO) so the driver's bus probe moves on. [a4091] unit0..6 images are attached as bus targets.

How it was tested

• The a4091 unit tests: ROM nibble encoding, register file and +$40 shadows, CTEST5 strobes, both FIFOs, interrupts/INT2, the SCRIPTS self-test instructions (including the self-window Memory Move), and the SCSI pin loopback walk.
• ncr7xx validation tool from a4091-software, run on the emulated machine over the serial console: full suite now 9/9 PASS -- Device access, Register test, DMA FIFO, SCSI FIFO, Bus access, DMA, DMA copy, DMA copy perf (~483 MB/s), and the SCSI pin test.
• Drives scan and mount: HD10/HD20 hardfiles attached to the A4091 are detected in the a4091.device boot menu, their RDB partitions mount, and their FFS filesystems read correctly.
• devtest (a4091-software) non-destructive suite on a mounted unit: -p bus probe (both targets), -g geometry, -b benchmark (~550 MB/s reads), -o open/close, and -t packet types -- CMD_READ, ETD_READ, TD_READ64 and the NSD 64-bit reads/seeks all pass.

Notes / still to come

• Rebased onto current main now that serial: bidirectional TCP sink (mode = "tcp") #121 (serial TCP sink) has merged; that's how it was tested (an AUX: shell over TCP gives a scriptable remote console).
• The write / DATA_OUT path is implemented but only lightly exercised so far (no destructive devtest run yet).
• READ CAPACITY (16) is not modelled by ScsiDisk (returns a sense error; the driver falls back to the 10-byte form, which works).
• Timing: SCRIPTS run synchronously inside the triggering register write; no bus arbitration is modelled (same simplification as the A2091's DMA), and the target completes each command without disconnect/reselect.

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 survives 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.

[codewiz]

This patch series can scan my 2 HDF images, boot the partitions and boot my system.

Still missing: config UI. Do we want it?

[LinuxJedi]

This patch series can scan my 2 HDF images, boot the partitions and boot my system.

Still missing: config UI. Do we want it?

At some point, even if it isn't this PR.

[LinuxJedi]

A great addition, many thanks!