extmod/machine_usb_device: Document xfer_cb result value, add enums.

projectgus · dpgeorge · commit eeed037f70ab · 2026-04-15T15:57:04.000+10:00
This callback argument was previously mis-labelled as a boolean,
but it's actually the tusb_xfer_result_t values from TinyUSB.

This work was funded through GitHub Sponsors.

Signed-off-by: Angus Gratton &lt;angus@redyak.com.au&gt;
diff --git a/docs/library/machine.USBDevice.rst b/docs/library/machine.USBDevice.rst
@@ -155,10 +155,11 @@ Methods
       The callback has three arguments:
 
       1. The Endpoint number for the completed transfer.
-      2. Result value: ``True`` if the transfer succeeded, ``False``
-         otherwise.
-      3. Number of bytes successfully transferred. In the case of a
-         "short" transfer, The result is ``True`` and ``xferred_bytes``
+      2. Result value. This is an integer which is ``0`` (`XFER_SUCCESS`) on
+         success, or one of the non-zero values `XFER_FAILED` or `XFER_STALLED`
+         if the transfer failed.
+      3. Number of bytes successfully transferred. In the case of a "short"
+         transfer, the result is ``0`` (`XFER_SUCCESS`) and ``xferred_bytes``
          will be smaller than the length of the buffer submitted for the
          transfer.
 
@@ -301,4 +302,20 @@ Constants
           - ``desc_cfg`` - ``bytes`` object containing the complete built-in USB
             configuration descriptor.
 
+.. data:: USBDevice.XFER_SUCCESS
+.. data:: USBDevice.XFER_FAILED
+.. data:: USBDevice.XFER_STALLED
+
+          These are integer constants that represent the possible transfer
+          result values passed to the ``xfer_cb`` callback (see
+          `USBDevice.config`).
+
+          - ``XFER_SUCCESS`` has value ``0`` and indicates the transfer was
+            successful.
+          - ``XFER_FAILED`` indicates the transfer failed due to low-level
+            integrity errors.
+          - ``XFER_STALLED`` indicates that the host has stalled this endpoint.
+
+          All failure values are non-zero integers.
+
 .. _usb driver modules in micropython-lib: https://github.com/micropython/micropython-lib/tree/master/micropython/usb#readme
diff --git a/extmod/machine_usb_device.c b/extmod/machine_usb_device.c
@@ -302,6 +302,16 @@ static const mp_rom_map_elem_t usb_device_locals_dict_table[] = {
     { MP_ROM_QSTR(MP_QSTR_BUILTIN_CDC_MSC), MP_ROM_PTR(&mp_type_usb_device_builtin_default) },
     #endif
     #endif // !HAS_BUILTIN_DRIVERS
+
+    // xfer_cb result values
+    // These are a subset of tusb_xfer_result_t
+    { MP_ROM_QSTR(MP_QSTR_XFER_SUCCESS), MP_OBJ_NEW_SMALL_INT(XFER_RESULT_SUCCESS) },
+    { MP_ROM_QSTR(MP_QSTR_XFER_FAILED), MP_OBJ_NEW_SMALL_INT(XFER_RESULT_FAILED) },
+    { MP_ROM_QSTR(MP_QSTR_XFER_STALLED), MP_OBJ_NEW_SMALL_INT(XFER_RESULT_STALLED) },
+    // Some values of tusb_xfer_result_t are not exposed here:
+    // - XFER_RESULT_TIMEOUT only appears if you call the "sync" API subset, or in one
+    //   case from the samd host controller.
+    // - XFER_RESULT_INVALID only appears in the host controller APIs
 };
 static MP_DEFINE_CONST_DICT(usb_device_locals_dict, usb_device_locals_dict_table);
 
