Update adapataion layer API descriptions

Change-Id: Ibea8f1596775f63d2912a74e60714af5c7911d34
Signed-off-by: Inki Dae <inki.dae@samsung.com>

diff --git a/include/inference_engine_common.h b/include/inference_engine_common.h
index b16b2144456d0c3f81daf21f03b278d533e8ac14..40bb0aa8da67622844b4fa463877f46e183f377b 100755 (executable)
--- a/include/inference_engine_common.h
+++ b/include/inference_engine_common.h
@@ -33,71 +33,129 @@ public:
     /**
      * @brief Set target devices.
      * @details See #inference_target_type_e
+     *          This callback passes given device types - CPU, GPU, CUSTOM or combinated one if a backend engine supports hybrid inferencea - to a backend engine.
+     *          Some backend engine can optimize a given NN model at graph level such as dropping operation or fusing operations targating
+     *          a given device or devices when the backend engine loads the NN model file.
      *
      * @since_tizen 5.5
+     * @param[in] types This could be one or more among device types enumerated on inference_target_type_e.
      */
     virtual int SetTargetDevices(int types) = 0;
 
     /**
-     * @brief Load model data with user-given model information.
+     * @brief Request to load model data with user-given model file information.
+     * @details This callback requests a backend engine to load given model files for inference.
+     *          The backend engine should load the given model files according to a given model file format.
      *
      * @since_tizen 6.0
+     * @param[in] model_paths Upper framework should add full path strings needed according to a given model format.
+     * @param[in] model_format It indicates what kinds of model file should be passed to a backend engine.
      */
     virtual int Load(std::vector<std::string> model_paths, inference_model_format_e model_format) { return 0; }
 
     /**
      * @brief Get input tensor buffers from a given backend engine.
+     * @details This callback requests a backend engine input tensor buffers.
+     *          If the backend engine is able to allocate the input tensor buffers internally, then
+     *          it has to add the input tensor buffers to buffers vector. By doing this, upper layer
+     *          will request a inference with the input tensor buffers.
+     *          Otherwise, the backend engine should just return INFERENCE_ENGINE_ERROR_NONE so that
+     *          upper layer can allocate input tensor buffers according to input layer property.
+     *          As for the input layer property, you can see GetInputLyaerProperty callback.
      *
      * @since_tizen 6.0
+     * @param[out] buffers A backend engine should add input tensor buffers allocated itself to buffers vector.
+     *              Otherwise, it should put buffers to be empty.
      */
     virtual int GetInputTensorBuffers(std::vector<inference_engine_tensor_buffer> &buffers) = 0;
 
     /**
      * @brief Get output tensor buffers from a given backend engine.
+     * @details This callback requests a backend engine output tensor buffers.
+     *          If the backend engine is able to allocate the output tensor buffers internally, then
+     *          it has to add the output tensor buffers to buffers vector. By doing this, upper layer
+     *          will request a inference with the output tensor buffers.
+     *          Otherwise, the backend engine should just return INFERENCE_ENGINE_ERROR_NONE so that
+     *          upper layer can allocate output tensor buffers according to output layer property.
+     *          As for the output layer property, you can see GetOutputLyaerProperty callback.
      *
      * @since_tizen 6.0
+     * @param[out] buffers A backend engine should add output tensor buffers allocated itself to buffers vector.
+     *              Otherwise, it should put buffers to be empty.
      */
     virtual int GetOutputTensorBuffers(std::vector<inference_engine_tensor_buffer> &buffers) = 0;
 
     /**
      * @brief Get input layer property information from a given backend engine.
+     * @details This callback requests a backend engine information about given layers by
+     *          SetInputTensorProperty callback.
+     *          If user wants to specify input layer that the backend engine starts from
+     *          then user can call SetInputTensorProperty callback with desired layer information.
+     *          If user dosn't specify the input layer then the backend engine should add tensor information
+     *          of the first layer in model graph in default.
      *
      * @since_tizen 6.0
+     * @param[out] property A backend engine should add given tensor information to be used as input layer.
      */
     virtual int GetInputLayerProperty(inference_engine_layer_property &property) = 0;
 
     /**
      * @brief Get output layer property information from a given backend engine.
+     * @details This callback requests a backend engine information about given layers by
+     *          SetOutputTensorProperty callback.
+     *          If user wants to specify output layer that the backend engine stores the inference result
+     *          then user can call SetOutputTensorProperty callback with desired layer information.
+     *          If user dosn't specify the output layer then the backend engine should add tensor information
+     *          of the last layer in model graph in default.
      *
      * @since_tizen 6.0
+     * @param[out] property A backend engine should add given tensor information to be used as output layer.
      */
     virtual int GetOutputLayerProperty(inference_engine_layer_property &property) = 0;
 
     /**
      * @brief Set input layer property information to a given backend engine.
+     * @details This callback passes a given input layer information to a backend engine.
+     *          If user wants to start the inference from some given layer in model graph.
+     *          The backend engine should keep the input layer found with the given information
+     *          in model graph and then set the layer as input layer.
      *
      * @since_tizen 6.0
+     * @param[in] property User should set layer information to be used as input layer.
      */
     virtual int SetInputTensorProperty(inference_engine_layer_property &property) { return 0; }
 
     /**
      * @brief Set output layer property information to a given backend engine.
+     * @details This callback passes a given output layer information to a backend engine.
+     *          If user wants to start the inference from some given layer in model graph.
+     *          The backend engine should keep the output layer found with the given information
+     *          in model graph and then set the layer as output layer.
      *
      * @since_tizen 6.0
+     * @param[in] property User should set layer information to be used as output layer.
      */
     virtual int SetOutputTensorProperty(inference_engine_layer_property &property) { return 0; }
 
     /**
      * @brief Get capacity from a given backend engine.
+     * @details This callback requests what supported features and constraints the backend engine has.
+     *          Upper layer should call this callback just after the backend engine library is loaded.
      *
      * @since_tizen 6.0
+     * @param[out] capacity A backend engine should add the features and constraints it has.
      */
     virtual int GetBackendCapacity(inference_engine_capacity *capacity) = 0;
 
     /**
      * @brief Run an inference with user-given input and output buffers.
+     * @details This callback requests a backend engine to do inference with given input and output tensor buffers.
+     *          input and output tensor buffers can be allocated by either a backend engine or upper layer according to
+     *          backend engine. So upper layer needs to make sure to clean up the buffers.
      *
      * @since_tizen 6.0
+     * @param[in] input_buffers It contains tensor buffers to be used as input layer.
+     * @param[in] output_buffers It contains tensor buffers to be used as output layer.
      */
     virtual int Run(std::vector<inference_engine_tensor_buffer> &input_buffers,
                     std::vector<inference_engine_tensor_buffer> &output_buffers) = 0;

diff --git a/include/inference_engine_common_impl.h b/include/inference_engine_common_impl.h
index f5be834ba49f9b56632269688c6a758d4dad2765..0d9be145a5e6d5afa9612c5736d3da4a6ba18679 100755 (executable)
--- a/include/inference_engine_common_impl.h
+++ b/include/inference_engine_common_impl.h
@@ -55,78 +55,153 @@ public:
     ~InferenceEngineCommon();
 
 
+    /**
+     * @brief Load a backend engine library with a given backend name.
+     * @details This callback loads a backend engine library with a given backend name.
+     *          In order to find a backend engine library corresponding to the given backend name,
+     *          this function makes a full name of the library file with given backend name.
+     *          After that, it opens the library file by calling dlopen function to find a entry point
+     *          function - EngineInit - of a actual backend library.
+     *
+     * @since_tizen 6.0
+     * @param[in] config A configuraion data needed to load a backend library.
+     */
     int BindBackend(inference_engine_config *config);
 
+    /**
+     * @brief Unload a backend engine library.
+     * @details This callback unload a backend engine library.
+     *
+     * @since_tizen 6.0
+     */
     void UnbindBackend(void);
 
     /**
      * @brief Set target devices.
      * @details See #inference_target_type_e
+     *          This callback passes given device types - CPU, GPU, CUSTOM or combinated one if a backend engine supports hybrid inferencea - to a backend engine.
+     *          Some backend engine can optimize a given NN model at graph level such as dropping operation or fusing operations targating
+     *          a given device or devices when the backend engine loads the NN model file.
      *
      * @since_tizen 5.5
+     * @param[in] types This could be one or more among device types enumerated on inference_target_type_e.
      */
     int SetTargetDevices(int types);
 
     /**
-     * @brief Load model data with user-given model information.
+     * @brief Request to load model data with user-given model file information.
+     * @details This callback requests a backend engine to load given model files for inference.
+     *          The backend engine should load the given model files according to a given model file format.
      *
      * @since_tizen 6.0
+     * @param[in] model_paths Upper framework should add full path strings needed according to a given model format.
+     * @param[in] model_format It indicates what kinds of model file should be passed to a backend engine.
      */
     int Load(std::vector<std::string> model_paths, inference_model_format_e model_format);
 
     /**
-     * @brief Get an input tensor buffer/buffers.
+     * @brief Get input tensor buffers from a given backend engine.
+     * @details This callback requests a backend engine input tensor buffers.
+     *          If the backend engine is able to allocate the input tensor buffers internally, then
+     *          it has to add the input tensor buffers to buffers vector. By doing this, upper layer
+     *          will request a inference with the input tensor buffers.
+     *          Otherwise, the backend engine should just return INFERENCE_ENGINE_ERROR_NONE so that
+     *          upper layer can allocate input tensor buffers according to input layer property.
+     *          As for the input layer property, you can see GetInputLyaerProperty callback.
      *
      * @since_tizen 6.0
+     * @param[out] buffers A backend engine should add input tensor buffers allocated itself to buffers vector.
+     *              Otherwise, it should put buffers to be empty.
      */
     int GetInputTensorBuffers(std::vector<inference_engine_tensor_buffer> &buffers);
 
     /**
-     * @brief Get an output tensor buffer/buffers.
+     * @brief Get output tensor buffers from a given backend engine.
+     * @details This callback requests a backend engine output tensor buffers.
+     *          If the backend engine is able to allocate the output tensor buffers internally, then
+     *          it has to add the output tensor buffers to buffers vector. By doing this, upper layer
+     *          will request a inference with the output tensor buffers.
+     *          Otherwise, the backend engine should just return INFERENCE_ENGINE_ERROR_NONE so that
+     *          upper layer can allocate output tensor buffers according to output layer property.
+     *          As for the output layer property, you can see GetOutputLyaerProperty callback.
      *
      * @since_tizen 6.0
+     * @param[out] buffers A backend engine should add output tensor buffers allocated itself to buffers vector.
+     *              Otherwise, it should put buffers to be empty.
      */
     int GetOutputTensorBuffers(std::vector<inference_engine_tensor_buffer> &buffers);
 
     /**
-     * @brief Get an input layer property information from a given backend engine.
+     * @brief Get input layer property information from a given backend engine.
+     * @details This callback requests a backend engine information about given layers by
+     *          SetInputTensorProperty callback.
+     *          If user wants to specify input layer that the backend engine starts from
+     *          then user can call SetInputTensorProperty callback with desired layer information.
+     *          If user dosn't specify the input layer then the backend engine should add tensor information
+     *          of the first layer in model graph in default.
      *
      * @since_tizen 6.0
+     * @param[out] property A backend engine should add given tensor information to be used as input layer.
      */
     int GetInputLayerProperty(inference_engine_layer_property &property);
 
     /**
-     * @brief Get an output layer property information from a given backend engine.
+     * @brief Get output layer property information from a given backend engine.
+     * @details This callback requests a backend engine information about given layers by
+     *          SetOutputTensorProperty callback.
+     *          If user wants to specify output layer that the backend engine stores the inference result
+     *          then user can call SetOutputTensorProperty callback with desired layer information.
+     *          If user dosn't specify the output layer then the backend engine should add tensor information
+     *          of the last layer in model graph in default.
      *
      * @since_tizen 6.0
+     * @param[out] property A backend engine should add given tensor information to be used as output layer.
      */
     int GetOutputLayerProperty(inference_engine_layer_property &property);
 
     /**
-     * @brief Set an input layer property information to a given backend engine.
+     * @brief Set input layer property information to a given backend engine.
+     * @details This callback passes a given input layer information to a backend engine.
+     *          If user wants to start the inference from some given layer in model graph.
+     *          The backend engine should keep the input layer found with the given information
+     *          in model graph and then set the layer as input layer.
      *
      * @since_tizen 6.0
+     * @param[in] property User should set layer information to be used as input layer.
      */
     int SetInputTensorProperty(inference_engine_layer_property &property);
 
     /**
-     * @brief Set an output layer property information to a given backend engine.
+     * @brief Set output layer property information to a given backend engine.
+     * @details This callback passes a given output layer information to a backend engine.
+     *          If user wants to start the inference from some given layer in model graph.
+     *          The backend engine should keep the output layer found with the given information
+     *          in model graph and then set the layer as output layer.
      *
      * @since_tizen 6.0
+     * @param[in] property User should set layer information to be used as output layer.
      */
     int SetOutputTensorProperty(inference_engine_layer_property &property);
 
     /**
      * @brief Get capacity from a given backend engine.
+     * @details This callback requests what supported features and constraints the backend engine has.
+     *          Upper layer should call this callback just after the backend engine library is loaded.
      *
      * @since_tizen 6.0
+     * @param[out] capacity A backend engine should add the features and constraints it has.
      */
     int GetBackendCapacity(inference_engine_capacity *capacity);
 
     /**
      * @brief Run an inference with user-given input and output buffers.
+     * @details This callback requests a backend engine to do inference with given input and output tensor buffers.
+     *          input and output tensor buffers can be allocated by either a backend engine or upper layer according to
+     *          backend engine. So upper layer needs to make sure to clean up the buffers.
      *
      * @since_tizen 6.0
+     * @param[in] input_buffers It contains tensor buffers to be used as input layer.
+     * @param[in] output_buffers It contains tensor buffers to be used as output layer.
      */
     int Run(std::vector<inference_engine_tensor_buffer> &input_buffers,
             std::vector<inference_engine_tensor_buffer> &output_buffers);

diff --git a/include/inference_engine_type.h b/include/inference_engine_type.h
index 7b5ef62533d39eacab4f8bf1e05199ec373d313c..be6f6b515fc6b1c5980c45cea98f1c2d9b0df8b0 100644 (file)
--- a/include/inference_engine_type.h
+++ b/include/inference_engine_type.h
@@ -42,7 +42,7 @@ typedef enum {
 } inference_backend_type_e;
 
 /**
- * @brief Enumeration for inference target.
+ * @brief Enumeration for inference target device.
  *
  * @since_tizen 5.5
  *
@@ -55,11 +55,17 @@ typedef enum {
     INFERENCE_TARGET_MAX    = 1 << 3,
 } inference_target_type_e;
 
+/**
+ * @brief Enumeration for NN model formats.
+ *
+ * @since_tizen 5.5
+ *
+ */
 typedef enum {
     INFERENCE_MODEL_NONE     = 0,
     INFERENCE_MODEL_CAFFE,           /**< CAFFE. *.prototxt config file is needed. */
     INFERENCE_MODEL_TF,              /**< Tensorflow. *.pbtxt config file is needed. */
-    INFERENCE_MODEL_TFLITE,          /** Tensorflow-Lite. */
+    INFERENCE_MODEL_TFLITE,          /**< Tensorflow-Lite. */
     INFERENCE_MODEL_TORCH,           /**< Torch */
     INFERENCE_MODEL_DARKNET,         /**< Darknet. *.cfg config file is needed. */
     INFERENCE_MODEL_DLDT,            /**< DLDT. *.xml config file is needed. */
@@ -126,7 +132,7 @@ typedef struct _tensor_t {
  */
 typedef struct _inference_engine_config {
     std::string backend_name; /**< a backend name which could be one among supported backends(tflite, opencv, armnn, dldt) */
-    int target_devices; /**< which device or devices to be targeted for inference. */
+    int target_devices; /**< which device or devices to be targeted for inference. (Please, refer to inference_target_type_e) */
     // TODO.
 } inference_engine_config;