Compute Library
 21.05
CLKernelLibrary.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_CLKERNELLIBRARY_H
25 #define ARM_COMPUTE_CLKERNELLIBRARY_H
26 
29 
30 #include <map>
31 #include <set>
32 #include <string>
33 #include <utility>
34 
35 namespace arm_compute
36 {
37 /** CLKernelLibrary class */
38 class CLKernelLibrary final
39 {
40 private:
41  /** Default Constructor. */
43  /** Prevent instances of this class from being copied */
44  CLKernelLibrary(const CLKernelLibrary &) = delete;
45  /** Prevent instances of this class from being copied */
46  const CLKernelLibrary &operator=(const CLKernelLibrary &) = delete;
47 
48 public:
49  /** Access the KernelLibrary singleton.
50  * This method has been deprecated and will be removed in future releases
51  * @return The KernelLibrary instance.
52  */
53  static CLKernelLibrary &get();
54  /** Initialises the kernel library.
55  *
56  * @param[in] kernel_path Path of the directory from which kernel sources are loaded.
57  * @param[in] context CL context used to create programs.
58  * @param[in] device CL device for which the programs are created.
59  */
60  void init(std::string kernel_path, cl::Context context, cl::Device device);
61  /** Sets the path that the kernels reside in.
62  *
63  * @param[in] kernel_path Path of the kernel.
64  */
65  void set_kernel_path(const std::string &kernel_path);
66  /** Gets the path that the kernels reside in.
67  */
68  std::string get_kernel_path();
69  /** Gets the source of the selected program.
70  *
71  * @param[in] program_name Program name.
72  *
73  * @return A pair with the source (false) or the binary (true), of the selected program.
74  */
75  std::pair<std::string, bool> get_program(const std::string &program_name) const;
76 
77  /** Accessor for the associated CL context.
78  *
79  * @return A CL context.
80  */
81  cl::Context &context();
82 
83  /** Gets the CL device for which the programs are created. */
84  const cl::Device &get_device();
85 
86  /** Sets the CL device for which the programs are created.
87  *
88  * @param[in] device A CL device.
89  */
90  void set_device(cl::Device device);
91 
92  /** Return the device version
93  *
94  * @return The content of CL_DEVICE_VERSION
95  */
96  std::string get_device_version();
97  /** Return the maximum number of compute units in the device
98  *
99  * @return The content of CL_DEVICE_MAX_COMPUTE_UNITS
100  */
101  cl_uint get_num_compute_units();
102  /** Creates a kernel from the kernel library.
103  *
104  * @param[in] kernel_name Kernel name.
105  * @param[in] build_options_set Kernel build options as a set.
106  *
107  * @return The created kernel.
108  */
109  Kernel create_kernel(const std::string &kernel_name, const std::set<std::string> &build_options_set = {}) const;
110  /** Find the maximum number of local work items in a workgroup can be supported for the kernel.
111  *
112  */
113  size_t max_local_workgroup_size(const cl::Kernel &kernel) const;
114  /** Return the default NDRange for the device.
115  *
116  */
117  cl::NDRange default_ndrange() const;
118 
119  /** Clear the library's cache of binary programs
120  */
121  void clear_programs_cache();
122 
123  /** Access the cache of built OpenCL programs */
124  const std::map<std::string, cl::Program> &get_built_programs() const;
125 
126  /** Add a new built program to the cache
127  *
128  * @param[in] built_program_name Name of the program
129  * @param[in] program Built program to add to the cache
130  */
131  void add_built_program(const std::string &built_program_name, const cl::Program &program);
132 
133  /** Returns true if FP16 is supported by the CL device
134  *
135  * @return true if the CL device supports FP16
136  */
137  bool fp16_supported() const;
138 
139  /** Returns true if int64_base_atomics extension is supported by the CL device
140  *
141  * @return true if the CL device supports int64_base_atomics extension
142  */
143  bool int64_base_atomics_supported() const;
144 
145  /** Returns the program name given a kernel name
146  *
147  * @return Program name
148  */
149  std::string get_program_name(const std::string &kernel_name) const;
150 
151  /* Returns true if the workgroup batch size modifier parameter is supported on the cl device
152  *
153  * @return true if the workgroup batch size modifier parameter is supported, false otherwise
154  */
155  bool is_wbsm_supported();
156 
157  /** Sets the CL context used to create programs.
158  *
159  * @note Setting the context also resets the device to the
160  * first one available in the new context.
161  *
162  * @param[in] context A CL context.
163  */
164  void set_context(cl::Context context);
165 
166  /** Gets the compile context used
167  *
168  * @return The used compile context
169  */
171 
172 private:
173  CLCompileContext _compile_context; /**< Compile Context. */
174  std::string _kernel_path; /**< Path to the kernels folder. */
175  mutable std::map<std::string, std::string> _decompressed_source_map; /**< Map holding the decompressed files when compression is used */
176  static const std::map<std::string, std::string> _kernel_program_map; /**< Map that associates kernel names with programs. */
177  static const std::map<std::string, std::string> _program_source_map; /**< Contains sources for all programs.
178  Used for compile-time kernel inclusion. >*/
179 };
180 } // namespace arm_compute
181 #endif /* ARM_COMPUTE_CLKERNELLIBRARY_H */
void set_kernel_path(const std::string &kernel_path)
Sets the path that the kernels reside in.
void add_built_program(const std::string &built_program_name, const cl::Program &program)
Add a new built program to the cache.
std::string get_device_version()
Return the device version.
std::pair< std::string, bool > get_program(const std::string &program_name) const
Gets the source of the selected program.
static CLKernelLibrary & get()
Access the KernelLibrary singleton.
CLCompileContext & get_compile_context()
Gets the compile context used.
void set_context(cl::Context context)
Sets the CL context used to create programs.
Copyright (c) 2017-2021 Arm Limited.
cl_uint get_num_compute_units()
Return the maximum number of compute units in the device.
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.
cl::NDRange default_ndrange() const
Return the default NDRange for the device.
void clear_programs_cache()
Clear the library's cache of binary programs.
void set_device(cl::Device device)
Sets the CL device for which the programs are created.
std::string kernel_name
Kernel create_kernel(const std::string &kernel_name, const std::set< std::string > &build_options_set={}) const
Creates a kernel from the kernel library.
void init(std::string kernel_path, cl::Context context, cl::Device device)
Initialises the kernel library.
std::string get_program_name(const std::string &kernel_name) const
Returns the program name given a kernel name.
CLCompileContext class.
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.
Wrapper to configure the Khronos OpenCL C++ header.
CLKernelLibrary class.
std::string get_kernel_path()
Gets the path that the kernels reside in.
const std::map< std::string, cl::Program > & get_built_programs() const
Access the cache of built OpenCL programs.
const cl::Device & get_device()
Gets the CL device for which the programs are created.
cl::Context & context()
Accessor for the associated CL context.