A newer version of this document is available. Customers should click here to go to the newest version.
Visible to Intel only — GUID: GUID-8210C31C-5232-4339-9666-97C9BFC6234C
Visible to Intel only — GUID: GUID-8210C31C-5232-4339-9666-97C9BFC6234C
Scalar Arguments
Basic Use
The USM version of oneMKL BLAS routines for DPC++ will accept either a scalar (for example float) or pointer (float*) for parameters that represent a single fixed value (not a vector or matrix). These parameters are often named alpha or beta in BLAS.
For example, users can call gemv with pointers:
float *alpha_ptr = sycl::malloc_shared<float>(1, queue); float *beta_ptr = sycl::malloc_shared<float>(1, queue); // fill alpha_ptr and beta_ptr with desired values oneapi::mkl::blas::column_major::gemv(queue, trans, m, n, alpha_ptr, lda, x, incx, beta_ptr, y, incy).wait();
or with literal values:
oneapi::mkl::blas::column_major::gemv(queue, trans, m, n, 2, lda, x, incx, 2.7, y, incy).wait();
Users can even mix scalar and pointer parameters in a single call:
float *alpha_ptr = sycl::malloc_shared<float>(1, queue); oneapi::mkl::blas::column_major::gemv(queue, trans, m, n, alpha_ptr, lda, x, incx, 2.7, y, incy).wait();
Pointers provided for scalar parameters may be SYCL-managed pointers to either device or host memory (for example pointers created with sycl::malloc_device, sycl::malloc_shared, or sycl::malloc_host), or they may be raw pointers created with malloc or new.
For most users, this is all they need to know. A few details about how this is implemented are provided below.
Wrapper type for scalar parameters
The USM version of oneMKL BLAS routines use a templated value_or_pointer<T> wrapper to enable either pointers or values to be passed to routines that take a scalar parameter. This type is in the oneapi::mkl:: namespace and defined in the header file oneapi/mkl/types.hpp.
In general, users should not explicitly use this type in their code. There is no need to construct an object of type value_or_pointer in order to use the oneMKL functions that include it in their function signatures. Instead, values and pointers in user code will be implicitly converted to this type when a user calls a oneMKL function.
The value_or_pointer<T> wrapper has two constructors, one that converts a value of type T (or anything convertible to T) to value_or_pointer<T>, and another that converts a pointer to T to value_or_pointer<T>. Internally, the oneMKL functions can behave slightly differently depending on whether the underlying data is a value or a pointer, and if it points to host-side memory or device-side memory, but these uses should be transparent to users.
Dependencies and pointer dereferencing
For scalar parameters passed to oneMKL BLAS routines as pointers, the timing of pointer dereferencing depends on whether it is a USM-managed pointer or a raw pointer.
For a USM-managed pointer, it is dereferenced at kernel launch after the dependencies passed to the function have been resolved, so the value may be assigned asynchronously in another event passed as a dependency to the routine.
A raw pointer (such as those allocated with malloc or new) is dereferenced at the function call, so it must be valid when the function is called. In this case the data must be valid when the function is called and it may not be assigned asynchronously.