lhuot / onemkl

oneAPI Math Kernel Library (oneMKL) Interfaces

oneAPI Math Kernel Library (oneMKL) Interfaces

Contents

• Introduction
• Support and Requirements
• Build Setup
• Building with CMake
• Project Cleanup
• Legal Information

---

Introduction

oneMKL interfaces are an open-source implementation of the oneMKL Data Parallel C++ (DPC++) interface according to the oneMKL specification. It works with multiple devices (backends) using device-specific libraries underneath.

User Application	oneMKL Layer	Third-Party Library	Hardware Backend
oneMKL interface	oneMKL selector	Intel(R) oneAPI Math Kernel Library for Intel CPU	Intel CPU
		Intel(R) oneAPI Math Kernel Library for Intel GPU	Intel GPU
		NVIDIA cuBLAS for NVIDIA GPU	NVIDIA GPU

Supported Usage Models:

There are two oneMKL selector layer implementations:

• Run-time dispatching: The application is linked with the oneMKL library and the required backend is loaded at run-time based on device vendor (all libraries should be dynamic).

Example of app.cpp with run-time dispatching:

include "onemkl/onemkl.hpp"

...
cpu_dev = cl::sycl::device(cl::sycl::cpu_selector());
gpu_dev = cl::sycl::device(cl::sycl::gpu_selector());

cl::sycl::queue cpu_queue(cpu_dev);
cl::sycl::queue gpu_queue(gpu_dev);

onemkl::blas::gemm(cpu_queue, transA, transB, m, ...);
onemkl::blas::gemm(gpu_queue, transA, transB, m, ...);

How to build an application with run-time dispatching:

$> clang++ -fsycl –I$ONEMKL/include app.cpp
$> clang++ -fsycl app.o –L$ONEMKL/lib –lonemkl

• Compile-time dispatching: The application uses a templated API where the template parameters specify the required backends and third-party libraries and the application is linked with the required oneMKL backend wrapper libraries (libraries can be static or dynamic).

Example of app.cpp with compile-time dispatching:

include "onemkl/onemkl.hpp"

...
cpu_dev = cl::sycl::device(cl::sycl::cpu_selector());
gpu_dev = cl::sycl::device(cl::sycl::gpu_selector());

cl::sycl::queue cpu_queue(cpu_dev);
cl::sycl::queue gpu_queue(gpu_dev);

onemkl::blas::gemm<intelcpu,intelmkl>(cpu_queue, transA, transB, m, ...);
onemkl::blas::gemm<nvidiagpu,cublas>(gpu_queue, transA, transB, m, ...);

How to build an application with run-time dispatching:

$> clang++ -fsycl –I$ONEMKL/include app.cpp
$> clang++ -fsycl app.o –L$ONEMKL/lib –lonemkl_blas_mklcpu –lonemkl_blas_cublas

Supported Configurations:

Supported domains: BLAS

Linux*

Backend	Library	Supported Link Type
Intel CPU	Intel(R) oneAPI Math Kernel Library	Dynamic, Static
Intel GPU	Intel(R) oneAPI Math Kernel Library	Dynamic, Static
NVIDIA GPU	NVIDIA cuBLAS	Dynamic, Static

Windows*

Backend	Library	Supported Link Type
Intel CPU	Intel(R) oneAPI Math Kernel Library	Dynamic, Static
Intel GPU	Intel(R) oneAPI Math Kernel Library	Dynamic, Static

---

Support and Requirements

Hardware Platform Support

• CPU
  • Intel Atom(R) Processors
  • Intel(R) Core(TM) Processor Family
  • Intel(R) Xeon(R) Processor Family
• Accelerators
  • Intel(R) Processor Graphics GEN9
  • NVIDIA(R) TITAN RTX(TM) (Linux* only. Not tested with other NVIDIA GPU families and products.)

---

Supported Operating Systems

Linux*

Operating System	CPU Host/Target	Integrated Graphics from Intel (Intel GPU)	NVIDIA GPU
Ubuntu	18.04.3, 19.04	18.04.3, 19.10	18.04.3
SUSE Linux Enterprise Server*	15	Not supported	Not supported
Red Hat Enterprise Linux* (RHEL*)	8	Not supported	Not supported
Linux* kernel	N/A	4.11 or higher	N/A

Windows*

Operating System	CPU Host/Target	Integrated Graphics from Intel (Intel GPU)
Microsoft Windows*	10 (64-bit version only)	10 (64-bit version only)
Microsoft Windows* Server	2016, 2019	Not supported

---

Software Requirements

What should I download?

General:

Functional Testing	Build Only	Documentation
CMake	CMake	CMake
Ninja (optional)	Ninja (optional)	Sphinx
GNU* FORTRAN Compiler
NETLIB LAPACK

Hardware and OS Specific:

Operating System	Hardware	Using CMake
Linux*	Any	GNU* GCC 5.1 or higher
	NVIDIA GPU	Intel project for LLVM* technology
		NVIDIA CUDA SDK
Windows*	Any	MSVS* 2017 or MSVS* 2019 (version 16.5 or newer)
Linux*/Windows*
	Intel CPU	Intel(R) oneAPI DPC++ Compiler or Intel project for LLVM* technology
		Intel(R) oneAPI Math Kernel Library
	Intel GPU	Intel(R) oneAPI DPC++ Compiler
		Intel GPU driver
		Intel(R) oneAPI Math Kernel Library

Product and Version Information:

Product	Supported Version	License
Python	3.6 or higher	PSF
CMake	3.13 or higher	The OSI-approved BSD 3-clause License
Ninja	1.9.0	Apache License v2.0
GNU* FORTRAN Compiler	7.4.0 or higher	GNU General Public License, version 3
Intel(R) oneAPI DPC++ Compiler	2021.1-beta05	End User License Agreement for the Intel(R) Software Development Products
Intel project for LLVM* technology binary for Intel CPU	Daily builds (experimental) tested with 20200331	Apache License v2
Intel project for LLVM* technology source for NVIDIA GPU	Daily source releases: tested with 20200421	Apache License v2
Intel(R) oneAPI Math Kernel Library	2021.1-beta05	Intel Simplified Software License
NVIDIA CUDA SDK	10.2	End User License Agreement
NETLIB LAPACK	3.7.1	BSD like license
Sphinx	2.4.4	BSD License

---

Build Setup

1. Install Intel(R) oneAPI DPC++ Compiler (select variant as per requirement).

2. Clone this project to <path to onemkl>, where <path to onemkl> is the root directory of this repository.

3. Build with CMake.

---

Building with CMake

1. Make sure you have completed Build Setup.

2. Build and install all required dependencies.

Then:

• On Linux*

# Inside <path to onemkl>
mkdir build && cd build
export CXX=<path_to_dpcpp_compiler>/bin/dpcpp;
cmake .. [-DMKL_ROOT=<mkl_install_prefix>] \               # required only if enviroment variable MKLROOT is not set
         [-DREF_BLAS_ROOT=<reference_blas_install_prefix>] # required only for testing
cmake --build .
ctest
cmake --install . --prefix <path_to_install_dir>

• On Windows*

# Inside <path to onemkl>
md build && cd build
cmake .. -G Ninja  -DCMAKE_TOOLCHAIN_FILE="..\cmake\toolchain\intel_clang-cl-toolchain.cmake"  
                  [-DMKL_ROOT=<mkl_install_prefix>] \                   # required only if enviroment variable MKLROOT is not set
                  [-DREF_BLAS_ROOT=<reference_blas_install_prefix>]     # required only for testing

ninja 
ctest
cmake --install . --prefix <path_to_install_dir>

Build Options

You can specify build options using -D<cmake_option>=<value>. The following table provides the list of options supported by CMake.

CMake Option	Supported Values	Default Value
BUILD_SHARED_LIBS	True, False	True
ENABLE_CUBLAS_BACKEND	True, False	False
ENABLE_MKLCPU_BACKEND	True, False	True
ENABLE_MKLGPU_BACKEND	True, False	True
ENABLE_MKLCPU_THREAD_TBB	True, False	True
BUILD_FUNCTIONAL_TESTS	True, False	True
BUILD_DOC	True, False	False

---

Project Cleanup

Most use-cases involve building the project without the need to cleanup the build directory. However, if you wish to cleanup the build directory, you can delete the build folder and create a new one. If you wish to cleanup the build files but retain the build configuration, following commands will help you do so.

# If you use "GNU/Unix Makefiles" for building,
make clean

# If you use "Ninja" for building
ninja -t clean

---

Legal information