cuBLAS使用（1）

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

介绍

cuBLAS库是在NVIDIA®CUDA™运行时之上实现的BLAS（基本线性代数子程序）。它允许用户访问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内存空间上传回主机HOST。cuBLAS API还提供用于从GPU写入和检索数据的辅助函数。
要使用cuBLASXt API，应用程序可能在主机或计算中涉及的任何设备上拥有数据，库将负责将操作分派到系统中的一个或多个GPU，并将数据传输到这些GPU，具体取决于用户请求。

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

数据布局

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

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

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

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

新旧 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（在使用cuBLAS传统API中有更详细的说明）可通过包含头文件cublas. h来使用。由于传统API与先前发布的cuBLAS库API相同，因此现有应用程序将开箱即用，并自动使用此传统API，而无需更改任何源代码。
当前和传统的cuBLAS API不能在单个翻译单元中同时使用：同时包含cublas. h和cublas_v2. h头文件将导致编译错误，因为重新声明了不兼容的符号。
一般来说，新应用程序不应使用传统的cuBLAS API，如果现有应用程序需要复杂且最佳的流并行性，或者如果它从多个线程并发调用cuBLAS例程，则应转换为使用新API。
在本文档的其余部分，新的cuBLAS库API将简称为cuBLAS库API。
如前所述，传统API和cuBLAS库API的接口分别是头文件cublas. h和cublas_v2.h。此外，使用cuBLAS库的应用程序需要链接到：

• The DSO cublas.so for Linux
• The DLL cublas.dll for Windows, or
• The dynamic library cublas.dy lib for Mac OS X.

例子

有关示例代码参考，请参见下面的两个示例。它们显示了使用具有两种索引样式的cuBLAS库API以C编写的应用程序（示例1）。“使用C和cuBLAS的应用程序：基于1的索引”和示例2。“使用C和cuBLAS的应用程序：基于0的索引”）。

//Example 1. Application Using C and cuBLAS: 1-based indexing
//-----------------------------------------------------------
#include <stdio.h>
#include <stdlib.h>
#include <math.h>
#include <cuda_runtime.h>
#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;
}

//Example 2. Application Using C and cuBLAS: 0-based indexing
//-----------------------------------------------------------
#include <stdio.h>
#include <stdlib.h>
#include <math.h>
#include <cuda_runtime.h>
#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;
}