M9B：在Tang Nano 9K FPGA上运行Doom和Descent的RISC-V计算机

m9b：在Tang Nano 9K上运行的RISC-V计算机

m9b是一台构建在Sipeed Tang Nano 9K（Gowin GW1NR-9）FPGA中的小型计算机：搭载36 MHz的VexiiRiscv CPU（带缓存）、板载8 MB封装内PSRAM、720×480 HDMI视频输出和48 kHz音频、两个用于键盘和鼠标的USB端口，以及SD卡插槽。启动后进入一个列出SD卡上程序的界面，可运行五款移植到该平台的DOS时代游戏（Ultima VII有两个引擎版本）：

所有游戏均配有音效和音乐；Ultima VII（两个引擎版本）的音乐来自Exult的Roland MT-32录音（若无这些录音，则使用The Black Gate的AdLib音乐且无音效）。音乐在PC上预先渲染或转换，并从SD卡流式播放。

本仓库将各部分整合在一起：每个部分都是独立的仓库，作为git子模块包含在此，因此请使用--recursive克隆（或之后运行git submodule update --init；make也会执行此操作）。

每个README的布局相同：该部分是什么及其状态、Sources表（构建或使用的上游项目及版本）、如何构建、工作原理，以及Changes to ...：上游代码中做了哪些修改（在那里标记为M9B）。SoC中来自其他来源的部分（VexiiRiscv、HDMI和USB主机核心、FatFs）见core/README.md的Sources部分。

其中均不包含任何游戏数据。每个游戏的data/README.md说明了所需游戏版本及应放入的内容；sdcard/README.md提供了概览。

一块 Tang Nano 9K、一个 HDMI 显示器、一张 microSD 卡（1 GB 或以上）。USB 键盘和鼠标：两个 USB-A 插座连接到排针 J5，D+ 和 D− 上各接 15 kΩ 下拉电阻（core/README.md，USB host）。串口控制台也可作为菜单操作的键盘使用。可选在 J5 上接一个 3.3 V USB 转串口适配器，用于快速上传程序（core/README.md，Serial loader）。开发板自带的 USB 串口也可以使用，但速度较慢。软件环境，在 Debian 或 Ubuntu 上：

sudo apt install make git gcc-riscv64-unknown-elf picolibc-riscv64-unknown-elf \ libstdc++-riscv64-unknown-elf-picolibc python3 openfpgaloader \ curl unzip 7zip cmake g++ ffmpeg mtools dosfstools fdisk（第二行用于 SD 卡：下载、音乐渲染和磁盘镜像。在较旧版本中 7zip 为 p7zip-full。）

FPGA 比特流使用 Gowin IDE 构建：Gowin EDA V1.9.11.03 Education，可从 Gowin 免费下载。将 GOWIN_HOME 设置为包含其 bin/gw_sh 的目录（默认 ~/gowin/IDE）。SD 卡还需要一些额外工具（见 sdcard/README.md）。仿真需要 Icarus Verilog，System Shock 和 Ultima VII 的主机测试框架需要 gcc-multilib g++-multilib。

从零开始制作一张可用的卡

git clone --recursive https://github.com/the-parts-bin/m9b-system.git cd m9b-system 将游戏数据放到对应位置：每个游戏的 data/README.md 说明了应放置的内容（符号链接可用）。Descent 和 Tyrian 无需任何操作：它们会被自动下载。例如：

cp ~/Downloads/doom19s.zip doom/data/ ln -s ~/.local/share/Steam/steamapps/common/SS1/SSHOCK sshock/data/SSHOCK ln -s path/to/ULTIMA7 exult/data/ULTIMA7 # The Black Gate ln -s path/to/SERPENT exult/data/SERPENT # Serpent Isle ln -s path/to/exult-audio exult/data/exult-audio # Exult的MT-32音色包（可选）然后

make sdcard 会构建移植版、收集数据、渲染音乐，并写入 sdcard/out/m9b-sd.img（以及 sdcard/out/card/ 中的卡内文件）。它会先检查所需工具，并跳过数据不存在的游戏。将镜像写入卡中（dd 会替换卡上所有内容：用 lsblk 确认设备名）：

sudo dd if=sdcard/out/m9b-sd.img of=/dev/sdX bs=4M conv=fsync status=progress 开发板需要将比特流和固件写入其闪存一次：

make bitstream # 生成FPGA比特流（Gowin IDE） make flash # 将比特流+固件写入开发板闪存（openFPGALoader） 插入卡并给开发板上电：启动画面会运行自检并列出程序。用方向键选择，按Enter启动。

make # 固件、五个游戏移植、板级工具（u7/：make sdcard） make bitstream # FPGA比特流（Gowin IDE） make flash # 将比特流+固件写入板载Flash（openFPGALoader） make sdcard # SD卡（sdcard/README.md；SDCARD="--doom ..."用于数据存放于其他位置） 开发过程中，core/tools/run.py PROGRAM.bin 通过串口上传程序并运行，无需操作SD卡；make sync 通过串口将板上的SD卡与 sdcard/out/card/ 同步至最新状态，仅发送有变更的内容（core/tools/sdput/sdput.py）。core/README.md 涵盖以上两项内容。每个游戏的README涵盖其构建选项、适配方式以及对上游代码的修改。

比特流已接近满载（逻辑资源约占88%，26个块RAM中使用了25个），时序余量很小：构建后请检查时序摘要（core/README.md，Clocks部分）。

每个仓库有其各自的许可证；本仓库（SD卡脚本及顶层文件）采用Apache License 2.0（LICENSE）。

游戏移植版保留其上游许可证，该许可证同样涵盖各移植版中新增的平台代码（port/、tools/）。游戏数据不在上述任何许可证的涵盖范围内，且均未包含在本仓库中。