api: rnn: Adding the new RNN API (experimental)

this closes #46 and closes #154

doc/mainpage.md

@@ -5,8 +5,9 @@ The Intel(R) Math Kernel Library for Deep Neural Networks (Intel(R) MKL-DNN) is
 open source performance library for Deep Learning (DL) applications intended
 for acceleration of DL frameworks on Intel(R) architecture. Intel MKL-DNN
 includes highly vectorized and threaded building blocks for implementation of
-convolutional neural networks (CNN) with C and C++ interfaces. This
-project is created to help the DL community innovate on the Intel(R) processor family.
+convolutional neural networks (CNN) and reccurent neural networks (RNN) with
+C and C++ interfaces. This project is created to help the DL community innovate
+on the Intel(R) processor family.
 
 The library supports the most commonly used primitives necessary to accelerate
 bleeding edge image recognition topologies, including Cifar*, AlexNet*, VGG*,
@@ -26,13 +27,21 @@ operations. The library includes the following classes of functions:
 
 * Activation
     - rectified linear unit neuron activation (ReLU)
-	- softmax
+    - softmax
 
 * Data manipulation
     - reorder (multi-dimensional transposition/conversion),
     - sum,
     - concat
-	- view
+    - view
+
+Also the library contains experimental support of RNN primitives to accelerate
+speech recognition and neural machine translation topologies. The experemental
+support includes the following classes of functions:
+
+* RNN
+    - RNN cell
+    - LSTM cell
 
 Intel MKL DNN primitives implement a plain C/C++ application programming
 interface (API) that can be used in the existing C/C++ DNN frameworks, as well
@@ -128,6 +137,9 @@ The following examples are available in the /examples directory and provide more
     - C: simple_training.c
     - C++: simple_training_net.cpp
 
+* Creation of forward propagation of GNMT topology (experimental support)
+    - C++: simple_rnn.cpp
+
 ### Performance Considerations
 
 *  Convolution and inner product primitives choose the memory format when you create them with the unspecified memory

include/mkldnn.h

@@ -939,6 +939,75 @@ mkldnn_status_t MKLDNN_API mkldnn_convolution_relu_desc_init(
 
 /** @} */
 
+/** @addtogroup c_api_rnn RNN
+ * A primitive to compute common recurrent layer.
+ * @todo add additional description for the group
+ * @{ */
+
+/**
+ * Initializes a recurrent cell descriptor @p rnn_cell_desc
+ * using @p rnn_cell_desc, @p kind (possible values are
+ *  #mkldnn_vanilla_rnn, #mkldnn_vanilla_lstm, #mkldnn_vanilla_gru),
+ *  @p f (possible values are #mkldnn_eltwise_relu,
+ *   #mkldnn_eltwise_tanh), @p flags, @p alpha, and @p clipping.
+ */
+mkldnn_status_t MKLDNN_API mkldnn_rnn_cell_desc_init(
+        mkldnn_rnn_cell_desc_t *rnn_cell_desc,
+        mkldnn_alg_kind_t kind, mkldnn_alg_kind_t f,
+        unsigned int flags, float alpha, float clipping);
+
+/** Returns the number of gates of a particular @p rnn_cell_desc. */
+int MKLDNN_API mkldnn_rnn_cell_get_gates_count(
+        const mkldnn_rnn_cell_desc_t *rnn_cell_desc);
+
+/** Returns the number of states of a particular @p rnn_cell_desc. */
+int MKLDNN_API mkldnn_rnn_cell_get_states_count(
+        const mkldnn_rnn_cell_desc_t *rnn_cell_desc);
+
+/** Initializes a rnn descriptor @p rnn_desc for forward propagation
+ * using @p prop_kind, @p rnn_cell_desc, @p direction, and memory descriptors.
+ * @note if @p prop_kind equals #mkldnn_forward_training, you need to query a
+ * worskpace memory descriptor before creating the primitive.
+ *
+ * @note all memory descriptors except @p src_iter_desc are allowed to be
+ * initialized with #mkldnn_any value of @p format_kind. */
+mkldnn_status_t MKLDNN_API mkldnn_rnn_forward_desc_init(
+        mkldnn_rnn_desc_t *rnn_desc, mkldnn_prop_kind_t prop_kind,
+        const mkldnn_rnn_cell_desc_t *rnn_cell_desc,
+        const mkldnn_rnn_direction_t direction,
+        const mkldnn_memory_desc_t *src_layer_desc,
+        const mkldnn_memory_desc_t *src_iter_desc,
+        const mkldnn_memory_desc_t *weights_layer_desc,
+        const mkldnn_memory_desc_t *weights_iter_desc,
+        const mkldnn_memory_desc_t *bias_desc,
+        const mkldnn_memory_desc_t *dst_layer_desc,
+        const mkldnn_memory_desc_t *dst_iter_desc);
+
+/** Initializes a rnn descriptor @p rnn_desc for backward propagation
+ * using @p prop_kind, @p rnn_cell_desc, @p direction, and memory descriptors.
+ * @note all memory descriptors are allowed to be initialized with
+ * #mkldnn_any value of @p format_kind. */
+mkldnn_status_t MKLDNN_API mkldnn_rnn_backward_desc_init(
+        mkldnn_rnn_desc_t *rnn_desc, mkldnn_prop_kind_t prop_kind,
+        const mkldnn_rnn_cell_desc_t *rnn_cell_desc,
+        const mkldnn_rnn_direction_t direction,
+        const mkldnn_memory_desc_t *src_layer_desc,
+        const mkldnn_memory_desc_t *src_iter_desc,
+        const mkldnn_memory_desc_t *weights_layer_desc,
+        const mkldnn_memory_desc_t *weights_iter_desc,
+        const mkldnn_memory_desc_t *bias_desc,
+        const mkldnn_memory_desc_t *dst_layer_desc,
+        const mkldnn_memory_desc_t *dst_iter_desc,
+        const mkldnn_memory_desc_t *diff_src_layer_desc,
+        const mkldnn_memory_desc_t *diff_src_iter_desc,
+        const mkldnn_memory_desc_t *diff_weights_layer_desc,
+        const mkldnn_memory_desc_t *diff_weights_iter_desc,
+        const mkldnn_memory_desc_t *diff_bias_desc,
+        const mkldnn_memory_desc_t *diff_dst_layer,
+        const mkldnn_memory_desc_t *diff_dst_iter_desc);
+
+/** @} */
+
 /** @} */
 
 /** @addtogroup c_api_engine Engine operations