MOS-Hardware

This crate contains hardware register tables and support functions for 8-bit retro computers like the Commodore 64, Commander X16, MEGA65 and others. Please check the examples directory to see how Rust can be used to generate simple demo effects.

Aims

• Excellent support for Rust programming on CBM (inspired) 8-bit computers
• Labelled registers for expressive hardware programming
• Intuitive bitflags with type checks where possible
• Minimum resource impact

Examples

Read and write to labelled hardware registers

use mos_hardware::{c64, vic2};
let old_border_color = c64::vic2().border_color.read();
unsafe {
    c64::vic2().border_color.write(vic2::LIGHT_RED);
    c64::sid().potentiometer_x.write(3); // compile error: read-only register
}

Use bitflags to safely control hardware

...for example where the VIC-II chip accesses screen memory and character sets:

use mos_hardware::{c64, vic2};
let bank = vic2::ScreenBank::AT_2C00.bits() | vic2::CharsetBank::AT_2000.bits();
unsafe {
    c64::vic2().screen_and_charset_bank.write(bank);
}

Convenience functions to perform hardware-specific tasks

...for example to generate random numbers using noise from the C64's SID chip:

use mos_hardware::c64::*;
clear_screen();
sid().start_random_generator();
let value = sid().random_byte();

Getting started

The project requires rust-mos and is setup to build for C64 by default. A docker image of rust-mos is available if you do not fancy compiling LLVM. If you want to start a new project which uses mos-hardware, there's a Github Template.

Docker and Visual Studio Code

The easiest way is to use the provided .devcontainer.json configuration for vscode by clicking the Dev Containers Open badge above, assuming you have VSC and Docker installed. You can also do this manually:

1. Configure Visual Studio Code with the Remote - Containers extension
2. Start Docker
3. Open the project inside devcontainer when asked
4. In the vscode terminal do:

   # if Docker uses qemu (i.e. on apple silicon)
   export CARGO_NET_GIT_FETCH_WITH_CLI=true
   
   # build for the MEGA65:
   cargo build --target mos-mega65-none
   

Status

The hardware registers are currently incomplete and the library may be subject to significant changes.

• Commodore 64:
  • sid
  • vic2
  • cia (partially)
  • c64 memory map (particlly)
  • PSID file support for SID music
  • Random number trait (RngCore)
• Commander X16
  • vera
  • via (partially)
  • cx16 Memory map (partially)
  • Support functions
• MEGA65:
  • partial support for vic3, vic4 and other hardware registers.
  • mega65-libc bindings
  • Random number traits (RngCore, SeedableRng)
  • Iterator to 28-bit address space
• Examples:
  • Plasma effect (c64, mega65)
  • Raster IRQ (c64)
  • Sprites (c64)
  • Smooth x-scrooll (c64)
  • Joystick read (c64)
  • 10print maze (c64)
  • Memory iteration and fat pointers (mega65)