Compute Library
 20.02.1
ICLKernel.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2016-2019 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_ICLKERNEL_H
25 #define ARM_COMPUTE_ICLKERNEL_H
26 
32 
33 #include <string>
34 
35 namespace arm_compute
36 {
37 template <typename T>
38 class ICLArray;
39 class ICLTensor;
40 class Window;
41 
42 /** Common interface for all the OpenCL kernels */
43 class ICLKernel : public IKernel
44 {
45 private:
46  /** Returns the number of arguments enqueued per array object.
47  *
48  * @return The number of arguments enqueued per array object.
49  */
50  template <unsigned int dimension_size>
51  constexpr static unsigned int num_arguments_per_array()
52  {
53  return num_arguments_per_tensor<dimension_size>();
54  }
55  /** Returns the number of arguments enqueued per tensor object.
56  *
57  * @return The number of arguments enqueued per tensor object.
58  */
59  template <unsigned int dimension_size>
60  constexpr static unsigned int num_arguments_per_tensor()
61  {
62  return 2 + 2 * dimension_size;
63  }
64  using IKernel::configure; //Prevent children from calling IKernel::configure() directly
65 protected:
66  /** Configure the kernel's window and local workgroup size hint.
67  *
68  * @param[in] window The maximum window which will be returned by window()
69  * @param[in] lws_hint (Optional) Local-Workgroup-Size to use.
70  */
71  void configure_internal(const Window &window, cl::NDRange lws_hint = CLKernelLibrary::get().default_ndrange())
72  {
73  _lws_hint = lws_hint;
74  IKernel::configure(window);
75  }
76 
77 public:
78  /** Constructor */
80  : _kernel(nullptr), _target(GPUTarget::MIDGARD), _config_id(arm_compute::default_config_id), _max_workgroup_size(0), _lws_hint()
81  {
82  }
83  /** Returns a reference to the OpenCL kernel of this object.
84  *
85  * @return A reference to the OpenCL kernel of this object.
86  */
87  cl::Kernel &kernel()
88  {
89  return _kernel;
90  }
91  /** Add the passed 1D array's parameters to the object's kernel's arguments starting from the index idx.
92  *
93  * @param[in,out] idx Index at which to start adding the array's arguments. Will be incremented by the number of kernel arguments set.
94  * @param[in] array Array to set as an argument of the object's kernel.
95  * @param[in] strides @ref Strides object containing stride of each dimension in bytes.
96  * @param[in] num_dimensions Number of dimensions of the @p array.
97  * @param[in] window Window the kernel will be executed on.
98  */
99  template <typename T>
100  void add_1D_array_argument(unsigned int &idx, const ICLArray<T> *array, const Strides &strides, unsigned int num_dimensions, const Window &window)
101  {
102  add_array_argument<T, 1>(idx, array, strides, num_dimensions, window);
103  }
104  /** Add the passed 1D tensor's parameters to the object's kernel's arguments starting from the index idx.
105  *
106  * @param[in,out] idx Index at which to start adding the tensor's arguments. Will be incremented by the number of kernel arguments set.
107  * @param[in] tensor Tensor to set as an argument of the object's kernel.
108  * @param[in] window Window the kernel will be executed on.
109  */
110  void add_1D_tensor_argument(unsigned int &idx, const ICLTensor *tensor, const Window &window)
111  {
112  add_tensor_argument<1>(idx, tensor, window);
113  }
114  /** Add the passed 1D tensor's parameters to the object's kernel's arguments starting from the index idx if the condition is true.
115  *
116  * @param[in] cond Condition to check
117  * @param[in,out] idx Index at which to start adding the tensor's arguments. Will be incremented by the number of kernel arguments set.
118  * @param[in] tensor Tensor to set as an argument of the object's kernel.
119  * @param[in] window Window the kernel will be executed on.
120  */
121  void add_1D_tensor_argument_if(bool cond, unsigned int &idx, const ICLTensor *tensor, const Window &window)
122  {
123  if(cond)
124  {
125  add_1D_tensor_argument(idx, tensor, window);
126  }
127  }
128  /** Add the passed 2D tensor's parameters to the object's kernel's arguments starting from the index idx.
129  *
130  * @param[in,out] idx Index at which to start adding the tensor's arguments. Will be incremented by the number of kernel arguments set.
131  * @param[in] tensor Tensor to set as an argument of the object's kernel.
132  * @param[in] window Window the kernel will be executed on.
133  */
134  void add_2D_tensor_argument(unsigned int &idx, const ICLTensor *tensor, const Window &window)
135  {
136  add_tensor_argument<2>(idx, tensor, window);
137  }
138  /** Add the passed 2D tensor's parameters to the object's kernel's arguments starting from the index idx if the condition is true.
139  *
140  * @param[in] cond Condition to check
141  * @param[in,out] idx Index at which to start adding the tensor's arguments. Will be incremented by the number of kernel arguments set.
142  * @param[in] tensor Tensor to set as an argument of the object's kernel.
143  * @param[in] window Window the kernel will be executed on.
144  */
145  void add_2D_tensor_argument_if(bool cond, unsigned int &idx, const ICLTensor *tensor, const Window &window)
146  {
147  if(cond)
148  {
149  add_2D_tensor_argument(idx, tensor, window);
150  }
151  }
152  /** Add the passed 3D tensor's parameters to the object's kernel's arguments starting from the index idx.
153  *
154  * @param[in,out] idx Index at which to start adding the tensor's arguments. Will be incremented by the number of kernel arguments set.
155  * @param[in] tensor Tensor to set as an argument of the object's kernel.
156  * @param[in] window Window the kernel will be executed on.
157  */
158  void add_3D_tensor_argument(unsigned int &idx, const ICLTensor *tensor, const Window &window)
159  {
160  add_tensor_argument<3>(idx, tensor, window);
161  }
162  /** Add the passed 4D tensor's parameters to the object's kernel's arguments starting from the index idx.
163  *
164  * @param[in,out] idx Index at which to start adding the tensor's arguments. Will be incremented by the number of kernel arguments set.
165  * @param[in] tensor Tensor to set as an argument of the object's kernel.
166  * @param[in] window Window the kernel will be executed on.
167  */
168  void add_4D_tensor_argument(unsigned int &idx, const ICLTensor *tensor, const Window &window)
169  {
170  add_tensor_argument<4>(idx, tensor, window);
171  }
172  /** Returns the number of arguments enqueued per 1D array object.
173  *
174  * @return The number of arguments enqueues per 1D array object.
175  */
176  constexpr static unsigned int num_arguments_per_1D_array()
177  {
178  return num_arguments_per_array<1>();
179  }
180  /** Returns the number of arguments enqueued per 1D tensor object.
181  *
182  * @return The number of arguments enqueues per 1D tensor object.
183  */
184  constexpr static unsigned int num_arguments_per_1D_tensor()
185  {
186  return num_arguments_per_tensor<1>();
187  }
188  /** Returns the number of arguments enqueued per 2D tensor object.
189  *
190  * @return The number of arguments enqueues per 2D tensor object.
191  */
192  constexpr static unsigned int num_arguments_per_2D_tensor()
193  {
194  return num_arguments_per_tensor<2>();
195  }
196  /** Returns the number of arguments enqueued per 3D tensor object.
197  *
198  * @return The number of arguments enqueues per 3D tensor object.
199  */
200  constexpr static unsigned int num_arguments_per_3D_tensor()
201  {
202  return num_arguments_per_tensor<3>();
203  }
204  /** Returns the number of arguments enqueued per 4D tensor object.
205  *
206  * @return The number of arguments enqueues per 4D tensor object.
207  */
208  constexpr static unsigned int num_arguments_per_4D_tensor()
209  {
210  return num_arguments_per_tensor<4>();
211  }
212  /** Enqueue the OpenCL kernel to process the given window on the passed OpenCL command queue.
213  *
214  * @note The queue is *not* flushed by this method, and therefore the kernel will not have been executed by the time this method returns.
215  *
216  * @param[in] window Region on which to execute the kernel. (Must be a valid region of the window returned by window()).
217  * @param[in,out] queue Command queue on which to enqueue the kernel.
218  */
219  virtual void run(const Window &window, cl::CommandQueue &queue) = 0;
220  /** Add the passed parameters to the object's kernel's arguments starting from the index idx.
221  *
222  * @param[in,out] idx Index at which to start adding the arguments. Will be incremented by the number of kernel arguments set.
223  * @param[in] value Value to set as an argument of the object's kernel.
224  */
225  template <typename T>
226  void add_argument(unsigned int &idx, T value)
227  {
228  _kernel.setArg(idx++, value);
229  }
230 
231  /** Set the Local-Workgroup-Size hint
232  *
233  * @note This method should be called after the configuration of the kernel
234  *
235  * @param[in] lws_hint Local-Workgroup-Size to use
236  */
237  void set_lws_hint(const cl::NDRange &lws_hint)
238  {
239  ARM_COMPUTE_ERROR_ON_UNCONFIGURED_KERNEL(this); // lws_hint will be overwritten by configure()
240  _lws_hint = lws_hint;
241  }
242 
243  /** Return the Local-Workgroup-Size hint
244  *
245  * @return Current lws hint
246  */
247  cl::NDRange lws_hint() const
248  {
249  return _lws_hint;
250  }
251 
252  /** Get the configuration ID
253  *
254  * @note The configuration ID can be used by the caller to distinguish different calls of the same OpenCL kernel
255  * In particular, this method can be used by CLScheduler to keep track of the best LWS for each configuration of the same kernel.
256  * The configuration ID should be provided only for the kernels potentially affected by the LWS geometry
257  *
258  * @note This method should be called after the configuration of the kernel
259  *
260  * @return configuration id string
261  */
262  const std::string &config_id() const
263  {
264  return _config_id;
265  }
266 
267  /** Set the targeted GPU architecture
268  *
269  * @param[in] target The targeted GPU architecture
270  */
271  void set_target(GPUTarget target)
272  {
273  _target = target;
274  }
275 
276  /** Set the targeted GPU architecture according to the CL device
277  *
278  * @param[in] device A CL device
279  */
280  void set_target(cl::Device &device);
281 
282  /** Get the targeted GPU architecture
283  *
284  * @return The targeted GPU architecture.
285  */
287  {
288  return _target;
289  }
290 
291  /** Get the maximum workgroup size for the device the CLKernelLibrary uses.
292  *
293  * @return The maximum workgroup size value.
294  */
295  size_t get_max_workgroup_size();
296  /** Get the global work size given an execution window
297  *
298  * @param[in] window Execution window
299  *
300  * @return Global work size of the given execution window
301  */
302  static cl::NDRange gws_from_window(const Window &window);
303 
304 private:
305  /** Add the passed array's parameters to the object's kernel's arguments starting from the index idx.
306  *
307  * @param[in,out] idx Index at which to start adding the array's arguments. Will be incremented by the number of kernel arguments set.
308  * @param[in] array Array to set as an argument of the object's kernel.
309  * @param[in] strides @ref Strides object containing stride of each dimension in bytes.
310  * @param[in] num_dimensions Number of dimensions of the @p array.
311  * @param[in] window Window the kernel will be executed on.
312  */
313  template <typename T, unsigned int dimension_size>
314  void add_array_argument(unsigned int &idx, const ICLArray<T> *array, const Strides &strides, unsigned int num_dimensions, const Window &window);
315  /** Add the passed tensor's parameters to the object's kernel's arguments starting from the index idx.
316  *
317  * @param[in,out] idx Index at which to start adding the tensor's arguments. Will be incremented by the number of kernel arguments set.
318  * @param[in] tensor Tensor to set as an argument of the object's kernel.
319  * @param[in] window Window the kernel will be executed on.
320  */
321  template <unsigned int dimension_size>
322  void add_tensor_argument(unsigned int &idx, const ICLTensor *tensor, const Window &window);
323 
324 protected:
325  cl::Kernel _kernel; /**< OpenCL kernel to run */
326  GPUTarget _target; /**< The targeted GPU */
327  std::string _config_id; /**< Configuration ID */
328  size_t _max_workgroup_size; /**< The maximum workgroup size for this kernel */
329 private:
330  cl::NDRange _lws_hint; /**< Local workgroup size hint for the OpenCL kernel */
331 };
332 
333 /** Add the kernel to the command queue with the given window.
334  *
335  * @note Depending on the size of the window, this might translate into several jobs being enqueued.
336  *
337  * @note If kernel->kernel() is empty then the function will return without adding anything to the queue.
338  *
339  * @param[in,out] queue OpenCL command queue.
340  * @param[in] kernel Kernel to enqueue
341  * @param[in] window Window the kernel has to process.
342  * @param[in] lws_hint (Optional) Local workgroup size requested. Default is based on the device target.
343  * @param[in] use_dummy_work_items (Optional) Use dummy work items in order to have two dimensional power of two NDRange. Default is false
344  * Note: it is kernel responsibility to check if the work-item is out-of-range
345  *
346  * @note If any dimension of the lws is greater than the global workgroup size then no lws will be passed.
347  */
348 void enqueue(cl::CommandQueue &queue, ICLKernel &kernel, const Window &window, const cl::NDRange &lws_hint = CLKernelLibrary::get().default_ndrange(), bool use_dummy_work_items = false);
349 
350 /** Add the passed array's parameters to the object's kernel's arguments starting from the index idx.
351  *
352  * @param[in,out] idx Index at which to start adding the array's arguments. Will be incremented by the number of kernel arguments set.
353  * @param[in] array Array to set as an argument of the object's kernel.
354  * @param[in] strides @ref Strides object containing stride of each dimension in bytes.
355  * @param[in] num_dimensions Number of dimensions of the @p array.
356  * @param[in] window Window the kernel will be executed on.
357  */
358 template <typename T, unsigned int dimension_size>
359 void ICLKernel::add_array_argument(unsigned &idx, const ICLArray<T> *array, const Strides &strides, unsigned int num_dimensions, const Window &window)
360 {
361  ARM_COMPUTE_ERROR_ON(array == nullptr);
362 
363  // Calculate offset to the start of the window
364  unsigned int offset_first_element = 0;
365 
366  for(unsigned int n = 0; n < num_dimensions; ++n)
367  {
368  offset_first_element += window[n].start() * strides[n];
369  }
370 
371  unsigned int idx_start = idx;
372  _kernel.setArg(idx++, array->cl_buffer());
373 
374  for(unsigned int dimension = 0; dimension < dimension_size; dimension++)
375  {
376  _kernel.setArg<cl_uint>(idx++, strides[dimension]);
377  _kernel.setArg<cl_uint>(idx++, strides[dimension] * window[dimension].step());
378  }
379 
380  _kernel.setArg<cl_uint>(idx++, offset_first_element);
381 
382  ARM_COMPUTE_ERROR_ON_MSG_VAR(idx_start + num_arguments_per_array<dimension_size>() != idx,
383  "add_%dD_array_argument() is supposed to add exactly %d arguments to the kernel", dimension_size, num_arguments_per_array<dimension_size>());
384  ARM_COMPUTE_UNUSED(idx_start);
385 }
386 }
387 #endif /*ARM_COMPUTE_ICLKERNEL_H */
static constexpr unsigned int num_arguments_per_1D_tensor()
Returns the number of arguments enqueued per 1D tensor object.
Definition: ICLKernel.h:184
static cl::NDRange gws_from_window(const Window &window)
Get the global work size given an execution window.
Definition: ICLKernel.cpp:141
Common information for all the kernels.
Definition: IKernel.h:33
void add_1D_tensor_argument_if(bool cond, unsigned int &idx, const ICLTensor *tensor, const Window &window)
Add the passed 1D tensor's parameters to the object's kernel's arguments starting from the index idx ...
Definition: ICLKernel.h:121
const Window & window() const
The maximum window the kernel can be executed on.
Definition: IKernel.cpp:28
static constexpr unsigned int num_arguments_per_1D_array()
Returns the number of arguments enqueued per 1D array object.
Definition: ICLKernel.h:176
void add_2D_tensor_argument_if(bool cond, unsigned int &idx, const ICLTensor *tensor, const Window &window)
Add the passed 2D tensor's parameters to the object's kernel's arguments starting from the index idx ...
Definition: ICLKernel.h:145
void enqueue(cl::CommandQueue &queue, ICLKernel &kernel, const Window &window, const cl::NDRange &lws_hint=CLKernelLibrary::get().default_ndrange(), bool use_dummy_work_items=false)
Add the kernel to the command queue with the given window.
Definition: ICLKernel.cpp:39
cl::Kernel & kernel()
Returns a reference to the OpenCL kernel of this object.
Definition: ICLKernel.h:87
cl::NDRange lws_hint() const
Return the Local-Workgroup-Size hint.
Definition: ICLKernel.h:247
void set_lws_hint(const cl::NDRange &lws_hint)
Set the Local-Workgroup-Size hint.
Definition: ICLKernel.h:237
void add_argument(unsigned int &idx, T value)
Add the passed parameters to the object's kernel's arguments starting from the index idx.
Definition: ICLKernel.h:226
void add_1D_array_argument(unsigned int &idx, const ICLArray< T > *array, const Strides &strides, unsigned int num_dimensions, const Window &window)
Add the passed 1D array's parameters to the object's kernel's arguments starting from the index idx.
Definition: ICLKernel.h:100
#define ARM_COMPUTE_ERROR_ON(cond)
If the condition is true then an error message is printed and an exception thrown.
Definition: Error.h:466
static CLKernelLibrary & get()
Access the KernelLibrary singleton.
#define ARM_COMPUTE_ERROR_ON_MSG_VAR(cond, msg,...)
Definition: Error.h:457
Common interface for all the OpenCL kernels.
Definition: ICLKernel.h:43
void add_3D_tensor_argument(unsigned int &idx, const ICLTensor *tensor, const Window &window)
Add the passed 3D tensor's parameters to the object's kernel's arguments starting from the index idx.
Definition: ICLKernel.h:158
Copyright (c) 2017-2020 ARM Limited.
const std::string & config_id() const
Get the configuration ID.
Definition: ICLKernel.h:262
Interface for OpenCL Array.
Definition: ICLArray.h:35
static constexpr unsigned int num_arguments_per_3D_tensor()
Returns the number of arguments enqueued per 3D tensor object.
Definition: ICLKernel.h:200
#define ARM_COMPUTE_UNUSED(...)
To avoid unused variables warnings.
Definition: Error.h:152
GPUTarget get_target() const
Get the targeted GPU architecture.
Definition: ICLKernel.h:286
static constexpr unsigned int num_arguments_per_2D_tensor()
Returns the number of arguments enqueued per 2D tensor object.
Definition: ICLKernel.h:192
static constexpr unsigned int num_arguments_per_4D_tensor()
Returns the number of arguments enqueued per 4D tensor object.
Definition: ICLKernel.h:208
Strides of an item in bytes.
Definition: Strides.h:37
virtual void run(const Window &window, cl::CommandQueue &queue)=0
Enqueue the OpenCL kernel to process the given window on the passed OpenCL command queue.
void add_2D_tensor_argument(unsigned int &idx, const ICLTensor *tensor, const Window &window)
Add the passed 2D tensor's parameters to the object's kernel's arguments starting from the index idx.
Definition: ICLKernel.h:134
Interface for OpenCL tensor.
Definition: ICLTensor.h:42
ICLKernel()
Constructor.
Definition: ICLKernel.h:79
GPUTarget
Available GPU Targets.
Definition: GPUTarget.h:34
size_t get_max_workgroup_size()
Get the maximum workgroup size for the device the CLKernelLibrary uses.
Definition: ICLKernel.cpp:132
void set_target(GPUTarget target)
Set the targeted GPU architecture.
Definition: ICLKernel.h:271
void add_1D_tensor_argument(unsigned int &idx, const ICLTensor *tensor, const Window &window)
Add the passed 1D tensor's parameters to the object's kernel's arguments starting from the index idx.
Definition: ICLKernel.h:110
void add_4D_tensor_argument(unsigned int &idx, const ICLTensor *tensor, const Window &window)
Add the passed 4D tensor's parameters to the object's kernel's arguments starting from the index idx.
Definition: ICLKernel.h:168
virtual const cl::Buffer & cl_buffer() const =0
Interface to be implemented by the child class to return a reference to the OpenCL buffer containing ...
Describe a multidimensional execution window.
Definition: Window.h:39
#define ARM_COMPUTE_ERROR_ON_UNCONFIGURED_KERNEL(k)
Definition: Validate.h:941