more doxygen work

rename tusb_mouse_report_t (keyboard) to hid_mouse_report_t (keyboard)

8 files changed, 66 insertions, 42 deletions

diff --git a/tinyusb/class/hid.c b/tinyusb/class/hid.c
index 2308e24ac..691751ac4 100644
--- a/tinyusb/class/hid.c
+++ b/tinyusb/class/hid.c
@@ -41,12 +41,12 @@
 #if defined DEVICE_CLASS_HID && defined TUSB_CFG_DEVICE
 
 #ifdef TUSB_CFG_DEVICE_HID_KEYBOARD
-tusb_keyboard_report_t hid_keyboard_report;
+hid_keyboard_report_t hid_keyboard_report;
 static volatile bool bKeyChanged = false;
 #endif
 
 #ifdef TUSB_CFG_DEVICE_HID_MOUSE
-tusb_mouse_report_t hid_mouse_report;
+hid_mouse_report_t hid_mouse_report;
 static volatile bool bMouseChanged = false;
 #endif
 
@@ -68,7 +68,7 @@ ErrorCode_t HID_GetReport( USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t
     #ifdef TUSB_CFG_DEVICE_HID_KEYBOARD
       case HID_PROTOCOL_KEYBOARD:
         *pBuffer = (uint8_t*) &hid_keyboard_report;
-        *plength = sizeof(tusb_keyboard_report_t);
+        *plength = sizeof(hid_keyboard_report_t);
 
         if (!bKeyChanged)
         {
@@ -81,7 +81,7 @@ ErrorCode_t HID_GetReport( USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t
     #ifdef TUSB_CFG_DEVICE_HID_MOUSE
       case HID_PROTOCOL_MOUSE:
         *pBuffer = (uint8_t*) &hid_mouse_report;
-        *plength = sizeof(tusb_mouse_report_t);
+        *plength = sizeof(hid_mouse_report_t);
 
         if (!bMouseChanged)
         {
@@ -132,9 +132,9 @@ ErrorCode_t HID_EpIn_Hdlr (USBD_HANDLE_T hUsb, void* data, uint32_t event)
         case HID_PROTOCOL_KEYBOARD:
           if (!bKeyChanged)
           {
-            memset(&hid_keyboard_report, 0, sizeof(tusb_keyboard_report_t));
+            memset(&hid_keyboard_report, 0, sizeof(hid_keyboard_report_t));
           }
-          ROM_API->hw->WriteEP(hUsb, pHidCtrl->epin_adr, (uint8_t*) &hid_keyboard_report, sizeof(tusb_keyboard_report_t));
+          ROM_API->hw->WriteEP(hUsb, pHidCtrl->epin_adr, (uint8_t*) &hid_keyboard_report, sizeof(hid_keyboard_report_t));
           bKeyChanged = false;
         break;
       #endif
@@ -143,9 +143,9 @@ ErrorCode_t HID_EpIn_Hdlr (USBD_HANDLE_T hUsb, void* data, uint32_t event)
         case HID_PROTOCOL_MOUSE:
           if (!bMouseChanged)
           {
-            memset(&hid_mouse_report, 0, sizeof(tusb_mouse_report_t));
+            memset(&hid_mouse_report, 0, sizeof(hid_mouse_report_t));
           }
-          ROM_API->hw->WriteEP(hUsb, pHidCtrl->epin_adr, (uint8_t*) &hid_mouse_report, sizeof(tusb_mouse_report_t));
+          ROM_API->hw->WriteEP(hUsb, pHidCtrl->epin_adr, (uint8_t*) &hid_mouse_report, sizeof(hid_mouse_report_t));
           bMouseChanged = false;
         break;
       #endif
@@ -224,11 +224,11 @@ tusb_error_t tusb_hid_init(USBD_HANDLE_T hUsb, USB_INTERFACE_DESCRIPTOR const *c
 tusb_error_t tusb_hid_configured(USBD_HANDLE_T hUsb)
 {
   #ifdef  TUSB_CFG_DEVICE_HID_KEYBOARD
-    ROM_API->hw->WriteEP(hUsb , HID_KEYBOARD_EP_IN , (uint8_t* ) &hid_keyboard_report , sizeof(tusb_keyboard_report_t) ); // initial packet for IN endpoint , will not work if omitted
+    ROM_API->hw->WriteEP(hUsb , HID_KEYBOARD_EP_IN , (uint8_t* ) &hid_keyboard_report , sizeof(hid_keyboard_report_t) ); // initial packet for IN endpoint , will not work if omitted
   #endif
 
   #ifdef  TUSB_CFG_DEVICE_HID_MOUSE
-    ROM_API->hw->WriteEP(hUsb , HID_MOUSE_EP_IN    , (uint8_t* ) &hid_mouse_report    , sizeof(tusb_mouse_report_t) ); // initial packet for IN endpoint, will not work if omitted
+    ROM_API->hw->WriteEP(hUsb , HID_MOUSE_EP_IN    , (uint8_t* ) &hid_mouse_report    , sizeof(hid_mouse_report_t) ); // initial packet for IN endpoint, will not work if omitted
   #endif
 
   return TUSB_ERROR_NONE;
diff --git a/tinyusb/class/hid.h b/tinyusb/class/hid.h
index 636cdac8b..6e82517a4 100644
--- a/tinyusb/class/hid.h
+++ b/tinyusb/class/hid.h
@@ -96,8 +96,10 @@ typedef ATTR_PACKED_STRUCT(struct) {
   uint16_t wReportLength;   /**< the total size of the Report descriptor. */

 } tusb_hid_descriptor_hid_t;

 

-/**

- *  \brief Standard HID Boot Protocol Mouse Report.

+/** \addtogroup ClassDriver_HID_Mouse Mouse

+ *  @{ */

+

+/**  \brief Standard HID Boot Protocol Mouse Report.

  *

  *  Type define for a standard Boot Protocol Mouse report

  */

@@ -107,7 +109,11 @@ typedef ATTR_PACKED_STRUCT(struct)
   int8_t  x;       /**< Current delta x movement of the mouse. */

   int8_t  y;       /**< Current delta y movement on the mouse. */

   int8_t  wheel;   /**< Current delta wheel movement on the mouse. */

-} tusb_mouse_report_t;

+} hid_mouse_report_t;

+/// @}

+

+/** \addtogroup ClassDriver_HID_Keyboard Keyboard

+ *  @{ */

 

 /**

  *  \brief Standard HID Boot Protocol Keyboard Report.

@@ -119,7 +125,9 @@ typedef ATTR_PACKED_STRUCT(struct)
   uint8_t modifier; /**< Keyboard modifier byte, indicating pressed modifier keys (a combination of HID_KEYBOARD_MODIFER_* masks). */

   uint8_t reserved; /**< Reserved for OEM use, always set to 0. */

   uint8_t keycode[6]; /**< Key codes of the currently pressed keys. */

-} tusb_keyboard_report_t;

+} hid_keyboard_report_t;

+

+/// @}

 

 /**

  * \brief buttons codes for HID mouse

diff --git a/tinyusb/class/hid_device.c b/tinyusb/class/hid_device.c
index 3653e33ae..d779e4117 100644
--- a/tinyusb/class/hid_device.c
+++ b/tinyusb/class/hid_device.c
@@ -172,13 +172,13 @@ tusb_error_t hidd_init(uint8_t coreid, tusb_descriptor_interface_t const * p_int
 //--------------------------------------------------------------------+
 #if TUSB_CFG_DEVICE_HID_KEYBOARD
 TUSB_CFG_ATTR_USBRAM uint8_t hidd_keyboard_buffer[1024]; // TODO memory reduce
-TUSB_CFG_ATTR_USBRAM tusb_keyboard_report_t hid_keyboard_report;
+TUSB_CFG_ATTR_USBRAM hid_keyboard_report_t hid_keyboard_report;
 static volatile bool bKeyChanged = false;
 #endif
 
 #if TUSB_CFG_DEVICE_HID_MOUSE
 TUSB_CFG_ATTR_USBRAM uint8_t hidd_mouse_buffer[1024]; // TODO memory reduce
-TUSB_CFG_ATTR_USBRAM tusb_mouse_report_t hid_mouse_report;
+TUSB_CFG_ATTR_USBRAM hid_mouse_report_t hid_mouse_report;
 static volatile bool bMouseChanged = false;
 #endif
 
@@ -198,7 +198,7 @@ ErrorCode_t HID_EpOut_Hdlr (USBD_HANDLE_T hUsb, void* data, uint32_t event);
 // APPLICATION API
 //--------------------------------------------------------------------+
 #if TUSB_CFG_DEVICE_HID_KEYBOARD
-tusb_error_t tusbd_hid_keyboard_send_report(tusb_keyboard_report_t *p_kbd_report)
+tusb_error_t tusbd_hid_keyboard_send_report(hid_keyboard_report_t *p_kbd_report)
 {
 //  uint32_t start_time = systickGetSecondsActive();
 //  while (bKeyChanged) // TODO blocking while previous key has yet sent - can use fifo to improve this
@@ -221,7 +221,7 @@ tusb_error_t tusbd_hid_keyboard_send_report(tusb_keyboard_report_t *p_kbd_report
 #endif
 
 #if TUSB_CFG_DEVICE_HID_MOUSE
-tusb_error_t tusbd_hid_mouse_send_report(tusb_mouse_report_t *p_mouse_report)
+tusb_error_t tusbd_hid_mouse_send_report(hid_mouse_report_t *p_mouse_report)
 {
 //  uint32_t start_time = systickGetSecondsActive();
 //  while (bMouseChanged) // TODO Block while previous key hasn't been sent - can use fifo to improve this
@@ -247,11 +247,11 @@ tusb_error_t tusbd_hid_mouse_send_report(tusb_mouse_report_t *p_mouse_report)
 tusb_error_t hidd_configured(void)
 {
   #if  TUSB_CFG_DEVICE_HID_KEYBOARD
-    ROM_API->hw->WriteEP(romdriver_hdl , HID_KEYBOARD_EP_IN , (uint8_t* ) &hid_keyboard_report , sizeof(tusb_keyboard_report_t) ); // initial packet for IN endpoint , will not work if omitted
+    ROM_API->hw->WriteEP(romdriver_hdl , HID_KEYBOARD_EP_IN , (uint8_t* ) &hid_keyboard_report , sizeof(hid_keyboard_report_t) ); // initial packet for IN endpoint , will not work if omitted
   #endif
 
   #if  TUSB_CFG_DEVICE_HID_MOUSE
-    ROM_API->hw->WriteEP(romdriver_hdl , HID_MOUSE_EP_IN    , (uint8_t* ) &hid_mouse_report    , sizeof(tusb_mouse_report_t) ); // initial packet for IN endpoint, will not work if omitted
+    ROM_API->hw->WriteEP(romdriver_hdl , HID_MOUSE_EP_IN    , (uint8_t* ) &hid_mouse_report    , sizeof(hid_mouse_report_t) ); // initial packet for IN endpoint, will not work if omitted
   #endif
 
   return TUSB_ERROR_NONE;
@@ -348,7 +348,7 @@ ErrorCode_t HID_GetReport( USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t
     #if TUSB_CFG_DEVICE_HID_KEYBOARD
       case HID_PROTOCOL_KEYBOARD:
         *pBuffer = (uint8_t*) &hid_keyboard_report;
-        *plength = sizeof(tusb_keyboard_report_t);
+        *plength = sizeof(hid_keyboard_report_t);
 
         if (!bKeyChanged)
         {
@@ -361,7 +361,7 @@ ErrorCode_t HID_GetReport( USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t
     #if TUSB_CFG_DEVICE_HID_MOUSE
       case HID_PROTOCOL_MOUSE:
         *pBuffer = (uint8_t*) &hid_mouse_report;
-        *plength = sizeof(tusb_mouse_report_t);
+        *plength = sizeof(hid_mouse_report_t);
 
         if (!bMouseChanged)
         {
@@ -402,9 +402,9 @@ ErrorCode_t HID_EpIn_Hdlr (USBD_HANDLE_T hUsb, void* data, uint32_t event)
         case HID_PROTOCOL_KEYBOARD:
           if (!bKeyChanged)
           {
-            memset(&hid_keyboard_report, 0, sizeof(tusb_keyboard_report_t));
+            memset(&hid_keyboard_report, 0, sizeof(hid_keyboard_report_t));
           }
-          ROM_API->hw->WriteEP(hUsb, pHidCtrl->epin_adr, (uint8_t*) &hid_keyboard_report, sizeof(tusb_keyboard_report_t));
+          ROM_API->hw->WriteEP(hUsb, pHidCtrl->epin_adr, (uint8_t*) &hid_keyboard_report, sizeof(hid_keyboard_report_t));
           bKeyChanged = false;
         break;
       #endif
@@ -413,9 +413,9 @@ ErrorCode_t HID_EpIn_Hdlr (USBD_HANDLE_T hUsb, void* data, uint32_t event)
         case HID_PROTOCOL_MOUSE:
           if (!bMouseChanged)
           {
-            memset(&hid_mouse_report, 0, sizeof(tusb_mouse_report_t));
+            memset(&hid_mouse_report, 0, sizeof(hid_mouse_report_t));
           }
-          ROM_API->hw->WriteEP(hUsb, pHidCtrl->epin_adr, (uint8_t*) &hid_mouse_report, sizeof(tusb_mouse_report_t));
+          ROM_API->hw->WriteEP(hUsb, pHidCtrl->epin_adr, (uint8_t*) &hid_mouse_report, sizeof(hid_mouse_report_t));
           bMouseChanged = false;
         break;
       #endif
diff --git a/tinyusb/class/hid_device.h b/tinyusb/class/hid_device.h
index 92f9961aa..ff0f342d2 100644
--- a/tinyusb/class/hid_device.h
+++ b/tinyusb/class/hid_device.h
@@ -57,8 +57,8 @@
 //--------------------------------------------------------------------+
 // KEYBOARD Application API
 //--------------------------------------------------------------------+
-tusb_error_t tusbd_hid_keyboard_send_report(tusb_keyboard_report_t *p_kbd_report);
-tusb_error_t tusbd_hid_mouse_send_report(tusb_mouse_report_t *p_mouse_report);
+tusb_error_t tusbd_hid_keyboard_send_report(hid_keyboard_report_t *p_kbd_report);
+tusb_error_t tusbd_hid_mouse_send_report(hid_mouse_report_t *p_mouse_report);
 
 //--------------------------------------------------------------------+
 // USBD-CLASS DRIVER API
diff --git a/tinyusb/class/hid_host.h b/tinyusb/class/hid_host.h
index c61d840cf..9fb765e1d 100644
--- a/tinyusb/class/hid_host.h
+++ b/tinyusb/class/hid_host.h
@@ -85,7 +85,7 @@ bool          tusbh_hid_keyboard_is_busy(uint8_t dev_addr) ATTR_PURE ATTR_WARN_U
  * \retval        TUSB_ERROR_NONE on success

  * \retval        TUSB_ERROR_INTERFACE_IS_BUSY if the interface is already transferring data with device

  * \retval        TUSB_ERROR_DEVICE_NOT_READY if device is not yet configured (by SET CONFIGURED request)

- * \retval        TUSB_ERROR_INVALID_PARA if inputs parameter are not correct

+ * \retval        TUSB_ERROR_INVALID_PARA if input parameters are not correct

  * \note          This function is non-blocking and returns immediately. The result of usb transfer will be reported by the interface's callback function

  */

 tusb_error_t  tusbh_hid_keyboard_get_report(uint8_t dev_addr, void * p_report) /*ATTR_WARN_UNUSED_RESULT*/;

@@ -150,7 +150,7 @@ bool          tusbh_hid_mouse_is_busy(uint8_t dev_addr) ATTR_PURE ATTR_WARN_UNUS
  * \retval        TUSB_ERROR_NONE on success

  * \retval        TUSB_ERROR_INTERFACE_IS_BUSY if the interface is already transferring data with device

  * \retval        TUSB_ERROR_DEVICE_NOT_READY if device is not yet configured (by SET CONFIGURED request)

- * \retval        TUSB_ERROR_INVALID_PARA if inputs parameter are not correct

+ * \retval        TUSB_ERROR_INVALID_PARA if input parameters are not correct

  * \note          This function is non-blocking and returns immediately. The result of usb transfer will be reported by the interface's callback function

  */

 tusb_error_t  tusbh_hid_mouse_get_report(uint8_t dev_addr, void* p_report) /*ATTR_WARN_UNUSED_RESULT*/;

diff --git a/tinyusb/class/msc_host.h b/tinyusb/class/msc_host.h
index 4a738c3a5..a2cba10f2 100644
--- a/tinyusb/class/msc_host.h
+++ b/tinyusb/class/msc_host.h
@@ -112,7 +112,7 @@ tusb_error_t tusbh_msc_get_capacity(uint8_t dev_addr, uint32_t* p_last_lba, uint
  * \retval      TUSB_ERROR_NONE on success

  * \retval      TUSB_ERROR_INTERFACE_IS_BUSY if the interface is already transferring data with device

  * \retval      TUSB_ERROR_DEVICE_NOT_READY if device is not yet configured (by SET CONFIGURED request)

- * \retval      TUSB_ERROR_INVALID_PARA if inputs parameter are not correct

+ * \retval      TUSB_ERROR_INVALID_PARA if input parameters are not correct

  * \note        This function is non-blocking and returns immediately. The result of USB transfer will be reported by the interface's callback function

  */

 tusb_error_t tusbh_msc_read10 (uint8_t dev_addr, uint8_t lun, void * p_buffer, uint32_t lba, uint16_t block_count) ATTR_WARN_UNUSED_RESULT;

@@ -126,7 +126,7 @@ tusb_error_t tusbh_msc_read10 (uint8_t dev_addr, uint8_t lun, void * p_buffer, u
  * \retval      TUSB_ERROR_NONE on success

  * \retval      TUSB_ERROR_INTERFACE_IS_BUSY if the interface is already transferring data with device

  * \retval      TUSB_ERROR_DEVICE_NOT_READY if device is not yet configured (by SET CONFIGURED request)

- * \retval      TUSB_ERROR_INVALID_PARA if inputs parameter are not correct

+ * \retval      TUSB_ERROR_INVALID_PARA if input parameters are not correct

  * \note        This function is non-blocking and returns immediately. The result of USB transfer will be reported by the interface's callback function

  */

 tusb_error_t tusbh_msc_write10(uint8_t dev_addr, uint8_t lun, void const * p_buffer, uint32_t lba, uint16_t block_count) ATTR_WARN_UNUSED_RESULT;

@@ -138,7 +138,7 @@ tusb_error_t tusbh_msc_write10(uint8_t dev_addr, uint8_t lun, void const * p_buf
  * \retval      TUSB_ERROR_NONE on success

  * \retval      TUSB_ERROR_INTERFACE_IS_BUSY if the interface is already transferring data with device

  * \retval      TUSB_ERROR_DEVICE_NOT_READY if device is not yet configured (by SET CONFIGURED request)

- * \retval      TUSB_ERROR_INVALID_PARA if inputs parameter are not correct

+ * \retval      TUSB_ERROR_INVALID_PARA if input parameters are not correct

  * \note        This function is non-blocking and returns immediately. The result of USB transfer will be reported by the interface's callback function

  */

 tusb_error_t tusbh_msc_request_sense(uint8_t dev_addr, uint8_t lun, uint8_t *p_data) ATTR_WARN_UNUSED_RESULT;

@@ -149,7 +149,7 @@ tusb_error_t tusbh_msc_request_sense(uint8_t dev_addr, uint8_t lun, uint8_t *p_d
  * \retval      TUSB_ERROR_NONE on success

  * \retval      TUSB_ERROR_INTERFACE_IS_BUSY if the interface is already transferring data with device

  * \retval      TUSB_ERROR_DEVICE_NOT_READY if device is not yet configured (by SET CONFIGURED request)

- * \retval      TUSB_ERROR_INVALID_PARA if inputs parameter are not correct

+ * \retval      TUSB_ERROR_INVALID_PARA if input parameters are not correct

  * \note        This function is non-blocking and returns immediately. The result of USB transfer will be reported by the interface's callback function

  */

 tusb_error_t tusbh_msc_test_unit_ready(uint8_t dev_addr, uint8_t lun, msc_cmd_status_wrapper_t * p_csw) ATTR_WARN_UNUSED_RESULT; // TODO to be refractor

diff --git a/tinyusb/common/common.h b/tinyusb/common/common.h
index e5c72ba7c..ef8f8c7c2 100644
--- a/tinyusb/common/common.h
+++ b/tinyusb/common/common.h
@@ -71,9 +71,9 @@
 #include "errors.h"
 
 //------------- TUSB Header -------------//
-#include "core/tusb_types.h"
-#include "core/std_descriptors.h"
-#include "core/std_request.h"
+#include "tusb_types.h"
+#include "std_descriptors.h"
+#include "std_request.h"
 
 //--------------------------------------------------------------------+
 // MACROS
diff --git a/tinyusb/hal/hal.h b/tinyusb/hal/hal.h
index 9e336de0f..b90085db6 100644
--- a/tinyusb/hal/hal.h
+++ b/tinyusb/hal/hal.h
@@ -41,8 +41,11 @@
 
 /** \addtogroup Port Port
  * @{
- *  \defgroup Port_Hal Hardware Abtract Layer (HAL)
- *  \brief Hardware Dependent Layer
+ * \defgroup Port_Hal Hardware Abtract Layer (HAL)
+ * Hardware Abstraction Layer (HAL) is an abstraction layer, between the physical hardware and the tinyusb stack.
+ * Its function is to hide differences in hardware from most of MCUs, so that most of the stack code does not need to be changed to
+ * run on systems with a different MCU.
+ * HAL are sets of routines that emulate some platform-specific details, giving programs direct access to the hardware resources.
  *  @{
  */
 
@@ -60,12 +63,24 @@
 // callback from tusb.h
 extern void tusb_isr(uint8_t controller_id);
 
-/// USB hardware init
+/** \brief    Initialize USB controller hardware
+ * \returns   \ref tusb_error_t type to indicate success or error condition.
+ * \note      This function is invoked by \ref tusb_init as part of the initialization.
+ */
 tusb_error_t hal_init(void);
 
-/// Enable USB Interrupt
+/** \brief 			Enable USB Interrupt on a specific USB Controller
+ * \param[in]		controller_id	is a zero-based index to identify USB controller's ID
+ * \note        Some MCUs such as NXP LPC43xx has multiple USB controllers. It is necessary to know which USB controller for
+ *              those MCUs.
+ */
 static inline void hal_interrupt_enable(uint8_t controller_id) ATTR_ALWAYS_INLINE;
-/// Disable USB Interrupt
+
+/** \brief 			Disable USB Interrupt on a specific USB Controller
+ * \param[in]		controller_id	is a zero-based index to identify USB controller's ID
+ * \note        Some MCUs such as NXP LPC43xx has multiple USB controllers. It is necessary to know which USB controller for
+ *              those MCUs.
+ */
 static inline void hal_interrupt_disable(uint8_t controller_id) ATTR_ALWAYS_INLINE;
 
 //--------------------------------------------------------------------+
@@ -93,6 +108,7 @@ extern "C" {
 static inline bool hal_debugger_is_attached(void) ATTR_PURE ATTR_ALWAYS_INLINE;
 static inline bool hal_debugger_is_attached(void)
 {
+// TODO check core M3/M4 defined instead
 #if !defined(_TEST_) && !(MCU==MCU_LPC11UXX)
   return ( (CoreDebug->DHCSR & CoreDebug_DHCSR_C_DEBUGEN_Msk) == CoreDebug_DHCSR_C_DEBUGEN_Msk );
 #else