COMPMID-2042: Extend the documentation of the configurable GEMM on OpenCL

Change-Id: I67a08492a632ba7d91e0979053334ddbd2264050
Signed-off-by: Manuel Bottini <manuel.bottini@arm.com>
Reviewed-on: https://review.mlplatform.org/c/915
Reviewed-by: Gian Marco Iodice <gianmarco.iodice@arm.com>
Comments-Addressed: Arm Jenkins <bsgcomp@arm.com>
Tested-by: Arm Jenkins <bsgcomp@arm.com>

4 files changed, 76 insertions, 36 deletions

diff --git a/arm_compute/core/CL/kernels/CLGEMMLowpMatrixMultiplyReshapedKernel.h b/arm_compute/core/CL/kernels/CLGEMMLowpMatrixMultiplyReshapedKernel.h
index d361236380..139f7ab0a8 100644
--- a/arm_compute/core/CL/kernels/CLGEMMLowpMatrixMultiplyReshapedKernel.h
+++ b/arm_compute/core/CL/kernels/CLGEMMLowpMatrixMultiplyReshapedKernel.h
@@ -49,23 +49,39 @@ public:
     CLGEMMLowpMatrixMultiplyReshapedKernel &operator=(CLGEMMLowpMatrixMultiplyReshapedKernel &&) = default;
     /** Initialise the kernel's input and output.
      *
-     * @param[in]  input0    Input tensor containing the LHS reshaped matrix. Data type supported: QASYMM8
-     * @param[in]  input1    Input tensor containing the RHS reshaped matrix. Data type supported: same as @p input0
+     * @param[in]  input0    Input tensor containing the LHS reshaped matrix. Data type supported: QASYMM8. The number of dimensions for the LHS matrix must be less or equal than 4.
+     * @param[in]  input1    Input tensor containing the RHS reshaped matrix. Data type supported: same as @p input0. The number of dimensions for the RHS matrix must be less or equal than 3.
      * @param[out] output    Output tensor to store the result of matrix multiplication. Data type supported: same as @p input0
-     * @param[in]  lhs_info  LHS matrix information used for reshaping the input0 tensor
-     * @param[in]  rhs_info  RHS matrix information used for reshaping the input1 tensor
+     * @param[in]  lhs_info  LHS matrix information used for reshaping the input0 tensor.  Only the following values are supported:
+     *                       lhs_info.m0: 2,3,4,5,6,7,8
+     *                       lhs_info.k0: 2,3,4,8,16
+     *                       lhs_info.transpose: false
+     * @param[in]  rhs_info  RHS matrix information used for reshaping the input1 tensor.  Only the following values are supported:
+     *                       rhs_info.n0: 2,3,4,8,16
+     *                       rhs_info.k0: 2,3,4,8,16
+     *                       rhs_info.transpose: true
      * @param[in]  gemm_info GEMM information used to retrieve the original dimensions of the input matrices
+     *
+     * @note lhs_info.k0 must be equal to rhs_info.k0
      */
     void configure(const ICLTensor *input0, const ICLTensor *input1, ICLTensor *output, const GEMMLHSMatrixInfo &lhs_info, const GEMMRHSMatrixInfo &rhs_info, const GEMMReshapeInfo &gemm_info);
     /** Static function to check if given info will lead to a valid configuration of @ref CLGEMMLowpMatrixMultiplyReshapedKernel
      *
-     * @param[in] input0    Input tensor info containing the LHS reshaped matrix. Data type supported: QASYMM8
-     * @param[in] input1    Input tensor info containing the RHS reshaped matrix. Data type supported: same as @p input0
+     * @param[in] input0    Input tensor info containing the LHS reshaped matrix. Data type supported: QASYMM8. The number of dimensions for the LHS matrix must be less or equal than 4.
+     * @param[in] input1    Input tensor info containing the RHS reshaped matrix. Data type supported: same as @p input0. The number of dimensions for the RHS matrix must be less or equal than 3.
      * @param[in] output    Output tensor info. Data type supported: same as @p input0
-     * @param[in] lhs_info  LHS matrix information used for reshaping the input0 tensor
-     * @param[in] rhs_info  RHS matrix information used for reshaping the input1 tensor
+     * @param[in] lhs_info  LHS matrix information used for reshaping the input0 tensor.  Only the following values are supported:
+     *                      lhs_info.m0: 2,3,4,5,6,7,8
+     *                      lhs_info.k0: 2,3,4,8,16
+     *                      lhs_info.transpose: false
+     * @param[in] rhs_info  RHS matrix information used for reshaping the input1 tensor.  Only the following values are supported:
+     *                      rhs_info.n0: 2,3,4,8,16
+     *                      rhs_info.k0: 2,3,4,8,16
+     *                      rhs_info.transpose: true
      * @param[in] gemm_info GEMM information used to retrieve the original dimensions of the input matrices
      *
+     * @note lhs_info.k0 must be equal to rhs_info.k0
+     *
      * @return a status
      */
     static Status validate(const ITensorInfo *input0, const ITensorInfo *input1, const ITensorInfo *output, const GEMMLHSMatrixInfo &lhs_info, const GEMMRHSMatrixInfo &rhs_info,
diff --git a/arm_compute/core/CL/kernels/CLGEMMMatrixMultiplyReshapedKernel.h b/arm_compute/core/CL/kernels/CLGEMMMatrixMultiplyReshapedKernel.h
index b0d245f342..4052a09162 100644
--- a/arm_compute/core/CL/kernels/CLGEMMMatrixMultiplyReshapedKernel.h
+++ b/arm_compute/core/CL/kernels/CLGEMMMatrixMultiplyReshapedKernel.h
@@ -49,26 +49,42 @@ public:
     CLGEMMMatrixMultiplyReshapedKernel &operator=(CLGEMMMatrixMultiplyReshapedKernel &&) = default;
     /** Initialise the kernel's input and output.
      *
-     * @param[in]  input0    Input tensor containing the LHS reshaped matrix. Data type supported: F32/F16
-     * @param[in]  input1    Input tensor containing the RHS reshaped matrix. Data type supported: same as @p input0
+     * @param[in]  input0    Input tensor containing the LHS reshaped matrix. Data type supported: F32/F16. The number of dimensions for the LHS matrix must be less or equal than 4
+     * @param[in]  input1    Input tensor containing the RHS reshaped matrix. Data type supported: same as @p input0. The number of dimensions for the RHS matrix must be less or equal than 3
      * @param[out] output    Output tensor to store the result of matrix multiplication. Data type supported: same as @p input0
      * @param[in]  alpha     Weight of the matrix product
-     * @param[in]  lhs_info  LHS matrix information used for reshaping the input0 tensor
-     * @param[in]  rhs_info  RHS matrix information used for reshaping the input1 tensor
+     * @param[in]  lhs_info  LHS matrix information used for reshaping the input0 tensor.  Only the following values are supported:
+     *                       lhs_info.m0: 2,3,4,5,6,7,8
+     *                       lhs_info.k0: 2,3,4,8,16
+     *                       lhs_info.transpose: false
+     * @param[in]  rhs_info  RHS matrix information used for reshaping the input1 tensor.  Only the following values are supported:
+     *                       rhs_info.n0: 2,3,4,8,16
+     *                       rhs_info.k0: 2,3,4,8,16
+     *                       rhs_info.transpose: true
      * @param[in]  gemm_info GEMM information used to retrieve the original dimensions of the input matrices
+     *
+     * @note lhs_info.k0 must be equal to rhs_info.k0
      */
     void configure(const ICLTensor *input0, const ICLTensor *input1, ICLTensor *output, float alpha, const GEMMLHSMatrixInfo &lhs_info, const GEMMRHSMatrixInfo &rhs_info,
                    const GEMMReshapeInfo &gemm_info);
     /** Static function to check if given info will lead to a valid configuration of @ref CLGEMMMatrixMultiplyReshapedKernel
      *
-     * @param[in] input0    Input tensor containing the LHS reshaped matrix. Data type supported: F32/F16
-     * @param[in] input1    Input tensor containing the RHS reshaped matrix. Data type supported: same as @p input0
+     * @param[in] input0    Input tensor containing the LHS reshaped matrix. Data type supported: F32/F16. The number of dimensions for the LHS matrix must be less or equal than 4
+     * @param[in] input1    Input tensor containing the RHS reshaped matrix. Data type supported: same as @p input0. The number of dimensions for the RHS matrix must be less or equal than 3
      * @param[in] output    Output tensor to store the result of matrix multiplication. Data type supported: same as @p input0
      * @param[in] alpha     Weight of the matrix product
-     * @param[in] lhs_info  LHS matrix information used for reshaping the input0 tensor
-     * @param[in] rhs_info  RHS matrix information used for reshaping the input1 tensor
+     * @param[in] lhs_info  LHS matrix information used for reshaping the input0 tensor.  Only the following values are supported:
+     *                      lhs_info.m0: 2,3,4,5,6,7,8
+     *                      lhs_info.k0: 2,3,4,8,16
+     *                      lhs_info.transpose: false
+     * @param[in] rhs_info  RHS matrix information used for reshaping the input1 tensor.  Only the following values are supported:
+     *                      rhs_info.n0: 2,3,4,8,16
+     *                      rhs_info.k0: 2,3,4,8,16
+     *                      rhs_info.transpose: true
      * @param[in] gemm_info GEMM information used to retrieve the original dimensions of the input matrices
      *
+     * @note lhs_info.k0 must be equal to rhs_info.k0
+     *
      * @return a status
      */
     static Status validate(const ITensorInfo *input0, const ITensorInfo *input1, const ITensorInfo *output, float alpha, const GEMMLHSMatrixInfo &lhs_info, const GEMMRHSMatrixInfo &rhs_info,
diff --git a/arm_compute/core/CL/kernels/CLGEMMMatrixMultiplyReshapedOnlyRHSKernel.h b/arm_compute/core/CL/kernels/CLGEMMMatrixMultiplyReshapedOnlyRHSKernel.h
index b3ee43555a..26a1378d27 100644
--- a/arm_compute/core/CL/kernels/CLGEMMMatrixMultiplyReshapedOnlyRHSKernel.h
+++ b/arm_compute/core/CL/kernels/CLGEMMMatrixMultiplyReshapedOnlyRHSKernel.h
@@ -49,24 +49,32 @@ public:
     CLGEMMMatrixMultiplyReshapedOnlyRHSKernel &operator=(CLGEMMMatrixMultiplyReshapedOnlyRHSKernel &&) = default;
     /** Initialise the kernel's input and output.
      *
-     * @param[in]  input0    Input tensor containing the LHS matrix. Data type supported: F32/F16
-     * @param[in]  input1    Input tensor containing the RHS reshaped matrix. Data type supported: same as @p input0
+     * @param[in]  input0    Input tensor containing the LHS matrix. Data type supported: F32/F16. The number of dimensions for the LHS matrix must be less or equal than 4.
+     * @param[in]  input1    Input tensor containing the RHS reshaped matrix. Data type supported: same as @p input0. The number of dimensions for the RHS matrix must be less or equal than 3.
      * @param[out] output    Output tensor to store the result of matrix multiplication. Data type supported: same as @p input0
      * @param[in]  alpha     Weight of the matrix product
-     * @param[in]  lhs_info  LHS matrix information used to retrieve the number of rows to be processed by each thread
-     * @param[in]  rhs_info  RHS matrix information used for reshaping the input1 tensor
+     * @param[in]  lhs_info  LHS matrix information used to retrieve the number of rows to be processed by each thread. Only the following values are supported:
+     *                       lhs_info.m0: 1,2,3,4,5,6,7,8
+     * @param[in]  rhs_info  RHS matrix information used for reshaping the input1 tensor.  Only the following values are supported:
+     *                       rhs_info.k0: 2,3,4,8,16
+     *                       rhs_info.n0: 2,3,4,8,16
+     *                       rhs_info.transpose: true,false
      * @param[in]  gemm_info GEMM information used to retrieve the original dimensions of the input matrices
      */
     void configure(const ICLTensor *input0, const ICLTensor *input1, ICLTensor *output, float alpha, const GEMMLHSMatrixInfo &lhs_info, const GEMMRHSMatrixInfo &rhs_info,
                    const GEMMReshapeInfo &gemm_info);
     /** Static function to check if given info will lead to a valid configuration of @ref CLGEMMMatrixMultiplyReshapedOnlyRHSKernel
      *
-     * @param[in] input0    Input tensor info for the LHS matrix. Data type supported: F32/F16
-     * @param[in] input1    Input tensor info for the RHS reshaped matrix. Data type supported: same as @p input0
+     * @param[in] input0    Input tensor info for the LHS matrix. Data type supported: F32/F16. The number of dimensions for the LHS matrix must be less or equal than 4.
+     * @param[in] input1    Input tensor info for the RHS reshaped matrix. Data type supported: same as @p input0. The number of dimensions for the RHS matrix must be less or equal than 3.
      * @param[in] output    Output tensor info. Data type supported: same as @p input0
      * @param[in] alpha     Weight of the matrix product
-     * @param[in] lhs_info  LHS matrix information used to retrieve the number of rows to be processed by each thread
-     * @param[in] rhs_info  RHS matrix information used for reshaping the input1 tensor
+     * @param[in] lhs_info  LHS matrix information used to retrieve the number of rows to be processed by each thread. Only the following values are supported:
+     *                      lhs_info.m0: 1,2,3,4,5,6,7,8
+     * @param[in] rhs_info  RHS matrix information used for reshaping the input1 tensor.  Only the following values are supported:
+     *                      rhs_info.k0: 2,3,4,8,16
+     *                      rhs_info.n0: 2,3,4,8,16
+     *                      rhs_info.transpose: true,false
      * @param[in] gemm_info GEMM information used to retrieve the original dimensions of the input matrices
      *
      * @return a status
diff --git a/arm_compute/core/CL/kernels/CLGEMMReshapeRHSMatrixKernel.h b/arm_compute/core/CL/kernels/CLGEMMReshapeRHSMatrixKernel.h
index 55e37867b9..26ab210b21 100644
--- a/arm_compute/core/CL/kernels/CLGEMMReshapeRHSMatrixKernel.h
+++ b/arm_compute/core/CL/kernels/CLGEMMReshapeRHSMatrixKernel.h
@@ -51,12 +51,12 @@ public:
      * @param[in]  input    Input tensor. Data types supported: U8/S8/QASYMM8/U16/S16/F16/U32/S32/F32
      * @param[out] output   Output tensor. Data type supported: same as @p input
      * @param[in]  rhs_info RHS matrix information to be used for reshaping. This object contains all the necessary
-     *                                      information to reshape the input tensor. Only the following values are supported:
-     *                                      rhs_info.n0: 2,3,4,8,16
-     *                                      rhs_info.k0: 1,2,3,4,8,16 (k0 = 1 only if rhs_info.transpose = false)
-     *                                      rhs_info.h0: greater than 0
-     *                                      rhs_info.transpose: true, false
-     *                                      rhs_info.interleave: true, false
+     *                      information to reshape the input tensor. Only the following values are supported:
+     *                      rhs_info.n0: 2,3,4,8,16
+     *                      rhs_info.k0: 1,2,3,4,8,16 (k0 = 1 only if rhs_info.transpose = false)
+     *                      rhs_info.h0: greater than 0
+     *                      rhs_info.transpose: true, false
+     *                      rhs_info.interleave: true, false
      */
     void configure(const ICLTensor *input, ICLTensor *output, const GEMMRHSMatrixInfo &rhs_info);
     /** Static function to check if given info will lead to a valid configuration of @ref CLGEMMReshapeRHSMatrixKernel
@@ -64,12 +64,12 @@ public:
      * @param[in] input    Input tensor info. Data types supported: U8/S8/QASYMM8/U16/S16/F16/U32/S32/F32
      * @param[in] output   Output tensor info which stores the interleaved matrix. Data type supported: same as @p input.
      * @param[in] rhs_info RHS matrix information to be used for reshaping. This object contains all the necessary
-     *                                      information to reshape the input tensor. Only the following values are supported:
-     *                                      rhs_info.n0: 2,3,4,8,16
-     *                                      rhs_info.k0: 1,2,3,4,8,16 (k0 = 1 only if rhs_info.transpose = false)
-     *                                      rhs_info.h0: greater than 0
-     *                                      rhs_info.transpose: true, false
-     *                                      rhs_info.interleave: true, false
+     *                     information to reshape the input tensor. Only the following values are supported:
+     *                     rhs_info.n0: 2,3,4,8,16
+     *                     rhs_info.k0: 1,2,3,4,8,16 (k0 = 1 only if rhs_info.transpose = false)
+     *                     rhs_info.h0: greater than 0
+     *                     rhs_info.transpose: true, false
+     *                     rhs_info.interleave: true, false
      *
      * @return a status
      */