Skip to content

Latest commit

 

History

History
321 lines (256 loc) · 11.5 KB

README.md

File metadata and controls

321 lines (256 loc) · 11.5 KB
Raw

oneAPI Math Kernel Library (oneMKL) Interfaces

Contents

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