revice

Reusable, independently tested cores for the custom features carried by the asid-vice fork of the VICE Commodore emulator.

The fork adds five features directly inside VICE's source tree. That makes them expensive to maintain: every time upstream VICE advances they have to be hand-reconciled against a moving codebase, and the feature logic has no tests of its own — it can only be exercised by building the whole emulator.

revice moves the logic out into small, pure C libraries with no dependency on VICE. Everything that touches the emulator is injected through a host-ops struct, so the fiddly, version-stable parts — the ASID MIDI wire format, the SCREEN_GET byte layout, the keymatrix tables / parsing / observation state machine, the binmon request decoders — are unit-tested here in CI with no VICE build required. VICE then consumes revice as a git submodule and each feature shrinks to a thin adapter plus a few unchanged wiring lines.

Each libs/<name> has:

• include/revice_<name>.h — the core API and host-ops vtable,
• src/<name>_core.c — pure C, no VICE headers (only <stdint.h> etc.),
• vice/… — the thin VICE adapter(s), compiled only inside a VICE tree,
• tests/test_<name>.c — assert-based unit tests run by CTest.

cmake -S . -B build
cmake --build build
ctest --test-dir build --output-on-failure

No dependencies beyond a C99 compiler and CMake ≥ 3.13. The vice/ adapters are not built here (they need VICE headers); they are compiled inside a VICE tree — see integration/vice/.

revice is added to a VICE tree as a submodule at src/revice; the cores + adapters are compiled directly from the submodule by the existing per-directory automake libraries, and the genuine VICE edits are a small set of patches. integration/vice/README.md has the full model, the wiring patches (integration/vice/patches/), an apply-wiring.sh helper, and a binmon smoke_test.py.

# inside a VICE tree:
git submodule add https://github.com/anarkiwi/revice src/revice
src/revice/integration/vice/apply-wiring.sh
./autogen.sh && ./configure --with-alsa && make -j

.github/workflows/ci.yml runs two jobs:

• unit — builds and runs the core unit tests (fast, no VICE).
• integration-build — checks out the asid-vice fork, wires revice in, and builds the affected VICE libraries (libmonitor, libc64sc, libsounddrv), asserting the revice objects archived in; then best-effort builds headless x64sc and runs the binmon smoke test.

This is the canonical reference for the wire formats and commands the cores here implement and test. For how to build/run the emulator with these features, see the asid-vice fork's README.md.

Enable with -sounddev asid; pick the MIDI port with -soundarg. The list of ports is printed to vice.log when the driver starts. The argument is a bitfield:

vsid -sounddev asid -soundarg 1 tune.sid          # port 1, standard form
vsid -sounddev asid -soundarg 1025 tune.sid       # port 1, short register form
vsid -sound -soundoutput 2 -sidextra 1 -sounddev asid -soundarg 1 2sid.sid   # 2SID

The codec tracks each SID's registers and, per IRQ, emits only the changed ones; control registers (4/11/18) are transmitted last so a voice's freq/PW/ADSR are applied before its gate edge (both the standard and short forms). Timing is scheduled against the machine's actual CPU clock (PAL / NTSC / Drean). C64 (and 2SID via Vessel/VAP) only.

Both commands work in the interactive text monitor (debugging) and as binary-monitor opcodes (automation). C64 only.

Injects key state into the CIA1 keyboard matrix, so programs that scan the matrix directly (games, demos, loaders) see it. tap releases on the first observed CIA1 read of an injected bit, or a frame timeout.

keymatrix tap     <key> [<key> ...] [for <frames>]   # release on observation / timeout
keymatrix press   <key> [<key> ...]                  # sticky chord
keymatrix release [<key> [<key> ...]]                # clear listed keys, or all
keymatrix poke    <row> <col> <0|1>                  # raw matrix bit
keymatrix show                                       # live matrix + last tap report
keymatrix names                                      # list recognised key names

Keys are symbolic (A, F1, LSHIFT, RUNSTOP, RESTORE, CBM, …; case-insensitive) or a raw <row>,<col> pair like 7,7.

KEYMATRIX_GET response (24 bytes, little-endian):

screenscrape (text; add raw for hex) renders the 40×25 screen; the binmon SCREEN_GET opcode returns the same state as one fixed blob.

SCREEN_GET response — header (24 bytes):

SCREEN_GET response — payload (4048 bytes, from body offset 24):

Attach/detach a disk image at runtime — a primitive RESOURCE_SET cannot express (it rejects zero-length values and the disk slot is not a resource). A same-path re-attach also forces a flush of pending writes.

path_len == 0 ⇒ detach; otherwise attach the (not NUL-terminated) path.

Start or stop native VICE video recording of the emulated screen to a host-side file, using the in-tree ZMBV gfxoutput driver (lossless ZMBV inside an AVI container; depends only on zlib, no external ffmpeg). The standard binmon protocol has no way to drive VICE's screenshot/movie recorder, and this headless build's text-monitor screenshot command only exposes still images.

action == 1 starts recording to the (not NUL-terminated) path — which should end in .avi; action == 0 finalizes/closes the file. Recording is driven per emulated frame out of the vsync hook, and screenshot_save_core() skips encoding while warp mode is active, so starting forces warp OFF and stopping restores the prior warp state — letting a warp-booted harness record a normal-speed clip and then resume warping. Starting while already recording, or a recorder that refuses to start, is reported as a command failure.

A per-checkpoint silent flag set via an optional byte appended to the binmon CHECKPOINT_SET (0x12) body:

When set, a hit increments hit_count but skips the per-hit CHECKPOINT_INFO event, trace print, disassembly, and command — so ~45K stop-when-hit=false watchpoints under warp playback don't drown the binmon pipeline in events.

Request:

Response (solicited or unsolicited event):

Error codes: 0x00 OK, 0x80 invalid length, 0x81 invalid parameter, 0x82 invalid API version, 0x8f command failure (e.g. SCREEN_GET on a non-C64 build). Unsolicited events: 0x61 JAM, 0x62 STOPPED, 0x63 RESUMED. Send EXIT (0xaa) once after connecting to resume the CPU (binmon halts it on connect).

GPL-2.0-or-later, matching VICE. See LICENSE.