📃 docs(): 添加 API 注释

include/hm_chipset.h

@@ -21,15 +21,64 @@ typedef struct hm_chipset {
     
 } hm_chipset_t;
 
-hm_chipset_t* hm_chipset_get_instance(void);
+/**
+ * @brief Init chipset module.
+ * 
+ * @param chip  Chipset instance.
+ * 
+ * @return int 
+ * @retval  HM_SUCCESS  Success.
+ */
+extern int chip_init(hm_chipset_t* chip);
 
-/* Send a command */
-int chip_hci_cmd_send(uint8_t *buf, uint16_t size);
+/**
+ * @brief Get hci middleware chipset instance.
+ * 
+ * @return hm_chipset_t* 
+ * @retval  Non-NULL    Chipset instance.
+ * @retval  NULL        Error.
+ */
+extern hm_chipset_t* hm_chipset_get_instance(void);
 
-/* Wait until read a event. */
-int chip_hci_event_read(uint8_t *buf, uint16_t size, int ms);
+/**
+ * @brief Send a hci command, used in chipset module.
+ * 
+ * @param buf       Buffer to store a hci command.
+ * @param size      HCI command size with bytes.
+ * 
+ * @return int 
+ * @retval  HM_SUCCESS           Send success.
+ * @retval  -HM_NO_MEMORY        Command memory pool is not enough.
+ * @retval  -HM_UART_SEND_ERR    Uart send command error.
+ */
+extern int chip_hci_cmd_send(uint8_t *buf, uint16_t size);
 
-void chip_send_hci_reset_cmd_until_ack(void);
+/**
+ * @brief Read a hci event, used in chipset module. 
+ *      This function will block until a hci event received or wait time timeout. 
+ *      Usually used in chipset init.
+ * 
+ * @param buf       Buffer to store a hci event.
+ * @param size      Buffer size.
+ * @param ms        Waitting time in ms. Specially, 
+ *              RT_WAITING_NO means no wait, 
+ *              RT_WAITING_FOREVER means wait forever.
+ * 
+ * @return int 
+ * @retval  HM_SUCCESS      Read hci event success.
+ * @retval  -HM_TIMEOUT     Timeout.
+ */
+extern int chip_hci_event_read(uint8_t *buf, uint16_t size, int ms);
+
+/**
+ * @brief This function will continually send HCI-Reset-Command until 
+ *      remote chipset respond a HCI-Somplete-Command-Event.
+ * 
+ * @note Because a chipset may not be ready, if we only send a reset command, 
+ *      remote chipset may not respond any event. So we should continually 
+ *      send reset command in chipset init start and end.
+ */
+extern void chip_send_hci_reset_cmd_until_ack(void);
 
 #ifdef __cplusplus
 }

include/hm_config.h

@@ -5,7 +5,7 @@
 extern "C" {
 #endif
 
-#define HM_CONFIG_BTSTACK   1
+#define HM_CONFIG_BTSTACK   1   /* Use btstack or not. */
 
 #ifdef __cplusplus
 }

include/hm_error.h

@@ -5,17 +5,17 @@
 extern "C" {
 #endif
 
-#define HM_SUCCESS          0   /* Success */
-#define HM_NOT_OPEN         1   /* Device not open */
-#define HM_NO_MEMORY        2   /* Memory is not enough */
-#define HM_THREAD_ERROR     3   /* Thread error */
-#define HM_UART_SEND_ERR    4   /* Uart send error */
-#define HM_HCI_CMD_ERROR    5   /* HCI command error */
-#define HM_CHIPSET_INIT_ERROR   6   /* Chipset init error */
-#define HM_OPEN_FILE_ERROR  7   /* Open file error */
+#define HM_SUCCESS                  0   /* Success */
+#define HM_NOT_OPEN                 1   /* Device not open */
+#define HM_NO_MEMORY                2   /* Memory is not enough */
+#define HM_THREAD_ERROR             3   /* Thread error */
+#define HM_UART_SEND_ERR            4   /* Uart send error */
+#define HM_HCI_CMD_ERROR            5   /* HCI command error */
+#define HM_CHIPSET_INIT_ERROR       6   /* Chipset init error */
+#define HM_OPEN_FILE_ERROR          7   /* Open file error */
 #define HM_CHIPSET_INIT_FILE_ERROR  8   /* Chipset init file is error */
-#define HM_TIMEOUT          9   /* Timeout */
-#define HM_NOT_SUPPORT      10  /* HCI Middleware not support now */
+#define HM_TIMEOUT                  9   /* Timeout */
+#define HM_NOT_SUPPORT              10  /* HCI Middleware not support now */
 
 #ifdef __cplusplus
 }

include/hm_hci_transport_h4.h

@@ -58,32 +58,14 @@ extern int hci_trans_h4_open(void);
 extern int hci_trans_h4_close(void);
 
 
-// typedef void (*hci_trans_h4_package_callback_t)(uint8_t pkg_type, uint8_t *pkg, uint16_t size);
-
-// /**
-//  * @brief Register a callback for incoming package.
-//  * 
-//  * @param callback A callback function pointer.
-//  * 
-//  * @return int
-//  * @retval  HM_SUCCESS      Register success.
-//  * @retval  HM_NO_MEMORY    Malloc memory fail.
-//  * 
-//  * @note If use btstack, this callback is resposibility to free package buffer with `rt_mp_free()`.
-//  */
-// extern int hci_trans_h4_register_callback(hci_trans_h4_package_callback_t callback);
-
-
-// extern void hci_trans_h4_remove_callback(hci_trans_h4_package_callback_t callback);
-
 /**
- * @brief HCI transport h4 receive a byte from uart, used for hci_transport_h4.c .
+ * @brief HCI transport h4 receive a byte from uart, used for hci_transport_h4_uart.c .
  * 
  * @param byte A byte coming from uart.
  * 
  * @return int 
- * @retval  HM_SUCCESS      Receive byte success.
- * @retval  HM_NOT_SUPPORT  H4 sync loss, or this package not support now.
+ * @retval  HM_SUCCESS       Receive byte success.
+ * @retval  -HM_NOT_SUPPORT  H4 sync loss, or this package not support now.
  */
 extern int hci_trans_h4_recv_byte(uint8_t byte);
 
@@ -114,23 +96,68 @@ extern void hci_trans_h4_send_free(uint8_t *buf);
  * @param data HCI package data.
  * 
  * @return int 
- * @retval  HM_SUCCESS  Send success.
- * @retval  HM_NOT_SUPPORT  This type package not support now.
+ * @retval  HM_SUCCESS       Send success.
+ * @retval  -HM_NOT_SUPPORT  This type package not support now.
  */
 extern int hci_trans_h4_send(uint8_t type, uint8_t *data);
 
-// typedef void (*hci_vendor_evt_callback_t)(uint8_t *hci_evt, uint16_t len);
-
-// extern int hci_vendor_cmd_send_sync(uint8_t *hci_cmd, uint16_t len, int32_t time, hci_vendor_evt_callback_t callback);
-
-// extern int hci_cmd_send_sync(uint8_t *hci_cmd, uint16_t len, int32_t time);
-
-// extern int hci_reset_cmd_send(void);
-
+/**
+ * @brief HCI transport h4 receive a hci event.
+ * 
+ * @param buf   A pointer to hci event buffer when receive event successfully.
+ * @param ms    Waitting time in ms. Specially, 
+ *          RT_WAITING_NO means no wait, 
+ *          RT_WAITING_FOREVER means wait forever.
+ * 
+ * @return int 
+ * @retval  HM_SUCCESS      Read hci event success.
+ * @retval  -HM_TIMEOUT     Timeout.
+ * 
+ * @note If this function return successfully, `buf` should be 
+ *      freed with `hci_trans_h4_recv_free()` when it's not needed.
+ */
 int hci_trans_h4_recv_event(uint8_t **buf, int ms);
+
+/**
+ * @brief HCI transport h4 receive a hci acl packet.
+ * 
+ * @param buf   A pointer to hci acl packet buffer when receive acl packet successfully.
+ * @param ms    Waitting time in ms. Specially, 
+ *          RT_WAITING_NO means no wait, 
+ *          RT_WAITING_FOREVER means wait forever.
+ * 
+ * @return int 
+ * @retval  HM_SUCCESS      Read hci acl packet success.
+ * @retval  -HM_TIMEOUT     Timeout.
+ * 
+ * @note If this function return successfully, `buf` should be 
+ *      freed with `hci_trans_h4_recv_free()` when it's not needed.
+ */
 int hci_trans_h4_recv_acl(uint8_t **buf, int ms);
+
+/**
+ * @brief HCI transport h4 receive a packet, which type is not limited.
+ * 
+ * @param buf   A pointer to hci packet buffer when receive successfully.
+ * @param ms    Waitting time in ms. Specially, RT_WAITING_NO means no wait,
+ * @param type  A pointer to restore hci packet type.
+ * 
+ * @return int 
+ * @retval  HM_SUCCESS      Read hci acl packet success.
+ * @retval  -HM_TIMEOUT     Timeout.
+ * 
+ * @note If this function return successfully, `buf` should be 
+ *      freed with `hci_trans_h4_recv_free()` when it's not needed.
+ * 
+ * @note ms shouldn't be RT_WAITING_FOREVER.
+ */
 int hci_trans_h4_recv_all(uint8_t **buf, int ms, uint8_t *type);
 
+/**
+ * @brief Free memory buffer, which is alloc by `hci_trans_h4_recv_*` API.
+ * 
+ * @param p     Memory buffer.
+ */
 void hci_trans_h4_recv_free(uint8_t *p);
 
 #ifdef __cplusplus

include/hm_hci_transport_h4_uart.h

@@ -27,8 +27,8 @@ extern void hci_trans_h4_uart_init(struct hci_trans_h4_uart_config *config);
  * @brief Open H4 uart.
  * 
  * @return int 
- * @retval  HM_SUCCESS              Open success.
- * @retval  HM_THREAD_ERROR Create  h4 uart thread error.
+ * @retval  HM_SUCCESS          Open success.
+ * @retval  -HM_THREAD_ERROR     Create h4 uart thread error.
  */
 extern int hci_trans_h4_uart_open(void);
 
@@ -47,8 +47,8 @@ extern int hci_trans_h4_uart_close(void);
  * @param len Data size needed to be sent.
  * 
  * @return int 
- * @retval  HM_SUCCESS          Send success.
- * @retval  HM_UART_SEND_ERR    H4 uart send error.
+ * @retval  HM_SUCCESS           Send success.
+ * @retval  -HM_UART_SEND_ERR    H4 uart send error.
  */
 int hci_trans_h4_uart_send(uint8_t *data, uint16_t len);