DOCA 文档 v2.10.0
NVIDIA 文档中心  NVIDIA 网络  BlueField DPU / SuperNIC 和 DOCA  DOCA 文档 v2.10.0  DOCA DMA 复制应用程序指南

本页内容

DOCA DMA 复制应用程序指南

本指南提供了一个在 NVIDIA® BlueField® DPU 之上实现 DMA 复制的示例。

简介

DOCA DMA（直接内存访问）复制应用程序使用 DOCA DMA 库 在 DPU 和 x86 主机之间传输文件（数据路径），文件大小不超过硬件支持的最大大小。DOCA DMA 库 提供了一个 API，可以使用硬件加速在 DOCA 缓冲区之间复制数据，支持本地和远程内存。

DOCA DMA 允许以优化的硬件加速方式轻松执行复杂的内存复制操作。

系统设计

DOCA DMA 复制旨在 BlueField DPU 和 x86 主机的实例上运行。DPU 应用程序必须首先启动，因为它会在双方之间打开 DOCA Comch 服务器，所有必要的 DOCA DMA 库配置文件（控制路径）都将在其上进行传输。

system-design-diagram-version-1-modificationdate-1734469425393-api-v2.png

应用程序架构

DOCA DMA 复制在 DOCA DMA 之上运行，可以直接从主机的内存中读取/写入，而无需任何用户/内核空间上下文切换，从而实现快速内存复制。

application-architecture-diagram-version-1-modificationdate-1734469425800-api-v2.png

流程

  1. 双方启动一个简短的协商，以确定文件大小和位置。

  2. 主机端使用 doca_mmap_export_pci() 创建导出描述符，并通过 Comch 将其与本地缓冲区地址和长度一起发送到 DPU 端应用程序。

  3. DPU 端应用程序使用接收到的导出描述符，通过 doca_mmap_create_from_export() 在本地创建一个远程内存映射，并使用主机缓冲区信息创建一个远程 DOCA 缓冲区。

  4. 从此时起，DPU 端应用程序拥有所有必要的内存信息，并且可以进行 DMA 复制。

DOCA 库

此应用程序利用了以下 DOCA 库

有关更多信息，请参阅它们各自的编程指南。

编译应用程序

信息

请参阅 DOCA Linux 安装指南，了解如何安装 BlueField 相关软件的详细信息。

DOCA 参考应用程序的安装包包含应用程序的源代码以及匹配的编译说明。这允许“按原样”编译应用程序，并提供修改源代码然后编译应用程序新版本的能力。

提示

有关应用程序以及开发和编译技巧的更多信息，请参阅 DOCA 参考应用程序 页面。

应用程序的源代码可以在应用程序的目录下找到：/opt/mellanox/doca/applications/dma_copy/。

编译所有应用程序

所有 DOCA 应用程序都在一个 meson 项目下定义。因此，默认情况下，编译会包含所有应用程序。

要一起构建所有应用程序，请运行

复制
已复制！
            

            
cd /opt/mellanox/doca/applications/
meson /tmp/build 
ninja -C /tmp/build

信息

doca_dma_copy 在 /tmp/build/dma_copy/ 下创建。


仅编译当前应用程序

要直接仅构建 DMA 复制应用程序

复制
已复制！
            

            
cd /opt/mellanox/doca/applications/
meson /tmp/build -Denable_all_applications=false -Denable_dma_copy=true
ninja -C /tmp/build

信息

doca_dma_copy 在 /tmp/build/dma_copy/ 下创建。

或者，可以在 meson_options.txt 文件中设置所需的标志，而不是在编译命令行中提供它们

  1. 编辑 /opt/mellanox/doca/applications/meson_options.txt 中的以下标志

    • 将 enable_all_applications 设置为 false

    • 将 enable_dma_copy 设置为 true

  2. 运行以下编译命令

    复制
    已复制！
                
    
            
    cd /opt/mellanox/doca/applications/
meson /tmp/build 
ninja -C /tmp/build

    信息

    doca_dma_copy 在 /tmp/build/dma_copy/ 下创建。

故障排除

有关应用程序编译遇到的任何问题，请参阅 DOCA 故障排除。

运行应用程序

应用程序执行

DMA 复制应用程序以源代码形式提供。因此，在执行应用程序之前需要进行编译。

  1. 应用程序使用说明

    复制
    已复制！
                
    
            
    Usage: doca_dma_copy [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:
  -f, --file                        Full path to file to be copied/created after a successful DMA copy
  -p, --pci-addr                    DOCA Comm Channel device PCI address
  -r, --rep-pci                     DOCA Comm Channel device representor PCI address (needed only on DPU)

    信息

    此用法打印输出可以使用 -h（或 --help）选项打印到命令行

    复制
    已复制！
                
    
            
    ./doca_dma_copy -h

    信息

    有关更多信息，请参阅“命令行标志”部分。

  2. 在 BlueField 上运行应用程序的 CLI 示例

    复制
    已复制！
                
    
            
    ./doca_dma_copy -p 03:00.0 -r 3b:00.0 -f received.txt

    注意

    DOCA Comch 设备 PCIe 地址 (03:00.0) 和 DOCA Comch 设备表示 PCIe 地址 (3b:00.0) 应与所需 PCIe 设备的地址匹配。

  3. 在主机上运行应用程序的 CLI 示例

    复制
    已复制！
                
    
            
    ./doca_dma_copy -p 3b:00.0 -f send.txt

    注意

    DOCA Comch 设备 PCIe 地址 3b:00.0 应与所需 PCIe 设备的地址匹配。

  4. 该应用程序还支持基于 JSON 的部署模式，其中所有命令行参数都通过 JSON 文件提供

    复制
    已复制！
                
    
            
    ./doca_dma_copy --json [json_file]

    例如

    复制
    已复制！
                
    
            
    ./doca_dma_copy --json ./dma_copy_params.json

    注意

    在执行之前，请确保使用的 JSON 文件包含正确的配置参数，尤其是部署所需的 PCIe 地址。

命令行标志

标志类型

短标志

长标志/JSON 键

描述

JSON 内容

通用标志

h

help

打印帮助概要

N/A

v

version

打印程序版本信息

N/A

l

log-level

设置应用程序的日志级别

  • DISABLE=10

  • CRITICAL=20

  • ERROR=30

  • WARNING=40

  • INFO=50

  • DEBUG=60

  • TRACE=70（需要使用 TRACE 日志级别支持进行编译）
复制
已复制！
            

            
"log-level": 60

N/A

sdk-log-level

设置程序的日志级别

  • DISABLE=10

  • CRITICAL=20

  • ERROR=30

  • WARNING=40

  • INFO=50

  • DEBUG=60

  • TRACE=70
复制
已复制！
            

            
"sdk-log-level": 40

j

json

从输入 JSON 文件解析所有命令标志

N/A

程序标志

f

file

要复制的文件/成功复制后创建的文件的完整路径

注意

这是一个强制标志。
复制
已复制！
            

            
"file": "/tmp/sample.txt"

p

pci-addr

DOCA Comch 设备 PCIe 地址。

注意

这是一个强制标志。
复制
已复制！
            

            
"pci-addr": "b1:00.0"

r

rep-pci

DOCA Comch 设备表示 PCIe 地址。

注意

这仅在 DPU 上是强制标志。
复制
已复制！
            

            
"rep-pci": "b1:02.0"
信息

有关支持的标志和执行模式的更多信息，请参阅 DOCA Arg Parser。


故障排除

有关 DOCA 应用程序的安装或执行遇到的任何问题，请参阅 DOCA 故障排除。

应用程序代码流程

  1. 解析应用程序参数。

    1. 初始化参数解析器资源并注册 DOCA 通用参数。

      复制
      已复制！
                  
      
            
      doca_argp_init();

    2. 注册 DMA 复制应用程序参数。

      复制
      已复制！
                  
      
            
      register_dma_copy_params();

    3. 解析参数。

      复制
      已复制！
                  
      
            
      doca_argp_start();

  1. 初始化 Comch 端点。

    复制
    已复制！
                
    
            
    init_cc();

    1. 创建 Comch 端点。

    2. 解析用户提供的 Comch 设备 PCIe 地址。

    3. 打开 Comch DOCA 设备。

    4. 解析用户提供的 Comch 设备表示 (DPU 侧) PCIe 地址。

    5. 打开 Comch DOCA 设备表示 (DPU 侧)。

    6. 设置 Comch 端点属性。

  2. 打开将从中进行复制的 DOCA 硬件设备。

    复制
    已复制！
                
    
            
    open_dma_device();

    1. 解析用户提供的 PCIe 地址。

    2. 创建所有可用 DOCA 设备的列表。

    3. 根据特定属性查找合适的 DOCA 设备。

    4. 打开设备。

  3. 创建所有必需的 DOCA 核心对象。

    复制
    已复制！
                
    
            
    create_core_objects();

  4. 初始化 DOCA 核心对象。

    复制
    已复制！
                
    
            
    init_core_objects();

  5. 启动主机/DPU DMA 复制。

    1. 主机端应用程序

      复制
      已复制！
                  
      
            
      host_start_dma_copy();

      1. 与 DPU 端应用程序开始协商文件位置和大小。

      2. 为 DMA 缓冲区分配内存。

      3. 导出内存映射并将输出（导出描述符）发送到 DPU 端应用程序。

      4. 通过 Comch 将主机本地缓冲区内存地址和长度发送到 DPU 端应用程序。

      5. 等待 DPU 通知 DMA 复制结束。

      6. 关闭所有内存对象。

      7. 清理资源。

    2. DPU 端应用程序

      复制
      已复制！
                  
      
            
      dpu_start_dma_copy();

      1. 与主机端应用程序开始协商文件位置和大小。

      2. 为 DMA 缓冲区分配内存。

      3. 在 Comch 上接收导出描述符。

      4. 为主机上的远程缓冲区创建 DOCA 内存映射。

      5. 在 Comch 上接收主机缓冲区信息。

      6. 创建两个 DOCA 缓冲区，一个用于远程（主机）缓冲区，另一个用于本地缓冲区。

      7. 提交 DMA 复制任务。

      8. 发送主机消息以通知 DMA 复制结束。

      9. 清理资源。

  6. 销毁 Comch。

    复制
    已复制！
                
    
            
    destroy_cc();

  7. 销毁 DOCA 核心对象。

    复制
    已复制！
                
    
            
    destroy_core_objects();

  8. 参数解析器销毁。

    复制
    已复制！
                
    
            
    doca_argp_destroy();

参考资料

  • /opt/mellanox/doca/applications/dma_copy/

  • /opt/mellanox/doca/applications/dma_copy/dma_copy_params.json
© 版权所有 2025 NVIDIA。 上次更新时间：2025 年 2 月 12 日。
content here