Compute Library
 22.05
CLUtils.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2020-2021 Arm Limited.
3  *
4  * SPDX-License-Identifier: MIT
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a copy
7  * of this software and associated documentation files (the "Software"), to
8  * deal in the Software without restriction, including without limitation the
9  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10  * sell copies of the Software, and to permit persons to whom the Software is
11  * furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included in all
14  * copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22  * SOFTWARE.
23  */
24 
25 #ifndef ARM_COMPUTE_CL_CLUTILS_H
26 #define ARM_COMPUTE_CL_CLUTILS_H
27 
30 
31 namespace arm_compute
32 {
33 class TensorShape;
34 class CLBuildOptions;
35 class ITensorInfo;
36 
37 /** Create a cl::Image2D object from an OpenCL buffer
38  *
39  * @note The following conditions are required to create a OpenCL image object from OpenCL buffer,
40  * -# The platform should support the OpenCL cl_khr_image2d_from_buffer extension
41  * -# The stride Y for the input1 should satisfy the OpenCL pitch alignment requirement
42  * -# input width should be less or equal to (CL_DEVICE_IMAGE2D_MAX_WIDTH * 4)
43  * -# input height should be less or equal to CL_DEVICE_IMAGE2D_MAX_HEIGHT
44  *
45  * It is user responsibility to ensure the above conditions are satisfied since no checks are performed within this function
46  *
47  * @param[in] ctx cl::Context object
48  * @param[in] buffer cl::Buffer object from which the OpenCL image2d object is created
49  * @param[in] shape2d 2D tensor shape
50  * @param[in] data_type DataType to use. Only supported: F32,F16
51  * @param[in] image_row_pitch Image row pitch (a.k.a. stride Y) to be used in the image2d object
52  *
53  * @return cl::Image2D object
54  */
55 cl::Image2D create_image2d_from_buffer(const cl::Context &ctx, const cl::Buffer &buffer, const TensorShape &shape2d, DataType data_type, size_t image_row_pitch);
56 
57 namespace experimental
58 {
59 /** @name (EXPERIMENTAL_POST_OPS)
60  * @{
61  */
62 
63 /** Manage validation, building and configurations of PostOp CL kernels */
65 {
66 public:
67  /** CL kernel name postfix for post ops */
68  using NamePostfix = std::string;
69  /** CL kernels that supports post ops assign each post op to a 'slot', in accordance with the postfix
70  * For example, for a kernel with postfix '_act_prelu_eltwiseadd', there are 3 slots
71  * slot 1: (unary) activation, slot 2: pRelu, slot 3: elementwise addition
72  *
73  * Some kernels may allow some slots to be optional, to support multiple combinations of post op sequences.
74  * In such cases, we need to explicitly set up a mapping between each post op and the slots for that kernel.
75  * For example, suppose we have 2 kernels with postfixes: _eltwiseadd_prelu, _act_eltwiseadd_act_prelu, where the activations in the
76  * second kernel are optional. Say we want to support an eltwise addition, followed by a prelu (sequence { eltwiseadd, prelu }).
77  * Now we can choose which one of the 2 kernels to use, since they both support this post op sequence.
78  * We can either:
79  * 1. assign the elementwise to slot 1 and prelu to slot 2 of kernel 1
80  * { { Eltwise_Add, PRelu } -> {"_eltwise_act", {1, 2} } } or
81  * 2. assign the elementwise to slot 2 and prelu to slot 4 of kernel 1
82  * { { Eltwise_Add, PRelu } -> {"_act_eltwiseadd_act_prelu", {2, 4} } }
83  */
84  using Slots = std::vector<unsigned int>;
85  using Config = std::map<PostOpTypeSequence, std::tuple<NamePostfix, Slots>>;
86 
87 public:
88  explicit PostOpCLKernelUtils(const Config &config);
89 
90  /** Check if post op argument tensor shapes are compliant
91  * All post ops must not alter the shape of the original dst tensor (even after broadcasting)
92  *
93  * @param[in] dst Dst tensor to apply the post ops to
94  * @param[in] post_ops Post ops
95  *
96  * @return true if shapes are compliant and false otherwise
97  */
99  /** Check if the post op sequence is supported in the current configuration
100  *
101  * @param[in] post_ops Post ops
102  *
103  * @return true if the post op sequence is supported and false otherwise
104  */
106  /** Helper function to set PostOp related build options
107  * @note Convention
108  * 1. Each post op "slot" is prefixed with "P<slot number>", followed by the usual parameters for that post op.
109  * E.g. If the first slot is an activation, we need to pass 3 definitions in this way:
110  * -P1_ACTIVATION_TYPE=... -P1_ACTIVATION_A_VAL=... -P1_ACTIVATION_B_VAL=...
111  *
112  * 2. For multi-ary post ops, to pass the position of the previous op's dest tensor,
113  * we append "_X_POS_<pos>" to the post op type.
114  * E.g. for a single post op add(dst, x), where dst is the result of the main op.
115  * In this case, the position of the previous op's dest is 0, so we pass
116  * -P1_ELTWISE_OP=ADD_X_POS_0
117  *
118  * @param[out] built_opts OpenCL kernel build options
119  * @param[in] post_ops Post ops
120  *
121  */
123  /** Helper function to set PostOp kernel name
124  *
125  * @param[out] kernel_name OpenCL kernel name
126  * @param[in] post_ops Post ops
127  *
128  */
130 
131 private:
132  Config _supported_config{};
133 };
134 /** @} */ // end of group (EXPERIMENTAL_POST_OPS)
135 
136 } // namespace experimental
137 
138 } // arm_compute
139 
140 #endif /* ARM_COMPUTE_CL_CLUTILS_H */
experimental::PostOpList< ITensorInfo * > post_ops
bool is_post_op_sequence_supported(const PostOpList< ITensorInfo *> &post_ops) const
Check if the post op sequence is supported in the current configuration.
Definition: CLUtils.cpp:111
Store the tensor&#39;s metadata.
Definition: ITensorInfo.h:40
Copyright (c) 2017-2022 Arm Limited.
std::string NamePostfix
CL kernel name postfix for post ops.
Definition: CLUtils.h:68
void set_post_ops_cl_kernel_name(std::string &kernel_name, const PostOpList< ITensorInfo *> &post_ops) const
Helper function to set PostOp kernel name.
Definition: CLUtils.cpp:171
PostOpCLKernelUtils(const Config &config)
Definition: CLUtils.cpp:74
void set_post_ops_cl_build_options(CLBuildOptions &built_opts, const PostOpList< ITensorInfo *> &post_ops) const
Helper function to set PostOp related build options.
Definition: CLUtils.cpp:122
static bool are_post_op_shapes_compliant(const ITensorInfo *dst, const experimental::PostOpList< ITensorInfo *> &post_ops)
Check if post op argument tensor shapes are compliant All post ops must not alter the shape of the or...
Definition: CLUtils.cpp:86
std::map< PostOpTypeSequence, std::tuple< NamePostfix, Slots > > Config
Definition: CLUtils.h:85
Manage validation, building and configurations of PostOp CL kernels.
Definition: CLUtils.h:64
Wrapper to configure the Khronos OpenCL C++ header.
cl::Image2D create_image2d_from_buffer(const cl::Context &ctx, const cl::Buffer &buffer, const TensorShape &shape2d, DataType data_type, size_t image_row_pitch)
Create a cl::Image2D object from an OpenCL buffer.
Definition: CLUtils.cpp:35
std::vector< unsigned int > Slots
CL kernels that supports post ops assign each post op to a &#39;slot&#39;, in accordance with the postfix For...
Definition: CLUtils.h:84
std::string kernel_name
DataType
Available data types.
Definition: Types.h:79
A sequence of PostOps that can be appended to the end of other operators.
Definition: IPostOp.h:119