inference-engine/include/ie_plugin.hpp

   1 // Copyright (C) 2018 Intel Corporation
   2 //
   3 // SPDX-License-Identifier: Apache-2.0
   4 //
   5
   6 /**
   7  * @brief A header file for Main Inference Engine API
   8  * @file ie_plugin.hpp
   9  */
  10 #pragma once
  11
  12 #include <ie_icnn_network.hpp>
  13 #include <ie_iextension.h>
  14 #include "ie_api.h"
  15 #include "details/ie_no_copy.hpp"
  16 #include "ie_error.hpp"
  17 #include "ie_version.hpp"
  18 #include "ie_iexecutable_network.hpp"
  19 #include <string>
  20 #include <vector>
  21 #include <memory>
  22 #include <map>
  23 #include <set>
  24
  25
  26 #if defined(_WIN32)
  27 #ifdef IMPLEMENT_INFERENCE_ENGINE_PLUGIN
  28 #define INFERENCE_PLUGIN_API(type) extern "C"   __declspec(dllexport) type
  29 #else
  30 #define INFERENCE_PLUGIN_API(type) extern "C" type
  31 #endif
  32
  33 #else
  34 #define INFERENCE_PLUGIN_API(TYPE) extern "C" TYPE
  35 #endif
  36
  37 namespace InferenceEngine {
  38
  39 /**
  40  * @brief Responce structure encapsulating information about supported layer
  41  */
  42 struct QueryNetworkResult {
  43     std::set<std::string> supportedLayers;
  44     StatusCode rc;
  45     ResponseDesc resp;
  46 };
  47
  48 /**
  49  * @brief This class is a main plugin interface
  50  */
  51 class IInferencePlugin : public details::IRelease {
  52 public:
  53     /**
  54      * @brief Returns plugin version information
  55      * @param versionInfo Pointer to version info. Is set by plugin
  56      */
  57     virtual void GetVersion(const Version *&versionInfo) noexcept = 0;
  58
  59     /**
  60      * @brief Sets logging callback
  61      * Logging is used to track what is going on inside
  62      * @param listener Logging sink
  63      */
  64     virtual void SetLogCallback(IErrorListener &listener) noexcept = 0;
  65
  66     /**
  67      * @deprecated use LoadNetwork with four parameters (executable network, cnn network, config, response)
  68      * @brief Loads a pre-built network with weights to the engine. In case of success the plugin will
  69      *        be ready to infer
  70      * @param network Network object acquired from CNNNetReader
  71      * @param resp Pointer to the response message that holds a description of an error if any occurred
  72      * @return Status code of the operation. OK if succeeded
  73      */
  74     virtual StatusCode LoadNetwork(ICNNNetwork &network, ResponseDesc *resp) noexcept = 0;
  75
  76     /**
  77      * @brief Creates an executable network from a network object. User can create as many networks as they need and use
  78      *        them simultaneously (up to the limitation of the hardware resources)
  79      * @param ret Reference to a shared ptr of the returned network interface
  80      * @param network Network object acquired from CNNNetReader
  81      * @param config Map of pairs: (config parameter name, config parameter value) relevant only for this load operation
  82      * @param resp Pointer to the response message that holds a description of an error if any occurred
  83      * @return Status code of the operation. OK if succeeded
  84      */
  85     virtual StatusCode
  86     LoadNetwork(IExecutableNetwork::Ptr &ret, ICNNNetwork &network, const std::map<std::string, std::string> &config,
  87                 ResponseDesc *resp) noexcept = 0;
  88
  89     /**
  90      * @brief Creates an executable network from a previously exported network
  91      * @param ret Reference to a shared ptr of the returned network interface
  92      * @param modelFileName Path to the location of the exported file
  93      * @param config Map of pairs: (config parameter name, config parameter value) relevant only for this load operation*
  94      * @param resp Pointer to the response message that holds a description of an error if any occurred
  95      * @return Status code of the operation. OK if succeeded
  96      */
  97     virtual StatusCode
  98     ImportNetwork(IExecutableNetwork::Ptr &ret, const std::string &modelFileName,
  99                   const std::map<std::string, std::string> &config, ResponseDesc *resp) noexcept = 0;
 100
 101     /**
 102      * @deprecated Uses Infer() working with multiple inputs and outputs
 103      * @brief Infers an image(s).
 104      * Input and output dimensions depend on the topology.
 105      *     As an example for classification topologies use a 4D Blob as input (batch, channels, width,
 106      *             height) and get a 1D blob as output (scoring probability vector). To Infer a batch,
 107      *             use a 4D Blob as input and get a 2D blob as output in both cases the method will
 108      *             allocate the resulted blob
 109      * @param input Any TBlob<> object that contains the data to infer. The type of TBlob must match the network input precision and size.
 110      * @param result Related TBlob<> object that contains the result of the inference action, typically this is a float blob.
 111                The blob does not need to be allocated or initialized, the engine allocates the relevant data.
 112      * @param resp Pointer to the response message that holds a description of an error if any occurred
 113      * @return Status code of the operation. OK if succeeded
 114      */
 115     virtual StatusCode Infer(const Blob &input, Blob &result, ResponseDesc *resp) noexcept = 0;
 116
 117     /**
 118      * @deprecated Loads IExecutableNetwork to create IInferRequest.
 119      * @brief Infers tensors. Input and output dimensions depend on the topology.
 120      *     As an example for classification topologies use a 4D Blob as input (batch, channels, width,
 121      *             height) and get a 1D blob as output (scoring probability vector). To Infer a batch,
 122      *             use a 4D Blob as input and get a 2D blob as output in both cases the method will
 123      *             allocate the resulted blob
 124      * @param input Map of input blobs accessed by input names
 125      * @param result Map of output blobs accessed by output names
 126      * @param resp Pointer to the response message that holds a description of an error if any occurred
 127      * @return Status code of the operation. OK if succeeded
 128      */
 129     virtual StatusCode Infer(const BlobMap &input, BlobMap &result, ResponseDesc *resp) noexcept = 0;
 130
 131     /**
 132      * @deprecated Uses IInferRequest to get performance measures
 133      * @brief Queries performance measures per layer to get feedback of what is the most time consuming layer
 134      *  Note: not all plugins provide meaningful data
 135      * @param perfMap Map of layer names to profiling information for that layer
 136      * @param resp Pointer to the response message that holds a description of an error if any occurred
 137      * @return Status code of the operation. OK if succeeded
 138      */
 139     virtual StatusCode GetPerformanceCounts(std::map<std::string, InferenceEngineProfileInfo> &perfMap,
 140                                             ResponseDesc *resp) const noexcept = 0;
 141
 142     /**
 143      * @brief Registers extension within the plugin
 144      * @param extension Pointer to already loaded extension
 145      * @param resp Pointer to the response message that holds a description of an error if any occurred
 146      * @return Status code of the operation. OK if succeeded
 147      */
 148     virtual StatusCode AddExtension(InferenceEngine::IExtensionPtr extension,
 149                                     InferenceEngine::ResponseDesc *resp) noexcept = 0;
 150
 151     /**
 152      * @brief Sets configuration for plugin, acceptable keys can be found in ie_plugin_config.hpp
 153      * @param config Map of pairs: (config parameter name, config parameter value)
 154      * @param resp Pointer to the response message that holds a description of an error if any occurred
 155      */
 156     virtual StatusCode SetConfig(const std::map<std::string, std::string> &config, ResponseDesc *resp) noexcept = 0;
 157
 158
 159     /**
 160      * @depricated Use the version with config parameter
 161      * @brief Query plugin if it supports specified network
 162      * @param network Network object to query
 163      * @param resp Pointer to the response message that holds a description of an error if any occurred
 164      */
 165     virtual void QueryNetwork(const ICNNNetwork& network, QueryNetworkResult& res) const noexcept {
 166         res.rc = InferenceEngine::NOT_IMPLEMENTED;
 167     }
 168
 169     /**
 170      * @brief Query plugin if it supports specified network with specified configuration
 171      * @param network Network object to query
 172      * @param config Map of pairs: (config parameter name, config parameter value)
 173      * @param resp Pointer to the response message that holds a description of an error if any occurred
 174      */
 175     virtual void QueryNetwork(const ICNNNetwork& network,
 176                               const std::map<std::string, std::string> &config, QueryNetworkResult& res) const noexcept {
 177         res.rc = InferenceEngine::NOT_IMPLEMENTED;
 178     }
 179 };
 180
 181 /**
 182  * @brief Creates the default instance of the interface (per plugin)
 183  * @param plugin Pointer to the plugin
 184  * @param resp Pointer to the response message that holds a description of an error if any occurred
 185  * @return Status code of the operation. OK if succeeded
 186  */
 187 INFERENCE_PLUGIN_API(StatusCode) CreatePluginEngine(IInferencePlugin *&plugin, ResponseDesc *resp) noexcept;
 188 }  // namespace InferenceEngine