Compute Library
 21.05
CLHelpers.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2016-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 #ifndef ARM_COMPUTE_CLHELPERS_H
25 #define ARM_COMPUTE_CLHELPERS_H
26 
29 #include "arm_compute/core/Types.h"
30 
31 #include <set>
32 #include <string>
33 
34 /* CL Device capabilities */
35 #define ARM_COMPUTE_LIBRARY_OPENCL_DEVICE_CAPABILITIES_ARM 0x41E4
36 /* Workgroup Batch Size Modifier */
37 #define ARM_COMPUTE_LIBRARY_OPENCL_EXEC_WBSM_ARM 0x41E6
38 
39 namespace arm_compute
40 {
41 class CLCoreRuntimeContext;
42 class CLCompileContext;
43 class CLBuildOptions;
44 
45 enum class DataType;
46 
47 /** Max vector width of an OpenCL vector */
48 static constexpr unsigned int max_cl_vector_width = 16;
49 
50 /** Translates a tensor data type to the appropriate OpenCL type.
51  *
52  * @param[in] dt @ref DataType to be translated to OpenCL type.
53  *
54  * @return The string specifying the OpenCL type to be used.
55  */
56 std::string get_cl_type_from_data_type(const DataType &dt);
57 
58 /** Translates a tensor data type to the appropriate OpenCL promoted type.
59  *
60  * @param[in] dt @ref DataType to be used to get the promoted OpenCL type.
61  *
62  * @return The string specifying the OpenCL type to be used.
63  */
65 
66 /** Translates the element size to an unsigned integer data type
67  *
68  * @param[in] element_size Size in bytes of an element.
69  *
70  * @return The string specifying the OpenCL type to be used.
71  */
72 std::string get_cl_unsigned_type_from_element_size(size_t element_size);
73 
74 /** Translates the element size to an signed integer data type
75  *
76  * @param[in] element_size Size in bytes of an element.
77  *
78  * @return The string specifying the OpenCL type to be used.
79  */
80 std::string get_cl_signed_type_from_element_size(size_t element_size);
81 
82 /** Translates a tensor data type to the appropriate OpenCL select type.
83  *
84  * @param[in] dt @ref DataType to be translated to OpenCL select type.
85  *
86  * @return The string specifying the OpenCL select type to be used.
87  */
89 
90 /** Translates a tensor data type to the appropriate OpenCL dot8 accumulator type.
91  *
92  * @param[in] dt @ref DataType to be translated to OpenCL dot8 accumulator type.
93  *
94  * @return The string specifying the OpenCL dot8 accumulator type to be used.
95  */
97 
98 /** Get the size of a data type in number of bits.
99  *
100  * @param[in] dt @ref DataType.
101  *
102  * @return Number of bits in the data type specified.
103  */
104 std::string get_data_size_from_data_type(const DataType &dt);
105 
106 /** Helper function to get the GPU target from CL device
107  *
108  * @param[in] device A CL device
109  *
110  * @return the GPU target
111  */
112 GPUTarget get_target_from_device(const cl::Device &device);
113 
114 /** Helper function to get the highest OpenCL version supported
115  *
116  * @param[in] device A CL device
117  *
118  * @return the highest OpenCL version supported
119  */
120 CLVersion get_cl_version(const cl::Device &device);
121 
122 /** Helper function to get the cl_image pitch alignment in pixels
123  *
124  * @param[in] device A CL device
125  *
126  * @return the cl_image pitch alignment in pixels. If an error occurs, the function will return 0
127  */
128 size_t get_cl_image_pitch_alignment(const cl::Device &device);
129 
130 /** Helper function to check whether a given extension is supported
131  *
132  * @param[in] device A CL device
133  * @param[in] extension_name Name of the extension to be checked
134  *
135  * @return True if the extension is supported
136  */
137 bool device_supports_extension(const cl::Device &device, const char *extension_name);
138 
139 /** Helper function to check whether the cl_khr_fp16 extension is supported
140  *
141  * @param[in] device A CL device
142  *
143  * @return True if the extension is supported
144  */
145 bool fp16_supported(const cl::Device &device);
146 /** Helper function to check whether the arm_non_uniform_work_group_size extension is supported
147  *
148  * @param[in] device A CL device
149  *
150  * @return True if the extension is supported
151  */
152 bool arm_non_uniform_workgroup_supported(const cl::Device &device);
153 /** Helper function to check whether the cl_arm_integer_dot_product_int8 extension is supported
154  *
155  * @param[in] device A CL device
156  *
157  * @return True if the extension is supported
158  */
159 bool dot8_supported(const cl::Device &device);
160 
161 /** Helper function to check whether the cl_arm_integer_dot_product_accumulate_int8 extension is supported
162  *
163  * @param[in] device A CL device
164  *
165  * @return True if the extension is supported
166  */
167 bool dot8_acc_supported(const cl::Device &device);
168 
169 /** This function checks if the Winograd configuration (defined through the output tile, kernel size and the data layout) is supported on OpenCL
170  *
171  * @param[in] output_tile Output tile for the Winograd filtering algorithm
172  * @param[in] kernel_size Kernel size for the Winograd filtering algorithm
173  * @param[in] data_layout Data layout of the input tensor
174  *
175  * @return True if the configuration is supported
176  */
177 bool cl_winograd_convolution_layer_supported(const Size2D &output_tile, const Size2D &kernel_size, DataLayout data_layout);
178 
179 /** Helper function to get the preferred native vector width size for built-in scalar types that can be put into vectors
180  *
181  * @param[in] device A CL device
182  * @param[in] dt data type
183  *
184  * @return preferred vector width
185  */
186 size_t preferred_vector_width(const cl::Device &device, DataType dt);
187 
188 /** Helper function to check if "dummy work-items" are preferred to have a power of two NDRange
189  * In case dummy work-items is enabled, it is OpenCL kernel responsibility to check if the work-item is out-of range or not
190  *
191  * @param[in] device A CL device
192  *
193  * @return True if dummy work-items should be preferred to dispatch the NDRange
194  */
195 bool preferred_dummy_work_items_support(const cl::Device &device);
196 
197 /** Helper function to check whether the cl_khr_image2d_from_buffer extension is supported
198  *
199  * @param[in] device A CL device
200  *
201  * @return True if the extension is supported
202  */
203 bool image2d_from_buffer_supported(const cl::Device &device);
204 
205 /** Creates an opencl kernel
206  *
207  * @param[in] ctx A context to be used to create the opencl kernel.
208  * @param[in] kernel_name The kernel name.
209  * @param[in] build_opts The build options to be used for the opencl kernel compilation.
210  *
211  * @return An opencl kernel
212  */
213 cl::Kernel create_opencl_kernel(CLCoreRuntimeContext *ctx, const std::string &kernel_name, const CLBuildOptions &build_opts);
214 
215 /** Creates an opencl kernel using a compile context
216  *
217  * @param[in] ctx A compile context to be used to create the opencl kernel.
218  * @param[in] kernel_name The kernel name.
219  * @param[in] build_opts The build options to be used for the opencl kernel compilation.
220  *
221  * @return An opencl kernel
222  */
223 cl::Kernel create_kernel(const CLCompileContext &ctx, const std::string &kernel_name, const std::set<std::string> &build_opts = std::set<std::string>());
224 
225 /** Creates a suitable LWS hint object for parallel implementations. Sets the number of WG based on the input size.
226  * If input width is smaller than 128 we can use fewer threads than 8.
227  *
228  * @param[in] input_dimension number of elements along the dimension to apply the parallellization
229  * @param[in] vector_size size of the vector in OpenCL
230  *
231  * @return An LWS hint object
232  */
233 cl::NDRange create_lws_hint_parallel_implementations(unsigned int input_dimension, unsigned int vector_size);
234 
235 /* Helper function to check if the workgroup batch size modifier parameter is supported on the cl device
236  *
237  * @param[in] device cl device to check for support
238  *
239  * @return true if the workgroup batch size modifier parameter is supported, false otherwise
240  */
241 bool get_wbsm_support_info(const cl::Device &device);
242 
243 /* Helper function to set the workgroup batch size modifier parameter in the kernel
244  *
245  * @param[in] kernel cl kernel to set the workgroup batch size modifier parameter
246  * @param[in] wbsm_hint workgroup batch size modifier to use
247  */
248 void set_wbsm(cl::Kernel &kernel, cl_int wbsm_hint);
249 
250 } // namespace arm_compute
251 #endif /* ARM_COMPUTE_CLHELPERS_H */
bool dot8_acc_supported(const cl::Device &device)
Helper function to check whether the cl_arm_integer_dot_product_accumulate_int8 extension is supporte...
Definition: CLHelpers.cpp:249
bool image2d_from_buffer_supported(const cl::Device &device)
Helper function to check whether the cl_khr_image2d_from_buffer extension is supported.
Definition: CLHelpers.cpp:368
bool dot8_supported(const cl::Device &device)
Helper function to check whether the cl_arm_integer_dot_product_int8 extension is supported.
Definition: CLHelpers.cpp:239
bool fp16_supported(const cl::Device &device)
Helper function to check whether the cl_khr_fp16 extension is supported.
Definition: CLHelpers.cpp:234
void set_wbsm(cl::Kernel &kernel, cl_int wbsm_hint)
Definition: CLHelpers.cpp:430
bool preferred_dummy_work_items_support(const cl::Device &device)
Helper function to check if "dummy work-items" are preferred to have a power of two NDRange In case d...
Definition: CLHelpers.cpp:361
std::string get_cl_select_type_from_data_type(const DataType &dt)
Translates a tensor data type to the appropriate OpenCL select type.
Definition: CLHelpers.cpp:139
std::string get_cl_dot8_acc_type_from_data_type(const DataType &dt)
Translates a tensor data type to the appropriate OpenCL dot8 accumulator type.
Definition: CLHelpers.cpp:173
CLVersion
Available OpenCL Version.
Definition: CLTypes.h:39
std::string get_cl_signed_type_from_element_size(size_t element_size)
Translates the element size to an signed integer data type.
Definition: CLHelpers.cpp:121
size_t preferred_vector_width(const cl::Device &device, DataType dt)
Helper function to get the preferred native vector width size for built-in scalar types that can be p...
Definition: CLHelpers.cpp:331
bool get_wbsm_support_info(const cl::Device &device)
Definition: CLHelpers.cpp:419
const DataLayout data_layout
Definition: Im2Col.cpp:151
Copyright (c) 2017-2021 Arm Limited.
DataType dt
cl::Kernel create_kernel(const CLCompileContext &ctx, const std::string &kernel_name, const std::set< std::string > &build_opts=std::set< std::string >())
Creates an opencl kernel using a compile context.
Definition: CLHelpers.cpp:403
std::string get_data_size_from_data_type(const DataType &dt)
Get the size of a data type in number of bits.
Definition: CLHelpers.cpp:191
std::string kernel_name
std::string get_cl_type_from_data_type(const DataType &dt)
Translates a tensor data type to the appropriate OpenCL type.
Definition: CLHelpers.cpp:37
GPUTarget get_target_from_device(const cl::Device &device)
Helper function to get the GPU target from CL device.
Definition: CLHelpers.cpp:221
cl::NDRange create_lws_hint_parallel_implementations(unsigned int input_dimension, unsigned int vector_size)
Creates a suitable LWS hint object for parallel implementations.
Definition: CLHelpers.cpp:411
size_t get_cl_image_pitch_alignment(const cl::Device &device)
Helper function to get the cl_image pitch alignment in pixels.
Definition: CLHelpers.cpp:373
CLVersion get_cl_version(const cl::Device &device)
Helper function to get the highest OpenCL version supported.
Definition: CLHelpers.cpp:254
std::string get_cl_promoted_type_from_data_type(const DataType &dt)
Translates a tensor data type to the appropriate OpenCL promoted type.
Definition: CLHelpers.cpp:73
bool device_supports_extension(const cl::Device &device, const char *extension_name)
Helper function to check whether a given extension is supported.
Definition: CLHelpers.cpp:277
GPUTarget
Available GPU Targets.
Definition: GPUTarget.h:34
cl::Kernel create_opencl_kernel(CLCoreRuntimeContext *ctx, const std::string &kernel_name, const CLBuildOptions &build_opts)
Creates an opencl kernel.
Definition: CLHelpers.cpp:389
std::string get_cl_unsigned_type_from_element_size(size_t element_size)
Translates the element size to an unsigned integer data type.
Definition: CLHelpers.cpp:103
Wrapper to configure the Khronos OpenCL C++ header.
bool arm_non_uniform_workgroup_supported(const cl::Device &device)
Helper function to check whether the arm_non_uniform_work_group_size extension is supported.
Definition: CLHelpers.cpp:229
bool cl_winograd_convolution_layer_supported(const Size2D &output_tile, const Size2D &kernel_size, DataLayout data_layout)
This function checks if the Winograd configuration (defined through the output tile,...
Definition: CLHelpers.cpp:284
DataType
Available data types.
Definition: Types.h:77
DataLayout
[DataLayout enum definition]
Definition: Types.h:114