doca-devemu

DOCA Device Emulation

示例

• “从 BlueField 向主机公开自定义 PCIe 设备。” — 这属于本技能范围。选择 PCI Generic / virtio-net / virtio-fs；此处不要部署 SNAP 或 Virtio-net Service。
• “lspci 未显示我的仿真设备。” — 更改 DPU 端代码前，先确认固件仿真类型和主机驱动程序。

说明

遵循下文的加载顺序。需要配置／仿真／调试时，打开任务配套文档。需要查看子库和能力查询时，打开能力配套文档。不要打开所有配套文件。

从这里开始： 本技能假定 DOCA 已安装在主机和 BlueField 上，用户正从 DPU 端进行仿真 PCIe 设备的实际开发工作（编写后端，供主机内核驱动程序通过仿真 PCIe 接口与之通信），并且用户知道要构建哪一类仿真设备。用户想要执行某项操作（配置／构建／修改／运行／测试／调试）时，打开任务配套文档；问题是此版本 DOCA + 此代 BlueField + 此固件上的 Device Emulation 能实现什么时，打开能力配套文档。如果用户尚未安装 DOCA，请先转到 doca-setup/SKILL.md。在进行任何其他操作之前，Agent 必须引导用户选择正确的子库——DOCA Device Emulation 是一个总称，涵盖 PCI Generic（原始 PCIe 设备仿真）、virtio-net（仿真 virtio 网络设备）和 virtio-fs（仿真 virtio 文件系统设备）；每个子库都有各自的上下文、pkg-config 模块和能力范围。子库选择规则见能力配套文档。 如果用户想要的是打包解决方案，而非库（例如，“我想在主机上使用 NVMe SNAP，不想自己编写后端”或“我想要一个受管理的 virtio-net 守护进程”），请通过 doca-public-knowledge-map/SKILL.md 引导用户查看 DOCA SNAP Service / DOCA Virtio-net Service 指南 ——这些服务构建于本库之上，是不同于本技能所涵盖内容的交付物。

目标读者

本技能面向使用 DOCA Device Emulation 库构建应用程序的外部开发者——也就是说，用户的 DPU 端代码会调用 doca_devemu_pci_*、doca_devemu_virtio_* 或 doca_devemu_vfs_*（直接通过 C / C++ 调用，或通过其他语言的 FFI／绑定调用），向主机公开仿真 PCIe 设备，使主机现有的内核驱动程序能够像驱动真实 PCIe 外设一样驱动该设备。本技能不适用于为 DOCA Device Emulation 本身做贡献的 NVIDIA 开发者，也不适用于想要打包的仿真设备守护进程、且不必自行编写后端的用户（DOCA SNAP Service 和 DOCA Virtio-net Service 是构建于本库之上的打包方案）。

语言范围。 DOCA Device Emulation 以 C 库的形式提供；本技能完整涵盖三个子库。请根据用户的仿真类别选择已安装的确切 pkg-config 模块（参见能力配套文档中的子库选择表）。 /opt/mellanox/doca/samples/doca_devemu/ 下提供的示例均以 C 编写。C 和 C++ 用户是主要使用场景，任务配套文档中的示例也以此为基础。 其他语言的用户（Rust、Go、Python 等）通过 FFI 或语言专用绑定使用相同的 *.so 文件；对于此类用户，本技能将提供与语言无关的子库选择、总括生命周期、能力发现、权限和错误分类指导，并引导 Agent 将公共 C ABI 作为权威接口，因为任何封装最终都会调用该接口。

何时加载此技能

当用户使用任意语言，从 DPU 侧实际开展 DOCA Device Emulation 工作时，加载此技能。具体包括：

• 判断用户需要哪个 Device Emulation 子库（PCI Generic、 virtio-net、virtio-fs）——这个总览性的选择问题是此技能的首要关键步骤。
• 在 DPU 上初始化每个子库对应的 DOCA Core 上下文（每个仿真设备、每个子库各一个上下文），并配置主机 PCIe 驱动将与之交互的 doorbell / DMA 基元。
• 在假设某个特性位或设备属性可用之前，针对活动的 doca_devinfo，通过 doca_devemu_pci_cap_*、 doca_devemu_virtio_cap_* 或 doca_devemu_vfs_cap_* 查询系列读取各子库的能力范围。
• 选择自行使用 doca-devemu 编写后端，还是采用已封装此库的打包服务（DOCA SNAP Service / DOCA Virtio-net Service）。
• 调试 doca_devemu_* 调用返回的 DOCA_ERROR_*——尤其要区分固件级仿真类型未启用、BlueField 代际完全不支持此子库、DPU 侧进程缺少权限，以及主机侧内核驱动未绑定。
• 设计或扩展封装某个设备仿真子库的非 C 绑定（Rust、Go、Python，……）——绑定必须遵守子库选择、总览生命周期、能力发现、权限和错误分类规则。

不要在以下情况下加载此技能：一般 DOCA 入门、安装 DOCA 本身、仿真设备类别对应的主机侧内核驱动（virtio-net / virtio-blk / virtio-fs 内核驱动随主机内核提供，不属于 DOCA）、打包的 SNAP / Virtio-net 服务（它们是独立的制品，各自有服务指南），或 BlueField 数据路径上的标准 NIC 行为（请改用 doca-flow/SKILL.md + doca-eth/SKILL.md——Device Emulation 用于自定义仿真设备，而非调整 BlueField 内置 NIC 的特性）。

此技能提供的内容

这是一个轻量级加载器。正文仅保留选择下一份合适文件所需的方向性信息。Device Emulation 的实质性专属内容位于两个配套文件中：

• 能力配套文件 — 说明此版本 + 此 BlueField 代际 + 此固件能够实现哪些功能： 总体架构（主机看到的是仿真 PCIe 设备；DPU 运行后端）、子库选择规则（PCI Generic、virtio-net 或 virtio-fs）、各子库的 Core 上下文结构、连接主机 ↔ DPU 的 doorbell / DMA 基元、各子库的能力查询系列（doca_devemu_*_cap_*）、各子库的 pkg-config 模块名称、映射到跨库 DOCA_ERROR_* 集合的 Device Emulation 错误分类、可观测性接口、库与打包服务之间的路径选择规则，以及用于门控环境前提条件的安全策略（DPU 侧权限、BlueField 固件级仿真类型启用情况、BlueField 代际是否实际支持该仿真类别）。
• 任务配套文件 — 针对六个适用的 Device Emulation 动词提供分步工作流：configure、build、modify、run、test、debug。此外还有一个 Deferred task verbs 区块，将不在范围内的问题指向合适的后续技能。

此技能假定主机与 BlueField 配对环境中的两端都已在标准位置安装 DOCA，BlueField 固件已启用用户希望构建的仿真类型，用户拥有其公开安装配置所要求的权限（尤其是要执行 PCIe 级仿真，DPU 侧需要 sudo），并且主机内核已提供用户正在构建的仿真设备类别的标准驱动。此技能不涵盖安装 DOCA、更改固件级配置或安装主机侧内核驱动 — 这些操作应通过 doca-setup/SKILL.md 进行。

加载顺序

1. 首先阅读此技能，确认用户的问题属于适用范围（基于 doca-devemu 库构建自定义仿真 PCIe 设备，而非打包的 SNAP / Virtio-net 服务、主机侧内核驱动或标准 NIC 行为）。
2. 关于总体架构、子库选择规则（PCI Generic、virtio-net 或 virtio-fs）、各子库的 Core 上下文结构、doorbell / DMA 基元、各子库的能力查询规则、各子库的 pkg-config 模块、库与打包服务之间的路径选择规则、错误分类、可观测性接口和安全策略，请参阅能力配套文件。
3. 关于分步工作流 — configure、build、modify、run、test、debug — 请参阅任务配套文件。

两个配套文件彼此交叉链接；还链接到 doca-version/SKILL.md，了解权威的 DOCA 版本处理规则（并附有 Device Emulation 补充说明：所选子库的 pkg-config 模块、固件级仿真插槽以及 doca_devemu_*_cap_* 查询，都是判断“此处是否支持此仿真”的组成部分）；如果正确答案是“查阅公开的 DOCA Device Emulation 总览指南、其中链接的各子库指南、DOCA SNAP / Virtio-net Service 指南或磁盘上的安装布局”，而非“Device Emulation 专属指南”，则参阅 doca-public-knowledge-map/SKILL.md。

相关技能

• doca-public-knowledge-map/SKILL.md — 所有公开 DOCA 文档源的路由表，以及已安装 DOCA 软件包的磁盘布局。Device Emulation 总览 URL 为 https://docs.nvidia.com/doca/sdk/DOCA-Device-Emulation/index.html； 各子库指南链接在总览页面中，而打包的 DOCA SNAP / Virtio-net 服务 则作为独立构件列在 DOCA Services 总览下。
• doca-setup/SKILL.md — 环境准备、 安装验证、DPU 侧权限检查、BlueField 固件配置（包括启用各子库的 仿真类型），以及使用公开 NGC DOCA 容器的尚未安装路径。本技能假设 其前提条件均已满足，且已启用用户所选子库对应的固件级仿真类型。
• doca-version/SKILL.md — DOCA 版本处理的 规范规则。本技能的版本兼容性补充内容交叉引用四方匹配规则，并添加 Device Emulation 特有的各子库 pkg-config + doca_devemu_*_cap_* 补充规则。
• doca-structured-tools-contract/SKILL.md — 此工具包的结构化工具优先级规则（检测 / 优先使用 / 回退 / 报告）。配套任务中的命令附录遵循 此约定。
• doca-programming-guide/SKILL.md — 所有库共用的通用 DOCA 编程模式：规范的 pkg-config + meson 构建 模式、通用的先修改随附示例再创建首个应用的工作流、通用 Core 上下文 生命周期、跨库的 DOCA_ERROR_* 分类，以及程序端调试顺序。 本技能在此基础上补充 Device Emulation 的特定内容。
• doca-comch/SKILL.md — 当用户需要通过 PCIe 在主机进程与 DPU 进程之间建立控制平面通道， 但不希望主机将 DPU 识别为带有标准主机内核驱动的仿真 PCIe 设备时，应使用此库。Device Emulation 会将 DPU 隐藏在一个看似真实的 PCIe 设备类别之后；Comch 则是明确的主机 ↔ DPU IPC。
• doca-flow/SKILL.md 和 doca-eth/SKILL.md — 当用户希望在 BlueField 内置 NIC 的网络接口上整形流量，而不是暴露一个自定义的仿真 PCIe 设备时，应使用这些库。Device Emulation 用于创建主机此前无法识别的新仿真 PCIe 设备；Flow / Eth 则用于 BlueField 现有的 NIC 接口。
• doca-debug/SKILL.md — 跨领域 调试阶梯（安装 / 版本 / 构建 / 链接 / 运行时 / 程序 / 驱动）。Device Emulation 特有的调试问题（未启用固件级仿真类型、选错 子库、主机内核驱动未绑定到仿真设备、virtio 功能协商失败） 都是在此阶梯基础上的补充。