CLI 与运行生命周期规格

1. 命令格式

macOS 或无网络启动：

./riscv_vector_emulator \
  --bios artifacts/firmware/opensbi.bin \
  --kernel artifacts/kernel/Image \
  --disk artifacts/disk/rootfs.ext4 \
  --net none

Linux TAP 网络启动：

./riscv_vector_emulator \
  --bios artifacts/firmware/opensbi.bin \
  --kernel artifacts/kernel/Image \
  --disk artifacts/disk/rootfs.ext4 \
  --net tap0

仓库文件参数示例必须使用根目录相对路径。程序可接受用户明确传入的其他路径，但不得把当前开发机器绝对路径写入默认值、日志模板或配置。

2. 必需参数

• RUN-REQ-001：--bios 指定固件。
• RUN-REQ-002：--kernel 指定内核。
• RUN-REQ-003：--disk 指定 rootfs 镜像。
• RUN-REQ-004：--net 是可选网络选择；none 关闭网络，其他非空值仅在 Linux 上解释为 TAP 接口名。省略该参数等价于 --net none。

重复参数、未知参数、缺少值和空值必须报错。程序不得在 macOS 上把任意字符串伪装成可用 TAP，也不得在省略网络参数时偷偷创建网络后端。

3. 启动校验顺序

1. 解析参数，不产生外部副作用。
2. 校验文件可读/写策略、格式、大小和相互兼容性。
3. 校验 RAM 配置与装载布局。
4. 打开并验证磁盘；仅在网络模式不是 none 时打开并验证 Linux TAP。
5. 构造机器、装载镜像和 FDT。
6. 安装资源清理保护。
7. 最后切换终端 Raw 模式。
8. 进入运行循环。

任何早期失败都应在终端仍为正常模式时报告。

4. 唯一主循环

• RUN-REQ-005：整个项目只能有一个生产执行循环。
• 在指令边界检查中断、取指、译码、执行和提交 Trap。
• 以明确策略推进 CLINT 并服务 UART/TAP/virtqueue。
• 使用非阻塞事件处理，不能让一个宿主 FD 永久阻塞 CPU；无网络档位不创建虚假网络 FD 或轮询分支。
• 支持 WFI：无事件时可阻塞等待，事件到达或计时器期限时唤醒。
• 不得通过跳过指令、伪造设备完成或直接调用宿主命令加速验收。

5. 退出与信号

Raw 模式下 Ctrl+C 交给来宾。宿主应通过文档化的转义序列、第二终端信号或其他明确机制请求退出。退出流程必须：

1. 停止接受新设备工作。
2. 完成或安全取消宿主异步操作。
3. 撤销设备中断并关闭磁盘及实际打开的 TAP FD。
4. 恢复终端属性。
5. 输出必要诊断并返回稳定退出码。

信号处理器本身只执行 async-signal-safe 操作，通过标志通知主循环清理。

6. 退出码

至少区分：成功退出、CLI 使用错误、资源/权限错误、镜像格式错误、运行期宿主 I/O 错误和模拟器内部错误。来宾关机是否视为成功必须明确；来宾普通 Trap 不应映射为宿主错误退出。

7. 日志与诊断

• 默认 UART 字节直通标准输出，诊断使用标准错误，避免污染来宾控制台流。
• 日志级别和类别明确，默认不输出每指令跟踪。
• 可选跟踪文件放在如 artifacts/logs/ 的被忽略相对目录。
• 诊断包含来宾 PC、特权级、访问类型或设备名，但不得泄露宿主无关数据。
• 日志不能作为设备行为的替代副作用。

8. 验收条件

• macOS 无网络命令和 Linux TAP 命令均可单次启动，不弹出 GUI 或交互确认框。
• 所有参数错误在产生外部状态前清楚报告。
• 持续 UART 和网络活动下 CPU、计时器均继续推进。
• 正常退出、资源失败和信号退出后终端均恢复。
• 唯一主循环由真实系统启动测试覆盖。