Integrating a Third-Party Library to oneAPI Math Library (oneMath)#
This step-by-step tutorial provides examples for enabling new third-party libraries in oneMath.
oneMath has a header-based implementation of the interface layer (include directory) and a source-based implementation of the backend layer for each third-party library (src directory). To enable a third-party library, you must update both parts of oneMath and integrate the new third-party library to the oneMath build and test systems.
For the new backend library and header naming please use the following template:
onemath_<domain>_<3rd-party library short name>[<wrapper for specific target>]
Where <wrapper for specific target> is required only if multiple wrappers are provided from the same 3rd-party library, e.g., wrappers with Intel oneMKL C API for CPU target onemath_blas_mklcpu.so and wrappers with Intel oneMKL DPC++ API for GPU target onemath_blas_mklgpu.so.
If there is no need for multiple wrappers only <domain> and <3rd-party library short name> are required, e.g. onemath_rng_curand.so
4. Integrate Wrappers To the Build System
1. Create Header Files#
For each new backend library, you should create the following two header files:
Header file with a declaration of entry points to the new third-party library wrappers
Compiler-time dispatching interface (see oneMath Usage Models) for new third-party libraries
Example header file include/oneapi/math/blas/detail/newlib/onemath_blas_newlib.hpp
namespace oneapi {
namespace math {
namespace newlib {
void asum(sycl::queue &queue, std::int64_t n, sycl::buffer<float, 1> &x, std::int64_t incx,
sycl::buffer<float, 1> &result);
Compile-time Dispatching Interface Example:
Example of the compile-time dispatching interface template instantiations for newlib and supported device newdevice in include/oneapi/math/blas/detail/newlib/blas_ct.hpp.
namespace oneapi {
namespace math {
namespace blas {
template <>
void asum<library::newlib, backend::newdevice>(sycl::queue &queue, std::int64_t n,
sycl::buffer<float, 1> &x, std::int64_t incx,
sycl::buffer<float, 1> &result) {
asum_precondition(queue, n, x, incx, result);
oneapi::math::newlib::asum(queue, n, x, incx, result);
asum_postcondition(queue, n, x, incx, result);
}
2. Integrate Header Files#
Below you can see structure of oneMath top-level include directory:
include/
oneapi/
math/
math.hpp -> oneMath spec APIs
types.hpp -> oneMath spec types
blas.hpp -> oneMath BLAS APIs w/ pre-check/dispatching/post-check
detail/ -> implementation specific header files
exceptions.hpp -> oneMath exception classes
backends.hpp -> list of oneMath backends
backends_table.hpp -> table of backend libraries for each domain and device
get_device_id.hpp -> function to query device information from queue for Run-time dispatching
blas/
predicates.hpp -> oneMath BLAS pre-check post-check
detail/ -> BLAS domain specific implementation details
blas_loader.hpp -> oneMath Run-time BLAS API
blas_ct_templates.hpp -> oneMath Compile-time BLAS API general templates
cublas/
blas_ct.hpp -> oneMath Compile-time BLAS API template instantiations for <cublas>
onemath_blas_cublas.hpp -> backend wrappers library API
mklcpu/
blas_ct.hpp -> oneMath Compile-time BLAS API template instantiations for <mklcpu>
onemath_blas_mklcpu.hpp -> backend wrappers library API
<other backends>/
<other domains>/
To integrate the new third-party library to a oneMath header-based part, following files from this structure should be updated:
include/oneapi/math/detail/backends.hpp: add the new backendExample: add the
newbackendbackendenum class backend { mklcpu, + newbackend,
static backendmap backend_map = { { backend::mklcpu, "mklcpu" }, + { backend::newbackend, "newbackend" },
include/oneapi/math/detail/backends_table.hpp: add new backend library for supported domain(s) and device(s)Example: enable
newlibforblasdomain andnewdevicedeviceenum class device : uint16_t { x86cpu, ... + newdevice }; static std::map<domain, std::map<device, std::vector<const char*>>> libraries = { { domain::blas, { { device::x86cpu, { #ifdef ONEMATH_ENABLE_MKLCPU_BACKEND LIB_NAME("blas_mklcpu") #endif } }, + { device::newdevice, + { + #ifdef ONEMATH_ENABLE_NEWLIB_BACKEND + LIB_NAME("blas_newlib") + #endif + } },
include/oneapi/math/detail/get_device_id.hpp: add new device detection mechanism for Run-time dispatchingExample: enable
newdeviceif the queue is targeted for the Hostinline oneapi::math::device get_device_id(sycl::queue &queue) { oneapi::math::device device_id; + if (queue.is_host()) + device_id=device::newdevice;
include/oneapi/math/blas.hpp: include the created header file for the compile-time dispatching interface (see oneMath Usage Models)Example: add
include/oneapi/math/blas/detail/newlib/blas_ct.hppcreated at the 1. Create Header Files step#include "oneapi/math/blas/detail/mklcpu/blas_ct.hpp" #include "oneapi/math/blas/detail/mklgpu/blas_ct.hpp" + #include "oneapi/math/blas/detail/newlib/blas_ct.hpp"
The new files created at the 1. Create Header Files step result in the following updated structure of the BLAS domain header files.
include/
oneapi/
math/
blas.hpp -> oneMath BLAS APIs w/ pre-check/dispatching/post-check
blas/
predicates.hpp -> oneMath BLAS pre-check post-check
detail/ -> BLAS domain specific implementation details
blas_loader.hpp -> oneMath Run-time BLAS API
blas_ct_templates.hpp -> oneMath Compile-time BLAS API general templates
cublas/
blas_ct.hpp -> oneMath Compile-time BLAS API template instantiations for <cublas>
onemath_blas_cublas.hpp -> backend wrappers library API
mklcpu/
blas_ct.hpp -> oneMath Compile-time BLAS API template instantiations for <mklcpu>
onemath_blas_mklcpu.hpp -> backend wrappers library API
+ newlib/
+ blas_ct.hpp -> oneMath Compile-time BLAS API template instantiations for <newbackend>
+ onemath_blas_newlib.hpp -> backend wrappers library API
<other backends>/
<other domains>/
3. Create Wrappers#
Wrappers convert Data Parallel C++ (DPC++) input data types to third-party library data types and call corresponding implementation from the third-party library. Wrappers for each third-party library are built to separate oneMath backend libraries. The libonemath.so dispatcher library loads the wrappers at run-time if you are using the interface for run-time dispatching, or you will link with them directly in case you are using the interface for compile-time dispatching (for more information see oneMath Usage Models).
All wrappers and dispatcher library implementations are in the src directory:
src/
include/
function_table_initializer.hpp -> general loader implementation w/ global libraries table
blas/
function_table.hpp -> loaded BLAS functions declaration
blas_loader.cpp -> BLAS wrappers for loader
backends/
cublas/ -> cuBLAS wrappers
mklcpu/ -> Intel oneMKL CPU wrappers
mklgpu/ -> Intel oneMKL GPU wrappers
<other backend libraries>/
<other domains>/
Each backend library should contain a table of all functions from the chosen domain.
Example: Create wrappers for newlib based on the header files created and integrated previously, and enable only one asum function
Create two new files:
src/blas/backends/newlib/newlib_wrappers.cpp- DPC++ wrappers for all functions frominclude/oneapi/math/blas/detail/newlib/onemath_blas_newlib.hppsrc/blas/backends/newlib/newlib_wrappers_table_dyn.cpp- structure of symbols for run-time dispatcher (in the same location as wrappers), suffix_dynindicates that this file is required for dynamic library only.
You can then modify src/blas/backends/newlib/newlib_wrappers.cpp to enable the C function newlib_sasum from the third-party library libnewlib.so.
To enable this function:
Include the header file
newlib.hwith thenewlib_sasumfunction declarationConvert all DPC++ parameters to proper C types: use the
get_accessmethod for input and output DPC++ buffers to get row pointersSubmit the DPC++ kernel with a C function call to
newlibassingle_task
The following code snippet is updated for src/blas/backends/newlib/newlib_wrappers.cpp:
#if __has_include(<sycl/sycl.hpp>)
#include <sycl/sycl.hpp>
#else
#include <CL/sycl.hpp>
#endif
#include "oneapi/math/types.hpp"
#include "oneapi/math/blas/detail/newlib/onemath_blas_newlib.hpp"
+
+ #include "newlib.h"
namespace oneapi {
namespace math {
namespace newlib {
void asum(sycl::queue &queue, std::int64_t n, sycl::buffer<float, 1> &x, std::int64_t incx,
sycl::buffer<float, 1> &result) {
- throw std::runtime_error("Not implemented for newlib");
+ queue.submit([&](sycl::handler &cgh) {
+ auto accessor_x = x.get_access<sycl::access::mode::read>(cgh);
+ auto accessor_result = result.get_access<sycl::access::mode::write>(cgh);
+ cgh.single_task<class newlib_sasum>([=]() {
+ accessor_result[0] = ::newlib_sasum((const int)n, accessor_x.get_pointer(), (const int)incx);
+ });
+ });
}
void asum(sycl::queue &queue, std::int64_t n, sycl::buffer<double, 1> &x, std::int64_t incx,
sycl::buffer<double, 1> &result) {
throw std::runtime_error("Not implemented for newlib");
}
Updated structure of the src folder with the newlib wrappers:
src/
blas/
loader.hpp -> general loader implementation w/ global libraries table
function_table.hpp -> loaded BLAS functions declaration
blas_loader.cpp -> BLAS wrappers for loader
backends/
cublas/ -> cuBLAS wrappers
mklcpu/ -> Intel oneMKL CPU wrappers
mklgpu/ -> Intel oneMKL GPU wrappers
+ newlib/
+ newlib.h
+ newlib_wrappers.cpp
+ newlib_wrappers_table_dyn.cpp
<other backend libraries>/
<other domains>/
4. Integrate Wrappers to the Build System#
Here is the list of files that should be created/updated to integrate the new wrappers for the third-party library to the oneMath build system:
Add the new option
ENABLE_XXX_BACKENDfor the new third-party library to the top of theCMakeList.txtfile.Example: changes for
newlibin the top of theCMakeList.txtfileoption(ENABLE_MKLCPU_BACKEND "" ON) option(ENABLE_MKLGPU_BACKEND "" ON) + option(ENABLE_NEWLIB_BACKEND "" ON)
Add the new directory (
src/<domain>/backends/<new_directory>) with the wrappers for the new third-party library under theENABLE_XXX_BACKENDcondition to thesrc/<domain>/backends/CMakeList.txtfile.Example: changes for
newlibinsrc/blas/backends/CMakeLists.txtif(ENABLE_MKLCPU_BACKEND) add_subdirectory(mklcpu) endif() + + if(ENABLE_NEWLIB_BACKEND) + add_subdirectory(newlib) + endif()
Create the
cmake/FindXXX.cmakecmake config file to find the new third-party library and its dependencies.Example: new config file
cmake/FindNEWLIB.cmakefornewlibinclude_guard() # Find library by name in NEWLIB_ROOT cmake variable or environment variable NEWLIBROOT find_library(NEWLIB_LIBRARY NAMES newlib HINTS ${NEWLIB_ROOT} $ENV{NEWLIBROOT} PATH_SUFFIXES "lib") # Make sure that the library was found include(FindPackageHandleStandardArgs) find_package_handle_standard_args(NEWLIB REQUIRED_VARS NEWLIB_LIBRARY) # Set cmake target for the library add_library(ONEMATH::NEWLIB::NEWLIB UNKNOWN IMPORTED) set_target_properties(ONEMATH::NEWLIB::NEWLIB PROPERTIES IMPORTED_LOCATION ${NEWLIB_LIBRARY})
Create the
src/<domain>/backends/<new_directory>/CMakeList.txtcmake config file to specify how to build the backend layer for the new third-party library.Check existing backends as a reference to create
cmake/FindXXX.cmakefile.You should update the config file with information about the new
cmake/FindXXX.cmakefile and instructions about how to link with the third-party library.Example: update the
src/blas/backends/newlib/CMakeLists.txtfile# Add third-party library - # find_package(XXX REQUIRED) + find_package(NEWLIB REQUIRED)
target_link_libraries(${LIB_OBJ} PUBLIC ONEMATH::SYCL::SYCL - # Add third-party library to link with here + PUBLIC ONEMATH::NEWLIB::NEWLIB )
Now you can build the backend library for newlib to make sure the third-party library integration was completed successfully (for more information, see Build with cmake)
cd build/
cmake .. -DNEWLIB_ROOT=<path/to/newlib> \
-DENABLE_MKLCPU_BACKEND=OFF \
-DENABLE_MKLGPU_BACKEND=OFF \
-DENABLE_NEWLIB_BACKEND=ON \ # Enable new third-party library backend
-DBUILD_FUNCTIONAL_TESTS=OFF # At this step we want build only
cmake --build . -j4
5. Update the Test System#
Update the following files to enable the new third-party library for unit tests:
src/config.hpp.in: add a cmake option for the new third-party library so this macro can be propagated to unit testsExample: add
ENABLE_NEWLIB_BACKEND#cmakedefine ONEMATH_ENABLE_MKLCPU_BACKEND + #cmakedefine ONEMATH_ENABLE_NEWLIB_BACKEND
tests/unit_tests/CMakeLists.txt: add instructions about how to link tests with the new backend libraryExample: add the
newlibbackend libraryif(ENABLE_MKLCPU_BACKEND) add_dependencies(test_main_ct onemath_blas_mklcpu) if(BUILD_SHARED_LIBS) list(APPEND ONEMATH_LIBRARIES onemath_blas_mklcpu) else() list(APPEND ONEMATH_LIBRARIES -foffload-static-lib=${CMAKE_LIBRARY_OUTPUT_DIRECTORY}/libonemath_blas_mklcpu.a) find_package(MKL REQUIRED) list(APPEND ONEMATH_LIBRARIES ${MKL_LINK_C}) endif() endif() + + if(ENABLE_NEWLIB_BACKEND) + add_dependencies(test_main_ct onemath_blas_newlib) + if(BUILD_SHARED_LIBS) + list(APPEND ONEMATH_LIBRARIES onemath_blas_newlib) + else() + list(APPEND ONEMATH_LIBRARIES -foffload-static-lib=${CMAKE_LIBRARY_OUTPUT_DIRECTORY}/libonemath_blas_newlib.a) + find_package(NEWLIB REQUIRED) + list(APPEND ONEMATH_LIBRARIES ONEMATH::NEWLIB::NEWLIB) + endif() + endif()
tests/unit_tests/include/test_helper.hpp: add the helper function for the compile-time dispatching interface with the new backend, and specify the device for which it should be calledExample: add the helper function for the
newlibcompile-time dispatching interface withnewdeviceif it is the Host#ifdef ONEMATH_ENABLE_MKLGPU_BACKEND #define TEST_RUN_INTELGPU(q, func, args) \ func<oneapi::math::backend::mklgpu> args #else #define TEST_RUN_INTELGPU(q, func, args) #endif + + #ifdef ONEMATH_ENABLE_NEWLIB_BACKEND + #define TEST_RUN_NEWDEVICE(q, func, args) \ + func<oneapi::math::backend::newbackend> args + #else + #define TEST_RUN_NEWDEVICE(q, func, args) + #endif
#define TEST_RUN_CT(q, func, args) \ do { \ + if (q.is_host()) \ + TEST_RUN_NEWDEVICE(q, func, args); \
tests/unit_tests/main_test.cpp: add the targeted device to the vector of devices to testExample: add the targeted device CPU for
newlib} } + + #ifdef ONEMATH_ENABLE_NEWLIB_BACKEND + devices.push_back(sycl::device(sycl::host_selector())); + #endif
Now you can build and run functional testing for enabled third-party libraries (for more information see Build with cmake).
cd build/
cmake .. -DNEWLIB_ROOT=<path/to/newlib> \
-DENABLE_MKLCPU_BACKEND=OFF \
-DENABLE_MKLGPU_BACKEND=OFF \
-DENABLE_NEWLIB_BACKEND=ON \
-DBUILD_FUNCTIONAL_TESTS=ON
cmake --build . -j4
ctest