DOCA Comch

本指南提供关于构建和开发需要在 x86 主机和 BlueField Arm 核心之间建立通信通道的应用的说明。

DOCA Comch 在主机上的客户端应用程序和 BlueField Arm 上的服务器之间提供通信通道。它引入了诸如通过消费者-生产者 API 的高性能数据路径，以及使用 DOCA 进度引擎和其他标准 DOCA Core 对象等功能。

使用 DOCA Comch 的优势

• 安全性 – 通信通道与网络隔离

• 网络独立性 – 通信通道的状态不依赖于网络的状态和配置

• 易于使用

DOCA Comch 提供两种不同的数据路径 API

• 用于控制消息的基本 DOCA Comch 发送/接收

• 高带宽、低延迟、零拷贝、多生产者、多消费者 API

下表总结了两种数据路径 API 之间的差异

此库遵循 DOCA Core Context 的架构，建议在之前阅读以下章节

• DOCA Core 执行模型

• DOCA Core 设备

• DOCA Core 内存子系统（仅限快速路径）

不适用

基于 DOCA Comch 的应用程序可以运行在主机或 NVIDIA BlueField Arm 上。

主机和 BlueField Arm 之间的消息发送只能在配置了 BlueField 操作模式 中描述的模式的 BlueField 上运行。

对于基本的 DOCA Comch 发送和接收，需要以下配置

• doca_comch_server 上下文必须在 BlueField Arm 核心上运行

• doca_comch_client 上下文必须在主机上运行

DOCA Comch 由四个 DOCA Core 上下文 组成。所有 DOCA Comch 上下文都利用 DOCA Core 架构来公开异步任务/事件，这些任务/事件被卸载到硬件。

doca_comch_server 上下文在 BlueField Arm 上运行，并侦听来自主机的传入连接。此类主机侧连接由 doca_comch_client 上下文启动。

服务器可以并行接收来自多个客户端的连接，但是，客户端只能与一个服务器连接。客户端和服务器之间已建立的 1 对 1 连接由 doca_comch_connection 表示。

一旦客户端和服务器之间存在已建立的连接，就可以使用 doca_comch_producer 和 doca_comch_consumer 上下文来运行快速路径通道。

下图提供了上下文用法的示例

对象

安全注意事项

• DOCA Comch 保证

  • 客户端通过在客户端提供确切的服务器名称来连接到服务器

  • 只有由服务器创建时提供的 doca_dev_rep 表示的 PF/VF/SF 上的客户端才能连接到服务器

  • 连接请求和数据路径与网络隔离

• DOCA Comch 不在应用程序级别提供安全性

  • 用户有责任实施应用程序级别的安全性并验证客户端应用程序的身份

  • 服务器处理来自单个 PF/VF/SF 的应用程序。如果服务器应用程序检测到受损的客户端应用程序，则服务器应用程序应认为所有客户端（来自该 PF/VF/SF）都已受损。

初始化流程

doca_comch_server 初始化流程

1. doca_comch_server 是在特定的 doca_dev 和特定的 doca_dev_rep 上创建的。

2. 每个 doca_dev/doca_dev_rep 的 doca_comch_server 必须具有唯一的名称（即，同一 doca_dev 和 doca_dev_rep 上的两个服务器不能具有相同的名称）。

3. 一旦调用 doca_ctx_start()，doca_comch_server 就可以开始接收新的连接请求。

4. 为了使 doca_comch_server 处理新的连接请求和消息，用户必须定期调用 doca_pe_progress()。

5. 当新的连接请求到达时，doca_comch_server 调用连接请求处理程序函数并传递 doca_comch_connection 对象。

服务器现在可以在由 doca_comch_connection 表示的连接上发送和接收消息。

doca_comch_client 初始化流程

1. doca_comch_client 是在特定的 doca_dev 上创建的，目标是特定的 doca_comch_server。

2. 一旦调用 doca_ctx_start()，doca_comch_client 异步尝试连接到服务器。

3. 为了建立连接并接收消息，用户必须定期调用 doca_pe_progress()。

4. 当连接建立时，doca_comch_client 调用状态更改回调，指示状态更改为“RUNNING”。

客户端现在可以发送接收消息。

下图描述了 DOCA Comch 上基本客户端/服务器连接的初始化

doca_comch_consumer 初始化流程

1. doca_comch_consumer 是在特定的 doca_comch_connection 上创建的。

2. doca_pe_progress() 必须在客户端/服务器 PE 上定期调用，以允许注册消费者。

3. 在 doca_comch_consumer 移动到“RUNNING”状态之后

   1. doca_comch_consumer 将其存在通知给对等方（调用新的消费者事件）。

   2. 应用程序可以开始发布接收任务。

   3. 对等方上的 doca_comch_producer 可以开始向该消费者发送消息。

初始化流程在下图中描述

拆卸流程

拆卸流程必须按以下顺序执行，否则可能会发生错误。

断开特定连接

特定连接的正确断开过程包括以下步骤

1. 停止所有链接到连接的消费者和生产者。

2. 服务器/客户端

   1. 对于服务器，可以使用 doca_comch_server_disconnect() 断开连接。如果连接有任何活动的生产者/消费者，则断开连接将失败。断开连接会通知客户端并启动客户端的拆卸。

   2. 对于客户端，由于在任何给定时间只有一个连接，因此可以通过调用 doca_ctx_stop() 来断开连接。如果存在任何活动的生产者/消费者，则命令将失败。停止客户端上下文会通知服务器断开连接，并导致服务器端连接断开。

拆卸 DOCA Comch

DOCA Comch 上下文的正确拆卸包括以下内容

1. 停止所有链接到上下文的消费者和生产者。

2. 调用 doca_ctx_stop()。如果存在任何活动的连接，它们都将被断开连接。如果存在任何活动的消费者/生产者，则命令将失败。断开连接/停止上下文会通知所有活动的对等方断开连接，并导致拆卸（在客户端上）或断开连接（在服务器上）。成功调用 doca_ctx_stop() 会将上下文移动到“停止中”状态。

3. 在移动到停止状态后，必须调用 doca_pe_progress()，直到上下文移动到空闲状态。

MsgQ（DPA 通信）

DOCA Comch MsgQ 利用现有的消费者/生产者模型，以允许主机/BlueField 和 DPA 之间的通信。

由于主机/BlueField 和 DPA 之间的通信是本地的，因此无需创建服务器、客户端或连接。相反，用户可以创建一个 MsgQ 并使用它直接创建生产者和消费者。

当使用 MsgQ 创建消费者/生产者时，可以在 DPA 应用程序以及 CPU 应用程序中使用它们

• CPU 应用程序可以利用现有的消费者/生产者 API 进行通信

• DPA 应用程序有一组不同的 API，可以在 DPA 应用程序中使用

通信方向

MsgQ 的每个实例只能支持单个通信方向，如下所示

• 从主机/BlueField 到 DPA 的通信

  • 可以使用 doca_comch_msgq_set_dpa_consumer 指定此方向

  • 从此 MsgQ 创建的消费者称为 DPA 消费者，而生产者是 CPU 生产者

• 从 DPA 到主机/BlueField 的通信

  • 可以使用 doca_comch_msgq_set_dpa_producer 指定此方向

  • 从此 MsgQ 创建的消费者称为 CPU 消费者，而生产者是 DPA 生产者

为了在应用程序中支持双向通信，用户必须创建 2 个 MsgQ 实例，如上述 图 所示。

要开始使用该库，用户必须经历一个配置阶段，如 DOCA Core 上下文配置阶段 中所述。

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

配置

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

要了解是否支持特定配置，或其最小/最大值是多少，请参阅 设备支持。

强制配置

这些配置是强制性的，必须由应用程序在尝试启动上下文之前设置

• 对于基本发送/接收客户端或服务器

  • 发送任务回调

  • 接收事件回调

  • 必须在创建时提供具有适当支持的设备

  • 必须在创建时提供有效的服务器名称（对于客户端，这是要连接的服务器）

  • 连接事件回调（仅限服务器）

• 对于快速路径生产者或消费者

  • 必须在创建时提供具有适当支持的设备

  • 必须在创建时提供已建立的客户端到服务器连接

  • 必须在创建时提供具有 PCIe 读/写权限的 doca_mmap，数据应接收到该位置（仅限消费者）

  • 发布接收任务回调（仅限消费者）

  • 发送任务回调（仅限生产者）

  • 新的消费者回调（在创建/销毁远程消费者时触发）

• 对于 MsgQ 快速路径生产者或消费者

  • 必须在创建时提供已启动的 MsgQ

  • 必须提供 DPA 实例（仅限 DPA 消费者/生产者）

  • 必须连接 DPA 消费者完成上下文（仅限 DPA 消费者）

  • 必须附加 DPA 完成上下文（仅限 DPA 生产者）

  • 发布接收任务回调（仅限 CPU 消费者）

  • 接收操作的数量（仅限 DPA 消费者）

  • 发送任务回调（仅限 CPU 生产者）

  • 发送操作的数量（仅限 DPA 生产者）

可选配置

以下配置是可选的，如果未设置，则将使用默认值

对于基本发送/接收客户端

• doca_comch_(server|client)_set_max_msg_size – 设置可以发送的最大消息大小。如果设置，则服务器和客户端之间必须匹配。

• doca_comch_(server|client)_set_recv_queue_size – 设置接收新消息的队列大小

对于快速路径消费者

• doca_comch_consumer_set_imm_data_len – 设置消费者可以接收的立即数据长度。

设备支持

DOCA Comch 需要设备才能运行。有关选择设备的说明，请参阅 DOCA Core 设备发现。

由于设备功能可能会发生变化（请参阅 DOCA Core 设备支持），建议使用以下方法选择设备

• 对于基本客户端和服务器

  • doca_comch_cap_server_is_supported

  • doca_comch_cap_client_is_supported

• 对于扩展的快速路径功能

  • doca_comch_producer_cap_is_supported

  • doca_comch_consumer_cap_is_supported

某些设备可能允许不同的功能，如下所示

• 最大服务器名称长度

• 最大消息大小

• 最大接收队列长度

• 可以连接到服务器的最大客户端数

• 最大发送任务数或发布接收任务数

• 快速路径的最大缓冲区长度

• 快速路径消费者支持的最大立即数据

缓冲区支持

客户端和服务器之间的基本发送和接收不使用 DOCA 缓冲区，因此对缓冲区类型没有限制。

• 对于生产者，提供的缓冲区只需要来自本地 mmap

• 对于消费者，发布接收缓冲区需要来自 PCIe 导出 mmap

本节介绍使用 DOCA Core 进度引擎 在 CPU 上的执行。有关其他执行环境，请参阅“替代数据路径选项”部分。

任务

DOCA Comch 根据 DOCA Core 架构 公开利用 BlueField 硬件的异步任务。

控制通道发送任务

此任务允许在连接的客户端和服务器对象之间发送消息。

任务配置

任务输入

如 DOCA Core 任务 中所述的通用输入。

任务输出

如 DOCA Core 任务 中所述的通用输出。

任务完成成功

在任务成功完成后

• 消息已传递到连接的远程客户端/服务器

• 在远程端触发接收事件

任务完成失败

如果任务中途失败

• 如果发生致命错误，上下文可能会进入停止状态

• 消息未传递到远程端

任务限制

• 操作不是原子的

• 一旦提交了任务，则不应更新消息

• 其他限制在 DOCA Core 任务 中描述

消费者发布接收任务

此任务允许消费者对象发布可供远程生产者写入的缓冲区。

任务配置

任务输入

如 DOCA Core 任务 中所述的通用输入。

任务输出

如 DOCA Core 任务 中所述的通用输出。

任务完成成功

任务仅在生产者已写入已通告的缓冲区（或立即数据，或两者兼有）时完成，而不是在发布接收完成时完成。

成功完成后，缓冲区包含生产者写入的数据，并且其长度已相应更新。

任务完成失败

如果缓冲区未成功发布以接收数据，则会发生任务失败。

如果任务中途失败

• 如果发生致命错误，上下文可能会进入停止状态

• 生产者不知道缓冲区，因此不会写入缓冲区

任务限制

• 操作不是原子的

• 一旦提交了任务，则不应读取/写入缓冲区

• 缓冲区必须来自具有 PCIe 读/写访问权限的内存

• 不支持链接缓冲区列表

• MsgQ 消费者不支持提供 doca_buf，并且只能接收立即数据

• 其他限制在 DOCA Core 任务 中描述

生产者发送任务

此任务允许生产者对象复制缓冲区以供远程消费者使用。

任务配置

任务输入

如 DOCA Core 任务 中所述的通用输入。

任务输出

如 DOCA Core 任务 中所述的通用输出。

任务完成成功

在任务成功完成后

• 数据从缓冲区复制到给定消费者发布的下一个空闲缓冲区

• 消费者按发送顺序处理来自给定消费者的缓冲区

任务完成失败

如果任务中途失败

• 如果发生致命错误，上下文可能会进入停止状态

• 源和目标 doca_buf 对象未修改

• 目标内存可能会被修改

任务限制

• 操作不是原子的

• 一旦提交了任务，则不应读取/写入缓冲区

• 缓冲区长度不应大于消费者发布接收缓冲区（否则会返回无效值）

• MsgQ 生产者不支持提供 doca_buf，并且只能发送立即数据

• DOCA Core 任务 中描述的所有限制

事件

DOCA Comch 公开异步事件，以根据 DOCA Core 架构通知突然发生的更改。请参阅 DOCA Core 事件。

如 DOCA Core 事件 中所述的通用事件。

控制通道接收事件

每当远程客户端/服务器向本地客户端/服务器对象发送消息时，都会触发此事件。

事件配置

事件触发条件

当在与客户端或服务器关联的任何当前活动连接上收到远程消息时，会触发该事件。

事件输出

检测到事件后，将触发注册的回调，并传递以下参数

• 指向消息数据的指针

  信息

  数据仅在回调的上下文中有效。

• 消息的长度（以字节为单位）

• 接收消息的活动连接

连接状态更改事件（仅限服务器）

此事件提供有关与服务器关联的任何连接状态的异步更新。

事件配置

事件触发条件

当服务器上建立新连接或断开当前连接时，会触发该事件。

事件输出

为连接或断开连接事件注册单独的回调，并根据特定事件触发相应的回调。

两个回调都包含一个布尔值，指示连接或断开连接是否成功。

消费者事件

此事件指示已创建新的消费者对象或已销毁现有的消费者对象。

事件配置

事件触发条件

每当在已建立的 DOCA Comch 连接的远程端创建新消费者或销毁当前消费者时，都会触发该事件。

事件输出

该事件为消费者的创建或销毁触发单独的回调。

回调参数包括

• 消费者连接到的已建立的 DOCA Comch 连接（在远程端）

• 消费者的 ID（每个 Comch 连接的唯一值）

DOCA Comch 库遵循 DOCA Core 上下文状态机 中描述的上下文状态机。

以下部分介绍如何移动到该状态以及每种状态允许的操作。

空闲

在此状态下，应用程序应执行以下操作之一

• 销毁上下文

• 启动上下文

允许的操作

• 根据 配置 配置上下文

• 启动上下文

可以按如下方式达到此状态

启动中

在此状态下，应用程序应执行以下操作

• 调用进度以允许转换到下一个状态（例如，当连接尝试完成时）

允许的操作

• 调用进度

可以按如下方式达到此状态

运行中

在此状态下，应用程序应执行以下操作

• 分配并提交任务

• 调用进度以完成任务和/或接收事件

允许的操作

• 分配先前配置的任务

• 提交已分配的任务

• 调用停止

可以按如下方式达到此状态

停止中

在此状态下，应用程序应执行以下操作

• 释放任何已完成的任务

允许的操作

• 分配先前配置的任务

• 提交已分配的任务

• 调用停止

可以按如下方式达到此状态

DOCA Comch 可以作为 DPA 数据路径的一部分运行，使用 MsgQ。

DPA

使用 MsgQ，可以在 DPA 上创建消费者/生产者。它们遵循 DOCA Core DPA 中描述的定义。

由于这些对象可以在 DPA 中使用，因此它们具有 DPA API，可用于执行以下小节中扩展的数据路径操作。

消费者确认

doca_dpa_dev_comch_consumer_ack API 准备 DPA 消费者以接收来自 CPU 生产者的多个立即消息。

配置

输入

完成

每当从 CPU 生产者收到消息时，都会生成一个完成元素，并且可以使用 doca_dpa_dev_comch_consumer_get_completion 进行轮询。

使用生成的完成，可以获得以下输出

限制

• 最大立即消息大小为 32 字节

生产者发布仅立即发送

doca_dpa_dev_comch_producer_post_send_imm_only API 向 CPU 消费者发送立即消息。一旦消息到达 CPU 消费者端，CPU 消费者接收任务就会完成。

CPU 生产者必须在此之前发布接收任务。用户可以使用 doca_dpa_dev_comch_producer_is_consumer_empty 验证消费者是否可以接收消息。但是，请注意，这可能会增加开销。

配置

输入

完成

一旦消息到达 CPU 消费者，就会生成一个完成元素，指示发送已完成（这与 CPU 消费者接收到的完成是分开的），并且可以使用 doca_dpa_dev_get_completion 进行轮询。

使用生成的完成，可以获得以下输出

限制

• 最大立即消息大小为 32 字节

生产者 DMA 复制

doca_dpa_dev_comch_producer_dma_copy API 执行 DMA 复制操作，并在复制操作完成后，向 CPU 消费者发送即时消息。一旦消息到达 CPU 消费者端，CPU 消费者接收任务完成。

CPU 生产者必须在此之前发布接收任务。用户可以使用 doca_dpa_dev_comch_producer_is_consumer_empty 验证消费者是否可以接收消息。但是，请注意，这可能会增加开销。

配置

输入

完成

一旦复制完成并且消息到达 CPU 消费者，就会生成一个完成元素，指示复制已完成（这与 CPU 消费者接收到的完成是分开的），并且可以使用 doca_dpa_dev_get_completion 进行轮询。

使用生成的完成，可以获得以下输出

限制

• 最大立即消息大小为 32 字节

本节介绍基于 DOCA Comch 库的 DOCA Comch 示例。

这些示例说明了如何使用 DOCA Comch API 来执行以下操作

• 在主机和 BlueField Arm 内核之间建立客户端/服务器，并使用它来发送文本消息

• 配置快速路径生产者和消费者，并在它们之间发送消息

运行示例

1. 请参阅以下文档

   • DOCA Linux 安装指南，了解如何安装 BlueField 相关软件的详细信息。

   • DOCA 故障排除，以解决您在 DOCA 示例的安装、编译或执行过程中可能遇到的任何问题。

2. 构建给定示例

   复制

   已复制！

               
   
               
   cd /opt/mellanox/doca/samples/doca_comch/<sample_name>
   meson /tmp/build
   ninja -C /tmp/build
           

   二进制文件 doca_<sample_name> 在 /tmp/build/ 下创建。

3. 所有 DOCA Comch 示例都接受相同的输入参数

   示例	参数	描述
   doca_comch_ctrl_path_server doca_comch_ctrl_path_client doca_comch_data_path_high_speed_server doca_comch_data_path_high_speed_client	-p, --pci-addr	DOCA Comch 设备 PCIe 地址
   	-r, --rep-pci	DOCA Comch 设备表示器 PCIe 地址（仅在 BlueField Arm 上需要）
   	-t, --text	要发送到通道另一侧的文本（覆盖默认值）

4. 有关每个示例的更多信息，请使用 -h 选项

   复制

   已复制！

               
   
               
   /tmp/build/<sample_name> -h
           

示例

DOCA Comch 控制路径客户端/服务器

此示例在主机和 BlueField Arm 内核之间建立客户端服务器连接。

该连接用于传递两条消息，第一条由客户端在连接建立时发送，第二条由服务器在收到客户端消息时发送。

示例逻辑包括

1. 定位 DOCA 设备。

2. 初始化核心 DOCA 结构。

3. 初始化和配置客户端/服务器上下文。

4. 注册用于发送/接收消息和跟踪连接更改的任务和事件。

5. 分配和提交用于发送控制路径消息的任务。

6. 处理用于接收消息的事件完成。

7. 停止和销毁客户端/服务器对象。

参考

• /opt/mellanox/doca/samples/doca_comch/comch_ctrl_path_client/comch_ctrl_path_client_main.c

• /opt/mellanox/doca/samples/doca_comch/comch_ctrl_path_client/comch_ctrl_path_client_sample.c

• /opt/mellanox/doca/samples/doca_comch/comch_ctrl_path_server/comch_ctrl_path_server_main.c

• /opt/mellanox/doca/samples/doca_comch/comch_ctrl_path_server/comch_ctrl_path_server_sample.c

• /opt/mellanox/doca/samples/doca_comch/comch_ctrl_path_common.c

• /opt/mellanox/doca/samples/doca_comch/comch_ctrl_path_common.h

DOCA Comch 数据路径客户端/服务器

此示例在主机和 BlueField Arm 之间建立客户端服务器连接。

该连接用于在两侧创建生产者和消费者，并在两个快速路径连接之间传递消息。

示例逻辑包括

1. 定位 DOCA 设备。

2. 初始化核心 DOCA 结构。

3. 初始化和配置客户端/服务器上下文。

4. 在已建立的连接之上初始化和配置生产者/消费者上下文。

5. 提交由生产者填充的发布接收任务。

6. 提交来自生产者的发送任务以写入消费者。

7. 停止和销毁生产者/消费者对象。

8. 停止和销毁客户端/服务器对象。

参考

• /opt/mellanox/doca/samples/doca_comch/comch_data_path_high_speed_client/comch_data_path_high_speed_client_main.c

• /opt/mellanox/doca/samples/doca_comch/comch_data_path_high_speedclient/comch_data_path_high_speed_client_sample.c

• /opt/mellanox/doca/samples/doca_comch/comch_data_path_high_speedserver/comch_data_path_high_speed_server_main.c

• /opt/mellanox/doca/samples/doca_comch/comch_data_path_high_speedserver/comch_data_path_high_speed_server_sample.c

• /opt/mellanox/doca/samples/doca_comch/comch_data_path_high_speed_common.c

• /opt/mellanox/doca/samples/doca_comch/comch_data_path_high_speed_common.h