[Doxygen/libnpuhost] Revise some comments in libnpuhost.h

This patch revises some comments in libnpuhost.h

Signed-off-by: Dongju Chae <dongju.chae@samsung.com>

diff --git a/include/host/libnpuhost.h b/include/host/libnpuhost.h
index 01d4fa1..613f266 100644 (file)
--- a/include/host/libnpuhost.h
+++ b/include/host/libnpuhost.h
@@ -2,6 +2,9 @@
  * Proprietary
  * Copyright (C) 2019 Samsung Electronics
  * Copyright (C) 2019 MyungJoo Ham <myungjoo.ham@samsung.com>
+ * Copyright (C) 2019 Dongju Chae <dongju.chae@samsung.com>
+ * Copyright (C) 2019 Wook Song <wook16.song@samsung.com>
+ * Copyright (C) 2019 Parichay Kapoor <pk.kapoor@samsung.com>
  */
 /**
  * @file libnpuhost.h
@@ -9,13 +12,10 @@
  * @brief API to access NPU from Host Computer
  * @see https://code.sec.samsung.net/confluence/display/ODLC/2020+Overall+Software+Stack
  * @author MyungJoo Ham <myungjoo.ham@samsung.com>
+ *         Dongju Chae <dongju.chae@samsung.com>
+ *         Wook Song <wook16.song@samsung.com>
+ *         Parichay Kapoor <pk.kapoor@samsung.com>
  * @bug No known bugs except for NYI items
- *
- * To packagers: this is exported to HOST PROGRAMMERS as a devel package.
- *
- * @note This version does not support multi-model.
- *       Therefore registerNPUModel always returns "FULL" if there is a model
- *       registered.
  */
 
 #ifndef __NPU_HOST_LIBNPUHOST_H__
@@ -30,9 +30,9 @@
 /**
  * Note that libnpuhost is the entry point to access NPU Engine (by host handler).
  * Also, the term 'NPU' now includes all variants such as traditional NPU, ASR,
- * and new device types (i.e., TRIV, TRIV2, and TRIA). Existing APIs that have
- * specified a device type in the name are deprecated (but still supported).
- * (e.g., getNPUdevice/getASRdevice)
+ * and new device types (i.e., TRIV, TRIV2, and TRIA). Existing APIs that do not
+ * specify a device type in their names (e.g., getNPUdevice/getASRdevice) are now
+ * deprecated (but still supported).
  */
 
 #if defined(__cplusplus)
@@ -45,42 +45,34 @@ extern "C" {
 /** @brief type of memory represented by the buffer */
 typedef enum {
   BUFFER_FILE = 0,  /**< buffer is a file */
-  BUFFER_DMABUF,    /**< buffer is a dmabuf fd, representing contiguous memory */
   BUFFER_MAPPED,    /**< buffer is a memory-mapped ptr */
+  BUFFER_DMABUF,    /**< buffer is a dmabuf fd, representing contiguous memory */
   BUFFER_UNDEFINED  /**< buffer type is undefined */
 } buffer_types;
 
 /**
  * @brief Various kinds of buffer supported for input/output/model
- * @note size can be zero in case of filepath. Then size will be file size.
+ * @note In case of BUFFER_FILE, 'size' indicates a file size.
  */
 typedef struct {
   union {
-    /** BUFFER_FILE */
-    /**
-     * no memory allocated, provided with file
-     * the file is appended with data
-     * callers responsibility to empty the file before calling, if needed
-     */
-    const char *filepath;   /**< The filepath for the data */
-
-    /** BUFFER_MAPPED & BUFFER_DMABUF */
-    struct {
-      /** memory is allocated in physically/non-physically contiguous space */
-      void *addr;           /**< Mapped address of the buffer */
+    struct {    /** BUFFER_FILE */
+      const char *filepath;   /**< The filepath for the data */
+    };
+    struct {    /** BUFFER_MAPPED/DMABUF */
+      void *addr;             /**< Mapped address of the buffer */
       struct {  /** BUFFER_DMABUF only */
-        int dmabuf;         /**< The dma-buf fd handle of the memory allocated */
-        /** @todo offset is not supported yet */
-        uint64_t offset;    /**< Offset to be applied to the base memory address */
+        int dmabuf;           /**< The dma-buf fd handle of the memory allocated */
+        uint64_t offset;      /**< Offset to be applied to the base memory address */
       };
     };
   };
-  uint64_t size;            /**< The size of the buffer in bytes */
-  buffer_types type;        /**< Type of memory in this buffer */
+  uint64_t size;              /**< The size of the buffer in bytes */
+  buffer_types type;          /**< Type of memory in this buffer */
 } generic_buffer;
 
 /**
- * @brief Multiple buffers to hold dis-contiguous tensor buffers.
+ * @brief Multiple buffers to contain dis-contiguous tensor buffers.
  *        Each generic buffer can have different buffer types.
  */
 typedef struct {
@@ -95,7 +87,7 @@ typedef generic_buffers input_buffers;
 typedef generic_buffers output_buffers;
 
 /**
- * @brief Description of data info.
+ * @brief Description of tensor data info.
  */
 typedef struct {
   data_layout layout;
@@ -111,14 +103,14 @@ typedef struct {
 } tensors_data_info;
 
 /**
- * @brief Represents an "opened" single NPU device (e.g., a USB NPU Stick).
+ * @brief Represents an "opened" single NPU device (e.g., TRIV2).
  */
 typedef void *npudev_h;
 
 /**
  * @brief Returns the number of available NPU devices.
- * @return @c The number of NPU devices.
- * @retval 0 if no NPU devices available. if positive (number of NPUs) if NPU devices available. otherwise, a negative error value.
+ * @return @c The number of available NPU devices.
+ * @note this number indicates the range of device IDs in getNPUdeviceByType ().
 */
 int getnumNPUdeviceByType (dev_type type);
 
@@ -133,6 +125,7 @@ int getNPUdeviceByType (npudev_h *dev, dev_type type, uint32_t id);
 
 /**
  * @brief Description of npu device search conditions.
+ * @todo this feature is not supported yet
  */
 typedef struct {
   dev_type connection; /**< Desginates NPU connection types. Use NPUCOND_CONN_UNKNOWN to say "I don't care." */
@@ -157,7 +150,7 @@ typedef struct {
  * @param[in] cond The condition for device search.
  * @return @c 0 if no error. otherwise a negative error value
  * @note the caller should call putNPUdevice() to release the device handle
- * @note it's not supported yet
+ * @todo this feature is not supported yet
  */
 int getNPUdeviceByCondition(npudev_h *dev, const npucondition *cond);
 
@@ -188,15 +181,9 @@ npubin_meta * getNPUmodel_metadata(const char *model, bool need_extra);
  * @param[out] modelid The modelid allocated for this instance of NN model.
  * @return @c 0 if no error. otherwise a negative error value
  *
- * @detail This version does not support multimodel. Thus, dev should be
- *         emptied with unregister function before registering another.
- *         This may incur some latency with memory compatcion.
- *
- *         For ASR devices, which do not accept models, but have models
+ * @detail For ASR devices, which do not accept models, but have models
  *         embedded in devices, you do not need to call register and
  *         register calls for ASR are ignored.
- *
- * @todo Add a variation: in-memory model register.
  */
 int registerNPUmodel(npudev_h dev, generic_buffer *modelfile, uint32_t *modelid);
 
@@ -235,7 +222,6 @@ typedef struct {
   uint32_t timeout_ms;
   npu_priority priority;
   npu_notimode notimode;
-  /** @todo add more */
 } npuConstraint;
 
 static const uint32_t default_timeout = 3000;
@@ -359,7 +345,6 @@ int getNPUstatus(npudev_h dev, uint64_t *status);
  * - BUFFER_FILE: buffer with the content of filepath (virtual mapping)
  * - BUFFER_MAPPED: buffer with the requested memory size (virtual mapping)
  * - BUFFER_DMABUF: buffer with dmabuf-fd sharing (physically-contiguous)
- * (Note that to use BUFFER_DMABUF, 'resv_mem_size' in the config file should be 0)
  *
  * Each allocation API has several pre-/post-conditions
  * Pre-conditions: users must specify some variables of buffers
@@ -489,22 +474,22 @@ int getnumASRdevice(void);
  */
 int getASRdevice(npudev_h *dev, uint32_t id);
 
-/** @brief deprecated */
+/** @deprecated */
 int allocModelBuffer (generic_buffer *buffer);
-/** @brief deprecated */
+/** @deprecated */
 int cleanModelBuffer (generic_buffer *buffer);
-/** @brief deprecated */
+/** @deprecated */
 int allocInputBuffer (generic_buffer *buffer);
-/** @brief deprecated */
+/** @deprecated */
 int cleanInputBuffer (generic_buffer *buffer);
-/** @brief deprecated */
+/** @deprecated */
 int allocInputBuffers (input_buffers * input);
-/** @brief deprecated */
+/** @deprecated */
 int cleanInputBuffers (input_buffers * input);
-/** @brief deprecated */
+/** @deprecated */
 int allocNPUBuffer (uint64_t size, buffer_types type,
     const char * filepath, generic_buffer *buffer);
-/** @brief deprecated */
+/** @deprecated */
 int cleanNPUBuffer (generic_buffer * buffer);
 
 #if defined(__cplusplus)