firmware/README.md

FreeDOS on TTGO VGA32 (ESP32, FabGL 8086 emulator)

Sketch dosvga32/: FabGL 1.0.9 Machine (i8086, PIC, PIT, i8042, MC146818, CGA/Hercules adapter, embedded BIOS biosrom.h) from the PCEmulator example, copied locally and modified. No SD, WiFi or BT.

Build

export PATH=/tmp/opencode/w:$PATH ARDUINO_DIRECTORIES_DATA=/tmp/opencode/ard ARDUINO_DIRECTORIES_USER=/tmp/opencode/ardu
arduino-cli compile -b esp32:esp32:esp32:FlashMode=dio,FlashFreq=40 --build-path /tmp/b --jobs 4 dosvga32
# merge: see esptool merge_bin command in the task (0x1000 boot, 0x8000 parts, 0xe000 boot_app0, 0x10000 app, 0x200000 dosdisk.img)

dosvga32/partitions.csv is picked up automatically (PSRAM option must stay Disabled; the code calls esp_spiram_init itself). Extra QEMU test build: add --build-property build.extra_flags=-DDOSVGA_NO_VIDEO (skips VGA mode switching, which hangs in QEMU).

Flash layout (4 MB)

offset	size	content
0x1000		bootloader
0x8000	0x1000	partition table
0x9000	0x5000	nvs
0xe000	0x2000	otadata (boot_app0.bin)
0x10000	0x1F0000	app0 (ota_0, ~490 KB used)
0x200000	0x168000	dosdisk (data, subtype 0x40) = raw 1.44 MB FreeDOS 1.4 floppy 144m/x86BOOT.img

Pins (FabGL defaults = VGA32)

VGA R=22,21 G=19,18 B=5,4 HS=23 VS=15; PS/2 keyboard CLK=33 DATA=32; mouse CLK=26 DATA=27; audio 25. SD pins unused (MCP23S17 SPI probing removed).

Disk access

diskpart.cpp finds partition dosdisk (esp_partition_find_first) and exposes it as a FILE* via fopencookie for drive A: (fd0, geometry autodetected 80/2/18). Reads use esp_partition_read; writes go to a RAM overlay (copy-on-write 512 B sectors, 1 MB pool in the unused upper half of the emulated-RAM PSRAM block), lost at reset.

Notes

• Needs PSRAM (1 MB emulated PC RAM at 0x3F800000, as in FabGL PCEmulator). VGA32 v1.4 (WROVER) has it.
• Video: FabGL GraphicsAdapter -> VGADirectController (64 colours); text = 640x480@60 with 640x400 viewport (80x25, 8x16), Hercules = 720x350@70.
• Serial 115200 logs: stages + heartbeat with emulated instruction count and CS:IP.
• dist/: dosvga32.flash.bin (real HW), dosvga32.novideo-qemu.flash.bin (QEMU test), hello.flash.bin.
• QEMU: qemu-system-xtensa -nographic -machine esp32 -m 4M -global driver=ssi_psram,property=is_octal,value=false -drive file=F,if=mtd,format=raw (PSRAM needs these flags).

Extra notes (emulator project)

• dist/dosdisk.img is the FreeDOS 1.4 boot floppy with FDCONFIG.SYS (menu timeout 1 s) and FDAUTO.BAT (installer step replaced by a banner) patched so the demo reaches A:\> quickly; the untouched floppy is dist/dosdisk.orig.img.
• vgademo/ (FabGL VGA16 + PS/2 keyboard echo) and echo/ (Serial echo + LED on GPIO2) are the two extra example sketches.
• Build all sketches with arduino-cli compile -b esp32:esp32:esp32:FlashMode=dio,FlashFreq=40 (core esp32@2.0.17, FabGL@1.0.9), then merge with esptool.py merge_bin --fill-flash-size 4MB ... (see ../tools).