{"id":23802902,"url":"https://github.com/binaryfields/zinc64","last_synced_at":"2025-07-28T02:05:34.947Z","repository":{"id":57672882,"uuid":"77186402","full_name":"binaryfields/zinc64","owner":"binaryfields","description":"Commodore 64 emulator toolkit with batteries included but swappable. Baremetal emulation on RPI3.","archived":false,"fork":false,"pushed_at":"2024-01-20T01:33:12.000Z","size":1736,"stargazers_count":24,"open_issues_count":1,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-07-27T04:08:56.849Z","etag":null,"topics":["bare-metal","c64","commodore","emulator","rpi","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/binaryfields.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2016-12-23T00:59:29.000Z","updated_at":"2024-12-18T09:58:42.000Z","dependencies_parsed_at":"2024-01-07T18:54:14.941Z","dependency_job_id":null,"html_url":"https://github.com/binaryfields/zinc64","commit_stats":null,"previous_names":["digitalstreamio/zinc64"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/binaryfields/zinc64","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binaryfields%2Fzinc64","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binaryfields%2Fzinc64/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binaryfields%2Fzinc64/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binaryfields%2Fzinc64/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/binaryfields","download_url":"https://codeload.github.com/binaryfields/zinc64/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binaryfields%2Fzinc64/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267451489,"owners_count":24089312,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-28T02:00:09.689Z","response_time":68,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bare-metal","c64","commodore","emulator","rpi","rust"],"created_at":"2025-01-01T22:28:24.734Z","updated_at":"2025-07-28T02:05:34.920Z","avatar_url":"https://github.com/binaryfields.png","language":"Rust","readme":"# Zinc64\n\n[![Build Status](https://travis-ci.org/digitalstreamio/zinc64.svg?branch=master)](https://travis-ci.org/digitalstreamio/zinc64)\n[![Crates.io](https://img.shields.io/crates/v/zinc64.svg?maxAge=2592000)](https://crates.io/crates/zinc64)\n\n## Overview\n\nzinc64 is a Commodore 64 emulator toolkit \"with batteries included but\nswappable\". It is designed to be used as a standalone emulator or a library\nused to build new emulators. The design philosophy allows for each component\nto be swapped out and replaced by different implementation. Therefore,\nspecial considerations were made to model interactions between chips\nwithout coupling them together.\n\nIt implements MOS 6510 CPU, MOS 6526 CIA, MOS 6581 SID,\nMOS 6567/6569 VIC chipset as well as various devices and peripherals available\nwith C64.\n\n### Story\n\nzinc64 was started as an exercise to learn Rust and explore Commodore 64\nhardware in more detail. Somewhere around mid 2016 I needed to feed my 8-bit\nnostalgia so I picked up a working Commodore 64 (physical version) and started\nto assemble various accessories required to get software onto it. Soon enough I\nhad picked up a copy of C64 Programmer's Reference Guide and the rest is now\nhistory.\n\n2020 is bringing support for revised OpenGL port with console support and\nbare-metal environments, more specifically a bare-metal Raspberry Pi 3 port.\nSee zinc64-rpi for an early preview.\n\n## Design\n\n### Feature `std`\n\nzinc64-system crate works without the standard library, such as in bare-metal environments. To use zinc64-system in a #[no_std] environment, use: \n\n```toml\n[dependencies]\nzinc64-system = { version = \"0.9.0\", default-features = false }\n```\n\n### Extensibility\n\nThe emulator components may be swapped out by providing custom core::ChipFactory trait\nimplementation. The default implementation of the core::ChipFactory trait is done through\nsystem::C64Factory. The chip factory object is passed into system::C64 component\nthat provides core emulator functionality.\n\nHere is an example how these components are used together:\n\n        let config = Rc::new(Config::new(SystemModel::from(\"pal\")));\n        let chip_factory = Box::new(C64Factory::new(config.clone()));\n        let mut c64 = C64::new(config.clone(), chip_factory).unwrap();\n        c64.reset(true);\n\nThe four core traits used to model system operation are Chip, Cpu, Mmu and Addressable.\n\n    /// A chip represents a system component that is driven by clock signal.\n    pub trait Chip {\n        /// The core method of the chip, emulates one clock cycle of the chip.\n        fn clock(\u0026mut self);\n        /// Process delta cycles at once.\n        fn clock_delta(\u0026mut self, delta: u32);\n        /// Handle vsync event.\n        fn process_vsync(\u0026mut self);\n        /// Handle reset signal.\n        fn reset(\u0026mut self);\n        // I/O\n        /// Read value from the specified register.\n        fn read(\u0026mut self, reg: u8) -\u003e u8;\n        /// Write value to the specified register.\n        fn write(\u0026mut self, reg: u8, value: u8);\n    }\n\n    /// CPU is responsible for decoding and executing instructions.\n    pub trait Cpu {\n        ...\n        /// The core method of the cpu, decodes and executes one instruction. Tick callback is invoked\n        /// for each elapsed clock cycle.\n        fn step(\u0026mut self, tick_fn: \u0026TickFn);\n        // I/O\n        /// Read byte from the specified address.\n        fn read(\u0026self, address: u16) -\u003e u8;\n        /// Write byte to the specified address.\n        fn write(\u0026mut self, address: u16, value: u8);\n    }\n\n    /// Represents memory management unit which controls visible memory banks\n    /// and is used by CPU to read from and write to memory locations.\n    pub trait Mmu {\n        /// Change bank configuration based on the specified mode.\n        fn switch_banks(\u0026mut self, mode: u8);\n        // I/O\n        /// Read byte from the specified address.\n        fn read(\u0026self, address: u16) -\u003e u8;\n        /// Write byte to the specified address.\n        fn write(\u0026mut self, address: u16, value: u8);\n    }\n\n    /// Addressable represents a bank of memory.\n    pub trait Addressable {\n        /// Read byte from the specified address.\n        fn read(\u0026self, address: u16) -\u003e u8;\n        /// Write byte to the specified address.\n        fn write(\u0026mut self, address: u16, value: u8);\n    }\n\nSince all system components with the exception of Cpu and Mmu implement Chip trait,\ninteractions between chips and other components are limited to and handled through\nshared I/O lines/pins that are provided to chip constructors. This allows implementation\nof chips to be decoupled from each other.\n\n## Status\n\n| Class    | Component     | Status      |\n|----------|---------------|-------------|\n| Chipset  | 6510 CPU      | Done\n| Chipset  | Memory        | Done\n| Chipset  | 6526 CIA      | Done\n| Chipset  | 6581 SID      | Done\n| Chipset  | 6567 VIC      | Done\n| Device   | Cartridge     | Done\n| Device   | Floppy        | Not Started\n| Device   | Datassette    | Done\n| Device   | Keyboard      | Done\n| Device   | Joystick      | Done\n| Device   | Mouse         | Not Started\n| Debugger | Remote        | Done\n| Debugger | Radare2       | Done\n| Format   | Bin           | Done\n| Format   | Crt           | Done\n| Format   | D64           | Not Started\n| Format   | P00           | Done\n| Format   | Prg           | Done\n| Format   | Tap           | Done\n| Format   | T64           | Not Started\n| Client   | OpenGl        | In Progress\n| Client   | Raspi3        | In Progress\n\n## Roadmap\n\n- v0.9   - opengl client\n- v0.10  - rpi port\n- v0.11  - floppy support\n\n## Getting Started\n\n1. Install Rust compiler or follow steps @ https://www.rust-lang.org/en-US/install.html.\n\n        curl https://sh.rustup.rs -sSf | sh\n\n2. Clone this repository.\n\n        git clone https://github.com/binaryfields/zinc64\n\n\tor download as zip archive\n\n\t\thttps://github.com/binaryfields/zinc64/archive/master.zip\n\n3. Build the emulator.\n\n        cd zinc64\n        cargo build --release --all\n\n4. Run the emulator.\n\n        ./target/release/zinc64\n\n    or start a program\n\n    \t./target/release/zinc64 --autostart path\n\n### Windows Considerations\n\n1. Install [Microsoft Visual C++ Build Tools 2017](https://www.visualstudio.com/downloads/#build-tools-for-visual-studio-2017). Select Visual C++ build tools workload.\n\n## Debugger\n\nTo start the debugger, run the emulator with '-d' or '--debug' option. Optionally, you can specify '--debugaddress'\nto bind to a specific address.\n\n        ./target/release/zinc64 --debug\n\nTo connect to the debugger, telnet to the address and port used by the debugger.\n\n        telnet localhost 9999\n\nDebugger commands and syntax are modeled after Vice emulator.  To see a list of available commands,\ntype in the debugging session:\n\n        help\n\nor to get help on a specific command:\n\n        help \u003ccommand\u003e\n\n### Radare2\n\nInitial support for radare2 has been merged in version 0.3. To start the emulator with RAP server support, run\n\n        ./target/release/zinc64 --rap 127.0.0.1:9999\n\nand connect with\n\n        radare2 -a 6502 -d rap://localhost:9999/1\n\n## Examples\n\nI've included a number of examples from Kick Assembler that I've used to test various components of the emulator. They can be found in the bin folder of this repository and started with the emulator's autostart option.\n\n        ./target/release/zinc64 --autostart bin/SineAndGraphics.prg\n\n| Program                  | Status  |\n|--------------------------|---------|\n| 6502_functional_test.bin | Pass    |\n| FloydSteinberg.prg       | Pass    | \n| KoalaShower.prg          | Pass    |\n| Message.prg              | Pass    |\n| MusicIrq.prg             | Pass    |\n| Scroll.prg               | Pass    |\n| SID_Player.prg           | Pass    |\n| SimpleSplits.prg         | Fails   |\n| SineAndGraphics.prg      | Pass    |\n\n### Tests\n\nThe cpu validation was performed with the help of [Klaus2m5 functional tests](https://github.com/Klaus2m5/6502_65C02_functional_tests) for the 6502 processor \n\n        ./target/release/zinc64 --console --loglevel trace bin/6502_functional_test.bin \n\n## Keyboard Shortcuts\n\n| Shortcut  | Function          |\n|-----------|-------------------|\n| Escape    | Console\n| Alt-Enter | Toggle Full Screen\n| Alt-F9    | Reset\n| Alt-H     | Activate Debugger\n| Alt-M     | Toggle Mute\n| Alt-P     | Toggle Pause\n| Alt-Q     | Quit\n| Alt-W     | Warp Mode\n| Ctrl-F1   | Tape Play/Stop\n| NumPad-2  | Joystick Bottom\n| NumPad-4  | Joystick Left\n| NumPad-5  | Joystick Fire\n| NumPad-6  | Joystick Right\n| NumPad-8  | Joystick Top\n\n## Credits\n\n- Commodore folks for building an iconic 8-bit machine\n- Rust developers for providing an incredible language to develop in\n- Thanks to Rafal Wiosna for passing onto me some of his passion for 8-bit machines ;)\n- Thanks to Klaus Dormann for his 6502_65C02_functional_tests, without which I would be lost\n- Thanks to Dag Lem for his reSID implementation\n- Thanks to Christian Bauer for his wonderful \"The MOS 6567/6569 video controller (VIC-II) and its application in the Commodore 64\" paper\n- Thanks to Peter Schepers for his \"Introduction to the various Emulator File Formats\"\n- Thanks to c64-wiki.com for my to go reference on various hardware components\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbinaryfields%2Fzinc64","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbinaryfields%2Fzinc64","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbinaryfields%2Fzinc64/lists"}