1 /* 2 * Copyright (c) 2016-2022 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_CLSCHEDULER_H 25 #define ARM_COMPUTE_CLSCHEDULER_H 26 27 #include "arm_compute/core/CL/CLHelpers.h" 28 #include "arm_compute/core/CL/CLTypes.h" 29 #include "arm_compute/core/CL/OpenCL.h" 30 #include "arm_compute/core/Error.h" 31 #include "arm_compute/core/Types.h" 32 #include "arm_compute/core/experimental/Types.h" 33 #include "arm_compute/runtime/CL/CLGEMMHeuristicsHandle.h" 34 #include "arm_compute/runtime/CL/CLHelpers.h" 35 #include "arm_compute/runtime/CL/CLTypes.h" 36 #include "arm_compute/runtime/CL/ICLTuner.h" 37 38 namespace arm_compute 39 { 40 class ICLKernel; 41 class ICLTuner; 42 /** Provides global access to a CL context and command queue. */ 43 class CLScheduler final 44 { 45 public: 46 /** Constructor */ 47 CLScheduler(); 48 /** Prevent instances of this class from being copied (As this class contains pointers) */ 49 CLScheduler(const CLScheduler &) = delete; 50 /** Prevent instances of this class from being copied (As this class contains pointers) */ 51 CLScheduler &operator=(const CLScheduler &) = delete; 52 /** Default destructor */ 53 ~CLScheduler() = default; 54 /** Access the scheduler singleton. 55 * This method has been deprecated and will be removed in future releases 56 * @return The scheduler 57 */ 58 static CLScheduler &get(); 59 /** Initialises the context and command queue used by the scheduler to default values 60 * and sets a default device and kernel path for the @ref CLKernelLibrary. 61 * 62 * @param[in] cl_tuner (Optional) Pointer to ICLTuner (default=nullptr) 63 * @param[in] gemm_h (Optional) Pointer to CLGEMMHeuristicsHandle (default = nullptr) 64 * @param[in] cl_backend_type (Optional) Type of backend to use (default = CLBackendType::Native) 65 */ 66 void default_init(ICLTuner *cl_tuner = nullptr, CLGEMMHeuristicsHandle *gemm_h = nullptr, CLBackendType cl_backend_type = CLBackendType::Native); 67 /** Initialises the scheduler with context and device provided by the user 68 * 69 * @param[in] device OpenCL device to be used 70 * @param[in] ctx OpenCL ctx to be used 71 * @param[in] cl_tuner (Optional) Pointer to ICLTuner (default=nullptr) 72 * @param[in] gemm_h (Optional) Pointer to CLGEMMHeuristicsHandle (default = nullptr) 73 */ 74 void default_init_with_context(cl::Device &device, cl::Context &ctx, ICLTuner *cl_tuner = nullptr, CLGEMMHeuristicsHandle *gemm_h = nullptr); 75 76 /** Re-initializes the context and command queue used by the scheduler to default values 77 * and sets a default device and kernel path for the @ref CLKernelLibrary. 78 * 79 * @param[in] cl_tuner (Optional) Pointer to ICLTuner (default=nullptr) 80 * @param[in] gemm_h (Optional) Pointer to CLGEMMHeuristicsHandle (default = nullptr) 81 * @param[in] cl_backend_type (Optional) Type of backend to use (default = CLBackendType::Native) 82 */ 83 void default_reinit(ICLTuner *cl_tuner = nullptr, CLGEMMHeuristicsHandle *gemm_h = nullptr, CLBackendType cl_backend_type = CLBackendType::Native); 84 85 /** Schedule the execution of the passed kernel if possible. 86 * 87 * @param[in] kernel Kernel to execute. 88 * @param[in] flush (Optional) Specifies if the command queue will be flushed after running the kernel. This will be ignored if job chaining is enabled. 89 */ 90 void enqueue(ICLKernel &kernel, bool flush = true); 91 /** Schedule the execution of the passed kernel if possible. 92 * 93 * @param[in] kernel Kernel to execute. 94 * @param[in] tensors Vector containing the tensors to operate on. 95 * @param[in] flush (Optional) Specifies if the command queue will be flushed after running the kernel. This will be ignored if job chaining is enabled. 96 */ 97 void enqueue_op(ICLKernel &kernel, ITensorPack &tensors, bool flush = true); 98 /** Initialises the context and command queue to be used by the scheduler. 99 * 100 * @param[in] context A CL context. 101 * @param[in] queue A CL command queue. 102 * @param[in] device A CL device. 103 * @param[in] cl_tuner (Optional) Pointer to OpenCL tuner (default=nullptr) 104 * Note: It is caller's responsibility to release the allocated memory for CLTuner 105 * @param[in] gemm_h (Optional) Pointer to CLGEMMHeuristicsHandle (default = nullptr) 106 * @param[in] cl_backend_type (Optional) Type of backend to use (default = CLBackendType::Native) 107 */ 108 void init(cl::Context context, cl::CommandQueue queue, const cl::Device &device, ICLTuner *cl_tuner = nullptr, CLGEMMHeuristicsHandle *gemm_h = nullptr, 109 CLBackendType cl_backend_type = CLBackendType::Native); 110 111 /** Accessor for the associated CL context. 112 * 113 * @return A CL context. 114 */ 115 cl::Context &context(); 116 117 /** Accessor for the associated CL command queue. 118 * 119 * @return A CL command queue. 120 */ 121 cl::CommandQueue &queue(); 122 123 /** Get the target GPU. 124 * 125 * @return The target GPU. 126 */ 127 GPUTarget target() const; 128 129 /** Accessor for the associated CLGEMMHeuristicsHandle 130 * 131 * @return Pointer to CLGEMMHeuristicsHandle 132 */ 133 CLGEMMHeuristicsHandle *gemm_heuristics() const; 134 135 /** Accessor to set the CL context to be used by the scheduler. 136 * 137 * @param[in] context A CL context. 138 */ 139 void set_context(cl::Context context); 140 141 /** Accessor to set the CL command queue to be used by the scheduler. 142 * 143 * @param[in] queue A CL command queue. 144 */ 145 void set_queue(cl::CommandQueue queue); 146 147 /** Accessor to set target GPU to be used by the scheduler. 148 * 149 * @param[in] target The target GPU. 150 */ 151 void set_target(GPUTarget target); 152 153 /** Accessor to set the CL tuner to be used by the scheduler. 154 * 155 * @param[in] tuner A CL tuner 156 */ 157 void set_tuner(ICLTuner *tuner); 158 159 /** Blocks until all commands in the associated command queue have finished. */ 160 void sync(); 161 162 /** Enqueues a marker into the associated command queue and return the event. 163 * 164 * @return An event that can be waited on to block the executing thread. 165 */ 166 cl::Event enqueue_sync_event(); 167 168 /** Tunes OpenCL kernel 169 * 170 * @param[in] kernel Kernel to tune 171 */ 172 void tune_kernel_static(ICLKernel &kernel); 173 174 /** Enable job chaining. The command queue will only be flushed when @p job_chaining_size kernels have been enqueued. 175 * 176 * @param[in] job_chaining_size Kernels to enqueue before flushing 177 */ 178 void enable_job_chaining(int job_chaining_size); 179 180 bool is_initialised() const; 181 182 private: 183 void enqueue_common(ICLKernel &kernel, ITensorPack &tensors, bool flush); 184 /** If job chain is disabled, then flush the command queue according to @p flush. Otherwise @p flush is ignored and the queue is only flushed when job chain count exceeds allocated job chain size 185 * 186 * @param[in] flush Flush the command queue. Ignored when job chain is enabled. 187 */ 188 void flush_queue(bool flush); 189 190 /** Flag to ensure symbols initialisation is happening before Scheduler creation */ 191 static std::once_flag _initialize_symbols; 192 193 cl::Context _context; 194 cl::CommandQueue _queue; 195 GPUTarget _target; 196 bool _is_initialised; 197 ICLTuner *_cl_tuner; 198 CLGEMMHeuristicsHandle *_gemm_heuristics; 199 CLBackendType _backend_type; 200 bool _job_chaining_enabled; 201 int _job_chaining_size; 202 int _job_chaining_count; 203 }; 204 } // namespace arm_compute 205 #endif /* ARM_COMPUTE_CLSCHEDULER_H */ 206