Compute Library
 20.08
CLCompileContext.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2020 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_CLCOMPILECONTEXT_H
25 #define ARM_COMPUTE_CLCOMPILECONTEXT_H
26 
29 
30 #include <map>
31 #include <set>
32 #include <string>
33 #include <utility>
34 
35 namespace arm_compute
36 {
37 /** Build options */
38 class CLBuildOptions final
39 {
40  using StringSet = std::set<std::string>;
41 
42 public:
43  /** Default constructor. */
45  /** Adds option to the existing build option list
46  *
47  * @param[in] option Option to add
48  */
49  void add_option(std::string option);
50  /** Adds option if a given condition is true;
51  *
52  * @param[in] cond Condition to check
53  * @param[in] option Option to add if condition is true
54  */
55  void add_option_if(bool cond, std::string option);
56  /** Adds first option if condition is true else the second one
57  *
58  * @param[in] cond Condition to check
59  * @param[in] option_true Option to add if condition is true
60  * @param[in] option_false Option to add if condition is false
61  */
62  void add_option_if_else(bool cond, std::string option_true, std::string option_false);
63  /** Appends given build options to the current's objects options.
64  *
65  * @param[in] options Build options to append
66  */
67  void add_options(const StringSet &options);
68  /** Appends given build options to the current's objects options if a given condition is true.
69  *
70  * @param[in] cond Condition to check
71  * @param[in] options Option to add if condition is true
72  */
73  void add_options_if(bool cond, const StringSet &options);
74  /** Gets the current options list set
75  *
76  * @return Build options set
77  */
78  const StringSet &options() const;
79 
80 private:
81  StringSet _build_opts; /**< Build options set */
82 };
83 
84 /** Program class */
85 class Program final
86 {
87 public:
88  /** Default constructor. */
89  Program();
90  /** Construct program from source file.
91  *
92  * @param[in] context CL context used to create the program.
93  * @param[in] name Program name.
94  * @param[in] source Program source.
95  */
96  Program(cl::Context context, std::string name, std::string source);
97  /** Construct program from binary file.
98  *
99  * @param[in] context CL context used to create the program.
100  * @param[in] device CL device for which the programs are created.
101  * @param[in] name Program name.
102  * @param[in] binary Program binary.
103  */
104  Program(cl::Context context, cl::Device device, std::string name, std::vector<unsigned char> binary);
105  /** Default Copy Constructor. */
106  Program(const Program &) = default;
107  /** Default Move Constructor. */
108  Program(Program &&) = default;
109  /** Default copy assignment operator */
110  Program &operator=(const Program &) = default;
111  /** Default move assignment operator */
112  Program &operator=(Program &&) = default;
113  /** Returns program name.
114  *
115  * @return Program's name.
116  */
117  std::string name() const
118  {
119  return _name;
120  }
121  /** User-defined conversion to the underlying CL program.
122  *
123  * @return The CL program object.
124  */
125  explicit operator cl::Program() const;
126  /** Build the given CL program.
127  *
128  * @param[in] program The CL program to build.
129  * @param[in] build_options Options to build the CL program.
130  *
131  * @return True if the CL program builds successfully.
132  */
133  static bool build(const cl::Program &program, const std::string &build_options = "");
134  /** Build the underlying CL program.
135  *
136  * @param[in] build_options Options used to build the CL program.
137  *
138  * @return A reference to itself.
139  */
140  cl::Program build(const std::string &build_options = "") const;
141 
142 private:
143  cl::Context _context; /**< Underlying CL context. */
144  cl::Device _device; /**< CL device for which the programs are created. */
145  bool _is_binary; /**< Create program from binary? */
146  std::string _name; /**< Program name. */
147  std::string _source; /**< Source code for the program. */
148  std::vector<unsigned char> _binary; /**< Binary from which to create the program. */
149 };
150 
151 /** Kernel class */
152 class Kernel final
153 {
154 public:
155  /** Default Constructor. */
156  Kernel();
157  /** Default Copy Constructor. */
158  Kernel(const Kernel &) = default;
159  /** Default Move Constructor. */
160  Kernel(Kernel &&) = default;
161  /** Default copy assignment operator */
162  Kernel &operator=(const Kernel &) = default;
163  /** Default move assignment operator */
164  Kernel &operator=(Kernel &&) = default;
165  /** Constructor.
166  *
167  * @param[in] name Kernel name.
168  * @param[in] program Built program.
169  */
170  Kernel(std::string name, const cl::Program &program);
171  /** Returns kernel name.
172  *
173  * @return Kernel's name.
174  */
175  std::string name() const
176  {
177  return _name;
178  }
179  /** Returns OpenCL kernel.
180  *
181  * @return OpenCL Kernel.
182  */
183  explicit operator cl::Kernel() const
184  {
185  return _kernel;
186  }
187 
188 private:
189  std::string _name; /**< Kernel name */
190  cl::Kernel _kernel; /**< OpenCL Kernel */
191 };
192 
193 /** CLCompileContext class */
194 class CLCompileContext final
195 {
196  using StringSet = std::set<std::string>;
197 
198 public:
199  /** Constructor */
201  /** Constructor
202  *
203  * @param[in] context A CL context.
204  * @param[in] device A CL device.
205  * */
206  CLCompileContext(cl::Context context, const cl::Device &device);
207 
208  /** Accessor for the associated CL context.
209  *
210  * @return A CL context.
211  */
212  cl::Context &context();
213 
214  /** Sets the CL context used to create programs.
215  *
216  * @note Setting the context also resets the device to the
217  * first one available in the new context.
218  *
219  * @param[in] context A CL context.
220  */
221  void set_context(cl::Context context);
222 
223  /** Gets the CL device for which the programs are created. */
224  const cl::Device &get_device() const;
225 
226  /** Sets the CL device for which the programs are created.
227  *
228  * @param[in] device A CL device.
229  */
230  void set_device(cl::Device device);
231 
232  /** Creates an OpenCL kernel.
233  *
234  * @param[in] kernel_name Kernel name.
235  * @param[in] program_name Program name.
236  * @param[in] program_source Program source.
237  * @param[in] kernel_path CL kernel path.
238  * @param[in] build_options_set Kernel build options as a set.
239  * @param[in] is_binary Flag to indicate if the program source is binary.
240  *
241  * @return The created kernel.
242  */
243  Kernel create_kernel(const std::string &kernel_name, const std::string &program_name, const std::string &program_source,
244  const std::string &kernel_path, const StringSet &build_options_set, bool is_binary) const;
245 
246  /** Clear the library's cache of binary programs
247  */
248  void clear_programs_cache();
249 
250  /** Access the cache of built OpenCL programs */
251  const std::map<std::string, cl::Program> &get_built_programs() const;
252 
253  /** Add a new built program to the cache
254  *
255  * @param[in] built_program_name Name of the program
256  * @param[in] program Built program to add to the cache
257  */
258  void add_built_program(const std::string &built_program_name, const cl::Program &program) const;
259 
260  /** Returns true if FP16 is supported by the CL device
261  *
262  * @return true if the CL device supports FP16
263  */
264  bool fp16_supported() const;
265 
266  /** Return the maximum number of compute units in the device
267  *
268  * @return The content of CL_DEVICE_MAX_COMPUTE_UNITS
269  */
270  cl_uint get_num_compute_units() const;
271  /** Find the maximum number of local work items in a workgroup can be supported for the kernel.
272  *
273  */
274  size_t max_local_workgroup_size(const cl::Kernel &kernel) const;
275  /** Return the default NDRange for the device.
276  *
277  */
278  cl::NDRange default_ndrange() const;
279  /** Return the device version
280  *
281  * @return The content of CL_DEVICE_VERSION
282  */
283  std::string get_device_version() const;
284 
285  /** Returns true if int64_base_atomics extension is supported by the CL device
286  *
287  * @return true if the CL device supports int64_base_atomics extension
288  */
289  bool int64_base_atomics_supported() const;
290 
291 private:
292  /** Load program and its dependencies.
293  *
294  * @param[in] program_name Name of the program to load.
295  * @param[in] program_source Source of the program.
296  * @param[in] is_binary Flag to indicate if the program source is binary.
297  */
298  const Program &load_program(const std::string &program_name, const std::string &program_source, bool is_binary) const;
299 
300  /** Generates the build options given a string of user defined ones
301  *
302  * @param[in] build_options User defined build options
303  * @param[in] kernel_path Path of the CL kernels
304  *
305  * @return Generated build options
306  */
307  std::string generate_build_options(const StringSet &build_options, const std::string &kernel_path) const;
308 
309  /** Concatenates contents of a set into a single string.
310  *
311  * @param[in] s Input set to concatenate.
312  * @param[in] kernel_path Path of the CL kernels
313  *
314  * @return Concatenated string.
315  */
316  std::string stringify_set(const StringSet &s, const std::string &kernel_path) const;
317 
318  cl::Context _context; /**< Underlying CL context. */
319  CLDevice _device; /**< Underlying CL device. */
320  mutable std::map<std::string, const Program> _programs_map; /**< Map with all already loaded program data. */
321  mutable std::map<std::string, cl::Program> _built_programs_map; /**< Map with all already built program data. */
322 };
323 } // namespace arm_compute
324 #endif /* ARM_COMPUTE_CLCOMPILECONTEXT_H */
void set_device(cl::Device device)
Sets the CL device for which the programs are created.
const cl::Device & get_device() const
Gets the CL device for which the programs are created.
cl::Context & context()
Accessor for the associated CL context.
Kernel()
Default Constructor.
const StringSet & options() const
Gets the current options list set.
CLBuildOptions()
Default constructor.
std::string get_device_version() const
Return the device version.
Copyright (c) 2017-2020 Arm Limited.
void add_option(std::string option)
Adds option to the existing build option list.
std::string name() const
Returns program name.
void add_options(const StringSet &options)
Appends given build options to the current's objects options.
cl_uint get_num_compute_units() const
Return the maximum number of compute units in the device.
std::set< std::string > build_options
std::string kernel_name
OpenCL device type class.
Definition: CLDevice.h:42
static bool build(const cl::Program &program, const std::string &build_options="")
Build the given CL program.
cl::NDRange default_ndrange() const
Return the default NDRange for the device.
void add_option_if(bool cond, std::string option)
Adds option if a given condition is true;.
Kernel create_kernel(const std::string &kernel_name, const std::string &program_name, const std::string &program_source, const std::string &kernel_path, const StringSet &build_options_set, bool is_binary) const
Creates an OpenCL kernel.
CLCompileContext class.
Kernel & operator=(const Kernel &)=default
Default copy assignment operator.
void clear_programs_cache()
Clear the library's cache of binary programs.
Program()
Default constructor.
bool int64_base_atomics_supported() const
Returns true if int64_base_atomics extension is supported by the CL device.
bool fp16_supported() const
Returns true if FP16 is supported by the CL device.
const std::map< std::string, cl::Program > & get_built_programs() const
Access the cache of built OpenCL programs.
size_t max_local_workgroup_size(const cl::Kernel &kernel) const
Find the maximum number of local work items in a workgroup can be supported for the kernel.
Program & operator=(const Program &)=default
Default copy assignment operator.
void add_built_program(const std::string &built_program_name, const cl::Program &program) const
Add a new built program to the cache.
void set_context(cl::Context context)
Sets the CL context used to create programs.
std::string name() const
Returns kernel name.
void add_options_if(bool cond, const StringSet &options)
Appends given build options to the current's objects options if a given condition is true.
void add_option_if_else(bool cond, std::string option_true, std::string option_false)
Adds first option if condition is true else the second one.