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