DOCA DPACC 编译器

目录

本文档描述了 DOCA DPACC 编译器，以及关于 DPA 工具链设置和使用的说明。

DPACC 是 DPA 处理器的*高级*编译器，它将面向数据路径加速器 (DPA) 处理器的代码编译为设备可执行文件，并生成 DPA 程序。

DPA 程序是一个主机库，其接口封装了设备可执行文件。此 DPA 程序与主机应用程序链接，以生成主机可执行文件。主机可执行文件可以通过 FlexIO 运行时 API 调用 DPA 代码。

DPACC 使用 DPA 编译器 (dpa-clang) 来编译面向 DPA 的代码。dpa-clang 是 DPA 工具链软件包的一部分，该软件包是基于 LLVM 的交叉编译裸机工具链。它提供 Clang 编译器、面向 DPA 架构的 LLD 链接器和其他实用程序。

词汇表

在 DPA 上卸载工作负载

要从主机调用 DPA 函数，需要以下内容

• DPA 设备代码 – C 程序，目标是在 DPA 上运行。DPA 设备代码可以包含一个或多个入口函数。

• 主机应用程序代码 – 相应的主机应用程序。请参阅 DPA 子系统 以了解更多详细信息

• 运行时 – FlexIO 或 DOCA DPA 库提供运行时

生成的 DPA 程序在与主机应用程序链接时，会生成也包含设备可执行文件的主机可执行文件。主机应用程序负责将设备可执行文件加载到设备上。

DPACC 预定义宏

DPACC 预定义以下宏

编写 DPA 应用程序

DPA 设备代码是 C 代码，具有一些限制和特殊定义。

FlexIO 或 DOCA-DPA API 提供 DPA 的接口。

语言支持

DPA 使用 C11 语言标准的子集进行编程。编译器会记录任何不可用的构造。可用的语言构造保留其标准定义。

DPA 代码的限制

• C 线程本地存储不允许用于任何变量

• 带有 _dpacc/__dpacc 前缀的标识符由编译器保留。使用此类标识符可能会导致错误或未定义的行为

• DPA 处理器没有原生浮点支持；浮点运算的使用被禁用

DPA RPC 函数

远程过程调用函数是同步调用，它触发 DPA 中的工作并等待其完成。这些函数返回 uint64_t 类型的值。它们使用 __dpa_rpc__ 属性进行注解。

DPA 全局函数

DPA 全局函数是从主机代码引用的事件处理程序设备函数。这些函数不返回任何内容。它们使用 __dpa_global__ 属性进行注解。

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

注解函数的特性

• 全局函数必须具有 void 返回类型，RPC 函数必须具有 uint64_t 返回类型

• 注解函数不能接受 C 指针和数组作为参数（例如，void my_global (int *ptr, int arr[])）

• 注解函数不能接受可变数量的参数

• 内联说明符不允许在注解函数上使用

处理用户定义的数据类型

用户定义的数据类型在用作全局函数参数时，需要特殊处理。它们必须使用 __dpa_global__ 属性进行注解。

如果用户定义的数据类型是 typedef'd，则 typedef 语句必须与数据类型本身一起使用 __dpa_global__ 属性进行注解。

注解类型的特性

• 它们必须在所有转换单元中都有定义的副本，在这些转换单元中，它们被用作全局函数参数

• 它们不能将指针、可变长度数组和灵活数组作为成员

• 支持作为 C 结构成员的固定大小数组

• 这些特性递归地应用于作为注解类型成员的任何用户定义/typedef'd 类型

DPACC 处理所有注解函数以及注解类型，并生成主机和设备接口以方便函数启动。

DPA 内联函数

DPA 功能（例如栅栏和特定于处理器的指令）通过 DPA 编译器通过内部函数公开。头文件 dpaintrin.h 中定义的所有内部函数都受 DPA_INTRIN_VERSION_USED 宏保护。当前的 DPA_INTRIN_VERSION 是 1.3。

示例

            

            
#define DPA_INTRIN_VERSION_USED (DPA_INTRIN_VERSION(1, 3))
#include <dpaintrin.h>
…
__dpa_thread_writeback_window();   // Fence for write barrier
        

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

DPACC 输入和输出

DPACC 可以通过接受所有源文件作为输入，在单个命令中生成 DPA 程序。DPACC 还提供了从输入文件生成 DPA 对象文件或库的灵活性。

DPA 对象文件包含主机存根对象（DPACC 生成的接口）和设备对象。这些 DPA 对象文件稍后可以作为输入提供给 DPACC，以生成 DPA 库。

DPACC 可以接受以下文件类型作为输入

根据操作模式，DPACC 可以生成以下输出文件

以下内容提供了为每种输入文件类型生成不同类型的受支持输出文件类型的命令

dpacc -hostcc=<cc> -mcpu=<targets> in.c -o libprog.a

dpacc -hostcc=<cc> -mcpu=<targets> in.c -c

dpacc -hostcc=<cc> -mcpu=<targets> in.c -o lib<name> -gen-libs

dpacc -hostcc=<cc> -mcpu=<targets> in.dpa.o -o libprog.a

dpacc -hostcc=<cc> -mcpu=<targets> in.dpa.o -o lib<name> -gen-libs

dpacc -hostcc=<cc> -mcpu=<targets> in.a -o libprog.a

dpacc -hostcc=<cc> -mcpu=<targets> in.a -o lib<name> -gen-libs

DPA 程序

DPACC 在编译和链接模式下生成 DPA 程序。DPA 程序是一个主机库，其中包含

• DPACC 生成的主机存根，用于注册 DPA 应用程序并方便从主机应用程序调用入口点函数

• 设备可执行文件，由 DPACC 通过编译和链接输入 DPA 设备代码生成

DPA 程序库必须与包含适当运行时 API 的主机应用程序链接，以将设备可执行文件加载到设备上。

DPA 程序可以包含多个目标的设备可执行文件。所有特定于目标的设备可执行文件都封装在特殊的 fatbinary 容器格式中，并且此容器作为节嵌入到主机库中存在的主机对象中。

DPA 对象

DPACC 在仅编译模式下生成 DPA 对象文件。DPA 对象是一个主机对象文件，其布局类似于 DPA 程序，其中包含 DPACC 生成的主机存根和通过编译输入设备代码生成的设备对象。

DPA 对象可以包含类似于 DPA 程序的多个目标的设备对象。所有特定于目标的设备对象都封装在特殊的 fatbinary 容器格式中，并且此容器作为节嵌入到主机对象中。

DPA 库

DPA 库是两个单独库的集合

• DPA 主机库 – 包含与 DPA 设备库中的设备对象对应的主机接口对象

• DPA 设备库 – 包含通过编译输入设备代码文件生成的设备对象

DPA 设备库在 DPA 程序生成期间由 DPACC 使用，DPA 主机库可以选择与其他主机代码链接，并作为主机库分发。这两个库都生成为静态归档。

主机库是一个静态归档。设备库是专门的 fatbinary 容器格式类型的文件，其中包含为不同目标构建的设备对象的归档。

上图中的深灰色框表示 fatbinary 容器。最终用户应将 fatbinary 容器视为不透明对象，并且不应以任何方式对其进行操作。

DPACC 轨迹

下图说明了 DPACC 编译和链接模式轨迹。

操作模式

在以下每种模式中，DPACC 通过“mcpu”选项接受单个或多个目标名称，并构建输出，以便支持所有提及的目标。

编译和链接模式

这是一种单步模式，它接受 C 源文件或 DPA 对象文件，并生成 DPA 程序。在此模式下，指定输出库名称是强制性的。

示例命令

            

            
$ dpacc in1.c in2.c -o myLib1.a -hostcc=gcc -mcpu=nv-dpa-bf3                               # Takes C sources to produce myLib1.a library which supports a single target - nv-dpa-bf3
$ dpacc in3.dpa.o in4.dpa.o -o myLib2.a -hostcc=gcc -mcpu=nv-dpa-bf3,nv-dpa-cx8            # Takes DPA object files to produce myLib2.a library which supports multiple targets - nv-dpa-bf3 and nv-dpa-cx8
$ dpacc in1.c in3.dpa.o -o myLib3.a -hostcc=gcc -mcpu=nv-dpa-bf3,nv-dpa-cx7,nv-dpa-cx8     # Takes C source and DPA object to produce myLib3.a library which supports multiple targets - nv-dpa-bf3, nv-dpa-cx7 and nv-dpa-cx8
        

仅编译模式

此模式接受 C 源代码，并生成 .dpa.o 对象文件。可以将这些文件提供给 DPACC 以生成 DPA 程序。此模式通过 --compile 或 -c 选项调用。

用户可以使用 --output-file 或 -o 选项显式提供输出对象文件名。

示例命令

            

            
$ dpacc -c input1.c -hostcc=gcc -mcpu=nv-dpa-cx7                                     # Produces input1.dpa.o which supports a single target - nv-dpa-cx7
$ dpacc -c input2.c -o myObj.dpa.o -hostcc=gcc -mcpu=nv-dpa-cx8,nv-dpa-cx7           # Produces myObj.dpa.o which supports multiple targets - nv-dpa-cx7 and nv-dpa-cx8
$ dpacc -c input3.c input4.c -hostcc=gcc -mcpu=nv-dpa-bf3,nv-dpa-cx7,nv-dpa-cx8      # Produces input3.dpa.o and input4.dpa.o which support multiple targets - nv-dpa-bf3, nv-dpa-cx7 and nv-dpa-cx8
        

库生成模式

此模式接受 C 源文件或 DPA 对象文件，并生成 DPA 程序。在此模式下，指定输出 DPA 库名称是强制性的。

示例命令

            

            
$ dpacc in1.c in2.c -o libdummy1 -hostcc=gcc -mcpu=nv-dpa-cx8 -gen-libs                                    # Takes C sources to produce a DPA-Library (libdummy1_host.a and libdummy_device.a archives) which supports a single target - nv-dpa-cx8
$ dpacc in3.dpa.o in4.dpa.o -o libdummy2 -hostcc=gcc -mcpu=nv-dpa-cx8,nv-dpa-bf3 -gen-libs                 # Takes DPA object files to produce a DPA-Library (libdummy2_host.a and libdummy2_device.a archives) which supports multiple targets - nv-dpa-bf3 and nv-dpa-cx8
$ dpacc in1.c in3.dpa.o -o outdir/libdummy3 -hostcc=gcc -mcpu=nv-dpa-bf3,nv-dpa-cx7,nv-dpa-cx8 -gen-libs   # Takes C source and DPA object to produce a DPA-Library (outdir/libdummy3_host.a and outdir/libdummy3_device.a archives) which supports multiple targets - nv-dpa-bf3, nv-dpa-cx7 and nv-dpa-cx8
        

要执行 DOCA DPACC 编译器

            

            
Usage: dpacc <list-of-input-files> -hostcc=<path> -mcpu=<targets> [other options]
Helper Flags:
  -h, --help                          Print help information about DPACC
  -V, --version                       Print DPACC version information
  -v, --verbose                       List the compilation commands generated by this invocation while also executing every command in verbose mode
  -dryrun, --dryrun                   Only list the compilation commands generated by DPACC, without executing them
  -keep, --keep                       Keep all intermediate files that are generated during internal compilation steps in the current directory
  -keep-dir, --keep-dir               Keep all intermediate files that are generated during internal compilation steps in the given directory
  -optf, --options-file <file>,...    Include command line options from the specified file
        

强制参数

常用参数

DPA 硬件架构

下表列出了 DPA 架构、编译器中通过 -mcpu 选项支持的相关值以及编译器定义的用于标识这些架构的宏。

由于 ConnectX-7 和 Bluefield-3 共享相同的 DPA 硬件，因此编译器将 nv-dpa-cx7 视为 nv-dpa-bf3 的别名。

链接兼容性

只允许链接链接兼容的可重定位对象。不兼容的对象在链接期间会出错。链接器的工具链版本应与生成对象的编译器的工具链版本相同。

如果两个架构“A”和“B”是链接兼容的，并且“B”比“A”更新，则为目标“A”构建的对象可以链接以构建目标“B”的应用程序。但是，反过来，即将为目标“B”构建的对象链接以构建目标“A”的应用程序是无效的。

Bluefield-3/ConnectX-7 和 ConnectX-8 是链接兼容的，即为 Bluefield-3/ConnectX-7 构建的对象可以链接在一起以构建 ConnectX-8 的应用程序。

架构宏

编译器为每个版本的 DPA 硬件定义标识符宏，如 DPA 硬件架构 部分所述。每个标识符宏将具有唯一的整数值，该值严格大于旧 DPA CPU 型号的宏的整数值。已知的别名（例如 Bluefield-3 DPA 和 ConnectX-7 DPA）共享相同的整数值。宏 __NV_DPA 定义为当前编译目标的值。这可用于编写特定于 DPA 硬件生成的设备代码，如下所示

            

            
#if __NV_DPA == __NV_DPA_BF3
// Code for Bluefield-3 here
#elif __NV_DPA > __NV_DPA_BF3
// Code for devices after Bluefield-3 here
#endif
        

注意：硬件版本标识符宏的值建立的顺序并不意味着硬件支持的功能的顺序。用户有责任确保 DPA 版本特定代码中使用的功能实际上在硬件上受支持。

LTO 使用指南

限制

• LTO 仅支持默认链接器脚本

• 启用 LTO 时，不支持通过 -devicecc-options 使用选项 -fPIC/-fpic/-shared/-mcmodel=large

• 不支持包含 LLVM bitcode 和 ELF 表示的 fat bitcode 对象

• 不支持 Thin LTO

兼容性

在编译期间，当启用 LTO 时，LLVM 将对象生成为 bitcode IR（中间表示），而不是 ELF 表示。DPA 编译器生成的 bitcode IR 仅保证在同一版本中兼容。参与链接时优化（通过 -flto 启用）的对象的编译器工具链版本和执行 LTO 的链接器工具链版本必须相同。

已弃用功能

• 链接 DOCA-DPA 库的 '-ldpa' 选项已弃用，将在未来的版本中删除。应使用选项 '-ldoca_dpa' 代替 '-ldpa'。

示例

本节提供 DPACC 的一些常见用例，并展示 dpacc 命令。

构建库

此示例演示如何使用 DPACC 构建 DPA 库。DPA 库通常包含两个归档，一个用于主机，一个用于设备。

            

            
dpacc input.c -hostcc=gcc -mcpu=nv-dpa-bf3 -o lib<name> -gen-libs -hostcc-options="-fPIC"
        

此命令生成输出文件 lib<name>_host.a 和 lib<name>_device.a。

主机存根归档可以与其他主机代码链接，以生成共享/静态主机库。

• 生成静态主机库

  复制

  已复制！

              
  
              
  ar x lib<name>_host.a                   # Extract objects to generate *.o
  ar cr lib<name>.a <*src.host.o> *.o     # Generate final static archive with all objects
          

• 生成共享主机库

  复制

  已复制！

              
  
              
  gcc -shared -o lib<name>.so <*src.host.o> -Wl,-whole-archive -l<name>_host -Wl,-no-whole-archive       # Link the generated archive to build a shared library
          

与 DPA 设备库链接

DPACC 使用 -gen-libs 作为 DPA 库的一部分生成的 DPA 设备库可以由 DPACC 使用 -device-libs 选项使用。

            

            
dpacc input.c -hostcc=gcc -mcpu=nv-dpa-bf3 -o libInput.a -device-libs="-L <path-to-library> -l<libName>"
        

启用链接时优化

可以使用 -flto 以及为设备编译指定的优化级别来启用链接时优化。

            

            
dpacc input1.c -hostcc=gcc -mcpu=nv-dpa-bf3 -c -flto -devicecc-options="-O2" 
dpacc input2.c -hostcc=gcc -mcpu=nv-dpa-bf3 -c -flto -devicecc-options="-O2"   
dpacc -mcpu=nv-dpa-bf3 input1.dpa.o input2.dpa.o -hostcc=gcc -o libInput.a
        

包含头文件

此示例包含使用 devicecc-options 进行设备编译和使用 hostcc-options 进行主机编译的头文件。您还可以使用 -I 选项为主机和设备端的任何编译指定头文件。

            

            
dpacc input.c -hostcc=gcc -mcpu=nv-dpa-bf3 -o libInput.a -I <common-headers-path> -devicecc-options="-I <device-headers-path>" -hostcc-options="-I <host-headers-path>"
        

转储 fatbinary 文件支持的目标

fatbinary 文件支持的目标可以使用 dpa-fatbin 工具转储。这可以用于从设备归档转储 DPA 库支持的目标。

            

            
dpa-fatbin --list libfoo_device.a
dpa-fatbin --list device_exec.fatbin
        

转储设备 ELF 文件的目标

可以使用 dpa-objdump 工具转储构建设备 ELF 文件的目标。

            

            
dpa-objdump --file-headers foo.o
        

将输出生成为源代码

DPACC 提供了一个 '-src-output' 选项，用于将输出生成为主机源代码。此源代码可以由主机编译器编译，以生成与 DPACC 直接生成的输出功能等效的输出。

此示例演示如何使用此选项将 DPACC 的各种输出构建为源代码，以及如何编译生成的源代码。

DPA-程序源代码

生成 DPA-程序源代码，将此选项传递给 DPACC

            

            
dpacc input.c -hostcc=gcc -mcpu=nv-dpa-bf3 -o libfoo.c -src-output
        

使用主机编译器编译生成的源代码以生成对象，并使用此对象构建归档。在从源代码构建此对象时，需要定义宏 __DPACC_SRC_TARGET__ 以删除构建源代码时不需要的不必要的代码。

            

            
$ gcc libfoo.c -c -I /opt/mellanox/flexio/include -Wno-attributes -Wno-pedantic -Wno-unused-parameter -Wno-return-type -Wno-implicit-function-declaration -D__DPACC_SRC_TARGET__
$ ar cr libfoo.a libfoo.o
        

DPA-库源代码

生成 DPA-库源代码，将此选项传递给 DPACC

            

            
dpacc input.c -hostcc=gcc -mcpu=nv-dpa-bf3 -o libfoo -gen-libs -src-output 
        

这将生成设备归档 libfoo_device.a 和主机代码文件 libfoo.lib.c、input.dpa.c。DPA-库的主机归档通过编译这些源代码并构建归档来生成。在这种情况下，需要定义 __DPACC_SRC_TARGET__ 宏以删除不必要的代码。

            

            
$ gcc libfoo.lib.c input.dpa.c -c -I /opt/mellanox/flexio/include -Wno-attributes -Wno-pedantic -Wno-unused-parameter -Wno-return-type -Wno-implicit-function-declaration -D__DPACC_SRC_TARGET__
$ ar cr libfoo_host.a libfoo.lib.o input.dpa.o
        

DPA-对象源代码

生成 DPA-对象源代码，将此选项传递给 DPACC

            

            
dpacc input.c -hostcc=gcc -mcpu=nv-dpa-bf3 -c -src-output 
        

这将生成单个文件 input.dpa.c。编译主机文件以生成对象。

            

            
gcc input.dpa.c -c -I /opt/mellanox/flexio/include -Wno-attributes -Wno-pedantic -Wno-unused-parameter -Wno-return-type -Wno-implicit-function-declaration
        

DPA 编译器用法

DPA-编译器是基于 LLVM 的编译器，DPACC 在内部使用它来编译和链接设备代码文件。用户指定的选项可以通过 DPACC 选项 '--devicecc-options' 和 '--devicelink-options' 分别传递给编译器和链接器。

有关可以传递的选项，请参阅以下资源

• Clang 编译器用户手册

• Clang 命令行参数参考

• 目标相关的编译选项

• LLD 命令行参考

dpacc-extract 命令行选项

dpacc-extract 是一个用于从 DPA 程序或包含 DPA 程序的主机可执行文件中提取设备可执行文件的工具。

要执行 dpacc-extract

            

            
Usage: dpacc-extract <input-file> -o=<output-file> [other options]
Helper Flags:
 
  -o, --output-file                   Specify name of the output file
  -app-name, --app-name <name>        Specify name of the DPA application to extract
  -mcpu, --mcpu <target>              Specify name of the device for which the application is to be extracted
  -h, --help                          Print help information about dpacc-extract
  -V, --version                       Print dpacc-extract version information
  -optf, --options-file <file>,...    Include command line options from the specified file
        

强制参数

Objdump 命令行选项

dpa-objdump 实用程序打印在命令行上命名的对象文件和最终链接映像的内容。

有关更多信息，请参阅 Objdump 命令行参考。

Archiver 命令行选项

dpa-ar 是与 Unix ar 兼容的归档器。

有关更多信息，请参阅 Archiver 命令行参考。

NM 工具命令行选项

dpa-nm 实用程序列出对象文件和归档中的符号名称。

有关更多信息，请参阅 NM 工具命令行参考。

其他注意事项

• LLD 生成的对象与任何其他链接器生成的对象都不兼容。

• 确保主机应用程序中至少有一个对设备入口点函数的引用，以便在链接期间，DPA 程序不会因未被引用而被主机链接器静默丢弃。

DPACC 1.10.0 中的更改

新功能

• 支持 fatbinary，其中 DPACC 通过“mcpu”选项接受多个目标

• 强制链接策略，其中只能链接兼容的对象

• dpa-objdump 自动推断目标，而无需显式指定“mcpu”选项

• 在生成的主机存根中设置 FLEXIO_VER_USED

• 支持 nv-dpa-cx8 目标上的新内置 __dpa_thread_l1_flush

限制

• 当从 v1.9.0 或更旧版本生成的 DPA 对象构建 DPA 库时，DPACC 会生成关于未知目标的警告