api docs

Signed-off-by: zhoufeng <zhoufeng54@huawei.com>

include/api/context.h

@@ -38,12 +38,19 @@ class Allocator;
 class Delegate;
 class DeviceInfoContext;
 
+/// \brief Context is used to store environment variables during execution.
 class MS_API Context {
  public:
   Context();
   ~Context() = default;
 
+  /// \brief Set the number of threads at runtime. This option is only valid for MindSpore Lite.
+  ///
+  /// \param[in] thread_num the number of threads at runtime.
   void SetThreadNum(int32_t thread_num);
+  /// \brief Get the current thread number setting.
+  ///
+  /// \return The current thread number setting.
   int32_t GetThreadNum() const;
 
   /// \brief Set the thread affinity to CPU cores.
@@ -60,6 +67,10 @@ class MS_API Context {
   void SetDelegate(const std::shared_ptr<Delegate> &delegate);
   std::shared_ptr<Delegate> GetDelegate() const;
 
+  /// \brief Get a mutable reference of DeviceInfoContext vector in this context. Only MindSpore Lite supports
+  /// heterogeneous scenarios with multiple members in the vector.
+  ///
+  /// \return Mutable reference of DeviceInfoContext vector in this context.
   std::vector<std::shared_ptr<DeviceInfoContext>> &MutableDeviceInfo();
 
  private:
@@ -67,14 +78,24 @@ class MS_API Context {
   std::shared_ptr<Data> data_;
 };
 
+/// \brief DeviceInfoContext defines different device contexts.
 class MS_API DeviceInfoContext : public std::enable_shared_from_this<DeviceInfoContext> {
  public:
   struct Data;
 
   DeviceInfoContext();
   virtual ~DeviceInfoContext() = default;
+
+  /// \brief Get the type of this DeviceInfoContext.
+  ///
+  /// \return Type of this DeviceInfoContext.
   virtual enum DeviceType GetDeviceType() const = 0;
 
+  /// \brief A similar function to RTTI is provided when the -fno-rtti compilation option is turned on, which converts
+  /// DeviceInfoContext to a shared pointer of type T, and returns nullptr if the conversion fails.
+  ///
+  /// \param T Type
+  /// \return A pointer of type T after conversion. If the conversion fails, it will be nullptr.
   template <class T>
   std::shared_ptr<T> Cast() {
     static_assert(std::is_base_of<DeviceInfoContext, T>::value, "Wrong cast type.");
@@ -98,27 +119,60 @@ class MS_API DeviceInfoContext : public std::enable_shared_from_this<DeviceInfoC
   std::shared_ptr<Data> data_;
 };
 
+/// \brief Derived from DeviceInfoContext, The configuration of the model running on the CPU. This option is only valid
+/// for MindSpore Lite.
 class MS_API CPUDeviceInfo : public DeviceInfoContext {
  public:
+  /// \brief Get the type of this DeviceInfoContext.
+  ///
+  /// \return Type of this DeviceInfoContext.
   enum DeviceType GetDeviceType() const override { return DeviceType::kCPU; };
 
+  /// \brief Set enables to perform the float16 inference
+  ///
+  /// \param[in] is_fp16 Enable float16 inference or not.
   void SetEnableFP16(bool is_fp16);
+  /// \brief Get enables to perform the float16 inference
+  ///
+  /// \return Whether enable float16 inference.
   bool GetEnableFP16() const;
 };
 
+/// \brief Derived from DeviceInfoContext, The configuration of the model running on the NPU. This option is only valid
+/// for MindSpore Lite.
 class MS_API KirinNPUDeviceInfo : public DeviceInfoContext {
  public:
+  /// \brief Get the type of this DeviceInfoContext.
+  ///
+  /// \return Type of this DeviceInfoContext.
   enum DeviceType GetDeviceType() const override { return DeviceType::kKirinNPU; };
 
+  /// \brief Set the NPU frequency.
+  ///
+  /// \param[in] frequency Can be set to 1 (low power consumption), 2 (balanced), 3 (high performance), 4 (extreme
+  /// performance), default as 3.
   void SetFrequency(int frequency);
+  /// \brief Get the NPU frequency.
+  ///
+  /// \return NPU frequency
   int GetFrequency() const;
 };
 
+/// \brief Derived from DeviceInfoContext, The configuration of the model running on the GPU.
 class MS_API GPUDeviceInfo : public DeviceInfoContext {
  public:
+  /// \brief Get the type of this DeviceInfoContext.
+  ///
+  /// \return Type of this DeviceInfoContext.
   enum DeviceType GetDeviceType() const override { return DeviceType::kGPU; };
 
+  /// \brief Set device id.
+  ///
+  /// \param[in] device_id The device id.
   void SetDeviceID(uint32_t device_id);
+  /// \brief Get the device id.
+  ///
+  /// \return The device id.
   uint32_t GetDeviceID() const;
 
   void SetGpuTrtInferMode(bool gpu_trt_infer_mode);
@@ -127,8 +181,15 @@ class MS_API GPUDeviceInfo : public DeviceInfoContext {
   inline void SetPrecisionMode(const std::string &precison_mode);
   inline std::string GetPrecisionMode() const;
 
+  /// \brief Set enables to perform the float16 inference
+  ///
+  /// \param[in] is_fp16 Enable float16 inference or not.
   void SetEnableFP16(bool is_fp16);
+  /// \brief Get enables to perform the float16 inference
+  ///
+  /// \return Whether enable float16 inference.
   bool GetEnableFP16() const;
+
  private:
   void SetPrecisionMode(const std::vector<char> &precision_mode);
   std::vector<char> GetPrecisionModeChar() const;
@@ -139,52 +200,113 @@ void GPUDeviceInfo::SetPrecisionMode(const std::string &precision_mode) {
 }
 std::string GPUDeviceInfo::GetPrecisionMode() const { return CharToString(GetPrecisionModeChar()); }
 
+/// \brief Derived from DeviceInfoContext, The configuration of the model running on the Ascend910. This option is
+/// invalid for MindSpore Lite.
 class MS_API Ascend910DeviceInfo : public DeviceInfoContext {
  public:
+  /// \brief Get the type of this DeviceInfoContext.
+  ///
+  /// \return Type of this DeviceInfoContext.
   enum DeviceType GetDeviceType() const override { return DeviceType::kAscend910; };
 
+  /// \brief Set device id.
+  ///
+  /// \param[in] device_id The device id.
   void SetDeviceID(uint32_t device_id);
+  /// \brief Get the device id.
+  ///
+  /// \return The device id.
   uint32_t GetDeviceID() const;
 };
 
+/// \brief Derived from DeviceInfoContext, The configuration of the model running on the Ascend310. This option is
+/// invalid for MindSpore Lite.
 class MS_API Ascend310DeviceInfo : public DeviceInfoContext {
  public:
+  /// \brief Get the type of this DeviceInfoContext.
+  ///
+  /// \return Type of this DeviceInfoContext.
   enum DeviceType GetDeviceType() const override { return DeviceType::kAscend310; };
 
+  /// \brief Set device id.
+  ///
+  /// \param[in] device_id The device id.
   void SetDeviceID(uint32_t device_id);
+  /// \brief Get the device id.
+  ///
+  /// \return The device id.
   uint32_t GetDeviceID() const;
 
   inline void SetDumpConfigPath(const std::string &cfg_path);
   inline std::string GetDumpConfigPath() const;
 
-  // aipp config file
+  /// \brief Set AIPP configuration file path.
+  ///
+  /// \param[in] cfg_path AIPP configuration file path.
   inline void SetInsertOpConfigPath(const std::string &cfg_path);
+  /// \brief Get AIPP configuration file path.
+  ///
+  /// \return AIPP configuration file path.
   inline std::string GetInsertOpConfigPath() const;
 
-  // nchw or nhwc
+  /// \brief Set format of model inputs.
+  ///
+  /// \param[in] format Optional "NCHW", "NHWC", etc.
   inline void SetInputFormat(const std::string &format);
+  /// \brief Get format of model inputs.
+  ///
+  /// \return The format of model inputs.
   inline std::string GetInputFormat() const;
 
-  // Mandatory while dynamic batch: e.g. "input_op_name1: 1,2,3,4;input_op_name2: 4,3,2,1"
+  /// \brief Set shape of model inputs.
+  ///
+  /// \param[in] shape e.g. "input_op_name1: 1,2,3,4;input_op_name2: 4,3,2,1".
   inline void SetInputShape(const std::string &shape);
+  /// \brief Get shape of model inputs.
+  ///
+  /// \return The shape of model inputs.
   inline std::string GetInputShape() const;
 
+  /// \brief Set shape of model inputs.
+  ///
+  /// \param[in] shape e.g. {{1, {1,2,3,4}}, {2, {4,3,2,1}}} means the first input shape 1,2,3,4 and the second input
+  /// shape 4,3,2,1.
   void SetInputShapeMap(const std::map<int, std::vector<int>> &shape);
+  /// \brief Get shape of model inputs.
+  ///
+  /// \return The shape of model inputs.
   std::map<int, std::vector<int>> GetInputShapeMap() const;
 
   void SetDynamicBatchSize(const std::vector<size_t> &dynamic_batch_size);
   inline std::string GetDynamicBatchSize() const;
 
-  // FP32, UINT8 or FP16, default as FP32
+  /// \brief Set type of model outputs.
+  ///
+  /// \param[in] output_type FP32, UINT8 or FP16, default as FP32.
   void SetOutputType(enum DataType output_type);
+  /// \brief Get type of model outputs.
+  ///
+  /// \return The set type of model outputs.
   enum DataType GetOutputType() const;
 
-  // "force_fp16", "allow_fp32_to_fp16", "must_keep_origin_dtype" or "allow_mix_precision", default as "force_fp16"
+  /// \brief Set precision mode of model.
+  ///
+  /// \param[in] precision_mode Optional "force_fp16", "allow_fp32_to_fp16", "must_keep_origin_dtype" and
+  /// "allow_mix_precision", "force_fp16" is set as default
   inline void SetPrecisionMode(const std::string &precision_mode);
+  /// \brief Get precision mode of model.
+  ///
+  /// \return The set type of model outputs
   inline std::string GetPrecisionMode() const;
 
-  // Optional "high_performance" and "high_precision", "high_performance" is set as default
+  /// \brief Set op select implementation mode.
+  ///
+  /// \param[in] op_select_impl_mode Optional "high_performance" and "high_precision", "high_performance" is set as
+  /// default.
   inline void SetOpSelectImplMode(const std::string &op_select_impl_mode);
+  /// \brief Get op select implementation mode.
+  ///
+  /// \return The set op select implementation mode.
   inline std::string GetOpSelectImplMode() const;
 
   inline void SetFusionSwitchConfigPath(const std::string &cfg_path);

include/api/model.h

@@ -37,32 +37,75 @@ class Metrics;
 namespace dataset {
 class Dataset;
 }  // namespace dataset
-
+/// \brief The Model class is used to define a MindSpore model, facilitating computational graph management.
 class MS_API Model {
  public:
   Model();
   ~Model();
   Model(const Model &) = delete;
   void operator=(const Model &) = delete;
-
+  /// \brief Builds a model so that it can run on a device.
+  ///
+  /// \param[in] graph GraphCell is a derivative of Cell. Cell is not available currently. GraphCell can be constructed
+  /// from Graph, for example, model.Build(GraphCell(graph), context).
+  /// \param[in] model_context A context used to store options during execution.
+  /// \param[in] train_cfg A config used by training.
+  ///
+  /// \return Status.
   Status Build(GraphCell graph, const std::shared_ptr<Context> &model_context = nullptr,
                const std::shared_ptr<TrainCfg> &train_cfg = nullptr);
+
+  /// \brief Resizes the shapes of inputs.
+  ///
+  /// \param[in] inputs A vector that includes all input tensors in order.
+  /// \param[in] dims Defines the new shapes of inputs, should be consistent with inputs.
+  ///
+  /// \return Status.
   Status Resize(const std::vector<MSTensor> &inputs, const std::vector<std::vector<int64_t>> &dims);
 
+  /// \brief Inference model.
+  ///
+  /// \param[in] inputs A vector where model inputs are arranged in sequence.
+  /// \param[out] outputs Which is a pointer to a vector. The model outputs are filled in the container in sequence.
+  /// \param[in] before CallBack before predict.
+  /// \param[in] after CallBack after predict.
+  ///
+  /// \return Status.
   Status Predict(const std::vector<MSTensor> &inputs, std::vector<MSTensor> *outputs,
                  const MSKernelCallBack &before = nullptr, const MSKernelCallBack &after = nullptr);
 
+  /// \brief Obtains all input tensors of the model.
+  ///
+  /// \return The vector that includes all input tensors.
   std::vector<MSTensor> GetInputs();
+  /// \brief Obtains the input tensor of the model by name.
+  ///
+  /// \return The input tensor with the given name, if the name is not found, an invalid tensor is returned.
   inline MSTensor GetInputByTensorName(const std::string &tensor_name);
 
   Status InitMetrics(std::vector<Metrics *> metrics);
   std::vector<Metrics *> GetMetrics();
 
+  /// \brief Obtains all output tensors of the model.
+  ///
+  /// \return The vector that includes all output tensors.
   std::vector<MSTensor> GetOutputs();
+  /// \brief Obtains names of all output tensors of the model.
+  ///
+  /// \return A vector that includes names of all output tensors.
   inline std::vector<std::string> GetOutputTensorNames();
+  /// \brief Obtains the output tensor of the model by name.
+  ///
+  /// \return The output tensor with the given name, if the name is not found, an invalid tensor is returned.
   inline MSTensor GetOutputByTensorName(const std::string &tensor_name);
   inline std::vector<MSTensor> GetOutputsByNodeName(const std::string &tensor_name);
 
+  /// \brief Inference model.
+  ///
+  /// \param[in] device_type Device type，options are kGPU, kAscend910, etc.
+  /// \param[in] model_type The type of model file, options are ModelType::kMindIR, ModelType::kOM.
+  ///
+  /// \return Is supported or not.
   static bool CheckModelSupport(enum DeviceType device_type, ModelType model_type);
 
   Status SetTrainMode(bool train);

include/api/serialization.h

@@ -27,13 +27,43 @@
 #include "include/api/dual_abi_helper.h"
 
 namespace mindspore {
-
+/// \brief The Serialization class is used to summarize methods for reading and writing model files.
 class MS_API Serialization {
  public:
+  /// \brief Loads a model file from memory buffer.
+  ///
+  /// \param[in] model_data A buffer filled by model file.
+  /// \param[in] data_size The size of the buffer.
+  /// \param[in] model_type The Type of model file, options are ModelType::kMindIR, ModelType::kOM.
+  /// \param[out] graph The output parameter, an object saves graph data.
+  /// \param[in] dec_key The decryption key, key length is 16, 24, or 32.
+  /// \param[in] dec_mode The decryption mode, optional options are AES-GCM, AES-CBC.
+  ///
+  /// \return Status.
   inline static Status Load(const void *model_data, size_t data_size, ModelType model_type, Graph *graph,
                             const Key &dec_key = {}, const std::string &dec_mode = kDecModeAesGcm);
+
+  /// \brief Loads a model file from path, is not supported on MindSpore Lite.
+  ///
+  /// \param[in] file The path of model file.
+  /// \param[in] model_type The Type of model file, options are ModelType::kMindIR, ModelType::kOM.
+  /// \param[out] graph The output parameter, an object saves graph data.
+  /// \param[in] dec_key The decryption key, key length is 16, 24, or 32.
+  /// \param[in] dec_mode The decryption mode, optional options are AES-GCM, AES-CBC.
+  ///
+  /// \return Status.
   inline static Status Load(const std::string &file, ModelType model_type, Graph *graph, const Key &dec_key = {},
                             const std::string &dec_mode = kDecModeAesGcm);
+
+  /// \brief Load multiple models from multiple files, MindSpore Lite does not provide this feature.
+  ///
+  /// \param[in] files The path of model files.
+  /// \param[in] model_type The Type of model file, options are ModelType::kMindIR, ModelType::kOM.
+  /// \param[out] graph The output parameter, an object saves graph data.
+  /// \param[in] dec_key The decryption key, key length is 16, 24, or 32.
+  /// \param[in] dec_mode The decryption mode, optional options are AES-GCM, AES-CBC.
+  ///
+  /// \return Status.
   inline static Status Load(const std::vector<std::string> &files, ModelType model_type, std::vector<Graph> *graphs,
                             const Key &dec_key = {}, const std::string &dec_mode = kDecModeAesGcm);
   static Status SetParameters(const std::map<std::string, Buffer> &parameters, Model *model);

include/api/types.h

@@ -64,18 +64,64 @@ struct QuantParam {
 };
 
 class Allocator;
+/// \brief The MSTensor class defines a tensor in MindSpore.
 class MS_API MSTensor {
  public:
   class Impl;
-
+  /// \brief Creates a MSTensor object, whose data need to be copied before accessed by Model, must be used in pairs
+  /// with DestroyTensorPtr.
+  ///
+  /// \param[in] name The name of the MSTensor.
+  /// \param[in] type The data type of the MSTensor.
+  /// \param[in] shape The shape of the MSTensor.
+  /// \param[in] data The data pointer that points to allocated memory.
+  /// \param[in] data_len The length of the memory, in bytes.
+  ///
+  /// \return A pointer of MSTensor.
   static inline MSTensor *CreateTensor(const std::string &name, DataType type, const std::vector<int64_t> &shape,
                                        const void *data, size_t data_len) noexcept;
+  /// \brief Creates a MSTensor object, whose data can be directly accessed by Model, must be used in pairs with
+  /// DestroyTensorPtr.
+  ///
+  /// \param[in] name The name of the MSTensor.
+  /// \param[in] type The data type of the MSTensor.
+  /// \param[in] shape The shape of the MSTensor.
+  /// \param[in] data The data pointer that points to allocated memory.
+  /// \param[in] data_len The length of the memory, in bytes.
+  ///
+  /// \return A pointer of MSTensor.
   static inline MSTensor *CreateRefTensor(const std::string &name, DataType type, const std::vector<int64_t> &shape,
                                           const void *data, size_t data_len) noexcept;
+  /// \brief Creates a MSTensor object, whose device data can be directly accessed by Model, must be used in pairs with
+  /// DestroyTensorPtr.
+  ///
+  /// \param[in] name The name of the MSTensor.
+  /// \param[in] type The data type of the MSTensor.
+  /// \param[in] shape The shape of the MSTensor.
+  /// \param[in] data The data pointer that points to device memory.
+  /// \param[in] data_len The length of the memory, in bytes.
+  ///
+  /// \return A pointer of MSTensor.
   static inline MSTensor *CreateDevTensor(const std::string &name, DataType type, const std::vector<int64_t> &shape,
                                           const void *data, size_t data_len) noexcept;
+  /// \brief Create a string type MSTensor object whose data can be accessed by Model only after being copied, must be
+  /// used in pair with DestroyTensorPtr.
+  ///
+  /// \param[in] name The name of the MSTensor.
+  /// \param[in] str A vector container containing several strings.
+  ///
+  /// \return A pointer of MSTensor.
   static inline MSTensor *StringsToTensor(const std::string &name, const std::vector<std::string> &str);
+  /// \brief Parse the string type MSTensor object into strings.
+  ///
+  /// \param[in] tensor A MSTensor object.
+  ///
+  /// \return A vector container containing several strings.
   static inline std::vector<std::string> TensorToStrings(const MSTensor &tensor);
+  /// \brief Destroy an object created by Clone, StringsToTensor, CreateRefTensor, CreateDevTensor or CreateTensor. Do
+  /// not use it to destroy MSTensor from other sources.
+  ///
+  /// \param[in] tensor A MSTensor object.
   static void DestroyTensorPtr(MSTensor *tensor) noexcept;
 
   MSTensor();
@@ -85,19 +131,51 @@ class MS_API MSTensor {
   explicit MSTensor(std::nullptr_t);
   ~MSTensor();
 
+  /// \brief Obtains the name of the MSTensor.
+  ///
+  /// \return The name of the MSTensor.
   inline std::string Name() const;
+  /// \brief Obtains the data type of the MSTensor.
+  ///
+  /// \return The data type of the MSTensor.
   enum DataType DataType() const;
+  /// \brief Obtains the shape of the MSTensor.
+  ///
+  /// \return The shape of the MSTensor.
   const std::vector<int64_t> &Shape() const;
+  /// \brief Obtains the number of elements of the MSTensor.
+  ///
+  /// \return The number of elements of the MSTensor.
   int64_t ElementNum() const;
 
+  /// \brief Obtains a shared pointer to the copy of data of the MSTensor. The data can be read on host.
+  ///
+  /// \return A shared pointer to the copy of data of the MSTensor.
   std::shared_ptr<const void> Data() const;
+  /// \brief Obtains the pointer to the data of the MSTensor. If the MSTensor is a device tensor, the data cannot be
+  /// accessed directly on host.
+  ///
+  /// \return A pointer to the data of the MSTensor.
   void *MutableData();
+  /// \brief Obtains the length of the data of the MSTensor, in bytes.
+  ///
+  /// \return The length of the data of the MSTensor, in bytes.
   size_t DataSize() const;
-
+  /// \brief Gets the boolean value that indicates whether the memory of MSTensor is on device.
+  ///
+  /// \return The boolean value that indicates whether the memory of MSTensor is on device.
   bool IsDevice() const;
-
+  /// \brief Gets a deep copy of the MSTensor, must be used in pair with DestroyTensorPtr.
+  ///
+  /// \return A pointer points to a deep copy of the MSTensor.
   MSTensor *Clone() const;
+  /// \brief Gets the boolean value that indicates whether the MSTensor is valid.
+  ///
+  /// \return The boolean value that indicates whether the MSTensor is valid.
   bool operator==(std::nullptr_t) const;
+  /// \brief Gets the boolean value that indicates whether the MSTensor is valid.
+  ///
+  /// \return The boolean value that indicates whether the MSTensor is valid.
   bool operator!=(std::nullptr_t) const;
   bool operator==(const MSTensor &tensor) const;