
Introduction
www.nvidia.com
cuBLAS Library DU-06702-001_v9.0|2
indexing, in which case the array index of a matrix element in row “i” and column “j”
can be computed via the following macro
#define IDX2C(i,j,ld) (((j)*(ld))+(i))
1.2.New and Legacy cuBLAS API
Starting with version 4.0, the cuBLAS Library provides a new updated API, in addition
to the existing legacy API. This section discusses why a new API is provided, the
advantages of using it, and the differences with the existing legacy API.
The new cuBLAS library API can be used by including the header file “cublas_v2.h”. It
has the following features that the legacy cuBLAS API does not have:
‣
the handle to the cuBLAS library context is initialized using the function and is
explicitly passed to every subsequent library function call. This allows the user to
have more control over the library setup when using multiple host threads and
multiple GPUs. This also allows the cuBLAS APIs to be reentrant.
‣
the scalars and can be passed by reference on the host or the device, instead of
only being allowed to be passed by value on the host. This change allows library
functions to execute asynchronously using streams even when and are generated
by a previous kernel.
‣
when a library routine returns a scalar result, it can be returned by reference on
the host or the device, instead of only being allowed to be returned by value only
on the host. This change allows library routines to be called asynchronously when
the scalar result is generated and returned by reference on the device resulting in
maximum parallelism.
‣
the error status cublasStatus_t is returned by all cuBLAS library function calls.
This change facilitates debugging and simplifies software development. Note that
cublasStatus was renamed cublasStatus_t to be more consistent with other
types in the cuBLAS library.
‣
the cublasAlloc() and cublasFree() functions have been deprecated.
This change removes these unnecessary wrappers around cudaMalloc() and
cudaFree(), respectively.
‣
the function cublasSetKernelStream() was renamed cublasSetStream() to be
more consistent with the other CUDA libraries.
The legacy cuBLAS API, explained in more detail in the Appendix A, can be used by
including the header file “cublas.h”. Since the legacy API is identical to the previously
released cuBLAS library API, existing applications will work out of the box and
automatically use this legacy API without any source code changes. In general, new
applications should not use the legacy cuBLAS API, and existing existing applications
should convert to using the new API if it requires sophisticated and optimal stream
parallelism or if it calls cuBLAS routines concurrently from multiple threads. For the rest
of the document, the new cuBLAS Library API will simply be referred to as the cuBLAS
Library API.
As mentioned earlier the interfaces to the legacy and the cuBLAS library APIs are the
header file “cublas.h” and “cublas_v2.h”, respectively. In addition, applications using
the cuBLAS library need to link against the DSO cublas.so (Linux), the DLL cublas.dll