PointToSubtensor section is commented as it's a subject for change

Author: dzakhar

doc/documents/mli_api_data/kernel_sp_conf_struct.rst

@@ -30,8 +30,9 @@ describe fields of existing MLI configuration structures:
  - Table :ref:`t_mli_prelu_cfg_desc`
 
  - Table :ref:`t_mli_mov_cfg_desc`
- 
- - Table :ref:`t_mli_sub_tensor_cfg_desc`
+
+..
+   - Table :ref:`t_mli_sub_tensor_cfg_desc`
 
 
 

doc/documents/mli_kernels/conv_2d.rst

@@ -25,7 +25,7 @@ convolution parameters (such as padding or stride), inputs and weights shape.
 ..
 
 Optionally, saturating ReLU activation function can be applied to the result of the 
-convolution during the function’s execution. For more information on supported ReLU types 
+convolution during the function's execution. For more information on supported ReLU types 
 and calculations, see :ref:`relu_prot`.
 
 This is a MAC-based kernel which implies accumulation. See :ref:`quant_accum_infl` for more information on 

doc/documents/mli_kernels/conv_depthwise.rst

@@ -35,7 +35,7 @@ filters for each channel of input. Such functionality refers to group convolutio
 and can be obtained by the corresponding kernel (see :ref:`grp_conv`). 
 
 Optionally, a saturating ReLU activation function can be applied to the result of the 
-convolution during the function’s execution. For more information on supported ReLU types 
+convolution during the function's execution. For more information on supported ReLU types 
 and calculations, see :ref:`relu_prot`.
 
 This is a MAC-based kernel which implies accumulation. See :ref:`quant_accum_infl` for more information 

doc/documents/mli_kernels/conv_grp.rst

@@ -25,7 +25,7 @@ number of filters per each group.
 ..
 
 Optionally, saturating ReLU activation function can be applied to the result of 
-the convolution during the function’s execution. For more information on supported ReLU 
+the convolution during the function's execution. For more information on supported ReLU 
 types and calculations, see :ref:`relu_prot`.
 
 This is a MAC-based kernel which implies accumulation. See :ref:`quant_accum_infl` for more information on related quantization aspects. 

doc/documents/mli_kernels/conv_transp.rst

@@ -7,7 +7,7 @@ For more details on calculations, see chapter 4 of `A guide to convolution
 arithmetic for deep learning <https://arxiv.org/abs/1603.07285>`_.
 
 Optionally, a saturating ReLU activation function can be applied to the 
-result of the convolution during the function’s execution. For more info 
+result of the convolution during the function's execution. For more info 
 on supported ReLU types and calculations, see :ref:`relu_prot`.
 
 The ``dilation_height`` and ``dilation_width`` parameter of ``mli_conv2d_cfg`` 

doc/documents/mli_kernels/introduction.rst

@@ -49,7 +49,7 @@ The slicing concept is illustrated in Figure :ref:`f_slicing_concept`.
    Slicing Concept
 ..
 
-If the tensors don’t fit into CCM, and there is no data cache, the data move functions can 
+If the tensors don't fit into CCM, and there is no data cache, the data move functions can 
 be used to copy full tensors or slices of tensors. (see Chapter :ref:`data_mvmt` ). Slicing 
 with some kernels requires updating the kernel parameters when passing each slice.
 

doc/documents/mli_kernels/rec_fully_con.rst

@@ -21,18 +21,18 @@ Each value of output tensor is calculated according to the following formula:
 
 Where:
 
-    :math:`x_{j}` *–* :math:`j_{\text{th}}` *value in input tensor*
+    :math:`x_{j}` *-* :math:`j_{\text{th}}` *value in input tensor*
 
-    :math:`y_{i}` *– output of* :math:`i_{\text{th}}` neuron
+    :math:`y_{i}` *- output of* :math:`i_{\text{th}}` neuron
     (:math:`i_{\text{th}}` *value in output tensor)*
 
-    :math:`W_{i,j}` *– weight of* :math:`j_{\text{th}}\ `\ *input element
+    :math:`W_{i,j}` *- weight of* :math:`j_{\text{th}}\ `\ *input element
     for* :math:`i_{\text{th}}` *neuron.*
 
-    :math:`b_{i}` *– bias for* :math:`i_{\text{th}}` *neuron*
+    :math:`b_{i}` *- bias for* :math:`i_{\text{th}}` *neuron*
 
 Optionally, a saturating ReLU activation function can be applied to the result of the calculations 
-during the function’s execution. For more information on supported ReLU types, see :ref:`relu_prot`.  
+during the function's execution. For more information on supported ReLU types, see :ref:`relu_prot`.  
 
 This is a MAC-based kernel which implies accumulation. See :ref:`quant_accum_infl` for more information on related quantization aspects. 
 The Number of accumulation series is equal to input size.

doc/documents/mli_kernels/rec_rnn_dense.rst

@@ -13,21 +13,21 @@ typically used in the majority of RNN architectures:
 
 Where:
 
-    :math:`{xa}_{j}`, :math:`{xb}_{j}`, :math:`{xn}_{j}` *–*
+    :math:`{xa}_{j}`, :math:`{xb}_{j}`, :math:`{xn}_{j}` *-*
     :math:`j_{\text{th}}` *value in one of the input tensors. These input
     tensors might be current input, previous output, cell state or any other 
     tensor depending on RNN Cell architecture*
 
-    :math:`{Wa}_{i,j}`, :math:`{Wb}_{i,j}`, :math:`{Wc}_{i,j}` *– weight
+    :math:`{Wa}_{i,j}`, :math:`{Wb}_{i,j}`, :math:`{Wc}_{i,j}` *- weight
     of* :math:`j_{th}\ `\ *input element for*
     :math:`i_{th}` *neuron in one of input weights tensors. These
     weights tensors might be input-to-a-gate weights, output-to-a-gate
     weights or any other tensor depending on RNN Cell architecture*
 
-    :math:`y_{i}` *– output of* :math:`i_{th}` neuron
+    :math:`y_{i}` *- output of* :math:`i_{th}` neuron
     ( :math:`i_{th}` *value in output tensor).*
 
-    :math:`b_{i}` *– bias for* :math:`i_{th}` *neuron*
+    :math:`b_{i}` *- bias for* :math:`i_{th}` *neuron*
 
 This is a MAC-based kernel which implies accumulation. See :ref:`quant_accum_infl` for more information on related quantization aspects. 
 The number of accumulation series is equal to total number of values in all inputs.

doc/documents/utility_functions/util_help_func.rst

@@ -13,9 +13,10 @@ getting information from data structures and performing various operations on th
  - :ref:`get_shift_val`
 
  - :ref:`get_zero_offset_val`
- 
- - :ref:`point_sub_tensor`
- 
+
+..
+   - :ref:`point_sub_tensor`
+
  - :ref:`num_of_accu_bits`
 
 
@@ -146,8 +147,8 @@ Get Scale Shift Value
 ~~~~~~~~~~~~~~~~~~~~~
 
 This function returns the shift value from the quantization parameters. 
-For data formats that don’t have a shift value, the value 0 is returned.
-For tensors with multiple scale values per-axis, the parameter``scale_idx`` 
+For data formats that don't have a shift value, the value 0 is returned.
+For tensors with multiple scale values per-axis, the parameter ``scale_idx`` 
 defines the particular scale shift value to be fetched.
 
 Function prototype
@@ -223,79 +224,86 @@ Conditions:
  - zero_idx must be less or equal to number of zero offset values in the tensor
 
 .. _point_sub_tensor:
- 
-Point to Sub-Tensor
-~~~~~~~~~~~~~~~~~~~
-
-This function points to sub tensors in the input tensor. This function can 
-be considered as indexing in a multidimensional array without copying or 
-used to create a slice/fragment of the input tensor without copying the data.
 
-For example, given a HWC tensor, this function could be used to create a HWC 
-tensor for the top half of the HW image for all channels.
-
-The configuration struct is defined as follows and the fields are explained in 
-Table :ref:`t_mli_sub_tensor_cfg_desc`.
-
-.. code:: c
-
-   typedef struct {
-     uint32_t offset[MLI_MAX_RANK];
-     uint32_t size[MLI_MAX_RANK];
-     uint32_t sub_tensor_rank;
-   } mli_sub_tensor_cfg;
 ..
-
-.. _t_mli_sub_tensor_cfg_desc:
-.. table:: mli_sub_tensor_cfg Structure Field Description
-   :align: center
-   :widths: auto
+   Point to Sub-Tensor
+   ~~~~~~~~~~~~~~~~~~~
+
+   .. warning::
+
+      The interface of this function is subject to change. Avoid using it.
+
+   ..
+
+   This function points to sub tensors in the input tensor. This function can 
+   be considered as indexing in a multidimensional array without copying or 
+   used to create a slice/fragment of the input tensor without copying the data.
+
+   For example, given a HWC tensor, this function could be used to create a HWC 
+   tensor for the top half of the HW image for all channels.
+
+   The configuration struct is defined as follows and the fields are explained in 
+   Table :ref:`t_mli_sub_tensor_cfg_desc`.
+
+   .. code:: c
+
+      typedef struct {
+      uint32_t offset[MLI_MAX_RANK];
+      uint32_t size[MLI_MAX_RANK];
+      uint32_t sub_tensor_rank;
+      } mli_sub_tensor_cfg;
+   ..
+
+   .. _t_mli_sub_tensor_cfg_desc:
+   .. table:: mli_sub_tensor_cfg Structure Field Description
+      :align: center
+      :widths: auto
+      
+      +---------------------+----------------+---------------------------------------------------------+
+      | **Field Name**      | **Type**       | Description                                             |
+      +=====================+================+=========================================================+
+      |                     |                | Start coordinate in the input tensor. Values must       |
+      | ``offset``          | ``uint32_t[]`` | be smaller than the shape of the input tensor. Size     |
+      |                     |                | of the array must be equal to the rank of the input     |
+      |                     |                | tensor.                                                 |
+      +---------------------+----------------+---------------------------------------------------------+
+      |                     |                | Size of the sub tensor in elements per dimension:       |
+      | ``size``            | ``uint32_t[]`` |                                                         |
+      |                     |                | Restrictions:  Size[d] +   offset[d] <= input->shape[d] |
+      +---------------------+----------------+---------------------------------------------------------+
+      |                     |                | Rank of the sub tensor that is produced. Must be        |
+      |                     |                | smaller or equal to the rank of the input tensor. If    |
+      | ``sub_tensor_rank`` | ``uint32_t``   | the ``sub_tensor_rank`` is smaller than the input rank, |
+      |                     |                | the dimensions with a size of 1 is removed in the       |
+      |                     |                | output shape starting from the first dimension until    |
+      |                     |                | the requested ``sub_tensor_rank`` value is reached.     |
+      +---------------------+----------------+---------------------------------------------------------+ 
+   ..
+
+   This function computes the new data pointer based on the offset vector and it sets 
+   the shape of the output tensor according to the size vector. The ``mem_stride`` fields 
+   are copied from the input to the output, so after this operation, the output tensor might  
+   not be a contiguous block of data.
+
+   The function also reduces the rank of the output tensor if requested by the 
+   configuration. Only the dimensions with a size of 1 can be removed. Data format and 
+   quantization parameters are copied from the input to the output tensor.
+
+   The capacity field of the output is the input capacity decremented with the same 
+   value as that used to increment the data pointer.
+
+   The function prototype:
+
+   .. code:: c
+
+      mli_status mli_hlp_subtensor(
+      const mli_tensor *in,
+      const mli_subtensor_cfg *cfg,
+      mli_tensor *out);
+   ..
    
-   +---------------------+----------------+---------------------------------------------------------+
-   | **Field Name**      | **Type**       | Description                                             |
-   +=====================+================+=========================================================+
-   |                     |                | Start coordinate in the input tensor. Values must       |
-   | ``offset``          | ``uint32_t[]`` | be smaller than the shape of the input tensor. Size     |
-   |                     |                | of the array must be equal to the rank of the input     |
-   |                     |                | tensor.                                                 |
-   +---------------------+----------------+---------------------------------------------------------+
-   |                     |                | Size of the sub tensor in elements per dimension:       |
-   | ``size``            | ``uint32_t[]`` |                                                         |
-   |                     |                | Restrictions:  Size[d] +   offset[d] <= input->shape[d] |
-   +---------------------+----------------+---------------------------------------------------------+
-   |                     |                | Rank of the sub tensor that is produced. Must be        |
-   |                     |                | smaller or equal to the rank of the input tensor. If    |
-   | ``sub_tensor_rank`` | ``uint32_t``   | the ``sub_tensor_rank`` is smaller than the input rank, |
-   |                     |                | the dimensions with a size of 1 is removed in the       |
-   |                     |                | output shape starting from the first dimension until    |
-   |                     |                | the requested ``sub_tensor_rank`` value is reached.     |
-   +---------------------+----------------+---------------------------------------------------------+ 
-..
-
-This function computes the new data pointer based on the offset vector and it sets 
-the shape of the output tensor according to the size vector. The ``mem_stride`` fields 
-are copied from the input to the output, so after this operation, the output tensor might  
-not be a contiguous block of data.
-
-The function also reduces the rank of the output tensor if requested by the 
-configuration. Only the dimensions with a size of 1 can be removed. Data format and 
-quantization parameters are copied from the input to the output tensor.
-
-The capacity field of the output is the input capacity decremented with the same 
-value as that used to increment the data pointer.
-
-The function prototype:
-
-.. code:: c
-
-   mli_status mli_hlp_subtensor(
-     const mli_tensor *in,
-     const mli_subtensor_cfg *cfg,
-     mli_tensor *out);
-..
- 
-Depending on the debug level (see section :ref:`err_codes`), this function performs a parameter 
-check and returns the result as an ``mli_status`` code as described in section :ref:`kernl_sp_conf`.
+   Depending on the debug level (see section :ref:`err_codes`), this function performs a parameter 
+   check and returns the result as an ``mli_status`` code as described in section :ref:`kernl_sp_conf`.
 
 
 .. _num_of_accu_bits: