Scalar Arguments in BLAS

The USM version of oneMath 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.

Basic Use

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::math::blas::column_major::gemv(queue, trans, m, n, alpha_ptr, lda, x, incx, beta_ptr,
                                      y, incy).wait();

or with literal values:

oneapi::math::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::math::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

The USM version of oneMath 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.

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 oneMath 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 oneMath 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 oneMath 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

For scalar parameters passed to oneMath 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.

Parent topic: Dense Linear Algebra