# xgo-lite2虚拟环境

**Repository Path**: duzc2/xgo-lite2-virtual-environment

## Basic Information

- **Project Name**: xgo-lite2虚拟环境
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-25
- **Last Updated**: 2026-10-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 树莓派 CM5 模拟运行环境 (QEMU)

> 🤖 **机器狗完全模拟**: 系统模拟器 + 3D 机体模拟器 + Canvas 头部屏幕已打通,
> Python 接口 (xgolib / edulib) 与真机一致。详见 [full-sim.md](full-sim.md),
> 一键启动: `./run-full-sim.sh` → http://localhost:8420

在 Windows 上通过 QEMU 全系统模拟运行官方 Raspberry Pi OS (arm64)，
用于在 PC 上开发和测试面向树莓派 CM5 (BCM2712) 的软件。

## 快速开始

```bash
./start-cm5.sh              # 启动虚拟机 (默认带图形窗口, 可看到屏幕)
./start-cm5.sh headless     # 无窗口模式 (纯 SSH)
./ssh-cm5.sh                # SSH 登录 (cm5 / cm5)
# 或直接: ssh -p 2222 cm5@127.0.0.1   (密码: cm5)

./run-cm5.sh                # 前台模式: 图形窗口 + 串口直显 (Ctrl+C 停止)
```

**图形窗口**: 启动后自动弹出一个 GTK 窗口显示虚拟机的屏幕（树莓派的
命令行控制台）。窗口可以观察启动过程、看运行状态。VM 的 HDMI 输出
渲染为帧缓冲显示在窗口中。

停止虚拟机: `taskkill //F //IM qemu-system-aarch64.exe`
查看启动日志: `cm5-console.log`

## 快照与还原

系统快照（备份/还原）请见 **[快照管理.md](./快照管理.md)**。

一键还原最新快照: `./restore-snapshot.sh`

## 环境规格

| 项目 | 模拟值 | CM5 实机 |
|---|---|---|
| 操作系统 | Raspberry Pi OS (Debian 13 Trixie) arm64 | 相同 |
| 内核 | 6.18.50+rpt-rpi-v8 (官方) | 相同 (2712 版) |
| CPU | 4 × Cortex-A72 | 4 × Cortex-A76 |
| 内存 | 2 GB (可用 ~960MB) | 4/8/16 GB |
| 存储 | 16 GB SD 卡 (rootfs 已扩容) | eMMC/SD |
| 网络 | usb-net (10.0.2.15, NAT, SSH 转发 2222→22) | 千兆网口 |

> **CPU 差异说明**: QEMU 尚无 BCM2712 整机模型 (无 Pi5/CM5 机器类型)，
> 本环境使用 QEMU 最接近的 `raspi4b` 机器 (BCM2711 外设集) 运行官方
> Raspberry Pi OS。CPU 指令集同为 ARMv8-A 64 位 (A72 vs A76 均为 ARMv8.2/8.0
> 兼容目标)，绝大多数用户态软件可无缝运行。若需 100% CPU 微架构一致性，
> 需等待 QEMU 上游加入 BCM2712 支持。

## 严格测试与验证

已内置两套验证工具：

```bash
# 1) 严格系统测试 (27 项, 全部通过)
node tools/ssh-run-script.js tools/strict-test.sh

# 2) Python 系统功能演示 (建立临时文件夹 + 调用系统功能)
node tools/ssh-upload-run.js tools/cm5-demo.py
```

**严格测试覆盖**: 系统身份(架构/内核/主机名)、CPU 计算(核数/数学运算/累加)、
内存、磁盘(读写/文件系统)、网络(IP/网关/DNS)、时钟、进程/系统调用、
文件系统操作(增删改查)、压缩解压、多核并发。共 27 项全部 [PASS]。

**Python 演示** 在虚拟机内建立临时文件夹 `/tmp/cm5-demo`，调用 10 类
系统功能: platform/uname、/proc/cpuinfo 与计算、/proc/meminfo、statvfs 磁盘、
socket 网络、subprocess 子进程、multiprocessing 四核并发、json 读写 + sha256、
time/perf_counter 时钟、/dev/urandom + loadavg。

## 目录结构

```
CM5/
├── start-cm5.sh          # 后台启动脚本
├── run-full-sim.sh       # 机器狗完全模拟一键启动 (见 full-sim.md)
├── full-sim.md           # 全模拟架构文档
├── xgo-lite2-emulator/   # Gitee 3D 机体模拟器 (嵌套仓库)
├── xgo-sim/              # guest 内下位机协议模拟器
├── xgo-web/              # 纯浏览器版模拟 (Pyodide, 无 QEMU)
├── run-cm5.sh            # 前台启动脚本 (串口直显)
├── ssh-cm5.sh            # SSH 快捷登录
├── cm5-console.log       # 串口日志 (启动后生成)
├── tools/
│   ├── qemu-silent/      # QEMU 11.1 便携版 (含 GTK/SDL 图形支持)
│   ├── 7zfull/           # 7-Zip (镜像维护工具)
│   ├── rebuild-initrd.js # 重建定制 initramfs
│   ├── patch-dtb.js      # DTB 结构补丁工具 (备用)
│   ├── fat-inject.js     # FAT 引导分区文件注入 (备用)
│   ├── ssh-run-script.js # 上传并执行远程脚本 (测试用)
│   ├── ssh-upload-run.js # 上传并执行 Python 脚本
│   ├── strict-test.sh    # 严格系统测试套件 (27 项)
│   ├── cm5-demo.py       # Python 系统功能演示
│   ├── boot1.js          # 旧版自动化脚本 (已废弃)
│   └── sshtool/          # Node SSH2 客户端
├── images/
│   ├── cm5-sd.img        # 16GB 虚拟 SD 卡 (主磁盘镜像)
│   ├── kernel8.img       # 官方 Pi4 arm64 内核
│   ├── bcm2711-rpi-4-b.dtb   # 补丁后设备树 (见下)
│   ├── initramfs8        # 官方 initramfs (模块部分)
│   └── initramfs8-cm5    # 定制 initramfs (实际使用)
└── downloads/            # 下载缓存 (可删除)
```

## 已做的定制 (从官方镜像到本环境的修改)

1. **设备树 (DTB) 补丁** (`bcm2711-rpi-4-b.dtb`):
   - 禁用 PM/watchdog 节点 compatible (`brcm,bcm2711-pm`→`-px`,
     `brcm,bcm2835-pm-wdt`→`-nop`): QEMU 的 powermgt 设备会把内核
     看门狗超时翻译成整机复位，导致无限重启循环
   - 启用 dwc2 USB (`usb@7e980000` status: disabled→okay): QEMU 的
     raspi4b 没有 PCIe XHCI，网络走 dwc2 上的 usb-net
2. **定制 initramfs** (`initramfs8-cm5`): 官方 initramfs (模块+主initramfs)
   合并重建，覆盖 `scripts/init-top/rpi_wd` (阻止看门狗 disarm 触发复位)、
   注入 `scripts/init-bottom/cm5setup`，每次启动自动执行:
   - 根分区 remount rw
   - 重写 /etc/fstab 为 mmcblk 路径 (QEMU 下 udev 不生成 by-partuuid 链接)
   - 创建用户 cm5 (幂等)
   - 静态 IP 配置 (usb0 = 10.0.2.15/24)
   - 屏蔽 userconfig/zram 服务
   - 启用 SSH
3. **SD 卡镜像** (`cm5-sd.img`): 官方镜像扩容至 16GB，MBR 分区表同步扩展，
   根文件系统已在线扩容至 15.5GB

## 已知限制

- **图形窗口**: GTK 窗口显示的是命令行控制台 (文本帧缓冲)，不会显示桌面
  GUI (本环境为 Lite 版无桌面)。窗口用于观察启动过程和运行状态。
- **串口只能输出**: 连接真机串口的输入不可用，交互请用 SSH
- **客户机内 `reboot` 无效**: PM 驱动被禁用 (防重启循环)，重启请用
  宿主机: `taskkill //F //IM qemu-system-aarch64.exe && ./start-cm5.sh`
- **无 GPU/视频加速**: VideoCore 未模拟，涉及 GPU 的软件不可用
- **无 GPIO**: 外设引脚不模拟
- 首次启动后用户 cm5 已创建；sudo 密码同为 cm5

## 维护提示

- **扩容/重装**: 重新下载官方镜像后按 `tools/rebuild-initrd.js` 与 DTB
  补丁流程重新构建 (补丁已在脚本中固化)
- **改 SSH 端口**: 修改 `start-cm5.sh` 中 `hostfwd=tcp::2222-:22` 的 2222
- **备份系统**: 直接复制 `images/cm5-sd.img` (停止虚拟机后)
- **登录密码修改**: `ssh-cm5.sh "passwd"` 后按提示操作