more doxygen work

rename tusb_mouse_report_t (keyboard) to hid_mouse_report_t (keyboard)

15 files changed, 98 insertions, 73 deletions

diff --git a/demos/device/keyboard/main.c b/demos/device/keyboard/main.c
index eb943221e..6fa31e294 100644
--- a/demos/device/keyboard/main.c
+++ b/demos/device/keyboard/main.c
@@ -102,7 +102,7 @@ void keyboard_device_app_task(void * p_para)
       count++;
 
       tusbd_hid_keyboard_send_report(
-          &(tusb_keyboard_report_t) {
+          &(hid_keyboard_report_t) {
               .keycode = { 0x04 } }
       );
     }
@@ -122,7 +122,7 @@ void mouse_device_app_task(void * p_para)
     {
       count++;
       tusbd_hid_mouse_send_report(
-          &(tusb_mouse_report_t) {
+          &(hid_mouse_report_t) {
               .x = 20,
               .y = 20 } );
     }
diff --git a/demos/host/src/keyboard_app.c b/demos/host/src/keyboard_app.c
index e978af5fe..8a1beb4fd 100644
--- a/demos/host/src/keyboard_app.c
+++ b/demos/host/src/keyboard_app.c
@@ -56,13 +56,13 @@
 // INTERNAL OBJECT & FUNCTION DECLARATION

 //--------------------------------------------------------------------+

 OSAL_TASK_DEF(keyboard_app_task, 128, KEYBOARD_APP_TASK_PRIO);

-OSAL_QUEUE_DEF(queue_kbd_def, QUEUE_KEYBOARD_REPORT_DEPTH, tusb_keyboard_report_t);

+OSAL_QUEUE_DEF(queue_kbd_def, QUEUE_KEYBOARD_REPORT_DEPTH, hid_keyboard_report_t);

 

 static osal_queue_handle_t queue_kbd_hdl;

-static tusb_keyboard_report_t usb_keyboard_report TUSB_CFG_ATTR_USBRAM;

+static hid_keyboard_report_t usb_keyboard_report TUSB_CFG_ATTR_USBRAM;

 

 static inline uint8_t keycode_to_ascii(uint8_t modifier, uint8_t keycode) ATTR_CONST ATTR_ALWAYS_INLINE;

-static inline void process_kbd_report(tusb_keyboard_report_t const * report);

+static inline void process_kbd_report(hid_keyboard_report_t const * report);

 

 //--------------------------------------------------------------------+

 // tinyusb callback (ISR context)

@@ -106,7 +106,7 @@ void tusbh_hid_keyboard_isr(uint8_t dev_addr, tusb_event_t event)
 //--------------------------------------------------------------------+

 void keyboard_app_init(void)

 {

-  memclr_(&usb_keyboard_report, sizeof(tusb_keyboard_report_t));

+  memclr_(&usb_keyboard_report, sizeof(hid_keyboard_report_t));

 

   queue_kbd_hdl = osal_queue_create( OSAL_QUEUE_REF(queue_kbd_def) );

   ASSERT_PTR( queue_kbd_hdl, VOID_RETURN );

@@ -119,7 +119,7 @@ void keyboard_app_init(void)
 OSAL_TASK_FUNCTION( keyboard_app_task ) (void* p_task_para)

 {

   tusb_error_t error;

-  tusb_keyboard_report_t kbd_report;

+  hid_keyboard_report_t kbd_report;

 

   OSAL_TASK_LOOP_BEGIN

 

@@ -135,7 +135,7 @@ OSAL_TASK_FUNCTION( keyboard_app_task ) (void* p_task_para)
 //--------------------------------------------------------------------+

 

 // look up new key in previous keys

-static inline bool is_key_in_report(tusb_keyboard_report_t const *p_report, uint8_t modifier, uint8_t keycode)

+static inline bool is_key_in_report(hid_keyboard_report_t const *p_report, uint8_t modifier, uint8_t keycode)

 {

   for(uint8_t i=0; i<6; i++)

   {

@@ -148,9 +148,9 @@ static inline bool is_key_in_report(tusb_keyboard_report_t const *p_report, uint
   return false;

 }

 

-static inline void process_kbd_report(tusb_keyboard_report_t const *p_new_report)

+static inline void process_kbd_report(hid_keyboard_report_t const *p_new_report)

 {

-  static tusb_keyboard_report_t prev_report = { 0 }; // previous report to check key released

+  static hid_keyboard_report_t prev_report = { 0 }; // previous report to check key released

 

   //------------- example code ignore control (non-printable) key affects -------------//

   for(uint8_t i=0; i<6; i++)

diff --git a/demos/host/src/mouse_app.c b/demos/host/src/mouse_app.c
index c5969cd40..59798691b 100644
--- a/demos/host/src/mouse_app.c
+++ b/demos/host/src/mouse_app.c
@@ -57,12 +57,12 @@
 // INTERNAL OBJECT & FUNCTION DECLARATION

 //--------------------------------------------------------------------+

 OSAL_TASK_DEF(mouse_app_task, 128, MOUSE_APP_TASK_PRIO);

-OSAL_QUEUE_DEF(queue_mouse_def, QUEUE_MOUSE_REPORT_DEPTH, tusb_mouse_report_t);

+OSAL_QUEUE_DEF(queue_mouse_def, QUEUE_MOUSE_REPORT_DEPTH, hid_mouse_report_t);

 

 static osal_queue_handle_t queue_mouse_hdl;

-static tusb_mouse_report_t usb_mouse_report TUSB_CFG_ATTR_USBRAM;

+static hid_mouse_report_t usb_mouse_report TUSB_CFG_ATTR_USBRAM;

 

-static inline void process_mouse_report(tusb_mouse_report_t const * p_report);

+static inline void process_mouse_report(hid_mouse_report_t const * p_report);

 

 //--------------------------------------------------------------------+

 // tinyusb callback (ISR context)

@@ -108,7 +108,7 @@ void tusbh_hid_mouse_isr(uint8_t dev_addr, tusb_event_t event)
 //--------------------------------------------------------------------+

 void mouse_app_init(void)

 {

-  memclr_(&usb_mouse_report, sizeof(tusb_mouse_report_t));

+  memclr_(&usb_mouse_report, sizeof(hid_mouse_report_t));

 

   queue_mouse_hdl = osal_queue_create( OSAL_QUEUE_REF(queue_mouse_def) );

   ASSERT_PTR( queue_mouse_hdl, VOID_RETURN);

@@ -121,7 +121,7 @@ void mouse_app_init(void)
 OSAL_TASK_FUNCTION( mouse_app_task ) (void* p_task_para)

 {

   tusb_error_t error;

-  tusb_mouse_report_t mouse_report;

+  hid_mouse_report_t mouse_report;

 

   OSAL_TASK_LOOP_BEGIN

 

@@ -164,9 +164,9 @@ void cursor_movement(int8_t x, int8_t y, int8_t wheel)
   }else { }

 }

 

-static inline void process_mouse_report(tusb_mouse_report_t const * p_report)

+static inline void process_mouse_report(hid_mouse_report_t const * p_report)

 {

-  static tusb_mouse_report_t prev_report = { 0 };

+  static hid_mouse_report_t prev_report = { 0 };

 

   //------------- button state  -------------//

   uint8_t button_changed_mask = p_report->buttons ^ prev_report.buttons;

diff --git a/tests/lpc18xx_43xx/test/host/hid/test_hidh_generic.c b/tests/lpc18xx_43xx/test/host/hid/test_hidh_generic.c
index b50f84404..d3d7f9cae 100644
--- a/tests/lpc18xx_43xx/test/host/hid/test_hidh_generic.c
+++ b/tests/lpc18xx_43xx/test/host/hid/test_hidh_generic.c
@@ -56,7 +56,7 @@
 
 extern hidh_interface_info_t mouseh_data[TUSB_CFG_HOST_DEVICE_MAX];
 hidh_interface_info_t *p_hidh_mouse;
-tusb_mouse_report_t report;
+hid_mouse_report_t report;
 
 tusb_descriptor_interface_t const *p_mouse_interface_desc = &desc_configuration.mouse_interface;
 tusb_descriptor_endpoint_t  const *p_mouse_endpoint_desc  = &desc_configuration.mouse_endpoint;
@@ -75,7 +75,7 @@ void setUp(void)
 //
 //  p_hidh_mouse = &mouse_data[dev_addr-1];
 //
-//  p_hidh_mouse->report_size = sizeof(tusb_mouse_report_t);
+//  p_hidh_mouse->report_size = sizeof(hid_mouse_report_t);
 //  p_hidh_mouse->pipe_hdl = (pipe_handle_t) {
 //    .dev_addr  = dev_addr,
 //    .xfer_type = TUSB_XFER_INTERRUPT,
diff --git a/tests/lpc18xx_43xx/test/host/hid/test_hidh_keyboard.c b/tests/lpc18xx_43xx/test/host/hid/test_hidh_keyboard.c
index ee1016969..ed9d90237 100644
--- a/tests/lpc18xx_43xx/test/host/hid/test_hidh_keyboard.c
+++ b/tests/lpc18xx_43xx/test/host/hid/test_hidh_keyboard.c
@@ -50,7 +50,7 @@
 
 extern hidh_interface_info_t keyboardh_data[TUSB_CFG_HOST_DEVICE_MAX];
 
-tusb_keyboard_report_t sample_key[2] =
+hid_keyboard_report_t sample_key[2] =
 {
     {
         .modifier = KEYBOARD_MODIFIER_LEFTCTRL,
@@ -65,7 +65,7 @@ tusb_keyboard_report_t sample_key[2] =
 uint8_t dev_addr;
 hidh_interface_info_t *p_hidh_kbd;
 
-tusb_keyboard_report_t report;
+hid_keyboard_report_t report;
 
 tusb_descriptor_interface_t const *p_kbd_interface_desc = &desc_configuration.keyboard_interface;
 tusb_descriptor_endpoint_t  const *p_kdb_endpoint_desc  = &desc_configuration.keyboard_endpoint;
@@ -73,12 +73,12 @@ tusb_descriptor_endpoint_t  const *p_kdb_endpoint_desc  = &desc_configuration.ke
 void setUp(void)
 {
   hidh_init();
-  memclr_(&report, sizeof(tusb_keyboard_report_t));
+  memclr_(&report, sizeof(hid_keyboard_report_t));
   dev_addr = RANDOM(TUSB_CFG_HOST_DEVICE_MAX)+1;
 
   p_hidh_kbd = &keyboardh_data[dev_addr-1];
 
-  p_hidh_kbd->report_size = sizeof(tusb_keyboard_report_t);
+  p_hidh_kbd->report_size = sizeof(hid_keyboard_report_t);
   p_hidh_kbd->pipe_hdl = (pipe_handle_t) {
     .dev_addr  = dev_addr,
     .xfer_type = TUSB_XFER_INTERRUPT,
diff --git a/tests/lpc18xx_43xx/test/host/hid/test_hidh_mouse.c b/tests/lpc18xx_43xx/test/host/hid/test_hidh_mouse.c
index 507a041dc..28d22ac42 100644
--- a/tests/lpc18xx_43xx/test/host/hid/test_hidh_mouse.c
+++ b/tests/lpc18xx_43xx/test/host/hid/test_hidh_mouse.c
@@ -51,7 +51,7 @@
 
 extern hidh_interface_info_t mouseh_data[TUSB_CFG_HOST_DEVICE_MAX];
 hidh_interface_info_t *p_hidh_mouse;
-tusb_mouse_report_t report;
+hid_mouse_report_t report;
 
 tusb_descriptor_interface_t const *p_mouse_interface_desc = &desc_configuration.mouse_interface;
 tusb_descriptor_endpoint_t  const *p_mouse_endpoint_desc  = &desc_configuration.mouse_endpoint;
@@ -62,12 +62,12 @@ void setUp(void)
 {
   hidh_init();
 
-  memclr_(&report, sizeof(tusb_mouse_report_t));
+  memclr_(&report, sizeof(hid_mouse_report_t));
   dev_addr = RANDOM(TUSB_CFG_HOST_DEVICE_MAX)+1;
 
   p_hidh_mouse = &mouseh_data[dev_addr-1];
 
-  p_hidh_mouse->report_size = sizeof(tusb_mouse_report_t);
+  p_hidh_mouse->report_size = sizeof(hid_mouse_report_t);
   p_hidh_mouse->pipe_hdl = (pipe_handle_t) {
     .dev_addr  = dev_addr,
     .xfer_type = TUSB_XFER_INTERRUPT,
diff --git a/tinyusb.Doxyfile b/tinyusb.Doxyfile
index e6b7fac5c..a0a87b417 100644
--- a/tinyusb.Doxyfile
+++ b/tinyusb.Doxyfile
@@ -424,7 +424,7 @@ EXTRACT_PACKAGE        = NO
 # included in the documentation.
 # The default value is: NO.
 
-EXTRACT_STATIC         = NO
+EXTRACT_STATIC         = YES
 
 # If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) defined
 # locally in source files will be included in the documentation. If set to NO
@@ -457,7 +457,7 @@ EXTRACT_ANON_NSPACES   = NO
 # section is generated. This option has no effect if EXTRACT_ALL is enabled.
 # The default value is: NO.
 
-HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_MEMBERS     = YES
 
 # If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all
 # undocumented classes that are normally visible in the class hierarchy. If set
@@ -1956,7 +1956,7 @@ ENABLE_PREPROCESSING   = YES
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
 # the macro expansion is limited to the macros specified with the PREDEFINED and
@@ -1964,7 +1964,7 @@ MACRO_EXPANSION        = NO
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-EXPAND_ONLY_PREDEF     = NO
+EXPAND_ONLY_PREDEF     = YES
 
 # If the SEARCH_INCLUDES tag is set to YES the includes files in the
 # INCLUDE_PATH will be searched if a #include is found.
@@ -1999,7 +1999,8 @@ INCLUDE_FILE_PATTERNS  =
 PREDEFINED             = TUSB_CFG_CONTROLLER_0_MODE=TUSB_MODE_HOST \
                          TUSB_CFG_CONTROLLER_1_MODE=TUSB_MODE_HOST \
                          TUSB_CFG_HOST_HID_KEYBOARD=1 \
-                         TUSB_CFG_HOST_CDC_RNDIS=1
+                         TUSB_CFG_HOST_CDC_RNDIS=1 \
+                         ATTR_PACKED_STRUCT(x)=x
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The
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