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 调用结果代码。
函数
- 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
-
enumerator NVVM_SUCCESS
2.2. 函数
-
const char *nvvmGetErrorString(nvvmResult result)
-
获取给定 nvvmResult 代码的消息字符串。
- 参数
-
result – [in] NVVM API 结果代码。
- 返回值
-
给定 nvvmResult 代码的消息字符串。
3. 常规信息查询
函数
- 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 版本。
- 参数
-
majorIR – [out] NVVM IR 主版本号。
minorIR – [out] NVVM IR 次版本号。
majorDbg – [out] NVVM IR 调试元数据主版本号。
minorDbg – [out] NVVM IR 调试元数据次版本号。
- 返回值
-
nvvmResult nvvmVersion(int *major, int *minor)
-
获取 NVVM 版本。
- 参数
-
major – [out] NVVM 主版本号。
minor – [out] NVVM 次版本号。
- 返回值
4. 编译
函数
- 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 的文本表示形式的支持已被弃用，并可能在以后的版本中删除。- 参数
-
prog – [in] NVVM 程序。
buffer – [in] 位代码或文本表示形式的 NVVM IR 模块。
size – [in] NVVM IR 模块的大小。
name – [in] NVVM IR 模块的名称。如果为 NULL，则使用“<unnamed>”作为名称。
- 返回值
-
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 语句中的 case 密度百分比，并将其用作确定是否将使用跳转表（brx.idx 指令）来实现 switch 语句的最小阈值。默认值为 101。百分比范围为 0 到 101，包括 0 和 101。
-gen-lto（生成 LTO IR 而不是 PTX）。
- 参数
-
prog – [in] NVVM 程序。
numOptions – [in] 传递的编译器
options的数量。options – [in] C 字符串数组形式的编译器选项。
- 返回值
-
nvvmResult nvvmCreateProgram(nvvmProgram *prog)
-
创建一个程序，并将其句柄的值设置为
*prog。另请参阅
- 参数
-
prog – [in] NVVM 程序。
- 返回值
-
nvvmResult nvvmDestroyProgram(nvvmProgram *prog)
-
销毁一个程序。
另请参阅
- 参数
-
prog – [in] NVVM 程序。
- 返回值
-
nvvmResult nvvmGetCompiledResult(nvvmProgram prog, char *buffer)
-
获取编译结果。
结果存储在
buffer指向的内存中。- 参数
-
prog – [in] NVVM 程序。
buffer – [out] 编译结果。
- 返回值
-
nvvmResult nvvmGetCompiledResultSize(nvvmProgram prog, size_t *bufferSizeRet)
-
获取编译结果的大小。
- 参数
-
prog – [in] NVVM 程序。
bufferSizeRet – [out] 编译结果的大小（包括尾部的 NULL）。
- 返回值
-
nvvmResult nvvmGetProgramLog(nvvmProgram prog, char *buffer)
-
获取编译器/验证器消息。
当返回值为 NVVM_SUCCESS 时，NULL 终止的消息字符串存储在
buffer指向的内存中。- 参数
-
prog – [in] NVVM 程序。
buffer – [out] 编译/验证日志。
- 返回值
-
nvvmResult nvvmGetProgramLogSize(nvvmProgram prog, size_t *bufferSizeRet)
-
获取编译器/验证器消息的大小。
当返回值为 NVVM_SUCCESS 时，消息字符串的大小（包括尾部的 NULL）存储到
bufferSizeRet中。- 参数
-
prog – [in] NVVM 程序。
bufferSizeRet – [out] 编译/验证日志的大小（包括尾部的 NULL）。
- 返回值
-
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 加载模块效率更高，应尽可能使用。
- 参数
-
prog – [in] NVVM 程序。
buffer – [in] 位代码表示形式的 NVVM IR 模块。
size – [in] NVVM IR 模块的大小。
name – [in] NVVM IR 模块的名称。如果为 NULL，则使用“<unnamed>”作为名称。
- 返回值
-
nvvmResult nvvmVerifyProgram(nvvmProgram prog, int numOptions, const char **options)
-
验证 NVVM 程序。
有效的编译器选项包括
与 nvvmCompileProgram() 相同。
另请参阅
- 参数
-
prog – [in] NVVM 程序。
numOptions – [in] 传递的编译器
options的数量。options – [in] C 字符串数组形式的编译器选项。
- 返回值
4.2. 类型定义
-
typedef struct _nvvmProgram *nvvmProgram
-
NVVM 程序。
程序的不透明句柄。
5. 注意事项
5.1. 注意
本文档仅供参考，不应被视为对产品的特定功能、状况或质量的保证。NVIDIA Corporation (“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 已被告知可能发生此类损害。尽管客户可能因任何原因遭受任何损害，NVIDIA 对客户就本文所述产品承担的总体和累积责任应根据产品的销售条款进行限制。
5.2. OpenCL
OpenCL 是 Apple Inc. 的商标，已获得 Khronos Group Inc. 的许可使用。
5.3. 商标
NVIDIA 和 NVIDIA 标识是 NVIDIA Corporation 在美国和其他国家/地区的商标或注册商标。其他公司和产品名称可能是与其各自公司相关的商标。