Compute Library
 22.11
CLTuningParametersList.cpp
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2019-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  */
25 
26 namespace arm_compute
27 {
28 namespace cl_tuner
29 {
30 constexpr unsigned int max_lws_supported_x{ 64u };
31 constexpr unsigned int max_lws_supported_y{ 32u };
32 constexpr unsigned int max_lws_supported_z{ 32u };
33 
34 /** Non instantiable base class for Tuning parameters combinations that use Index2Cooard mapping */
35 class CLTuningParametersList : public ICLTuningParametersList
36 {
37 protected:
38  /* Shape of 4-D search space */
39  TensorShape search_space_shape{ 0, 0, 0, 0 };
40  std::vector<unsigned int> _lws_x{ 0 };
41  std::vector<unsigned int> _lws_y{ 0 };
42  std::vector<unsigned int> _lws_z{ 0 };
43  std::vector<int> _wbsm{ 0 }; /* Modify the batches size of workgroups distributed to compute units.
44  The value is in the range [-31,+31].
45  When 0, the runtime-selected wbs used is unmodified. */
46 
47  /** Constructor */
48  CLTuningParametersList() = default;
49  /** Copy Constructor */
50  CLTuningParametersList(const CLTuningParametersList &) = default;
51  /** Move Constructor */
52  CLTuningParametersList(CLTuningParametersList &&) noexcept(true) = default;
53  /** Assignment */
54  CLTuningParametersList &operator=(const CLTuningParametersList &) = default;
55  /** Move Assignment */
56  CLTuningParametersList &operator=(CLTuningParametersList &&) noexcept(true) = default;
57  /** Destructor */
58  virtual ~CLTuningParametersList() = default;
59 
60  // Inherited methods overridden:
61  virtual size_t size() override;
62 };
63 
64 /** Exhaustive list of all possible Tuning parameters (lws) values */
65 class CLTuningParametersListExhaustive : public CLTuningParametersList
66 {
67 public:
68  /** Prevent default constructor calls */
69  CLTuningParametersListExhaustive() = delete;
70  /** Constructor */
71  CLTuningParametersListExhaustive(const cl::NDRange &gws, CLTuningInfo tuning_info);
72  /** Copy Constructor */
73  CLTuningParametersListExhaustive(const CLTuningParametersListExhaustive &) = default;
74  /** Move Constructor */
75  CLTuningParametersListExhaustive(CLTuningParametersListExhaustive &&) noexcept(true) = default;
76  /** Assignment */
77  CLTuningParametersListExhaustive &operator=(const CLTuningParametersListExhaustive &) = default;
78  /** Move Assignment */
79  CLTuningParametersListExhaustive &operator=(CLTuningParametersListExhaustive &&) noexcept(true) = default;
80  /** Destructor */
81  ~CLTuningParametersListExhaustive() = default;
82 
83  // Inherited methods overridden:
84  CLTuningParams operator[](size_t) override;
85 };
86 
87 /** A subset of LWS values that are either factors of gws when gws[2] < 16 or power of 2 */
88 class CLTuningParametersListNormal : public CLTuningParametersList
89 {
90 public:
91  /** Constructor */
92  CLTuningParametersListNormal(const cl::NDRange &gws, CLTuningInfo tuning_info);
93  /** Copy Constructor */
94  CLTuningParametersListNormal(const CLTuningParametersListNormal &) = default;
95  /** Move Constructor */
96  CLTuningParametersListNormal(CLTuningParametersListNormal &&) noexcept(true) = default;
97  /** Assignment */
98  CLTuningParametersListNormal &operator=(const CLTuningParametersListNormal &) = default;
99  /** Move Assignment */
100  CLTuningParametersListNormal &operator=(CLTuningParametersListNormal &&) noexcept(true) = default;
101  /** Destructor */
102  ~CLTuningParametersListNormal() = default;
103 
104  // Inherited methods overridden:
105  CLTuningParams operator[](size_t) override;
106 
107  /** Prevent default constructor calls */
108  CLTuningParametersListNormal() = default;
109 
110 private:
111  /** Utility function used to initialize the LWS values to test.
112  * Only the LWS values which are power of 2 or satisfy the modulo conditions with GWS are taken into account by the CLTuner
113  *
114  * @param[in, out] lws Vector of LWS to test
115  * @param[in] gws Size of the specific GWS
116  * @param[in] lws_max Max LWS value allowed to be tested
117  * @param[in] mod_let_one True if the results of the modulo operation between gws and the lws can be less than one.
118  */
119  void initialize_lws_values(std::vector<unsigned int> &lws, unsigned int gws, unsigned int lws_max, bool mod_let_one);
120 };
121 
122 /** A minimal subset of LWS values that only have 1,2 and 4/8 */
123 class CLTuningParametersListRapid : public CLTuningParametersListNormal
124 {
125 public:
126  /** Prevent default constructor calls */
127  CLTuningParametersListRapid() = delete;
128  /** Constructor */
129  CLTuningParametersListRapid(const cl::NDRange &gws, CLTuningInfo tuning_info);
130  /** Copy Constructor */
131  CLTuningParametersListRapid(const CLTuningParametersListRapid &) = default;
132  /** Move Constructor */
133  CLTuningParametersListRapid(CLTuningParametersListRapid &&) noexcept(true) = default;
134  /** Assignment */
135  CLTuningParametersListRapid &operator=(const CLTuningParametersListRapid &) = default;
136  /** Move Assignment */
137  CLTuningParametersListRapid &operator=(CLTuningParametersListRapid &&) noexcept(true) = default;
138  /** Destructor */
139  virtual ~CLTuningParametersListRapid() = default;
140 
141 private:
142  /** Utility function used to initialize the LWS values to test.
143  * Only the LWS values that have 1,2 and 4/8 for each dimension are taken into account by the CLTuner
144  *
145  * @param[in, out] lws Vector of LWS to test
146  * @param[in] lws_max Max LWS value allowed to be tested
147  */
148  void initialize_lws_values(std::vector<unsigned int> &lws, unsigned int lws_max);
149 };
150 
151 size_t CLTuningParametersList::size()
152 {
153  return search_space_shape.total_size();
154 }
155 
156 CLTuningParams CLTuningParametersListExhaustive::operator[](size_t index)
157 {
158  ARM_COMPUTE_ERROR_ON(index >= size());
159  auto coords = index2coords(search_space_shape, index);
160  return CLTuningParams(coords[0] + 1U, coords[1] + 1U, coords[2] + 1U, static_cast<int>(coords[3]));
161 }
162 
163 CLTuningParametersListExhaustive::CLTuningParametersListExhaustive(const cl::NDRange &gws, CLTuningInfo tuning_info)
164 {
165  ARM_COMPUTE_UNUSED(gws);
166  search_space_shape[0] = max_lws_supported_x;
167  search_space_shape[1] = max_lws_supported_y;
168  search_space_shape[2] = max_lws_supported_z;
169  search_space_shape[3] = 1;
170  if(tuning_info.tune_wbsm)
171  {
172  _wbsm = { -3, -2, -1, 0, 1, 2, 3 };
173  search_space_shape[3] = _wbsm.size();
174  }
175 }
176 
177 CLTuningParams CLTuningParametersListNormal::operator[](size_t index)
178 {
179  ARM_COMPUTE_ERROR_ON(index >= size());
180  auto coords = index2coords(search_space_shape, index);
181  return CLTuningParams(_lws_x[coords[0]], _lws_y[coords[1]], _lws_z[coords[2]], _wbsm[coords[3]]);
182 }
183 
184 CLTuningParametersListNormal::CLTuningParametersListNormal(const cl::NDRange &gws, CLTuningInfo tuning_info)
185 {
186  auto lws_x_max = std::min(static_cast<unsigned int>(gws[0]), max_lws_supported_x);
187  auto lws_y_max = std::min(static_cast<unsigned int>(gws[1]), max_lws_supported_y);
188  auto lws_z_max = std::min(static_cast<unsigned int>(gws[2]), max_lws_supported_z);
189 
190  // Initialize the tuning parameters values to test
191  _lws_x = {};
192  _lws_y = {};
193  _lws_z = {};
194  initialize_lws_values(_lws_x, gws[0], lws_x_max, gws[2] > 16); // Explore lws that are not factors of gws only when gws[2] > 16
195  initialize_lws_values(_lws_y, gws[1], lws_y_max, gws[2] > 16); // Explore lws that are not factors of gws only when gws[2] > 16
196  initialize_lws_values(_lws_z, gws[2], lws_z_max, false);
197 
198  search_space_shape[0] = _lws_x.size();
199  search_space_shape[1] = _lws_y.size();
200  search_space_shape[2] = _lws_z.size();
201  search_space_shape[3] = 1;
202  if(tuning_info.tune_wbsm)
203  {
204  _wbsm = { -2, -1, 0, 1, 2 };
205  search_space_shape[3] = _wbsm.size();
206  }
207 }
208 
209 void CLTuningParametersListNormal::initialize_lws_values(std::vector<unsigned int> &lws, unsigned int gws, unsigned int lws_max, bool mod_let_one)
210 {
211  lws.push_back(1);
212 
213  for(unsigned int i = 2; i <= lws_max; ++i)
214  {
215  // Power of two condition
216  const bool is_power_of_two = (i & (i - 1)) == 0;
217 
218  // Condition for the module accordingly with the mod_let_one flag
219  const bool mod_cond = mod_let_one ? (gws % i) <= 1 : (gws % i) == 0;
220 
221  if(mod_cond || is_power_of_two)
222  {
223  lws.push_back(i);
224  }
225  }
226 }
227 
228 CLTuningParametersListRapid::CLTuningParametersListRapid(const cl::NDRange &gws, CLTuningInfo tuning_info)
229 {
230  auto lws_x_max = std::min(static_cast<unsigned int>(gws[0]), 8u); // Limit exploration to 1 - 8
231  auto lws_y_max = std::min(static_cast<unsigned int>(gws[1]), 4u); // Limit exploration to 1 - 4
232  auto lws_z_max = std::min(static_cast<unsigned int>(gws[2]), 4u); // Limit exploration to 1 - 4
233 
234  // Initialize the LWS values to test
235  _lws_x = {};
236  _lws_y = {};
237  _lws_z = {};
238  initialize_lws_values(_lws_x, lws_x_max);
239  initialize_lws_values(_lws_y, lws_y_max);
240  initialize_lws_values(_lws_z, lws_z_max);
241 
242  search_space_shape[0] = _lws_x.size();
243  search_space_shape[1] = _lws_y.size();
244  search_space_shape[2] = _lws_z.size();
245  search_space_shape[3] = 1;
246  if(tuning_info.tune_wbsm)
247  {
248  _wbsm = { -1, 0, 1 };
249  search_space_shape[3] = _wbsm.size();
250  }
251 }
252 
253 void CLTuningParametersListRapid::initialize_lws_values(std::vector<unsigned int> &lws, unsigned int lws_max)
254 {
255  lws.push_back(1);
256 
257  for(unsigned int i = 2; i <= lws_max; i *= 4)
258  {
259  lws.push_back(i);
260  }
261 }
262 
263 std::unique_ptr<ICLTuningParametersList> get_tuning_parameters_list(CLTuningInfo tuning_info, const cl::NDRange &gws)
264 {
265  switch(tuning_info.tuner_mode)
266  {
268  return std::make_unique<CLTuningParametersListExhaustive>(gws, tuning_info);
269  case CLTunerMode::NORMAL:
270  return std::make_unique<CLTuningParametersListNormal>(gws, tuning_info);
271  case CLTunerMode::RAPID:
272  return std::make_unique<CLTuningParametersListRapid>(gws, tuning_info);
273  default:
274  return nullptr;
275  }
276 }
277 } // namespace cl_tuner
278 } // namespace arm_compute
Shape of a tensor.
Definition: TensorShape.h:39
Coordinates index2coords(const TensorShape &shape, int index)
Convert a linear index into n-dimensional coordinates.
Definition: Helpers.inl:156
bool tune_wbsm
Flag to tune the batches of work groups distributed to compute units.
Definition: CLTunerTypes.h:46
Searches a subset of LWS configurations while tuning.
#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
< OpenCL tuner parameters
constexpr unsigned int max_lws_supported_z
constexpr unsigned int max_lws_supported_y
Copyright (c) 2017-2022 Arm Limited.
Interface for Tuning Parameters lists.
Searches a minimal subset of LWS configurations while tuning.
#define ARM_COMPUTE_UNUSED(...)
To avoid unused variables warnings.
Definition: Error.h:152
constexpr unsigned int max_lws_supported_x
CLTunerMode tuner_mode
Parameter to select the level (granularity) of the tuning.
Definition: CLTunerTypes.h:45
std::unique_ptr< ICLTuningParametersList > get_tuning_parameters_list(CLTuningInfo tuning_info, const cl::NDRange &gws)
Construct an ICLTuningParametersList object for the given tuner mode and gws configuration.
Searches all possible LWS configurations while tuning.