MFC 6502 Kernel

A comprehensive 6502 microprocessor kernel implementation with an interactive monitor program for debugging, programming, and system control.

This project started as a continuation of a CPU/assembler/disassembler I wrote in Python. I wanted to create an actual running environment to enter code directly or load from a file and run.

I also wanted to test the abilities of AI as part of the development and documentation process.

Project Overview

This project implements a complete 6502-based computer system kernel for emulated environments. The kernel provides low-level system initialization, hardware control, and most importantly, a powerful interactive monitor program for direct system interaction.

Key Features:

• Complete 6502 assembly language kernel optimized for emulated environments
• Cycle-stepped WDC 65C02 CPU emulator (full CMOS instruction set, validated against the Klaus2m5/amb5l functional, decimal, and 65C02-extended test suites)
• Interactive monitor with comprehensive debugging tools
• Built-in MFC BASIC interpreter (derived from EhBASIC), launched with the B: command (with human-readable .bas LOAD/SAVE)
• Memory manipulation and program execution capabilities
• Streamlined architecture with universal commands and simplified modes
• File I/O operations for loading and saving programs
• Comprehensive search, fill, move, and copy operations

Monitor Program

The heart of this system is the 6502 Monitor - a complete interactive debugging and programming environment that provides direct control over the computer's memory and execution. The monitor offers a command-line interface with powerful tools for memory operations, program execution, and system inspection.

Architecture Overview

The monitor features a streamlined architecture with:

• Two primary modes: Command mode (default) and Write mode for interactive editing
• Simplified command processing with consistent syntax and error handling
• Command repeatability recall last command for quick replay or modification

Getting Started

When the system boots, you'll see:

-=MFC 6502 OPERATIONAL=-
>

The > prompt indicates you're in command mode. You can now enter any monitor command.

Monitor Commands

For complete command documentation including syntax, examples, and detailed usage information, see:

📖 Complete Command Reference

The command reference provides comprehensive documentation for all monitor commands, organized by category:

Quick Command Summary

Category	Commands	Description
Memory Operations	R:, W:, F:, M:, X:	Read, write, fill, move/copy, and search memory
Program Operations	G:, L:, S:	Execute, load, and save programs
Modules	B:	Module bank menu — map and run a ROM module (BASIC is bank 1)
Number Conversion	D:, H:	Convert between decimal and hexadecimal
Display Commands	C:, T:, Z:	Clear screen, show stack, show zero page
System Commands	?, ESC, .	Help, exit mode, command recall

Key Command Features

Commands are listed alphabetically by command letter (matching the on-screen ? help):

• B: Module Bank Menu - List the available ROM modules and map/run one in the $B000-$DFFF window; BASIC is module bank 1 (modules return to the monitor on exit). See docs/module_slot_design.md
• C: Clear Screen - Clear the display
• D: Decimal to Hex - Convert decimal (0-65535) to hexadecimal format
• F: Fill Memory - High-performance memory filling with progress feedback
• G: Go/Run - Direct program execution with return to monitor
• H: Hex to Decimal - Convert hexadecimal (0000-FFFF) to decimal format
• L: Load File - Load a host-selected file to an address: L:8000 (host shows a file dialog)
• M: Move/Copy - Smart memory operations with overlap detection (M:src-end,dest,B where B: 0=copy, 1=move)
• R: Read Memory - Display bytes in memory, supports single addresses or ranges
• S: Save File - Save a memory range to a host-selected file: S:8000-8FFF (host shows a file dialog)
• T: Stack - Display the stack page ($0100-$01FF), paged
• W: Write Memory - Interactive hex editing with address advancement
• X: Search Memory - Multi-byte pattern search with paged output
• Z: Zero Page - Display zero page ($0000-$00FF), paged
• ESC - Exit the current mode and return to the command prompt

Error Handling

The monitor provides clear, consistent error messages:

• ERROR? - Invalid command syntax or parameters
• RANGE? - Invalid or out-of-bounds address range
• VALUE? - Invalid hexadecimal characters in input

📖 Detailed Architecture Reference

Memory Layout

• $0000-$00FF: Zero Page (system workspace; monitor uses $14-$39, EhBASIC uses the rest)
• $0100-$01FF: Stack memory
• $0200-$03FF: Monitor variables and command buffers
• $0400-$07E7: Screen memory (40x25 display buffer)
• $0800-$AFFF: User RAM (module working RAM; EhBASIC program/variable space)
• $B000-$DFFF: Module window (12 KB; bank 0 = RAM, banks 1..255 = ROM modules — BASIC is bank 1)
• $E000-$FFFF: Kernel ROM (8 KB; CODE ~3,900 bytes, rest free for growth)
• $FE00-$FE22: PIA registers (keyboard, file I/O, timer) — an I/O page reserved within the kernel region

See docs/kernel_memory_map.md for the full map.

📖 Kernel Services Guide

User programs can access kernel services via the jump table at $FF00:

Address	Service	Description
$FF00	PRINT_CHAR	Print single character
$FF03	PRINT_MESSAGE	Print null-terminated string
$FF06	PRINT_NEWLINE	Print carriage return/line feed
$FF09	GET_KEYSTROKE	Wait for key press
$FF0C	CLEAR_SCREEN	Clear display
$FF0F	GET_RANDOM_NUMBER	Generate random byte
$FF12	RETURN_FROM_MODULE	Module exit point — unmaps the bank, returns to monitor (BASIC BYE)

File I/O Interface

The kernel provides memory-mapped file I/O at:

• $FE10: File command register
• $FE11: File status register
• $FE12-$FE13: Address registers
• $FE14-$FE1F: Filename buffer
• $FE20-$FE21: End address (for save operations)

Building and Development

Prerequisites

• CMake 3.20 or later
• C++20 compatible compiler (GCC 10+, Clang 10+, MSVC 2019+)
• cc65 toolchain (ca65 assembler and ld65 linker)
• Qt6 or Qt5 (optional, for GUI support)

Build Instructions

# Option 1: Use the convenient build script (recommended)
./build.sh

# Option 2: Manual out-of-source build
cd cmake-build-debug
cmake -G Ninja ..
ninja

# Build outputs:
# - Executable: cmake-build-debug/bin/6502-kernel
# - Kernel ROM: cmake-build-debug/kernel/kernel.rom
# - BASIC ROM:  cmake-build-debug/kernel/basic.rom
# - Memory map: cmake-build-debug/kernel/kernel.map

Project Structure

6502-kernel/
├── src/                    # C++ source files
│   ├── computer/          # CPU, memory, VIC, PIA emulation
│   ├── ui/                # Qt GUI
│   └── kernel/            # 6502 assembly (kernel.asm, basic.asm) + ld65 configs
├── include/                # C++ header files
├── docs/                  # Documentation
├── examples/              # Example 6502 programs
├── tools/cmake/           # CMake modules
└── tests/                 # Unit and integration tests

For detailed development information and project context, see:

• CLAUDE.md - Development guidelines and architecture documentation
• docs/ - Detailed command documentation and requirements

Tips for Effective Use

1. Start with Help: Use ? to see all available commands
2. Use Command Recall: The . command saves time when refining commands
3. File Operations: L:8000 loads and S:8000-8FFF saves; the host shows a file dialog to pick the file
4. Search Effectively: Use X: with multiple byte patterns for precise matching
5. Number Conversion: Use D: and H: commands to convert between decimal and hex
6. Program Development: Load programs with L:, test with G:, save modifications with S:

The monitor is designed for both interactive exploration and efficient program development workflows.