cuBLAS开发指南中文版

cuBLAS 的 API 参考指南，CUDA 基本线性代数子程序库(CUDA Basic Linear Algebra Subroutine)。

1.简介

cuBLAS 库是 BLAS（基本线性代数子程序）在 NVIDIA®CUDA™ 运行时之上的实现。它允许用户访问 NVIDIA 图形处理单元 (GPU) 的计算资源。

cuBLAS 库公开了三组 API：

• cuBLAS API，在本文档中简称为 cuBLAS API（从 CUDA 6.0 开始），
• cuBLASXt API（从 CUDA 6.0 开始），以及
• cuBLASLt API（从 CUDA 10.1 开始）

要使用 cuBLAS API，应用程序必须在 GPU 内存空间中分配所需的矩阵和向量，用数据填充它们，调用所需的 cuBLAS 函数序列，然后将结果从 GPU 内存空间上传回主机。 cuBLAS API 还提供了用于从 GPU 写入和检索数据的辅助函数。

要使用 cuBLASXt API，应用程序可能在主机或任何参与计算的设备上拥有数据，库将负责将操作分派到存在于一个或多个 GPU 上，并将数据传输到系统，取决于用户的要求。

cuBLASLt 是一个轻量级库，专用于通用矩阵到矩阵乘法 (GEMM) 操作，具有新的灵活 API。该库增加了矩阵数据布局、输入类型、计算类型以及通过参数可编程性选择算法实现和启发式的灵活性。在用户确定了一组用于预期 GEMM 操作的选项后，这些选项可以重复用于不同的输入。这类似于 cuFFT 和 FFTW 如何首先创建计划并重用具有不同输入数据的相同大小和类型的 FFT。

1.1 数据布局

为了最大限度地兼容现有的 Fortran 环境，cuBLAS 库使用列优先存储和基于 1 的索引。 由于 C 和 C++ 使用行优先存储，用这些语言编写的应用程序不能将原生数组语义用于二维数组。 相反，应该定义宏或内联函数以在一维数组之上实现矩阵。 对于以机械方式移植到 C 的 Fortran 代码，可以选择保留基于 1 的索引以避免转换循环的需要。 在这种情况下，可以通过以下宏计算“i”行和“j”列中矩阵元素的数组索引

#define IDX2F(i,j,ld) ((((j)-1)*(ld))+((i)-1))
1

这里，ld 指的是矩阵的前导维度，在以列为主存储的情况下，它是分配矩阵的行数（即使只使用了它的子矩阵）。 对于原生编写的 C 和 C++ 代码，很可能会选择基于 0 的索引，在这种情况下，可以通过以下宏计算矩阵元素在“i”行和“j”列中的数组索引

#define IDX2C(i,j,ld) (((j)*(ld))+(i))
1

1.2 新旧 cuBLAS API

从 4.0 版开始，cuBLAS 库除了现有的旧 API 外，还提供了一个新的 API。本节讨论为什么提供新 API、使用它的优点以及与现有旧 API 的区别。

警告：旧版 cuBLAS API 已弃用，将在未来版本中删除。
新的 cuBLAS 库 API 可以通过包含头文件“cublas_v2.h”来使用。它具有传统 cuBLAS API 所不具备的以下功能：

• cuBLAS 库上下文的句柄使用函数初始化，并显式传递给每个后续库函数调用。这允许用户在使用多个主机线程和多个 GPU 时更好地控制库设置。这也允许 cuBLAS API 可重入。
• 标量$\alpha$ 和$\beta$ 可以在主机或设备上通过引用传递，而不是只允许在主机上按值传递。此更改允许库函数使用流异步执行，即使在之前的内核生成时也是如此。
• 当一个库例程返回一个标量结果时，它可以在主机或设备上通过引用返回，而不是只允许在主机上按值返回。此更改允许在生成标量结果并在设备上通过引用返回时异步调用库例程，从而实现最大并行度。
• 错误状态 cublasStatus_t 由所有 cuBLAS 库函数调用返回。此更改有助于调试并简化软件开发。请注意，cublasStatus 已重命名为 cublasStatus_t 以与 cuBLAS 库中的其他类型更加一致。
• cublasAlloc() 和 cublasFree() 函数已被弃用。此更改分别删除了 cudaMalloc() 和 cudaFree() 周围的这些不必要的包装器。
• 函数 cublasSetKernelStream() 被重命名为 cublasSetStream() 以与其他 CUDA 库更加一致。

遗留的 cuBLAS API，在附录 A 中有更详细的解释，可以通过包含头文件“cublas.h”来使用。由于旧版 API 与之前发布的 cuBLAS 库 API 相同，现有应用程序将开箱即用并自动使用此旧版 API，无需更改任何源代码。

当前和旧版 cuBLAS API 不能在单个翻译单元中同时使用：同时包含“cublas.h”和“cublas_v2.h”头文件将由于不兼容的符号重新声明而导致编译错误。

通常，新应用程序不应使用旧版 cuBLAS API，如果现有应用程序需要复杂和最佳的流并行性，或者如果它从多个线程同时调用 cuBLAS 例程，则现有应用程序应转换为使用新 API。

对于文档的其余部分，新的 cuBLAS 库 API 将简称为 cuBLAS 库 API。

如前所述，传统和 cuBLAS 库 API 的接口分别是头文件“cublas.h”和“cublas_v2.h”。此外，使用 cuBLAS 库的应用程序需要链接：

• Linux 的 DSO cublas.so，
• 适用于 Windows 的 DLL cublas.dll，或
• Mac OS X 的动态库 cublas.dylib。

注意：同一个动态库同时实现了新的和旧的 cuBLAS API。

1.3 示例代码

有关示例代码参考，请参阅下面的两个示例。 他们展示了一个使用 C 语言编写的应用程序，该应用程序使用具有两种索引样式的 cuBLAS 库 API（示例 1.“使用 C 和 cuBLAS 的应用程序：基于 1 的索引”和示例 2.“使用 C 和 cuBLAS 的应用程序：基于 0 的索引”）。

//Example 1. Application Using C and cuBLAS: 1-based indexing
//-----------------------------------------------------------
#include 
#include 
#include 
#include 
#include "cublas_v2.h"
#define M 6
#define N 5
#define IDX2F(i,j,ld) ((((j)-1)*(ld))+((i)-1))

static __inline__ void modify (cublasHandle_t handle, float *m, int ldm, int n, int p, int q, float alpha, float beta){
    cublasSscal (handle, n-q+1, &alpha, &m[IDX2F(p,q,ldm)], ldm);
    cublasSscal (handle, ldm-p+1, &beta, &m[IDX2F(p,q,ldm)], 1);
}

int main (void){
    cudaError_t cudaStat;
    cublasStatus_t stat;
    cublasHandle_t handle;
    int i, j;
    float* devPtrA;
    float* a = 0;
    a = (float *)malloc (M * N * sizeof (*a));
    if (!a) {
        printf ("host memory allocation failed");
        return EXIT_FAILURE;
    }
    for (j = 1; j <= N; j++) {
        for (i = 1; i <= M; i++) {
            a[IDX2F(i,j,M)] = (float)((i-1) * N + j);
        }
    }
    cudaStat = cudaMalloc ((void**)&devPtrA, M*N*sizeof(*a));
    if (cudaStat != cudaSuccess) {
        printf ("device memory allocation failed");
        return EXIT_FAILURE;
    }
    stat = cublasCreate(&handle);
    if (stat != CUBLAS_STATUS_SUCCESS) {
        printf ("CUBLAS initialization failed\n");
        return EXIT_FAILURE;
    }
    stat = cublasSetMatrix (M, N, sizeof(*a), a, M, devPtrA, M);
    if (stat != CUBLAS_STATUS_SUCCESS) {
        printf ("data download failed");
        cudaFree (devPtrA);
        cublasDestroy(handle);
        return EXIT_FAILURE;
    }
    modify (handle, devPtrA, M, N, 2, 3, 16.0f, 12.0f);
    stat = cublasGetMatrix (M, N, sizeof(*a), devPtrA, M, a, M);
    if (stat != CUBLAS_STATUS_SUCCESS) {
        printf ("data upload failed");
        cudaFree (devPtrA);
        cublasDestroy(handle);
        return EXIT_FAILURE;
    }
    cudaFree (devPtrA);
    cublasDestroy(handle);
    for (j = 1; j <= N; j++) {
        for (i = 1; i <= M; i++) {
            printf ("%7.0f", a[IDX2F(i,j,M)]);
        }
        printf ("\n");
    }
    free(a);
    return EXIT_SUCCESS;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

---

//Example 2. Application Using C and cuBLAS: 0-based indexing
//-----------------------------------------------------------
#include 
#include 
#include 
#include 
#include "cublas_v2.h"
#define M 6
#define N 5
#define IDX2C(i,j,ld) (((j)*(ld))+(i))

static __inline__ void modify (cublasHandle_t handle, float *m, int ldm, int n, int p, int q, float alpha, float beta){
    cublasSscal (handle, n-q, &alpha, &m[IDX2C(p,q,ldm)], ldm);
    cublasSscal (handle, ldm-p, &beta, &m[IDX2C(p,q,ldm)], 1);
}

int main (void){
    cudaError_t cudaStat;
    cublasStatus_t stat;
    cublasHandle_t handle;
    int i, j;
    float* devPtrA;
    float* a = 0;
    a = (float *)malloc (M * N * sizeof (*a));
    if (!a) {
        printf ("host memory allocation failed");
        return EXIT_FAILURE;
    }
    for (j = 0; j < N; j++) {
        for (i = 0; i < M; i++) {
            a[IDX2C(i,j,M)] = (float)(i * N + j + 1);
        }
    }
    cudaStat = cudaMalloc ((void**)&devPtrA, M*N*sizeof(*a));
    if (cudaStat != cudaSuccess) {
        printf ("device memory allocation failed");
        return EXIT_FAILURE;
    }
    stat = cublasCreate(&handle);
    if (stat != CUBLAS_STATUS_SUCCESS) {
        printf ("CUBLAS initialization failed\n");
        return EXIT_FAILURE;
    }
    stat = cublasSetMatrix (M, N, sizeof(*a), a, M, devPtrA, M);
    if (stat != CUBLAS_STATUS_SUCCESS) {
        printf ("data download failed");
        cudaFree (devPtrA);
        cublasDestroy(handle);
        return EXIT_FAILURE;
    }
    modify (handle, devPtrA, M, N, 1, 2, 16.0f, 12.0f);
    stat = cublasGetMatrix (M, N, sizeof(*a), devPtrA, M, a, M);
    if (stat != CUBLAS_STATUS_SUCCESS) {
        printf ("data upload failed");
        cudaFree (devPtrA);
        cublasDestroy(handle);
        return EXIT_FAILURE;
    }
    cudaFree (devPtrA);
    cublasDestroy(handle);
    for (j = 0; j < N; j++) {
        for (i = 0; i < M; i++) {
            printf ("%7.0f", a[IDX2C(i,j,M)]);
        }
        printf ("\n");
    }
    free(a);
    return EXIT_SUCCESS;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69