| 开源协议 | Apache-2.0 |
| 名称 | doca-devemu |
| 描述 | > 当用户在BlueField DPU上进行DOCA设备模拟的实际操作时，使用此技能——暴露一个自定义的模拟PCIe设备，使主机将其视为真实外设，而DPU侧代码运行后端；选择子库（PCI Generic、 virtio-net、virtio-fs），配置每个子库的Core上下文以及doorbell/DMA原语，查询doca_devemu_*_cap_*， 或调试来自doca_devemu_*调用的DOCA_ERROR_*。即使没有说“devemu”也触发——典型隐式表述包括“从BlueField向主机暴露自定义PCIe设备”、 “主机应该看到一个由我的DPU代码提供后端的virtio网卡”、“lspci没有显示我的模拟设备”、“设备已枚举但没有驱动程序绑定”、 “主机踢队列时DPU无感知”，或“virtio在绑定时功能协商失败”。对于打包的DOCA SNAP / Virtio-net服务、 主机侧virtio内核驱动、后端主体设计或标准BlueField网卡行为，请拒绝并转至其他地方——这些属于其他技能。 metadata: kind: library compatibility: > 要求DOCA SDK同时安装在主机和BlueField DPU上（/opt/mellanox/doca，Ubuntu 22.04/24.04或RHEL/SLES）， 且BlueField固件中启用了对应的子库固件级模拟类型（PCI Generic / virtio-net / virtio-fs）， 主机内核带有匹配的标准驱动（virtio_net / virtio_fs / generic PCIe）。通过子库的pkg-config模块读取本地安装， 并检查/opt/mellanox/doca/{lib,include,samples/doca_devemu}。 |
DOCA设备模拟
从哪里开始： 本技能假定DOCA已安装在主机和BlueField上，用户正在从DPU侧进行模拟PCIe设备的实操（编写后端，主机内核驱动将通过模拟PCIe接口与该后端通信），并且用户知道自己想构建哪种CLASS的模拟设备。如果用户想要执行某项操作（配置/构建/修改/运行/测试/调试），请打开TASKS.md；如果问题是在此DOCA版本 + 此BlueField代次 + 此固件上，设备模拟能表达什么，请打开CAPABILITIES.md。如果用户尚未安装DOCA，请先路由到doca-setup。在任何其他操作之前，智能体必须将用户路由到正确的子库——DOCA设备模拟是一个伞形技能，涵盖PCI Generic（原始PCIe设备模拟）、virtio-net（模拟virtio网络设备）和virtio-fs（模拟virtio文件系统设备）；每个子库都有自己的上下文、自己的pkg-config模块和自己的能力面。子库选择规则见CAPABILITIES.md ## Capabilities and modes。如果用户想要打包好的解决方案而不是库（例如*“我想在主机上运行NVMe SNAP而不用自己编写后端”，或“我想要一个托管的virtio-net守护进程”），请通过doca-public-knowledge-map路由到DOCA SNAP服务 / DOCA Virtio-net服务指南——这些服务构建在本库之上*，是与本技能所覆盖内容不同的工件。
受众
本技能服务于构建使用DOCA设备模拟库的应用的外部开发者——即那些DPU侧代码直接调用doca_devemu_pci_*、doca_devemu_virtio_*或doca_devemu_vfs_*（通过C/C++，或通过来自其他语言的FFI/绑定）的用户，以向主机暴露一个模拟PCIe设备，使主机现有内核驱动可以像驱动真正的PCIe外设一样驱动它。它不是为贡献DOCA设备模拟库本身的NVIDIA开发者准备的，也不是适用于那些想要一个无需自行编写后端的打包模拟设备守护进程的用户的工件（DOCA SNAP服务和DOCA Virtio-net服务是构建在本库之上的打包选项）。
语言范围。 DOCA设备模拟以C库形式提供；本技能端到端地涵盖三个子库。为用户选择的模拟类别选择精确安装的pkg-config模块（参见CAPABILITIES.md ## Capabilities and modes中的子库选择表）。/opt/mellanox/doca/samples/doca_devemu/下的示例用C编写。C和C++用户是典型场景，TASKS.md中的示例假定这一路径。其他语言用户（Rust、Go、Python等）通过FFI或语言特定绑定消费相同的*.so文件；在这种情况下，技能的贡献在于保持子库选择、伞形生命周期、能力发现、权限和错误分类指南的语言中立性，并将智能体路由到公共C ABI作为任何包装器最终调用的权威接口。
何时加载此技能
当用户在DPU侧以任何语言进行DOCA设备模拟实操时，加载此技能。具体来说：
- 决定用户需要哪个设备模拟子库（PCI Generic、virtio-net、virtio-fs）——伞形选择问题是本技能承重的第一步。
- 在DPU上初始化每个子库的DOCA Core上下文（每个子库的每个模拟设备一个上下文），并配置主机PCIe驱动将与之交互的doorbell/DMA原语。
- 在假设特定功能位或设备特性可用之前，通过
doca_devemu_pci_cap_*、doca_devemu_virtio_cap_*或doca_devemu_vfs_cap_*查询族，针对活跃的doca_devinfo读取每个子库的能力面。 - 决定是自己使用
doca-devemu编写后端，还是采用已封装本库的打包服务（DOCA SNAP服务 / DOCA Virtio-net服务）。 - 调试从
doca_devemu_*调用返回的DOCA_ERROR_*——特别是区分固件级模拟类型未启用、该BlueField代次根本不支持此子库、DPU侧进程缺少权限与主机侧内核驱动程序未绑定。 - 设计或扩展包装设备模拟子库之一的非C绑定（Rust、Go、Python等）——为了包装器必须遵守的子库选择、伞形生命周期、能力发现、权限和错误分类规则。
不要将本技能用于：一般DOCA入门、DOCA本身的安装、模拟设备类的主机侧内核驱动（virtio-net / virtio-blk / virtio-fs内核驱动随主机内核提供，不属于DOCA）、打包的SNAP/Virtio-net服务（它们是带有各自服务指南的独立工件），或BlueField数据路径上的标准网卡行为（应使用doca-flow + doca-eth —— 设备模拟用于自定义模拟设备，而非塑造BlueField内置NIC特性）。
本技能提供的内容
这是一个瘦加载器。正文只保留选择正确下一个文件所需的定向信息。实质性的设备模拟特定材料位于两个附带文件中：
CAPABILITIES.md—— 在此版本 + 此BlueField代次 + 此固件上设备模拟能表达什么：伞形架构（主机看到一个模拟PCIe设备；DPU运行后端）、子库选择规则（PCI Generic vs virtio-net vs virtio-fs）、每子库Core上下文形状、桥接主机↔DPU的doorbell/DMA原语、每子库能力查询族（doca_devemu_*_cap_*）、每子库pkg-config模块名称、设备模拟错误分类映射到跨库DOCA_ERROR_*集合、可观测性面、库与打包服务的路径选择规则，以及控制环境前置条件的安全策略（DPU侧权限、BlueField固件级模拟类型启用、BlueField代次实际支持该模拟类别）。TASKS.md—— 六个范围内的设备模拟动词的分步工作流：configure、build、modify、run、test、debug。外加一个Deferred task verbs块，将范围外的问题指向正确的下一个技能。
该技能假定一个主机+BlueField配对，DOCA已按标准位置安装在两侧，BlueField固件已启用用户想构建的模拟类型，用户拥有其公开安装配置所预期的权限（特别是在DPU侧拥有sudo以执行PCIe级模拟），并且主机内核带有用户正在构建的模拟设备类的标准驱动。它不包括安装DOCA、切换固件级配置或安装主机侧内核驱动程序——这些路径通过doca-setup处理。
加载顺序
- 首先阅读此
SKILL.md以确认用户的问题在范围内（基于doca-devemu库的自定义模拟PCIe设备，而不是打包的SNAP / Virtio-net服务，不是主机侧内核驱动，不是标准NIC行为）。 - 有关伞形架构、子库选择规则（PCI Generic vs virtio-net vs virtio-fs）、每子库Core上下文形状、doorbell/DMA原语、每子库能力查询规则、每子库
pkg-config模块、库与打包服务的路径选择规则、错误分类、可观测性面和安全策略，请参阅CAPABILITIES.md。 - 有关逐步工作流——configure、build、modify、run、test、debug——请参阅TASKS.md。
两个附带文件相互交叉链接；关于规范DOCA版本处理规则，请参阅doca-version（包含设备模拟叠加：所选子库的pkg-config模块、固件级模拟槽和doca_devemu_*_cap_*查询都是*“此模拟在此是否受支持”*的一部分）；每当正确答案是“在公共DOCA设备模拟伞形指南、其链接的每个子库指南、DOCA SNAP / Virtio-net服务指南或磁盘安装布局中查找”，而不是“设备模拟特定指导”时，请参阅doca-public-knowledge-map。