add synchronous (blocking) support for usbh control transfer

- add synchronous version of all get descriptor API
- update bare example to use sync API for string descriptor
- change order of index, language_id in tuh_descriptor_get_string() to
match similar API of libusb
- add index to tuh_descriptor_get_hid_report()

examples/host/bare_api/src/main.c

@@ -66,17 +66,9 @@ int main(void)
 #define LANGUAGE_ID 0x0409
 
 //uint8_t usb_buf[256] TU_ATTR_ALIGNED(4);
+TU_ATTR_ALIGNED(4)
 tusb_desc_device_t desc_device;
 
-static volatile xfer_result_t _get_string_result;
-
-static bool _transfer_done_cb(uint8_t daddr, tuh_control_xfer_t const *xfer, xfer_result_t result) {
-    (void)daddr;
-    (void)xfer;
-    _get_string_result = result;
-    return true;
-}
-
 static void _convert_utf16le_to_utf8(const uint16_t *utf16, size_t utf16_len, uint8_t *utf8, size_t utf8_len) {
     // TODO: Check for runover.
     (void)utf8_len;
@@ -116,14 +108,7 @@ static int _count_utf8_bytes(const uint16_t *buf, size_t len) {
     return total_bytes;
 }
 
-static void _wait_and_convert(uint16_t *temp_buf, size_t buf_len) {
-    while (_get_string_result == 0xff) {
-        tuh_task();
-    }
-    if (_get_string_result != XFER_RESULT_SUCCESS) {
-        temp_buf[0] = 0;
-        return;
-    }
+static void utf16_to_utf8(uint16_t *temp_buf, size_t buf_len) {
     size_t utf16_len = ((temp_buf[0] & 0xff) - 2) / sizeof(uint16_t);
     size_t utf8_len = _count_utf8_bytes(temp_buf + 1, utf16_len);
     _convert_utf16le_to_utf8(temp_buf + 1, utf16_len, (uint8_t *) temp_buf, sizeof(uint16_t) * buf_len);
@@ -153,31 +138,29 @@ bool print_device_descriptor(uint8_t daddr, tuh_control_xfer_t const * xfer, xfe
   printf("  idProduct           0x%04x\r\n" , desc_device.idProduct);
   printf("  bcdDevice           %04x\r\n"   , desc_device.bcdDevice);
 
-  _get_string_result = 0xff;
+  uint32_t timeout_ms = 10;
   uint16_t temp_buf[128];
 
   printf("  iManufacturer       %u     "     , desc_device.iManufacturer);
-  temp_buf[0] = 0;
-  if (tuh_descriptor_get_manufacturer_string(daddr, LANGUAGE_ID, temp_buf, TU_ARRAY_SIZE(temp_buf), _transfer_done_cb, 0)) {
-    _wait_and_convert(temp_buf, TU_ARRAY_SIZE(temp_buf));
+  if (XFER_RESULT_SUCCESS == tuh_descriptor_get_manufacturer_string_sync(daddr, LANGUAGE_ID, temp_buf, TU_ARRAY_SIZE(temp_buf), timeout_ms) )
+  {
+    utf16_to_utf8(temp_buf, TU_ARRAY_SIZE(temp_buf));
     printf((const char*) temp_buf);
   }
   printf("\r\n");
 
   printf("  iProduct            %u     "     , desc_device.iProduct);
-  _get_string_result = 0xff;
-  temp_buf[0] = 0;
-  if (tuh_descriptor_get_product_string(daddr, LANGUAGE_ID, temp_buf, TU_ARRAY_SIZE(temp_buf), _transfer_done_cb, 0)) {
-    _wait_and_convert(temp_buf, TU_ARRAY_SIZE(temp_buf));
+  if (XFER_RESULT_SUCCESS == tuh_descriptor_get_product_string_sync(daddr, LANGUAGE_ID, temp_buf, TU_ARRAY_SIZE(temp_buf), timeout_ms))
+  {
+    utf16_to_utf8(temp_buf, TU_ARRAY_SIZE(temp_buf));
     printf((const char*) temp_buf);
   }
   printf("\r\n");
 
   printf("  iSerialNumber       %u     "     , desc_device.iSerialNumber);
-  _get_string_result = 0xff;
-  temp_buf[0] = 0;
-  if (tuh_descriptor_get_serial_string(daddr, LANGUAGE_ID, temp_buf, TU_ARRAY_SIZE(temp_buf), _transfer_done_cb, 0)) {
-    _wait_and_convert(temp_buf, TU_ARRAY_SIZE(temp_buf));
+  if (XFER_RESULT_SUCCESS == tuh_descriptor_get_serial_string_sync(daddr, LANGUAGE_ID, temp_buf, TU_ARRAY_SIZE(temp_buf), timeout_ms))
+  {
+    utf16_to_utf8(temp_buf, TU_ARRAY_SIZE(temp_buf));
     printf((const char*) temp_buf);
   }
   printf("\r\n");
@@ -192,7 +175,7 @@ void tuh_mount_cb (uint8_t daddr)
 {
   printf("Device attached, address = %d\r\n", daddr);
 
-  // Get Device Descriptor
+  // Get Device Descriptor using asynchronous API
   tuh_descriptor_get_device(daddr, &desc_device, 18, print_device_descriptor, 0);
 }
 

src/class/hid/hid_host.c

@@ -437,7 +437,7 @@ static bool config_get_report_desc(uint8_t dev_addr, tuh_control_xfer_t const *
     config_driver_mount_complete(dev_addr, instance, NULL, 0);
   }else
   {
-    TU_ASSERT(tuh_descriptor_get_hid_report(dev_addr, itf_num, hid_itf->report_desc_type, usbh_get_enum_buf(), hid_itf->report_desc_len, config_get_report_desc_complete, 0));
+    TU_ASSERT(tuh_descriptor_get_hid_report(dev_addr, itf_num, hid_itf->report_desc_type, 0, usbh_get_enum_buf(), hid_itf->report_desc_len, config_get_report_desc_complete, 0));
   }
 
   return true;

src/common/tusb_types.h

@@ -228,6 +228,8 @@ typedef enum
   XFER_RESULT_SUCCESS,
   XFER_RESULT_FAILED,
   XFER_RESULT_STALLED,
+  XFER_RESULT_TIMEOUT,
+  XFER_RESULT_INVALID
 }xfer_result_t;
 
 enum // TODO remove

src/host/usbh.c

@@ -243,7 +243,7 @@ struct
 {
   tuh_control_xfer_t xfer;
   uint8_t daddr;  // device address that is transferring
-  uint8_t stage;
+  volatile uint8_t stage;
 }_ctrl_xfer;
 
 //------------- Helper Function -------------//
@@ -300,8 +300,8 @@ void osal_task_delay(uint32_t msec)
 // Descriptors
 //--------------------------------------------------------------------+
 
-bool tuh_descriptor_get(uint8_t daddr, uint8_t type, uint8_t index, void* buffer, uint16_t len,
-                        tuh_control_xfer_cb_t complete_cb, uintptr_t user_arg)
+static bool _get_descriptor(uint8_t daddr, uint8_t type, uint8_t index, uint16_t language_id, void* buffer, uint16_t len,
+                            tuh_control_xfer_cb_t complete_cb, uintptr_t user_arg)
 {
   tuh_control_xfer_t const xfer =
   {
@@ -315,7 +315,7 @@ bool tuh_descriptor_get(uint8_t daddr, uint8_t type, uint8_t index, void* buffer
       },
       .bRequest = TUSB_REQ_GET_DESCRIPTOR,
       .wValue   = tu_htole16( TU_U16(type, index) ),
-      .wIndex   = 0,
+      .wIndex   = tu_htole16(language_id),
       .wLength  = tu_htole16(len)
     },
 
@@ -327,6 +327,12 @@ bool tuh_descriptor_get(uint8_t daddr, uint8_t type, uint8_t index, void* buffer
   return tuh_control_xfer(daddr, &xfer);
 }
 
+bool tuh_descriptor_get(uint8_t daddr, uint8_t type, uint8_t index, void* buffer, uint16_t len,
+                        tuh_control_xfer_cb_t complete_cb, uintptr_t user_arg)
+{
+  return _get_descriptor(daddr, type, index, 0x0000, buffer, len, complete_cb, user_arg);
+}
+
 bool tuh_descriptor_get_device(uint8_t daddr, void* buffer, uint16_t len,
                                tuh_control_xfer_cb_t complete_cb, uintptr_t user_arg)
 {
@@ -340,31 +346,12 @@ bool tuh_descriptor_get_configuration(uint8_t daddr, uint8_t index, void* buffer
   return tuh_descriptor_get(daddr, TUSB_DESC_CONFIGURATION, index, buffer, len, complete_cb, user_arg);
 }
 
-bool tuh_descriptor_get_string(uint8_t daddr, uint16_t language_id, uint8_t index, void* buffer, uint16_t len,
+//------------- String Descriptor -------------//
+
+bool tuh_descriptor_get_string(uint8_t daddr, uint8_t index, uint16_t language_id, void* buffer, uint16_t len,
                                tuh_control_xfer_cb_t complete_cb, uintptr_t user_arg)
 {
-  tuh_control_xfer_t const xfer =
-  {
-    .request =
-    {
-      .bmRequestType_bit =
-      {
-        .recipient = TUSB_REQ_RCPT_DEVICE,
-        .type      = TUSB_REQ_TYPE_STANDARD,
-        .direction = TUSB_DIR_IN
-      },
-      .bRequest = TUSB_REQ_GET_DESCRIPTOR,
-      .wValue   = tu_htole16( TU_U16(TUSB_DESC_STRING, index) ),
-      .wIndex   = tu_htole16(language_id),
-      .wLength  = tu_htole16(len)
-    },
-
-    .buffer      = buffer,
-    .complete_cb = complete_cb,
-    .user_arg    = user_arg
-  };
-
-  return tuh_control_xfer(daddr, &xfer);
+  return _get_descriptor(daddr, TUSB_DESC_STRING, index, language_id, buffer, len, complete_cb, user_arg);
 }
 
 // Get manufacturer string descriptor
@@ -376,7 +363,7 @@ bool tuh_descriptor_get_manufacturer_string(uint8_t daddr, uint16_t language_id,
   if (dev->i_manufacturer == 0) {
     return false;
   }
-  return tuh_descriptor_get_string(daddr, language_id, dev->i_manufacturer, buffer, len, complete_cb, user_arg);
+  return tuh_descriptor_get_string(daddr, dev->i_manufacturer, language_id, buffer, len, complete_cb, user_arg);
 }
 
 // Get product string descriptor
@@ -388,7 +375,7 @@ bool tuh_descriptor_get_product_string(uint8_t daddr, uint16_t language_id, void
   if (dev->i_product == 0) {
     return false;
   }
-  return tuh_descriptor_get_string(daddr, language_id, dev->i_product, buffer, len, complete_cb, user_arg);
+  return tuh_descriptor_get_string(daddr, dev->i_product, language_id, buffer, len, complete_cb, user_arg);
 }
 
 // Get serial string descriptor
@@ -400,11 +387,11 @@ bool tuh_descriptor_get_serial_string(uint8_t daddr, uint16_t language_id, void*
   if (dev->i_serial == 0) {
     return false;
   }
-  return tuh_descriptor_get_string(daddr, language_id, dev->i_serial, buffer, len, complete_cb, user_arg);
+  return tuh_descriptor_get_string(daddr, dev->i_serial, language_id, buffer, len, complete_cb, user_arg);
 }
 
 // Get HID report descriptor
-bool tuh_descriptor_get_hid_report(uint8_t daddr, uint8_t itf_num, uint8_t desc_type, void* buffer, uint16_t len,
+bool tuh_descriptor_get_hid_report(uint8_t daddr, uint8_t itf_num, uint8_t desc_type, uint8_t index, void* buffer, uint16_t len,
                                    tuh_control_xfer_cb_t complete_cb, uintptr_t user_arg)
 {
   TU_LOG2("HID Get Report Descriptor\r\n");
@@ -419,8 +406,8 @@ bool tuh_descriptor_get_hid_report(uint8_t daddr, uint8_t itf_num, uint8_t desc_
         .direction = TUSB_DIR_IN
       },
       .bRequest = TUSB_REQ_GET_DESCRIPTOR,
-      .wValue   = tu_htole16(TU_U16(desc_type, 0)),
-      .wIndex   = itf_num,
+      .wValue   = tu_htole16(TU_U16(desc_type, index)),
+      .wIndex   = tu_htole16((uint16_t) itf_num),
       .wLength  = len
     },
 
@@ -461,6 +448,58 @@ bool tuh_configuration_set(uint8_t daddr, uint8_t config_num,
   return tuh_control_xfer(daddr, &xfer);
 }
 
+//--------------------------------------------------------------------+
+// Asynchronous
+//--------------------------------------------------------------------+
+
+#define _CONTROL_SYNC_API(_async_func, _timeout, ...) \
+  (void) _timeout; \
+  xfer_result_t result = XFER_RESULT_INVALID;\
+  /* TODO use timeout to wait */ \
+  TU_VERIFY(_async_func(__VA_ARGS__, NULL, (uintptr_t) &result), XFER_RESULT_TIMEOUT); \
+  return (uint8_t) result
+
+uint8_t tuh_descriptor_get_sync(uint8_t daddr, uint8_t type, uint8_t index, void* buffer, uint16_t len, uint8_t timeout_ms)
+{
+  _CONTROL_SYNC_API(tuh_descriptor_get, timeout_ms, daddr, type, index, buffer, len);
+}
+
+uint8_t tuh_descriptor_get_device_sync(uint8_t daddr, void* buffer, uint16_t len, uint8_t timeout_ms)
+{
+  len = tu_min16(len, sizeof(tusb_desc_device_t));
+  return tuh_descriptor_get_sync(daddr, TUSB_DESC_DEVICE, 0, buffer, len, timeout_ms);
+}
+
+uint8_t tuh_descriptor_get_configuration_sync(uint8_t daddr, uint8_t index, void* buffer, uint16_t len, uint8_t timeout_ms)
+{
+  return tuh_descriptor_get_sync(daddr, TUSB_DESC_CONFIGURATION, index, buffer, len, timeout_ms);
+}
+
+uint8_t tuh_descriptor_get_hid_report_sync(uint8_t daddr, uint8_t itf_num, uint8_t desc_type, uint8_t index, void* buffer, uint16_t len, uint8_t timeout_ms)
+{
+  _CONTROL_SYNC_API(tuh_descriptor_get_hid_report, timeout_ms, daddr, itf_num, desc_type, index, buffer, len);
+}
+
+uint8_t tuh_descriptor_get_string_sync(uint8_t daddr, uint8_t index, uint16_t language_id, void* buffer, uint16_t len, uint8_t timeout_ms)
+{
+  _CONTROL_SYNC_API(tuh_descriptor_get_string, timeout_ms, daddr, index, language_id, buffer, len);
+}
+
+uint8_t tuh_descriptor_get_manufacturer_string_sync(uint8_t daddr, uint16_t language_id, void* buffer, uint16_t len, uint8_t timeout_ms)
+{
+  _CONTROL_SYNC_API(tuh_descriptor_get_manufacturer_string, timeout_ms, daddr, language_id, buffer, len);
+}
+
+uint8_t tuh_descriptor_get_product_string_sync(uint8_t daddr, uint16_t language_id, void* buffer, uint16_t len, uint8_t timeout_ms)
+{
+  _CONTROL_SYNC_API(tuh_descriptor_get_product_string, timeout_ms, daddr, language_id, buffer, len);
+}
+
+uint8_t tuh_descriptor_get_serial_string_sync(uint8_t daddr, uint16_t language_id, void* buffer, uint16_t len, uint8_t timeout_ms)
+{
+  _CONTROL_SYNC_API(tuh_descriptor_get_serial_string, timeout_ms, daddr, language_id, buffer, len);
+}
+
 //--------------------------------------------------------------------+
 // CLASS-USBD API (don't require to verify parameters)
 //--------------------------------------------------------------------+
@@ -833,11 +872,22 @@ bool usbh_edpt_busy(uint8_t dev_addr, uint8_t ep_addr)
 // Control transfer
 //--------------------------------------------------------------------+
 
+static bool _control_blocking_complete_cb(uint8_t daddr, tuh_control_xfer_t const * xfer, xfer_result_t result)
+{
+  (void) daddr;
+
+  // update result
+  *((xfer_result_t*) xfer->user_arg) = result;
+
+  return true;
+}
+
 bool tuh_control_xfer (uint8_t daddr, tuh_control_xfer_t const* xfer)
 {
   // pre-check to help reducing mutex lock
   TU_VERIFY(_ctrl_xfer.stage == CONTROL_STAGE_IDLE);
 
+  // TODO probably better to use semaphore as resource management than mutex
   usbh_lock();
 
   bool const is_idle = (_ctrl_xfer.stage == CONTROL_STAGE_IDLE);
@@ -855,7 +905,52 @@ bool tuh_control_xfer (uint8_t daddr, tuh_control_xfer_t const* xfer)
 
   _ctrl_xfer.daddr = daddr;
   _ctrl_xfer.xfer = (*xfer);
-  return hcd_setup_send(rhport, daddr, (uint8_t*) &_ctrl_xfer.xfer.request);
+
+  if (xfer->complete_cb)
+  {
+    TU_ASSERT( hcd_setup_send(rhport, daddr, (uint8_t*) &_ctrl_xfer.xfer.request) );
+  }else
+  {
+    // user_arg must point to xfer_result_t to hold result
+    TU_VERIFY(xfer->user_arg);
+
+    // blocking if complete callback is not provided
+    // change callback to internal blocking, and result as user argument
+    volatile xfer_result_t* result = (volatile xfer_result_t*) xfer->user_arg;
+
+    _ctrl_xfer.xfer.complete_cb = _control_blocking_complete_cb;
+    *result = XFER_RESULT_INVALID;
+
+    TU_ASSERT( hcd_setup_send(rhport, daddr, (uint8_t*) &_ctrl_xfer.xfer.request) );
+
+    while ((*result) == XFER_RESULT_INVALID)
+    {
+      // only need to call task if not preempted RTOS
+      #if CFG_TUSB_OS == OPT_OS_NONE || CFG_TUSB_OS == OPT_OS_PICO
+      tuh_task();
+      #endif
+
+      // TODO probably some timeout to prevent hanged
+    }
+  }
+
+  return true;
+}
+
+uint8_t tuh_control_xfer_sync(uint8_t daddr, tuh_control_xfer_t const* xfer, uint32_t timeout_ms)
+{
+  (void) timeout_ms;
+
+  xfer_result_t result = XFER_RESULT_INVALID;
+  tuh_control_xfer_t xfer_sync = (*xfer);
+
+  xfer_sync.complete_cb = NULL;
+  xfer_sync.user_arg = (uintptr_t) &result;
+
+  // TODO use timeout to wait
+  TU_VERIFY(tuh_control_xfer(daddr, &xfer_sync), XFER_RESULT_TIMEOUT);
+
+  return result;
 }
 
 TU_ATTR_ALWAYS_INLINE static inline void set_control_xfer_stage(uint8_t stage)
@@ -869,15 +964,16 @@ static void _xfer_complete(uint8_t dev_addr, xfer_result_t result)
 {
   TU_LOG2("\r\n");
 
+  // duplicate xfer since user can execute control transfer within callback
+  tuh_control_xfer_t const xfer_temp = _ctrl_xfer.xfer;
+
   usbh_lock();
   _ctrl_xfer.stage = CONTROL_STAGE_IDLE;
   usbh_unlock();
 
-  if (_ctrl_xfer.xfer.complete_cb)
+  if (xfer_temp.complete_cb)
   {
-    // duplicate xfer since user can execute control transfer within callback
-    tuh_control_xfer_t const xfer_temp = _ctrl_xfer.xfer;
-    _ctrl_xfer.xfer.complete_cb(dev_addr, &xfer_temp, result);
+    xfer_temp.complete_cb(dev_addr, &xfer_temp, result);
   }
 }
 

src/host/usbh.h

@@ -52,6 +52,18 @@ struct tuh_control_xfer_s
   uintptr_t user_arg;
 };
 
+//--------------------------------------------------------------------+
+// APPLICATION CALLBACK
+//--------------------------------------------------------------------+
+
+//TU_ATTR_WEAK uint8_t tuh_attach_cb (tusb_desc_device_t const *desc_device);
+
+// Invoked when device is mounted (configured)
+TU_ATTR_WEAK void tuh_mount_cb (uint8_t daddr);
+
+/// Invoked when device is unmounted (bus reset/unplugged)
+TU_ATTR_WEAK void tuh_umount_cb(uint8_t daddr);
+
 //--------------------------------------------------------------------+
 // APPLICATION API
 //--------------------------------------------------------------------+
@@ -93,65 +105,101 @@ static inline bool tuh_ready(uint8_t daddr)
 }
 
 // Carry out a control transfer
-// true on success, false if there is on-going control transfer
-// Note: function is blocking if complete callback is NULL
+// true on success, false if there is on-going control transfer or incorrect parameters
+// Blocking if complete callback is NULL, in this case 'user_arg' must contain xfer_result_t variable
 bool tuh_control_xfer (uint8_t daddr, tuh_control_xfer_t const* xfer);
 
-// Carry out a control transfer
-// true on success, false if there is on-going control transfer
-// Note: function is blocking if complete callback is NULL
-//bool tuh_control_xfer (uint8_t daddr, tusb_control_request_t const* request, void* buffer,
-//                       tuh_control_xfer_cb_t complete_cb, uintptr_t user_arg);
+// Sync (blocking) version of tuh_control_xfer()
+// return transfer result
+uint8_t tuh_control_xfer_sync(uint8_t daddr, tuh_control_xfer_t const* xfer, uint32_t timeout_ms);
 
-// Set Configuration
+// Set Configuration (control transfer)
 // config_num = 0 will un-configure device. Note: config_num = config_descriptor_index + 1
+// true on success, false if there is on-going control transfer or incorrect parameters
+// Blocking if complete callback is NULL, in this case 'user_arg' must contain xfer_result_t variable
 bool tuh_configuration_set(uint8_t daddr, uint8_t config_num,
                            tuh_control_xfer_cb_t complete_cb, uintptr_t user_arg);
 
-//------------- descriptors -------------//
+//--------------------------------------------------------------------+
+// Descriptors Asynchronous (non-blocking)
+//--------------------------------------------------------------------+
 
-// Get an descriptor
+// Get an descriptor (control transfer)
+// true on success, false if there is on-going control transfer or incorrect parameters
 bool tuh_descriptor_get(uint8_t daddr, uint8_t type, uint8_t index, void* buffer, uint16_t len,
                         tuh_control_xfer_cb_t complete_cb, uintptr_t user_arg);
 
-// Get device descriptor
+// Get device descriptor (control transfer)
+// true on success, false if there is on-going control transfer or incorrect parameters
 bool tuh_descriptor_get_device(uint8_t daddr, void* buffer, uint16_t len,
                                tuh_control_xfer_cb_t complete_cb, uintptr_t user_arg);
 
-// Get configuration descriptor
+// Get configuration descriptor (control transfer)
+// true on success, false if there is on-going control transfer or incorrect parameters
 bool tuh_descriptor_get_configuration(uint8_t daddr, uint8_t index, void* buffer, uint16_t len,
                                       tuh_control_xfer_cb_t complete_cb, uintptr_t user_arg);
 
-// Get HID report descriptor
-bool tuh_descriptor_get_hid_report(uint8_t daddr, uint8_t itf_num, uint8_t desc_type, void* buffer, uint16_t len,
+// Get HID report descriptor (control transfer)
+// true on success, false if there is on-going control transfer or incorrect parameters
+bool tuh_descriptor_get_hid_report(uint8_t daddr, uint8_t itf_num, uint8_t desc_type, uint8_t index, void* buffer, uint16_t len,
                                    tuh_control_xfer_cb_t complete_cb, uintptr_t user_arg);
 
-// Get string descriptor
-bool tuh_descriptor_get_string(uint8_t daddr, uint16_t language_id, uint8_t index, void* buffer, uint16_t len,
+// Get string descriptor (control transfer)
+// true on success, false if there is on-going control transfer or incorrect parameters
+// Blocking if complete callback is NULL, in this case 'user_arg' must contain xfer_result_t variable
+bool tuh_descriptor_get_string(uint8_t daddr, uint8_t index, uint16_t language_id, void* buffer, uint16_t len,
                                tuh_control_xfer_cb_t complete_cb, uintptr_t user_arg);
 
-// Get manufacturer string descriptor
+// Get manufacturer string descriptor (control transfer)
+// true on success, false if there is on-going control transfer or incorrect parameters
 bool tuh_descriptor_get_manufacturer_string(uint8_t daddr, uint16_t language_id, void* buffer, uint16_t len,
                                             tuh_control_xfer_cb_t complete_cb, uintptr_t user_arg);
 
-// Get product string descriptor
+// Get product string descriptor (control transfer)
+// true on success, false if there is on-going control transfer or incorrect parameters
 bool tuh_descriptor_get_product_string(uint8_t daddr, uint16_t language_id, void* buffer, uint16_t len,
                                        tuh_control_xfer_cb_t complete_cb, uintptr_t user_arg);
 
-// Get serial string descriptor
+// Get serial string descriptor (control transfer)
+// true on success, false if there is on-going control transfer or incorrect parameters
 bool tuh_descriptor_get_serial_string(uint8_t daddr, uint16_t language_id, void* buffer, uint16_t len,
                                       tuh_control_xfer_cb_t complete_cb, uintptr_t user_arg);
 
 //--------------------------------------------------------------------+
-// APPLICATION CALLBACK
+// Descriptors Synchronous (blocking)
 //--------------------------------------------------------------------+
-//TU_ATTR_WEAK uint8_t tuh_attach_cb (tusb_desc_device_t const *desc_device);
 
-// Invoked when device is mounted (configured)
-TU_ATTR_WEAK void tuh_mount_cb (uint8_t daddr);
+// Sync (blocking) version of tuh_descriptor_get()
+// return transfer result
+uint8_t tuh_descriptor_get_sync(uint8_t daddr, uint8_t type, uint8_t index, void* buffer, uint16_t len, uint8_t timeout_ms);
 
-/// Invoked when device is unmounted (bus reset/unplugged)
-TU_ATTR_WEAK void tuh_umount_cb(uint8_t daddr);
+// Sync (blocking) version of tuh_descriptor_get_device()
+// return transfer result
+uint8_t tuh_descriptor_get_device_sync(uint8_t daddr, void* buffer, uint16_t len, uint8_t timeout_ms);
+
+// Sync (blocking) version of tuh_descriptor_get_configuration()
+// return transfer result
+uint8_t tuh_descriptor_get_configuration_sync(uint8_t daddr, uint8_t index, void* buffer, uint16_t len, uint8_t timeout_ms);
+
+// Sync (blocking) version of tuh_descriptor_get_hid_report()
+// return transfer result
+uint8_t tuh_descriptor_get_hid_report_sync(uint8_t daddr, uint8_t itf_num, uint8_t desc_type, uint8_t index, void* buffer, uint16_t len, uint8_t timeout_ms);
+
+// Sync (blocking) version of tuh_descriptor_get_string()
+// return transfer result
+uint8_t tuh_descriptor_get_string_sync(uint8_t daddr, uint8_t index, uint16_t language_id, void* buffer, uint16_t len, uint8_t timeout_ms);
+
+// Sync (blocking) version of tuh_descriptor_get_manufacturer_string()
+// return transfer result
+uint8_t tuh_descriptor_get_manufacturer_string_sync(uint8_t daddr, uint16_t language_id, void* buffer, uint16_t len, uint8_t timeout_ms);
+
+// Sync (blocking) version of tuh_descriptor_get_product_string()
+// return transfer result
+uint8_t tuh_descriptor_get_product_string_sync(uint8_t daddr, uint16_t language_id, void* buffer, uint16_t len, uint8_t timeout_ms);
+
+// Sync (blocking) version of tuh_descriptor_get_serial_string()
+// return transfer result
+uint8_t tuh_descriptor_get_serial_string_sync(uint8_t daddr, uint16_t language_id, void* buffer, uint16_t len, uint8_t timeout_ms);
 
 #ifdef __cplusplus
  }

src/tusb_option.h

@@ -285,7 +285,7 @@
   #define CFG_TUSB_OS_INC_PATH
 #endif
 
-// mutex is only needed for RTOS
+// mutex is only needed for RTOS TODO also required with multiple core MCUs
 #define TUSB_OPT_MUTEX    (CFG_TUSB_OS != OPT_OS_NONE)
 
 //--------------------------------------------------------------------