doca_error_t doca_eth_rxq_set_metadata_num(struct doca_eth_rxq *eth_rxq, uint8_t metadata_num)
doca_error_t doca_eth_rxq_set_flow_tag(struct doca_eth_rxq *eth_rxq, uint8_t enable_flow_tag)
doca_error_t doca_eth_rxq_set_rx_hash(struct doca_eth_rxq *eth_rxq, uint8_t enable_rx_hash)
doca_error_t doca_eth_rxq_cap_get_max_metadata_num(const struct doca_devinfo *devinfo, uint8_t *max_metadata_num)
doca_error_t doca_eth_rxq_event_batch_managed_recv_get_l3_ok_array(const struct doca_eth_rxq_event_batch_managed_recv *event_batch_managed_recv, const uint8_t **l3_ok_array)
doca_error_t doca_eth_rxq_event_batch_managed_recv_get_l4_ok_array(const struct doca_eth_rxq_event_batch_managed_recv *event_batch_managed_recv, const uint8_t **l4_ok_array)
doca_error_t doca_eth_rxq_task_recv_get_metadata_array(const struct doca_eth_rxq_task_recv *task_recv, const uint32_t **metadata_array)
doca_error_t doca_eth_rxq_event_managed_recv_get_metadata_array(const struct doca_eth_rxq_event_managed_recv *event_managed_recv, const uint32_t **metadata_array)
doca_error_t doca_eth_rxq_event_batch_managed_recv_get_metadata_array(const struct doca_eth_rxq_event_batch_managed_recv *event_batch_managed_recv, const uint32_t **metadata_array)
doca_error_t doca_eth_rxq_task_recv_get_flow_tag(const struct doca_eth_rxq_task_recv *task_recv, uint32_t *flow_tag)
doca_error_t doca_eth_rxq_event_managed_recv_get_flow_tag(const struct doca_eth_rxq_event_managed_recv *event_managed_recv, uint32_t *flow_tag)
doca_error_t doca_eth_rxq_event_batch_managed_recv_get_flow_tag_array(const struct doca_eth_rxq_event_batch_managed_recv *event_batch_managed_recv, const uint32_t **flow_tag_array)
doca_error_t doca_eth_rxq_task_recv_get_rx_hash(const struct doca_eth_rxq_task_recv *task_recv, uint32_t *rx_hash)
doca_error_t doca_eth_rxq_event_managed_recv_get_rx_hash(const struct doca_eth_rxq_event_managed_recv *event_managed_recv, uint32_t *rx_hash)
doca_error_t doca_eth_rxq_event_batch_managed_recv_get_rx_hash_array(const struct doca_eth_rxq_event_batch_managed_recv *event_batch_managed_recv, const uint32_t **rx_hash_array)
#define doca_eth_rxq_event_batch_managed_recv_metadata_array_get_metadata(metadata_array, metadata_num, packet_index, metadata_index) metadata_array[packet_index * metadata_num + metadata_index]

ETH TXQ

doca_error_t doca_eth_txq_set_metadata_num(struct doca_eth_rxq *eth_txq, uint8_t metadata_num)
doca_error_t doca_eth_txq_cap_get_max_metadata_num(const struct doca_devinfo *devinfo, uint8_t *max_metadata_num)
doca_error_t doca_eth_txq_get_flow_queue_id(struct doca_eth_txq *eth_txq, uint16_t *flow_queue_id)
doca_error_t doca_eth_txq_task_send_get_metadata_array(struct doca_eth_txq_task_send *task_send, uint32_t **metadata_array)
doca_error_t doca_eth_txq_task_lso_send_get_metadata_array(struct doca_eth_txq_task_lso_send *task_lso_send, uint32_t **metadata_array)
doca_error_t doca_eth_txq_task_batch_send_get_metadata_array(struct doca_task_batch *task_batch_send, uint32_t **metadata_array)
doca_error_t doca_eth_txq_task_batch_lso_send_get_metadata_array(struct doca_task_batch *task_batch_lso_send, uint32_t **metadata_array)
void doca_eth_txq_task_send_set_ol_flags(struct doca_eth_txq_task_send *task_send, uint16_t ol_flags)
void doca_eth_txq_task_lso_send_set_ol_flags(struct doca_eth_txq_task_lso_send *task_lso_send, uint16_t ol_flags)
doca_error_t doca_eth_txq_task_batch_send_get_ol_flags_array(struct doca_task_batch *task_batch_send, uint16_t **ol_flags_array)
doca_error_t doca_eth_txq_task_batch_lso_send_get_ol_flags_array(struct doca_task_batch *task_batch_lso_send, uint16_t **ol_flags_array)
void doca_eth_txq_task_lso_send_set_mss(struct doca_eth_txq_task_lso_send *task_lso_send, uint16_t mss)
doca_error_t doca_eth_txq_task_batch_lso_send_get_mss_array(struct doca_task_batch *task_batch_lso_send, uint16_t **mss_array)
#define doca_eth_txq_task_batch_metadata_array_get_metadata(metadata_array, metadata_num, packet_index, metadata_index) metadata_array[packet_index * metadata_num + metadata_index]

修改

ETH RXQ

typedef void (*doca_eth_rxq_event_batch_managed_recv_handler_cb_t)(uint16_t events_number, union doca_data event_batch_user_data, doca_error_t status, struct doca_buf **pkt_array, uint8_t *l3_ok_array, uint8_t *l4_ok_array)
- → typedef void (*doca_eth_rxq_event_batch_managed_recv_handler_cb_t)(struct doca_eth_rxq_event_batch_managed_recv *event_batch_managed_recv, uint16_t events_number, union doca_data event_batch_user_data, doca_error_t status, struct doca_buf **pkt_array)

ETH TXQ

不适用

环境

基于 DOCA ETH 的应用程序可以在 Linux 主机或 NVIDIA® BlueField® DPU 目标上运行。以下是必需的

应用程序应以 root 权限运行
应用程序需要使用 DOCA Flow 将传入流量转发到 DOCA ETH RXQ 的队列。有关参考，请参见 DOCA Flow 和 DOCA ETH RXQ 示例。

信息

确保系统有用于 DOCA Flow 的空闲巨页。

架构

DOCA ETH 由两部分组成：DOCA ETH RXQ 和 DOCA ETH TXQ。

DOCA ETH RXQ

运行模式

DOCA ETH RXQ 可以在三种模式下运行，每种模式都公开略有不同的控制/数据路径。

常规接收

信息

此模式仅支持 CPU 数据路径。

在此模式下，接收到的数据包缓冲区由用户管理。要接收数据包，用户应提交包含 doca_buf 的接收任务，以将数据包写入其中。

如果应用程序想要执行以下操作，则可以使用此模式

在 CPU 上运行
管理接收到的数据包的内存和数据包在内存中的确切位置
将接收到的数据包转发到其他 DOCA 库

regular-receive-version-1-modificationdate-1725255457140-api-v2.png

循环接收

信息

此模式仅支持 GPU 数据路径。

在此模式下，库以循环方式将数据包分散到数据包缓冲区（由用户作为 doca_mmap 提供）。如果应用程序处理速度不够快，用户获取的数据包可能会被库覆盖。

在此模式下，用户必须为 DOCA ETH RXQ 提供一个由库管理的数据包缓冲区（参见 doca_eth_rxq_set_pkt_buf()）。缓冲区应足够大，以避免数据包丢失（参见 doca_eth_rxq_estimate_packet_buf_size()）。

如果应用程序符合以下条件，则可以使用此模式

想要在 GPU 上运行
具有确定性的数据包处理时间，保证在库用新数据包覆盖之前处理数据包
想要获得最佳性能

cyclic-receive-version-1-modificationdate-1725255457407-api-v2.png

托管内存池接收

信息

此模式仅支持 CPU 数据路径。

在此模式下，库使用各种优化来管理数据包缓冲区。用户获取的数据包不会被库覆盖，除非应用程序显式释放它们。因此，如果应用程序释放数据包缓冲区的速度不够快，库将耗尽内存，数据包将开始丢失。

与循环接收模式不同，用户可以将数据包传递给 DOCA 中的其他库，并保证数据包在被这些库处理时不会被覆盖。

如果应用程序符合以下条件，则可以使用此模式

想要在 CPU 上运行
具有确定性的数据包处理时间，保证在库耗尽内存和数据包开始丢失之前处理数据包
想要将接收到的数据包转发到其他 DOCA 库
想要获得最佳性能

managed-memory-pool-receive-version-1-modificationdate-1725255457717-api-v2.png

使用 DOCA Flow

要将传入数据包路由到所需的 DOCA ETH RXQ，应用程序需要使用 DOCA Flow。应用程序需要执行以下操作

在适当的端口（设备）上创建并启动 DOCA Flow
创建管道以将数据包路由到
使用 doca_eth_rxq_get_flow_queue_id() 获取队列的队列 ID（在 DOCA ETH RXQ 内部）
向管道添加条目，将数据包路由到 RX 队列（使用我们获得的队列 ID）

working-with-doca-flow-version-1-modificationdate-1725255458067-api-v2.png

有关更多详细信息，请参见 DOCA ETH RXQ 示例和 DOCA Flow。

大型分段卸载 (LSO) – 硬件支持在通过 IPv4 和 IPv6 传输的 TCP 数据包上进行 LSO。LSO 使软件能够准备大型 TCP 消息以进行发送，并使用标头模板（应用程序应向库提供此标头），该模板针对每个生成的分段自动更新。硬件将大型 TCP 消息分段为多个 TCP 分段。对于每个这样的分段，设备都会相应地更新标头模板（参见 LSO 发送任务）。
L3/L4 校验和卸载 – 硬件支持计算传输数据包的校验和以及验证接收数据包校验和。校验和计算支持在 IPv4 和 IPv6 上运行的 TCP/UDP。（在隧道的情况下，硬件计算外部标头的校验和。）硬件不需要任何伪标头校验和计算，并且在执行计算时会忽略放置在 TCP/UDP 校验和中的值。参见 doca_eth_txq_set_l3_chksum_offload()/doca_eth_txq_set_l4_chksum_offload()。
元数据支持 – 对于 RXQ，硬件支持检索在数据包流表处理期间收集的元数据值（参见 doca_eth_rxq_set_metadata_num()）。对于 TXQ，硬件支持附加元数据值，该值被带入传输流表处理中（参见 doca_eth_txq_set_metadata_num()）。
流标签 – 对于 RXQ，硬件支持检索软件（例如，DOCA Flow）在创建流条目时设置的流标签值（参见 doca_eth_rxq_set_flow_tag()）。
RX 哈希 – 对于 RXQ，硬件支持检索数据包的 RX 哈希值（参见 doca_eth_rxq_set_rx_hash()）。

对象

doca_mmap – 在循环接收和托管内存池接收模式下，用户必须将 DOCA ETH RXQ 配置为数据包缓冲区，以将接收到的数据包写入为 doca_mmap （参见 DOCA Core 内存子系统）
doca_buf – 在常规接收模式下，用户必须提交接收任务，其中包括一个缓冲区，用于将接收到的数据包写入为 doca_buf。此外，在常规发送模式下，用户必须提交发送任务，其中包括一个数据包缓冲区，用于将要发送的数据包作为 doca_buf 发送（参见 DOCA Core 内存子系统）。

配置阶段

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

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

注意

GPU 数据路径中的 DOCA ETH 不需要与 DOCA PE 关联（因为数据路径不在 CPU 上）。

必须至少配置一种任务/事件/事件批处理类型。有关更多信息，请参阅任务/事件/事件批处理。
最大数据包大小（可以接收的数据包的最大大小）必须在创建 DOCA ETH RXQ 上下文时提供
最大突发大小（库可以同时处理的最大数据包数量）必须在创建 DOCA ETH RXQ 上下文时提供
在创建时必须提供具有适当支持的设备
在循环接收或托管内存池接收模式下，必须提供 doca_mmap 以便写入接收到的数据包（参见 doca_eth_rxq_set_pkt_buf()）
对于 GPU 数据路径，必须使用 doca_ctx_set_datapath_on_gpu() 提供 DOCA GPU 子设备

DOCA ETH TXQ

必须至少配置一种任务/任务批处理类型。有关更多信息，请参阅任务/任务批处理。
最大突发大小（库可以同时处理的最大数据包数量）必须在创建 DOCA ETH TXQ 上下文时提供
在创建时必须提供具有适当支持的设备
对于 GPU 数据路径，必须使用 doca_ctx_set_datapath_on_gpu() 提供 DOCA GPU 子设备

可选配置

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

DOCA ETH RXQ

RXQ 模式 – 用户可以使用 doca_eth_rxq_set_type() 设置工作模式。默认类型为常规接收。
最大接收缓冲区列表长度 – 用户可以使用 doca_eth_rxq_set_max_recv_buf_list_len() 将缓冲区列表/链的最大长度设置为接收缓冲区。默认值为 1。
元数据数量 – 用户可以使用 doca_eth_rxq_set_metadata_num() 设置每个数据包检索的元数据数量。默认值为 0（即，不检索元数据）。
流标签 – 用户可以使用 doca_eth_rxq_set_flow_tag() 启用/禁用每个数据包检索的流标签。默认值为 0（即，不检索流标签）。
RX 哈希 – 用户可以使用 doca_eth_rxq_set_rx_hash() 启用/禁用每个数据包检索的 RX 哈希。默认值为 0（即，不检索 RX 哈希）。

DOCA ETH TXQ

TXQ 模式 – 用户可以使用 doca_eth_txq_set_type() 设置工作模式。默认类型为常规发送。
最大发送缓冲区列表长度 – 用户可以使用 doca_eth_txq_set_max_send_buf_list_len() 将缓冲区列表/链的最大长度设置为发送缓冲区。默认值为 1。
L3/L4 卸载校验和 – 用户可以使用 doca_eth_txq_set_l3_chksum_offload()/doca_eth_txq_set_l4_chksum_offload() 启用/禁用默认 L3/L4 校验和卸载。默认情况下禁用。
MSS – 用户可以使用 doca_eth_txq_set_mss() 为 LSO 发送任务/任务批处理设置默认 MSS（最大分段大小）值。默认值为 1500。
最大 LSO 标头大小 – 用户可以使用 doca_eth_txq_set_max_lso_header_size() 为 LSO 发送任务/任务批处理设置最大 LSO 标头大小。默认值为 74。
元数据数量 – 用户可以使用 doca_eth_txq_set_metadata_num() 设置每个数据包附加的元数据数量。默认值为 0（即，不附加元数据）。

设备支持

DOCA ETH 需要设备才能运行。有关选择设备的信息，请参见 DOCA Core 设备发现。

要检查设备是否支持特定模式，请使用类型功能函数（参见 doca_eth_rxq_cap_is_type_supported() 和 doca_eth_txq_cap_is_type_supported()）。

设备可以允许以下功能

最大突发大小
最大缓冲区链列表（仅适用于常规接收/常规发送模式）
最大数据包大小（仅适用于 DOCA ETH RXQ）
L3/L4 校验和卸载功能（仅适用于 DOCA ETH TXQ）
最大 LSO 消息/标头大小（仅适用于 DOCA ETH TXQ）
等待时间卸载功能（仅适用于 GPU 数据路径中的 DOCA ETH TXQ）
最大元数据数量功能（仅适用于 CPU 数据路径）

缓冲区支持

DOCA ETH 支持具有以下功能的缓冲区（ doca_mmap 或 doca_buf ）

缓冲区类型	发送任务	LSO 发送任务	接收任务	托管接收事件
本地 mmap 缓冲区	是	是	是	是
来自 PCIe 导出的 mmap 缓冲区	是	是	是	是
来自 RDMA 导出的 mmap 缓冲区	否	否	否	否
链接列表缓冲区	是	是	是	否

有关 GPU 数据路径情况下的缓冲区支持，请参见 DOCA GPUNetIO 编程指南。

执行阶段

本节介绍在 CPU 上使用 DOCA Core 进度引擎执行（除非另有说明）。

注意

有关 GPU 数据路径的信息，请参见 DOCA GPUNetIO。

描述	设置配置的 API	查询支持的 API
启用任务	调用 `doca_eth_rxq_task_recv_set_conf()`	`doca_eth_rxq_cap_is_type_supported()` 检查对常规接收模式的支持
任务数量	`task_recv_num` 在 `doca_eth_rxq_task_recv_set_conf()` 中	–
最大接收缓冲区列表长度	`doca_eth_rxq_set_max_recv_buf_list_len()` （默认值为 1）	`doca_eth_rxq_cap_get_max_recv_buf_list_len()`
最大数据包大小	`max_packet_size` 在 `doca_eth_rxq_create()` 中	`doca_eth_rxq_cap_get_max_packet_size()`
元数据数量	`metadata_num` 在 `doca_eth_rxq_set_metadata_num()` 中	`doca_eth_rxq_cap_get_max_metadata_num()`
启用流标签	`enable_flow_tag` 在 `doca_eth_rxq_set_flow_tag()` 中	–
启用 RX 哈希	`enable_rx_hash` 在 `doca_eth_rxq_set_rx_hash()` 中	–

任务输入

与 DOCA Core 任务中描述的通用输入相同。

名称	描述	注释
数据包缓冲区	指向要写入接收数据包的内存的缓冲区	接收到的数据包被写入尾部段，扩展数据段

任务输出

与 DOCA Core 任务中描述的通用输出相同。

此外

名称	描述	注释
L3 校验和结果	指示接收数据包的 L3 校验和是否有效的值	可以使用 `doca_eth_rxq_task_recv_get_l3_ok()` 查询
L4 校验和结果	指示接收数据包的 L4 校验和是否有效的值	可以使用 `doca_eth_rxq_task_recv_get_l4_ok()` 查询
元数据数组	包含与数据包关联的元数据值的数组	可以使用 `doca_eth_rxq_task_recv_get_metadata_array()` 查询
流标签	与数据包关联的流标签值	可以使用 `doca_eth_rxq_task_recv_get_flow_tag()` 查询
RX 哈希	与数据包关联的 RX 哈希值	可以使用 `doca_eth_rxq_task_recv_get_rx_hash()` 查询

任务完成成功

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

接收到的数据包被写入数据包缓冲区
数据包缓冲区数据段被扩展以包含接收到的数据包

任务完成失败

如果任务中途失败

上下文进入停止状态
数据包缓冲区 doca_buf 对象未修改
数据包缓冲区内容可能会被修改

任务限制

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

此外

操作不是原子的。
提交任务后，不应读取/写入数据包缓冲区。

描述	设置配置的 API	查询支持的 API
启用任务	调用 `doca_eth_txq_task_send_set_conf()`	`doca_eth_txq_cap_is_type_supported()` 检查对常规发送模式的支持
任务数量	`task_send_num` 在 `doca_eth_txq_task_send_set_conf()` 中注意可以使用 `doca_eth_txq_task_send_num_expand()` 扩展任务数量。	–
最大发送缓冲区列表长度	`doca_eth_txq_set_max_send_buf_list_len()` （默认值为 1）	`doca_eth_txq_cap_get_max_send_buf_list_len()`
默认 L3/L4 卸载校验和	`doca_eth_txq_set_l3_chksum_offload()` `doca_eth_txq_set_l4_chksum_offload()` 信息默认情况下禁用。	`doca_eth_txq_cap_is_l3_chksum_offload_supported()` `doca_eth_txq_cap_is_l4_chksum_offload_supported()`
元数据数量	`metadata_num` 在 `doca_eth_txq_set_metadata_num()` 中	`doca_eth_txq_cap_get_max_metadata_num()`

任务输入

与 DOCA Core 任务中描述的通用输入相同。

名称	描述	注释
数据包缓冲区	指向要发送的数据包的缓冲区	发送的数据包是数据段中的内存
元数据值	元数据数组，包含要附加到数据包的元数据值	数组长度是 `metadata_num`*`metadata_num` 在 `doca_eth_txq_set_metadata_num()` 中
卸载标志	要与特定数据包关联的卸载标志（如果用户想要覆盖默认值）	卸载标志是 `enum doca_eth_txq_ol_flags` 中值的位掩码

上下文进入停止状态
数据包缓冲区 doca_buf 对象未修改

任务限制

操作不是原子的
提交任务后，不应写入数据包缓冲区
其他限制在 DOCA Core 任务中描述

LSO 发送任务

此任务允许从 doca_dev 发送“大型”数据包（大于 MTU）（硬件将数据包拆分为几个小于 MTU 的数据包并发送它们）。

任务配置

描述	设置配置的 API	查询支持的 API
启用任务	调用 `doca_eth_txq_task_lso_send_set_conf()`	`doca_eth_txq_cap_is_type_supported()` 检查对常规发送模式的支持
任务数量	`task_lso_send_num` 在 `doca_eth_txq_task_lso_send_set_conf()` 中注意可以使用 `doca_eth_txq_task_lso_send_num_expand()` 扩展任务数量。	–
最大发送缓冲区列表长度	`doca_eth_txq_set_max_send_buf_list_len()` （默认值为 1）	`doca_eth_txq_cap_get_max_send_buf_list_len()`
默认 L3/L4 卸载校验和	`doca_eth_txq_set_l3_chksum_offload()` `doca_eth_txq_set_l4_chksum_offload()` 信息默认情况下禁用。	`doca_eth_txq_cap_is_l3_chksum_offload_supported()` `doca_eth_txq_cap_is_l4_chksum_offload_supported()`
默认 MSS	`doca_eth_txq_set_mss()` （默认值为 1500）	–
最大 LSO 标头大小	`doca_eth_txq_set_max_lso_header_size()` （默认值为 74）	`doca_eth_txq_cap_get_max_lso_header_size()`
元数据数量	`metadata_num` 在 `doca_eth_txq_set_metadata_num()` 中	`doca_eth_txq_cap_get_max_metadata_num()`

任务输入

与 DOCA Core 任务中描述的通用输入相同。

名称	描述	注释
数据包有效负载缓冲区	指向要发送的“大型”数据包的有效负载（不包括标头）的缓冲区	发送的数据包是数据段中的内存
数据包标头缓冲区	收集列表，组合后包括要发送的“大型”数据包的标头	参见 `struct doca_gather_list`
元数据值	元数据数组，包含要附加到数据包的元数据值	数组长度是 `metadata_num`*`metadata_num` 在 `doca_eth_txq_set_metadata_num()` 中
卸载标志	要与特定数据包关联的卸载标志（如果用户想要覆盖默认值）	卸载标志是 `enum doca_eth_txq_ol_flags` 中值的位掩码
MSS	要与 LSO 数据包关联的 MSS（如果用户想要覆盖默认值）	–

上下文进入停止状态
数据包有效负载缓冲区 doca_buf 对象和数据包标头缓冲区 doca_gather_list 未修改

任务限制

操作不是原子的
提交任务后，不应写入数据包有效负载缓冲区和数据包标头缓冲区
其他限制在 DOCA Core 任务中描述

描述	设置配置的 API	查询支持的 API
注册事件	`doca_eth_rxq_event_managed_recv_register()`	`doca_eth_rxq_cap_is_type_supported()` 检查对托管内存池接收模式的支持
元数据数量	`metadata_num` 在 `doca_eth_rxq_set_metadata_num()` 中	`doca_eth_rxq_cap_get_max_metadata_num()`
启用流标签	`enable_flow_tag` 在 `doca_eth_rxq_set_flow_tag()` 中	–
启用 RX 哈希	`enable_rx_hash` 在 `doca_eth_rxq_set_rx_hash()` 中	–

事件触发条件

每次收到数据包时都会触发事件。

事件成功处理程序

调用成功回调（在事件注册中提供），并且用户应执行以下操作

使用 pkt 参数处理接收到的数据包
使用 event_user_data 获取应用程序上下文
查询数据包的 L3/L4 校验和结果
查询与数据包关联的元数据值的元数据数组
查询与数据包关联的流标签值
查询与数据包关联的 RX 哈希值
释放 pkt （ doca_buf 对象）并将其返回到库

注意

不释放 pkt 可能会导致数据包丢失的情况。

事件失败处理程序

调用失败回调（在事件注册中提供），并且会发生以下情况

上下文进入停止状态
pkt 参数变为 NULL
event_user_data 参数包含应用程序注册事件时提供的值

描述	设置配置的 API	查询支持的 API
注册事件	`doca_eth_txq_gpu_event_error_send_packet_register()`	始终支持

事件触发条件

发送数据包失败时会触发事件。

事件处理程序

调用回调（在事件注册中提供），用户可以

获取 TXQ 发送失败的数据包的位置（索引）

通知发送数据包

当在 GPU 数据路径上运行 DOCA ETH 时，此事件相关（参见 DOCA GPUNetIO）。它在每次成功发送数据包时通知用户。

事件配置

描述	设置配置的 API	查询支持的 API
注册事件	`doca_eth_txq_gpu_event_notify_send_packet_register()`	始终支持

事件触发条件

发送数据包失败时会触发事件。

事件处理程序

调用回调（在事件注册中提供），用户可以

获取已发送数据包的位置（索引）
发送数据包的时间戳

描述	设置配置的 API	查询支持的 API
启用任务批处理	调用 `doca_eth_txq_task_batch_send_set_conf()`	`doca_eth_txq_cap_is_type_supported()` 检查对常规发送模式的支持
任务批处理数量	`num_task_batches` 在 `doca_eth_txq_task_batch_send_set_conf()` 中信息可以使用 `doca_eth_txq_task_batch_send_num_expand()` 扩展任务批处理数量。	–
每个任务批处理的最大任务数	`max_tasks_number` 在 `doca_eth_txq_task_batch_send_set_conf()` 中	–
最大发送缓冲区列表长度	`doca_eth_txq_set_max_send_buf_list_len()` 信息默认情况下禁用。	`doca_eth_txq_cap_get_max_send_buf_list_len()`
默认 L3/L4 卸载校验和	`doca_eth_txq_set_l3_chksum_offload()` `doca_eth_txq_set_l4_chksum_offload()` 信息默认情况下禁用。	`doca_eth_txq_cap_is_l3_chksum_offload_supported()` `doca_eth_txq_cap_is_l4_chksum_offload_supported()`
元数据数量	`metadata_num` 在 `doca_eth_txq_set_metadata_num()` 中	`doca_eth_txq_cap_get_max_metadata_num()`

任务输入

名称	描述	注释
任务数量	任务批处理“背后”的发送任务数量	此数字等于要发送的数据包数量
批处理用户数据	与任务批处理关联的用户数据	–
数据包数组	指向缓冲区数组的指针，这些缓冲区指向每个任务要发送的数据包	发送的数据包是每个缓冲区的数据段中的内存
用户数据数组	指向每个任务的用户数据数组的指针	–
元数据数组	指向每个任务的元数据数组的指针	数组长度为 `tasks_num`*`metadata_num` 在 `doca_eth_txq_set_metadata_num()` 中信息参见 `doca_eth_txq_task_batch_metadata_array_get_metadata()` 宏。
卸载标志数组	指向每个任务的卸载标志数组的指针（如果用户想要覆盖默认值）	卸载标志是 `enum doca_eth_txq_ol_flags` 中值的位掩码

任务输出

名称	描述
状态数组	指向已完成任务批处理的每个任务的状态数组的指针

任务完成成功

如果所有发送任务都成功完成并且所有数据包都进入了设备的 TX 硬件，则任务批处理完成。“数据包数组”中的所有数据包现在都归用户所有。

任务完成失败

如果任务批次失败，则与该任务批次关联的一个或多个任务失败。用户可以查看“状态数组”以了解哪个任务/数据包导致了失败。

此外，预期会有以下行为

上下文进入停止状态
数据包的 doca_buf 对象不会被修改

任务限制

除了所有的发送任务限制之外

任务批次完成仅在所有任务都完成时发生（无部分完成）

LSO 发送任务批次

这是一个针对 LSO 发送任务的扩展任务批次，允许从 doca_dev 批量发送 LSO 数据包。

任务配置

描述	设置配置的 API	查询支持的 API
启用任务批处理	调用 `doca_eth_txq_task_batch_lso_send_set_conf()`	`doca_eth_txq_cap_is_type_supported()` 检查对常规发送模式的支持
任务批处理数量	`doca_eth_txq_task_batch_lso_send_set_conf()` 中的 `num_task_batches` 信息任务批次的数量可以使用 `doca_eth_txq_task_batch_lso_send_num_expand()` 扩展。	–
每个任务批处理的最大任务数	`doca_eth_txq_task_batch_lso_send_set_conf()` 中的 `num_task_batches`	–
最大发送缓冲区列表长度	`doca_eth_txq_set_max_send_buf_list_len()` 信息默认值为 1。	`doca_eth_txq_cap_get_max_send_buf_list_len()`
默认 L3/L4 卸载校验和	`doca_eth_txq_set_l3_chksum_offload()` `doca_eth_txq_set_l4_chksum_offload()` 信息默认情况下禁用。	`doca_eth_txq_cap_is_l3_chksum_offload_supported()` `doca_eth_txq_cap_is_l4_chksum_offload_supported()`
默认 MSS	`doca_eth_txq_set_mss()` 信息默认值为 1500。	–
最大 LSO 标头大小	`doca_eth_txq_set_max_lso_header_size()` （默认值为 74）	`doca_eth_txq_cap_get_max_lso_header_size()`
元数据数量	`metadata_num` 在 `doca_eth_txq_set_metadata_num()` 中	`doca_eth_txq_cap_get_max_metadata_num()`

任务输入

名称	描述	注释
任务数量	任务批处理“背后”的发送任务数量	此数字等于要发送的数据包数量
批处理用户数据	与任务批处理关联的用户数据	–
数据包有效负载数组	指向缓冲区数组的指针，该数组指向每个任务要发送的“大型”数据包的有效负载	发送的数据包有效负载是每个缓冲区数据段中的内存
数据包标头数组	指向 gather list 数组的指针，每个 gather list 在组合时会组装成每个任务要发送的“大型”数据包的标头	参见 `struct doca_gather_list`
用户数据数组	指向每个任务的用户数据数组的指针	–
元数据数组	指向每个任务的元数据数组的指针	数组长度为 `tasks_num`*`metadata_num` 在 `doca_eth_txq_set_metadata_num()` 中信息参见 `doca_eth_txq_task_batch_metadata_array_get_metadata()` 宏。
卸载标志数组	指向每个任务的卸载标志数组的指针（如果用户想要覆盖默认值）	卸载标志是 `enum doca_eth_txq_ol_flags` 中值的位掩码
MSS 数组	指向每个任务 MSS 的数组的指针（如果用户想要覆盖默认值）	–

任务输出

名称	描述
状态数组	指向已完成任务批次的每个任务状态的数组的指针

任务完成成功

如果所有 LSO 发送任务都成功完成，并且所有数据包都进入了设备的 TX 硬件，则任务批次完成。“数据包有效负载数组”中的所有数据包有效负载和“数据包标头数组”中的数据包标头现在都归用户所有。

任务完成失败

如果任务批次失败，则与该任务批次关联的一个或多个任务失败，用户可以查看“状态数组”以尝试找出哪个任务/数据包导致了失败。

此外，预期会有以下行为

上下文进入停止状态
数据包有效负载 doca_buf 对象不会被修改
数据包标头 doca_gather_list 对象不会被修改

任务限制

除了所有的 LSO 发送任务限制之外

任务批次完成仅在所有任务都完成时发生（无部分完成）

描述	设置配置的 API	查询支持的 API
注册到事件批次	调用 `doca_eth_rxq_event_batch_managed_recv_register()`	`doca_eth_rxq_cap_is_type_supported()` 检查对托管内存池接收模式的支持
最大事件数：等于每个事件批次完成的最大已完成事件数	`doca_eth_rxq_event_batch_managed_recv_register()` 中的 `events_number_max`	–
最小事件数：等于每个事件批次完成的最小已完成事件数	`doca_eth_rxq_event_batch_managed_recv_register()` 中的 `events_number_min`	–
元数据数量	`metadata_num` 在 `doca_eth_rxq_set_metadata_num()` 中	`doca_eth_rxq_cap_get_max_metadata_num()`
启用流标签	`enable_flow_tag` 在 `doca_eth_rxq_set_flow_tag()` 中	–
启用 RX 哈希	`enable_rx_hash` 在 `doca_eth_rxq_set_rx_hash()` 中	–

事件触发条件

每次收到多个数据包（数量介于“最小事件数”和“最大事件数”之间）时，都会触发事件批次。

事件批次成功处理程序

将调用成功回调（在事件批次注册中提供），并且用户应执行以下操作

通过 events_number 识别接收到的数据包数量。
使用 pkt_array 参数处理接收到的数据包。
使用 event_batch_user_data 获取应用程序上下文。
使用 l3_ok_array 和 l4_ok_array 查询数据包的 L3/L4 校验和结果。
使用 metadata_array 查询与数据包关联的元数据值的元数据数组。
使用 flow_tag_array 查询与数据包关联的流标签值。
使用 rx_hash_array 查询与数据包关联的 RX 哈希值。
从 pkt_array （doca_buf 对象）释放缓冲区并将其返回到库。可以通过两种方式完成此操作
- 迭代 pkt_array 中的缓冲区，并使用 doca_buf_dec_refcount() 释放它们。
- 一起释放 pkt_array 中的所有缓冲区（提供更好的性能），使用 doca_eth_rxq_event_batch_managed_recv_pkt_array_free() 。

事件批次失败处理程序

将调用失败回调（在事件批次注册中提供），并且会发生以下情况

上下文进入停止状态
pkt_array 参数为 NULL
l3_ok_array 参数为 NULL
l4_ok_array 参数为 NULL
event_batch_user_data 参数包含应用程序在注册事件时提供的值

销毁上下文
启动上下文

允许的操作

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

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

上一个状态	转换操作
无	创建上下文
运行中	在之后调用停止所有任务都已完成并释放托管接收事件回调返回的所有 `doca_buf` 对象都已释放
停止中	调用 progress 直到所有任务都已完成并释放托管接收事件回调返回的所有 `doca_buf` 对象都已释放

启动中

无法达到此状态。

运行中

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

分配和提交任务
调用 progress 以完成任务和/或接收事件

允许的操作

分配先前配置的任务
提交任务
调用 doca_eth_rxq_get_flow_queue_id() 以将 RX 队列连接到 DOCA Flow
调用 stop

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

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

停止中

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

调用 progress 以完成所有正在进行的任务（任务完成时失败）
释放任何已完成的任务
释放托管接收事件回调返回的 doca_buf 对象

允许的操作

调用 progress

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

上一个状态	转换操作
运行中	调用 progress 并且发生致命错误
运行中	调用 stop 而不执行以下任一操作释放所有任务释放托管接收事件回调返回的所有 `doca_buf` 对象

上一个状态

转换操作

运行中

调用 progress 并且发生致命错误

运行中

调用 stop 而不执行以下任一操作

释放所有任务
释放托管接收事件回调返回的所有 doca_buf 对象

替代数据路径选项

除了 CPU 数据路径（在执行阶段中提到）之外，DOCA ETH 还支持在 GPU 数据路径上运行。这允许应用程序从数据路径管理中释放 CPU，并允许对网络流量进行低延迟 GPU 处理。

要导出句柄，应用程序应在 doca_ctx_start() 之前调用 doca_ctx_set_datapath_on_gpu() 以编程库来设置 GPU 操作的上下文。

要获取 GPU 上下文句柄，用户应调用 doca_rxq_get_gpu_handle()，该函数返回指向 GPU 内存空间中句柄的指针。

注意

GPU 和 CPU 的数据路径不能同时进行管理。

DOCA ETH 上下文在 CPU 上配置，然后导出到 GPU

doca-eth-context-version-1-modificationdate-1725255458693-api-v2.png

以下示例显示了 GPU 管理的数据路径的预期流程，其中数据包被分散到 GPU 内存（对于 doca_eth_rxq）

创建 DOCA GPU 设备处理程序。
创建 doca_eth_rxq 并配置其参数。
将上下文的数据路径设置为 GPU。
启动上下文。
获取上下文的 GPU 句柄。

image-2023-10-12_8-40-19-version-1-modificationdate-1725255454377-api-v2.png

有关 GPU 数据路径的更多信息，请参阅 DOCA GPUNetIO。

DOCA ETH 示例

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

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

使用 DOCA ETH TXQ 发送“常规”数据包（小于 MTU）
使用 DOCA ETH TXQ 发送“大型”数据包（大于 MTU）
在常规接收模式下使用 DOCA ETH RXQ 接收数据包
在托管内存池接收模式下使用 DOCA ETH RXQ 接收数据包

信息

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

运行示例

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

要构建给定的示例（例如，eth_txq_send_ethernet_frames):

复制
已复制！

            
            cd /opt/mellanox/doca/samples/doca_eth/eth_txq_send_ethernet_frames
meson /tmp/build
ninja -C /tmp/build

二进制文件eth_txq_send_ethernet_frames在 /tmp/build/ 下创建。

示例（例如，eth_txq_send_ethernet_frames）用法

复制
已复制！

            
            Usage: doca_eth_txq_send_ethernet_frames [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, --device                      IB device name - default: mlx5_0
   -m, --mac-addr                    Destination MAC address to associate with the ethernet frames - default: FF:FF:FF:FF:FF:FF

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

复制
已复制！

            
            /tmp/build/<sample_name> -h

示例

注意

以下示例适用于 CPU 数据路径。有关 GPU 数据路径示例，请参阅 DOCA GPUNetIO。

ETH TXQ 发送以太网帧

此示例说明了如何使用 DOCA ETH TXQ 发送“常规”数据包（小于 MTU）。

示例逻辑包括

查找 DOCA 设备。
初始化所需的 DOCA Core 结构。
使用一个缓冲区填充 DOCA 内存映射到数据包的数据。
将数据包的内容写入分配的缓冲区。
从缓冲区的 DOCA 缓冲区库存中分配元素。
初始化和配置 DOCA ETH TXQ 上下文。
启动 DOCA ETH TXQ 上下文。
分配 DOCA ETH TXQ 发送任务。
将 DOCA ETH TXQ 发送任务提交到进度引擎。
从进度引擎检索 DOCA ETH TXQ 发送任务。
使用提供的回调处理已完成的任务。
停止 DOCA ETH TXQ 上下文。
销毁 DOCA ETH TXQ 上下文。
销毁所有 DOCA Core 结构。

参考

/opt/mellanox/doca/samples/doca_eth/eth_txq_send_ethernet_frames/eth_txq_send_ethernet_frames_sample.c
/opt/mellanox/doca/samples/doca_eth/eth_txq_send_ethernet_frames/eth_txq_send_ethernet_frames_main.c
/opt/mellanox/doca/samples/doca_eth/eth_txq_send_ethernet_frames/meson.build

ETH TXQ LSO 发送以太网帧

此示例说明了如何使用 DOCA ETH TXQ 发送“大型”数据包（大于 MTU）。

示例逻辑包括

查找 DOCA 设备。
初始化所需的 DOCA Core 结构。
使用一个缓冲区填充 DOCA 内存映射到数据包的有效负载。
将数据包的有效负载写入分配的缓冲区。
从缓冲区的 DOCA 缓冲区库存中分配元素。
分配 DOCA gather list，其中包含一个节点到数据包的标头。
将数据包的标头写入分配的 gather list 节点。
初始化和配置 DOCA ETH TXQ 上下文。
启动 DOCA ETH TXQ 上下文。
分配 DOCA ETH TXQ LSO 发送任务。
将 DOCA ETH TXQ LSO 发送任务提交到进度引擎。
从进度引擎检索 DOCA ETH TXQ LSO 发送任务。
使用提供的回调处理已完成的任务。
停止 DOCA ETH TXQ 上下文。
销毁 DOCA ETH TXQ 上下文。
销毁所有 DOCA Core 结构。

参考

/opt/mellanox/doca/samples/doca_eth/eth_txq_lso_send_ethernet_frames/eth_txq_lso_send_ethernet_frames_sample.c
/opt/mellanox/doca/samples/doca_eth/eth_txq_lso_send_ethernet_frames/eth_txq_lso_send_ethernet_frames_main.c
/opt/mellanox/doca/samples/doca_eth/eth_txq_lso_send_ethernet_frames/meson.build

ETH TXQ 批处理发送以太网帧

此示例说明了如何使用 DOCA ETH TXQ 发送一批“常规”数据包（小于 MTU）。

示例逻辑包括

查找 DOCA 设备。
初始化所需的 DOCA Core 结构。
使用多个缓冲区填充 DOCA 内存映射，每个缓冲区代表一个数据包的数据。
将数据包的内容写入分配的缓冲区。
从缓冲区的 DOCA 缓冲区库存中分配元素。
初始化和配置 DOCA ETH TXQ 上下文。
启动 DOCA ETH TXQ 上下文。
分配 DOCA ETH TXQ 发送任务批次。
将所有缓冲区的指针复制到任务批次的pkt_arry.
将 DOCA ETH TXQ 发送任务批次提交到进度引擎。
从进度引擎检索 DOCA ETH TXQ 发送任务批次。
使用提供的回调处理已完成的任务批次。
停止 DOCA ETH TXQ 上下文。
销毁 DOCA ETH TXQ 上下文。
销毁所有 DOCA Core 结构。

参考

/opt/mellanox/doca/samples/doca_eth/eth_txq_batch_send_ethernet_frames/eth_txq_batch_send_ethernet_frames_sample.c
/opt/mellanox/doca/samples/doca_eth/eth_txq_batch_send_ethernet_frames/eth_txq_batch_send_ethernet_frames_main.c
/opt/mellanox/doca/samples/doca_eth/eth_txq_batch_send_ethernet_frames/meson.build

ETH TXQ 批处理 LSO 发送以太网帧

此示例说明了如何使用 DOCA ETH TXQ 发送一批“大型”数据包（大于 MTU）。

示例逻辑包括

查找 DOCA 设备。
初始化所需的 DOCA Core 结构。
使用多个缓冲区填充 DOCA 内存映射，每个缓冲区代表一个数据包的有效负载。
将数据包的有效负载写入分配的缓冲区。
从缓冲区的 DOCA 缓冲区库存中分配元素。
分配 DOCA gather list，每个 gather list 包含一个节点用于数据包的标头。
将数据包的标头写入分配的 gather list 节点。
初始化和配置 DOCA ETH TXQ 上下文。
启动 DOCA ETH TXQ 上下文。
分配 DOCA ETH TXQ LSO 发送任务。
将所有缓冲区的指针复制到任务批次的pkt_payload_arry.
将所有 gather list 的指针复制到任务批次的headers_arry.
将 DOCA ETH TXQ LSO 发送任务批次提交到进度引擎。
从进度引擎检索 DOCA ETH TXQ LSO 发送任务批次。
使用提供的回调处理已完成的任务批次。
停止 DOCA ETH TXQ 上下文。
销毁 DOCA ETH TXQ 上下文。
销毁所有 DOCA Core 结构。

参考

/opt/mellanox/doca/samples/doca_eth/eth_txq_batch_lso_send_ethernet_frames/eth_txq_batch_lso_send_ethernet_frames_sample.c
/opt/mellanox/doca/samples/doca_eth/eth_txq_batch_lso_send_ethernet_frames/eth_txq_batch_lso_send_ethernet_frames_main.c
/opt/mellanox/doca/samples/doca_eth/eth_txq_batch_lso_send_ethernet_frames/meson.build

ETH RXQ 常规接收

此示例说明了如何在常规接收模式下使用 DOCA ETH RXQ 接收数据包。

示例逻辑包括

查找 DOCA 设备。
初始化所需的 DOCA Core 结构。
使用一个缓冲区填充 DOCA 内存映射到数据包的数据。
从每个缓冲区的 DOCA 缓冲区库存中分配元素。
初始化 DOCA Flow。
初始化和配置 DOCA ETH RXQ 上下文。
启动 DOCA ETH RXQ 上下文。
启动 DOCA Flow。
创建连接到 DOCA ETH RXQ 的 RX 队列的管道。
分配 DOCA ETH RXQ 接收任务。
将 DOCA ETH RXQ 接收任务提交到进度引擎。
从进度引擎检索 DOCA ETH RXQ 接收任务。
使用提供的回调处理已完成的任务。
停止 DOCA Flow。
停止 DOCA ETH RXQ 上下文。
销毁 DOCA ETH RXQ 上下文。
销毁 DOCA Flow。
销毁所有 DOCA Core 结构。

参考

/opt/mellanox/doca/samples/doca_eth/eth_rxq_regular_receive/eth_rxq_regular_receive_sample.c
/opt/mellanox/doca/samples/doca_eth/eth_rxq_regular_receive/eth_rxq_regular_receive_main.c
/opt/mellanox/doca/samples/doca_eth/eth_rxq_regular_receive/meson.build

ETH RXQ 托管接收

此示例说明了如何在托管内存池接收模式下使用 DOCA ETH RXQ 接收数据包。

示例逻辑包括

查找 DOCA 设备。
初始化所需的 DOCA Core 结构。
计算接收来自 DOCA ETH RXQ 的数据包所需的缓冲区大小。
使用数据包缓冲区填充 DOCA 内存映射。
初始化 DOCA Flow。
初始化和配置 DOCA ETH RXQ 上下文。
注册 DOCA ETH RXQ 托管接收事件。
启动 DOCA ETH RXQ 上下文。
启动 DOCA Flow。
创建连接到 DOCA ETH RXQ 的 RX 队列的管道。
从进度引擎检索 DOCA ETH RXQ 托管接收事件。
使用提供的回调处理已完成的事件。
停止 DOCA Flow。
停止 DOCA ETH RXQ 上下文。
销毁 DOCA ETH RXQ 上下文。
销毁 DOCA Flow。
销毁所有 DOCA Core 结构。

参考

/opt/mellanox/doca/samples/doca_eth/eth_rxq_managed_mempool_receive/eth_rxq_managed_mempool_receive_sample.c
/opt/mellanox/doca/samples/doca_eth/eth_rxq_managed_mempool_receive/eth_rxq_managed_mempool_receive_main.c
/opt/mellanox/doca/samples/doca_eth/eth_rxq_managed_mempool_receive/meson.build

ETH RXQ 批处理托管接收

此示例说明了如何在托管内存池接收模式下使用 DOCA ETH RXQ 接收批次数据包。

示例逻辑包括

查找 DOCA 设备。
初始化所需的 DOCA Core 结构。
计算接收来自 DOCA ETH RXQ 的数据包所需的缓冲区大小。
使用数据包缓冲区填充 DOCA 内存映射。
初始化 DOCA Flow。
初始化和配置 DOCA ETH RXQ 上下文。
注册 DOCA ETH RXQ 托管接收事件批次。
启动 DOCA ETH RXQ 上下文。
启动 DOCA Flow。
创建连接到 DOCA ETH RXQ 的 RX 队列的管道。
从进度引擎检索 DOCA ETH RXQ 托管接收事件批次。
使用提供的回调处理已完成的事件批次。
停止 DOCA Flow。
停止 DOCA ETH RXQ 上下文。
销毁 DOCA ETH RXQ 上下文。
销毁 DOCA Flow。
销毁所有 DOCA Core 结构。

参考

/opt/mellanox/doca/samples/doca_eth/eth_rxq_batch_managed_mempool_receive/eth_rxq_batch_managed_mempool_receive_sample.c
/opt/mellanox/doca/samples/doca_eth/eth_rxq_batch_managed_mempool_receive/eth_rxq_batch_managed_mempool_receive_main.c
/opt/mellanox/doca/samples/doca_eth/eth_rxq_batch_managed_mempool_receive/meson.build