Files
CoCo3_Plus_MiSTer/verilator
Alan SterembergandClaude Opus 5.5 9e70212e87 Sim: follow the 20260927 release
- sim.v: the coco3fpga ports changed (RED_O/GREEN_O/BLUE_O, PROBE_O/PROBE_I,
  Display_Debug) and so did the switch word (rs_swap, UART_INPUT, and the cart
  interrupt option on SWITCH[9]); mirror CoCo3.sv. SNAC inputs idle high.
- rtl/ovo.v: Verilog translation of the new rtl/OVO.vhd overlay; the
  Makefile drops the removed Mister_Video_GIMEX.v.
- PIX_CLK is now a clk_sys enable, high 2 of every 4 cycles, fed to the
  mixer's ce_pix. Capture video as video_mixer.sv does: on a clk_sys rising
  edge, one pixel per rising edge of the enable.
- New reference screenshots: the release's video timing moves the picture
  about 2 pixels; text checks unchanged.
- Commit tests/dw_boot.sh, which the dw_boot* ignore pattern was hiding.

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
2026-10-02 07:29:18 -04:00
..
2026-10-02 07:29:18 -04:00
2026-10-02 07:29:18 -04:00
2026-10-02 07:29:18 -04:00
2026-10-02 07:29:18 -04:00
2026-10-02 07:29:18 -04:00
2026-10-02 07:29:18 -04:00
2026-10-02 07:29:18 -04:00
2026-10-02 07:29:18 -04:00

CoCo3 Verilator simulation

Runs the core on the host, windowed (ImGui + SDL2) or headless, so you can boot it, type at it, mount disks, screenshot it and trace the 6809, without a DE10-Nano or a Quartus build.

It uses the same framework as the FM-7 and Apple-IIgs sims: sim.v stands in for CoCo3.sv, sim/ is the shared ImGui/SDL harness (sim_bus, sim_video, sim_input, sim_blkdevice, ...), and one binary does both modes.

Build and run

cd verilator
make                 # -> ./obj_dir/Vemu
make run             # windowed
make headless        # boot headless to frame 150, screenshot
make test            # headless smoke tests (run_tests.sh)
make lint            # elaborate only

Needs Verilator 5 (built and tested with 5.044), SDL2, and Python 3 for the generators (brew install verilator sdl2). Run the binary from this directory: the ROM defaults and the $readmemh images under rtl/ are relative paths.

ROMs

The core loads its ROMs over ioctl at start-up, the way Main_MiSTer does, so the sim needs the same two files the MiSTer SD card has in games/CoCo3/:

file contents ioctl index
roms/boot0.rom CoCo 3 ROM (32K, coco3.rom) 0
roms/boot1.rom Disk BASIC 1.1 (8K, disk11.rom) 64

They are not in git (roms/*.rom is ignored). Copy them from your MiSTer, or from ToolShed's cocoroms/ build. --rom / --disk-rom point elsewhere.

Headless

# Boot and print the text screen
./obj_dir/Vemu --headless --stop-at-frame 150 --ascii-end

# Type at BASIC; {RETURN} or \n for Enter, {BREAK}, {CLEAR}, {UP}...
./obj_dir/Vemu --headless --stop-at-frame 260 --type '140:PRINT 2+2\n' --ascii-end

# Floppy in drive 0 (selects MPI slot 4), load and run a program
./obj_dir/Vemu --headless --disk tests/hello.dsk --stop-at-frame 420 \
    --type '140:RUN"HELLO\n' --screenshot 420

# Disassembly trace of frames 10-11
./obj_dir/Vemu --headless --stop-at-frame 11 --trace-cpu trace.txt --trace-from 10

--help lists everything: cartridge (--cart), cassette (--cas), CoCoSDC (--sdc), memory size, turbo speed, artifact mode, --frame-log (per-frame framebuffer hash + instruction count), --trace-bus, --vcd.

BASIC's banner appears around frame 130. Most of that is the core itself: coco3fpga.sv holds RESET_N for 143 ms and CPU_RESET for 286 ms after power-on, and the first frame only appears once the video timing leaves reset. Type from frame 140 on.

--ascii prints the 32×16 VDG screen at $0400 as the CPU last wrote it (from a shadow of the CPU bus). That is what the tests judge. It does not follow WIDTH 40/80 or graphics modes; use a screenshot for those.

Typed keys are held 2 frames with a 2-frame gap, plus 30 frames after each RETURN (--key-hold, --key-gap, --return-gap). The CoCo has no type-ahead: while BASIC runs a line it does not scan the keyboard, so keys pressed then are lost, on the real machine as well as here.

Tests

./run_tests.sh [name...] runs these in parallel (about 8 minutes in all):

test does judged on
boot power on, wait for the banner text screen: DISK EXTENDED COLOR BASIC 2.1, OK
keyboard PRINT 2+2 text screen: 4
disk RUN"HELLO from tests/hello.dsk text screen: HELLO FROM DISK, 42
width80 WIDTH 80, then print screenshot (GIME 80-column text)
hscreen HSCREEN 2, HCIRCLE, HLINE ... B screenshot (GIME 320x192 graphics)

Every test's final screenshot is compared byte for byte with test-ref/. The sim is deterministic, so a changed image means the RTL or harness changed what is drawn. After an intended change, BLESS=1 ./run_tests.sh records new references. Output goes to test-out/.

Speed

About 1.2 simulated frames per second (boot to BASIC ~125 s on an Apple-silicon Mac), or ~1.6 fps with --fast-clocks (~77 s).

Where the time goes, and the two speed-ups made:

  • The CoCo clocks are 114.5 MHz (SDRAM controller, the data_ready latch, the video line fetcher), 57.3 MHz clk_sys (everything else: 48 negedge and 10 posedge blocks), 14.3 MHz pixel clock, and CLK_50M for the RTC/UART. CLK_28 is unused.
  • status (the OSD word) used to be a top-level input. It feeds the video pixel mux, so Verilator re-evaluated that mux on every eval, about 20% of the run time. sim.v now registers it, as hps_io does on the FPGA.
  • --fast-clocks steps per half-period of clk_sys and runs the 114 MHz domain at 57 MHz, halving the evals. At normal CPU speeds an SDRAM access still finishes well inside a CPU cycle. All five tests give byte-identical screenshots and identical instruction counts either way (SIMARGS=--fast-clocks ./run_tests.sh). High turbo speeds (6 clk_sys per CPU cycle at 9.54 MHz) and video fetch bandwidth are where it could differ; use the default when timing is the question.

Serial (RS-232 Pak / FujiNet)

The core's only UART is the RS-232 Pak, a glb6551 at $FF68-$FF6B; on MiSTer its pins are the UART_* signals the FujiNet daemon reaches as /dev/ttyS1. The sim works on those pins, not on the registers:

  • TXD is decoded at whatever rate the 6551 is programmed for, and every byte is printed: SERIAL TX <frame> <hex> |ascii|.
  • RXD is driven from a pty (--serial-pty, name printed at start) or from --serial-send FRAME:HEX..., at the far end's rate: --serial-baud N, or by default the 6551's transmit rate.
  • --trace-acia logs every CPU access to $FF68-$FF6B, and whether it actually reached the chip. The exit summary counts bytes, accesses and undecoded accesses, and warns on a receive-clock mismatch.
  • The windowed build has a Serial window with the same information.
  • tests/dwserver.py PTY DISK... is a minimal DriveWire 3 server (stdlib only) to stand in for FujiNet: READEX, WRITE, TIME, DWINIT, ...

tests/dw_boot.sh CART DISK STOP [sim args] wires the two together:

tests/dw_boot.sh ../../FujiNet_MiSTer/roms/HDBDW3S3.CCC tests/hello.dsk 350 \
    --type '140:RUN"HELLO\n'

That boots HDB-DOS over DriveWire (reads LSN 0 and the directory), then RUN"HELLO loads and runs the program from the served image, about 5 minutes.

The sim runs ~50x slower than real time, so the far end sees roughly 400 baud of real throughput whatever rate is programmed. A real FujiNet may time out where dwserver.py does not.

FujiNet on this core: what was wrong, and the fix

Tested with FujiNet_MiSTer's carts and the real FujiNet daemon (FujiNet-PC built for COCO, run with FujiNet_MiSTer's fnconfig.ini pointed at the sim's pty; tests/fujinet_boot.sh).

  1. The 6551 was unreachable with a cart in slot 3. coco3fpga.sv decoded $FF68-$FF6B only when the Multi-Pak I/O select was slot 1 (MPI_SCS == 0), and the OSD offers only slots 2-4. HDB-DOS programmed the chip and polled status forever. It read $AA from an empty bus, stopped at HDB-DOS 1.5 SY6551 COCO 3, and transmitted nothing. On a real CoCo the SCS line covers only $FF40-$FF5F, and the RS-232 Pak decodes $FF68 from the address bus, so it works in any slot. Fix: RS232_EN no longer looks at MPI_SCS. (Upstream's 20260927 release moved the decode to slots 2 and 4, MPI_SCS[0] == 1; HDB-DOS carts can only boot from slot 3, so that still missed every access.)

  2. The 19,200 cart received at 115,200. HDBDW3L3_19200.CCC writes control $0F. Bit 4 = 0 selects the "external" receive clock, which uart_6551.v tied to the 1.8475 MHz enable, i.e. 115,200 baud. The cart transmitted at 19,200 and received garbage: FujiNet logged Checksum error: expected 65280, got 57344. Fix: the receiver is clocked from the baud generator (RX_CLK = TX_CLK). That is unchanged for control $1x and for baud select 0.

  3. Slot 3 hung FujiNet's CONFIG loader. Once a cart finished downloading after boot, slot 3 toggled the CART interrupt every CPU cycle, forever. That is right for a program pak (CART tied to Q autostarts it), but a disk-style ROM such as HDB-DOS never drives CART. FujiNet's CFGLOAD.BIN re-enables that interrupt and then hung in an endless FIRQ, after reading 17 sectors. A reset cleared it, which is why "load cart, then Reset" worked. The OSD's "Cart Interrupt Disabled" option was not connected to anything. Fix: a cart that starts with DK gets a cold boot instead, the way BASIC starts it at power-on, and the OSD option (Debug menu, status[19] -> SWITCH[9]) now suppresses the autostart interrupt. Program paks behave as before. The sim reproduces both cases with --cart-frame N, which loads the cart after boot the way the OSD and MGL do.

With these fixes, the L3 cart at 19,200 (the MiSTer configuration) boots from the real FujiNet daemon with no checksum errors, and gets to FujiNet's CONFIG splash. The S3 cart (115,200) reaches the CONFIG host-slots screen.

On the FPGA the rest of the path already works. sys_top.v wires the core's UART_* pins straight to the HPS UART (/dev/ttyS1), whatever the OSD UART mode. The 6551 only transmits while CTS is low, and CTS is the HPS UART's RTS. FujiNet-PC turns off CRTSCTS and leaves RTS as Linux sets it on open (asserted), so that holds while start_fujinet.sh has the port open.

Sim-only caveat: FujiNet times out reads after 500 ms of wall-clock time, and the sim runs ~50x slower than real time. The CoCo cannot return a sector's checksum in time, and FujiNet logs got 65535. These tests used a FujiNet build with .readTimeout(120000) in lib/bus/drivewire/drivewire.cpp. On hardware the stock value is fine.

Windowed

make run. Windows: the video, a CPU/GIME inspector (registers, $FF90, a live disassembly from the bus shadow), Control (run/pause/step, reset, cold boot, screenshot, the OSD options, cart/cassette/floppy/SDC file dialogs) and a console. Keys go to the CoCo from the host keyboard through the same PS/2 path as on hardware.

What is simulated, and what is replaced

sim.v wires the core the way CoCo3.sv does, including the OSD status word decode, the joystick centring and the cassette RAM. The replacements:

on MiSTer here why
PLL (114.545/57.27/28.64/14.32 MHz) clocks from sim_main.cpp all phase 0, exact /2 /4 /8, so they are derived from one counter and all rise in the same eval
rtl/sdram/sdram2.sv rtl/sdram2.sv same controller logic, plus a CAS-3, burst-2 SDR chip model in place of the SDRAM_* pins
hps_io keyboard sys/hps_io.sv's own ps2_device ps2_key events are fed into the real PS/2 serializer at PS2DIV(2400), so cocokey.v sees the same serial stream
rtl/VDAC.v (altsyncram) rtl/VDAC.v registered dual-port RAM, preloaded from VDAC.mif
VHDL ROM/RAM entities rtl/coco_rom.v, rtl/coco_sram.v Verilog conversions, see below

VHDL to Verilog

The build uses the Verilog cycle-accurate 6809 (rtl/mc6809glb/mc6809glb.v), because rtl/config.sv defines CoCo3_CYC_ACC_6809. The VHDL CPU (rtl/CPU09/cpu09*.vhd) is not instantiated, so nothing needs ghdl. The VHDL the core does use was converted by hand, one module per entity with the same names and ports:

VHDL Verilog
rtl/rom/coco_rom_32K.vhd, coco_rom_8K.vhd, coco_rom_cart.vhd rtl/coco_rom.v (COCO_ROM_32K, COCO_ROM_8K, COCO_ROM_CART)
rtl/rom/coco_rom_16.vhd rtl/coco_rom.v (COCO_ROM_16)
rtl/rom/coco3_char_rom.vhd rtl/coco_rom.v (coco3_Char_ROM) + rtl/coco3_char_rom.mem
rtl/sram/coco_ram.vhd, coco_vid_ram_buf.vhd rtl/coco_sram.v (COCO_SRAM, COCO_VID_RAM_BUF)
rtl/OVO.vhd (debug / "NO ROM" overlay) rtl/ovo.v (ovo)

make mem (gen_mem.py) regenerates rtl/coco3_char_rom.mem from the font table in the VHDL and rtl/vdac.mem from rtl/VDAC.mif.

Traps found while bringing it up

Verilator re-runs block-local initialisers. A variable declared with an initialiser inside an always block, like reg [4:0] state = STATE_STARTUP; in sdram2.sv, is re-initialised every time the block runs under Verilator 5.044. It is not a one-time static. The SDRAM controller was pinned in STATE_STARTUP, and the CPU stalled on its first RAM access. The sim copy hoists those registers to module scope. Look for this in any other core (make lint flags them as IMPLICITSTATIC).

Quartus powers async-set registers up at 1. A register with an asynchronous set is built with NOT-gate push-back, so it starts at 1 on the FPGA and at 0 here. mc6809x's NMILatched (active low) is one of them. At 0 the CPU took a phantom NMI on its first instruction. sim.v sets it to 1 in an initial block, which models the FPGA's power-up state.

// verilator ... in a comment is a pragma. A comment line that starts with the word "verilator" is parsed as a directive and fails the build with BADVLTPRAGMA.

rtl/wd1793.sv: spt_addr and buff_wr were declared inside generate blocks but assigned outside them. Quartus accepts that. Verilator rejects spt_addr, and silently makes buff_wr a separate implicit net, so the sector-buffer write strobe would never reach the RAM. Both are now declared at module scope. FM-7 made the same fix to its copy of the file. There is no behavioural change on the FPGA.

The core also declares some registers as wire and assigns them in always blocks (Build_Info, VMA, PIX_CLK_D, the $FF40 latch in fdc.sv). Quartus accepts it. The Makefile passes -Wno-PROCASSWIRE rather than editing the RTL.

Files

Makefile            build, lint, test
sim.v               emu top: CoCo3.sv without sys/, plus debug taps
sim_main.cpp        clocks, options, headless loop, ImGui windows
serial.{cpp,h}      6551 line model: TXD decoder, RXD driver, pty bridge
sim.vlt             Verilator config (forceable net for --acia-any-slot)
dis6809.{cpp,h}     6809 disassembler (shared with FM-7)
run_tests.sh        smoke tests, judged on text screen + screenshot
gen_mem.py          VHDL/MIF -> rtl/*.mem
rtl/                Verilog conversions and sim replacements
sim/                shared ImGui/SDL framework
tests/              make_test_disk.py -> hello.dsk (Disk BASIC image),
                    dwserver.py (minimal DriveWire 3 server)
test-ref/           blessed screenshots for run_tests.sh