🖥️ Frank-386: An i386 PC Emulator for the RP2350

The frank-386 project is a specialized port of the Tiny386 emulator, designed specifically for the Raspberry Pi Pico 2 (RP2350). It transforms a microcontroller into a functional vintage PC capable of running legacy operating systems.

For more information, visit the official hub at frank.rh1.tech.

---

🚀 Core Capabilities

This emulator provides a comprehensive i386 environment with the following specifications:

• Processing Power: Full emulation of the i386 CPU, with partial support for i486 and i586 architectures.
  • Optional: Integrated x87 Floating Point Unit (FPU) emulation.
• Memory: Supports up to $8\text{MB}$ of RAM (utilizing external PSRAM).
• Visuals: VGA and HDMI output supporting standard text modes and graphical resolutions up to $640 \times 480$.
• Audio Suite:
  • AdLib OPL2 & Sound Blaster 16
  • PC Speaker & Tandy
  • Covox & Disney Sound Source
• Storage: SD card integration for simulating floppy disks, hard drives, and CD-ROMs.
• Input:
  • PS/2 Keyboard and Mouse.
  • Native USB HID Keyboard and Mouse.
  • NES Gamepads (includes a specialized mouse emulation mode).
• OS Compatibility: Successfully boots MS-DOS, Windows 3.x, Windows 95, and various Linux distributions.

---

🛠️ Hardware Ecosystem

Supported Hardware Platforms

The firmware is optimized for RP2350 boards featuring VGA/HDMI and SD slots:

1. FRANK: The primary versatile development board.
2. Murmulator: A compact retro-computing device (M1 and M2 versions).
3. Olimex PICO-PC: The official Olimex RP2350 PC implementation.
4. Waveshare RP2350-PiZero: The PiZero-style RP2350 board.

Minimum Requirements

• MCU: Raspberry Pi Pico 2 (RP2350).
• RAM: 8MB PSRAM (Optional Mandatory for extended memory).
• Video: VGA or HDMI interface.
• Storage: SPI-mode SD card module.
• Input: PS/2 or USB Keyboard.
• Audio: PWM or I2S DAC (Optional).

⚠️ Critical Note on USB: Enabling USB HID for keyboard/mouse input occupies the native USB port. Consequently, the USB serial console (CDC) is disabled; you must use a physical UART connection for debugging.

---

📌 Pin Mapping & Configurations

The emulator supports four distinct GPIO layouts: M1, M2, PC (Olimex), and Z2 (Waveshare).

Signal Assignments (M1 vs M2)

---

💾 Storage & Disk Management

SD Card Organization

You must create a directory named 386/ on the root of your SD card.

Configuration (config.ini)

Define your system parameters in the 386/config.ini file:

[pc]
mem = 8M
bios = bios.bin
vga_bios = vgabios.bin

[frank-386]
cpu_freq = 504
psram_freq = 166

Creating Disk Images

• Floppies: Standard 1.44MB images ($1,474,560$ bytes). dd if=/dev/zero of=floppy.img bs=512 count=2880
• Hard Drives: Raw images up to 2GB. dd if=/dev/zero of=hdd.img bs=1M count=512 (Then partition via FDISK).
• CD-ROMs: Standard ISO 9660 format.

---

🎮 Operation & Controls

Hotkeys

Runtime Menus

1. Settings Menu (Win+F11) Modify the following without re-flashing:

• Memory allocation (1MB to 8MB).
• CPU Generation (386 $\rightarrow$ 486 $\rightarrow$ 586).
• FPU toggle.
• Audio device selection (SB16, AdLib, etc.).
• Input toggles (PS/2 vs USB vs NES Mouse).
• Clock speeds for RP2350 and PSRAM.

2. Disk Manager (Win+F12) Allows "hot-swapping" of virtual media:

• Drives: A: (Floppy 1), B: (Floppy 2), C: (HDD), D: (HDD), E: (CD-ROM).
• Action: Browse the 386/ folder, select an image to mount, or eject the current one.

---

🛠️ Building the Firmware

Prerequisites

• Raspberry Pi Pico SDK (v2.0 or newer).
• ARM GCC Toolchain.
• Environment variable set: export PICO_SDK_PATH=/path/to/pico-sdk.

Compilation Steps

# Clone the source
git clone https://github.com/rh1tech/frank-386.git
cd frank-386

# Standard build (M2 board, 378MHz, PS/2)
./build.sh

# Build for M1 board
./build.sh -M1

# Build with USB HID support
./build.sh --usb-hid

# Advanced custom build
./build.sh -b M1 -c 504 -p 166 --debug

Build Flag Reference