libNVVM API

libNVVM API v4.0 参考手册

1. libNVVM API

1.1. 简介

libNVVM API 提供了从二进制和文本NVVM IR输入生成PTX代码的接口。兼容的输入可由生成LLVM 7.0 IR和位码的工具和库产生。对读取文本NVVM IR表示的支持已被弃用，并可能在后续版本中移除。

1.2. 线程安全性

libNVVM API 提供了一个线程安全的接口来访问 libNVVM。客户端可以通过同时生成多个编译线程来利用改进的编译速度。

1.3. 模块

本章介绍libNVVM库的API。以下是所有模块的列表：

错误处理

通用信息查询

编译

2. 错误处理

枚举

nvvmResult: NVVM API调用结果代码。

Functions

const char * nvvmGetErrorString(nvvmResult result): 获取给定nvvmResult代码对应的消息字符串。

2.1. 枚举

enum nvvmResult

NVVM API调用结果代码。

取值：

enumerator NVVM_SUCCESS

enumerator NVVM_ERROR_OUT_OF_MEMORY

enumerator NVVM_ERROR_PROGRAM_CREATION_FAILURE

enumerator NVVM_ERROR_IR_VERSION_MISMATCH

enumerator NVVM_ERROR_INVALID_INPUT

enumerator NVVM_ERROR_INVALID_PROGRAM

enumerator NVVM_ERROR_INVALID_IR

enumerator NVVM_ERROR_INVALID_OPTION

enumerator NVVM_ERROR_NO_MODULE_IN_PROGRAM

enumerator NVVM_ERROR_COMPILATION

enumerator NVVM_ERROR_CANCELLED

2.2. 函数

const char *nvvmGetErrorString(nvvmResult result)

获取给定nvvmResult代码对应的消息字符串。

Parameters: result – [输入] NVVM API 结果代码。
Returns: 给定nvvmResult代码对应的消息字符串。

3. 通用信息查询

Functions

nvvmResult nvvmIRVersion(int *majorIR, int *minorIR, int *majorDbg, int *minorDbg): 获取NVVM IR版本。
nvvmResult nvvmVersion(int *major, int *minor): 获取NVVM版本。

3.1. 功能

nvvmResult nvvmIRVersion(int *majorIR, int *minorIR, int *majorDbg, int *minorDbg)

获取NVVM IR版本。

Parameters

majorIR – [输出] NVVM IR主版本号。
minorIR – [out] NVVM IR 次要版本号。
majorDbg – [out] NVVM IR调试元数据的主版本号。
minorDbg – [out] NVVM IR调试元数据次要版本号。

Returns

NVVM_SUCCESS

nvvmResult nvvmVersion(int *major, int *minor)

获取NVVM版本。

Parameters

major – [out] NVVM主版本号。
minor – [out] NVVM 次要版本号。

Returns

NVVM_SUCCESS

4. 编译

Functions

nvvmResult nvvmAddModuleToProgram(nvvmProgram prog, const char *buffer, size_t size, const char *name): 向程序中添加一个模块级别的NVVM IR。
nvvmResult nvvmCompileProgram(nvvmProgram prog, int numOptions, const char **options): 编译NVVM程序。
nvvmResult nvvmCreateProgram(nvvmProgram *prog): 创建一个程序，并将其句柄的值设置为*prog。
nvvmResult nvvmDestroyProgram(nvvmProgram *prog): 销毁一个程序。
nvvmResult nvvmGetCompiledResult(nvvmProgram prog, char *buffer): 获取编译结果。
nvvmResult nvvmGetCompiledResultSize(nvvmProgram prog, size_t *bufferSizeRet): 获取编译结果的大小。
nvvmResult nvvmGetProgramLog(nvvmProgram prog, char *buffer): 获取编译器/验证器消息。
nvvmResult nvvmGetProgramLogSize(nvvmProgram prog, size_t *bufferSizeRet): 获取编译器/验证器消息的大小。
nvvmResult nvvmLazyAddModuleToProgram(nvvmProgram prog, const char *buffer, size_t size, const char *name): 向程序添加模块级别的NVVM IR。
nvvmResult nvvmVerifyProgram(nvvmProgram prog, int numOptions, const char **options): 验证NVVM程序。

类型定义

nvvmProgram: NVVM程序。

4.1. 函数

nvvmResult nvvmAddModuleToProgram(nvvmProgram prog, const char *buffer, size_t size, const char *name)

向程序中添加一个模块级别的NVVM IR。

buffer应包含一个NVVM IR模块。该模块应包含LLVM 7.0.1位码表示形式或LLVM 7.0.1文本表示形式的NVVM IR。对读取NVVM IR文本表示形式的支持已被弃用，并可能在后续版本中移除。

Parameters

prog – [输入] NVVM程序。
buffer – [输入] 以位码或文本形式表示的NVVM IR模块。
size – [in] NVVM IR模块的大小。
name – [in] NVVM IR模块的名称。如果为NULL，则使用""作为名称。

Returns

NVVM_SUCCESS
NVVM_ERROR_OUT_OF_MEMORY
NVVM_ERROR_INVALID_INPUT
NVVM_ERROR_INVALID_PROGRAM

nvvmResult nvvmCompileProgram(nvvmProgram prog, int numOptions, const char **options)

编译NVVM程序。

程序中的NVVM IR模块将在IR级别进行链接。链接后的IR程序将被编译为PTX。

链接IR程序中的目标数据布局用于确定地址大小（32位或64位）。

有效的编译器选项包括：

-g（启用完整调试信息生成）。完整调试支持仅在‘-opt=0’时有效。调试支持要求输入模块使用NVVM IR调试元数据。行号（行信息）生成同样通过NVVM IR调试元数据启用，该情况下没有特定的libNVVM API标志。
-opt=
- 0 (禁用优化)
- 3 (默认值，启用优化)
-arch=
- compute_50
- compute_52 (默认)
- compute_53
- compute_60
- compute_61
- compute_62
- compute_70
- compute_72
- compute_75
- compute_80
- compute_87
- compute_89
- compute_90
- compute_90a
- compute_100
- compute_100a
-ftz=
- 0 (默认值，在执行单精度浮点运算时保留非规格化值)
- 1 (在执行单精度浮点运算时，将非规格化数值刷新为零)
-prec-sqrt=
- 0 (使用更快的单精度浮点数平方根近似计算)
- 1 (默认，使用IEEE四舍五入模式计算单精度浮点平方根)
-prec-div=
- 0 (使用更快的近似方法进行单精度浮点除法和倒数运算)
- 1 (默认，单精度浮点除法和倒数运算使用IEEE四舍五入模式)
-fma=
- 0 (禁用FMA收缩)
- 1 (默认值，启用FMA收缩)
-jump-table-density=[0-101] 指定switch语句中的分支密度百分比，作为判断是否使用跳转表(brx.idx指令)来实现switch语句的最小阈值。默认值为101。百分比范围包含0到101。
-gen-lto (生成LTO IR而非PTX)。

Parameters

prog – [输入] NVVM程序。
numOptions – [in] 传入的编译器options数量。
options – [输入] 以C字符串数组形式表示的编译器选项。

Returns

NVVM_SUCCESS
NVVM_ERROR_OUT_OF_MEMORY
NVVM_ERROR_IR_VERSION_MISMATCH
NVVM_ERROR_INVALID_PROGRAM
NVVM_ERROR_INVALID_OPTION
NVVM_ERROR_NO_MODULE_IN_PROGRAM
NVVM_ERROR_COMPILATION

nvvmResult nvvmCreateProgram(nvvmProgram *prog)

创建一个程序，并将其句柄的值设置为*prog。

另请参阅

nvvmDestroyProgram()

Parameters

prog – [输入] NVVM程序。

Returns

NVVM_SUCCESS
NVVM_ERROR_OUT_OF_MEMORY
NVVM_ERROR_INVALID_PROGRAM

nvvmResult nvvmDestroyProgram(nvvmProgram *prog)

销毁一个程序。

另请参阅

nvvmCreateProgram()

Parameters

prog – [输入] NVVM程序。

Returns

NVVM_SUCCESS
NVVM_ERROR_INVALID_PROGRAM

nvvmResult nvvmGetCompiledResult(nvvmProgram prog, char *buffer)

获取编译结果。

结果存储在由buffer指向的内存中。

Parameters

prog – [输入] NVVM程序。
buffer – [out] 编译结果。

Returns

NVVM_SUCCESS
NVVM_ERROR_INVALID_PROGRAM

nvvmResult nvvmGetCompiledResultSize(nvvmProgram prog, size_t *bufferSizeRet)

获取编译结果的大小。

Parameters

prog – [输入] NVVM程序。
bufferSizeRet – [输出] 编译结果的大小（包含结尾的NULL字符）。

Returns

NVVM_SUCCESS
NVVM_ERROR_INVALID_PROGRAM

nvvmResult nvvmGetProgramLog(nvvmProgram prog, char *buffer)

获取编译器/验证器消息。

当返回值为NVVM_SUCCESS时，以NULL结尾的消息字符串存储在buffer指向的内存中。

Parameters

prog – [输入] NVVM程序。
buffer – [out] 编译/验证日志。

Returns

NVVM_SUCCESS
NVVM_ERROR_INVALID_PROGRAM

nvvmResult nvvmGetProgramLogSize(nvvmProgram prog, size_t *bufferSizeRet)

获取编译器/验证器消息的大小。

当返回值为NVVM_SUCCESS时，消息字符串的大小（包括结尾的NULL字符）将被存储到bufferSizeRet中。

Parameters

prog – [输入] NVVM程序。
bufferSizeRet – [输出] 编译/验证日志的大小（包含结尾的NULL字符）。

Returns

NVVM_SUCCESS
NVVM_ERROR_INVALID_PROGRAM

nvvmResult nvvmLazyAddModuleToProgram(nvvmProgram prog, const char *buffer, size_t size, const char *name)

向程序中添加一个模块级别的NVVM IR。

buffer 应包含一个 NVVM IR 模块。该模块应采用 LLVM 7.0.1 位码格式的 NVVM IR。

通过此API添加的模块采用延迟加载方式——仅加载那些由使用nvvmAddModuleToProgram加载的模块所必需的符号。若程序中所有模块都通过此API加载将导致错误。编译器还可能通过将这些实体内部化到链接的NVVM IR模块中，对此模块中的实体进行优化，使其有资格进行其他优化。由于这些优化，此加载模块的API效率更高，应尽可能使用。

Parameters

prog – [输入] NVVM程序。
buffer – [输入] 以位码形式表示的NVVM IR模块。
size – [in] NVVM IR模块的大小。
name – [in] NVVM IR模块的名称。如果为NULL，则使用"<unnamed>"作为名称。

Returns

NVVM_SUCCESS
NVVM_ERROR_OUT_OF_MEMORY
NVVM_ERROR_INVALID_INPUT
NVVM_ERROR_INVALID_PROGRAM

nvvmResult nvvmVerifyProgram(nvvmProgram prog, int numOptions, const char **options)

验证NVVM程序。

有效的编译器选项包括：

与 nvvmCompileProgram() 相同。

另请参阅

nvvmCompileProgram()

Parameters

prog – [输入] NVVM程序。
numOptions – [in] 传递的编译器options数量。
options – [输入] 以C字符串数组形式表示的编译器选项。

Returns

NVVM_SUCCESS
NVVM_ERROR_OUT_OF_MEMORY
NVVM_ERROR_IR_VERSION_MISMATCH
NVVM_ERROR_INVALID_PROGRAM
NVVM_ERROR_INVALID_IR
NVVM_ERROR_INVALID_OPTION
NVVM_ERROR_NO_MODULE_IN_PROGRAM

4.2. 类型定义

typedef struct _nvvmProgram *nvvmProgram

NVVM程序。

程序的不透明句柄。

5. 通知

5.1. 注意事项

本文档仅供信息参考之用，不应视为对产品功能、状态或质量的保证。NVIDIA公司（“NVIDIA”）对本文件所含信息的准确性或完整性不作任何明示或暗示的陈述或保证，并对其中可能存在的错误不承担任何责任。NVIDIA对于因使用此类信息而产生的后果、或因使用该信息导致的第三方专利或其他权利侵权概不负责。本文件不构成对开发、发布或交付任何材料（定义见下文）、代码或功能的承诺。

NVIDIA保留随时对本文件进行更正、修改、增强、改进以及任何其他变更的权利，恕不另行通知。

客户在下单前应获取最新的相关信息，并确认这些信息是最新且完整的。

除非NVIDIA与客户授权代表签署的单独销售协议中另有约定，否则NVIDIA产品的销售均以订单确认时提供的NVIDIA标准销售条款和条件为准（以下简称"销售条款"）。NVIDIA特此明确反对将任何客户通用条款适用于本文件所述NVIDIA产品的采购。本文件不直接或间接构成任何合同义务。

NVIDIA产品并非设计、授权或保证适用于医疗、军事、航空、航天或生命支持设备，也不适用于那些可以合理预期NVIDIA产品故障或失灵会导致人身伤害、死亡、财产或环境损害的应用场景。NVIDIA对于在此类设备或应用中使用和/或包含NVIDIA产品不承担任何责任，因此客户需自行承担相关风险。

NVIDIA不声明或保证基于本文档的产品适用于任何特定用途。NVIDIA未必会对每个产品的所有参数进行测试。客户应全权负责评估和确定本文档所含信息的适用性，确保产品适合并满足客户计划的应用需求，并执行必要的应用测试以避免应用或产品出现故障。客户产品设计中的缺陷可能会影响NVIDIA产品的质量和可靠性，并可能导致超出本文档范围的其他或不同的条件和/或要求。对于任何因以下原因导致的故障、损坏、成本或问题，NVIDIA不承担任何责任：(i) 以违反本文档的任何方式使用NVIDIA产品或(ii) 客户产品设计。

本文档不授予任何NVIDIA专利权、版权或其他NVIDIA知识产权的明示或暗示许可。NVIDIA发布的关于第三方产品或服务的信息，不构成NVIDIA对这些产品或服务的使用许可或担保认可。使用此类信息可能需要获得第三方基于其专利或其他知识产权的许可，或需要获得NVIDIA基于其专利或其他知识产权的许可。

本文件中的信息仅可在获得NVIDIA事先书面批准、未经改动完整复制且完全符合所有适用的出口法律法规，并附带所有相关条件、限制和声明的情况下进行复制。

本文件及所有NVIDIA设计规格、参考板、文件、图纸、诊断工具、清单和其他文档（统称及单独称为"材料"）均以"现状"提供。NVIDIA不对材料作出任何明示或默示的保证，包括但不限于对不侵权、适销性和特定用途适用性的默示保证免责。在法律允许的最大范围内，NVIDIA不就因使用本文件导致的任何损害承担责任，包括但不限于任何直接、间接、特殊、附带、惩罚性或后果性损害，无论损害成因如何，也无论责任理论为何，即使NVIDIA已被告知发生此类损害的可能性。不论客户因任何原因可能遭受的任何损害，NVIDIA对客户就本文所述产品的全部及累计责任应受产品销售条款的限制。

5.2. OpenCL

OpenCL是苹果公司的商标，经Khronos Group Inc.授权使用。

5.3. 商标

NVIDIA和NVIDIA标识是美国及其他国家NVIDIA公司的商标或注册商标。其他公司及产品名称可能是其各自关联公司的商标。