参考手册

本章是 schema、参数、版本、文件路径、GART 格式与已知问题的唯一事实源： 其他章节只解释行为，表格统一链接到这里，避免同一份数据在多个页面维护。

• 拓扑 YAML schema
• 设备适配器
• vHost 镜像配方
• 客户机参数
• 版本矩阵
• 产物、路径与源码地图
• GART 格式
• 已知问题
• 遗留 launcher 参数表

推荐阅读路径

• 第一次启动客户机、驱动没有加载：先看 客户机参数，再按症状在 已知问题 中查找。

• 编写或修改拓扑 YAML：从 拓扑 YAML schema 查字段与默认值，设备启动约定见 设备适配器，完整写法见 如何编写拓扑 YAML。

• 复现构建或排查版本差异：先查 版本矩阵，再按 产物、路径与源码地图 定位产物、日志与源码。

• 新增或审查 vHost 镜像 recipe：字段与产物规则见 vHost 镜像配方，贡献步骤见 新增 vHost 镜像配方。

• 排查 GPU 地址翻译与 GART 表：GART 格式 给出表项与寄存器格式，翻译流程见 GPU 地址翻译。

• 维护或对照遗留 shell launcher：遗留 launcher 参数表 是该路径的唯一参数表。

事实源约定

页面	拥有的内容	主要来源
拓扑 YAML schema	拓扑与 vHost 的字段、类型、默认值与上限	crates/cosim-topology/src/raw.rs、resolve.rs
设备适配器	各设备适配器的参数、argv 与就绪探测	crates/cosim-topology/src/adapter/
vHost 镜像配方	vHost 镜像 recipe 的目录、字段、输入身份与 bundle 格式	resources/images/recipe.py、identity.py、bundle.py
客户机参数	amdgpu 模块参数、ROM 写入、内核命令行、IP block mask	tests/test_modprobe_params.sh、镜像 recipe
版本矩阵	记录版本、镜像 tag 与 provenance	third_party/qemu/VERSION、recipe.toml、Cargo.toml
产物、路径与源码地图	源码目录、构建产物、会话目录、客户机文件与环境变量	仓库目录结构、crates/cosim-runtime/src/layout.rs
GART 格式	GART PTE、aperture 寄存器与典型布局	third_party/gem5/src/dev/amdgpu/amdgpu_vm.cc
已知问题	按 symptom/cause/fix 组织的问题目录	历史问题记录与驱动、模型行为
遗留 launcher 参数表	shell launcher 与 gem5 config 的修正参数表	scripts/host/cosim_launch.sh、mi300_cosim.py

相关章节

• 拓扑字段的使用方式：如何编写拓扑 YAML

• vfio-user 接口与设备模型：QEMU 作为 device model、MI300X PCI/BAR 接口

• 客户机驱动要求：客户机驱动要求

• 命令与会话生命周期：命令与选项、会话生命周期