What is the 6502?#

• The MOS Technology 6502 is an 8-bit microprocessor originally introduced in the 1970s. It became one of the most influential CPUs of the early personal-computer and video-game era.

• The processor has:

• an 8-bit accumulator (A),

• two 8-bit index registers (X and Y),

• an 8-bit stack pointer (SP),

• a 16-bit program counter (PC),

• an 8-bit processor-status register (P),

• a 16-bit address space,

• and an instruction set consisting of operations with different addressing modes and cycle counts.

• The emulator reproduces these CPU concepts using Rust data structures and functions.

High-level architecture#

• The crate is divided into two primary modules:

+-----------------------------+
|          6502 CPU           |
|                             |
|  +-----+ +-----+ +------+  |
|  |  A  | |  X  | |  Y   |  |
|  +-----+ +-----+ +------+  |
|                             |
|  +------+ +------+ +-----+ |
|  |  PC  | |  SP   | | P  | |
|  +------+ +------+ +-----+ |
+-------------+---------------+
             |
             | read / write
             v
+-----------------------------+
|            Mem              |
|                             |
|     64 KiB address space    |
+-----------------------------+

• The [Cpu] represents the processor itself, while [Mem] represents the memory visible to the processor.

Modules#

2^16 = 65,536 bytes

$0000 ..= $FFFF

CPU execution model#

At a high level, a 6502 repeatedly performs the following operations:

      +-------+
      | Fetch |
      +---+---+
          |
          v
     +---------+
     | Decode  |
     +----+----+
          |
          v
     +---------+
     | Execute |
     +----+----+
          |
          v
     +---------+
     | Update  |
     | State   |
     +----+----+
          |
          +-----------> Fetch next instruction

• The program counter (PC) identifies the next instruction to fetch. The CPU reads the opcode from memory, determines which instruction it represents, obtains any required operands, executes the operation, and updates its registers and processor-status flags.

Registers#

• The 6502 exposes several important CPU registers.

Addressing modes#

• A 6502 instruction does not necessarily obtain its operand in the same way for every instruction. The CPU provides several addressing modes.

• Important addressing modes include:

  • Immediate
  • Zero Page
  • Zero Page,X
  • Zero Page,Y
  • Absolute
  • Absolute,X
  • Absolute,Y
  • Indirect
  • Indexed Indirect
  • Indirect Indexed
  • Relative
  • Accumulator
  • Implied

• For example, an immediate instruction may contain its operand directly after the opcode:

LDA #$42

• Conceptually, the CPU reads:

opcode | operand
-------+--------
 A9   |   42

• and loads $42 directly into the accumulator.

• By contrast, an absolute addressing instruction contains a 16-bit memory address from which the operand must be loaded.

Status flags#

• Many 6502 instructions modify one or more processor-status flags.
• For example, an arithmetic or logical operation may set the Zero flag when its result is zero, or set the Negative flag when bit 7 of an 8-bit result is set.
• The flags are important because conditional branch instructions use them to determine whether execution should continue at another address.

Memory and CPU interaction#

• The CPU does not operate in isolation. Instructions frequently require memory reads and writes.

• Conceptually:

Cpu
|
| read/write(address)
v
Mem
|
v
[0x0000 ... 0xFFFF]

• Keeping the CPU and memory implementation separate makes the emulator easier to understand and test.

• It also mirrors an important aspect of the actual hardware: the CPU communicates with the outside world through its address and data buses.

Rust module structure#

• This crate uses two external Rust modules:

src/
├── lib.rs
├── cpu.rs
└── mem.rs

• The declarations below tell Rust to load cpu.rs and mem.rs as submodules of this crate. Rust’s module system maps an external module declaration such as mod cpu; to the corresponding source file src/cpu.rs.

crate
├── cpu
└── mem

Public API#

• The implementation modules are declared with pub, which makes the modules themselves accessible to users of the crate.

pub mod cpu;
pub mod mem;

• The crate then re-exports the most important types:

pub use cpu::{Cpu, StatusFlags};
pub use mem::Mem;

• This means users can write:

use emulator::{Cpu, Mem, StatusFlags};

• instead of having to write:

use emulator::cpu::Cpu;
use emulator::cpu::StatusFlags;
use emulator::mem::Mem;

• Re-exporting the primary types provides a simpler public API while allowing the implementation to remain organized into separate modules.

Example#

• A typical emulator program can conceptually be structured like this:

use emulator::{Cpu, Mem};

fn main() {
   // Create the memory used by the emulated computer.
   let mut mem = Mem::new();

   // Create the 6502 CPU.
   let mut cpu = Cpu::new();

   // Load a program into memory.
   //
   // The exact initialization and execution API depends on the
   // implementation in `cpu.rs` and `mem.rs`.
   
   // cpu.reset(&mut mem);
   // cpu.step(&mut mem);
}

Useful references#

• The following resources are useful when studying this emulator.

Documentation strategy#

• This crate-level documentation intentionally explains both the software architecture and the hardware concepts being emulated.
• The goal is that a reader can start at lib.rs, understand the overall architecture, and then move into the implementation:

lib.rs
|
+--> cpu.rs
|      |
|      +--> registers
|      +--> status flags
|      +--> addressing modes
|      +--> opcode decoding
|      +--> instruction execution
|
+--> mem.rs
       |
       +--> 6502 address space
       +--> memory reads
       +--> memory writes

• The detailed implementation comments in cpu.rs and mem.rs should explain how each part of the source code corresponds to the behavior of the original 6502 processor.

Further reading#

• When documenting individual instructions, it is useful to cross-reference the official/technical descriptions of the 6502 instruction set and then explain how the Rust implementation reproduces that behavior.

• In particular, pay attention to:

  • 1. opcode values,
  • 2. addressing modes,
  • 3. affected status flags,
  • 4. instruction length,
  • 5. cycle count,
  • 6. page-boundary behavior,
  • 7. signed relative branch offsets,
  • 8. stack behavior,
  • 9. interrupt/reset behavior,
  • 10. 8-bit arithmetic and overflow behavior.

• These details are where an emulator can differ subtly from a simple high-level implementation of the same instruction.

//! [`cpu`]: crate::cpu
//! [`mem`]: crate::mem
//! [`Cpu`]: crate::Cpu
//! [`Mem`]: crate::Mem
//! [`StatusFlags`]: crate::StatusFlags
pub mod cpu;
pub mod mem;

pub use cpu::{Cpu, StatusFlags};
pub use mem::Mem;