DOCA Rivermax - NVIDIA 文档

本指南提供关于构建和开发需要媒体/数据流应用程序的说明。

简介

DOCA Rivermax (RMAX) 是 NVIDIA® Rivermax® 的 DOCA API，这是一个针对媒体和数据流应用程序优化的网络 SDK。Rivermax 利用 NVIDIA® BlueField® DPU 硬件流加速技术，该技术支持与 GPU 之间直接数据传输，从而为流工作负载提供一流的吞吐量和延迟，同时最大限度地减少 CPU 利用率。

本文档适用于希望加速其网络操作的软件开发人员。

prerequisites

该库遵循 DOCA Core Context 的架构。建议在继续之前阅读以下内容

环境

信息

基于 DOCA Rivermax 的应用程序只能在目标 DPU 上运行。

信息

基于 DOCA Rivermax 的应用程序必须以 root 权限运行。

Rivermax 库必须编译和运行，并且需要 Rivermax 许可证才能运行应用程序。请参阅NVIDIA Rivermax SDK 页面以获取该许可证。
必须设置要使用的设备的 IP 地址。

建议启用至少 800 个巨页以实现最佳性能

复制
已复制！

            
            dpu> echo 1000000000 > /proc/sys/kernel/shmmax
dpu> echo 800 > /proc/sys/vm/nr_hugepages

架构

DOCA Rivermax 输入流是由 DOCA Core 定义的DOCA Context
DOCA Rivermax 利用 DOCA Core 架构来公开异步事件，这些事件被卸载到硬件
DOCA Rivermax 可用于定义输入流，从而允许在 IP 端口上获取数据包。此外，输入流可以拆分为 TCP/UDP 5 元组，以允许单独处理流。

对象

doca_rmax_flow – 是一个流对象，表示 IP/端口元组
doca_rmax_in_stream – 是一个 doca_ctx，它表示输入流，可以被认为是接收队列，它将接收到的数据分散到内存中。每个流可以接收一个或多个流。

配置阶段

要开始使用该库，用户必须首先完成配置阶段，如DOCA Core Context 配置阶段中所述。

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

配置

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

要查找配置是否受支持或其最小/最大值，请参阅“设备支持”部分。

强制配置

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

必须配置事件类型。请参阅事件的配置。
CPU 亲和性，然后按此顺序进行 Rivermax 库全局初始化。以下 API 可用于实现此目的 doca_rmax_set_cpu_affinity_mask() 和 doca_rmax_init()
保存数据包内存的内存块
流元素的数量
最小数据包段大小
最大数据包段大小

可选配置

如果未设置以下配置，则使用默认值

输入流类型 – 默认为通用
输入流数据包的数据分散类型 – 默认为原始
输入流时间戳格式 – 默认为原始计数器

设备支持

DOCA Rivermax 输入流需要设备才能运行。有关选择设备，请参阅DOCA Core 设备发现。

设备必须来自 DPU 内部：PF 或 SF。

建议使用以下方法选择您的设备

doca_devinfo_get_ipv4_addr()

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

PTP 时钟支持。

缓冲区支持

内存块支持具有以下功能的缓冲区

缓冲区类型	内存块
本地 mmap 缓冲区	是
来自 PCIe 导出缓冲区的 Mmap	是
来自 RDMA 导出缓冲区的 Mmap	否
链表缓冲区	是（头部拆分模式）

执行阶段

本节介绍如何使用 DOCA Core Progress Engine 在 CPU 上执行。

事件

DOCA Rivermax 公开异步事件，以根据 DOCA Core 架构通知意外发生的变化。

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

Rx 数据

Rx 数据事件由流用于通知应用程序已从网络接收到数据。

事件配置

描述	用于设置配置的 API	用于查询支持的 API
注册事件	`doca_rmax_in_stream_event_rx_data_register`	–

事件触发条件

每当数据包到达时，都会触发事件。

事件输出

与DOCA Core 事件中描述的通用输出相同。

如果成功，则提供以下内容

接收到的数据包数量
第一个数据包的到达时间
最后一个数据包的到达时间
第一个数据包的序列号
由输入流配置的内存块数组

如果发生错误，则提供以下内容

错误代码
人类可读的消息

注意

这些参数仅在事件回调内部有效。

事件处理

一旦事件被触发，应用程序可以决定处理接收到的数据。

运行时配置

这些配置可以在上下文启动后进行

输入流必须在 Rx 事件中返回的最小数据包数。
输入流必须在 Rx 事件中返回的最大数据包数。
接收超时。库将忙等待（轮询）至少 min_packets 个数据包接收的微秒数。

状态机

DOCA RMAX 库遵循上下文状态机，如DOCA Core Context 状态机中所述

以下部分描述如何移动到状态以及每个状态允许的操作。

空闲

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

销毁上下文
启动上下文

允许的操作

根据配置配置上下文
启动上下文

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

上一个状态	转换操作
无	创建上下文
运行中	调用停止

启动中

预计不会达到此状态。

运行中

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

调用进度以接收事件

允许的操作

调用停止
更改运行时配置，如运行时配置中所述

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

上一个状态	转换操作
空闲	配置后调用启动

停止中

预计不会达到此状态。

DOCA Rivermax 示例

示例说明了如何使用 DOCA Rivermax API 来

列出可用设备，包括其 IP 和支持的功能
为 Rivermax 内部线程设置 CPU 亲和性，以获得更好的性能
设置要在 DOCA Rivermax 内部使用的 PTP 时钟设备
创建流，创建流并将其附加到创建的流，最后开始接收数据缓冲区（基于附加的流）
在头部数据分离模式下创建流，此时数据包头部和有效负载被拆分到不同的 RX 缓冲区

信息

本节中描述的所有 DOCA 示例均受 BSD-3 软件许可协议管辖。

运行示例

请参阅以下文档
- NVIDIA DOCA Linux 安装指南，了解如何安装 BlueField 相关软件的详细信息
- DOCA 故障排除，了解您在 DOCA 示例的安装、编译或执行中可能遇到的任何问题

要构建给定的示例

复制
已复制！

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

信息

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

示例（例如，doca_rmax_create_stream）用法

复制
已复制！

            
            Usage: doca_rmax_create_stream [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>
  -j, --json <path>                       Parse all command flags from an input json file
  
Program Flags:
  -p, --pci_addr <PCI-ADDRESS>            PCI device address

注意

运行 DOCA Rivermax 示例时，必须在运行示例之前将 IPv4 地址 192.168.105.2 配置到可用的上行链路，以便示例按预期运行

复制
已复制！

            
            $ifconfig p0 192.168.105.2

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

复制
已复制！

            
            /tmp/build/<sample_name> -h

示例

列出设备

此示例说明如何列出所有可用设备，转储其 IPv4 地址，并告知是否支持 PTP 时钟。

示例逻辑包括

初始化 DOCA Rivermax 库。
迭代可用设备。
转储其 IPv4 地址
转储每个设备是否支持 PTP 时钟。
释放 DOCA Rivermax 库。

参考

/opt/mellanox/doca/samples/doca_rmax/rmax_list_devices/rmax_list_devices_sample.c
/opt/mellanox/doca/samples/doca_rmax/rmax_list_devices/rmax_list_devices_main.c
/opt/mellanox/doca/samples/doca_rmax/rmax_list_devices/meson.build
/opt/mellanox/doca/samples/doca_rmax/rmax_common.h; /opt/mellanox/doca/samples/doca_rmax/rmax_common.c

设置 CPU 亲和性

此示例说明如何为 Rivermax 内部线程设置 CPU 亲和性掩码以获得更好的性能。此参数必须在库初始化之前设置，否则将不会应用。

示例逻辑包括

使用 DOCA Rivermax API 设置 CPU 亲和性。
初始化 DOCA Rivermax 库。
释放 DOCA Rivermax 库。

参考

/opt/mellanox/doca/samples/doca_rmax/rmax_set_affinity/rmax_set_affinity_sample.c
/opt/mellanox/doca/samples/doca_rmax/rmax_set_affinity/rmax_set_affinity_main.c
/opt/mellanox/doca/samples/doca_rmax/rmax_set_affinity/meson.build
/opt/mellanox/doca/samples/doca_rmax/rmax_common.h; /opt/mellanox/doca/samples/doca_rmax/rmax_common.c

设置时钟

此示例说明如何设置要在 DOCA Rivermax 内部使用的 PTP 时钟设备。

示例逻辑包括

使用给定的 PCIe 地址打开 DOCA 设备。
初始化 DOCA Rivermax 库。
设置设备以用于获取 PTP 时间。
释放 DOCA Rivermax 库。

参考

/opt/mellanox/doca/samples/doca_rmax/rmax_set_clock/rmax_set_clock_sample.c
/opt/mellanox/doca/samples/doca_rmax/rmax_set_clock/rmax_set_clock_main.c
/opt/mellanox/doca/samples/doca_rmax/rmax_set_clock/meson.build
/opt/mellanox/doca/samples/doca_rmax/rmax_common.h; /opt/mellanox/doca/samples/doca_rmax/rmax_common.c

创建流

此示例说明如何创建流，创建流并将其附加到创建的流，最后开始接收数据缓冲区（基于附加的流）。

示例逻辑包括

使用给定的 PCIe 地址打开 DOCA 设备。
初始化 DOCA Rivermax 库。
创建输入流。
从创建的流创建上下文。
初始化 DOCA Core 相关对象。
设置创建的流的属性。
创建流并将其附加到创建的流。
开始接收数据缓冲区。
清理—分离流并销毁它，销毁创建的流和 DOCA Core 相关对象。

参考

/opt/mellanox/doca/samples/doca_rmax/rmax_create_stream/rmax_create_stream_sample.c
/opt/mellanox/doca/samples/doca_rmax/rmax_create_stream/rmax_create_stream_main.c
/opt/mellanox/doca/samples/doca_rmax/rmax_create_stream/meson.build
/opt/mellanox/doca/samples/doca_rmax/rmax_common.h; /opt/mellanox/doca/samples/doca_rmax/rmax_common.c

创建流 – 头部数据分离模式

此示例说明如何在头部数据分离模式下创建流，此时数据包头部和有效负载被拆分到不同的 RX 缓冲区。

示例逻辑包括

使用给定的 PCIe 地址打开 DOCA 设备。
初始化 DOCA Rivermax 库。
创建输入流。
从创建的流创建上下文。
初始化 DOCA Core 相关对象。
设置创建的流的属性。链接缓冲区并将头部大小设置为非零对于创建具有头部数据分离模式的流至关重要。
创建流并将其附加到创建的流。
开始接收数据以拆分缓冲区。
清理—分离流并销毁它，销毁创建的流和 DOCA Core 相关对象。

参考

/opt/mellanox/doca/samples/doca_rmax/rmax_create_stream_hds/rmax_create_stream_hds_sample.c
/opt/mellanox/doca/samples/doca_rmax/rmax_create_stream_hds/rmax_create_stream_hds_main.c
/opt/mellanox/doca/samples/doca_rmax/rmax_create_stream_hds/meson.build
/opt/mellanox/doca/samples/doca_rmax/rmax_common.h; /opt/mellanox/doca/samples/doca_rmax/rmax_common.c

本页内容