clean up, rename some HID device symbol/API

- add tud_hid_n_interface_protocol()
- rename tud_hid_n_boot_mode() to  tud_hid_n_get_protocol()
- rename tud_hid_boot_mode_cb() to tud_hid_set_protocol_cb()
- add HID_PROTOCOL_BOOT/REPORT to avoid magic number 0,1
- rename HID_PROTOCOL_NONE/KEYBOARD/MOUSE to HID_ITF_PROTOCOL_ to avoid
confusion

4 files changed, 87 insertions, 59 deletions

diff --git a/src/class/hid/hid.h b/src/class/hid/hid.h
index 351a4d600..6014e54a6 100644
--- a/src/class/hid/hid.h
+++ b/src/class/hid/hid.h
@@ -62,15 +62,15 @@ typedef enum
 {
   HID_SUBCLASS_NONE = 0, ///< No Subclass
   HID_SUBCLASS_BOOT = 1  ///< Boot Interface Subclass
-}hid_subclass_type_t;
+}hid_subclass_enum_t;
 
-/// HID Protocol
+/// HID Interface Protocol
 typedef enum
 {
-  HID_PROTOCOL_NONE     = 0, ///< None
-  HID_PROTOCOL_KEYBOARD = 1, ///< Keyboard
-  HID_PROTOCOL_MOUSE    = 2  ///< Mouse
-}hid_protocol_type_t;
+  HID_ITF_PROTOCOL_NONE     = 0, ///< None
+  HID_ITF_PROTOCOL_KEYBOARD = 1, ///< Keyboard
+  HID_ITF_PROTOCOL_MOUSE    = 2  ///< Mouse
+}hid_interface_protocol_enum_t;
 
 /// HID Descriptor Type
 typedef enum
@@ -78,7 +78,7 @@ typedef enum
   HID_DESC_TYPE_HID      = 0x21, ///< HID Descriptor
   HID_DESC_TYPE_REPORT   = 0x22, ///< Report Descriptor
   HID_DESC_TYPE_PHYSICAL = 0x23  ///< Physical Descriptor
-}hid_descriptor_type_t;
+}hid_descriptor_enum_t;
 
 /// HID Request Report Type
 typedef enum
@@ -87,7 +87,7 @@ typedef enum
   HID_REPORT_TYPE_INPUT,      ///< Input
   HID_REPORT_TYPE_OUTPUT,     ///< Output
   HID_REPORT_TYPE_FEATURE     ///< Feature
-}hid_report_type_t;
+}hid_report_enum_t;
 
 /// HID Class Specific Control Request
 typedef enum
@@ -98,9 +98,9 @@ typedef enum
   HID_REQ_CONTROL_SET_REPORT   = 0x09, ///< Set Report
   HID_REQ_CONTROL_SET_IDLE     = 0x0a, ///< Set Idle
   HID_REQ_CONTROL_SET_PROTOCOL = 0x0b  ///< Set Protocol
-}hid_request_type_t;
+}hid_request_enum_t;
 
-/// HID Country Code
+/// HID Local Code
 typedef enum
 {
   HID_LOCAL_NotSupported = 0   , ///< NotSupported
@@ -139,7 +139,14 @@ typedef enum
   HID_LOCAL_US                 , ///< US
   HID_LOCAL_Yugoslavia         , ///< Yugoslavia
   HID_LOCAL_Turkish_F            ///< Turkish-F
-} hid_country_code_t;
+} hid_local_enum_t;
+
+// HID protocol value used by GetProtocol / SetProtocol
+enum
+{
+  HID_PROTOCOL_BOOT = 0,
+  HID_PROTOCOL_REPORT = 1
+};
 
 /** @} */
 
diff --git a/src/class/hid/hid_device.c b/src/class/hid/hid_device.c
index 18d35bc20..62d63e30a 100644
--- a/src/class/hid/hid_device.c
+++ b/src/class/hid/hid_device.c
@@ -43,7 +43,8 @@ typedef struct
   uint8_t itf_num;
   uint8_t ep_in;
   uint8_t ep_out;        // optional Out endpoint
-  uint8_t boot_protocol; // Boot mouse or keyboard
+  uint8_t itf_protocol;  // Boot mouse or keyboard
+
   bool    boot_mode;     // default = false (Report)
   uint8_t idle_rate;     // up to application to handle idle rate
   uint16_t report_desc_len;
@@ -51,6 +52,8 @@ typedef struct
   CFG_TUSB_MEM_ALIGN uint8_t epin_buf[CFG_TUD_HID_EP_BUFSIZE];
   CFG_TUSB_MEM_ALIGN uint8_t epout_buf[CFG_TUD_HID_EP_BUFSIZE];
 
+  // TODO save hid descriptor since host can specifically request this after enumeration
+  // Note: HID descriptor may be not available from application after enumeration
   tusb_hid_descriptor_hid_t const * hid_descriptor;
 } hidd_interface_t;
 
@@ -70,16 +73,16 @@ static inline uint8_t get_index_by_itfnum(uint8_t itf_num)
 //--------------------------------------------------------------------+
 // APPLICATION API
 //--------------------------------------------------------------------+
-bool tud_hid_n_ready(uint8_t itf)
+bool tud_hid_n_ready(uint8_t instance)
 {
-  uint8_t const ep_in = _hidd_itf[itf].ep_in;
+  uint8_t const ep_in = _hidd_itf[instance].ep_in;
   return tud_ready() && (ep_in != 0) && !usbd_edpt_busy(TUD_OPT_RHPORT, ep_in);
 }
 
-bool tud_hid_n_report(uint8_t itf, uint8_t report_id, void const* report, uint8_t len)
+bool tud_hid_n_report(uint8_t instance, uint8_t report_id, void const* report, uint8_t len)
 {
   uint8_t const rhport = 0;
-  hidd_interface_t * p_hid = &_hidd_itf[itf];
+  hidd_interface_t * p_hid = &_hidd_itf[instance];
 
   // claim endpoint
   TU_VERIFY( usbd_edpt_claim(rhport, p_hid->ep_in) );
@@ -102,12 +105,17 @@ bool tud_hid_n_report(uint8_t itf, uint8_t report_id, void const* report, uint8_
   return usbd_edpt_xfer(TUD_OPT_RHPORT, p_hid->ep_in, p_hid->epin_buf, len);
 }
 
-bool tud_hid_n_boot_mode(uint8_t itf)
+uint8_t tud_hid_n_interface_protocol(uint8_t instance)
+{
+  return _hidd_itf[instance].itf_protocol;
+}
+
+bool tud_hid_n_get_protocol(uint8_t instance)
 {
-  return _hidd_itf[itf].boot_mode;
+  return _hidd_itf[instance].boot_mode;
 }
 
-bool tud_hid_n_keyboard_report(uint8_t itf, uint8_t report_id, uint8_t modifier, uint8_t keycode[6])
+bool tud_hid_n_keyboard_report(uint8_t instance, uint8_t report_id, uint8_t modifier, uint8_t keycode[6])
 {
   hid_keyboard_report_t report;
 
@@ -121,10 +129,10 @@ bool tud_hid_n_keyboard_report(uint8_t itf, uint8_t report_id, uint8_t modifier,
     tu_memclr(report.keycode, 6);
   }
 
-  return tud_hid_n_report(itf, report_id, &report, sizeof(report));
+  return tud_hid_n_report(instance, report_id, &report, sizeof(report));
 }
 
-bool tud_hid_n_mouse_report(uint8_t itf, uint8_t report_id,
+bool tud_hid_n_mouse_report(uint8_t instance, uint8_t report_id,
                             uint8_t buttons, int8_t x, int8_t y, int8_t vertical, int8_t horizontal)
 {
   hid_mouse_report_t report =
@@ -136,10 +144,10 @@ bool tud_hid_n_mouse_report(uint8_t itf, uint8_t report_id,
     .pan     = horizontal
   };
 
-  return tud_hid_n_report(itf, report_id, &report, sizeof(report));
+  return tud_hid_n_report(instance, report_id, &report, sizeof(report));
 }
 
-bool tud_hid_n_gamepad_report(uint8_t itf, uint8_t report_id,
+bool tud_hid_n_gamepad_report(uint8_t instance, uint8_t report_id,
                               int8_t x, int8_t y, int8_t z, int8_t rz, int8_t rx, int8_t ry, uint8_t hat, uint16_t buttons)
 {
   hid_gamepad_report_t report =
@@ -154,7 +162,7 @@ bool tud_hid_n_gamepad_report(uint8_t itf, uint8_t report_id,
     .buttons = buttons,
   };
 
-  return tud_hid_n_report(itf, report_id, &report, sizeof(report));
+  return tud_hid_n_report(instance, report_id, &report, sizeof(report));
 }
 
 //--------------------------------------------------------------------+
@@ -203,7 +211,7 @@ uint16_t hidd_open(uint8_t rhport, tusb_desc_interface_t const * desc_itf, uint1
   p_desc = tu_desc_next(p_desc);
   TU_ASSERT(usbd_open_edpt_pair(rhport, p_desc, desc_itf->bNumEndpoints, TUSB_XFER_INTERRUPT, &p_hid->ep_out, &p_hid->ep_in), 0);
 
-  if ( desc_itf->bInterfaceSubClass == HID_SUBCLASS_BOOT ) p_hid->boot_protocol = desc_itf->bInterfaceProtocol;
+  if ( desc_itf->bInterfaceSubClass == HID_SUBCLASS_BOOT ) p_hid->itf_protocol = desc_itf->bInterfaceProtocol;
 
   p_hid->boot_mode = false; // default mode is REPORT
   p_hid->itf_num   = desc_itf->bInterfaceNumber;
@@ -318,8 +326,7 @@ bool hidd_control_xfer_cb (uint8_t rhport, uint8_t stage, tusb_control_request_t
       case HID_REQ_CONTROL_GET_PROTOCOL:
         if ( stage == CONTROL_STAGE_SETUP )
         {
-          // 0 is Boot, 1 is Report protocol
-          uint8_t protocol = (uint8_t)(1-p_hid->boot_mode);
+          uint8_t protocol = (p_hid->boot_mode ? HID_PROTOCOL_BOOT : HID_PROTOCOL_REPORT);
           tud_control_xfer(rhport, request, &protocol, 1);
         }
       break;
@@ -327,15 +334,14 @@ bool hidd_control_xfer_cb (uint8_t rhport, uint8_t stage, tusb_control_request_t
       case HID_REQ_CONTROL_SET_PROTOCOL:
         if ( stage == CONTROL_STAGE_SETUP )
         {
-          // 0 is Boot, 1 is Report protocol
-          p_hid->boot_mode = 1 - request->wValue;
+          p_hid->boot_mode = (request->wValue == HID_PROTOCOL_BOOT);
           tud_control_status(rhport, request);
         }
         else if ( stage == CONTROL_STAGE_ACK )
         {
-          if (tud_hid_boot_mode_cb)
+          if (tud_hid_set_protocol_cb)
           {
-            tud_hid_boot_mode_cb(hid_itf, p_hid->boot_mode);
+            tud_hid_set_protocol_cb(hid_itf, p_hid->boot_mode);
           }
         }
       break;
@@ -354,29 +360,29 @@ bool hidd_xfer_cb(uint8_t rhport, uint8_t ep_addr, xfer_result_t result, uint32_
 {
   (void) result;
 
-  uint8_t itf = 0;
+  uint8_t instance = 0;
   hidd_interface_t * p_hid = _hidd_itf;
 
   // Identify which interface to use
-  for (itf = 0; itf < CFG_TUD_HID; itf++)
+  for (instance = 0; instance < CFG_TUD_HID; instance++)
   {
-    p_hid = &_hidd_itf[itf];
+    p_hid = &_hidd_itf[instance];
     if ( (ep_addr == p_hid->ep_out) || (ep_addr == p_hid->ep_in) ) break;
   }
-  TU_ASSERT(itf < CFG_TUD_HID);
+  TU_ASSERT(instance < CFG_TUD_HID);
 
   // Sent report successfully
   if (ep_addr == p_hid->ep_in)
   {
     if (tud_hid_report_complete_cb)
     {
-      tud_hid_report_complete_cb(itf, p_hid->epin_buf, (uint8_t) xferred_bytes);
+      tud_hid_report_complete_cb(instance, p_hid->epin_buf, (uint8_t) xferred_bytes);
     }
   }
   // Received report
   else if (ep_addr == p_hid->ep_out)
   {
-    tud_hid_set_report_cb(itf, 0, HID_REPORT_TYPE_INVALID, p_hid->epout_buf, xferred_bytes);
+    tud_hid_set_report_cb(instance, 0, HID_REPORT_TYPE_INVALID, p_hid->epout_buf, xferred_bytes);
     TU_ASSERT(usbd_edpt_xfer(rhport, p_hid->ep_out, p_hid->epout_buf, sizeof(p_hid->epout_buf)));
   }
 
diff --git a/src/class/hid/hid_device.h b/src/class/hid/hid_device.h
index 0c59d5d20..cc34f19ac 100644
--- a/src/class/hid/hid_device.h
+++ b/src/class/hid/hid_device.h
@@ -55,34 +55,39 @@
 //--------------------------------------------------------------------+
 
 // Check if the interface is ready to use
-bool tud_hid_n_ready(uint8_t itf);
+bool tud_hid_n_ready(uint8_t instance);
 
-// Check if current mode is Boot (true) or Report (false)
-bool tud_hid_n_boot_mode(uint8_t itf);
+// Get interface supported protocol (bInterfaceProtocol) check out hid_interface_protocol_enum_t for possible value
+uint8_t tud_hid_n_interface_protocol(uint8_t instance);
+
+// Check if active protocol is Boot (true) or Report (false)
+bool tud_hid_n_get_protocol(uint8_t instance);
 
 // Send report to host
-bool tud_hid_n_report(uint8_t itf, uint8_t report_id, void const* report, uint8_t len);
+bool tud_hid_n_report(uint8_t instance, uint8_t report_id, void const* report, uint8_t len);
 
 // KEYBOARD: convenient helper to send keyboard report if application
 // use template layout report as defined by hid_keyboard_report_t
-bool tud_hid_n_keyboard_report(uint8_t itf, uint8_t report_id, uint8_t modifier, uint8_t keycode[6]);
+bool tud_hid_n_keyboard_report(uint8_t instance, uint8_t report_id, uint8_t modifier, uint8_t keycode[6]);
 
 // MOUSE: convenient helper to send mouse report if application
 // use template layout report as defined by hid_mouse_report_t
-bool tud_hid_n_mouse_report(uint8_t itf, uint8_t report_id, uint8_t buttons, int8_t x, int8_t y, int8_t vertical, int8_t horizontal);
+bool tud_hid_n_mouse_report(uint8_t instance, uint8_t report_id, uint8_t buttons, int8_t x, int8_t y, int8_t vertical, int8_t horizontal);
 
 // Gamepad: convenient helper to send mouse report if application
 // use template layout report TUD_HID_REPORT_DESC_GAMEPAD
-bool tud_hid_n_gamepad_report(uint8_t itf, uint8_t report_id, int8_t x, int8_t y, int8_t z, int8_t rz, int8_t rx, int8_t ry, uint8_t hat, uint16_t buttons);
+bool tud_hid_n_gamepad_report(uint8_t instance, uint8_t report_id, int8_t x, int8_t y, int8_t z, int8_t rz, int8_t rx, int8_t ry, uint8_t hat, uint16_t buttons);
 
 //--------------------------------------------------------------------+
 // Application API (Single Port)
 //--------------------------------------------------------------------+
-static inline bool tud_hid_ready(void);
-static inline bool tud_hid_boot_mode(void);
-static inline bool tud_hid_report(uint8_t report_id, void const* report, uint8_t len);
-static inline bool tud_hid_keyboard_report(uint8_t report_id, uint8_t modifier, uint8_t keycode[6]);
-static inline bool tud_hid_mouse_report(uint8_t report_id, uint8_t buttons, int8_t x, int8_t y, int8_t vertical, int8_t horizontal);
+static inline bool    tud_hid_ready(void);
+static inline uint8_t tud_hid_interface_protocol(void);
+static inline bool    tud_hid_get_protocol(void);
+static inline bool    tud_hid_report(uint8_t report_id, void const* report, uint8_t len);
+static inline bool    tud_hid_keyboard_report(uint8_t report_id, uint8_t modifier, uint8_t keycode[6]);
+static inline bool    tud_hid_mouse_report(uint8_t report_id, uint8_t buttons, int8_t x, int8_t y, int8_t vertical, int8_t horizontal);
+static inline bool    tud_hid_gamepad_report(uint8_t report_id, int8_t x, int8_t y, int8_t z, int8_t rz, int8_t rx, int8_t ry, uint8_t hat, uint16_t buttons);
 
 //--------------------------------------------------------------------+
 // Callbacks (Weak is optional)
@@ -90,29 +95,29 @@ static inline bool tud_hid_mouse_report(uint8_t report_id, uint8_t buttons, int8
 
 // Invoked when received GET HID REPORT DESCRIPTOR request
 // Application return pointer to descriptor, whose contents must exist long enough for transfer to complete
-uint8_t const * tud_hid_descriptor_report_cb(uint8_t itf);
+uint8_t const * tud_hid_descriptor_report_cb(uint8_t instance);
 
 // Invoked when received GET_REPORT control request
 // Application must fill buffer report's content and return its length.
 // Return zero will cause the stack to STALL request
-uint16_t tud_hid_get_report_cb(uint8_t itf, uint8_t report_id, hid_report_type_t report_type, uint8_t* buffer, uint16_t reqlen);
+uint16_t tud_hid_get_report_cb(uint8_t instance, uint8_t report_id, hid_report_type_t report_type, uint8_t* buffer, uint16_t reqlen);
 
 // Invoked when received SET_REPORT control request or
 // received data on OUT endpoint ( Report ID = 0, Type = 0 )
-void tud_hid_set_report_cb(uint8_t itf, uint8_t report_id, hid_report_type_t report_type, uint8_t const* buffer, uint16_t bufsize);
+void tud_hid_set_report_cb(uint8_t instance, uint8_t report_id, hid_report_type_t report_type, uint8_t const* buffer, uint16_t bufsize);
 
 // Invoked when received SET_PROTOCOL request ( mode switch Boot <-> Report )
-TU_ATTR_WEAK void tud_hid_boot_mode_cb(uint8_t itf, uint8_t boot_mode);
+TU_ATTR_WEAK void tud_hid_set_protocol_cb(uint8_t instance, bool boot_mode);
 
 // Invoked when received SET_IDLE request. return false will stall the request
 // - Idle Rate = 0 : only send report if there is changes, i.e skip duplication
 // - Idle Rate > 0 : skip duplication, but send at least 1 report every idle rate (in unit of 4 ms).
-TU_ATTR_WEAK bool tud_hid_set_idle_cb(uint8_t itf, uint8_t idle_rate);
+TU_ATTR_WEAK bool tud_hid_set_idle_cb(uint8_t instance, uint8_t idle_rate);
 
 // Invoked when sent REPORT successfully to host
 // Application can use this to send the next report
 // Note: For composite reports, report[0] is report ID
-TU_ATTR_WEAK void tud_hid_report_complete_cb(uint8_t itf, uint8_t const* report, uint8_t len);
+TU_ATTR_WEAK void tud_hid_report_complete_cb(uint8_t instance, uint8_t const* report, uint8_t len);
 
 
 //--------------------------------------------------------------------+
@@ -123,9 +128,14 @@ static inline bool tud_hid_ready(void)
   return tud_hid_n_ready(0);
 }
 
-static inline bool tud_hid_boot_mode(void)
+static inline uint8_t tud_hid_interface_protocol(void)
+{
+  return tud_hid_n_interface_protocol(0);
+}
+
+static inline bool tud_hid_get_protocol(void)
 {
-  return tud_hid_n_boot_mode(0);
+  return tud_hid_n_get_protocol(0);
 }
 
 static inline bool tud_hid_report(uint8_t report_id, void const* report, uint8_t len)
@@ -143,6 +153,11 @@ static inline bool tud_hid_mouse_report(uint8_t report_id, uint8_t buttons, int8
   return tud_hid_n_mouse_report(0, report_id, buttons, x, y, vertical, horizontal);
 }
 
+static inline bool  tud_hid_gamepad_report(uint8_t report_id, int8_t x, int8_t y, int8_t z, int8_t rz, int8_t rx, int8_t ry, uint8_t hat, uint16_t buttons)
+{
+  return tud_hid_n_gamepad_report(0, x, y, z, rz, rx, ry, hat, buttons);
+}
+
 /* --------------------------------------------------------------------+
  * HID Report Descriptor Template
  *
diff --git a/src/class/hid/hid_host.c b/src/class/hid/hid_host.c
index 64d1b8e5d..28440b1b4 100644
--- a/src/class/hid/hid_host.c
+++ b/src/class/hid/hid_host.c
@@ -178,7 +178,7 @@ bool hidh_open_subtask(uint8_t rhport, uint8_t dev_addr, tusb_desc_interface_t c
   if ( HID_SUBCLASS_BOOT == p_interface_desc->bInterfaceSubClass )
   {
     #if CFG_TUH_HID_KEYBOARD
-    if ( HID_PROTOCOL_KEYBOARD == p_interface_desc->bInterfaceProtocol)
+    if ( HID_ITF_PROTOCOL_KEYBOARD == p_interface_desc->bInterfaceProtocol)
     {
       TU_ASSERT( hidh_interface_open(rhport, dev_addr, p_interface_desc->bInterfaceNumber, p_endpoint_desc, &keyboardh_data[dev_addr-1]) );
       TU_LOG2_HEX(keyboardh_data[dev_addr-1].ep_in);
@@ -186,7 +186,7 @@ bool hidh_open_subtask(uint8_t rhport, uint8_t dev_addr, tusb_desc_interface_t c
     #endif
 
     #if CFG_TUH_HID_MOUSE
-    if ( HID_PROTOCOL_MOUSE == p_interface_desc->bInterfaceProtocol)
+    if ( HID_ITF_PROTOCOL_MOUSE == p_interface_desc->bInterfaceProtocol)
     {
       TU_ASSERT ( hidh_interface_open(rhport, dev_addr, p_interface_desc->bInterfaceNumber, p_endpoint_desc, &mouseh_data[dev_addr-1]) );
       TU_LOG2_HEX(mouseh_data[dev_addr-1].ep_in);