https://github.com/hchunhui/tiny386
tiny 386 PC emulator; running win9x on esp32
https://github.com/hchunhui/tiny386
emulator esp32 x86
Last synced: 5 days ago
JSON representation
tiny 386 PC emulator; running win9x on esp32
- Host: GitHub
- URL: https://github.com/hchunhui/tiny386
- Owner: hchunhui
- License: bsd-3-clause
- Created: 2024-05-26T09:30:44.000Z (about 2 years ago)
- Default Branch: master
- Last Pushed: 2026-04-05T08:42:20.000Z (2 months ago)
- Last Synced: 2026-04-05T10:18:55.849Z (2 months ago)
- Topics: emulator, esp32, x86
- Language: C
- Homepage: https://hchunhui.github.io/tiny386
- Size: 721 KB
- Stars: 529
- Watchers: 14
- Forks: 50
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Tiny386
## Introduction
Tiny386 is an x86 PC emulator written in C99. The highlight of the project is its portability. It now boots Windows 9x/NT on MCU such as ESP32-S3.
The core of the project is a built-from-scratch, simple and stupid i386 cpu emulator. Some features are missing, e.g. debugging, hardware tasking and some permission checks, but it should be able to run most 16/32 bit software. To boot modern linux kernel and windows, some 486 and 586 instrutions are added. The cpu emulator is kept in ~6K LOC. There is also an optional x87 fpu emulator.
To assemble a complete PC system, we have ported many peripherals from TinyEMU and QEMU, it now includes:
- 8259 PIC
- 8254 PIT
- 8042 Keyboard Controller
- CMOS RTC
- ISA VGA with Bochs VBE
- IDE Disk Controller
- NE2000 ISA Network Card
- 8257 ISA DMA
- PC Speaker
- Adlib OPL2 (optional)
- SoundBlaster 16
For firmware, the BIOS/VGABIOS comes from seabios. Tiny386 also supports booting linux kernel directly, without traditional BIOS. The idea comes from JSLinux, and it uses a small stub code called linuxstart.
## Demo
See [here](https://hchunhui.github.io/tiny386)
## Build
Linux (with rawdraw): You need to install `libslirp` `libx11` and `libasound2` first, then type `make`.
Linux (with SDL): You need to install `libslirp` `SDL1.2` (or `sdl12-compat`) first, then type `make USE_SDL=y`.
For other platforms, please refer to `.github/workflows/build.yml`.
Pre-built binaries: [here](https://github.com/hchunhui/tiny386/releases)
## Usage
- Prepare an ini file
```ini
[pc]
; set path to BIOS and VGA BIOS
bios = bios.bin
vga_bios = vgabios.bin
; set memory size and VGA memory size
mem_size = 32M
vga_mem_size = 2M
; fda/fdb for floppy disks (optional)
fda = floppy.img
; hda/hdb/hdc/hdd for hard disks (optional)
; cda/cdb/cdc/cdd for CD-ROM disks (optional)
hda = win95.img
cdb = win95_cd.iso
; "fill_cmos" fixes "MS-DOS compatibility mode" in win9x, but it breaks winNT...
fill_cmos = 1
; force 8-dot mode (640 pixel wide in text mode) if set to 1
vga_force_8dm = 0
[display]
width = 720
height = 480
[cpu]
; gen = 3/4/5/6, for 386/486/586/686
gen = 3
; fpu = 0/1, to disable/enable x87
fpu = 0
```
- Run
```sh
./tiny386 config.ini
./tiny386 -kvm config.ini # run with KVM (build with `make USE_CPUABS=y`)
```
For rawdraw and SDL port:
Press "Ctrl + ]" to grab/ungrab the keyboard and mouse. Press "Ctrl + [" to show/hide OSD (On Screen Display). In OSD mode, the floppy/CD-ROM disk can be changed on the fly.
## ESP32 port
Supported boards:
With ESP-IDF 5.2.x:
- JC3248W535 (ESP32-S3, 480x320)
- [Elecrow CrowPanel Advance 7.0" HMI](https://github.com/Elecrow-RD/CrowPanel-Advance-HMI-ESP32-AI-Display) (ESP32-S3, 800x480)
With ESP-IDF 6.0.x (experimental):
- JC4880P443 (ESP32-P4 Rev1.3 360MHz, 800x480)
### Build and Flash
You can find the pre-built flash image `esp/flash_image_JC3248W535.bin` from [here](https://github.com/hchunhui/tiny386/releases).
The pre-built image can be flashed directly to offset 0.
Online flasher for esp chips: https://espressif.github.io/esptool-js
To build and flash manually:
```sh
scripts/build.sh patch_idf # apply patches to ESP-IDF 5.2.x
#scripts/build.sh patch_idf_60 # apply patches to ESP-IDF 6.0.x
make prepare
cd esp
idf.py -DBOARD=jc3248w535 update-dependencies build # or -DBOARD=elecrow7s3
idf.py flash
```
### Configure
All files should be put in a SD card with FAT/exFAT file system. The ini file should be `tiny386.ini` and put in the root directory.
Please refer to `esp/tiny386.ini`.
Alternative usage: `bios.bin` `vgabios.bin` `vmlinux.bin` and `linuxstart.bin` can be put in corresponding flash partition. Other files can be put in the `storage` flash partition. Please refer to `esp/partition.csv`.
### Keyboard/Mouse Input
- Forward over WIFI
`wifikbd` is used to forward keyboard/mouse events to the dev board over WIFI:
```
(ESP32-S3 board: listen on TCP port 9999) <--- WIFI ---> AP <--- WIFI/Wire ---> (PC: ./wifikbd esp_board_addr 9999)
```
- USB hid (WIP)
See [here](https://github.com/hchunhui/tiny386/pull/4).
## Troubleshooting
### "0 bytes of memory" during Windows 95 setup
Use "setup /im" to bypass memory check.
### "protection error" during Windows 95 startup
Use [patcher9x](https://github.com/JHRobotics/patcher9x).
### NE2000 doesn't work
Manually set the IRQ to 9(or 2).
### freeze during Windows NT4/2000/XP startup
Use `fill_cmos = 0` in the config ini file.
## License
The cpu emulator and the project as a whole are both licensed under the BSD-3-Clause license.
Adlib emulation is an optional part of the project, and it requires the library fmopl which is licensed under the LGPL.
Use `make USE_FMOPL=n` to build without adlib emulation.
SeaBIOS is distributed under the GNU LGPL-3 license.
Some parts ported from QEMU/TinyEMU are under the MIT license.