inference-engine/thirdparty/clDNN/api/CPP/engine.hpp

   1 /*
   2 // Copyright (c) 2016 Intel Corporation
   3 //
   4 // Licensed under the Apache License, Version 2.0 (the "License");
   5 // you may not use this file except in compliance with the License.
   6 // You may obtain a copy of the License at
   7 //
   8 //      http://www.apache.org/licenses/LICENSE-2.0
   9 //
  10 // Unless required by applicable law or agreed to in writing, software
  11 // distributed under the License is distributed on an "AS IS" BASIS,
  12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 // See the License for the specific language governing permissions and
  14 // limitations under the License.
  15 */
  16
  17 ///////////////////////////////////////////////////////////////////////////////////////////////////
  18 #pragma once
  19 #include "cldnn_defs.h"
  20
  21 namespace cldnn
  22 {
  23
  24 /// @addtogroup cpp_api C++ API
  25 /// @{
  26
  27 /// @defgroup cpp_engine Execution Engine
  28 /// @{
  29
  30 /// @brief Defines available engine types
  31 enum class engine_types : int32_t
  32 {
  33     ocl = cldnn_engine_ocl
  34 };
  35
  36 /// @brief Defines available priority mode types
  37 enum class priority_mode_types : int16_t
  38 {
  39     disabled = cldnn_priority_disabled,
  40     low = cldnn_priority_low,
  41     med = cldnn_priority_med,
  42     high = cldnn_priority_high
  43 };
  44
  45 /// @brief Defines available priority mode types
  46 enum class throttle_mode_types : int16_t
  47 {
  48     disabled = cldnn_throttle_disabled,
  49     low = cldnn_throttle_low,
  50     med = cldnn_throttle_med,
  51     high = cldnn_throttle_high
  52 };
  53
  54 /// @brief Configuration parameters for created engine.
  55 struct engine_configuration
  56 {
  57     const bool enable_profiling;                ///< Enable per-primitive profiling.
  58     const bool meaningful_kernels_names;        ///< Generate meaniful names fo OpenCL kernels.
  59     const bool dump_custom_program;             ///< Dump the user OpenCL programs to files
  60     const std::string compiler_options;         ///< OpenCL compiler options string.
  61     const std::string single_kernel_name;       ///< If provided, runs specific layer.
  62     const bool enable_parallelisation;          ///< Enables parallel execution of primitives which don't depend on each other. Disabled by default.
  63     const std::string engine_log;               ///< Specifies a file to which engine log should be dumped. Empty by default (means no logging).
  64     const std::string sources_dumps_dir;        ///< Specifies a directory where sources of cldnn::program objects should be dumped. Empty by default (means no dumping).
  65     const priority_mode_types priority_mode;    ///< Priority mode (support of priority hints in command queue). If cl_khr_priority_hints extension is not supported by current OpenCL implementation, the value must be set to cldnn_priority_disabled.
  66
  67     const throttle_mode_types throttle_mode;    ///< Throttle mode (support of throttle hints in command queue). If cl_khr_throttle_hints extension is not supported by current OpenCL implementation, the value must be set to cldnn_throttle_disabled.
  68
  69     bool enable_memory_pool;                    ///< Enables memory usage optimization. memory objects will be reused when possible (switched off for older drivers then NEO).
  70     void* context;              ///< Pointer to user context
  71     const std::string tuning_cache_path;        ///< Path to tuning kernel cache
  72
  73     /// @brief Constructs engine configuration with specified options.
  74     /// @param profiling Enable per-primitive profiling.
  75     /// @param decorate_kernel_names Generate meaniful names fo OpenCL kernels.
  76     /// @param dump_custom_program Dump the custom OpenCL programs to files
  77     /// @param options OpenCL compiler options string.
  78     /// @param single_kernel If provided, runs specific layer.
  79     engine_configuration(
  80             bool profiling = false,
  81             bool decorate_kernel_names = false,
  82             bool dump_custom_program = false,
  83             const std::string& options = std::string(),
  84             const std::string& single_kernel = std::string(),
  85             bool primitives_parallelisation = true,
  86             const std::string& engine_log = std::string(),
  87             const std::string& sources_dumps_dir = std::string(),
  88             priority_mode_types priority_mode = priority_mode_types::disabled,
  89             throttle_mode_types throttle_mode = throttle_mode_types::disabled,
  90             bool memory_pool = true,
  91             void* context = nullptr,
  92             const std::string& tuning_cache_path = "cache.json")
  93         : enable_profiling(profiling)
  94         , meaningful_kernels_names(decorate_kernel_names)
  95         , dump_custom_program(dump_custom_program)
  96         , compiler_options(options)
  97         , single_kernel_name(single_kernel)
  98         , enable_parallelisation(primitives_parallelisation)
  99         , engine_log(engine_log)
 100         , sources_dumps_dir(sources_dumps_dir)
 101         , priority_mode(priority_mode)
 102         , throttle_mode(throttle_mode)
 103         , enable_memory_pool(memory_pool)
 104         , context(context)
 105         , tuning_cache_path(tuning_cache_path)
 106     {}
 107
 108     engine_configuration(const cldnn_engine_configuration& c_conf)
 109         : enable_profiling(c_conf.enable_profiling != 0)
 110         , meaningful_kernels_names(c_conf.meaningful_kernels_names != 0)
 111         , dump_custom_program(c_conf.dump_custom_program != 0)
 112         , compiler_options(c_conf.compiler_options)
 113         , single_kernel_name(c_conf.single_kernel_name)
 114         , enable_parallelisation(c_conf.enable_parallelisation != 0)
 115         , engine_log(c_conf.engine_log)
 116         , sources_dumps_dir(c_conf.sources_dumps_dir)
 117         , priority_mode(static_cast<priority_mode_types>(c_conf.priority_mode))
 118         , throttle_mode(static_cast<throttle_mode_types>(c_conf.throttle_mode))
 119         , enable_memory_pool(c_conf.enable_memory_pool != 0)
 120         , context(c_conf.context)
 121                 , tuning_cache_path(c_conf.tuning_cache_path)
 122     {}
 123
 124     /// @brief Implicit conversion to C API @ref ::cldnn_engine_configuration
 125     operator ::cldnn_engine_configuration() const
 126     {
 127         return{
 128             enable_profiling,
 129             meaningful_kernels_names,
 130             dump_custom_program,
 131             compiler_options.c_str(),
 132             single_kernel_name.c_str(),
 133             enable_parallelisation,
 134             engine_log.c_str(),
 135             sources_dumps_dir.c_str(),
 136             static_cast<int16_t>(priority_mode),
 137             static_cast<int16_t>(throttle_mode),
 138             enable_memory_pool,
 139             context,
 140             tuning_cache_path.c_str()
 141         };
 142     }
 143 };
 144
 145 /// @brief Information about the engine properties and capabilities.
 146 /// @details Look into @ref ::cldnn_engine_info for details.
 147 using engine_info = ::cldnn_engine_info;
 148
 149 /// @brief Represents clDNN engine object.
 150 struct engine
 151 {
 152     /// @brief Constructs @p OpenCL engine
 153     engine(const engine_configuration& configuration = engine_configuration())
 154         :engine(engine_types::ocl, 0, configuration)
 155     {}
 156
 157     /// @brief Construct engine of the specified @p type, @p engine_num, and @p configuration options.
 158     /// @param[in] type Engine type @ref cldnn_engine_type. Only OCL engine is supported.
 159     /// @param[in] engine_num Engine index. Should be 0.
 160     /// @param[in] configuration Pointer to engine configuration options.
 161     engine(engine_types type, uint32_t engine_num, const engine_configuration& configuration = engine_configuration())
 162         :_impl(check_status<::cldnn_engine>("failed to create engine", [&](status_t* status)
 163               {
 164                   cldnn_engine_configuration conf = configuration;
 165                   return cldnn_create_engine(static_cast<int32_t>(type), engine_num, &conf, status);
 166               }))
 167     {}
 168
 169     // TODO add move construction/assignment
 170     engine(const engine& other) :_impl(other._impl)
 171     {
 172         retain();
 173     }
 174
 175     engine& operator=(const engine& other)
 176     {
 177         if (_impl == other._impl) return *this;
 178         release();
 179         _impl = other._impl;
 180         retain();
 181         return *this;
 182     }
 183
 184     ~engine()
 185     {
 186         release();
 187     }
 188
 189     friend bool operator==(const engine& lhs, const engine& rhs) { return lhs._impl == rhs._impl; }
 190     friend bool operator!=(const engine& lhs, const engine& rhs) { return !(lhs == rhs); }
 191
 192     /// @brief Returns number of available engines of the particular @p type.
 193     static uint32_t engine_count(engine_types type)
 194     {
 195         return check_status<uint32_t>("engine_count failed", [=](status_t* status)
 196         {
 197             return cldnn_get_engine_count(static_cast<int32_t>(type), status);
 198         });
 199     }
 200
 201
 202     /// @brief Release pending memory allocated in OpenCL context.
 203     void release_pending_memory() const
 204     {
 205         check_status<void>("flush_memory failed", [=](status_t* status)
 206         {
 207             return cldnn_release_pending_memory(_impl, status);
 208         });
 209     }
 210
 211
 212     /// @brief Returns information about properties and capabilities for the engine.
 213     engine_info get_info() const
 214     {
 215         return check_status<engine_info>("engine_count failed", [=](status_t* status)
 216         {
 217             return cldnn_get_engine_info(_impl, status);
 218         });
 219     }
 220
 221     /// @brief Returns total size of all resources allocated using given engine
 222     uint64_t get_max_used_device_memory_size() const
 223     {
 224         return check_status<uint64_t>("get total device memory failed", [=](status_t* status)
 225         {
 226             return cldnn_get_max_used_device_memory_size(_impl, status);
 227         });
 228     }
 229
 230     /// @brief Returns total size of currently resources allocated using given engine
 231     uint64_t get_temp_used_device_memory_size() const
 232     {
 233         return check_status<uint64_t>("get device memory failed", [=](status_t* status)
 234         {
 235             return cldnn_get_temp_used_device_memory_size(_impl, status);
 236         });
 237     }
 238
 239     /// @brief Returns type of the engine.
 240     engine_types get_type() const
 241     {
 242         return check_status<engine_types>("engine_count failed", [=](status_t* status)
 243         {
 244             return static_cast<engine_types>(cldnn_get_engine_type(_impl, status));
 245         });
 246     }
 247
 248     /// @brief get C API engine handler.
 249     ::cldnn_engine get() const { return _impl; }
 250
 251 private:
 252     friend struct network;
 253     friend struct memory;
 254     friend struct event;
 255     engine(::cldnn_engine impl) : _impl(impl)
 256     {
 257         if (_impl == nullptr) throw std::invalid_argument("implementation pointer should not be null");
 258     }
 259     ::cldnn_engine _impl;
 260
 261     void retain()
 262     {
 263         check_status<void>("retain engine failed", [=](status_t* status) { cldnn_retain_engine(_impl, status); });
 264     }
 265     void release()
 266     {
 267         check_status<void>("release engine failed", [=](status_t* status) { cldnn_release_engine(_impl, status); });
 268     }
 269 };
 270 CLDNN_API_CLASS(engine)
 271
 272 /// @}
 273
 274 /// @}
 275
 276 }