DOCA DevEmu PCI

DOCA DevEmu PCI 是 DOCA 设备模拟子系统的一部分。它提供低级软件 API，允许使用 NVIDIA® BlueField® 网络平台的模拟功能来管理模拟 PCIe 设备。

它是所有 PCIe 模拟模块的通用层，例如 DOCA DevEmu PCIe 通用模拟和 DOCA DevEmu Virtio 子系统模拟。

此库遵循 DOCA Core Context 的架构。建议事先阅读以下部分

• DOCA Core 执行模型

• DOCA Core 设备

• DOCA Core 内存子系统

通用设备模拟是 DOCA 设备模拟的一部分。建议事先阅读以下指南

• DOCA 设备模拟

DOCA DevEmu PCI 模拟仅在 BlueField 目标上受支持。BlueField 必须满足以下要求

• DOCA 版本 2.7.0 或更高版本

• BlueField-3 固件 32.41.1000 或更高版本

该库必须以 root 权限运行。

执行以下操作

1. 将 BlueField 配置为在 DPU 模式下工作，如 BlueField 工作模式 中所述。

2. 启用热插拔模拟 PCIe 设备所需的 PCIe 交换机模拟功能。这可以通过在主机或 BlueField 上运行以下命令来完成

   复制

   已复制！

               
   
               
   host/bf> sudo mlxconfig -d /dev/mst/mt41692_pciconf0 s PCI_SWITCH_EMULATION_ENABLE=1
           

3. 执行 BlueField 系统级重置，使 mlxconfig 设置生效。

为了支持热插拔功能，主机必须具有以下启动参数

• Intel CPU

  复制

  已复制！

              
  
              
  intel_iommu=on iommu=pt pci=realloc
          

• AMD CPU

  复制

  已复制！

              
  
              
  iommu=pt pci=realloc
          

这可以使用以下步骤完成

1. 添加启动参数

   复制

   已复制！

               
   
               
   host> sudo nano /etc/default/grub
   Find the variable
   GRUB_CMDLINE_LINUX_DEFAULT="<existing-params>"
   Add the params at the end
   GRUB_CMDLINE_LINUX_DEFAULT="<existing-params> intel_iommu=on iommu=pt pci=realloc"
           

2. 更新配置。

   • 对于 Ubuntu

     复制

     已复制！

                 
     
                 
     host> update-grub
             

   • 对于 RHEL

     复制

     已复制！

                 
     
                 
     host> grub2-mkconfig -o /boot/grub2/grub.cfg
             

3. 执行热启动。

4. 确认参数是否生效

   复制

   已复制！

               
   
               
   host> cat /proc/cmdline
   <existing-params> intel_iommu=on iommu=pt pci=realloc
           

DOCA DevEmu PCI 库提供 2 个主要软件抽象，PCIe 类型和 PCIe 设备。PCIe 类型表示模拟设备的配置，而 PCIe 设备表示模拟设备的实例。此外，任何 PCIe 设备实例都必须与单个 PCIe 类型关联，而 PCIe 类型可以与多个 PCIe 设备关联。

预定义 PCI 类型与通用 PCI 类型

可以通过 2 种不同的方式获取 PCIe 类型对象

• 使用现有协议的模拟库（例如 DOCA DevEmu Virtio FS 库）获取预定义类型

• 使用 DOCA DevEmu Generic 库从头开始创建

如果使用预定义类型，则类型的可配置性受到限制。

PCIe 类型名称

作为 DOCA PCIe 模拟的一部分，每个类型都有一个分配给它的名称。此属性不是 PCIe 规范的一部分，而是在 DOCA 中唯一标识 PCIe 类型的一种机制。

不能存在两个名称不同的 PCIe 类型，即使跨不同的进程也是如此，除非第二个进程中的类型以与第一个进程中相同的方式配置。此外，尝试配置具有相同名称但配置略有不同的第二种类型将失败。

创建模拟设备

在配置所需的 DOCA Devemu PCIe 类型后，可以使用 doca_devemu_pci_dev_create_rep 基于配置的类型创建模拟设备。此顺序过程确保 DOCA DevEmu PCIe 设备是使用 PCIe 类型对象指定的参数和配置创建的。此外，可以使用 doca_devemu_pci_dev_destroy_rep 销毁模拟设备。

创建的设备表示器以“power_off”状态启动，并且在用户发出热插拔序列之前对主机不可见，请参阅 热插拔模拟设备。然后，只能在“power_off”状态下销毁设备。

热插拔模拟设备

热插拔是指在系统已通电并初始化后，模拟将 PCIe 设备物理连接到主机 PCIe 子系统的过程。请注意，某些操作系统需要额外的设置才能启用 PCIe 设备的热插拔过程。对于受支持的系统，此功能对于需要在扩展其硬件资源（例如额外的存储和网络功能）的同时保持运行的系统尤其有利。DOCA DevEmu PCI 提供软件 API，允许用户以异步方式模拟此过程。

创建 PCIe 设备对象时，如果它以“power off”状态启动，则该设备对主机尚不可见。然后可以从 BlueField 热插拔设备。这将启动一个异步过程，使设备热插拔到主机。一旦过程完成，模拟设备将转换为“power on”状态，并且对主机可见。通常在此阶段，模拟设备会收到其 BDF 地址。热拔出过程以类似的异步方式工作。

使用 DOCA API，BlueField Arm 可以使用 doca_devemu_pci_dev_event_hotplug_state_change_register 注册到每个模拟设备的热插拔状态的任何更改。

模拟设备发现

模拟设备表示为 doca_devinfo_rep。可以遍历所有模拟设备，如 DOCA Core 表示器发现 中所述。

有两种方法可以过滤模拟设备列表

• 获取所有模拟设备 – 在 doca_devinfo_rep_create_list 中使用 DOCA_DEVINFO_REP_FILTER_EMULATED 作为过滤器参数

• 获取属于特定类型的所有模拟设备 – doca_devemu_pci_type_create_rep_list

对象生命周期和持久性

本节区分固件资源和软件资源

• 固件资源持续存在，直到下次电源循环，并且可以从 BlueField Arm 上的不同进程访问。一旦应用程序退出，此类资源不会被清除。

• 软件资源是固件资源的表示，并且仅与同一线程相关

使用此术语，可以将对象描述如下

• PCIe 类型对象 doca_devemu_pci_type 表示 PCIe 类型固件资源。如果满足以下任一条件，则资源将持续存在

  • 至少有 1 个进程持有对 PCIe 类型的引用

  • 至少有 1 个 PCIe 设备固件资源属于此类型

• 模拟设备表示器 doca_devinfo_rep 表示模拟 PCIe 功能固件资源

  • doca_devemu_pci_dev_create_rep 可用于创建此类固件资源

  • 要销毁固件资源，可以使用 doca_devemu_pci_dev_destroy_rep

  • 对于静态功能，表示器资源将持续存在，直到在 NVCONFIG 中配置其他设置为止

  • 要查找现有的 PCIe 设备固件资源，请使用 doca_devemu_pci_type_create_rep_list

功能级重置

创建的模拟设备支持 PCIe 功能级重置 (FLR)。

使用 DOCA API，BlueField Arm 可以使用 doca_devemu_pci_dev_event_flr_register 注册到 FLR 事件。一旦驱动程序请求 FLR，将触发此事件，并调用用户提供的回调。

一旦检测到 FLR，BlueField Arm 预计会执行以下操作

• 销毁与 PCIe 设备相关的所有资源。有关此类资源的信息，请参阅具体 PCIe 类型（通用/virtiofs）的指南。

• 停止 PCIe 设备

• 再次启动 PCIe 设备

PCIe 资源

可以查询可用 PCIe 模拟资源的数量。可以查询的资源有

• 门铃数量

• MSI-X 数量

这些资源在系统中的所有模拟设备之间全局共享，这些模拟设备是使用相同的 doca_dev 创建的。

DOCA PCIe 设备模拟需要设备才能运行。有关选择设备的信息，请参阅 DOCA Core 设备发现。

设备模拟库仅支持 BlueField-3。

由于设备功能将来可能会发生变化（请参阅 功能检查），建议用户使用以下方法选择设备

• doca_devemu_pci_cap_type_is_hotplug_supported – 用于创建和热插拔支持

• doca_devemu_pci_cap_type_is_mgmt_supported – 仅用于设备发现

配置阶段

要开始使用 DOCA DevEmu PCI 设备，用户必须首先经历一个配置阶段，如 DOCA Core Context 配置阶段 中所述。

本节介绍如何配置和启动上下文以允许检索事件。

配置

可以配置上下文以匹配应用程序用例。

要查找是否支持配置或其最小值/最大值是多少，请参阅 设备支持。

强制配置

所有强制配置都在创建 PCIe 设备期间提供。

这些配置如下

• DOCA DevEmu PCIe 类型对象

• DOCA 设备表示器，表示与提供的 PCIe 对象类型类型相同的模拟功能

• DOCA 进度引擎对象

可选配置

这些配置是可选的。如果未设置，则使用默认值

• 注册到事件，如“事件”部分中所述。默认情况下，用户不会收到事件

• PCIe 设备 ID。默认情况下，它从 PCIe 类型派生。

• PCIe 供应商 ID。默认情况下，它从 PCIe 类型派生。

• PCIe 子系统 ID。默认情况下，它从 PCIe 类型派生。

• PCIe 子系统供应商 ID。默认情况下，它从 PCIe 类型派生。

• PCIe 修订 ID。默认情况下，它从 PCIe 类型派生。

• PCIe 类代码。默认情况下，它从 PCIe 类型派生。

• MSI-X 功能的 MSI-X 向量数。默认情况下，它从 PCIe 类型派生。

执行阶段

本节介绍使用 DOCA Core 进度引擎 在 CPU 上的执行。

事件

DOCA DevEmu PCI 设备公开异步事件，以根据 DOCA Core 架构通知突然的变化。

常见事件在 DOCA Core 事件 中描述。

热插拔状态更改

热插拔状态更改事件允许用户在模拟设备的热插拔状态发生更改时接收通知。请参阅“ 热插拔模拟设备”部分。

事件配置

事件触发条件

当异步转换发生时，事件随时触发，如下所示

• DOCA_DEVEMU_PCI_HP_STATE_PLUG_IN_PROGRESS → DOCA_DEVEMU_PCI_HP_STATE_POWER_ON

• DOCA_DEVEMU_PCI_HP_STATE_UNPLUG_IN_PROGRESS → DOCA_DEVEMU_PCI_HP_STATE_POWER_OFF

• DOCA_DEVEMU_PCI_HP_STATE_POWER_ON → DOCA_DEVEMU_PCI_HP_STATE_UNPLUG_IN_PROGRESS（由主机发起时）

用户发起的任何转换都不会触发（例如，调用 hotplug 以从 POWER_OFF 转换为 PLUG_IN_PROGRESS）。

以下 API 可用于启动热插拔或热拔出转换过程

• doca_devemu_pci_dev_hotplug

• doca_devemu_pci_dev_hotunplug

事件输出

常见输出，如 DOCA Core 事件 中所述。

此外，内部缓存的热插拔状态已更新，可以使用 doca_devemu_pci_dev_get_hotplug_state 获取。

事件处理

一旦事件被触发，即表示热插拔状态已更改。应用程序预计会执行以下操作

• 使用 doca_devemu_pci_dev_get_hotplug_state 检索新的热插拔状态

功能级重置

FLR 事件允许用户在主机发起 FLR 流时接收通知。请参阅“ 功能级重置”部分。

事件配置

事件触发条件

当主机驱动程序发起 FLR 流时，事件随时触发。请参阅“功能级重置”部分。

事件输出

常见输出，如 DOCA Core 事件 中所述。

此外，内部缓存的 FLR 指示器已更新，可以使用 doca_devemu_pci_dev_is_flr 获取。

事件处理

一旦事件被触发，即表示主机驱动程序已发起 FLR 流。

用户必须通过执行以下操作来处理 FLR 流

1. 将所有未完成的请求刷新回关联的资源

2. 释放设备启动后动态创建的所有 PCIe 设备资源

3. 停止 PCIe 设备 – doca_ctx_stop

4. 再次启动 PCIe 设备 – doca_ctx_start

   • 重复调用 doca_pe_progress，直到 PCIe 设备转换为“running”状态

有关再次启动 PCIe 设备的更多信息，请参阅“状态机”部分。

状态机

DOCA DevEmu PCI 设备对象遵循上下文状态机，如 DOCA Core Context 状态机 中所述。

以下部分介绍如何转换到任何状态以及每个状态允许的操作。

空闲

在此状态下，预计应用程序将执行以下任一操作

• 销毁上下文

• 启动上下文

允许的操作

• 根据“配置”部分配置上下文

• 启动上下文

可以通过以下方式达到此状态

正在启动

在此状态下，预计应用程序将

• 调用 progress 以允许转换到下一个状态

• 将上下文保持在此状态，直到 FLR 流完成

可以通过以下方式达到此状态

正在运行

在此状态下，预计应用程序将

• 调用 progress 以接收事件

• 创建/销毁 PCIe 设备资源

可以通过以下方式达到此状态

正在停止

在此状态下，预计应用程序将

• 销毁所有模拟设备资源，如“ 功能级重置”部分中所述。

允许的操作

• 销毁 PCIe 设备资源

可以通过以下方式达到此状态