megabytefisher/Dragonfruit 源代码：https://github.com/megabytefisher/Dragonfruit # Dragonfruit 摩托罗拉MC68EZ328（“DragonBall EZ”）的模拟器，这款基于68000的片上系统是上世纪90年代末Palm掌上电脑的核心。该项目对周边机器进行了足够建模，能够启动并运行原版Palm OS 3.x。所有代码均使用可移植的C语言从头编写：包括一个68000解释器以及DragonBall片上外设（中断控制器、定时器、RTC、GPIO、SPI、UART、LCD控制器）的模型。核心无平台依赖。可在PC上无头运行用于开发，在ESP32硬件上运行以实现真实效果。参考目标是 M5Paper，一款配备电子墨水屏和电容触摸屏的ESP32板，该模拟器将其变为一台可用的Palm IIIx：它能够启动到启动器，运行首次启动设置向导，并支持包括Graffiti手写在内的触控笔输入。你需要自行提供ROM。Palm OS受版权保护，不包含在此；参见运行它。 一台在M5Paper上运行的Palm IIIx，可识别Graffiti手写输入 ## 已完成的功能 - 从原版Palm IIIx ROM启动Palm OS 3.1，一路进入启动器，在PC主机和设备上均可。 - 首次启动设置向导：欢迎、触控校准、国家/时间/日期。 - 触控笔输入：点击、屏幕按钮（应用/菜单/计算/查找）以及Graffiti手写，全部通过一个连续的数字化仪表面板实现，ROM原生处理。 - 实时时钟和基于真实时间的100Hz系统时钟滴答，无论模拟速度如何，两者都保持正确。 - 休眠和自动关机（DragonBall的PLL关闭STOP模式），可通过建模的键盘矩阵唤醒电源键。在M5Paper上，这还会驱动ESP32进入轻度睡眠。 - 从SD卡安装.prc / .pdb / .pqa文件到模拟RAM，并将设备数据库备份或恢复到SD卡。 - 可选的可配置屏幕布局：通过SD卡上的文件重新定位或调整屏幕按钮大小、旋转至横屏或放大。 ## 可移植性 本项目是模拟器，而非单一开发板。这种划分是刻意的： - 核心，可移植C语言。 68000解释器、DragonBall外设模型、总线以及Palm OS集成（触控笔注入、安装器、备份/还原）不携带任何ESP-IDF或开发板依赖。PC主机构建编译的正是这些代码，并用一个薄层替代ESP-IDF，这使得无需刷写硬件即可进行日常开发成为可能。 - 性能后端，按ISA划分。 在设备上，热点路径采用突发JIT，将68000块翻译为本地代码。其代码生成器位于一个构建时选择的后端接口之后，因此新指令集仅需新后端，无需重写。经典的ESP32（Xtensa）后端已经完成；ESP32-P4（RISC-V）构建可链接并仅运行解释器，其后端尚未编写。 - 开发板，外设。 电子墨水驱动、触摸控制器、SD挂载和电池检测位于各自的组件中。要适配不同的ESP32开发板，只需编写这些驱动，无需触碰核心。在ESP32方面，要求外部PSRAM（2MB模拟RAM和ROM镜像存放在其中）和双核（JIT编译器在第二核上运行）。这排除了单核、无PSRAM的芯片，如ESP32-C3。 ## 硬件（M5Paper参考目标） - SoC — ESP32-D0WDQ6-V3，双核240 MHz，16 MB闪存，8 MB PSRAM。 - 显示 — IT8951电子墨水控制器，通过SPI连接，960×540面板。Palm的160×160 1bpp帧缓冲被缩放并逆时针旋转90°，形成顶部对齐的竖屏布局，Graffiti屏幕按钮区域渲染在其下方。 - 触摸 — GT911电容控制器，通过I2C连接。 ## 仓库结构 src/ main/ ESP-IDF入口点和FreeRTOS任务（CPU、显示、输入、电池） components/ m68k/ 68000解释器（解码、寻址、ALU、移动、分支、移位、位操作、BCD、系统）以及仅用于设备的突发JIT及其按ISA划分的后端 bus/ 24位地址空间：2 MB RAM、ROM窗口、外设译码 dragonball/ MC68EZ328外设：中断控制器、定时器、RTC、GPIO、SPI（数字化仪+电池ADC）、UART、LCD控制器 display/ IT8951电子墨水驱动程序；合成帧缓冲和屏幕按钮覆盖层 input/ GT911触摸轮询，生成笔事件队列；按键锁存 layout/ 面板到Palm坐标映射，显示和输入共享 config/ 启动时从SD卡读取可选的布局配置 rom_loader/ 启动时从SD卡将ROM加载到PSRAM installer/ 将PRC/PDB/PQA安装到RAM中；备份和还原数据库 m5_sd/ 管理电子墨水SPI总线上的共享microSD挂载 host/ PC构建框架：无头运行核心，用esp_shim.h替代ESP-IDF，并附带PNG快照生成器（以及可选的SDL窗口）用于屏幕输出 tools/ 主机端脚本，用于驱动设备上的串行调试控制台 reference/ 只读参考模拟器和数据手册，用于了解硬件行为，绝不复制（不提交；见下方） reference/ 目录包含第三方模拟器（CloudpilotEmu, Mu, POSE）和供应商驱动示例，仅用于理解硬件行为。它不是本仓库源代码的一部分，不会被提交。 ## 运行它 你需要一份Palm IIIx的Palm OS 3.x ROM。此处不提供。通常的获取方式是从你拥有的设备上传输（经典的Palm OS模拟器附带了ROM传输工具）。 ### 在PC上，无需硬件 这是最快迭代的方式。主机版本编译相同的模拟器核心，并在屏幕变化时写入PNG。 cmake -S src/host -B build-host cmake --build build-host ./build-host/dragonfruit -r Palm-IIIx-3.1.rom -c 150000000 -r 选择ROM，-c 限制周期数，-i 队列自动安装PRC/PDB，-b 退出时导出RAM数据库。 若需要交互窗口（模拟屏幕和屏幕按钮，鼠标点击作为触控笔交互），请使用SDL UI构建并加上--ui运行： cmake -S src/host -B build-host -DHOST_UI=ON cmake --build build-host ./build-host/dragonfruit -r Palm-IIIx-3.1.rom --ui ### 在M5Paper上 固件可在可复现的ESP-IDF Docker容器中构建；刷写在主机上进行，因为Windows上的Docker Desktop无法透传COM端口。 powershell ./build.ps1 # 在容器内执行 idf.py build（子命令透传） ./flash.ps1 -Port COM5 -Monitor # 从主机使用 esptool；-Monitor 可打开115200波特率的串行日志 ROM不嵌入在固件中。将Palm IIIx ROM复制到FAT32格式的SD卡上，命名为palm.rom，并在开机前插入。启动时，固件会挂载SD卡（它与电子墨水SPI总线共享），将ROM读入PSRAM，然后卸载。如果SD卡或文件缺失或无效，设备会在电子墨水屏上显示原因并停止。 #### SD卡上需要的内容 固件会读取SD卡根目录下的所有内容。仅有palm.rom是必需的，其余可选，可稍后添加。 palm.rom (必需) Palm IIIx ROM镜像，启动时读入PSRAM。 palm.cfg (可选) 屏幕布局（重新定位/旋转/放大屏幕按钮）以及串行桥接设置。 digitizer.cfg (可选) 触摸灵敏度调整。若缺失，固件会在首次启动时根据面板当前值写入一份，方便编辑。 install/ (可选) 包含.prc / .pdb / .pqa文件的目录，每次启动时安装到RAM。文件保留在原处；模拟RAM是易失性的，因此每次冷启动时都需要重新安装。 backup/ (可选) 数据库备份的目标目录。按住UP侧键一秒钟可备份到此目录；按住DOWN则还原。 若要自定义布局，请将palm.cfg.example复制到SD卡上并命名为palm.cfg，然后进行编辑。 要求：Docker Desktop，并且主机上安装有Python及esptool和pyserial（pip install esptool pyserial）。 ## 工作原理 1. CPU。 一个基于switch分派的68000解释器执行ROM，处理向量中断以及用于休眠的STOP指令。 2. 总线。 24位地址空间：2 MB RAM位于0x0，ROM窗口位于0x10C08000，DragonBall寄存器块位于0xFFFFF000，热读/写路径内联。 3. 外设。 DragonBall模型驱动中断控制器、100Hz定时器、RTC（基于真实时间）、GPIO、SPI主控（数字化仪和电池ADC）、UART以及LCD控制器（发布帧缓冲地址）。 4. 显示和输入。 1bpp帧缓冲与屏幕按钮合成后传送到面板。触摸点并非通过数字化仪硬件注入——该路径在IIIx上会导致致命错误——而是通过ROM的EvtEnqueuePenPoint系统调用排队，这是其他Palm模拟器采用的设备无关方式。 5. JIT（设备）。 热ROM块在第二个核上编译为本地代码并缓存在可执行内存中；冷代码运行内联解释器的突发模式。只编译ROM，因此无需处理自修改代码的失效问题。 ## 性能 纯解释器运行68000大约8 MHz，约为真实IIIx（16.58 MHz）的58%，性能瓶颈在于每条指令的处理工作。突发JIT可将稳定状态下的屏幕速度提升至大约真实时间的87%。剩余差距来自冷操作系统代码，这些代码执行次数太少，不值得编译，因此停留在解释器水平；缩小差距是冷路径问题，而非更多JIT优化的问题。JIT默认开启，可禁用以回退到解释器。 ## 许可证 MIT。请参见LICENSE。 Palm OS启动器在M5Paper的电子墨水屏上运行