ROM Setup

ROM Handling

Starting fresh? USER-GUIDE.md is the higher-level entry point: install, first run, CLI launcher, and machine YAML topologies. This file is the deep reference for ROM sourcing and layout.

Overview

ViceSharp requires Commodore ROM images to boot emulated machines. ROMs are copyrighted by Commodore/Tulip and are NOT included in the ViceSharp distribution.

Legal ROM Options

1. VICE ROM Distribution

The VICE project distributes ROM images with its binary packages. If you have VICE installed, point ViceSharp at the VICE data root that contains C64/, DRIVES/, and the other machine resource folders.

Typical VICE data-root locations:

• Windows: C:\Program Files\WinVICE-* or a Chocolatey/UniGetUI package root such as ...\GTK3VICE-3.8-win64
• Linux: /usr/share/vice or /usr/lib/vice
• macOS: /Applications/vice-*

2. Cloanto C64 Forever

C64 Forever by Cloanto provides legally licensed ROM images. The "Plus" and "Premium" editions include complete ROM sets for all Commodore machines.

3. Open-Source Alternatives

• Open ROMs - open-source KERNAL and BASIC replacements (limited compatibility)
• JiffyDOS - aftermarket replacement KERNAL (requires purchase)

4. Physical Extraction

If you own original Commodore hardware, you may legally extract ROM contents using hardware tools (e.g., EPROM reader).

Environment Variable

Set VICESHARP_ROM_PATH to point to your VICE data root. You can also use VICE_DATA_PATH or VICE_HOME, and on Windows the test/runtime resolver can derive the data root from x64sc.exe on PATH.

# Linux/macOS
export VICESHARP_ROM_PATH="/usr/share/vice"

# Windows
set VICESHARP_ROM_PATH=C:\path\to\GTK3VICE-3.8-win64

# PowerShell
$env:VICESHARP_ROM_PATH = "C:\path\to\GTK3VICE-3.8-win64"

ROM Directory Structure

ViceSharp resolves the native VICE data layout by machine/resource folder. If VICESHARP_ROM_PATH points directly at C64/, the resolver normalizes it to the parent data root.

$VICESHARP_ROM_PATH/
    C64/
        basic-901226-01.bin
        chargen-901225-01.bin
        kernal-901227-03.bin
        gtk3_pos.vkm
    DRIVES/
        dos1541-325302-01+901229-05.bin
        dos1541ii-251968-03.bin
    C128/
    VIC20/
    PET/
    PLUS4/

ROM Validation

ViceSharp validates ROM files at load time using MD5 checksums for known-good images (C64RomLoader.LoadRom in src/ViceSharp.RomFetch/C64RomLoader.cs). Validation is strict: if a file matches a known ROM name but its MD5 does not match the descriptor, the load fails (no warning, no fallback). ROM file names the loader does not recognize skip checksum validation entirely and load as-is (this is what supports modified/patched ROMs). Each descriptor also stores a SHA1 hash for reference, but only MD5 is checked at load time. SHA256 is used elsewhere: it pins RomFetch downloads (RomProvider) and the CI ROM staging in build/Build.cs (EnsureCiRomRoot).

Known C64 ROM Checksums

Copied from the descriptors in C64RomLoader.cs:

File	Size	MD5 (validated at load)	Description
kernal-901227-03.bin	8,192	39065497630802346bce17963f13c092	Standard C64 KERNAL (901227-03)
kernal-901227-02.bin	8,192	7360b296d64e18b88f6cf52289fd99a1	KERNAL rev 2 (901227-02)
kernal-901227-01.bin	8,192	1ae0ea224f2b291dafa2c20b990bb7d4	KERNAL rev 1 (901227-01)
kernal-251104-04.bin	8,192	187b8c713b51931e070872bd390b472a	SX-64 KERNAL (251104-04)
kernal-901246-01.bin	8,192	da92801e3a03b005b746a4dd0b639c7c	PET64 KERNAL (901246-01)
kernal-906145-02.bin	8,192	479553fd53346ec84054f0b1c6237397	Japanese C64 KERNAL (906145-02)
kernal-390852-01.bin	8,192	ddee89b0fed19572da5245ea68ff11b5	C64GS KERNAL (390852-01)
basic-901226-01.bin	8,192	57af4ae21d4b705c2991d98ed5c1f7b8	BASIC V2 (901226-01)
chargen-901225-01.bin	4,096	12a4202f5331d45af846af6c58fba946	Character ROM (901225-01)
chargen-906143-02.bin	4,096	cf32a93c0a693ed359a4f483ef6db53d	Japanese character ROM (906143-02)
dos1541-325302-01+901229-05.bin	16,384	n/a (no descriptor; loads unvalidated)	1541 DOS (325302-01/901229-05)

ViceSharp.RomFetch Tool

ViceSharp.RomFetch is currently a class library, not a command-line tool: the project has no executable entry point, so there is no dotnet run --project src/ViceSharp.RomFetch invocation today (the Nuke RomFetch target logs "tool not yet implemented"). A standalone CLI remains planned work.

What the library provides today:

• C64RomLoader - loads C64 ROM images into the bus with strict MD5 validation (see ROM Validation above).
• RomProvider - resolves ROM files from one or more base paths and can download known ROMs from a user-supplied URL database, verifying each download against a pinned SHA256 hash before writing it to disk.
• ViceDataPathResolver - locates the VICE data root from VICESHARP_ROM_PATH, VICE_DATA_PATH, VICE_HOME, or (on Windows) x64sc.exe on PATH, and normalizes a C64/ subdirectory to its parent root.

CI uses the same hash-pinning approach: the CiTest Nuke target stages the required ROM dumps via EnsureCiRomRoot in build/Build.cs, downloading them SHA256-pinned when they are not already present on the agent.

Fallback Behavior

When ROMs are missing or invalid:

• VICESHARP_ROM_PATH / VICE_DATA_PATH unset and no x64sc.exe found on PATH → error with setup instructions
• ROM directory exists but files missing → error listing missing files
• Known ROM name but MD5 checksum mismatch → load fails
• Unrecognized ROM file name → checksum validation skipped, loads as-is
• ROM loads and checksum matches → normal operation

ViceSharp will NOT attempt to download ROMs automatically without explicit user action via the RomFetch APIs.