DOCA DevEmu Virtio-FS

DOCA DevEmu Virtio-FS 库是 DOCA DevEmu Virtio 子系统的一部分。它提供低级软件 API，为使用 NVIDIA® BlueField® DPU 的设备仿真功能开发和操作 virtio 文件系统设备提供构建块。

DOCA 支持通过 PCIe 总线仿真 virtio-FS 设备。PCIe 传输是 virtio 设备常用的传输方式。与 PCIe 相关的配置、发现和特性（例如，MSI-X 和 PCIe 设备热插拔/拔出）通过 DOCA DevEmu PCI API 进行管理。配置通用 virtio 寄存器和处理通用 virtio 逻辑（例如，virtio 设备重置流程）由 DOCA Virtio 通用库处理。这种模块化设计使 DOCA 设备仿真子系统中的每一层都能够管理自己的业务逻辑。它有助于与其他层无缝集成，确保整个系统中独立的功能和操作。

DOCA Devemu Virtio-FS 库有效地处理 virtio 描述符，这些描述符携带设备驱动程序发送的 FUSE 请求，并将它们转换为抽象的 virtio-FS 请求，然后路由给用户。此转换过程确保底层设备特定的加速细节被抽象化，允许应用程序与抽象的 virtio-FS 请求进行交互。

此库的用户负责开发 virtio-FS 控制器，该控制器管理底层的 DOCA Devemu Virtio-FS 设备以及 DOCA 范围之外的外部后端文件系统。控制器应用程序旨在接收 DOCA Virtio-FS 请求，并根据 virtio-FS 和 FUSE 规范处理它们，将基于 FUSE 的命令转换为适当的后端文件系统协议。

Virtio-FS 设备仿真是 DOCA DevEmu Virtio 子系统的一部分。因此，建议在继续之前阅读以下指南

• DOCA 设备仿真

• DOCA DevEmu PCI

• DOCA DevEmu Virtio

DOCA DevEmu Virtio-FS 仅在 BlueField 目标上受支持。BlueField 必须满足以下要求

• DOCA 版本 2.7.0 或更高版本

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

执行以下操作

1. 按照 BlueField 工作模式 中的描述，配置 BlueField 在 DPU 模式下工作。

2. 通过在主机或 DPU 上运行以下命令来启用仿真

   复制

   已复制!

               
   
               
   host/dpu> sudo mlxconfig -d /dev/mst/mt41692_pciconf0 s VIRTIO_FS_EMULATION_ENABLE=1
           

3. 配置静态 virtio-FS 物理功能的数量以及每个物理功能要公开的 MSIX 数量。这可以通过在 DPU 上运行以下命令来完成

   复制

   已复制!

               
   
               
   host/dpu> sudo mlxconfig -d /dev/mst/mt41692_pciconf0 s VIRTIO_FS_EMULATION_NUM_PF=2 VIRTIO_FS_EMULATION_NUM_MSIX=18
           

4. 执行 BlueField 系统重启，使 mlxconfig 设置生效。

热插拔

主机配置

在主机操作系统上的 Linux 环境中，需要额外的内核启动参数来支持热插拔功能

• 对于 Intel 机器

  复制

  已复制!

              
  
              
  intel_iommu=on iommu=pt pci=realloc
          

• 对于 AMD 机器

  复制

  已复制!

              
  
              
  iommu=pt pci=realloc
          

  注意

  在 AMD 机器上，热插拔可能无法工作。

固件配置

当启用 PCIe 交换机仿真时，BlueField 可以支持 1 个热插拔 virtio-fs 功能。这些 PCIe 功能在所有 BlueField 用户和应用程序之间共享，并且可以容纳 NVMe、virtio-blk、virtio-fs 或其他类型（例如，virtio-net）的热插拔设备。

要启用 PCIe 交换机仿真并配置一个热插拔端口，请运行

            

            
[dpu] mlxconfig -d /dev/mst/mt41692_pciconf0 s PCI_SWITCH_EMULATION_ENABLE=1 PCI_SWITCH_EMULATION_NUM_PORT=2
        

PCI_SWITCH_EMULATION_NUM_PORT 等于 1 加上热插拔 PCIe 功能的数量。

DOCA DevEmu Virtio-FS 库提供以下主要软件抽象

• virtio-FS 类型 – 扩展了 virtio 类型；表示仿真 virtio-FS 设备的通用/默认 virtio-FS 配置

• virtio-FS 设备 – 扩展了 virtio 设备；表示仿真 virtio-FS 设备的实例

• virtio-FS IO 上下文 – 扩展了 virtio IO 上下文；表示负责处理 virtio 描述符、携带 FUSE 请求及其关联的 virtio 队列（例如，hiprio、请求、管理和通知队列）的进度上下文。

• virtio-FS 请求

Virtio-FS 特性位

根据 virtio 规范，virtio-FS 设备可以报告对 VIRTIO_FS_F_NOTIFICATION 的支持，这表示能够处理通过通知队列发送的 FUSE 通知消息。

Virtio-FS 配置布局

根据 virtio 规范，virtio-FS 配置结构布局如下

            

            
struct virtio_fs_config {
	char tag[36];
	le32 num_request_queues;
	le32 notify_buf_size;
};
        

tag 和 num_request_queues 字段始终可用。notify_buf_size 字段仅在设置 VIRTIO_FS_F_NOTIFICATION 时可用。

Virtio-FS 类型

virtio-FS 类型扩展了 virtio 类型，并描述了仿真 virtio-FS 设备的通用/默认配置，包括一些 virtio-FS 配置空间寄存器（例如，num_request_queues ）。

目前，virtio-FS 类型是只读的（即，只有 getter API 可用于检索信息）。以下方法可用于此目的

• doca_devemu_vfs_type_get_num_request_queues – 获取关联的 virtio-FS 设备的 num_request_queues 寄存器的默认初始值

DOCA 支持默认 virtio-FS 类型。要检索默认 virtio-FS 类型，用户可以使用以下方法

• doca_devemu_vfs_is_default_vfs_type_supported – 检查设备是否支持默认 DOCA Virtio-FS 类型。如果支持

  • doca_dev_open – 打开受支持的 DOCA 设备

  • doca_devemu_vfs_find_default_vfs_type_by_dev – 获取与设备关联的默认 DOCA Virtio-FS 类型

Virtio-FS 设备

virtio-FS 设备扩展了 virtio 设备。在使用 DOCA DevEmu Virtio-FS 设备之前，建议阅读 DOCA DevEmu Virtio 设备、DOCA DevEmu PCI 设备 和 DOCA Core 上下文配置阶段 的指南。

本节介绍如何创建、配置和操作 virtio-FS 设备。

Virtio-FS 设备配置

从主机的角度来看，仿真的 virtio-FS 设备可能处于几个不同的可见性级别

• 对 PCIe 子系统可见/不可见 – 如果设备对 PCIe 子系统可见，则用户无法配置与 PCIe 相关的参数（例如，MSI-X 向量数、subsystem_id）。

• 对 virtio 子系统可见/不可见 – 如果设备对 virtio 子系统可见，则用户将无法配置与 virtio 相关的参数（例如，队列数、queue_size）。

创建和配置 virtio-FS 设备的流程如下

1. doca_devemu_vfs_dev_create – 创建新的 DOCA DevEmu Virtio-FS 设备实例。

2. doca_devemu_vfs_dev_set_tag – 根据 virtio 规范为设备设置唯一标签。

3. doca_devemu_vfs_dev_set_num_request_queues – 设置设备的请求队列数。

4. doca_devemu_vfs_dev_set_vfs_req_user_data_size – 设置 virtio-FS 请求的用户数据大小。如果设置，则会代表用户为每个 DOCA DevEmu Virtio-FS 分配具有此大小的缓冲区。

5. 按照 DOCA Virtio 配置 中的描述配置与 virtio 相关的参数。

   注意

   doca_devemu_virtio_dev_set_num_queues 应等于请求队列数 +1（对于 hiprio 队列），因为 DOCA 目前不支持 virtio-FS 通知队列。

6. 按照 DOCA DevEmu PCI 配置 中的描述配置与 PCIe 相关的参数。

7. doca_ctx_start – 启动 virtio-FS 设备上下文以完成配置阶段。

   • virtio-FS 设备对象遵循 DOCA Core 上下文状态机 中描述的 DOCA 上下文状态机

   • virtio-FS 设备上下文在初始数量的 virtio IO 上下文绑定到它之后移动到 running 状态，并转换为 running 状态，如 DOCA DevEmu Virtio 配置 中所述

此时，DOCA Devemu Virtio-FS 上下文已完全可操作。

强制配置

以下是强制配置

• doca_devemu_vfs_dev_set_tag – 为设备设置唯一标签

可选配置

可选配置如下

• doca_devemu_vfs_dev_set_num_request_queues – 设置设备的请求队列数。如果未设置，则默认值取自 virtio-FS 类型配置。

• doca_devemu_vfs_dev_set_vfs_req_user_data_size – 设置 virtio-FS 请求的用户数据大小。如果未设置，则用户数据大小默认为 0。

Virtio-FS 设备事件

DOCA DevEmu Virtio-FS 设备公开异步事件，以根据 DOCA Core 架构通知突然发生的更改。

常见事件在 DOCA DevEmu Virtio 设备事件、DOCA DevEmu PCI 设备事件 和 DOCA Core 事件 中描述。

Virtio-FS IO

virtio-FS IO 上下文扩展了 Virtio IO 上下文。要开始使用 DOCA DevEmu Virtio-FS IO，建议阅读 DOCA DevEmu Virtio IO 和 DOCA Core 上下文配置阶段 的指南。

本节介绍如何创建、配置和操作 virtio-FS IO 上下文。

Virtio-FS IO 配置

创建和配置 virtio-FS IO 上下文的流程应如下所示

1. doca_devemu_vfs_io_create – 创建新的 DOCA DevEmu Virtio-FS IO 实例。

2. doca_devemu_vfs_io_event_vfs_req_notice_register – 注册传入 virtio-FS 请求的事件处理程序。

3. doca_ctx_start – 启动 virtio-FS IO 上下文以完成配置阶段。virtio-FS IO 对象遵循 DOCA Core 上下文状态机。virtio-FS 设备上下文在初始数量的 virtio-FS IO 上下文绑定到它之后移动到 running 状态，并移动到 running 状态（如 DOCA DevEmu Virtio 配置 中所述）。

强制配置

以下是强制配置

• doca_devemu_vfs_io_event_vfs_req_notice_register – 注册传入 virtio-FS 请求的事件处理程序是强制性的

Virtio-FS 请求

virtio-FS 请求对象用作处理 virtio-FS 队列（包括高优先级、请求或通知队列）上到达的请求的抽象。这些请求最初由设备驱动程序通过创建的 virtio 队列生成，然后通过注册的事件处理程序（使用 doca_devemu_vfs_io_event_vfs_req_notice_register 设置）路由给用户，该处理程序在关联的 virtio IO 上下文上设置。此事件处理程序由 DOCA Virtio FS 库发布，确保用户可以在其应用程序中有效接收和处理 virtio-FS 请求。一旦调用事件处理程序，virtio-FS 请求和关联的请求用户数据的所有权将转移给用户。请求所有权在用户通过调用 doca_devemu_vfs_req_complete 完成请求后，移回关联的 virtio IO 上下文。

以下 API 操作 virtio-FS 请求

1. doca_devemu_vfs_req_get_datain – 获取表示 virtio-FS 请求的 data-in 的 DOCA 缓冲区。此 DOCA 缓冲区表示根据 virtio 规范的请求的设备可读部分的host内存。

2. doca_devemu_vfs_req_get_dataout – 获取表示 virtio-FS 请求的 data-out 的 DOCA 缓冲区。此 DOCA 缓冲区表示根据 virtio 规范的请求的设备可写部分的host内存。

3. doca_devemu_vfs_req_complete – 完成 virtio-FS 请求。关联的 virtio-FS IO 上下文根据 virtio-FS 规范完成对设备驱动程序的请求。

仿真的 virtio-FS PCIe 功能由 doca_devinfo_rep 表示。要找到用作 doca_devemu_vfs_dev_create 的输入参数的合适 doca_devinfo_rep，用户应首先使用以下命令发现现有设备表示器

1. doca_devinfo_create_list – 获取所有 DOCA 设备的列表。

2. doca_devemu_vfs_is_default_vfs_type_supported – 检查设备是否可以管理与 virtio-FS 类型关联的设备。

3. 如果支持

   1. doca_dev_open – 获取可用作 virtio-FS 仿真管理器的 DOCA 设备的实例。

   2. doca_devemu_vfs_find_default_vfs_type_by_dev – 获取默认 virtio-FS 设备类型。

   3. doca_devemu_vfs_type_as_pci_type – 将 virtio-FS 类型转换为 PCIe 类型。

   4. doca_devemu_pci_type_rep_list_create – 为 virtio-FS 类型创建所有可用表示器设备的列表。

4. 此时，用户可以选择首选的表示器设备，使用 doca_dev_rep_open 打开它，然后继续执行“Virtio-FS 设备配置”部分中描述的流程。

本节介绍 DOCA DevEmu Virtio-FS 设备和一个或多个 DOCA DevEmu Virtio-FS IO 上下文（在此示例中为 4 个）的初始化流程。在此过程中，用户在开始接收控制路径事件（来自 virtio-FS 设备上下文）和 IO 请求（来自 virtio-FS IO 上下文）之前，设置并准备环境。在初始化期间，用户应配置各种基本组件以确保行为正确。

用户应执行以下操作

1. 选择 4 个 Arm 内核来运行应用程序线程。

2. 创建 4 个 DOCA Core 进度引擎 (PE) 对象（pe1、pe2 、pe3 、pe4 ）。

3. 根据 发现 流程或任何其他方法，找到合适的表示器设备。

4. 根据 virtio-FS 设备 配置流程 创建、配置和启动新的 virtio-FS 设备。假设 pe1 与 virtio-FS 设备关联，并且 doca_devemu_virtio_dev_set_num_required_running_virtio_io_ctxs 设置为 4。

5. 根据 virtio-FS IO 配置流程 创建、配置和启动 4 个新的 virtio-FS IO 上下文。假设 pe1、pe2 、pe3 和 pe4 分别与 4 个 virtio-FS IO 上下文中的每一个关联。

6. 此时，4 个 virtio-FS IO 上下文转换为 running 状态，然后 virtio-FS 设备上下文转换为 running 状态。

本节介绍 DOCA DevEmu Virtio-FS 设备和一个或多个 DOCA DevEmu Virtio-FS IO 上下文（在此示例中为 4 个）的拆卸流程。在此过程中，用户清理在初始化流程中分配的所有资源以及所有未完成的事件和请求。

用户应执行以下操作

1. 通过调用 doca_ctx_stop 启动拆卸流程。这会导致 DOCA Virtio-FS 设备上下文转换为 stopping 状态。保证在此状态下不会生成 virtio/PCIe 控制路径事件。

2. 为任何 DOCA Virtio-FS IO 上下文调用 doca_ctx_stop。这会导致 DOCA Virtio-FS IO 上下文转换为 stopping 状态。保证在此状态下不会生成 IO 路径事件。

3. 通过调用 doca_devemu_vfs_req_complete 将所有未完成的 virtio-FS 请求刷新到关联的 virtio-FS IO 上下文。在完成与 virtio-FS IO 上下文关联的所有请求后，DOCA Virtio-FS IO 上下文转换为 idle 状态。

4. 此时，可以安全地通过调用 doca_devemu_vfs_io_destroy 销毁 virtio-FS IO 上下文。销毁未处于 idle 状态的 virtio-FS IO 上下文将失败。

5. 一旦与 virtio-FS 设备关联的所有 4 个 virtio-FS IO 上下文转换为 idle 状态，DOCA Virtio-FS 设备上下文也转换为 idle 状态。

6. 此时，可以安全地通过调用 doca_devemu_vfs_dev_destroy 销毁 virtio-FS 设备上下文。销毁未处于 idle 状态的 virtio-FS 设备上下文将失败。

本节介绍如何使用多个 DOCA Core PE 对象（每个内核一个）在 BlueField Arm 内核上执行

1. 选择 4 个 Arm 内核来运行应用程序线程。

2. 创建 4 个 DOCA Core PE 对象。应用程序线程应定期调用 doca_pe_progress 以推进与 PE 关联的所有 DOCA 上下文。

3. 创建、配置和启动 DOCA Virtio-FS 设备。

4. 创建、配置和启动 4 个 DOCA Virtio-FS IO 上下文。

DOCA Virtio-FS 对象的进度如下图所示

控制路径

DOCA Virtio-FS 设备上下文扩展了 DOCA Virtio 设备上下文（后者扩展了 DOCA PCIe 设备上下文）。这意味着 DOCA Virtio-FS 设备控制路径由其扩展的所有对象组成（即，DOCA 上下文、DOCA DevEmu PCI 设备和 DOCA DevEmu Virtio 设备）。

virtio-FS 设备上下文可以触发以下事件

• DOCA 上下文状态更改事件，如 DOCA Core 上下文状态机 和 DOCA DevEmu PCI 状态机 中所述

• DOCA DevEmu PCI FLR 流程

• DOCA DevEmu Virtio 重置流程

DOCA Virtio-FS IO 上下文扩展了 DOCA Virtio IO 上下文（后者扩展了 DOCA core 上下文）。这意味着 DOCA Virtio-FS IO 上下文控制路径由其扩展的所有对象组成（即，DOCA 上下文和 DOCA DevEmu Virtio IO）。

Virtio-FS IO 上下文可以触发以下事件

• DOCA 上下文状态更改事件，如 DOCA Core 上下文状态机 中所述

除了控制路径事件外，DOCA DevEmu Virtio-FS IO 上下文还会生成 IO 路径事件，如 IO 路径 中所述。

IO 路径

本节介绍从设备驱动程序发送单个 virtio-FS 请求到其完成的流程。

假设用户已正确配置传入 virtio-FS 请求的事件处理程序，如“Virtio-FS IO 配置”部分中所述。

还假设用户熟悉 virtio-FS 规范，并且能够使用 DOCA DMA 或任何其他合适的方法执行与主机的 DMA 操作。

DOCA virtio-FS 流程如下图所示