DOCA PCC

本指南概述了 DOCA 可编程拥塞控制 (PCC) API 及其配置说明。

简介

DOCA PCC 库提供了一个高级编程接口，允许用户实现自己的自定义拥塞控制 (CC) 算法，从而促进其应用程序中网络拥塞的有效管理。

DOCA PCC 库提供了一个 API，用于

配置要发送和接收的探测数据包
获取 CC 事件/数据包并访问其字段
为流设置速率限制
维护每个流的上下文
启动和配置 CC 算法
获取从网络到达的请求数据包并设置返回的响应数据包

此库使用 NVIDIA® BlueField®-3 平台硬件加速进行 CC 管理，同时提供一个简化硬件复杂性的 API，使用户能够专注于 CC 算法的功能。

前提条件

基于 DOCA PCC 的应用程序可以在主机或 NVIDIA® BlueField®-3 平台（或更高版本）目标上运行。

信息

目前，DOCA PCC 仅支持以太网链路类型。

要启用 DOCA PCC RP

在主机/VM 上运行以下命令

复制
已复制！

            
            mlxconfig -d <mlx_device> -y s USER_PROGRAMMABLE_CC=1

执行优雅关机，然后重启主机电源。

要启用 DOCA PCC NP

在主机/VM 上运行以下命令

复制
已复制！

            
            mlxconfig -d <mlx_device> -y s PCC_INT_EN=0

执行优雅关机，然后重启主机电源。

注意

将 PCC_INT_EN 配置为 1 会阻止创建 DOCA PCC NP 上下文并启用旧版 NP 解决方案。此外，它仅支持 DOCA PCC RP 上下文来设置拥塞控制消息后丢弃 (CCMAD) 探测数据包格式。

如果需要 IFA2.0 支持，用户需要在集群的所有节点上启用 DOCA PCC RP 和 DOCA PCC NP。

注意

如果在 NIC 模式下从主机运行，用户必须具有特权权限才能配置上述参数。要检查特权级别，请运行

复制
已复制！

            
            mlxprivhost -d <mlx_device> q

DPACC 工具用于编译和链接用户算法和设备代码以及 DOCA PCC 设备库，以获取可以从主机程序加载的应用程序。

DPACC 作为 DOCA SDK 安装包的一部分捆绑提供。有关 DPACC 的更多信息，请参阅NVIDIA DOCA DPACC 编译器。

2.9.0 版本中的更改

已添加

doca_pcc.h:

doca_pcc_cap_is_ccmad_custom_header_supported(const struct doca_devinfo *devinfo);
doca_pcc_rp_set_ccmad_custom_header_size(struct doca_pcc *pcc, uint32_t probe_format_slot, uint8_t header_size);
doca_pcc_rp_set_ccmad_custom_header_location(struct doca_pcc *pcc, uint32_t probe_format_slot, doca_pcc_ccmad_custom_header_loc_t header_loc);
doca_pcc_cap_is_probe_priority_change_supported(const struct doca_devinfo *devinfo);
doca_pcc_rp_set_ccmad_probe_priority_change_en(struct doca_pcc *pcc, uint32_t probe_format_slot, bool enable);

doca_pcc_dev_common.h:

doca_pcc_dev_get_logical_ports(void);
doca_pcc_dev_get_port_planes(uint32_t portid);
doca_pcc_dev_get_port_speed(uint32_t portid);
doca_pcc_dev_user_port_info_changed(uint32_t portid) __attribute__((weak));

doca_pcc_np_dev.h:

doca_pcc_np_dev_get_port_num(const struct doca_pcc_np_dev_request_packet *input);

doca_pcc_dev.h:

doca_pcc_dev_custom_header_set(doca_pcc_dev_algo_ctxt_t *algo_ctxt, doca_pcc_dev_event_t *event, uint32_t *header, uint32_t header_size, uint32_t wait_completed);
doca_pcc_dev_probe_prio_set(doca_pcc_dev_algo_ctxt_t *algo_ctxt, doca_pcc_dev_event_t *event, uint32_t use_custom_prio, uint32_t prio, uint32_t wait_completed);

doca_pcc_dev_event.h:

doca_pcc_dev_get_ttl_hoplimit(doca_pcc_dev_event_t *event);
doca_pcc_dev_get_flow_qpn(doca_pcc_dev_event_t *event);
doca_pcc_dev_get_rtt_np_rx_byte_counter(doca_pcc_dev_event_t *event);
doca_pcc_dev_get_rtt_resp_version(doca_pcc_dev_event_t *event);
doca_pcc_dev_get_rtt_resp_port_type(doca_pcc_dev_event_t *event);

已更新

enum doca_pcc_dev_nic_counter_ids_t → enum doca_pcc_dev_nic_port_counter_types_t;

struct mlnx_cc_roce_tx_t

复制
已复制！

            
            struct mlnx_cc_roce_tx_extra_t {       /* Little Endian */
     uint32_t                   flow_qpn:24;                    /* flow qp number */
        /* access: RW */
     uint32_t                   reserved_at_0:8;                        
        /* access: RW */
 /* --------------------------------------------------------- */
 };
 
struct mlnx_cc_roce_tx_t {     /* Little Endian */
     uint32_t                   first_timestamp;                        /* first coalesced event timestamp */
        /* access: RW */
        /*----------------------------------------------------------*/
     struct mlnx_cc_roce_tx_cntrs_t                     cntrs;                  /* tx counters */
        /* access: RW */
        /*----------------------------------------------------------*/
-    uint32_t                   flow_qpn:24;                    /* flow qp number */
-    uint32_t                   reserved_at_40:8;
+    struct mlnx_cc_roce_tx_extra_t                     extra;                  
        /* access: RW */
        /*----------------------------------------------------------*/
     unsigned char                      reserved_at_60[4];                      
        /* access: RW */
 /* --------------------------------------------------------- */
 };

已删除 struct mlnx_cc_results_t 并替换为 struct doca_pcc_dev_results

复制
已复制！

            
            /**
 * @brief CC algorithm results
 */
typedef struct doca_pcc_dev_results {
	uint32_t rate; /**< Tx rate of the CC flow */
	union {
		uint32_t rtt_req;   /**< rtt request bit */
		uint32_t probe_req; /**< probe request bit */
	};
	uint32_t probe_type_slot; /**< probe type slot to indicate which probe to send */
	uint32_t credits;	  /**< Num of credits allowed for the CC flow */
	uint32_t reload_credits;  /**< Command to reload credits to the CC flow */
} doca_pcc_dev_results_t;

主机库

主机库为管理 DOCA PCC 上下文配置提供了统一的接口。

作为控制路径的一部分，主机库被动地集成在应用程序中，协调拥塞控制活动，而无需直接处理数据传输。

主机/设备库和头文件

host-dpu-library-and-header-files-version-1-modificationdate-1709127880633-api-v2.png

设备库

DOCA PCC 上下文承担以下两种角色之一

反应点 (RP)：主动监控网络状况，动态调整数据传输速率以及时缓解拥塞。RP 上下文是每个 NIC 全局的。

设备库和头文件
通知点 (NP)：被动地接收来自外部源的拥塞通知，智能地处理它们，以便在应用程序内做出明智的决策。NP 上下文是每个电子交换机所有者全局的。

设备库和头文件

RP 和 NP 设备库共享通用头文件

image-2024-2-28_16-45-6-version-1-modificationdate-1726744786120-api-v2.png

目前，设备库和用户算法是在 BlueField 的数据路径加速器 (DPA) 子系统上实现和管理的。

有关 DPA 的更多信息，请参阅DPA 子系统。

开发流程

DOCA 使开发人员能够使用 DOCA PCC 库将拥塞控制算法编程到系统中。

以下是开始编程所需的步骤

使用设备头文件提供的 API 实现 CC 算法和探测数据包处理。
实现库为 DataPath 定义的用户回调
- 对于 RP：doca_pcc_dev_user_init()、doca_pcc_dev_user_set_algo_params()、doca_pcc_dev_user_algo()。
- 对于 NP：doca_pcc_dev_np_user_packet_handler()
使用 DPACC 构建 DPA 应用程序（即，包含嵌入式设备可执行文件的主机库）。DPACC 的输入是包含先前步骤实现的文件。
使用主机编译器构建主机可执行文件。主机编译器的输入是在上一步中生成的 DPA 应用程序和用户应用程序主机源文件。
在主机可执行文件中，创建并启动 DOCA PCC 上下文，该上下文设置为包含设备代码的 DPA 应用程序。

development-flow-version-1-modificationdate-1726744785430-api-v2.png

有关更详细的示例，请参阅NVIDIA DOCA PCC 应用程序指南。

系统设计

用于实现 RP 程序的 DOCA PCC 流程

image-2024-6-25_15-58-25-version-1-modificationdate-1726744785900-api-v2.png

用于实现 NP 程序的 DOCA PCC 流程

image-2024-6-25_15-58-50-version-1-modificationdate-1726744785723-api-v2.png

API

有关库 API 参考，请参阅DOCA 库 API中的 PCC API 文档。

以下部分提供有关库 API 的更多详细信息。

主机 API

主机库 API 由用于设置 PCC 上下文属性和观察进程可用性的调用组成。

选择和打开 DOCA 设备

要执行 PCC 操作，必须选择一个设备。要选择设备，用户可以使用 doca_devinfo_list_create() 迭代所有 DOCA 设备，并检查设备是否支持所需的 PCC 角色，可以通过 doca_devinfo_get_is_pcc_supported() 检查 RP，或通过 doca_pcc_np_cap_is_supported() 检查 NP。

设置和启动 DOCA PCC 上下文

选择 DOCA 设备后，可以创建 PCC 上下文。

如“架构”部分所述，DOCA PCC 库提供 API 来利用反应点 (RP) 和通知点 (NP) 来实现可编程拥塞控制策略。

调用 doca_pcc_create() 创建 DOCA PCC RP 上下文，调用 doca_pcc_np_create() 创建 DOCA PCC NP 上下文。

之后，必须为 PCC 上下文设置以下属性

上下文应用程序 – 使用 DPACC 编译的 DPA 应用程序的名称，由设备算法和代码组成。这可以使用 doca_pcc_set_app() 调用进行设置。
上下文线程 – 用于处理 CC 事件的 DPA 线程的关联性。这可以使用 doca_pcc_set_thread_affinity() 调用进行设置。要使用的线程数必须限制在允许运行 PCC 进程的最小和最大线程数之间（请参阅 doca_pcc_get_min_num_threads() 和 doca_pcc_get_max_num_threads()）。线程对于 PCC 的可用性和使用情况取决于 CC 算法的复杂性、链路速率和其他潜在的 DPA 用户。

注意

用户可以使用 EU 预配置和 dpaeumgmt 工具管理系统中的 DPA 线程。有关更多信息，请参阅DOCA DPA 执行单元管理工具。

设置上下文属性后，可以使用 doca_pcc_start() 启动上下文。启动上下文会启动用户提供的 CC 算法。

配置探测数据包

DOCA PCC 库提供 API 来配置探测数据包设置，以根据特定的网络条件定制拥塞控制行为。

探测数据包用于探测网络拥塞并收集拥塞控制算法的重要反馈。

DOCA PCC 库支持以下探测数据包类型

CCMAD – 提供有关网络往返时间的信息，以便算法可以主动检测和适应拥塞
IFA1 – 带内流分析器 1 数据包提供带内拥塞反馈，用于主动拥塞控制
IFA2 – 带内流分析器 2 数据包为带内拥塞反馈提供了一种替代方法，针对特定的网络环境进行了优化

为不同探测类型配置专用字段

DOCA PCC 库提供 API 来配置不同支持的探测数据包类型中的特定字段。

IFA1 – 支持配置探测标记
IFA2 – 支持配置 gns 和跳数限制

配置远程 NP 处理程序

为了使反应点上下文能够与远程通知点上下文交互，DOCA PCC 库提供了一个 API 来设置预期的远程处理程序类型。

当 DOCA PCC RP 进程期望来自 DOCA PCC NP 进程的 CCMAD 探测数据包响应时，应使用 API doca_pcc_rp_set_ccmad_remote_sw_handler() 将其设置为这样。如果未设置，则 DOCA PCC RP 进程期望未激活远程 DOCA PCC NP 进程，并且响应由远程节点的硬件处理。请注意，如果使用 CCMAD 以外的其他探测类型，则始终期望探测数据包响应由远程通知点进程生成。

可调试性

DOCA PCC 库提供了一组调试 API，允许用户诊断和排除设备上的任何问题，以及从正在运行的应用程序访问实时信息

doca_pcc_set_dev_coredump_file() – API，用于设置文件名，以便在应用程序的设备端发生致命错误时将崩溃数据和核心转储写入其中。写入文件的数据将包括崩溃时的内存快照，其中将包含有助于查明崩溃原因的信息（例如，程序状态、变量值和调用堆栈）。
doca_pcc_set_trace_message() – API，通过设置可以从设备打印的跟踪消息格式，在应用程序的设备端启用跟踪。库提供的跟踪器是高频率的，旨在不对应用程序的性能产生重大影响。此 API 可以帮助用户监视和深入了解正在运行的设备算法的行为、识别性能瓶颈和诊断问题，而不会导致任何明显的性能下降。
doca_pcc_set_print_buffer_size() – API，用于设置设备库提供的打印 API 要打印的缓冲区大小。

设备邮箱

DOCA PCC 库提供了一组 API，用于通过邮箱发送和接收消息。此服务允许主机和设备之间进行通信

doca_pcc_set_mailbox() – API，用于设置进程的邮箱属性。
doca_pcc_mailbox_get_request_buffer() 和 doca_pcc_mailbox_get_response_buffer() – API，用于获取将用于处理通信的缓冲区。用户可以设置他想要发送到设备的请求，并获得响应。
doca_pcc_mailbox_send() – API，用于将邮箱请求发送到设备。这是一个阻塞调用，它在设备 doca_pcc_dev_user_mailbox_handle() 上调用回调，用户可以处理该回调。

高可用性

DOCA PCC 库提供高可用性，允许在运行的 PCC 进程发生故障时快速恢复。可以通过并行运行多个 PCC 进程来实现高可用性。

当调用 doca_pcc_start() 时，库会在 BlueField 固件中注册该进程，以便注册的第一个 PCC 进程成为 ACTIVE PCC 进程（即，实际在 DPA 上运行并处理 CC 事件）。

其他进程以 STANDBY 模式运行。如果 ACTIVE 进程停止处理事件或遇到错误，固件会将其替换为其中一个备用进程，使其变为 ACTIVE。

已失效的进程应调用 doca_pcc_destroy() 以释放其资源。

可以使用 doca_pcc_get_process_state() 定期观察进程的状态。进程状态的更改将返回调用 doca_pcc_wait()。

以下值描述了任何时候 PCC 进程的状态

复制
已复制！

            
            typedef enum {
	DOCA_PCC_PS_ACTIVE = 0,
    /**< The process handles CC events (only one process is active at a given time) */
    DOCA_PCC_PS_STANDBY = 1,
    /**< The process is in standby mode (another process is already ACTIVE)*/
    DOCA_PCC_PS_DEACTIVATED = 2,
    /**< The process was deactivated by NIC FW and should be destroyed */
    DOCA_PCC_PS_ERROR = 3,
    /**< The process is in error state and should be destroyed */
} doca_pcc_process_state_t;

设备 API

设备库 API 由用于设置 CC 算法以处理硬件上到达的 CC 事件的调用组成。

计数器采样

设备库 API 提供了一个 API 来采样 NIC 字节计数器。这些计数器有助于监控通过 NIC 传输和接收的数据量。

用户可以使用 doca_pcc_dev_nic_counters_config() 准备要读取的计数器列表，并使用 doca_pcc_dev_nic_counters_sample() 调用采样新的计数器值。

建议在用户回调 doca_pcc_dev_user_port_info_changed() 中配置计数器，因为它指示要从中采样计数器的端口状态。

算法访问

反应点 (RP) 设备库 API 提供了一组函数来启动和识别不同的 CC 算法。

DOCA PCC 库旨在支持多个 PCC 算法。该库附带一个默认算法，用户可以使用 doca_pcc_dev_default_internal_algo() 完全或部分使用该算法，以及用户提供的其他 CC 算法。这对于在不同算法之间进行快速比较运行非常有用。每个算法可以使用 doca_pcc_dev_init_algo_slot() 在不同的设备端口上运行。

该算法可以提供自己的标识符，初始化其参数（使用 doca_pcc_dev_algo_init_param()）、计数器（使用 doca_pcc_dev_algo_init_counter()）和元数据基础（使用 doca_pcc_dev_algo_init_metadata()）。

doca_pcc_dev_user_init() – 在 PCC 进程加载时调用，应初始化所有用户算法的数据
doca_pcc_dev_user_algo() – 用户算法处理代码的入口点
doca_pcc_dev_user_set_algo_params() – 在外部设置参数更改时调用

要为 NP 实现的回调集

doca_pcc_dev_np_user_packet_handler() – 在探测数据包到达时调用

本页内容

简介