3. DOCA开发环境与工具链

DOCA 应用开发并不是“装一个 SDK 就能写代码”这么简单。它同时涉及宿主机驱动、DOCA 运行时库、容器运行时、编译目标架构以及调试与性能分析工具，任何一环版本不匹配，都会在编译期或运行期以难以定位的方式暴露出来。本节围绕安装包、容器化环境、本地与交叉编译、调试与性能分析工具、版本兼容性管理五条主线，梳理一条可落地的环境搭建路径。

一、DOCA 安装包与组成

DOCA 的发布形态主要有三类：面向宿主机的 doca-host 安装包（.deb/.rpm）、面向容器镜像的 doca-runtime 与 doca-full 镜像，以及面向开发者的 doca-sdk 开发包。宿主机包负责安装内核模块、固件工具（如 mlxconfig、mst）和 DOCA 驱动；容器镜像则把用户态库、头文件、示例代码打包在一起，便于在 Kubernetes 或 Docker 中直接运行。

安装前应先确认三件事：BlueField DPU 或 ConnectX 网卡的固件版本、宿主机内核版本、以及目标 DOCA 版本。以 DOCA 2.6 为例，它要求固件不低于 32.42.1000，Ubuntu 22.04 内核 5.15 以上。安装命令通常如下：

# 添加 NVIDIA DOCA 仓库
sudo apt install -y doca-host
# 安装指定版本
sudo apt install -y doca-host=2.6.0-1
# 验证
doca_version

安装完成后，/opt/mellanox/doca 下会出现 include、lib、samples 等目录，这是后续编译时最重要的路径来源。

二、容器化开发环境

容器化是 DOCA 开发的主流方式，因为它把“宿主机驱动 + 容器内用户态库”解耦。典型做法是：宿主机安装 doca-host 并加载内核模块，容器内使用 doca-runtime 镜像，通过 --privileged 或挂载 /dev/infiniband、/dev/mst 等设备节点访问硬件。

docker run --rm -it \
  --privileged \
  --network host \
  -v /dev/infiniband:/dev/infiniband \
  -v /opt/mellanox/doca:/opt/mellanox/doca \
  nvcr.io/nvidia/doca/doca:2.6.0-devel

进入容器后，pkg-config --cflags doca 应能正确输出头文件路径。若报错，多半是镜像版本与宿主机驱动不匹配，此时应优先核对 doca_version 与镜像 tag 是否一致。

三、本地编译与交叉编译

本地编译指在 DPU 或 x86 宿主机上直接编译运行，适合快速验证。交叉编译则用于在 x86 开发机上生成 aarch64 目标程序，再部署到 BlueField DPU。两者共用同一套 DOCA 头文件与库，但工具链不同。

本地编译示例（以 DOCA 示例程序为例）：

cd /opt/mellanox/doca/samples/doca_dma/dma_copy
meson setup build
ninja -C build
./build/doca_dma_copy --help

交叉编译需要指定 --cross-file，并在其中声明 aarch64 的编译器、sysroot 与 pkg-config 路径。关键点是 sysroot 中必须包含与目标 DPU 一致的 DOCA 库，否则链接阶段会报未定义符号。

[binaries]
c = 'aarch64-linux-gnu-gcc'
cpp = 'aarch64-linux-gnu-g++'
pkgconfig = 'aarch64-linux-gnu-pkg-config'

[host_machine]
system = 'linux'
cpu_family = 'aarch64'
cpu = 'aarch64'
endian = 'little'

四、调试与性能分析工具

DOCA 应用运行在用户态，但底层依赖 RDMA、DPDK 与硬件队列，因此调试手段要覆盖“用户态逻辑”和“硬件数据面”两层。常用工具包括：gdb 用于用户态断点调试；doca_debug 与 doca_caps 用于查看设备能力与运行时状态；perf 与 nsys 用于 CPU/GPU 侧性能采样；mlx5 相关工具（如 mlxconfig、ethtool -S）用于查看网卡队列与丢包统计。

一个典型的排障顺序是：先用 doca_caps 确认设备是否被识别，再用 gdb 定位用户态崩溃点，最后用 perf top 观察是否存在轮询空转导致的 CPU 占用过高。若数据面吞吐不达预期，应检查 ethtool -S 中的 rx_discards 与 tx_discards，判断是否为队列深度不足。

五、版本兼容性管理

DOCA 的版本兼容性可以用“三层对齐”来概括：固件层、驱动层、用户态库层。三者版本必须落在 NVIDIA 官方兼容矩阵内。实践中建议用一张版本锁定表来管理，避免“开发机能跑、DPU 上跑不起来”的问题。

六、环境搭建的完整判断路径

把上述内容串起来，可以用一张关系图表达“宿主机—容器—编译目标—调试工具”之间的依赖与数据流。图中左侧是宿主机侧（固件、驱动、doca-host），中间是容器与编译环境，右侧是目标 DPU 与调试/性能工具，箭头表示依赖方向与版本约束。

从图中可以看出，环境搭建的核心不是“装哪个包”，而是保证固件、驱动、DOCA 用户态库、容器镜像四者版本一致。建议在项目启动阶段就固定版本，并在 CI 中加入 doca_version 与 mlxfwmanager 的校验步骤，这样后续的编译、调试与性能分析才有稳定的基线。