同步事件

DOCA 同步事件 (SE) 是一种软件同步机制，用于跨 CPU、DPU、DPA 和远程节点进行并行执行。SE 持有一个 64 位计数器，可以从这些单元中的任何一个更新、读取和等待，以实现它们之间执行的同步。

为了获得最佳性能，DOCA SE 定义了订阅者和发布者的本地性，其中

• 发布者 – 更新（设置或递增）事件值的实体

• 订阅者 – 获取和等待 SE 的实体

  信息

  发布者和订阅者都可以读取（获取）计数器的实际值。

基于提示，DOCA 选择 SE 计数器的内存本地性，使其更靠近订阅者端。每个 DOCA SE 都配置有单个发布者位置和单个订阅者位置，它们可以是 CPU 或 DPU。

SE 控制路径在 CPU（主机 CPU 或 DPU CPU）上通过 DOCA SE CPU 句柄发生。可以通过 CPU 句柄导出 SE 实例来检索不同的特定于执行单元的句柄（DPU/DPA/GPU/远程句柄）。每个 SE 句柄都引用从中检索它的 DOCA SE 实例。通过使用特定于执行单元的句柄，可以从该执行单元操作关联的 SE 实例。

在基本场景中，通过从一个执行单元更新 SE 并从另一个执行单元等待 SE 来实现同步。

DOCA SE 可以用作遵循 DOCA Core Context 架构的上下文，建议在继续之前阅读 DOCA Core 页面的以下部分

• DOCA 执行模型

• DOCA 设备

• DOCA 内存子系统

基于 DOCA SE 的应用程序可以在主机或 NVIDIA® BlueField® DPU 目标上运行，并且可以涉及 DPA、GPU 和其他远程节点。

将 DOCA SE 与 DPU 结合使用需要将 BlueField 配置为在 DPU 模式下工作，如 BlueField 操作模式 中所述。

DOCA SE 可以转换为 DOCA Core 定义的 DOCA 上下文。有关更多信息，请参阅 DOCA 上下文。

作为上下文，DOCA SE 利用 DOCA Core 架构来公开卸载到硬件的异步任务/事件。

下图演示了 DOCA SE 使用的组件。DOCA 设备提供有关 SE 使用的已配置硬件功能的信息，以控制系统资源。

跨设备同步（可能是 DPA、GPU 或远程对等方）需要 DOCA DPA、GPUNetIO 和 RDMA 模块。

DOCA SE 通过其指定外部缓冲区的能力实现灵活的内存管理，其中 DOCA mmap 模块处理高级同步场景的内存注册。

对于异步操作调度，SE 使用 DOCA Progress Engine (PE) 模块。

DOCA 同步事件组件图

下图表示 DOCA SE 在各种设备上的同步能力。

DOCA 同步事件交互图

DOCA 同步事件对象

DOCA SE 为每个执行单元公开不同类型的句柄，如下表详述。

这些句柄类型中的每一种都有其自己的专用 API，用于创建句柄并与之交互。

任何 DOCA SE 创建都从调用 doca_sync_event_create API 创建 CPU 句柄开始。

创建后，可以通过专用句柄创建，经由 DOCA SE 导出流程，将 SE 实体与本地 PCIe、远程 CPU、DPA 和 GPU 共享，如下图所示

操作模式

DOCA SE 公开两个不同的 API 来启动它，具体取决于所需的操作模式：同步或异步。

同步模式

调用 doca_sync_event_start 启动 SE 以在同步模式下运行。

在同步操作模式下，每个数据路径操作（获取、更新、等待）都会阻止调用线程继续，直到操作完成。

异步模式

要启动 SE 以在异步模式下运行，请通过调用 doca_sync_event_as_ctx 将 SE 实例转换为 doca_ctx。然后使用 DOCA CTX API 启动 SE 和 DOCA PE API 在 SE 上提交任务（有关更多信息，请参阅“DOCA Progress Engine”部分）。

配置

强制配置

这些配置必须由应用程序在尝试启动 SE 之前设置

• 必须通过提供关于发布者和订阅者位置的运行时提示来配置 DOCA SE CPU 句柄。订阅者和发布者位置都必须使用以下 API 进行配置

  • doca_sync_event_add_publisher_location_<cpu|dpa|gpu|remote_pci|remote_net>

  • doca_sync_event_add_subscriber_location_<cpu|dpa|gpu|remote_pci>

• 对于异步用例，必须至少配置一种任务/事件类型。请参阅 任务 的配置。

可选配置

• 这些配置提供了一个 8 字节的缓冲区，用作 SE 的后备内存。如果设置了，则用户有责任处理内存（即，在 DOCA SE 生命周期内保留分配的内存，并在 DOCA SE 销毁后释放它）。如果未提供，则 SE 后备内存由 SE 分配。

  • doca_sync_event_set_addr

  • doca_sync_event_set_doca_buf

将 DOCA 同步事件导出到另一个执行单元

要从 CPU 以外的执行单元使用 SE，必须导出它以获取特定执行单元的句柄

• DPA – doca_sync_event_get_dpa_handle 返回一个 DOCA SE DPA 句柄 (doca_dpa_dev_sync_event_t)，可以将其从 DPA 内核传递到 DPA SE 数据路径 API

• GPU – doca_sync_event_get_gpu_handle 返回一个 DOCA SE GPU 句柄 (doca_gpu_dev_sync_event_t)，可以将其传递到 CUDA 内核的 GPU SE 数据路径 API

• DPU – doca_sync_event_export_to_remote_pci 返回一个 blob，DPU CPU 可以使用该 blob 通过 doca_sync_event_create_from_export 函数实例化 DOCA SE DPU 句柄 (struct doca_sync_event)

DOCA SE 允许来自远程对等方（远程网络）的通知，利用 DOCA RDMA 库的功能。下图说明了远程网络导出流程

• 远程网络 CPU – doca_sync_event_export_to_remote_net 返回一个 blob，远程网络 CPU 可以使用该 blob 通过 doca_sync_event_remote_net_create_from_export 函数实例化 DOCA SE 远程网络 CPU 句柄 (struct doca_sync_event_remote_net)。该句柄可以直接用于通过 doca_rdma 库提交异步任务，或导出到远程 DPA/GPU。

• 远程网络 DPA – doca_sync_event_remote_net_get_dpa_handle 返回一个 DOCA SE 远程网络 DPA 句柄 (doca_dpa_dev_sync_event_remote_net_t)，可以将其从 DPA 内核传递到 DPA RDMA 数据路径 API

• 远程网络 GPU – doca_sync_event_remote_net_get_gpu_handle 返回一个 DOCA SE 远程网络 GPU 句柄 (doca_gpu_dev_sync_event_remote_net_t)，可以将其传递到 CUDA 内核的 GPU RDMA 数据路径 API

设备支持

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

由于设备功能将来可能会发生变化（请参阅 DOCA 功能检查），建议您使用任何相关功能方法（以前缀 doca_sync_event_cap_* 开头）选择您的设备。

用于查询是否可以从导出 blob 构建同步事件的功能 API

• doca_sync_event_cap_is_create_from_export_supported

• doca_sync_event_cap_remote_net_is_create_from_export_supported

用于查询是否可以将同步事件导出到其他执行单元的功能 API

• doca_sync_event_cap_is_export_to_remote_pci_supported

• doca_sync_event_cap_is_export_to_dpa_supported

• doca_sync_event_cap_is_export_to_gpu_supported

• doca_sync_event_cap_is_export_to_remote_net_supported

• doca_sync_event_cap_remote_net_is_export_to_dpa_supported

• doca_sync_event_cap_remote_net_is_export_to_gpu_supported

用于查询是否支持异步任务的功能 API

• doca_sync_event_cap_task_get_is_supported

• doca_sync_event_cap_task_notify_set_is_supported

• doca_sync_event_cap_task_notify_add_is_supported

• doca_sync_event_cap_task_wait_eq_is_supported

• doca_sync_event_cap_task_wait_neq_is_supported

本节描述 CPU 上的执行。有关其他执行环境，请参阅“备选数据路径选项”部分。

DOCA 同步事件数据路径操作

DOCA SE 同步机制是使用公开的数据路径操作实现的。API 公开了一个用于“写入”SE 和用于“读取”SE 的函数。

同步 API 是一组可以由用户直接调用的函数，而 异步 API 通过为要在 DOCA PE 上提交的每个同步函数定义相应的 doca_task 来公开（有关更多信息，请参阅 DOCA Progress Engine 和 DOCA 上下文）。

以下小节描述了关于同步和异步操作模式的 DOCA SE 数据路径操作。

在 DOCA 同步事件上发布

设置 DOCA 同步事件值

用户可以将 DOCA SE 设置为 64 位值

• 同步地通过调用 doca_sync_event_update_set

• 异步地通过提交 doca_sync_event_task_notify_set 任务

添加到 DOCA 同步事件值

用户可以原子地递增 DOCA SE 的值

• 同步地通过调用 doca_sync_event_update_add

• 异步地通过提交 doca_sync_event_task_notify_add 任务

订阅 DOCA 同步事件

获取 DOCA 同步事件值

用户可以获取 DOCA SE 的值

• 同步地通过调用 doca_sync_event_get

• 异步地通过提交 doca_sync_event_task_get 任务

等待 DOCA 同步事件

等待事件是在不同执行单元之间实现同步的主要操作。

用户可以通过多种方式等待 SE 达到特定值。

同步地

doca_sync_event_wait_gt 以“轮询忙等待”方式（100% 处理器利用率）等待 DOCA SE 的值大于指定值。此 API 使用户能够实时等待 SE。

doca_sync_event_wait_gt_yield 以“周期性忙等待”方式等待 DOCA SE 的值大于指定值。在每次轮询迭代后，调用线程放弃 CPU，以便新线程可以运行。此 API 允许在实时轮询到 CPU 饥饿之间进行权衡。

doca_sync_event_wait_eq 以“轮询忙等待”方式（100% 处理器利用率）等待 DOCA SE 的值等于指定值。此 API 使用户能够实时等待 SE。

doca_sync_event_wait_eq_yield 以“周期性忙等待”方式等待 DOCA SE 的值等于指定值。在每次轮询迭代后，调用线程放弃 CPU，以便新线程可以运行。此 API 允许在实时轮询到 CPU 饥饿之间进行权衡。

doca_sync_event_wait_neq 以“轮询忙等待”方式（100% 处理器利用率）等待 DOCA SE 的值不等于指定值。此 API 使用户能够实时等待 SE。

doca_sync_event_wait_neq_yield 以“周期性忙等待”方式等待 DOCA SE 的值不等于指定值。在每次轮询迭代后，调用线程放弃 CPU，以便新线程可以运行。此 API 允许在实时轮询到 CPU 饥饿之间进行权衡。

异步地

DOCA SE 通过定义 doca_sync_event_task_wait_eq 和 doca_sync_event_task_wait_neq 任务来公开异步等待方法。

用户可以使用以下方法等待等待作业完成

• 阻塞 – 从 doca_pe 获取 doca_event_handle_t 以进行阻塞等待

• 轮询 – 通过调用 doca_pe_progress 轮询等待任务

任务

DOCA SE 上下文公开异步任务，这些任务根据 DOCA Core 架构利用 DPU 硬件。请参阅 DOCA Core 任务。

获取任务

get 任务检索 DOCA SE 的值。

任务配置

任务输入

在 DOCA Core 任务 中描述的通用输入。

任务输出

在 DOCA Core 任务 中描述的通用输出。

任务完成成功

任务成功完成后，返回值内存保存 DOCA SE 值。

任务完成失败

如果任务中途失败

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

• 返回值内存可能会被修改

任务限制

所有限制都在 DOCA Core 任务 中描述。

通知设置任务

notify set 任务允许设置 DOCA SE 的值。

任务配置

任务输入

在 DOCA Core 任务 中描述的通用输入。

任务输出

在 DOCA Core 任务 中描述的通用输出。

任务完成成功

任务成功完成后，DOCA SE 值将设置为给定的设置值。

任务完成失败

如果任务中途失败，如果发生致命错误，上下文可能会进入停止状态。

任务限制

此操作不是原子的。其他限制在 DOCA Core 任务 中描述。

通知添加任务

notify add 任务允许原子地设置 DOCA SE 的值。

任务配置

任务输入

在 DOCA Core 任务 中描述的通用输入。

任务输出

在 DOCA Core 任务 中描述的通用输出。

任务完成成功

任务成功完成后，会发生以下情况

• DOCA SE 值根据给定的递增值递增

• 获取的值内存保存递增前 DOCA SE 值

任务完成失败

如果任务中途失败

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

• 获取的值内存可能会被修改。

任务限制

所有限制都在 DOCA Core 任务 中描述。

等待等于任务

wait-equal 任务允许原子地等待 DOCA SE 值等于某个阈值。

任务配置

任务输入

在 DOCA Core 任务 中描述的通用输入。

任务输出

在 DOCA Core 任务 中描述的通用输出。

任务完成成功

任务成功完成后，会发生以下情况

• DOCA SE 值等于给定的等待阈值。

任务完成失败

如果任务中途失败，如果发生致命错误，上下文可能会进入停止状态。

任务限制

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

等待不等于任务

wait-not-equal 任务允许原子地等待 DOCA SE 值不等于某个阈值。

任务配置

任务输入

在 DOCA Core 任务 中描述的通用输入。

任务输出

在 DOCA Core 任务 中描述的通用输出。

任务完成成功

任务成功完成后，会发生以下情况

• DOCA SE 值不等于给定的等待阈值。

任务完成失败

如果任务中途失败，如果发生致命错误，上下文可能会进入停止状态。

任务限制

限制在 DOCA Core 任务 中描述。

事件

DOCA SE 上下文公开异步事件，以根据 DOCA Core 架构 通知意外发生的更改。

DOCA SE 上下文公开的唯一事件是在 DOCA Core 事件 中描述的通用事件。

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

以下小节描述了如何移动到特定状态以及每个状态允许的操作。

空闲

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

• 销毁上下文；或

• 启动上下文

在此状态下允许的操作

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

• 启动上下文

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

启动中

无法达到此状态。

运行中

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

• 分配和提交任务

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

在此状态下允许的操作

• 分配先前配置的任务

• 提交已分配的任务

• 调用 stop

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

停止中

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

• 调用 progress 以完成所有正在进行的任务（任务将完成并失败）

• 释放任何已完成的任务

在此状态下允许的操作

• 调用 progress

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

与同一 DOCA SE 实例关联的多个 SE 句柄（用于不同的执行单元）可以同时存在，但拆卸流程仅从 CPU 上的 CPU 句柄执行。

停止 DOCA 同步事件

要停止 DOCA SE

• 同步 – 在 CPU 句柄上调用 doca_sync_event_stop

• 异步 – 停止与 DOCA SE 实例关联的 DOCA 上下文

销毁 DOCA 同步事件

一旦停止，就可以通过在 CPU 句柄上调用 doca_sync_event_destroy 来销毁 DOCA SE 实例。

远程网络 CPU 句柄实例通过在远程网络 CPU 句柄上调用 doca_sync_event_remote_net_destroy 来终止和释放。

销毁后，所有内部资源都将被释放，分配的内存将被释放，关联的 doca_ctx（如果存在）将被销毁，并且任何关联的导出句柄（CPU 句柄除外）及其资源都将被销毁。

DOCA SE 支持 CPU 上的数据路径（请参阅“执行阶段”部分）以及 DPA 和 GPU 上的数据路径。

GPU 数据路径

DOCA SE 目前不支持 GPU 相关功能。

DPA 数据路径

一旦检索到 DOCA SE DPA 句柄 (doca_dpa_dev_sync_event_t)，就可以在 DOCA DPA 内核中使用它，如 DOCA DPA 同步事件 中所述。

本节提供基于 BlueField DPU 的 DOCA SE 示例实现。

该示例演示了如何在主机和 DPU 之间共享 SE，同时使用不同的句柄从主机和 DPU 侧与事件进行交互。

运行 DOCA 同步事件示例

1. 请参阅以下文档

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

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

2. 要构建给定的示例

   复制

   已复制！

               
   
               
   cd /opt/mellanox/doca/samples/doca_common/sync_event_<local|remote>_pci
   meson /tmp/build
   ninja -C /tmp/build
           

   注意

   二进制文件 doca_sync_event_<local|remote>_pci 在 /tmp/build/ 下创建。

3. 示例用法

   复制

   已复制！

               
   
               
   Usage: doca_sync_event_remote_pci [DOCA Flags] [Program Flags]
    
   DOCA Flags:
     -h, --help                        Print a help synopsis
     -v, --version                     Print program version information
     -l, --log-level                   Set the (numeric) log level for the program <10=DISABLE, 20=CRITICAL, 30=ERROR, 40=WARNING, 50=INFO, 60=DEBUG, 70=TRACE>
     --sdk-log-level                   Set the SDK (numeric) log level for the program <10=DISABLE, 20=CRITICAL, 30=ERROR, 40=WARNING, 50=INFO, 60=DEBUG, 70=TRACE>
     -j, --json <path>                 Parse all command flags from an input json file
    
   Program Flags:
     -d, --pci-addr                	Device PCI address
     -r, --rep-pci-addr                DPU representor PCI address
     --async                           Start DOCA Sync Event in asynchronous mode (synchronous mode by default)
     --async_num_tasks                 Async num tasks for asynchronous mode
     --atomic                          Update DOCA Sync Event using Add operation (Set operation by default)
           

   注意

   标志 --rep-pci-addr 仅与 DPU 相关。

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

   复制

   已复制！

               
   
               
   /tmp/build/doca_sync_event_<local|remote>_pci -h
           

示例

同步事件远程 PCIe

此示例演示了如何从与本地 PCIe（主机或 DPU）上的 SE 关联的导出创建 SE，以及如何与 SE 交互以实现主机和 DPU 之间的同步。

示例逻辑包括

1. 读取配置文件并将内容保存到本地缓冲区中。

2. 查找和打开与给定 PCIe 地址匹配的 DOCA 设备和 DOCA representor（如果在 DPU 上运行）。

3. 初始化 DOCA Comm Channel。

4. 通过 Comm Channel 接收 SE blob。

5. 从导出创建 SE。

6. 以请求的操作模式（同步或异步）启动上述 SE。

7. 与 SE 交互

   1. 等待来自主机的信号 – 根据用户输入同步或异步（使用忙等待轮询）。

   2. 根据用户输入，同步或异步地向主机发送 SE 信号 – 使用 set 或原子加操作。

8. 清理所有资源。

参考

• /opt/mellanox/doca/samples/doca_common/sync_event_remote_pci/sync_event_remote_pci_sample.c

• /opt/mellanox/doca/samples/doca_common/sync_event_remote_pci/sync_event_remote_pci_main.c

• /opt/mellanox/doca/samples/doca_common/sync_event_remote_pci/meson.build

同步事件本地 PCIe

此示例演示了如何初始化一个 SE 以便与远程 PCIe（主机或 DPU）共享，如何将其导出到远程 PCIe，以及如何与 SE 交互以实现主机和 DPU 之间的同步。

示例逻辑包括

1. 读取配置文件并将内容保存到本地缓冲区中。

2. 查找和打开与给定 PCIe 地址匹配的 DOCA 设备和 DOCA representor（如果在 DPU 上运行）。

3. 创建和配置要与远程 PCIe 共享的 SE。

4. 以请求的操作模式（同步或异步）启动上述 SE。

5. 初始化 DOCA Comm Channel。

6. 导出 SE 并通过通信通道发送。

7. 与 SE 交互

   1. 根据用户输入，同步或异步地向远程 PCIe 发送 SE 信号 – 使用 set 或原子加操作。

   2. 根据用户输入，同步或异步地等待信号 – 使用忙等待轮询。

8. 清理所有资源。

参考

• /opt/mellanox/doca/samples/doca_common/sync_event_local_pci/sync_event_local_pci_sample.c

• /opt/mellanox/doca/samples/doca_common/sync_event_local_pci/sync_event_local_pci_main.c

• /opt/mellanox/doca/samples/doca_common/sync_event_local_pci/meson.build