pico-286

🕹️ Pico-286 Project

The Pico-286 project is an endeavor to emulate a classic PC system, reminiscent of late 80s and early 90s computers, on the Raspberry Pi Pico (RP2040/RP2350 microcontroller). It aims to provide a lightweight and educational platform for experiencing retro computing and understanding low-level system emulation. 🖥️✨

⭐ Key Features

🎮 Supported Hardware Emulations

🧠 CPU Emulation

🎵 Sound Card Emulations

🖼️ Graphics Card Emulations

📝 Text Modes (Common to All Graphics Cards)

All graphics card emulations support standard text display modes for character-based applications:

📝 Standard Text Modes:

🚀 Advanced CGA Text Modes (8088 MPH Demo Techniques):

🎨 CGA (Color Graphics Adapter)

The CGA emulation provides authentic IBM Color Graphics Adapter functionality, supporting the classic early PC graphics modes:

🎮 Graphics Modes:

📊 HGC (Hercules Graphics Card)

The Hercules Graphics Card emulation recreates the popular monochrome high-resolution graphics standard:

🖥️ Graphics Mode:

🖥️ EGA (Enhanced Graphics Adapter)

The Enhanced Graphics Adapter emulation provides IBM EGA compatibility with full 16-color support:

🚀 Enhanced Graphics Modes:

🖥️ TGA (Tandy Graphics Adapter)

The Tandy Graphics Adapter emulation recreates the enhanced graphics capabilities of Tandy 1000 series computers:

🚀 Enhanced Graphics Modes:

🖼️ VGA (Video Graphics Array)

The VGA emulation provides comprehensive Video Graphics Array support with planar memory architecture and multiple advanced modes:

📊 Standard VGA Modes:

🔧 VGA Technical Features:

💾 Storage: Disk Images and Host Access

The emulator supports two primary types of storage: virtual disk images for standard DOS drives (A:, B:, C:, D:) and direct access to the host filesystem via a mapped network drive (H:).

Virtual Floppy and Hard Disks (Drives A:, B:, C:, D:)

The emulator supports up to two floppy disk drives (A: and B:) and up to two hard disk drives (C: and D:). Disk images are stored on the SD card.

The emulator expects the following file paths and names for the disk images:

Important Notes:

Host Filesystem Access (Drive H:)

For seamless file exchange, the emulator can map a directory from the host filesystem and present it as drive H: in the DOS environment. This feature is implemented through the standard DOS network redirector interface (INT 2Fh, Function 11h).

This is ideal for development, allowing you to edit files on your host machine and access them instantly within the emulator without modifying disk images.

How It Works

The emulator intercepts file operations for drive H: and translates them into commands for the host’s filesystem. To enable this drive, you must run the MAPDRIVE.COM utility within the emulator.

The mapped directory depends on the platform:

MAPDRIVE.COM Utility

The tools/mapdrive.asm source file can be assembled into MAPDRIVE.COM using FASM. This utility registers drive H: with the DOS kernel as a network drive.

Prerequisite: Before using MAPDRIVE.COM, ensure your CONFIG.SYS file contains the line LASTDRIVE=H (or higher, e.g., LASTDRIVE=Z). This tells DOS to allocate space for drive letters up to H:, allowing MAPDRIVE.COM to successfully create the new drive.

To use it:

  1. Assemble mapdrive.asm to mapdrive.com.
  2. Copy mapdrive.com to your boot disk image (e.g., fdd0.img or hdd.img).
  3. Run MAPDRIVE.COM from the DOS command line.
  4. Add MAPDRIVE.COM to your AUTOEXEC.BAT to automatically map the drive on boot.

🔧 Hardware Configuration

The Pico-286 emulator is designed to run on Raspberry Pi Pico (RP2040) based hardware. 🍓

🎛️ Supported Components

🏗️ Minimal Configuration

🚀 Recommended Configuration for Maximum Performance

🛠️ Development Platform

🔧 Supported PSRAM Configurations

The emulator automatically detects and configures various PSRAM hardware:

Memory Detection: Runtime PSRAM size detection (16MB, 8MB, 4MB, 1MB) with validation through test patterns

🔌 Default Pinout

The emulator has a default GPIO pin configuration for its peripherals on the Raspberry Pi Pico. These are defined in CMakeLists.txt and can be modified there if needed.

Peripheral GPIO Pin(s) Notes
VGA Output 6 (base pin) Sequential pins used for RGB
HDMI Output 6 (base pin)  
NTSC TV Out 22 Composite video output
TFT Display CS: 6, RST: 8, LED: 9, DC: 10, DATA: 12, CLK: 13 ST7789 driver
SD Card CS: 5, SCK: 2, MOSI: 3, MISO: 4 SPI0
PSRAM CS: 18, SCK: 19, MOSI: 20, MISO: 21 Generic external PSRAM
NES Gamepad CLK: 14, DATA: 16, LAT: 15 Used for mouse emulation if needed
I2S Audio CLOCK: 17, PCM: 22  
PWM Audio Beeper: 28, L: 26, R: 27  

⚙️ Platform-specific Details

The emulator’s resource allocation changes based on the target platform and build options.

Conventional RAM (RAM_SIZE)

This is the amount of memory available to the emulated PC as conventional memory (e.g., the classic 640KB).

Platform Memory Configuration Available RAM
Host N/A 640 KB
RP2350 PSRAM (default) 350 KB
RP2350 Virtual Memory 200 KB
RP2040 PSRAM (default) 116 KB
RP2040 Virtual Memory 72 KB

Audio Sample Rate (SOUND_FREQUENCY)

The audio quality depends on the platform and the chosen audio output method.

Platform Audio Option Sample Rate
Any HARDWARE_SOUND=ON 44100 Hz
Host Any other option 44100 Hz
RP2350 Any other option 44100 Hz
RP2040 Any other option 22050 Hz

Extended Memory (EMS/XMS)

To run more advanced DOS applications and games, the emulator supports two types of extended memory systems, providing memory beyond the conventional 640KB limit. The active system is chosen at compile time.

1. PSRAM (Pseudo-Static RAM)

This is the high-performance default method, used when a hardware PSRAM chip is available.

2. Virtual Memory (Swap File)

This is a fallback system for hardware that lacks a PSRAM chip, primarily intended for memory-constrained RP2040 boards.

🏛️ Platform Architecture

The emulator uses different architectures depending on the target platform to best utilize the available resources.

Raspberry Pi Pico (Dual-Core)

The Pico build takes full advantage of the RP2040/RP2350’s dual-core processor.

This division of labor ensures that the demanding CPU emulation does not interfere with smooth video and audio output.

Windows & Linux (Multi-threaded)

The host builds (for Windows and Linux) are multi-threaded to separate tasks.

This architecture allows for accurate timing and responsive I/O on a non-real-time desktop operating system.

🔨 Building and Getting Started

📋 Prerequisites

For Raspberry Pi Pico builds:

For Windows host builds:

For Linux host builds:

🛠️ Build Configuration

The project uses CMake with platform-specific configurations. All builds require exactly one display option and one audio option.

🖥️ Display Options (Choose exactly one):

🔊 Audio Options (Choose exactly one):

🧠 Memory Configuration:

🚀 Build Commands

Raspberry Pi Pico 2 (RP2350) - Recommended:

# Clone the repository
git clone <repository-url>
cd pc

# Create build directory
mkdir build && cd build

# Configure for RP2350 with VGA and PWM audio
cmake -DCMAKE_BUILD_TYPE=Release \
      -DPICO_PLATFORM=rp2350 \
      -DENABLE_VGA=ON \
      -DENABLE_PWM_SOUND=ON \
      ..

# Build
make -j$(nproc)

Raspberry Pi Pico (RP2040):

# Configure for RP2040 with TFT and I2S audio
cmake -DCMAKE_BUILD_TYPE=Release \
      -DPICO_PLATFORM=rp2040 \
      -DENABLE_TFT=ON \
      -DENABLE_I2S_SOUND=ON \
      ..

# Build  
make -j$(nproc)

Linux Host Build:

# Install dependencies (Ubuntu/Debian)
sudo apt update
sudo apt install build-essential cmake git libx11-dev

# Clone and build
git clone <repository-url>
cd pc
mkdir build && cd build

# Configure for Linux host platform
cmake -DCMAKE_BUILD_TYPE=Release \
      -DPICO_PLATFORM=host \
      ..

# Build
make -j$(nproc)

Windows Host Build:

# Configure for host platform (development/testing)
cmake -DCMAKE_BUILD_TYPE=Release \
      -DPICO_PLATFORM=host \
      ..

# Build
make -j$(nproc)
# On Windows with Visual Studio: cmake --build . --config Release

🔧 Advanced Build Options

Memory-constrained RP2040 with Virtual Memory:

cmake -DCMAKE_BUILD_TYPE=Release \
      -DPICO_PLATFORM=rp2040 \
      -DTOTAL_VIRTUAL_MEMORY_KBS=512 \
      -DENABLE_VGA=ON \
      -DENABLE_PWM_SOUND=ON \
      ..

High-performance RP2350 with HDMI:

cmake -DCMAKE_BUILD_TYPE=Release \
      -DPICO_PLATFORM=rp2350 \
      -DENABLE_HDMI=ON \
      -DENABLE_I2S_SOUND=ON \
      -DCPU_FREQ_MHZ=504 \
      -DFLASH_FREQ_MHZ=100 \
      -DPSRAM_FREQ_MHZ=166 \
      ..

Butter-PSRAM Configuration (MURM20 board):

cmake -DCMAKE_BUILD_TYPE=Release \
      -DPICO_PLATFORM=rp2350 \
      -DENABLE_VGA=ON \
      -DENABLE_PWM_SOUND=ON \
      -DMURM20=ON \
      ..

Batch Build All Configurations:

# Build all firmware variants automatically
./build_all_firmwares.sh

# Merge RP2040/RP2350 firmware pairs
./merge_firmwares.sh

📦 Build Outputs

After successful compilation, build artifacts are placed in the bin/<platform>/<build_type>/ directory.

For host builds:

For Pico builds:

The firmware filename is dynamically generated to reflect the build configuration, following this pattern: 286-<platform>-F<flash>-P<psram>-<cpu_freq>-<display>-<audio>.uf2

Example Filenames:

The following files are generated:

🎯 Flashing to Pico

  1. Hold the BOOTSEL button while connecting your Pico to USB
  2. Copy the .uf2 file to the mounted RPI-RP2 drive
  3. The Pico will automatically reboot and start running the emulator

💾 Setting up Disk Images

For Raspberry Pi Pico builds:

Create the required directory structure on your SD card:

SD Card Root/
└── XT/
    ├── fdd0.img    # Floppy Drive A:
    ├── fdd1.img    # Floppy Drive B: (optional)
    ├── hdd.img     # Hard Drive C:
    └── hdd2.img    # Hard Drive D: (optional)

For Linux/Windows host builds:

Place disk images in the project root directory:

# From your project directory (pc/)
# Place disk images directly in the root:
cp your-boot-disk.img fdd0.img     # Floppy Drive A:
cp your-floppy2.img fdd1.img       # Floppy Drive B: (optional)  
cp your-harddisk.img hdd.img       # Hard Drive C:
cp your-harddisk2.img hdd2.img     # Hard Drive D: (optional)

# Run from build directory
cd build
../bin/host/Release/286   # Linux
# or ../bin/host/Release/286.exe   # Windows

Supported disk image sizes:

🐛 Troubleshooting

Build fails with “display/audio option required”:

Linux build fails with “X11 not found”:

Host build shows “DISK: ERROR: cannot open disk file”:

Linux emulator window appears but shows black screen:

Out of memory errors on RP2040:

HDMI not working:

PSRAM detection issues:

Performance issues:

📚 Additional Resources

🤝 Contributing

Contributions to the Pico-286 project are welcome! Please refer to the CONTRIBUTING.md file (to be created) for guidelines. 💪

Stargazers over time

Stargazers over time

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

This site is open source. Improve this page.