1 /*******************************************************************************
2 * Copyright 2016-2018 Intel Corporation
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 *******************************************************************************/
20 #ifndef DOXYGEN_SHOULD_SKIP_THIS
22 /* All symbols shall be internal unless marked as MKLDNN_API */
23 #if defined _WIN32 || defined __CYGWIN__
24 # define MKLDNN_HELPER_DLL_IMPORT __declspec(dllimport)
25 # define MKLDNN_HELPER_DLL_EXPORT __declspec(dllexport)
28 # define MKLDNN_HELPER_DLL_IMPORT __attribute__ ((visibility ("default")))
29 # define MKLDNN_HELPER_DLL_EXPORT __attribute__ ((visibility ("default")))
31 # define MKLDNN_HELPER_DLL_IMPORT
32 # define MKLDNN_HELPER_DLL_EXPORT
37 # ifdef MKLDNN_DLL_EXPORTS
38 # define MKLDNN_API MKLDNN_HELPER_DLL_EXPORT
40 # define MKLDNN_API MKLDNN_HELPER_DLL_IMPORT
46 #if defined (__GNUC__)
47 # define MKLDNN_DEPRECATED __attribute__((deprecated))
48 #elif defined(_MSC_VER)
49 # define MKLDNN_DEPRECATED __declspec(deprecated)
51 # define MKLDNN_DEPRECATED
54 #include "mkldnn_types.h"
55 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
61 /** @addtogroup c_api C API
64 /** @addtogroup c_api_primitive Primitive operations
67 /** @addtogroup c_api_primitive_common Common primitive operations
70 /** Creates a primitive descriptor @p iterator for given @p op_desc, @p engine,
71 * and optionally a hint primitive descriptor from forward propagation
72 * (required for backward propagation). Pass @c NULL for forward propagation.
74 mkldnn_status_t MKLDNN_API mkldnn_primitive_desc_iterator_create(
75 mkldnn_primitive_desc_iterator_t *iterator,
76 const_mkldnn_op_desc_t op_desc, mkldnn_engine_t engine,
77 const_mkldnn_primitive_desc_t hint_forward_primitive_desc);
79 /** Creates a primitive descriptor @p iterator for given @p op_desc, @p attr,
80 * @p engine, and optionally a hint primitive descriptor from forward
81 * propagation (required for backward propagation). Pass @c NULL for forward
84 mkldnn_status_t MKLDNN_API mkldnn_primitive_desc_iterator_create_v2(
85 mkldnn_primitive_desc_iterator_t *iterator,
86 const_mkldnn_op_desc_t op_desc, const_mkldnn_primitive_attr_t attr,
87 mkldnn_engine_t engine,
88 const_mkldnn_primitive_desc_t hint_forward_primitive_desc);
90 /** Iterates over primitive descriptors. Returns #mkldnn_iterator_ends if no
91 * more primitive descriptors are available */
92 mkldnn_status_t MKLDNN_API mkldnn_primitive_desc_iterator_next(
93 mkldnn_primitive_desc_iterator_t iterator);
95 /** Fetches current primitive descriptor.
98 * fetched primitive descriptor should be deleted by user using
99 * mkldnn_primitive_desc_destroy() once becomes unneeded */
100 mkldnn_primitive_desc_t MKLDNN_API mkldnn_primitive_desc_iterator_fetch(
101 const_mkldnn_primitive_desc_iterator_t iterator);
103 /** Deletes a primitive descriptor @p iterator */
104 mkldnn_status_t MKLDNN_API mkldnn_primitive_desc_iterator_destroy(
105 mkldnn_primitive_desc_iterator_t iterator);
107 /** Creates a @p primitive_desc using @p op_desc, @p engine, and optionally a
108 * hint primitive descriptor from forward propagation. The call is equivalent
109 * to create a primitive descriptor iterator, instantly fetch a primitive_desc
110 * and destroy the iterator. */
111 mkldnn_status_t MKLDNN_API mkldnn_primitive_desc_create(
112 mkldnn_primitive_desc_t *primitive_desc,
113 const_mkldnn_op_desc_t op_desc, mkldnn_engine_t engine,
114 const_mkldnn_primitive_desc_t hint_forward_primitive_desc);
116 /** Creates a @p primitive_desc using @p op_desc, @p attr, @p engine, and
117 * optionally a hint primitive descriptor from forward propagation. The call is
118 * equivalent to create a primitive descriptor iterator, instantly fetch a @p
119 * primitive_desc and destroy the iterator. */
120 mkldnn_status_t MKLDNN_API mkldnn_primitive_desc_create_v2(
121 mkldnn_primitive_desc_t *primitive_desc,
122 const_mkldnn_op_desc_t op_desc, const_mkldnn_primitive_attr_t attr,
123 mkldnn_engine_t engine,
124 const_mkldnn_primitive_desc_t hint_forward_primitive_desc);
126 /** Makes a copy of a @p primitive_desc. */
127 mkldnn_status_t MKLDNN_API mkldnn_primitive_desc_clone(
128 mkldnn_primitive_desc_t *primitive_desc,
129 const_mkldnn_primitive_desc_t existing_primitive_desc);
131 /** Returns a constant reference to the attribute of a @p primitive_desc.
134 * User should not destroy obtained @p attr
137 * The lifetime of an @p attr is same as @p primitive_desc, so it is
138 * illegal to use the @p attr once @p primitive_desc is destroyed */
139 mkldnn_status_t MKLDNN_API mkldnn_primitive_desc_get_attr(
140 const_mkldnn_primitive_desc_t primitive_desc,
141 const_mkldnn_primitive_attr_t *attr);
143 /** Deletes a @p primitive_desc. */
144 mkldnn_status_t MKLDNN_API mkldnn_primitive_desc_destroy(
145 mkldnn_primitive_desc_t primitive_desc);
147 /** Queries primitive descriptor
149 * @sa mkldnn_query_t */
150 mkldnn_status_t MKLDNN_API mkldnn_primitive_desc_query(
151 const_mkldnn_primitive_desc_t primitive_desc, mkldnn_query_t what,
152 int index, void *result);
154 /** Queries primitive descriptor for memory descriptor
156 * @returns NULL in case of any error */
157 const mkldnn_memory_desc_t MKLDNN_API *mkldnn_primitive_desc_query_memory_d(
158 const_mkldnn_primitive_desc_t primitive_desc);
160 /** Queries primitive descriptor for primitive descriptor
162 * @returns NULL in case of any error */
163 const_mkldnn_primitive_desc_t MKLDNN_API mkldnn_primitive_desc_query_pd(
164 const_mkldnn_primitive_desc_t primitive_desc, mkldnn_query_t what,
167 /** Queries primitive descriptor for signed 32bit int
169 * @returns 0 in case of any error */
170 int MKLDNN_API mkldnn_primitive_desc_query_s32(
171 const_mkldnn_primitive_desc_t primitive_desc, mkldnn_query_t what,
174 /** Creates a @p primitive using a @p primitive_desc descriptor and arrays of
175 * @p inputs and @p outputs. */
176 mkldnn_status_t MKLDNN_API mkldnn_primitive_create(
177 mkldnn_primitive_t *primitive,
178 const_mkldnn_primitive_desc_t primitive_desc,
179 const mkldnn_primitive_at_t *inputs,
180 const_mkldnn_primitive_t *outputs);
182 /** Retrieves a reference to the @p primitive_desc descriptor of given @p
186 * Returned object must not be destroyed by user. 'const' qualifier of the
187 * returned object prevents such attempts. */
188 mkldnn_status_t MKLDNN_API mkldnn_primitive_get_primitive_desc(
189 const_mkldnn_primitive_t primitive,
190 const_mkldnn_primitive_desc_t *primitive_desc);
192 /** For a @p primitive, returns @p input at the @p index position. */
193 mkldnn_status_t MKLDNN_API mkldnn_primitive_get_input_at(
194 const_mkldnn_primitive_t primitive, size_t index,
195 mkldnn_primitive_at_t *input);
197 /** For a @p primitive, returns @p output at the @p index position. */
198 mkldnn_status_t MKLDNN_API mkldnn_primitive_get_output(
199 const_mkldnn_primitive_t primitive, size_t index,
200 const_mkldnn_primitive_t *output);
202 /** Deletes a @p primitive. */
203 mkldnn_status_t MKLDNN_API mkldnn_primitive_destroy(
204 mkldnn_primitive_t primitive);
206 /** Creates an #mkldnn_primitive_at_t structure from a @p primitive and @p
207 * output_index. This function only fills in the data structure
208 * and does not check whether parameters are correct. The actual error checking
209 * is done when the resulting #mkldnn_primitive_at structure is passed to a
210 * primitive creation function. */
211 mkldnn_primitive_at_t MKLDNN_API mkldnn_primitive_at(
212 const_mkldnn_primitive_t primitive, size_t output_index);
216 /** @addtogroup c_api_attributes Attributes
217 * An extension for controlling primitive behavior.
220 /** Creates an empty (default) @p attr attribute. All the parameters set to
223 * An empty attribute is used in primitive descriptor creating whenever it is
224 * not passed explicitly, e.g. in mkldnn_primitive_desc_create.
226 mkldnn_status_t MKLDNN_API mkldnn_primitive_attr_create(
227 mkldnn_primitive_attr_t *attr);
229 /** Makes a copy of an @p existing_attr. */
230 mkldnn_status_t MKLDNN_API mkldnn_primitive_attr_clone(
231 mkldnn_primitive_attr_t *attr,
232 const_mkldnn_primitive_attr_t existing_attr);
234 /** Deletes an @p attr. */
235 mkldnn_status_t MKLDNN_API mkldnn_primitive_attr_destroy(
236 mkldnn_primitive_attr_t attr);
238 /** Returns integer output rounding mode @p round_mode for a given @p attr,
239 * previously set by mkldnn_primitive_attr_set_int_output_round_mode. */
240 mkldnn_status_t MKLDNN_API mkldnn_primitive_attr_get_int_output_round_mode(
241 const_mkldnn_primitive_attr_t attr, mkldnn_round_mode_t *round_mode);
243 /** Sets output rounding mode @p round_mode for integer operations for a given
246 * The default value is #mkldnn_round_nearest.
248 mkldnn_status_t MKLDNN_API mkldnn_primitive_attr_set_int_output_round_mode(
249 mkldnn_primitive_attr_t attr, mkldnn_round_mode_t round_mode);
251 /** Returns @p count, correspondence scale @p mask, and pointer to a constant
252 * floating point array of output @p scales for given @p attr, previously set
253 * by mkldnn_primitive_attr_set_output_scales.
256 * @p scales array points to the internal @p attr field, so user should
257 * not modify/destroy @p scales.
260 * The lifetime of @p scales is same as @p attr it belongs to, so it is
261 * illegal to use the @p scales after @p attr is destroyed
263 mkldnn_status_t MKLDNN_API mkldnn_primitive_attr_get_output_scales(
264 const_mkldnn_primitive_attr_t attr, int *count, int *mask,
265 const float **scales);
267 /** Sets output @p scales for primitive operations. The number of elements @p
268 * count and correspondence scale @p mask are stored for future use.
270 * The @p mask argument defines correspondence between output tensor dimensions
271 * and the @p scales array. Set i-th bit of @p mask to 1 to use dedicated
272 * scaling factor for each slice of the output tensor over i-th dimension. Set
273 * @p mask to 0 to use common scaling factor for the whole output tensor.
276 * The dimension order is always native and does not depend on the actual
277 * layout used. Examples:
278 * - 2D dimensional data the order of dimensions is always: (n, c)
279 * - 4D dimensional data the order is always: (n, c, h, w)
280 * - 5D dimensional weights the order is always: (g, oc, ic, kh, kw)
284 * int mb = 32, oc = 32, oh = 14, ow = 14; // convolution output params
285 * float scales[oc] = { ... }; // unique output scales per output channel
286 * int oc_dim = 1; // mb_dim = 0, channel_dim = 1, height_dim = 2, ...
288 * mkldnn_convolution_desc_t cd; // create & configure convolution op_desc
290 * mkldnn_primitive_attr_t attr;
291 * mkldnn_primitive_attr_create(&attr); // create default attributes
292 * mkldnn_primitive_attr_set_output_scales(attr, oc, 1 << oc_dim, scales);
294 * mkldnn_primitive_desc_t cpd;
295 * mkldnn_primitive_desc_create_v2(&cpd, &cd, attr, NULL);
299 * There is no way to check that @p count corresponds to @p mask until an
300 * actual primitive descriptor is created, so it is user's responsibility
301 * to set proper values. The following formula must be hold:
303 * \f[count = \prod\limits_{d \in mask} output.dims[d]\f]
305 mkldnn_status_t MKLDNN_API mkldnn_primitive_attr_set_output_scales(
306 mkldnn_primitive_attr_t attr, int count, int mask,
307 const float *scales);
309 /** Returns @p post_ops for given attr.
312 * @p post_ops points to the internal @p attr field, so user should not
313 * modify/destroy @p post_ops. Also the lifetime of @p post_ops is the
314 * same as @p attr it belongs to, so it is illegal to use @p post_ops once
315 * @p attr is destroyed.
317 mkldnn_status_t MKLDNN_API mkldnn_primitive_attr_get_post_ops(
318 const_mkldnn_primitive_attr_t attr, const_mkldnn_post_ops_t *post_ops);
320 /** Sets configured @p post_ops to an attribute @p attr for future use (when
321 * primitive descriptor is being created.
324 * At this point of time there is no way to check whether primitive
325 * descriptor does or does not support given sequence of post operations.
326 * That means that user should handle an error that might happen at
327 * mkldnn_primitive_desc_create call.
329 mkldnn_status_t MKLDNN_API mkldnn_primitive_attr_set_post_ops(
330 mkldnn_primitive_attr_t attr, const_mkldnn_post_ops_t post_ops);
332 /** @addtogroup c_api_attributes_post_ops Sequence of post operations
333 * An extension for performing extra operations after base operation.
336 /** Creates an empty sequence of post operations @p post_ops. */
337 mkldnn_status_t MKLDNN_API mkldnn_post_ops_create(mkldnn_post_ops_t *post_ops);
339 /** Deletes a @p post_ops sequence. */
340 mkldnn_status_t MKLDNN_API mkldnn_post_ops_destroy(mkldnn_post_ops_t post_ops);
342 /** Returns the @p length of post operations for given @p post_ops. */
343 int MKLDNN_API mkldnn_post_ops_len(const_mkldnn_post_ops_t post_ops);
345 /** Returns the type of post operation with index @p index in given
346 * @p post_ops. In case of error returns #mkldnn_undefined_primitive. */
347 mkldnn_primitive_kind_t MKLDNN_API mkldnn_post_ops_get_kind(
348 const_mkldnn_post_ops_t post_ops, int index);
350 /** Appends accumulation (sum) post operation to the @p post_ops. Prior to
351 * accumulating the result the previous value would be multiplied by @p scale.
353 * The kind of this post operation is #mkldnn_sum.
355 * This feature might improve performance for the cases like residual learning
356 * blocks, where the result of convolution is accumulated to the previously
357 * computed activations. Scale parameter @p scale might be extremely for the
358 * integer-based computations, when the result and previous activations have
359 * different logical scaling factors.
361 * In the simplest case when the accumulation is the only post operation, the
362 * computations would be:
363 * dst[] <- scale * dst[] + op(...) // instead of dst[] <- op(...)
366 * This post op (as well as all the others) disregards the original layout
367 * of dst, i.e. the layout of the original dst is expected to be the same
368 * as the layout of stored dst.
370 mkldnn_status_t MKLDNN_API mkldnn_post_ops_append_sum(
371 mkldnn_post_ops_t post_ops, float scale);
373 /** Gets the parameters of the accumulation (sum) post operation with index
374 * @p index in the sequence of @p post_ops.
377 * If index @p index would not correspond to the accumulation post
378 * operation, the function return #mkldnn_invalid_arguments.
380 mkldnn_status_t MKLDNN_API mkldnn_post_ops_get_params_sum(
381 const_mkldnn_post_ops_t post_ops, int index, float *scale);
383 /** Appends eltwise post operation to the @p post_ops with given parameters
384 * @p kind, @p alpha and @p beta (@sa mkldnn_eltwise_forward_desc_init and
385 * mkldnn_eltwise_desc_t).
387 * The kind of this post operation is #mkldnn_eltwise.
389 * In the simplest case when the eltwise is the only post operation, the
390 * computations would be:
391 * dst[] <- scale * eltwise_op ( op(...) ) // instead of dst[] <- op(...)
392 * where eltwise_op is configured with given parameters.
394 mkldnn_status_t MKLDNN_API mkldnn_post_ops_append_eltwise(
395 mkldnn_post_ops_t post_ops, float scale, mkldnn_alg_kind_t alg,
396 float alpha, float beta);
398 /** Gets the eltwise parameters of the post operation with index @p index in
399 * the sequence of @p post_ops.
401 mkldnn_status_t MKLDNN_API mkldnn_post_ops_get_params_eltwise(
402 const_mkldnn_post_ops_t post_ops, int index, float *scale,
403 mkldnn_alg_kind_t *alg, float *alpha, float *beta);
407 /** Appends DW convolution post operation to the @p post_ops with given parameters
408 * @p weights and @p bias.
410 * The kind of this post operation is #mkldnn_convolution.
412 mkldnn_status_t MKLDNN_API mkldnn_post_ops_append_dw_conv(
413 mkldnn_post_ops_t post_ops, int in_h, int in_w, int ker_h, int ker_w, int str_h, int str_w,
414 const float* weights_data, const float* biases_data);
416 /** Gets the DW convolution parameters of the post operation with index @p index in
417 * the sequence of @p post_ops.
419 mkldnn_status_t MKLDNN_API mkldnn_post_ops_get_params_dw_conv(
420 const_mkldnn_post_ops_t post_ops, int index, int* in_h, int* in_w,
421 int* ker_h, int* ker_w, int* str_h, int* str_w, const float** weights_data,
422 const float** biases_data);
428 /** @addtogroup c_api_memory Memory
429 * A primitive to describe data.
432 /** Initializes a @p memory_desc memory descriptor using @p ndims, @p dims, @p
433 * data_type, and data @p format. @p format can be #mkldnn_any, which means
434 * that specific data layouts are not permitted. */
435 mkldnn_status_t MKLDNN_API mkldnn_memory_desc_init(
436 mkldnn_memory_desc_t *memory_desc, int ndims, const mkldnn_dims_t dims,
437 mkldnn_data_type_t data_type, mkldnn_memory_format_t format);
439 /** Creates a @p memory_primitive_desc memory primitive descriptor using @p
440 * memory_desc and @p engine. @p memory_desc cannot be uncertain, that is,
441 * initialized with #mkldnn_any. */
442 mkldnn_status_t MKLDNN_API mkldnn_memory_primitive_desc_create(
443 mkldnn_primitive_desc_t *memory_primitive_desc,
444 const mkldnn_memory_desc_t *memory_desc, mkldnn_engine_t engine);
446 /** Creates a @p view_primitive_desc for a given @p memory_primitive_desc, with
447 * @p dims sizes and @p offset offsets. May fail if layout used does not allow
448 * obtain desired view. In this case consider using extract primitive */
449 mkldnn_status_t MKLDNN_API mkldnn_view_primitive_desc_create(
450 mkldnn_primitive_desc_t *view_primitive_desc,
451 const_mkldnn_primitive_desc_t memory_primitive_desc,
452 const mkldnn_dims_t dims, const mkldnn_dims_t offsets);
454 /** Compares two descriptors of memory primitives.
455 * @return 1 if the descriptors are the same.
456 * @return 0 if the descriptors are different.
458 * Use this function to identify whether a reorder is required for the memory
459 * primitives. @p lhs and @p rhs must be either memory or view primitive
461 int MKLDNN_API mkldnn_memory_primitive_desc_equal(
462 const_mkldnn_primitive_desc_t lhs,
463 const_mkldnn_primitive_desc_t rhs);
465 /** Returns the size (in bytes) that is required for given @p
466 * memory_primitive_desc */
468 size_t MKLDNN_API mkldnn_memory_primitive_desc_get_size(
469 const_mkldnn_primitive_desc_t memory_primitive_desc);
471 /** For a @p memory primitive, returns the data @p handle. For the CPU engine,
472 * the data handle is a pointer to the actual data. */
474 mkldnn_status_t MKLDNN_API mkldnn_memory_get_data_handle(
475 const_mkldnn_primitive_t memory, void **handle);
477 /** For a @p memory primitive, sets the data @p handle. */
478 mkldnn_status_t MKLDNN_API mkldnn_memory_set_data_handle(
479 mkldnn_primitive_t memory, void *handle);
483 /** @addtogroup c_api_reorder Reorder
484 * A primitive to copy data between memory formats.
487 /** Initializes a @p reorder_primitive_desc using descriptors of @p input and
488 * @p output memory primitives. */
489 mkldnn_status_t MKLDNN_API mkldnn_reorder_primitive_desc_create(
490 mkldnn_primitive_desc_t *reorder_primitive_desc,
491 const_mkldnn_primitive_desc_t input,
492 const_mkldnn_primitive_desc_t output);
494 /** Initializes a @p reorder_primitive_desc using an @p attr attribute and
495 * descriptors of @p input and @p output memory primitives. */
496 mkldnn_status_t MKLDNN_API mkldnn_reorder_primitive_desc_create_v2(
497 mkldnn_primitive_desc_t *reorder_primitive_desc,
498 const_mkldnn_primitive_desc_t input,
499 const_mkldnn_primitive_desc_t output,
500 const_mkldnn_primitive_attr_t attr);
504 /** @addtogroup c_api_concat Concat
505 * A primitive to concatenate data by arbitrary dimension
508 /** Creates out-of-place @p concat_primitive_desc for concatenation of @p n
509 * inputs by @p concat_dimension with resulting @p output_desc memory
510 * descriptor. @p output_desc can be NULL or be specified with #mkldnn_any
511 * format -- in this case appropriate memory format would be chosen
513 mkldnn_status_t MKLDNN_API mkldnn_concat_primitive_desc_create(
514 mkldnn_primitive_desc_t *concat_primitive_desc,
515 const mkldnn_memory_desc_t *output_desc, int n, int concat_dimension,
516 const_mkldnn_primitive_desc_t *input_pds);
519 /** Creates in-place @p concat_primitive_desc for given @p n @p inputs memory
520 * primitive descriptors along @p concat_dimension. All inputs must have the
521 * same memory format. Output memory format would be the same. Likewise
522 * view_primitive_desc_create the call may fail, if memory format of inputs do
523 * not allow inplace concatenation for given sizes.
525 * @note this primitive is more like a synchronization stub for concatenation,
526 * since concat_inplace does no operation during execution.
528 * @note since not operation happens user must ensure that input */
529 mkldnn_status_t MKLDNN_API mkldnn_concat_inplace_by_input_primitive_desc_create(
530 mkldnn_primitive_desc_t *concat_primitive_desc,
531 int n, int concat_dimension, const_mkldnn_primitive_desc_t *inputs);
533 /** Creates in-place @p concat_primitive_desc for given @p output memory
534 * descriptor and @n inputs with @p sizes sizes along @p concat_dimension. As
535 * opposed to out-of-place concatenation @p output must be fully defined here.
536 * Likewise view_primitive_desc_create the call may fail, because given memory
537 * format does not allow inplace concatenation for given sizes.
539 * @note this primitive is more like a synchronization stub for concatenation,
540 * since concat_inplace does no operation during execution. */
541 mkldnn_status_t MKLDNN_API mkldnn_concat_inplace_by_output_primitive_desc_create(
542 mkldnn_primitive_desc_t *concat_primitive_desc,
543 const mkldnn_primitive_desc_t output, int n, int concat_dimension,
549 /** @addtogroup c_api_sum Sum
550 * A primitive to sum data
553 /** Creates out-of-place @p sum_primitive_desc for sum of @p n
554 * inputs multiplied by scale with resulting @p output_desc memory
555 * descriptor. @p output_desc can be NULL or be specified with #mkldnn_any
556 * format -- in this case appropriate memory format would be chosen
558 mkldnn_status_t MKLDNN_API mkldnn_sum_primitive_desc_create(
559 mkldnn_primitive_desc_t *sum_primitive_desc,
560 const mkldnn_memory_desc_t *output_desc, int n, const float *scales,
561 const_mkldnn_primitive_desc_t *input_pds);
565 /** @addtogroup c_api_convolution Convolution
566 * A primitive to compute convolution using different algorithms.
568 * \f[dst[n][oc][oh][ow] =
569 * \sum_{kw=0}^{KW}\sum_{kh=0}^{KH}\sum_{ic=0}^{IC}
570 * src[n][ic][oh \cdot s_h - p_l[0] + kh][ow \cdot s_w - p_r[1] + kw]
571 * \cdot weights[g][oc][ic][kh][kw]
574 * where size of output spatial domain is given by
575 * \f$ OH = \left\lfloor{\frac{IH - KH + p_l[0] + p_r[0]}{s_h}}
576 * \right\rfloor + 1\f$,
577 * \f$ OW = \left\lfloor{\frac{IW - KW + p_l[1] + p_r[1]}{s_w}}
578 * \right\rfloor + 1\f$,
580 * and summation is carried over input channels \f$ic\f$ in
581 * group \f$g\f$, and \f$s_h, s_w\f$ are @p strides and
582 * \f$p_l, p_r\f$ are @p padding_l and @p padding_r.
585 /** Initializes a convolution descriptor @p conv_desc for forward propagation
586 * using @p prop_kind (possible values are #mkldnn_forward_training or
587 * #mkldnn_forward_inference), @p alg_kind, memory descriptors, @p strides, @p
588 * padding_l, @p padding_r, and @p padding_kind. In order to create a
589 * convolution without bias, @p bias_desc should be either @c NULL or point to
590 * a descriptor with memory format equals to #mkldnn_format_undef.
592 * @note if @p padding_r is @c NULL, the padding is supposed to be symmetric
594 * @note memory descriptors are allowed to be initialized with #mkldnn_any
595 * value of @p format_kind. */
596 mkldnn_status_t MKLDNN_API mkldnn_convolution_forward_desc_init(
597 mkldnn_convolution_desc_t *conv_desc, mkldnn_prop_kind_t prop_kind,
598 mkldnn_alg_kind_t alg_kind, const mkldnn_memory_desc_t *src_desc,
599 const mkldnn_memory_desc_t *weights_desc,
600 const mkldnn_memory_desc_t *bias_desc,
601 const mkldnn_memory_desc_t *dst_desc, const mkldnn_dims_t strides,
602 const mkldnn_dims_t padding_l, const mkldnn_dims_t padding_r,
603 mkldnn_padding_kind_t padding_kind);
605 /** Initializes a dilated convolution descriptor @p conv_desc for forward
606 * propagation using @p prop_kind (possible values are #mkldnn_forward_training
607 * or #mkldnn_forward_inference), @p alg_kind, memory descriptors, @p strides,
608 * @p dilates, @p padding_l, @p padding_r, and @p padding_kind.
609 * In order to create a dilated convolution without bias, @p bias_desc
610 * should be either @c NULL or point to a descriptor with memory format equals
611 * to #mkldnn_format_undef.
613 * @note if @p padding_r is @c NULL, the padding is supposed to be symmetric
615 * @note memory descriptors are allowed to be initialized with #mkldnn_any
616 * value of @p format_kind. */
617 mkldnn_status_t MKLDNN_API mkldnn_dilated_convolution_forward_desc_init(
618 mkldnn_convolution_desc_t *conv_desc, mkldnn_prop_kind_t prop_kind,
619 mkldnn_alg_kind_t alg_kind, const mkldnn_memory_desc_t *src_desc,
620 const mkldnn_memory_desc_t *weights_desc,
621 const mkldnn_memory_desc_t *bias_desc,
622 const mkldnn_memory_desc_t *dst_desc, const mkldnn_dims_t strides,
623 const mkldnn_dims_t dilates, const mkldnn_dims_t padding_l,
624 const mkldnn_dims_t padding_r, mkldnn_padding_kind_t padding_kind);
626 /** Initializes a convolution descriptor @p conv_desc for backward propagation
627 * with respect to data using @p alg_kind, memory descriptors, @p strides, @p
628 * padding_l, @p padding_r, and @p padding_kind.
630 * @note memory descriptors are allowed to be initialized with #mkldnn_any
631 * value of @p format_kind. */
632 mkldnn_status_t MKLDNN_API mkldnn_convolution_backward_data_desc_init(
633 mkldnn_convolution_desc_t *conv_desc, mkldnn_alg_kind_t alg_kind,
634 const mkldnn_memory_desc_t *diff_src_desc,
635 const mkldnn_memory_desc_t *weights_desc,
636 const mkldnn_memory_desc_t *diff_dst_desc, const mkldnn_dims_t strides,
637 const mkldnn_dims_t padding_l, const mkldnn_dims_t padding_r,
638 mkldnn_padding_kind_t padding_kind);
640 /** Initializes a dilated convolution descriptor @p conv_desc for backward
641 * propagation with respect to data using @p alg_kind, memory descriptors, @p
642 * strides, @p dilates @p padding_l, @p padding_r, and @p padding_kind.
644 * @note memory descriptors are allowed to be initialized with #mkldnn_any
645 * value of @p format_kind. */
646 mkldnn_status_t MKLDNN_API mkldnn_dilated_convolution_backward_data_desc_init(
647 mkldnn_convolution_desc_t *conv_desc, mkldnn_alg_kind_t alg_kind,
648 const mkldnn_memory_desc_t *diff_src_desc,
649 const mkldnn_memory_desc_t *weights_desc,
650 const mkldnn_memory_desc_t *diff_dst_desc, const mkldnn_dims_t strides,
651 const mkldnn_dims_t dilates, const mkldnn_dims_t padding_l,
652 const mkldnn_dims_t padding_r, mkldnn_padding_kind_t padding_kind);
654 /** Initializes a convolution descriptor @p conv_desc for backward propagation
655 * with respect to weights using @p alg_kind, memory descriptors, @p strides,
656 * @p padding_l, @p padding_r, and @p padding_kind.
658 * @note memory descriptors are allowed to be initialized with #mkldnn_any
659 * value of @p format_kind. */
660 mkldnn_status_t MKLDNN_API mkldnn_convolution_backward_weights_desc_init(
661 mkldnn_convolution_desc_t *conv_desc, mkldnn_alg_kind_t alg_kind,
662 const mkldnn_memory_desc_t *src_desc,
663 const mkldnn_memory_desc_t *diff_weights_desc,
664 const mkldnn_memory_desc_t *diff_bias_desc,
665 const mkldnn_memory_desc_t *diff_dst_desc, const mkldnn_dims_t strides,
666 const mkldnn_dims_t padding_l, const mkldnn_dims_t padding_r,
667 mkldnn_padding_kind_t padding_kind);
669 /** Initializes a convolution descriptor @p conv_desc for backward propagation
670 * with respect to weights using @p alg_kind, memory descriptors, @p strides,
671 * @p dilates @p padding_l, @p padding_r, and @p padding_kind.
673 * @note memory descriptors are allowed to be initialized with #mkldnn_any
674 * value of @p format_kind. */
675 mkldnn_status_t MKLDNN_API
676 mkldnn_dilated_convolution_backward_weights_desc_init(
677 mkldnn_convolution_desc_t *conv_desc, mkldnn_alg_kind_t alg_kind,
678 const mkldnn_memory_desc_t *src_desc,
679 const mkldnn_memory_desc_t *diff_weights_desc,
680 const mkldnn_memory_desc_t *diff_bias_desc,
681 const mkldnn_memory_desc_t *diff_dst_desc, const mkldnn_dims_t strides,
682 const mkldnn_dims_t dilates, const mkldnn_dims_t padding_l,
683 const mkldnn_dims_t padding_r, mkldnn_padding_kind_t padding_kind);
687 /** @addtogroup c_api_deconvolution Deconvolution
688 * A primitive to compute deconvolution using different algorithms.
693 /** Initializes a deconvolution descriptor @p deconv_desc for forward propagation
694 * using @p prop_kind (possible values are #mkldnn_forward_training or
695 * #mkldnn_forward_inference), @p alg_kind, memory descriptors, @p strides, @p
696 * padding_l, @p padding_r, and @p padding_kind. In order to create a
697 * deconvolution without bias, @p bias_desc should be either @c NULL or point to
698 * a descriptor with memory format equals to #mkldnn_format_undef.
700 * @note if @p padding_r is @c NULL, the padding is supposed to be symmetric
702 * @note memory descriptors are allowed to be initialized with #mkldnn_any
703 * value of @p format_kind. */
704 mkldnn_status_t MKLDNN_API mkldnn_deconvolution_forward_desc_init(
705 mkldnn_deconvolution_desc_t *conv_desc, mkldnn_prop_kind_t prop_kind,
706 mkldnn_alg_kind_t alg_kind, const mkldnn_memory_desc_t *src_desc,
707 const mkldnn_memory_desc_t *weights_desc,
708 const mkldnn_memory_desc_t *bias_desc,
709 const mkldnn_memory_desc_t *dst_desc, const mkldnn_dims_t strides,
710 const mkldnn_dims_t padding_l, const mkldnn_dims_t padding_r,
711 mkldnn_padding_kind_t padding_kind);
713 /** Initializes a deconvolution descriptor @p conv_desc for backward propagation
714 * with respect to data using @p alg_kind, memory descriptors, @p strides, @p
715 * padding_l, @p padding_r, and @p padding_kind.
717 * @note memory descriptors are allowed to be initialized with #mkldnn_any
718 * value of @p format_kind. */
719 mkldnn_status_t MKLDNN_API mkldnn_deconvolution_backward_data_desc_init(
720 mkldnn_deconvolution_desc_t *conv_desc, mkldnn_alg_kind_t alg_kind,
721 const mkldnn_memory_desc_t *diff_src_desc,
722 const mkldnn_memory_desc_t *weights_desc,
723 const mkldnn_memory_desc_t *diff_dst_desc, const mkldnn_dims_t strides,
724 const mkldnn_dims_t padding_l, const mkldnn_dims_t padding_r,
725 mkldnn_padding_kind_t padding_kind);
727 /** Initializes a deconvolution descriptor @p conv_desc for backward propagation
728 * with respect to weights using @p alg_kind, memory descriptors, @p strides,
729 * @p padding_l, @p padding_r, and @p padding_kind.
731 * @note memory descriptors are allowed to be initialized with #mkldnn_any
732 * value of @p format_kind. */
733 mkldnn_status_t MKLDNN_API mkldnn_deconvolution_backward_weights_desc_init(
734 mkldnn_deconvolution_desc_t *conv_desc, mkldnn_alg_kind_t alg_kind,
735 const mkldnn_memory_desc_t *src_desc,
736 const mkldnn_memory_desc_t *diff_weights_desc,
737 const mkldnn_memory_desc_t *diff_bias_desc,
738 const mkldnn_memory_desc_t *diff_dst_desc, const mkldnn_dims_t strides,
739 const mkldnn_dims_t padding_l, const mkldnn_dims_t padding_r,
740 mkldnn_padding_kind_t padding_kind);
743 /** @addtogroup c_api_eltwise Eltwise
744 * A primitive to compute element wise operations like parametric rectifier
745 * linear unit (ReLU).
747 * Both forward and backward passes support in-place operation, i.e. src
748 * and dst point to the same memory for forward, and diff_dst and diff_src
749 * point to the same memory for backward pass.
751 * @warning Since for backward pass original src is required, in-place forward
752 * pass in general cannot be applied during training. However for some kinds of
753 * element wise operations (namely ReLU with alpha parameter equals 0) dst and
754 * src can be interchangeable for the backward pass, which allows performing
755 * in-place forward even for training.
759 /** Initializes a @p eltwise_desc for forward propagation using @p prop_kind
760 * (possible values are #mkldnn_forward_training or #mkldnn_forward_inference),
761 * @p alg_kind algorithm, memory descriptor @p data_desc, and @p alpha,
762 * @p beta parameters.
763 * @sa mkldnn_eltwise_desc_t for details */
764 mkldnn_status_t MKLDNN_API mkldnn_eltwise_forward_desc_init(
765 mkldnn_eltwise_desc_t *eltwise_desc, mkldnn_prop_kind_t prop_kind,
766 mkldnn_alg_kind_t alg_kind, const mkldnn_memory_desc_t *data_desc,
767 float alpha, float beta);
769 /** Initializes a @p eltwise_desc for backward propagation using @p alg_kind
770 * algorithm memory descriptors @p diff_data_desc and @p data_desc, and
771 * @p alpha, @p beta parameters.
772 * @sa mkldnn_eltwise_desc_t for details */
773 mkldnn_status_t MKLDNN_API mkldnn_eltwise_backward_desc_init(
774 mkldnn_eltwise_desc_t *eltwise_desc, mkldnn_alg_kind_t alg_kind,
775 const mkldnn_memory_desc_t *diff_data_desc,
776 const mkldnn_memory_desc_t *data_desc, float alpha, float beta);
780 /** @addtogroup c_api_relu ReLU (deprecated, use Eltwise instead)
781 * A primitive to compute a parametric rectifier linear unit (ReLU).
783 * \f[dst[n][c][h][w] = \max(src[n][c][h][w], 0) +
784 * \min(src[n][c][h][w], 0) \cdot negative\_slope\f]
787 /** Initializes a @p relu_desc for forward propagation using @p prop_kind
788 * (possible values are #mkldnn_forward_training or #mkldnn_forward_inference),
789 * @p negative_slope and memory descriptor @p data_desc.
791 * @deprecated use mkldnn_eltwise_forward_desc_init() instead, with @p alpha
792 * equals @p negative_slope */
794 mkldnn_status_t MKLDNN_API mkldnn_relu_forward_desc_init(
795 mkldnn_relu_desc_t *relu_desc, mkldnn_prop_kind_t prop_kind,
796 const mkldnn_memory_desc_t *data_desc, float negative_slope);
798 /** Initializes a @p relu_desc for backward propagation using @p negative_slope
799 * and memory descriptors @p diff_data_desc and @p data_desc.
801 * @deprecated use mkldnn_eltwise_backward_desc_init() instead, with @p alpha
802 * equals @p negative_slope */
804 mkldnn_status_t MKLDNN_API mkldnn_relu_backward_desc_init(
805 mkldnn_relu_desc_t *relu_desc,
806 const mkldnn_memory_desc_t *diff_data_desc,
807 const mkldnn_memory_desc_t *data_desc, float negative_slope);
811 /** @addtogroup c_api_depthwise Depthwise
812 * A primitive to compute channel wise operations like scale and shift
815 /** Initializes a @p depthwise_desc for forward propagation using @p prop_kind
816 * (possible values are #mkldnn_forward_training or #mkldnn_forward_inference),
817 * @p alg_kind algorithm, memory descriptor @p data_desc.
818 * @sa mkldnn_depthwise_desc_t for details */
819 mkldnn_status_t MKLDNN_API mkldnn_depthwise_forward_desc_init(
820 mkldnn_depthwise_desc_t *depthwise_desc, mkldnn_prop_kind_t prop_kind,
821 mkldnn_alg_kind_t alg_kind, const mkldnn_memory_desc_t *src_desc, const mkldnn_memory_desc_t *dst_desc,
822 const mkldnn_memory_desc_t *weights_desc, const mkldnn_memory_desc_t *bias_desc);
826 /** @addtogroup c_api_softmax Softmax
827 * A primitive to perform softmax.
830 * \frac{\exp(src[ou][c][in]) - \max\limits_{c}(src[ou][c][in])}
831 * {\sum\limits_{c}\{\exp(src[ou][c][in])
832 * - \max\limits_{c}(src[ou][c][in])\}},\f]
834 * where \f$ou, iu\f$ are outer and inner sizes repectively, defined
835 * by @p data_desc.dims and @p softmax_axis.
838 /** Initializes a @p softmax_desc for forward propagation using @p prop_kind
839 * (possible value are #mkldnn_forward_training or #mkldnn_forward_inference)
840 * and memory descriptor @p data_desc. */
841 mkldnn_status_t MKLDNN_API mkldnn_softmax_forward_desc_init(
842 mkldnn_softmax_desc_t *softmax_desc, mkldnn_prop_kind_t prop_kind,
843 const mkldnn_memory_desc_t *data_desc, int softmax_axis);
845 /** Initializes a @p softmax_desc for backward propagation using memory
846 * descriptors @p diff_desc and @p data_desc. */
847 mkldnn_status_t MKLDNN_API mkldnn_softmax_backward_desc_init(
848 mkldnn_softmax_desc_t *softmax_desc,
849 const mkldnn_memory_desc_t *diff_desc,
850 const mkldnn_memory_desc_t *data_desc, int softmax_axis);
854 /** @addtogroup c_api_pooling Pooling
855 * A primitive to perform max or average pooling.
858 * \f[dst[n][oc][oh][ow] =
859 * \max\limits_{kw,kh}
860 * (src[n][ic][oh \cdot s_h - p_l[0] + kh][ow \cdot s_w - p_r[1] + kw]),\f]
863 * \f[dst[n][oc][oh][ow] =
864 * \frac{1}{KW \cdot KH}\sum\limits_{kw,kh}
865 * src[n][ic][oh \cdot s_h - p_l[0] + kh][ow \cdot s_w - p_r[1] + kw],\f]
867 * where \f$p_l, p_r\f$ are @p padding_l and @p padding_r
868 * respectively and output spatial dimensions are calculated
869 * similarly as done in convolution.
872 /** Initializes a pooling descriptor @p pool_desc for forward propagation using
873 * @p prop_kind (possible values are #mkldnn_forward_training or
874 * #mkldnn_forward_inference), @p alg_kind, memory descriptors, and pooling
875 * parameters in spatial domain: @p strides, @p kernel sizes, @p padding_l, @p
876 * padding_r, and @p padding_kind.
878 * @note if @p padding_r is @c NULL, the padding is supposed to be symmetric
881 mkldnn_status_t MKLDNN_API mkldnn_pooling_forward_desc_init(
882 mkldnn_pooling_desc_t *pool_desc, mkldnn_prop_kind_t prop_kind,
883 mkldnn_alg_kind_t alg_kind, const mkldnn_memory_desc_t *src_desc,
884 const mkldnn_memory_desc_t *dst_desc, const mkldnn_dims_t strides,
885 const mkldnn_dims_t kernel, const mkldnn_dims_t padding_l,
886 const mkldnn_dims_t padding_r, mkldnn_padding_kind_t padding_kind);
888 /** Initializes a pooling descriptor @p pool_desc for backward propagation
889 * using @p alg_kind, memory descriptors, and pooling parameters in spatial
890 * domain: @p strides, @p kernel sizes, @p padding_l, @p padding_r, and @p
894 mkldnn_status_t MKLDNN_API mkldnn_pooling_backward_desc_init(
895 mkldnn_pooling_desc_t *pool_desc, mkldnn_alg_kind_t alg_kind,
896 const mkldnn_memory_desc_t *diff_src_desc,
897 const mkldnn_memory_desc_t *diff_dst_desc, const mkldnn_dims_t strides,
898 const mkldnn_dims_t kernel, const mkldnn_dims_t padding_l,
899 const mkldnn_dims_t padding_r, mkldnn_padding_kind_t padding_kind);
903 /** @addtogroup c_api_lrn LRN
904 * A primitive to perform local response normalization (LRN) across or within
907 * LRN accross channels:
908 * \f[dst[n][c][h][w] = \left\{k + \frac{\alpha}{n_{l}}
909 * \sum\limits_{i=-(n_{l}-1)/2}^{(n_{l}+1)/2}
910 * (src[n][c+i][h][w])^2\right\}^{-\beta}
911 * src[n][c][h][w],\f]
913 * LRN within channels:
914 * \f[dst[n][c][h][w] = \left\{k + \frac{\alpha}{n_{l}}
915 * \sum\limits_{i=-(n_{l}-1)/2}^{(n_{l}+1)/2}
916 * (src[n][c][h+i][w+i])^2\right\}^{-\beta}
917 * src[n][c][h][w],\f]
919 * where \f$n_{l}\f$ is the @p local_size.
922 /** Initializes an @p lrn_desc for forward propagation using @p prop_kind
923 * (possible values are #mkldnn_forward_training or #mkldnn_forward_inference),
924 * @p alg_kind, memory descriptor @p data_desc, and regularization
925 * parameters @p local_size, @p alpha, @p beta, and @p k. */
926 mkldnn_status_t MKLDNN_API mkldnn_lrn_forward_desc_init(
927 mkldnn_lrn_desc_t *lrn_desc, mkldnn_prop_kind_t prop_kind,
928 mkldnn_alg_kind_t alg_kind, const mkldnn_memory_desc_t *data_desc,
929 int local_size, float alpha, float beta, float k);
931 /** Initializes an @p lrn_desc for backward propagation using @p alg_kind,
932 * memory descriptors @p data_desc, and @p diff_data_desc, and regularization
933 * parameters @p local_size, @p alpha, @p beta, and @p k. */
934 mkldnn_status_t MKLDNN_API mkldnn_lrn_backward_desc_init(
935 mkldnn_lrn_desc_t *lrn_desc, mkldnn_alg_kind_t alg_kind,
936 const mkldnn_memory_desc_t *diff_data_desc,
937 const mkldnn_memory_desc_t *data_desc, int local_size, float alpha,
938 float beta, float k);
942 /** @addtogroup c_api_batch_normalization Batch Normalization
943 * A primitive to perform batch normalization.
945 * \f[dst[n][c][h][w] = \gamma[c] \frac{src[n][c][h][w] - \mu[c]}
946 * {\sqrt{\sigma[c] + eps}} + \beta[c],\f]
948 * where \f$\gamma[c], \beta[c]\f$ are weights and bias for a channel and,
950 * \f$\mu[c] = \frac{1}{NHW} \sum\limits_{whn} src[n][c][h][w]\f$,
951 * \f$\sigma[c] = \frac{1}{NHW} \sum\limits_{whn}
952 * (src[n][c][h][w] - \mu[c])^2\f$,
954 * and eps is a constant to improve numerical stability.
956 * Both forward and backward passes support in-place operation, i.e. src
957 * and dst point to the same memory for forward, and diff_dst and diff_src
958 * point to the same memory for backward pass.
962 /** Initializes a batch normalization descriptor @p bnrm_desc for forward
963 * propagation using @p prop_kind, (possible values are
964 * #mkldnn_forward_training or #mkldnn_forward_inference), memory descriptor
965 * @p data_desc, normalization parameter @p epsilon and flags (possible values
966 * are #mkldnn_use_global_stats and #mkldnn_use_scaleshift).
968 * @sa mkldnn_batch_normalization_desc_t */
969 mkldnn_status_t MKLDNN_API mkldnn_batch_normalization_forward_desc_init(
970 mkldnn_batch_normalization_desc_t *bnrm_desc,
971 mkldnn_prop_kind_t prop_kind, const mkldnn_memory_desc_t *data_desc,
972 float epsilon, unsigned flags);
974 /** Initializes a batch normalization descriptor @p bnrm_desc for backward
975 * propagation with respect to data and scale-shift parameters using memory
976 * descriptors @p data_desc and @p diff_data_desc, and normalization parameter
977 * @p epsilon and flags (possible values are #mkldnn_use_global_stats and
978 * #mkldnn_use_scaleshift).
980 * @sa mkldnn_batch_normalization_desc_t */
981 mkldnn_status_t MKLDNN_API mkldnn_batch_normalization_backward_desc_init(
982 mkldnn_batch_normalization_desc_t *bnrm_desc,
983 mkldnn_prop_kind_t prop_kind,
984 const mkldnn_memory_desc_t *diff_data_desc,
985 const mkldnn_memory_desc_t *data_desc,
986 float epsilon, unsigned flags);
990 /** @addtogroup c_api_inner_product Inner product
991 * A primitive to compute an inner product.
993 * Inner product layer is also known as fully connected layer.
994 * with spatial dimension:
996 * \f[dst[n][oc] = \sum\limits_{ic, kh, kw}
997 * src[n][ic][kh][kw] \cdot weights[oc][ic][kh][kw]
1001 /** Initializes an inner product descriptor @p ip_desc for forward propagation
1002 * using @p prop_kind (possible values are #mkldnn_forward_training or
1003 * #mkldnn_forward_inference) and memory descriptors. In order to create an
1004 * inner product without bias, @p bias_desc should be either @c NULL or a
1005 * pointer to descriptor with memory format equals to #mkldnn_format_undef.
1008 * memory descriptors are allowed to be initialized with #mkldnn_any value
1009 * of @p format_kind. */
1010 mkldnn_status_t MKLDNN_API mkldnn_inner_product_forward_desc_init(
1011 mkldnn_inner_product_desc_t *ip_desc, mkldnn_prop_kind_t prop_kind,
1012 const mkldnn_memory_desc_t *src_desc,
1013 const mkldnn_memory_desc_t *weights_desc,
1014 const mkldnn_memory_desc_t *bias_desc,
1015 const mkldnn_memory_desc_t *dst_desc);
1017 /** Initializes an inner product descriptor @p ip_desc for backward propagation
1018 * with respect to data using memory descriptors.
1021 * memory descriptors are allowed to be initialized with #mkldnn_any value
1022 * of @p format_kind. */
1023 mkldnn_status_t MKLDNN_API mkldnn_inner_product_backward_data_desc_init(
1024 mkldnn_inner_product_desc_t *ip_desc,
1025 const mkldnn_memory_desc_t *diff_src_desc,
1026 const mkldnn_memory_desc_t *weights_desc,
1027 const mkldnn_memory_desc_t *diff_dst_desc);
1029 /** Initializes an inner product descriptor @p ip_desc for backward propagation
1030 * with respect to weights using memory descriptors.
1033 * memory descriptors are allowed to be initialized with #mkldnn_any value
1034 * of @p format_kind. */
1035 mkldnn_status_t MKLDNN_API mkldnn_inner_product_backward_weights_desc_init(
1036 mkldnn_inner_product_desc_t *ip_desc,
1037 const mkldnn_memory_desc_t *src_desc,
1038 const mkldnn_memory_desc_t *diff_weights_desc,
1039 const mkldnn_memory_desc_t *diff_bias_desc,
1040 const mkldnn_memory_desc_t *diff_dst_desc);
1044 /** @addtogroup c_api_convolution_relu Convolution followed by ReLU (deprecated)
1045 * A merged primitive to compute a convolution followed by relu.
1048 /** Initializes a merged convolution-relu descriptor @p conv_relu_desc for
1049 * forward propagation (supported inference mode only) using convolution
1050 * descriptor @p conv_desc and ReLU parameter @p negative slope.
1052 * @deprecated use mkldnn_convolution_desc_init with
1053 * mkldnn_post_ops_append_eltwise to append ReLU */
1054 mkldnn_status_t MKLDNN_API mkldnn_convolution_relu_desc_init(
1055 mkldnn_convolution_relu_desc_t *conv_relu_desc,
1056 const mkldnn_convolution_desc_t *conv_desc, float negative_slope);
1060 /** @addtogroup c_api_rnn RNN
1061 * A primitive to compute common recurrent layer.
1062 * @todo add additional description for the group
1066 * Initializes a recurrent cell descriptor @p rnn_cell_desc
1067 * using @p rnn_cell_desc, @p kind (possible values are
1068 * #mkldnn_vanilla_rnn, #mkldnn_vanilla_lstm, #mkldnn_vanilla_gru,
1069 * #mkldnn_gru_linear_before_reset),
1070 * @p f (possible values are #mkldnn_eltwise_relu,
1071 * #mkldnn_eltwise_tanh), @p flags, @p alpha, and @p clipping.
1073 mkldnn_status_t MKLDNN_API mkldnn_rnn_cell_desc_init(
1074 mkldnn_rnn_cell_desc_t *rnn_cell_desc,
1075 mkldnn_alg_kind_t kind, mkldnn_alg_kind_t f,
1076 unsigned int flags, float alpha, float clipping);
1078 /** Returns the number of gates of a particular @p rnn_cell_desc. */
1079 int MKLDNN_API mkldnn_rnn_cell_get_gates_count(
1080 const mkldnn_rnn_cell_desc_t *rnn_cell_desc);
1082 /** Returns the number of states of a particular @p rnn_cell_desc. */
1083 int MKLDNN_API mkldnn_rnn_cell_get_states_count(
1084 const mkldnn_rnn_cell_desc_t *rnn_cell_desc);
1086 /** Initializes a rnn descriptor @p rnn_desc for forward propagation
1087 * using @p prop_kind, @p rnn_cell_desc, @p direction, and memory descriptors.
1088 * @note if @p prop_kind equals #mkldnn_forward_training, you need to query a
1089 * worskpace memory descriptor before creating the primitive.
1091 * @note all memory descriptors except @p src_iter_desc are allowed to be
1092 * initialized with #mkldnn_any value of @p format_kind. */
1093 mkldnn_status_t MKLDNN_API mkldnn_rnn_forward_desc_init(
1094 mkldnn_rnn_desc_t *rnn_desc, mkldnn_prop_kind_t prop_kind,
1095 const mkldnn_rnn_cell_desc_t *rnn_cell_desc,
1096 const mkldnn_rnn_direction_t direction,
1097 const mkldnn_memory_desc_t *src_layer_desc,
1098 const mkldnn_memory_desc_t *src_iter_desc,
1099 const mkldnn_memory_desc_t *weights_layer_desc,
1100 const mkldnn_memory_desc_t *weights_iter_desc,
1101 const mkldnn_memory_desc_t *bias_desc,
1102 const mkldnn_memory_desc_t *dst_layer_desc,
1103 const mkldnn_memory_desc_t *dst_iter_desc);
1105 /** Initializes a rnn descriptor @p rnn_desc for backward propagation
1106 * using @p prop_kind, @p rnn_cell_desc, @p direction, and memory descriptors.
1107 * @note all memory descriptors are allowed to be initialized with
1108 * #mkldnn_any value of @p format_kind. */
1109 mkldnn_status_t MKLDNN_API mkldnn_rnn_backward_desc_init(
1110 mkldnn_rnn_desc_t *rnn_desc, mkldnn_prop_kind_t prop_kind,
1111 const mkldnn_rnn_cell_desc_t *rnn_cell_desc,
1112 const mkldnn_rnn_direction_t direction,
1113 const mkldnn_memory_desc_t *src_layer_desc,
1114 const mkldnn_memory_desc_t *src_iter_desc,
1115 const mkldnn_memory_desc_t *weights_layer_desc,
1116 const mkldnn_memory_desc_t *weights_iter_desc,
1117 const mkldnn_memory_desc_t *bias_desc,
1118 const mkldnn_memory_desc_t *dst_layer_desc,
1119 const mkldnn_memory_desc_t *dst_iter_desc,
1120 const mkldnn_memory_desc_t *diff_src_layer_desc,
1121 const mkldnn_memory_desc_t *diff_src_iter_desc,
1122 const mkldnn_memory_desc_t *diff_weights_layer_desc,
1123 const mkldnn_memory_desc_t *diff_weights_iter_desc,
1124 const mkldnn_memory_desc_t *diff_bias_desc,
1125 const mkldnn_memory_desc_t *diff_dst_layer,
1126 const mkldnn_memory_desc_t *diff_dst_iter_desc);
1130 /** @addtogroup c_api_roi_pooling ROI Pooling
1131 * A primitive to perform roi pooling.
1134 /** Initializes a @p roi_pooling_desc for forward propagation using @p prop_kind
1135 * (possible value are #mkldnn_forward_inference)
1136 * and memory descriptor @p data_desc. */
1137 mkldnn_status_t MKLDNN_API mkldnn_roi_pooling_forward_desc_init(
1138 mkldnn_roi_pooling_desc_t *roi_pooling_desc, mkldnn_prop_kind_t prop_kind,
1139 mkldnn_alg_kind_t algorithm,
1140 mkldnn_memory_desc_t *src_descs, int num_inputs,
1141 const mkldnn_memory_desc_t *dst_desc,
1142 int pooled_h, int pooled_w, double spatial_scale);
1148 /** @addtogroup c_api_engine Engine operations
1151 /** Returns the number of engines of a particular @p kind. */
1152 size_t MKLDNN_API mkldnn_engine_get_count(mkldnn_engine_kind_t kind);
1154 /** Creates an @p engine of particular @p kind and @p index. */
1155 mkldnn_status_t MKLDNN_API mkldnn_engine_create(mkldnn_engine_t *engine,
1156 mkldnn_engine_kind_t kind, size_t index);
1158 /** Returns the kind of an @p engine. */
1159 mkldnn_status_t MKLDNN_API mkldnn_engine_get_kind(mkldnn_engine_t engine,
1160 mkldnn_engine_kind_t *kind);
1162 /** Destroys an @p engine. */
1163 mkldnn_status_t MKLDNN_API mkldnn_engine_destroy(mkldnn_engine_t engine);
1167 /** @addtogroup c_api_stream Execution stream operations
1170 /** Creates an execution @p stream of @p stream_kind. */
1171 mkldnn_status_t MKLDNN_API mkldnn_stream_create(mkldnn_stream_t *stream,
1172 mkldnn_stream_kind_t stream_kind);
1174 /** Submits @p primitives to an execution @p stream. The number of primitives
1175 * is @p n. All or none of the primitives can be lazy. In case of an error,
1176 * returns the offending @p error_primitive if it is not @c NULL. */
1177 mkldnn_status_t MKLDNN_API mkldnn_stream_submit(mkldnn_stream_t stream,
1178 size_t n, mkldnn_primitive_t primitives[],
1179 mkldnn_primitive_t *error_primitive);
1181 /** Waits for all primitives in the execution @p stream to finish. Returns
1182 * immediately if @p block is zero. In case of an error, returns
1183 * the offending @p error_primitive if it is not @c NULL. */
1184 mkldnn_status_t MKLDNN_API mkldnn_stream_wait(mkldnn_stream_t stream,
1185 int block, mkldnn_primitive_t *error_primitive);
1187 /** Reruns all the primitives within the @p stream. In case of an error,
1188 * returns the offending @p error_primitive if it is not @c NULL. */
1189 mkldnn_status_t MKLDNN_API mkldnn_stream_rerun(mkldnn_stream_t stream,
1190 mkldnn_primitive_t *error_primitive);
1192 /** Destroys an execution @p stream. */
1193 mkldnn_status_t MKLDNN_API mkldnn_stream_destroy(mkldnn_stream_t stream);
1197 /** @addtogroup c_api_service Service functions
1200 /** Sets verbosity level (print information to stdout).
1201 * Possible levels are:
1202 * - 0 -- no verbose output
1203 * - 1 -- primitive information at execution
1204 * - 2 -- primitive information at creation and execution
1207 * Dumping information might affect performance */
1208 mkldnn_status_t MKLDNN_API mkldnn_verbose_set(int level);
1210 /** Returns cache size for specified level in bytes.
1212 * Currently, if it is not able to fetch the cache topology
1213 * function defaults to 32KB of L1, 512KB of L2 and 1MB of L3 per core. */
1214 unsigned int MKLDNN_API mkldnn_get_cache_size(int level, int per_core);
1218 /** @addtogroup c_api_blas BLAS functions
1221 /** SGEMM performs matrix-matrix multiplication operation
1222 * C := alpha*op( A )*op( B ) + beta*C,
1223 * where op( X ) is one of
1224 * op( X ) = X or op( X ) = X**T,
1225 * alpha and beta are scalars, and A, B and C are matrices, with op( A )
1226 * an m by k matrix, op( B ) a k by n matrix and C an m by n matrix.
1228 * API is different compared to standard BLAS routine
1229 * as it returns mkldnn_status_t for error handling.
1230 * XERBLA is not supported: no error message will be printed
1231 * in case of incorrect parameters */
1232 mkldnn_status_t MKLDNN_API mkldnn_sgemm(const char *transa, const char *transb,
1233 const int *M, const int *N, const int *K,
1234 const float *alpha, const float *A, const int *lda,
1235 const float *B, const int *ldb,
1236 const float *beta, float *C, const int *ldc);