Documentation Index

Source file

FPGA Documentation Index

Welcome to the 6502 SBC FPGA documentation. This directory contains comprehensive guides for understanding, building, and developing the FPGA implementation.

Quick Links

• README - Project overview and current status
• Architecture - System design and memory map
• Modules Reference - Detailed component documentation
• Building & Synthesis - How to build and synthesize the project
• Testing Guide - Test infrastructure and running tests
• Component Reference - Detailed specs for major components
• Sound Chip - Single-voice synth + PT8211 DAC: register map, usage, and wiring
• Simulation - Running and analyzing simulations
• Development Guide - Contributing and development workflow
• UART Monitor - Hardware monitor commands and live ROM upload over UART
• SD Bootloader - SD-card shadow-ROM boot flow
• FPGA Tools GUI - Graphical launcher for all Python build/upload/utility tools
• FPGA Image Captures - Real HDMI screenshots captured from FPGA hardware
• Roadmap - Project roadmap and milestones
• PIX16 Build Guide - Xilinx ISE build and programming guide for the PIX16 Spartan-6 board
• Tang Primer 20K Guide - Gowin build notes, CH340 UART, HDMI boot screen, and on-board microSD wiring
• Hardware Support - PIX16 board pinout, target device, and VGA smoke-test notes

Project Structure

fpga/
├── docs/                    Documentation files
│   ├── INDEX.md            This file
│   ├── 01_ARCHITECTURE.md  System design
│   ├── 02_MODULES.md       Component documentation
│   ├── 03_BUILDING.md      Build instructions
│   ├── 04_TESTING.md       Test guide
│   ├── 05_COMPONENTS.md    Component reference
│   ├── 06_SIMULATION.md    Simulation guide
│   ├── 07_DEVELOPMENT.md   Development guide
│   ├── UART_MONITOR.md     UART hardware monitor and ROM upload
│   ├── SD_BOOTLOADER_PLAN.md SD-card shadow-ROM boot flow
│   ├── FPGA_TOOLS_GUI.md   Graphical launcher for Python tools
│   ├── images/             Real FPGA HDMI screenshots captured through a video grabber
│   └── roadmap.md          Project roadmap
├── boards/
│   ├── pix16/              PIX16 Spartan-6 (constraints, scripts, project, bitstreams)
│   └── tang_primer_20k/    Gowin GW2A-18 (HDMI, CH340 UART, on-board SD boot)
├── rtl/core/               Board-agnostic VHDL
│   ├── cpu/                CPU adapters
│   ├── mem/                Memory (RAM/ROM)
│   ├── peripherals/        Device controllers
│   └── boot/               Boot subsystem
├── sim/
│   ├── tb/                 Testbenches
│   └── hex/                Static ROM hex files
├── sw/                     6502 firmware (assembly)
├── third_party/            Imported open-source cores
└── tools/                  Build utilities

Key Concepts

6502 Architecture Compatibility

The FPGA maintains 100% software compatibility with the C emulator:

• 16-bit address space (0x0000-0xFFFF)
• 8-bit data bus
• Same memory map with peripherals at identical addresses
• IRQ logic combining VIA, UART, and VIC interrupts
• SD boot top loads the 16 KB $C000-$FFFF ROM window into shadow RAM
• UART hardware monitor can inspect/patch RAM, VRAM, I/O, and shadow ROM

Design Approach

• Modular components: Each peripheral is independently testable
• Synthesizable VHDL: All RTL is ready for real FPGA targets
• Incremental development: Placeholders for incomplete features
• Deterministic testing: ROM-scripted tests for repeatability

FPGA Image Captures

The screenshots in images are real captures from the FPGA hardware output. They are not emulator renders or simulator frames. The HDMI video signal generated by the Tang Primer 20K FPGA design was recorded through an external HDMI video grabber and saved as documentation and regression reference images.

Current captures include boot/debug output, EhBASIC startup, Mandelbrot BASIC demo output, and PETSCII/VIC text-mode graphics used to verify the character ROM, HDMI scanout, and CPU-to-VRAM write path.

Tang Primer Debug Screen

EhBASIC Boot

Mandelbrot BASIC Demo

PETSCII Test

Getting Started

For Users

1. Read Architecture to understand the system design
2. Check Building & Synthesis to compile the project
3. Review Testing Guide to run existing tests

For Developers

1. Start with Architecture for system overview
2. Read Modules Reference for component details
3. Review Component Reference for detailed specs
4. Follow Development Guide for contribution process

For FPGA Synthesis

1. Understand the Architecture
2. Review Building & Synthesis for build flow
3. Check Components Reference for FPGA-specific notes

Current Status

Latest Tests Passing: All 14 smoke tests

• Address decoder verification
• Reset vector fetch from ROM
• SRAM read/write operations
• VIA 6522 timer and GPIO control
• UART 6551 serial communications
• T65 CPU core integration and instruction execution
• Real 6502 ROM boot sequences
• Interrupt handling and servicing

Completed Milestones

• ✅ Bus architecture and memory map
• ✅ Basic ROM/SRAM components
• ✅ T65 CPU core integration
• ✅ VIA 6522 partial implementation
• ✅ UART 6551 partial implementation
• ✅ PIX16 ISE project targeting xc6slx16-ftg256-2
• ✅ Board-level VGA smoke test with ROM-scripted welcome text
• ✅ PIX16 SD boot top with boot VGA status, SDRAM RAM test, and UART monitor
• ✅ Tang Primer 20K HDMI boot/status screen, CH340 UART, and KEY1 FPGA monitor bring-up
• ✅ Live 16 KB ROM upload into shadow ROM over UART
• ✅ Single-voice sound chip (square + noise) on the Tang dock PT8211 DAC
• ✅ Comprehensive documentation

In Progress

• VIC video controller expansion
• Complete UART implementation
• Full VIA functionality
• Larger ROM and BASIC bring-up on the SD boot top

Key Files

File	Purpose
rtl/core/sbc_pkg.vhd	Memory map constants and type definitions
rtl/core/bus_decode.vhd	Address decoder
rtl/core/sbc_top.vhd	Main system integration (test mode)
rtl/core/sbc_t65_top.vhd	System with T65 CPU
boards/pix16/rtl/pix16_sbc_sd_boot_top.vhd	Active PIX16 SD-card/SDRAM/monitor board top
rtl/core/sbc_t65_sdram_boot_top.vhd	T65 SBC core with SDRAM, shadow ROM, VGA, and monitor bus access
boards/tang_primer_20k/rtl/tang20k_sbc_top.vhd	Active Tang Primer 20K HDMI/CH340/on-board-SD board top
rtl/core/sbc_t65_boot_monitor_top.vhd	T65 SBC core with internal BSRAM, SD-loaded shadow ROM, VGA, and monitor bus access
rtl/core/boot/uart_debug_monitor.vhd	UART machine-language monitor
boards/pix16/rtl/pix16_sbc_minimal_top.vhd	Minimal PIX16 VGA smoke-test board top
boards/pix16/project/fpga.xise	Xilinx ISE project for xc6slx16-ftg256-2
rtl/core/peripherals/*.vhd	Peripheral controllers
rtl/core/mem/*.vhd	Memory components
sim/tb/*.vhd	Testbenches

Next Steps

1. For New Developers: Start with Architecture
2. For Building: See Building & Synthesis
3. For Contributing: See Development Guide
4. For Questions: Check individual documentation files or the main README

---

Last Updated: June 2026
Status: Active Development
Maintainer: Rudolf Stepan