1Transition from Intel MKL-DNN to oneDNN {#dev_guide_transition_to_dnnl} 2======================================================================= 3 4To simplify library naming and differentiate it from Intel MKL, starting with 5version 1.1 the library name is changed to 6**Deep Neural Network Library (DNNL)**. 7 8@note Subsequent library name change to 9oneAPI Deep Neural Network Library (oneDNN) does not impact API, environment 10variables, or build options. 11 12The library will maintain backward compatibility with respect to API, 13environment variables and build options until the next major release. 14However, there are some incompatibilities that are described in 15[Broken compatibility with Intel MKL-DNN](@ref dg_mtdt_s2) section below. 16 17## 1. Summary of Changes 18 19In short, the migration can be as simple as just replacing all 20`MKLDNN/mkldnn` substrings with `DNNL/dnnl`. 21 22### 1.1. Source code changes 23 24All headers, functions, types, and namespaces renamed by replacing `mkldnn` 25with `dnnl`. The macros with `MKLDNN` are replaced with `DNNL` counterparts. 26 27An example of code with Intel MKL-DNN v1.0: 28~~~ cpp 29#include "mkldnn.hpp" 30 31using namespace mkldnn; 32 33mkldnn_memory_desc_t md; 34if (md.format_kind == mkldnn_blocked) {} 35conv.exec(stream, {{MKLDNN_ARGS_SRC, src}, ...}); 36~~~ 37 38The updated example with DNNL v1.1: 39~~~ cpp 40#include "dnnl.hpp" 41 42using namespace dnnl; 43 44dnnl_memory_desc_t md; 45if (md.format_kind == dnnl_blocked) {} 46conv.exec(stream, {{DNNL_ARGS_SRC, src}, ...}); 47~~~ 48 49To API compatibility with Intel MKL-DNN is based on 50`include/mkldnn_dnnl_mangling.h` header file that maps all Intel MKL-DNN 51symbols to DNNL ones using C preprocessor: 52 53~~~ cpp 54// ... 55#define mkldnn_memory_desc_t dnnl_memory_desc_t 56#define mkldnn_memory_desc_init_by_tag dnnl_memory_desc_init_by_tag 57// ... 58~~~ 59 60This file is included to every former Intel MKL-DNN header files 61(for instance, see `mkldnn.h`) along with the DNNL counterpart. 62 63### 1.2. Build process 64 65The changes to the build options are similar to the ones in the source code. 66All the options and namespace with `MKLDNN` are replaced with `DNNL`: 67 68| Intel MKL-DNN | DNNL | 69| :-- | :-- | 70| MKLDNN (namespace) | DNNL (namespace) | 71| MKLDNN_ARCH_OPT_FLAGS | DNNL_ARCH_OPT_FLAGS | 72| MKLDNN_BUILD_EXAMPLES | DNNL_BUILD_EXAMPLES | 73| MKLDNN_BUILD_FOR_CI | DNNL_BUILD_FOR_CI | 74| MKLDNN_BUILD_TESTS | DNNL_BUILD_TESTS | 75| MKLDNN_CPU_RUNTIME | DNNL_CPU_RUNTIME | 76| MKLDNN_ENABLE_CONCURRENT_EXEC | DNNL_ENABLE_CONCURRENT_EXEC | 77| MKLDNN_ENABLE_JIT_PROFILING | DNNL_ENABLE_JIT_PROFILING | 78| MKLDNN_GPU_BACKEND | DNNL_GPU_BACKEND | 79| MKLDNN_GPU_RUNTIME | DNNL_GPU_RUNTIME | 80| MKLDNN_INSTALL_MODE | DNNL_INSTALL_MODE | 81| MKLDNN_LIBRARY_TYPE | DNNL_LIBRARY_TYPE | 82| MKLDNN_THREADING | DNNL_THREADING | 83| MKLDNN_USE_CLANG_SANITIZER | DNNL_USE_CLANG_SANITIZER | 84| MKLDNN_VERBOSE | DNNL_VERBOSE | 85| MKLDNN_WERROR | DNNL_WERROR | 86 87Similarly to the source code, DNNL preserves compatibility for build process 88as well. It should be possible to continue using: 89 90~~~ sh 91# Through find package 92find_package(mkldnn MKLDNN CONFIG REQUIRED) 93target_link_libraries(project_app MKLDNN::mkldnn) 94 95# Or direct sub-project inclusion 96add_subdirectory(${MKLDNN_DIR} MKLDNN) 97include_directories(${MKLDNN_DIR}/include) 98target_link_libraries(project_app mkldnn) 99~~~ 100 101Though it is preferable to switch to: 102 103~~~ sh 104# Through find package 105find_package(dnnl DNNL CONFIG REQUIRED) 106target_link_libraries(project_app DNNL::dnnl) 107 108# Or direct sub-project inclusion 109add_subdirectory(${DNNL_DIR} DNNL) 110include_directories(${DNNL_DIR}/include) 111target_link_libraries(project_app dnnl) 112~~~ 113 114In case both style options are set, the DNNL one takes precedence. 115 116### 1.3. Runtime parameters 117 118DNNL supports both old Intel MKL-DNN and new DNNL environment variable controls. 119DNNL value takes precedence over Intel MKL-DNN ones. 120 121| | Intel MKL-DNN | DNNL | 122| :-- | :-- | :-- | 123| [Verbose](@ref dev_guide_verbose) | MKLDNN_VERBOSE | DNNL_VERBOSE | 124| [Dumping jit kernels](@ref dev_guide_inspecting_jit) | MKLDNN_JIT_DUMP | DNNL_JIT_DUMP | 125 126@anchor dg_mtdt_s2 127## 2. Broken compatibility with Intel MKL-DNN 128 129Unfortunately, the full compatibility after renaming is not implemented. 130DNNL is **not** compatible with Intel MKL-DNN in the following things: 131- ABI: An application or a library built with Intel MKL-DNN cannot switch on 132 using DNNL without re-compilation. 133- Microsoft\* Visual Studio Solution files that are generated by cmake will 134 be based on DNNL name only 135 (e.g. `MKLDNN.sln` becomes `DNNL.sln`, and the former is no more generated). 136 137## 3. Information for developers 138 139The implementation of renaming (several patches and scripts that rename the 140library) can be found 141[here](https://github.com/emfomenk/intel-mkldnn-rebranding). 142 143Also it is worth mentioning that DNNL team finally switched to the mandatory 144code formatting based on `_clang-format` file in the root of the repository. 145The corresponding changes were done by 146[this](https://github.com/oneapi-src/oneDNN/commit/56ef626d6627e93da039c15e032603e1a4bc8af4) 147and neighbor commits. 148