NVBLAS

NVBLAS用户指南：即插即用的BLAS替代方案，支持多GPU加速

1. 简介

NVBLAS库是一个基于GPU加速的库，实现了BLAS（基础线性代数子程序）。当调用特性适合在GPU上加速时，它可以通过动态将BLAS调用路由到系统中一个或多个NVIDIA GPU，来加速大多数BLAS Level-3例程。

2. NVBLAS 概述

NVBLAS库构建于cuBLAS库之上，仅使用CUBLASXT API（更多详情请参阅cuBLAS文档中的CUBLASXT API章节）。NVBLAS还需要系统上存在CPU BLAS库。目前NVBLAS仅拦截计算密集型的BLAS Level-3调用（见下表）。根据这些BLAS调用的特性，NVBLAS会将调用重定向到系统中的GPU或CPU。该决策基于一个简单的启发式算法，用于估算BLAS调用执行时间是否足够长以分摊输入和输出数据到GPU的PCI传输开销。由于NVBLAS不支持所有标准BLAS例程，可能需要将其与现有的完整BLAS库关联使用。更多详情请参阅使用章节。

3. GPU加速例程

NVBLAS仅卸载计算密集型的BLAS3例程，这些例程在GPU上具有最佳的加速潜力。

下表展示了当前支持的功能例程:

例程	类型	操作
gemm	S,D,C,Z	两个矩阵的乘法
syrk	S,D,C,Z	对称秩-k更新
herk	C,Z	厄米特矩阵秩k更新
syr2k	S,D,C,Z	对称秩-2k更新
her2k	C,Z	厄米特矩阵秩-2k更新
trsm	S,D,C,Z	三角矩阵多右端求解
trmm	S,D,C,Z	三角矩阵乘法
symm	S,D,C,Z	对称矩阵乘法
hemm	C,Z	厄米特矩阵乘法

4. BLAS符号拦截

标准BLAS库实现通常会为同一例程暴露多个符号。假设func是一个BLAS例程名称，func_或/和func通常被定义为外部符号。某些BLAS库可能还会暴露带有专有前缀的符号。NVBLAS仅拦截func_和func这两个符号。用户需要确保那些希望通过NVBLAS进行GPU加速的应用程序实际调用的是这些已定义的符号。对于任何其他符号，NVBLAS将不会拦截，这些情况下将执行原始的BLAS例程。

5. 设备内存支持

从8.0版本开始，数据可以存放在任何GPU设备上，甚至包括未配置参与计算的GPU设备。当任意数据位于GPU上时，无论问题规模大小，计算都将完全在GPU上执行。但需谨慎使用此功能：用户必须确保BLAS调用确实会被NVBLAS拦截，否则当CPU BLAS尝试执行时会导致崩溃。

6. 安全注意事项

由于NVBLAS库依赖于符号拦截机制，必须确保该机制未被破坏。在这方面，NVBLAS绝不应在具有提升权限的进程中使用，例如Windows上的管理员或Linux上的root用户。

7. 配置

由于NVBLAS是BLAS的直接替代品，它必须通过一个ASCII文本文件进行配置，该文件描述了有多少以及哪些GPU可以参与拦截的BLAS调用。配置文件在加载库时被解析。配置文件的格式基于关键字，可选地后跟一个或多个用户定义的参数。每行最多允许一个关键字。以#字符开头的空行或行将被忽略。

7.1. NVBLAS_CONFIG_FILE 环境变量

配置文件的位置和名称必须由环境变量NVBLAS_CONFIG_FILE定义。默认情况下，如果未定义NVBLAS_CONFIG_FILE，NVBLAS将尝试打开当前目录中的nvblas.conf文件。为了安全使用NVBLAS，配置文件应设置受限的写入权限。

7.2. 配置关键词

配置关键字的语法在以下小节中描述。

7.2.1. NVBLAS_LOGFILE

此关键字定义NVBLAS应打印状态和错误消息的文件。默认情况下，如果未定义，将使用标准错误输出文件（如stderr）。建议在配置文件中尽早定义此关键字，以便捕获解析该文件本身时产生的错误。

7.2.2. NVBLAS_TRACE_LOG_ENABLED

当定义此关键字时，所有被拦截的BLAS调用将被记录到NVBLAS_LOGFILE中。尽管这个功能具有侵入性，但对于调试目的非常有用。

7.2.3. NVBLAS_CPU_BLAS_LIB

此关键字定义了NVBLAS应打开的CPU BLAS动态库文件（例如，Linux上的.so文件或Windows上的.dll），以查找CPU BLAS符号定义。必须定义此关键字才能使NVBLAS正常工作。由于CPU BLAS库通常由多个文件组成，即使将此关键字设置为CPU库主文件的完整路径，可能仍需要在系统环境中定义正确的路径以查找库的其余文件。在Linux上，可以通过设置环境变量LD_LIBRARY_PATH来实现，而在Windows上，则可以通过设置环境变量PATH来实现。

为了安全使用NVBLAS，强烈建议采取以下预防措施：

CPU BLAS库应位于普通用户没有写入权限的位置。
指定的路径应为绝对路径，而非相对路径。

7.2.4. NVBLAS_GPU列表

该关键字定义了应参与拦截的BLAS调用计算的GPU列表。如果未定义，则仅使用GPU设备0，因为通常是系统中计算能力最强的GPU。此关键字可设置为由空格字符分隔的设备编号列表。为简化操作，还接受以下通配符关键字：

关键词	含义
`ALL`	NVBLAS将使用系统上检测到的所有支持计算功能的GPU
`ALL0`	GPU设备0，以及所有检测到与设备0具有相同计算能力的其他GPU都将被NVBLAS使用

注意

在当前版本的CUBLAS中，如果GPU位于同一块板上（例如Tesla K10或GeForce GTX690），CUBLASXT API支持两个GPU，否则只支持一个GPU。由于NVBLAS构建在CUBLASXT API之上，NVBLAS具有相同的限制。如果需要访问更多GPU设备，许可详情请参阅cublasXt。

7.2.5. NVBLAS_TILE_DIM

该关键字定义了用于划分计算中涉及的矩阵的块维度。此定义直接映射到cublasXt API例程cublasXtSetBlockDim的调用。请参阅cuBLAS文档以了解将此值设置为较大或较小数值时涉及的权衡。

7.2.6. NVBLAS_GPU_DISABLED_

该关键字后接BLAS例程名称时，会禁止NVBLAS在GPU上运行指定的例程。此功能主要用于调试目的。默认情况下，所有受支持的BLAS例程均处于启用状态。

7.2.7. NVBLAS_CPU_RATIO_

该关键字与BLAS例程名称一起使用时，用于定义当NVBLAS决定将该例程的工作负载卸载到GPU时，应保留在CPU上的工作量比例。此功能直接映射到cublasXt API例程cublasXtSetCpuRatio。默认情况下，所有例程的该比例都设为零。详情及支持此功能的例程列表请参阅cuBLAS文档。

7.2.8. NVBLAS_AUTOPIN_MEM_ENABLED

此关键字用于启用固定内存模式。该功能直接映射到cublasXt API例程cublasXtSetPinningMemMode。如果配置文件中未出现此关键字，固定内存模式将被设置为CUBLASXT_PINNING_DISABLED。

注意

There are some restrictions to use this feature as specified in the cuBLAS documentation of the underlying routine cublasXtSetPinningMemMode. Specifically when NVBLAS is used in a multi-threaded applications, this option should not be used if there is a chance that matrices used by different threads overlaps while calling NVBLAS. Please refer to the cuBLAS Documentation of the routine `cublasXtSetPinningMemMode <https://docs.nvidia.com/cuda/cublas/index.html#cublasxt_setPinningMemMode>`__ for details.

7.2.9. 配置文件示例

以下示例展示了一个典型的NVBLAS配置文件：

# This is the configuration file to use NVBLAS Library
# Setup the environment variable NVBLAS_CONFIG_FILE to specify your own config file.
# By default, if NVBLAS_CONFIG_FILE is not defined,
# NVBLAS Library will try to open the file "nvblas.conf" in its current directory
# Example : NVBLAS_CONFIG_FILE  /home/cuda_user/my_nvblas.conf
# The config file should have restricted write permissions accesses

# Specify which output log file (default is stderr)
NVBLAS_LOGFILE  nvblas.log

# Enable trace log of every intercepted BLAS calls
NVBLAS_TRACE_LOG_ENABLED

#Put here the CPU BLAS fallback Library of your choice
#It is strongly advised to use full path to describe the location of the CPU Library
NVBLAS_CPU_BLAS_LIB  /usr/lib/libopenblas.so
#NVBLAS_CPU_BLAS_LIB  <mkl_path_installtion>/libmkl_rt.so

# List of GPU devices Id to participate to the computation
# Use ALL if you want all your GPUs to contribute
# Use ALL0, if you want all your GPUs of the same type as device 0 to contribute
# However, NVBLAS consider that all GPU have the same performance and PCI bandwidth
# By default if no GPU are listed, only device 0 will be used

#NVBLAS_GPU_LIST 0 2 4
#NVBLAS_GPU_LIST ALL
NVBLAS_GPU_LIST ALL0

# Tile Dimension
NVBLAS_TILE_DIM 2048

# Autopin Memory
NVBLAS_AUTOPIN_MEM_ENABLED

#List of BLAS routines that are prevented from running on GPU (use for debugging purpose
# The current list of BLAS routines supported by NVBLAS are
# GEMM, SYRK, HERK, TRSM, TRMM, SYMM, HEMM, SYR2K, HER2K

#NVBLAS_GPU_DISABLED_SGEMM
#NVBLAS_GPU_DISABLED_DGEMM
#NVBLAS_GPU_DISABLED_CGEMM
#NVBLAS_GPU_DISABLED_ZGEMM

# Computation can be optionally hybridized between CPU and GPU
# By default, GPU-supported BLAS routines are ran fully on GPU
# The option NVBLAS_CPU_RATIO_<BLAS_ROUTINE> give the ratio [0,1]
# of the amount of computation that should be done on CPU
# CAUTION : this option should be used wisely because it can actually
# significantly reduced the overall performance if too much work is given to CPU

#NVBLAS_CPU_RATIO_CGEMM 0.07

8. NVBLAS 安装指南

NVBLAS库是CUDA工具包的一部分，将随其他所有CUDA库一起安装。它适用于64位操作系统。NVBLAS库构建于cuBLAS之上，因此NVBLAS需要能够访问cuBLAS库。

9. 使用指南

要使用NVBLAS库，用户应用程序除了原始CPU BLAS外，还需重新链接到NVBLAS（技术上仅需NVBLAS，除非应用程序使用了NVBLAS不支持的某些BLAS例程）。为确保链接器链接的是NVBLAS暴露的符号而非CPU BLAS的符号，需要在链接命令行中将NVBLAS库置于CPU BLAS之前。

在Linux系统上，使用NVBLAS库的另一种方法是通过LD_PRELOAD环境变量；这种技术的优势在于可以避免重新链接的步骤。但用户应避免全局定义该环境变量，因为这会导致系统执行的每个shell命令都加载NVBLAS库，从而导致系统响应迟缓。

最后，数学工具和库通常允许通过环境变量或配置文件指定要使用的BLAS库。由于NVBLAS不支持所有标准BLAS例程，即使您的应用程序仅调用受支持的NVBLAS例程，也可能需要将NVBLAS与完整的BLAS库配对使用。幸运的是，这些工具和库通常提供指定多个BLAS库的方法。详情请参阅相关工具和库的文档。

10. 通知

10.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对客户就本文所述产品的全部及累计责任应受产品销售条款的限制。

10.2. OpenCL

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

10.3. 商标

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