📚 课程目录第3章 DOCA开发环境搭建

3. DOCA开发环境搭建

DOCA 开发环境与普通 x86 服务器上的软件开发有本质区别：代码最终运行在 BlueField DPU 内部的 ARM 核（Arm Cortex-A72）与专用加速器上，而开发、编译、调试往往在 x86 主机上完成。因此，环境搭建的核心是打通“主机—DPU—容器—目标固件”这条链路，让工具链、驱动版本、DOCA SDK 版本与 DPU 固件版本彼此匹配。版本错配是初学者最常见的失败原因，例如用 DOCA 2.5 的库去链接 2.2 固件上的驱动，通常会在初始化上下文时直接报错。

一、BlueField DPU 固件与驱动安装

BlueField-2 DPU 在出厂时已烧录固件，但开发前应确认并升级到与目标 DOCA 版本兼容的固件。在主机（Host）侧，DPU 以 PCIe 设备形式出现，可用 lspci 查看，典型标识为 Mellanox Technologies MT42822 BlueField-2。固件版本通过 mlxfwmanager 或 flint 查询：

# 在 Host 上查看 DPU 固件与 PSID
sudo mst start
sudo mlxfwmanager --query
# 输出示例（示例值，非实测）：
# Device #1: BlueField-2
#   PSID: MT_0000000548
#   FW Version: 24.35.1000
#   PCI Device Name: /dev/mst/mt41692_pciconf0

升级固件使用 mlxfwmanager -u -i <fw.bin>，或通过 DOCA 提供的 bfb（BlueField Boot Stream）镜像整体刷写。BFB 是包含固件、操作系统镜像与驱动的一体化包，适合全新部署：

# 在 Host 上刷写 BFB（示例流程）
sudo bfb-install --bfb DOCA_2.5.0_BSP_4.5.0_Ubuntu_22.04-1.bfb \
                 --rshim rshim0
# 刷写完成后 DPU 自动重启，可通过 rshim 控制台观察启动日志
sudo cat /dev/rshim0/console

驱动方面，Host 侧需要安装 MLNX_OFED 或 DOCA-OFED，它提供 mlx5_core、ib_core 等内核模块，使 Host 能识别 DPU 的网卡与 RDMA 功能。DPU 侧（Arm 系统）则通常已随 BFB 预装对应驱动。安装后可用 ibv_devinfo 确认 RDMA 设备就绪，用 ip link 查看代表口（如 p0、pf0hpf）状态。

固件、OFED 驱动、DOCA SDK 三者存在官方兼容矩阵。升级前务必查阅对应 DOCA 版本的 Release Notes，避免“能装上但跑不通”。

二、DOCA SDK 获取与安装

DOCA SDK 从 NVIDIA 开发者网站下载，提供两种形态：Host 侧安装包（.deb/.rpm）与容器镜像（nvcr.io/nvidia/doca/doca）。SDK 包含 DOCA 库（如 DOCA Flow、DOCA Compress、DOCA DMA）、头文件、示例程序与 pkg-config 描述文件。安装后可用以下命令验证：

# 安装 DOCA SDK（Ubuntu 示例）
sudo dpkg -i doca-sdk_2.5.0-*.deb
# 验证版本与库路径
pkg-config --modversion doca-flow
ls /opt/mellanox/doca/include
# 编译并运行官方示例
cd /opt/mellanox/doca/samples/doca_flow/flow_acl
meson build && cd build && ninja
sudo ./doca_flow_acl --help

DOCA 示例普遍采用 meson + ninja 构建，依赖 libdoca 与 libibverbs。若 pkg-config 找不到 doca-flow，通常是 PKG_CONFIG_PATH 未包含 /opt/mellanox/doca/lib/pkgconfig。

三、容器化开发环境

容器化是 DOCA 开发推荐方式，可避免污染主机环境并保证版本一致。NVIDIA 提供官方 DOCA 容器，内含完整 SDK 与工具链。启动时需挂载 DPU 设备节点与共享库：

docker run --rm -it --privileged \
  -v /dev/hugepages:/dev/hugepages \
  -v /opt/mellanox/doca:/opt/mellanox/doca \
  nvcr.io/nvidia/doca/doca:2.5.0-devel \
  /bin/bash

容器内即可直接编译、运行 DOCA 程序。若需在容器中访问 DPU 的 RDMA 设备，应挂载 /dev/infiniband 并确保 --privileged 或相应 capability。开发阶段建议把源码目录以卷方式挂载进容器，实现“主机编辑、容器编译”。

四、交叉编译与部署流程

当目标程序运行在 DPU 的 Arm 核上时，需要在 x86 主机上进行交叉编译。DOCA 提供 aarch64 交叉工具链与对应的 SDK 库。关键是把 CC、CXX 指向交叉编译器，并让链接器找到 Arm 版 DOCA 库：

export CC=aarch64-linux-gnu-gcc
export PKG_CONFIG_PATH=/opt/mellanox/doca/lib/aarch64-linux-gnu/pkgconfig
meson build-aarch64 --cross-file cross_aarch64.txt
ninja -C build-aarch64

编译产物通过 scp 或 rshim 传输到 DPU，再在 DPU 的 Arm 系统上运行。部署后需确认动态库路径（LD_LIBRARY_PATH）与固件版本匹配。整个链路的对象与流向如下：

部署完成后，建议按以下顺序做一次最小验证：在 DPU 上执行 ibv_devinfo 确认 RDMA 设备存在；用 ip link show 检查 pf0hpf、p0 等接口是否 UP；再运行一个 DOCA 官方示例（如 doca_flow_acl），若程序能正常创建 DOCA 上下文并退出，说明固件、驱动、SDK 三者已匹配。若报 DOCA_ERROR_NOT_SUPPORTED，优先核对固件与 SDK 版本；若报链接错误，检查交叉编译时 PKG_CONFIG_PATH 是否指向了 Arm 版库目录。

交叉编译时最容易犯的错误是误用了 x86 版 DOCA 库。链接阶段可能不报错，但运行时会因架构不匹配而崩溃。务必确认 file 命令显示产物为 ARM aarch64，且链接的 libdoca_*.so 来自 aarch64-linux-gnu 目录。

把上述流程固化为脚本或 Makefile，可显著降低重复搭建成本。一个实用的做法是：在主机上维护 env.sh 统一导出 CC、PKG_CONFIG_PATH、DOCA_VERSION，容器启动时挂载该脚本与源码目录，DPU 侧则用 rsync 同步产物并重启目标服务。这样，从代码修改到 DPU 上验证的闭环可以压缩到分钟级，为后续 DOCA Flow、DOCA DMA 等具体功能的开发打好基础。