3. DOCA SDK与开发框架入门

DOCA（Data Center Infrastructure on a Chip Architecture）并不是一个单一库，而是一套面向DPU（如NVIDIA BlueField系列）的软件开发套件。它把底层硬件能力（网络、存储、安全、加解密、正则匹配、DMA等）封装成一组相对独立的库，再通过统一的运行时、编译系统和调试机制，让开发者能够以接近用户态应用的方式调用DPU加速能力。理解DOCA库结构、编译系统、示例程序运行方式以及调试与日志机制，是后续所有开发工作的基础。

一、DOCA库结构：分层与模块化

从整体上看，DOCA SDK可以划分为四个层次。最底层是驱动与固件层，包括DPU上的MLX5驱动、固件以及各种硬件加速引擎；其上是DOCA Core层，提供设备抽象、内存管理、事件队列、进度引擎（Progress Engine）等公共基础设施；再往上是功能库层，也就是开发者最常接触的部分，例如DOCA Flow（报文转发与匹配）、DOCA RDMA（远程直接内存访问）、DOCA AES-GCM（加解密）、DOCA RegEx（正则匹配）、DOCA Compress（压缩）、DOCA DMA（直接内存访问）等；最上层是应用与框架层，包括DOCA应用程序、参考示例以及与其他框架（如DPDK、SPDK）的集成接口。

这种分层设计的关键在于：DOCA Core负责“怎么和DPU打交道”，功能库负责“用DPU做什么”，应用层负责“业务逻辑是什么”。开发者通常不需要直接操作驱动，而是通过DOCA Core提供的设备上下文（doca_dev）、内存映射（doca_mmap）、事件队列（doca_pe）等对象来组织程序。每个功能库都会依赖Core层，但彼此之间相对独立，因此可以按需引入，避免不必要的依赖膨胀。

二、编译系统：从pkg-config到CMake

DOCA SDK在Linux环境下以标准库的形式安装，通常位于/opt/mellanox/doca目录下，包含include/、lib/、samples/等子目录。编译DOCA程序时，最直接的方式是使用pkg-config获取编译和链接参数。例如，编译一个使用DOCA Flow的程序，可以这样写：

gcc -o my_app my_app.c \
  $(pkg-config --cflags doca-flow) \
  $(pkg-config --libs doca-flow)

如果程序同时使用多个功能库，只需在pkg-config中依次列出，例如doca-flow doca-rdma doca-common。对于较大的项目，推荐使用CMake，通过find_package(DOCA REQUIRED)引入，再链接doca::doca_flow等目标。需要注意的是，DOCA库通常依赖libibverbs、libmlx5等底层库，pkg-config会自动处理这些传递依赖，但手动编写Makefile时容易遗漏，因此优先使用pkg-config或CMake是更稳妥的做法。

三、示例程序运行：以DOCA Flow为例

DOCA SDK自带大量示例程序，位于/opt/mellanox/doca/samples/下。以doca_flow的flow_acl示例为例，其典型运行流程如下：首先确认DPU设备已正确识别，可通过lspci | grep Mellanox查看；然后进入示例目录，执行make编译；编译成功后，使用sudo ./doca_flow_acl -a 03:00.0运行，其中-a指定PCIe地址。程序启动后会创建Flow管道、加载ACL规则，并进入报文处理循环。此时可以从另一台主机发送匹配规则的报文，观察示例程序输出的命中计数和转发结果。

四、调试与日志机制

DOCA的日志系统基于doca_log模块，支持按模块和级别输出日志。日志级别从低到高分为DEBUG、INFO、WARNING、ERROR、CRITICAL。默认情况下，INFO及以上级别会输出到标准错误。开发者可以通过环境变量DOCA_LOG_LEVEL动态调整，例如export DOCA_LOG_LEVEL=DEBUG可以打开详细调试信息。在代码中，使用DOCA_LOG_INFO("...")、DOCA_LOG_ERR("...")等宏即可输出日志，这些宏会自动附带文件名、行号和函数名，便于定位问题。

除了日志，DOCA还提供了doca_error错误码体系。每个API调用返回doca_error_t类型，成功时为DOCA_SUCCESS，失败时返回具体错误码。建议在每次调用后检查返回值，并使用doca_error_get_string()将错误码转换为可读字符串。对于更复杂的调试场景，可以结合gdb附加到运行中的进程，或者使用strace跟踪系统调用，观察DOCA库与驱动之间的交互。此外，DPU侧的固件日志可以通过mlxconfig和dmesg查看，有助于判断问题出在应用层还是硬件层。

五、一个可复用的编译与运行检查清单