inference-engine/include/ie_core.hpp

   1 // Copyright (C) 2018-2020 Intel Corporation
   2 // SPDX-License-Identifier: Apache-2.0
   3 //
   4
   5 /**
   6  * @brief This is a header file for the Inference Engine Core class C++ API
   7  *
   8  * @file ie_core.hpp
   9  */
  10 #pragma once
  11
  12 #include <map>
  13 #include <memory>
  14 #include <string>
  15 #include <vector>
  16
  17 #include "cpp/ie_plugin_cpp.hpp"
  18 #include "details/os/os_filesystem.hpp"
  19 #include "ie_extension.h"
  20 #include "ie_remote_context.hpp"
  21
  22 namespace InferenceEngine {
  23
  24 /**
  25  * @brief This class represents Inference Engine Core entity.
  26  *
  27  * It can throw exceptions safely for the application, where it is properly handled.
  28  */
  29 class INFERENCE_ENGINE_API_CLASS(Core) {
  30     class Impl;
  31     std::shared_ptr<Impl> _impl;
  32
  33 public:
  34     /** @brief Constructs Inference Engine Core instance using XML configuration file with
  35      * plugins description.
  36      *
  37      * See RegisterPlugins for more details.
  38      *
  39      * @param xmlConfigFile A path to .xml file with plugins to load from. If XML configuration file is not specified,
  40      * then default Inference Engine plugins are loaded from the default plugin.xml file.
  41      */
  42     explicit Core(const std::string& xmlConfigFile = std::string());
  43
  44     /**
  45      * @brief Returns plugins version information
  46      *
  47      * @param deviceName Device name to indentify plugin
  48      * @return A vector of versions
  49      */
  50     std::map<std::string, Version> GetVersions(const std::string& deviceName) const;
  51
  52     /**
  53      * @brief Sets logging callback
  54      *
  55      * Logging is used to track what is going on inside the plugins, Inference Engine library
  56      *
  57      * @param listener Logging sink
  58      */
  59     void SetLogCallback(IErrorListener& listener) const;
  60
  61 #ifdef ENABLE_UNICODE_PATH_SUPPORT
  62     /**
  63      * @brief Reads IR xml and bin files
  64      * @param modelPath path to IR file
  65      * @param binPath path to bin file, if path is empty, will try to read bin file with the same name as xml and
  66      * if bin file with the same name was not found, will load IR without weights.
  67      * @return CNNNetwork
  68      */
  69     CNNNetwork ReadNetwork(const std::wstring& modelPath, const std::wstring& binPath = std::wstring()) const {
  70         return ReadNetwork(details::wStringtoMBCSstringChar(modelPath), details::wStringtoMBCSstringChar(binPath));
  71     }
  72 #endif
  73
  74     /**
  75      * @brief Reads IR xml and bin files
  76      * @param modelPath path to IR file
  77      * @param binPath path to bin file, if path is empty, will try to read bin file with the same name as xml and
  78      * if bin file with the same name was not found, will load IR without weights.
  79      * @return CNNNetwork
  80      */
  81     CNNNetwork ReadNetwork(const std::string& modelPath, const std::string& binPath = "") const;
  82     /**
  83      * @brief Reads IR xml and bin (with the same name) files
  84      * @param model string with IR
  85      * @param weights shared pointer to constant blob with weights
  86      * @return CNNNetwork
  87      */
  88     CNNNetwork ReadNetwork(const std::string& model, const Blob::CPtr& weights) const;
  89
  90     /**
  91      * @brief Creates an executable network from a network object.
  92      *
  93      * Users can create as many networks as they need and use
  94      *        them simultaneously (up to the limitation of the hardware resources)
  95      *
  96      * @param network CNNNetwork object acquired from CNNNetReader
  97      * @param deviceName Name of device to load network to
  98      * @param config Optional map of pairs: (config parameter name, config parameter value) relevant only for this load
  99      * operation
 100      * @return An executable network reference
 101      */
 102     ExecutableNetwork LoadNetwork(
 103         CNNNetwork network, const std::string& deviceName,
 104         const std::map<std::string, std::string>& config = std::map<std::string, std::string>());
 105
 106     /**
 107      * @brief Registers extension
 108      * @param extension Pointer to already loaded extension
 109      */
 110     void AddExtension(const IExtensionPtr& extension);
 111
 112     /**
 113      * @brief Creates an executable network from a network object within a specified remote context.
 114      * @param network CNNNetwork object acquired from CNNNetReader
 115      * @param context Pointer to RemoteContext object
 116      * @param deviceName Name of device to load network to
 117      * @param config Optional map of pairs: (config parameter name, config parameter value) relevant only for this load
 118      * operation
 119      * @return An executable network reference
 120      */
 121     ExecutableNetwork LoadNetwork(
 122         CNNNetwork network, RemoteContext::Ptr context,
 123         const std::map<std::string, std::string>& config = std::map<std::string, std::string>());
 124
 125     /**
 126      * @brief Registers extension for the specified plugin
 127      *
 128      * @param extension Pointer to already loaded extension
 129      * @param deviceName Device name to identify plugin to add an executable extension
 130      */
 131     void AddExtension(IExtensionPtr extension, const std::string& deviceName);
 132
 133     /**
 134      * @brief Creates an executable network from a previously exported network
 135      *
 136      * @param deviceName Name of device load executable network on
 137      * @param modelFileName Path to the location of the exported file
 138      * @param config Optional map of pairs: (config parameter name, config parameter value) relevant only for this load
 139      * operation*
 140      * @return An executable network reference
 141      */
 142     ExecutableNetwork ImportNetwork(
 143         const std::string& modelFileName, const std::string& deviceName,
 144         const std::map<std::string, std::string>& config = std::map<std::string, std::string>());
 145
 146     /**
 147      * @brief Creates an executable network from a previously exported network
 148      * @param deviceName Name of device load executable network on
 149      * @param networkModel network model stream
 150      * @param config Optional map of pairs: (config parameter name, config parameter value) relevant only for this load
 151      * operation*
 152      * @return An executable network reference
 153      */
 154     ExecutableNetwork ImportNetwork(std::istream& networkModel, const std::string& deviceName = {},
 155                                     const std::map<std::string, std::string>& config = {});
 156
 157     /**
 158      * @brief Query device if it supports specified network with specified configuration
 159      *
 160      * @param deviceName A name of a device to query
 161      * @param network Network object to query
 162      * @param config Optional map of pairs: (config parameter name, config parameter value)
 163      * @return Pointer to the response message that holds a description of an error if any occurred
 164      */
 165     QueryNetworkResult QueryNetwork(
 166         const ICNNNetwork& network, const std::string& deviceName,
 167         const std::map<std::string, std::string>& config = std::map<std::string, std::string>()) const;
 168
 169     /**
 170      * @brief Sets configuration for device, acceptable keys can be found in ie_plugin_config.hpp
 171      *
 172      * @param deviceName An optinal name of a device. If device name is not specified, the config is set for all the
 173      * registered devices.
 174      *
 175      * @param config Map of pairs: (config parameter name, config parameter value)
 176      */
 177     void SetConfig(const std::map<std::string, std::string>& config, const std::string& deviceName = std::string());
 178
 179     /**
 180      * @brief Gets configuration dedicated to device behaviour.
 181      *
 182      * The method is targeted to extract information which can be set via SetConfig method.
 183      *
 184      * @param deviceName  - A name of a device to get a configuration value.
 185      * @param name  - value of config corresponding to config key.
 186      * @return Value of config corresponding to config key.
 187      */
 188     Parameter GetConfig(const std::string& deviceName, const std::string& name) const;
 189
 190     /**
 191      * @brief Gets general runtime metric for dedicated hardware.
 192      *
 193      * The method is needed to request common device properties
 194      * which are executable network agnostic. It can be device name, temperature, other devices-specific values.
 195      *
 196      * @param deviceName - A name of a device to get a metric value.
 197      * @param name - metric name to request.
 198      * @return Metric value corresponding to metric key.
 199      */
 200     Parameter GetMetric(const std::string& deviceName, const std::string& name) const;
 201
 202     /**
 203      * @brief Returns devices available for neural networks inference
 204      *
 205      * @return A vector of devices. The devices are returned as { CPU, FPGA.0, FPGA.1, MYRIAD }
 206        If there more than one device of specific type, they are enumerated with .# suffix.
 207      */
 208     std::vector<std::string> GetAvailableDevices() const;
 209
 210     /**
 211      * @brief Register new device and plugin which implement this device inside Inference Engine.
 212      *
 213      * @param pluginName A name of plugin. Depending on platform pluginName is wrapped with shared library suffix and
 214      * prefix to identify library full name
 215      *
 216      * @param deviceName A device name to register plugin for. If device name is not specified, then it's taken from
 217      * plugin using InferenceEnginePluginPtr::GetName function
 218      */
 219     void RegisterPlugin(const std::string& pluginName, const std::string& deviceName);
 220
 221     /**
 222      * @brief Unloads previously loaded plugin with a specified name from Inference Engine
 223      * The method is needed to remove plugin instance and free its resources. If plugin for a
 224      * specified device has not been created before, the method throws an exception.
 225      *
 226      * @param deviceName Device name identifying plugin to remove from Inference Engine
 227      */
 228     void UnregisterPlugin(const std::string& deviceName);
 229
 230     /** @brief Registers plugin to Inference Engine Core instance using XML configuration file with
 231      * plugins description.
 232      *
 233      *  XML file has the following structure:
 234      *
 235      * ```xml
 236      * <ie>
 237      *     <plugins>
 238      *         <plugin name="" location="">
 239      *             <extensions>
 240      *                 <extension location=""/>
 241      *             </extensions>
 242      *             <properties>
 243      *                 <property key="" value=""/>
 244      *             </properties>
 245      *         </plugin>
 246      *     </plugins>
 247      * </ie>
 248      * ```
 249      *
 250      * - `name` identifies name of device enabled by plugin
 251      * - `location` specifies absolute path to dynamic library with plugin. A path can also be relative to inference
 252      * engine shared library. It allows to have common config for different systems with different configurations.
 253      * - Properties are set to plugin via the `SetConfig` method.
 254      * - Extensions are set to plugin via the `AddExtension` method.
 255      *
 256      * @param xmlConfigFile A path to .xml file with plugins to register.
 257      */
 258     void RegisterPlugins(const std::string& xmlConfigFile);
 259
 260     /**
 261      * @brief Create a new shared context object on specified accelerator device
 262      * using specified plugin-specific low level device API parameters (device handle, pointer, etc.)
 263      * @param deviceName Name of a device to create new shared context on.
 264      * @param params Map of device-specific shared context parameters.
 265      */
 266     RemoteContext::Ptr CreateContext(const std::string& deviceName, const ParamMap& params);
 267
 268     /**
 269      * @brief Get a pointer to default(plugin-supplied) shared context object for specified accelerator device.
 270      * @param deviceName  - A name of a device to get create shared context from.
 271      */
 272     RemoteContext::Ptr GetDefaultContext(const std::string& deviceName);
 273 };
 274 }  // namespace InferenceEngine