Add basic Operator interface

- C facing interfaces
- Activation layer descriptor

Partially Resolves: COMPMID-4512

Signed-off-by: Georgios Pinitas <georgios.pinitas@arm.com>
Change-Id: I8530748fff178ca46d61bf2e40d3e543e93f340b
Reviewed-on: https://review.mlplatform.org/c/ml/ComputeLibrary/+/5908
Tested-by: Arm Jenkins <bsgcomp@arm.com>
Reviewed-by: Michele Di Giorgio <michele.digiorgio@arm.com>
Comments-Addressed: Arm Jenkins <bsgcomp@arm.com>

9 files changed, 220 insertions, 15 deletions

diff --git a/arm_compute/Acl.h b/arm_compute/Acl.h
index 316407c02e..1cd45d5756 100644
--- a/arm_compute/Acl.h
+++ b/arm_compute/Acl.h
@@ -34,6 +34,10 @@ extern "C" {
 #include "arm_compute/AclUtils.h"
 #include "arm_compute/AclVersion.h"
 
+/* Operator headers */
+#include "arm_compute/AclDescriptors.h"
+#include "arm_compute/AclOperators.h"
+
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
diff --git a/arm_compute/Acl.hpp b/arm_compute/Acl.hpp
index 93ac2d8ed9..7791c5633e 100644
--- a/arm_compute/Acl.hpp
+++ b/arm_compute/Acl.hpp
@@ -749,6 +749,30 @@ public:
         return detail::as_enum<StatusCode>(AclPackTensors(_object.get(), tensors.data(), slots.data(), size));
     }
 };
+
+/** Operator class
+ *
+ * Operators are the basic algorithmic blocks responsible for performing distinct operations
+ */
+class Operator : public detail::ObjectBase<AclOperator_>
+{
+public:
+    /** Run an operator on a given input list
+     *
+     * @param[in,out] queue Queue to scheduler the operator on
+     * @param pack  Tensor list to be used as input
+     *
+     * @return Status Code
+     */
+    StatusCode run(Queue &queue, TensorPack &pack)
+    {
+        return detail::as_cenum<StatusCode>(AclRunOperator(_object.get(), queue.get(), pack.get()));
+    }
+
+protected:
+    /** Constructor */
+    Operator() = default;
+};
 } // namespace acl
 #undef ARM_COMPUTE_IGNORE_UNUSED
 #endif /* ARM_COMPUTE_ACL_HPP_ */
diff --git a/arm_compute/AclDescriptors.h b/arm_compute/AclDescriptors.h
new file mode 100644
index 0000000000..7b7655e9c7
--- /dev/null
+++ b/arm_compute/AclDescriptors.h
@@ -0,0 +1,61 @@
+/*
+ * Copyright (c) 2021 Arm Limited.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+#ifndef ARM_COMPUTE_ACL_DESCRIPTORS_H_
+#define ARM_COMPUTE_ACL_DESCRIPTORS_H_
+
+#ifdef __cplusplus
+extern "C" {
+#endif /** __cplusplus */
+
+/**< Supported activation types */
+typedef enum
+{
+    AclActivationTypeNone = 0,  /**< No activation */
+    AclIdentity           = 1,  /**< Identity */
+    AclLogistic           = 2,  /**< Logistic */
+    AclTanh               = 3,  /**< Hyperbolic tangent */
+    AclRelu               = 4,  /**< Rectifier */
+    AclBoundedRelu        = 5,  /**< Upper Bounded Rectifier */
+    AclLuBoundedRelu      = 6,  /**< Lower and Upper Bounded Rectifier */
+    AclLeakyRelu          = 7,  /**< Leaky Rectifier */
+    AclSoftRelu           = 8,  /**< Soft Rectifier */
+    AclSoftElu            = 9,  /**< Exponential Linear Unit */
+    AclAbs                = 10, /**< Absolute */
+    AclSquare             = 11, /**< Square */
+    AclSqrt               = 12, /**< Square root */
+    AclLinear             = 13, /**< Linear */
+    AclHardSwish          = 14, /**< Hard-swish */
+} AclActivationType;
+
+/**< Activation layer descriptor */
+typedef struct
+{
+    AclActivationType type; /**< Activation type */
+    float             a;    /**< Factor &alpha used by some activations */
+    float             b;    /**< Factor &beta used by some activations */
+} AclActivationDescriptor;
+#ifdef __cplusplus
+}
+#endif /** __cplusplus */
+#endif /* ARM_COMPUTE_ACL_DESCRIPTORS_H_ */
diff --git a/arm_compute/AclEntrypoints.h b/arm_compute/AclEntrypoints.h
index cf4a237a44..ca3a911f5d 100644
--- a/arm_compute/AclEntrypoints.h
+++ b/arm_compute/AclEntrypoints.h
@@ -21,8 +21,8 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-#ifndef ARM_COMPUTE_ACLENTRYPOINTS_H_
-#define ARM_COMPUTE_ACLENTRYPOINTS_H_
+#ifndef ARM_COMPUTE_ACL_ENTRYPOINTS_H_
+#define ARM_COMPUTE_ACL_ENTRYPOINTS_H_
 
 #include "arm_compute/AclTypes.h"
 
@@ -232,7 +232,35 @@ AclStatus AclPackTensors(AclTensorPack pack, AclTensor *tensors, int32_t *slot_i
  */
 AclStatus AclDestroyTensorPack(AclTensorPack pack);
 
+/** Eager execution of a given operator on a list of inputs and outputs
+ *
+ * @param[in]     op      Operator to execute
+ * @param[in]     queue   Queue to schedule the operator on
+ * @param[in,out] tensors A list of input and outputs tensors to execute the operator on
+ *
+ * @return Status Code
+ *
+ * Returns:
+ *  - @ref AclSuccess if function was completed successfully
+ *  - @ref AclOutOfMemory if there was a failure allocating memory resources
+ *  - @ref AclUnsupportedTarget if the requested target is unsupported
+ *  - @ref AclInvalidArgument if a given argument is invalid
+ *  - @ref AclRuntimeError on any other runtime related error
+ */
+AclStatus AclRunOperator(AclOperator op, AclQueue queue, AclTensorPack tensors);
+
+/** Destroy a given operator object
+ *
+ * @param[in,out] op A valid operator object to destroy
+ *
+ * @return Status code
+ *
+ * Returns:
+ *  - @ref AclSuccess if functions was completed successfully
+ *  - @ref AclInvalidArgument if the provided context is invalid
+ */
+AclStatus AclDestroyOperator(AclOperator op);
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
-#endif /* ARM_COMPUTE_ACLENTRYPOINTS_H_ */
+#endif /* ARM_COMPUTE_ACL_ENTRYPOINTS_H_ */
diff --git a/arm_compute/AclOpenClExt.h b/arm_compute/AclOpenClExt.h
index b9080dabf2..c349f76d86 100644
--- a/arm_compute/AclOpenClExt.h
+++ b/arm_compute/AclOpenClExt.h
@@ -21,8 +21,8 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-#ifndef ARM_COMPUTE_ACLOPENCLEXT_H_
-#define ARM_COMPUTE_ACLOPENCLEXT_H_
+#ifndef ARM_COMPUTE_ACL_OPENCL_EXT_H_
+#define ARM_COMPUTE_ACL_OPENCL_EXT_H_
 
 #include "arm_compute/AclTypes.h"
 
@@ -109,4 +109,4 @@ AclStatus AclGetClMem(AclTensor tensor, cl_mem *opencl_mem);
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
-#endif /* ARM_COMPUTE_ACLOPENCLEXT_H_ */
+#endif /* ARM_COMPUTE_ACL_OPENCL_EXT_H_ */
diff --git a/arm_compute/AclOperators.h b/arm_compute/AclOperators.h
new file mode 100644
index 0000000000..bfdd7b1b9b
--- /dev/null
+++ b/arm_compute/AclOperators.h
@@ -0,0 +1,86 @@
+/*
+ * Copyright (c) 2021 Arm Limited.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+#ifndef ARM_COMPUTE_ACL_OPERATORS_H_
+#define ARM_COMPUTE_ACL_OPERATORS_H_
+
+#include "arm_compute/AclDescriptors.h"
+#include "arm_compute/AclTypes.h"
+
+/** Used during an operator creation to validate its support */
+#define ARM_COMPUTE_VALIDATE_OPERATOR_SUPPORT ((AclOperator *)(size_t)-1)
+
+#ifdef __cplusplus
+extern "C" {
+#endif /** __cplusplus */
+
+/** Create an activation operator
+ *
+ * Applies an activation function to a given tensor .
+ * Compute Library supports a wide list of activation functions @ref AclActivationType.
+ *
+ * A summarized table is the following:
+ *    Activation Function   |                                                    Mathematical Expression                                                               |
+ * -------------------------|------------------------------------------------------------------------------------------------------------------------------------------|
+ *         Identity         |                                                       \f$ f(x)= x \f$                                                                    |
+ *         Logistic         |                                               \f$ f(x) = \frac{1}{1 + e^{-x}} \f$                                                        |
+ *           Tanh           |                                              \f$ f(x) = a \cdot tanh(b \cdot x) \f$                                                      |
+ *           Relu           |                                                   \f$ f(x) = max(0,x) \f$                                                                |
+ *       Bounded Relu       |                                                \f$ f(x) = min(a, max(0,x)) \f$                                                           |
+ * Lower-Upper Bounded Relu |                                                \f$ f(x) = min(a, max(b,x)) \f$                                                           |
+ *        Leaky Relu        |     \f$ f(x) = \begin{cases}  \alpha x & \quad \text{if } x \text{ < 0}\\  x & \quad \text{if } x \geq \text{ 0 } \end{cases} \f$        |
+ *         Soft Relu        |                                                    \f$ f(x)= log(1+e^x) \f$                                                              |
+ *         Soft Elu         | \f$ f(x) = \begin{cases}  \alpha (exp(x) - 1) & \quad \text{if } x \text{ < 0}\\  x & \quad \text{if } x \geq \text{ 0 } \end{cases} \f$ |
+ *           Abs            |                                                      \f$ f(x)= |x| \f$                                                                   |
+ *         Square           |                                                      \f$ f(x)= x^2 \f$                                                                   |
+ *          Sqrt            |                                                   \f$ f(x) = \sqrt{x} \f$                                                                |
+ *         Linear           |                                                    \f$ f(x)= ax + b \f$                                                                  |
+ *       Hard Swish         |                                              \f$ f(x) = (x * relu6(x+3))/6 \f$                                                           |
+ *
+ * Backends:
+ *   - OpenCL: ClActivationLayer
+ *   - Cpu   : CpuActivationLayer
+ *
+ * @param[in, out] op   Operator construct to be created if creation was successful
+ * @param[in]      ctx  Context to be used for the creation of the operator
+ * @param[in]      src  Source tensor descriptor. Slot id: ACL_SRC
+ * @param[in]      dst  Destination tensor descriptor. Slot id: ACL_DST
+ * @param[in]      info Activation meta-data
+ *
+ * @return Status code
+ *
+ * Returns:
+ *  - @ref AclSuccess if function was completed successfully
+ *  - @ref AclOutOfMemory if there was a failure allocating memory resources
+ *  - @ref AclUnsupportedTarget if operator for the requested target is unsupported
+ *  - @ref AclInvalidArgument if a given argument is invalid
+ */
+AclStatus AclActivation(AclOperator                  *op,
+                        AclContext                    ctx,
+                        const AclTensorDescriptor    *src,
+                        const AclTensorDescriptor    *dst,
+                        const AclActivationDescriptor info);
+#ifdef __cplusplus
+}
+#endif /** __cplusplus */
+#endif /* ARM_COMPUTE_ACL_OPERATORS_H_ */
diff --git a/arm_compute/AclTypes.h b/arm_compute/AclTypes.h
index 902a508b91..368be1292b 100644
--- a/arm_compute/AclTypes.h
+++ b/arm_compute/AclTypes.h
@@ -21,8 +21,8 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-#ifndef ARM_COMPUTE_ACLTYPES_H_
-#define ARM_COMPUTE_ACLTYPES_H_
+#ifndef ARM_COMPUTE_ACL_TYPES_H_
+#define ARM_COMPUTE_ACL_TYPES_H_
 
 #include <stddef.h>
 #include <stdint.h>
@@ -39,6 +39,8 @@ typedef struct AclQueue_ *AclQueue;
 typedef struct AclTensor_ *AclTensor;
 /**< Opaque Tensor pack object */
 typedef struct AclTensorPack_ *AclTensorPack;
+/**< Opaque Operator object */
+typedef struct AclOperator_ *AclOperator;
 
 // Capabilities bitfield (Note: if multiple are enabled ComputeLibrary will pick the best possible)
 typedef uint64_t AclTargetCapabilities;
@@ -209,4 +211,4 @@ typedef enum
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
-#endif /* ARM_COMPUTE_ACLTYPES_H_ */
+#endif /* ARM_COMPUTE_ACL_TYPES_H_ */
diff --git a/arm_compute/AclUtils.h b/arm_compute/AclUtils.h
index 2e75772ee8..ef5fa42708 100644
--- a/arm_compute/AclUtils.h
+++ b/arm_compute/AclUtils.h
@@ -21,8 +21,8 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-#ifndef ARM_COMPUTE_ACLUTILS_H_
-#define ARM_COMPUTE_ACLUTILS_H_
+#ifndef ARM_COMPUTE_ACL_UTILS_H_
+#define ARM_COMPUTE_ACL_UTILS_H_
 
 #include "arm_compute/AclTypes.h"
 
@@ -60,4 +60,4 @@ AclStatus AclGetTensorDescriptor(AclTensor tensor, AclTensorDescriptor *desc);
 }
 #endif /* __cplusplus */
 
-#endif /* ARM_COMPUTE_ACLUTILS_H_ */
+#endif /* ARM_COMPUTE_ACL_UTILS_H_ */
diff --git a/arm_compute/AclVersion.h b/arm_compute/AclVersion.h
index 3a2f30791d..0b05a5e7dc 100644
--- a/arm_compute/AclVersion.h
+++ b/arm_compute/AclVersion.h
@@ -21,8 +21,8 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-#ifndef ARM_COMPUTE_ACLVERSION_H_
-#define ARM_COMPUTE_ACLVERSION_H_
+#ifndef ARM_COMPUTE_ACL_VERSION_H_
+#define ARM_COMPUTE_ACL_VERSION_H_
 
 #ifdef __cplusplus
 extern "C" {
@@ -53,4 +53,4 @@ const AclVersion *AclVersionInfo();
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
-#endif /* ARM_COMPUTE_ACLVERSION_H_ */
+#endif /* ARM_COMPUTE_ACL_VERSION_H_ */