add comment for ggml-cann.cpp

ggml/include/ggml-cann.h

@@ -1,46 +1,148 @@
+/*
+ * Copyright (c) 2023-2024 The ggml authors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
 #pragma once
 
 #include "ggml-backend.h"
 #include "ggml.h"
 
-#define GGML_CANN_NAME "CANN"
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/**
+ * @def GGML_CANN_NAME
+ * @brief Define for the name of the CANN backend.
+ */
+#define GGML_CANN_NAME "CANN"
+
+/**
+ * @brief Maximum number of CANN devices supported.
+ */
 #define GGML_CANN_MAX_DEVICES 16
 
+/**
+ * @brief Structure for QK4_0 data format.
+ */
 #define QK4_0 32
 typedef struct {
-    uint16_t d;           // delta
-    uint8_t qs[QK4_0 / 2]; // nibbles / quants
+    uint16_t d;            /**< Delta */
+    uint8_t qs[QK4_0 / 2]; /**< Nibbles / quants */
 } block_q4_0;
 
-
+/**
+ * @brief Structure for QK8_0 data format.
+ */
 #define QK8_0 32
 typedef struct {
-    uint16_t d;       // delta
-    int8_t  qs[QK8_0]; // quants
+    uint16_t d;       /**< Delta */
+    int8_t qs[QK8_0]; /**< Quants */
 } block_q8_0;
 
-// backend API
+/**
+ * @brief Initializes the CANN backend for a specified device.
+ *
+ * This function initializes the CANN backend for the given device.
+ * It verifies the device index, allocates a context, and creates a backend
+ * instance.
+ *
+ * @param device The index of the device to initialize.
+ * @return A pointer to the initialized backend instance, or nullptr on failure.
+ */
 GGML_API GGML_CALL ggml_backend_t ggml_backend_cann_init(int32_t device);
 
+/**
+ * @brief Checks if a given backend is a CANN backend.
+ *
+ * This function verifies if the provided backend is a CANN backend by comparing
+ * its GUID with the CANN backend's GUID.
+ *
+ * @param backend The backend instance to check.
+ * @return True if the backend is a CANN backend, false otherwise.
+ */
 GGML_API GGML_CALL bool ggml_backend_is_cann(ggml_backend_t backend);
 
-// device buffer
+/**
+ * @brief Retrieves the CANN buffer type for a specified device.
+ *
+ * This function initializes and returns the buffer type interface associated
+ * with the given device. It ensures thread-safe access using a mutex.
+ *
+ * @param device The device index for which to retrieve the buffer type.
+ * @return A pointer to the buffer type interface for the specified device, or
+ * nullptr if the device index is out of range.
+ */
 GGML_API GGML_CALL ggml_backend_buffer_type_t
 ggml_backend_cann_buffer_type(int32_t device);
 
+/**
+ * @brief Retrieves the number of CANN devices available.
+ *
+ * This function returns the number of CANN devices available based on
+ * information obtained from `ggml_cann_info()`.
+ *
+ * @return The number of CANN devices available.
+ */
 GGML_API GGML_CALL int32_t ggml_backend_cann_get_device_count(void);
+
+/**
+ * @brief Retrieves the description of a specific CANN device.
+ *
+ * This function sets the specified device, retrieves the SoC name,
+ * and writes it into the provided description buffer.
+ *
+ * @param device The device index to retrieve the description for.
+ * @param description Pointer to a buffer where the description will be written.
+ * @param description_size Size of the description buffer.
+ */
 GGML_API GGML_CALL void ggml_backend_cann_get_device_description(
     int32_t device, char* description, size_t description_size);
+
+/**
+ * @brief Retrieves the memory information of a specific CANN device.
+ *
+ * This function sets the specified device, retrieves the free and total
+ * memory information of the specified type (ACL_HBM_MEM), and stores them
+ * in the provided pointers.
+ *
+ * @param device The device index to retrieve memory information for.
+ * @param free Pointer to a variable where the free memory size will be stored.
+ * @param total Pointer to a variable where the total memory size will be
+ * stored.
+ */
 GGML_API GGML_CALL void ggml_backend_cann_get_device_memory(int32_t device,
                                                             size_t* free,
                                                             size_t* total);
+
+/**
+ * @brief Initializes resources required by the CANN backend.
+ */
 void ggml_cann_backend_init(void);
+
+/**
+ * @brief Frees resources used by the CANN backend.
+ */
 void ggml_cann_backend_free(void);
+
 #ifdef __cplusplus
 }
-#endif
+#endif