Crate ull65 

A no_std emulator library for MOS 6502 and WDC 65C02 microprocessors.

ull65 provides a flexible, trait-based architecture for emulating 6502-family CPUs. The library is designed for extensibility, allowing custom memory implementations, instruction sets, and addressing modes.

Architecture

The emulator is built around three core abstractions:

• Bus: Memory and I/O abstraction. Implement this trait to provide custom memory-mapped hardware, banking, or I/O devices.
• instruction::InstructionSet: Defines the instruction table for a CPU variant (e.g., MOS 6502, WDC 65C02, or custom extensions).
• Cpu: The CPU core that executes instruction using a specified bus and instruction set.

Quick Start

use ull65::{Byte, Cpu, Word, bus::SimpleBus, instruction::mos6502::Mos6502};

let mut bus = SimpleBus::default();
let program = [0xA9, 0x42, 0x00]; // LDA #$42; BRK
let mut cpu: Cpu<SimpleBus> =
    Cpu::with_program::<Mos6502>(&mut bus, Word(0x8000), &program, Word(0x8000));

let cycles = cpu.tick(&mut bus);
assert!(cycles > 0);
assert_eq!(cpu.a, Byte(0x42));

Type-Safe Primitives

The library uses newtype wrappers (Byte, Word) for type safety and to provide convenient operator overloads with wrapping arithmetic, matching 6502 behavior.

Examples

• See hello_world for the quickest possible demo using Cpu::run_until.
• See custom_instruction_set for how to extend or patch the instruction table.
• See custom_bus for implementing memory-mapped I/O.

For a broader architectural overview and onboarding guide, read crates/ull65/README.md.

Re-exports

pub use byte::Byte;

pub use word::Word;

pub use bus::AccessType;

pub use bus::Bus;

pub use bus::DmaRequest;

pub use bus::DmaResult;

pub use nibble::Nibble;

pub use processor::addressing_mode;

pub use processor::addressing_mode::AddressingMode;

pub use processor::run::RunConfig;

pub use processor::run::RunOutcome;

pub use processor::run::RunPredicate;

pub use processor::run::RunSummary;

pub use processor::Cpu;

pub use processor::RunState;

pub use processor::cpu::IRQ_VECTOR_HI;

pub use processor::cpu::IRQ_VECTOR_LO;

pub use processor::cpu::NMI_VECTOR_HI;

pub use processor::cpu::NMI_VECTOR_LO;

pub use processor::cpu::RESET_VECTOR_HI;

pub use processor::cpu::RESET_VECTOR_LO;

pub use processor::cpu::STACK_SPACE_START;

Modules

bus

Memory and I/O bus abstraction.

byte

Type-safe 8-bit value with automatic wrapping arithmetic.

instruction

Instruction sets and dispatch tables.

nibble

4-bit nibble type for internal BCD arithmetic.

processor

CPU core, status flags, and addressing modes.

word

Type-safe 16-bit value for addresses with wrapping arithmetic.

Macros

byte

nibble

word

Convenience macro for creating Word values.