inference-engine/include/ie_plugin_config.hpp

   1 // Copyright (C) 2018-2020 Intel Corporation
   2 // SPDX-License-Identifier: Apache-2.0
   3 //
   4
   5 /**
   6  * @brief a header for advanced hardware related properties for IE plugins
   7  *
   8  *        To use in SetConfig() method of plugins
   9  *        LoadNetwork() method overloads that accept config as parameter
  10  *
  11  * @file ie_plugin_config.hpp
  12  */
  13 #pragma once
  14
  15 #include <string>
  16 #include <tuple>
  17 #include <vector>
  18
  19 namespace InferenceEngine {
  20
  21 /**
  22  * @brief %Metrics
  23  */
  24 namespace Metrics {
  25
  26 #ifndef DECLARE_METRIC_KEY_IMPL
  27 #define DECLARE_METRIC_KEY_IMPL(...)
  28 #endif
  29
  30 /**
  31  * @def METRIC_KEY(name)
  32  * @brief shortcut for defining common Inference Engine metrics
  33  */
  34 #define METRIC_KEY(name) InferenceEngine::Metrics::METRIC_##name
  35
  36 /**
  37  * @def EXEC_NETWORK_METRIC_KEY(name)
  38  * @brief shortcut for defining common Inference Engine ExecutableNetwork metrics
  39  */
  40 #define EXEC_NETWORK_METRIC_KEY(name) METRIC_KEY(name)
  41
  42 #define DECLARE_METRIC_KEY(name, ...)            \
  43     static constexpr auto METRIC_##name = #name; \
  44     DECLARE_METRIC_KEY_IMPL(name, __VA_ARGS__)
  45
  46 #define DECLARE_EXEC_NETWORK_METRIC_KEY(name, ...) DECLARE_METRIC_KEY(name, __VA_ARGS__)
  47
  48 /**
  49  * @def METRIC_VALUE(name)
  50  * @brief shortcut for defining metric values
  51  */
  52 #define METRIC_VALUE(name) InferenceEngine::Metrics::name
  53 #define DECLARE_METRIC_VALUE(name) static constexpr auto name = #name
  54
  55 /**
  56  * @brief Metric to get a std::vector<std::string> of available device IDs. String value is "AVAILABLE_DEVICES"
  57  */
  58 DECLARE_METRIC_KEY(AVAILABLE_DEVICES, std::vector<std::string>);
  59
  60 /**
  61  * @brief Metric to get a std::vector<std::string> of supported metrics. String value is "SUPPORTED_METRICS"
  62  *
  63  * This can be used as an executable network metric as well.
  64  *
  65  * Each of the returned device metrics can be passed to Core::GetMetric, executable network metrics
  66  * can be passed to ExecutableNetwork::GetMetric.
  67  *
  68  */
  69 DECLARE_METRIC_KEY(SUPPORTED_METRICS, std::vector<std::string>);
  70
  71 /**
  72  * @brief Metric to get a std::vector<std::string> of supported config keys. String value is "SUPPORTED_CONFIG_KEYS"
  73  *
  74  * This can be used as an executable network metric as well.
  75  *
  76  * Each of the returned device configuration keys can be passed to Core::SetConfig, Core::GetConfig, and
  77  * Core::LoadNetwork, configuration keys for executable networks can be passed to ExecutableNetwork::SetConfig and
  78  * ExecutableNetwork::GetConfig.
  79  *
  80  */
  81 DECLARE_METRIC_KEY(SUPPORTED_CONFIG_KEYS, std::vector<std::string>);
  82
  83 /**
  84  * @brief Metric to get a std::string value representing a full device name. String value is "FULL_DEVICE_NAME"
  85  */
  86 DECLARE_METRIC_KEY(FULL_DEVICE_NAME, std::string);
  87
  88 /**
  89  * @brief Metric to get a std::vector<std::string> of optimization options per device. String value is
  90  * "OPTIMIZATION_CAPABILITIES"
  91  *
  92  * The possible values:
  93  *  - "FP32" - device can support FP32 models
  94  *  - "FP16" - device can support FP16 models
  95  *  - "INT8" - device can support models with INT8 layers
  96  *  - "BIN" - device can support models with BIN layers
  97  *  - "WINOGRAD" - device can support models where convolution implemented via Winograd transformations
  98  */
  99 DECLARE_METRIC_KEY(OPTIMIZATION_CAPABILITIES, std::vector<std::string>);
 100
 101 DECLARE_METRIC_VALUE(FP32);
 102 DECLARE_METRIC_VALUE(FP16);
 103 DECLARE_METRIC_VALUE(INT8);
 104 DECLARE_METRIC_VALUE(BIN);
 105 DECLARE_METRIC_VALUE(WINOGRAD);
 106
 107 /**
 108  * @brief Metric to provide information about a range for streams on platforms where streams are supported.
 109  *
 110  * Metric returns a value of std::tuple<unsigned int, unsigned int> type, where:
 111  *  - First value is bottom bound.
 112  *  - Second value is upper bound.
 113  * String value for metric name is "RANGE_FOR_STREAMS".
 114  */
 115 DECLARE_METRIC_KEY(RANGE_FOR_STREAMS, std::tuple<unsigned int, unsigned int>);
 116
 117 /**
 118  * @brief Metric to provide a hint for a range for number of async infer requests. If device supports streams,
 119  * the metric provides range for number of IRs per stream.
 120  *
 121  * Metric returns a value of std::tuple<unsigned int, unsigned int, unsigned int> type, where:
 122  *  - First value is bottom bound.
 123  *  - Second value is upper bound.
 124  *  - Third value is step inside this range.
 125  * String value for metric name is "RANGE_FOR_ASYNC_INFER_REQUESTS".
 126  */
 127 DECLARE_METRIC_KEY(RANGE_FOR_ASYNC_INFER_REQUESTS, std::tuple<unsigned int, unsigned int, unsigned int>);
 128
 129 /**
 130  * @brief Metric to get an unsigned int value of number of waiting infer request.
 131  *
 132  * String value is "NUMBER_OF_WAITNING_INFER_REQUESTS". This can be used as an executable network metric as well
 133  */
 134 DECLARE_METRIC_KEY(NUMBER_OF_WAITING_INFER_REQUESTS, unsigned int);
 135
 136 /**
 137  * @brief Metric to get an unsigned int value of number of infer request in execution stage.
 138  *
 139  * String value is "NUMBER_OF_EXEC_INFER_REQUESTS". This can be used as an executable network metric as well
 140  */
 141 DECLARE_METRIC_KEY(NUMBER_OF_EXEC_INFER_REQUESTS, unsigned int);
 142
 143 /**
 144  * @brief Metric to get a name of network. String value is "NETWORK_NAME".
 145  */
 146 DECLARE_EXEC_NETWORK_METRIC_KEY(NETWORK_NAME, std::string);
 147
 148 /**
 149  * @brief  Metric to get a float of device thermal. String value is "DEVICE_THERMAL"
 150  */
 151 DECLARE_METRIC_KEY(DEVICE_THERMAL, float);
 152
 153 /**
 154  * @brief Metric to get an unsigned integer value of optimal number of executable network infer requests.
 155  */
 156 DECLARE_EXEC_NETWORK_METRIC_KEY(OPTIMAL_NUMBER_OF_INFER_REQUESTS, unsigned int);
 157
 158 }  // namespace Metrics
 159
 160 /**
 161  * @brief Generic plugin configuration
 162  */
 163 namespace PluginConfigParams {
 164
 165 /**
 166  * @def CONFIG_KEY(name)
 167  * @brief shortcut for defining configuration keys
 168  */
 169 #define CONFIG_KEY(name) InferenceEngine::PluginConfigParams::_CONFIG_KEY(name)
 170 #define _CONFIG_KEY(name) KEY_##name
 171 #define DECLARE_CONFIG_KEY(name) static constexpr auto _CONFIG_KEY(name) = #name
 172
 173 /**
 174  * @def CONFIG_VALUE(name)
 175  * @brief shortcut for defining configuration values
 176  */
 177 #define CONFIG_VALUE(name) InferenceEngine::PluginConfigParams::name
 178 #define DECLARE_CONFIG_VALUE(name) static constexpr auto name = #name
 179
 180 /**
 181  * @brief generic boolean values
 182  */
 183 DECLARE_CONFIG_VALUE(YES);
 184 DECLARE_CONFIG_VALUE(NO);
 185
 186 /**
 187  * @brief Limit #threads that are used by Inference Engine for inference on the CPU.
 188  */
 189 DECLARE_CONFIG_KEY(CPU_THREADS_NUM);
 190
 191 /**
 192  * @brief The name for setting CPU affinity per thread option.
 193  *
 194  * It is passed to IInferencePlugin::SetConfig(), this option should be used with values:
 195  * PluginConfigParams::YES (pinning threads to cores, best for static benchmarks),
 196  * PluginConfigParams::NUMA (pinning therads to NUMA nodes, best for real-life, contented cases)
 197  * this is TBB-specific knob, and the only pinning option (beyond 'NO', below) on the Windows*
 198  * PluginConfigParams::NO (no pinning for CPU inference threads)
 199  * All settings are ignored, if the OpenVINO compiled with OpenMP threading and any affinity-related OpenMP's
 200  * environment variable is set (as affinity is configured explicitly)
 201  */
 202 DECLARE_CONFIG_KEY(CPU_BIND_THREAD);
 203 DECLARE_CONFIG_VALUE(NUMA);
 204
 205 /**
 206  * @brief Optimize CPU execution to maximize throughput.
 207  *
 208  * It is passed to IInferencePlugin::SetConfig(), this option should be used with values:
 209  * - KEY_CPU_THROUGHPUT_NUMA creates as many streams as needed to accomodate NUMA and avoid associated penalties
 210  * - KEY_CPU_THROUGHPUT_AUTO creates bare minimum of streams to improve the performance,
 211  *   this is the most portable option if you have no insights into how many cores you target machine will have
 212  *   (and what is the optimal number of streams)
 213  * - finally, specifying the positive integer value creates the requested number of streams
 214  */
 215 DECLARE_CONFIG_VALUE(CPU_THROUGHPUT_NUMA);
 216 DECLARE_CONFIG_VALUE(CPU_THROUGHPUT_AUTO);
 217 DECLARE_CONFIG_KEY(CPU_THROUGHPUT_STREAMS);
 218
 219 /**
 220  * @brief Optimize GPU plugin execution to maximize throughput.
 221  *
 222  * It is passed to IInferencePlugin::SetConfig(), this option should be used with values:
 223  * - KEY_GPU_THROUGHPUT_AUTO creates bare minimum of streams that might improve performance in some cases,
 224  *   this option allows to enable throttle hint for opencl queue thus reduce CPU load without significant performance
 225  * drop
 226  * - a positive integer value creates the requested number of streams
 227  */
 228 DECLARE_CONFIG_VALUE(GPU_THROUGHPUT_AUTO);
 229 DECLARE_CONFIG_KEY(GPU_THROUGHPUT_STREAMS);
 230
 231 /**
 232  * @brief The name for setting performance counters option.
 233  *
 234  * It is passed to IInferencePlugin::SetConfig(), this option should be used with values:
 235  * PluginConfigParams::YES or PluginConfigParams::NO
 236  */
 237 DECLARE_CONFIG_KEY(PERF_COUNT);
 238
 239 /**
 240  * @brief The key defines dynamic limit of batch processing.
 241  *
 242  * Specified value is applied to all following Infer() calls. Inference Engine processes
 243  * min(batch_limit, original_batch_size) first pictures from input blob. For example, if input
 244  * blob has sizes 32x3x224x224 after applying plugin.SetConfig({KEY_DYN_BATCH_LIMIT, 10})
 245  * Inference Engine primitives processes only beginner subblobs with size 10x3x224x224.
 246  * This value can be changed before any Infer() call to specify a new batch limit.
 247  *
 248  * The paired parameter value should be convertible to integer number. Acceptable values:
 249  * -1 - Do not limit batch processing
 250  * >0 - Direct value of limit. Batch size to process is min(new batch_limit, original_batch)
 251  */
 252 DECLARE_CONFIG_KEY(DYN_BATCH_LIMIT);
 253
 254 DECLARE_CONFIG_KEY(DYN_BATCH_ENABLED);
 255
 256 DECLARE_CONFIG_KEY(DUMP_QUANTIZED_GRAPH_AS_DOT);
 257 DECLARE_CONFIG_KEY(DUMP_QUANTIZED_GRAPH_AS_IR);
 258
 259 /**
 260  * @brief The key controls threading inside Inference Engine.
 261  *
 262  * It is passed to IInferencePlugin::SetConfig(), this option should be used with values:
 263  * PluginConfigParams::YES or PluginConfigParams::NO
 264  */
 265 DECLARE_CONFIG_KEY(SINGLE_THREAD);
 266
 267 /**
 268  * @brief This key directs the plugin to load a configuration file.
 269  *
 270  * The value should be a file name with the plugin specific configuration
 271  */
 272 DECLARE_CONFIG_KEY(CONFIG_FILE);
 273
 274 /**
 275  * @brief This key enables dumping of the kernels used by the plugin for custom layers.
 276  *
 277  * This option should be used with values: PluginConfigParams::YES or PluginConfigParams::NO (default)
 278  */
 279 DECLARE_CONFIG_KEY(DUMP_KERNELS);
 280
 281 /**
 282  * @brief This key controls performance tuning done or used by the plugin.
 283  *
 284  * This option should be used with values: PluginConfigParams::TUNING_CREATE,
 285  * PluginConfigParams::TUNING_USE_EXISTING or PluginConfigParams::TUNING_DISABLED (default)
 286  */
 287 DECLARE_CONFIG_KEY(TUNING_MODE);
 288
 289 DECLARE_CONFIG_VALUE(TUNING_CREATE);
 290 DECLARE_CONFIG_VALUE(TUNING_USE_EXISTING);
 291 DECLARE_CONFIG_VALUE(TUNING_DISABLED);
 292
 293 /**
 294  * @brief This key defines the tuning data filename to be created/used
 295  */
 296 DECLARE_CONFIG_KEY(TUNING_FILE);
 297
 298 /**
 299  * @brief the key for setting desirable log level.
 300  *
 301  * This option should be used with values: PluginConfigParams::LOG_NONE (default),
 302  * PluginConfigParams::LOG_ERROR, PluginConfigParams::LOG_WARNING,
 303  * PluginConfigParams::LOG_INFO, PluginConfigParams::LOG_DEBUG, PluginConfigParams::LOG_TRACE
 304  */
 305 DECLARE_CONFIG_KEY(LOG_LEVEL);
 306
 307 DECLARE_CONFIG_VALUE(LOG_NONE);     // turn off logging
 308 DECLARE_CONFIG_VALUE(LOG_ERROR);    // error events that might still allow the application to continue running
 309 DECLARE_CONFIG_VALUE(LOG_WARNING);  // potentially harmful situations which may further lead to ERROR
 310 DECLARE_CONFIG_VALUE(
 311     LOG_INFO);  // informational messages that display the progress of the application at coarse-grained level
 312 DECLARE_CONFIG_VALUE(LOG_DEBUG);  // fine-grained events that are most useful to debug an application.
 313 DECLARE_CONFIG_VALUE(LOG_TRACE);  // finer-grained informational events than the DEBUG
 314
 315 /**
 316  * @brief the key for setting of required device to execute on
 317  * values: device id starts from "0" - first device, "1" - second device, etc
 318  */
 319 DECLARE_CONFIG_KEY(DEVICE_ID);
 320
 321 /**
 322  * @brief the key for enabling exclusive mode for async requests of different executable networks and the same plugin.
 323  *
 324  * Sometimes it is necessary to avoid oversubscription requests that are sharing the same device in parallel.
 325  * E.g. There 2 task executors for CPU device: one - in the Hetero plugin, another - in pure CPU plugin.
 326  * Parallel execution both of them might lead to oversubscription and not optimal CPU usage. More efficient
 327  * to run the corresponding tasks one by one via single executor.
 328  * By default, the option is set to YES for hetero cases, and to NO for conventional (single-plugin) cases
 329  * Notice that setting YES disables the CPU streams feature (see another config key in this file)
 330  */
 331 DECLARE_CONFIG_KEY(EXCLUSIVE_ASYNC_REQUESTS);
 332
 333 /**
 334  * @brief This key enables dumping of the internal primitive graph.
 335  *
 336  * Should be passed into LoadNetwork method to enable dumping of internal graph of primitives and
 337  * corresponding configuration information. Value is a name of output dot file without extension.
 338  * Files <dot_file_name>_init.dot and <dot_file_name>_perf.dot will be produced.
 339  */
 340 DECLARE_CONFIG_KEY(DUMP_EXEC_GRAPH_AS_DOT);
 341
 342 }  // namespace PluginConfigParams
 343 }  // namespace InferenceEngine