set errno for USBError & USBTimeoutError

This sets unique errno values for each place in the usb.core.Device
implementation that raises USBError or USBTimeoutError. The idea is
to provide more visibility so CircuitPython code can understand
what's gone wrong when TinyUSB complains about something.

CAUTION: This removes two error strings (stalled pipe and config
not set).

The new way relies on unique error codes as defined in
shared-module/usb/core/Device.h. The "errno" values here are
arbitrary with no relation to POSIX errno codes. I don't see this
as a problem because the so-called errno codes returned by desktop
PyUSB are undocumented and appear to be rather aribitrary.

Author: samblenny

shared-bindings/usb/core/__init__.c

@@ -30,17 +30,9 @@
 //|
 //|
 MP_DEFINE_USB_CORE_EXCEPTION(USBError, OSError)
-NORETURN void mp_raise_usb_core_USBError(mp_rom_error_text_t fmt, ...) {
-    mp_obj_t exception;
-    if (fmt == NULL) {
-        exception = mp_obj_new_exception(&mp_type_usb_core_USBError);
-    } else {
-        va_list argptr;
-        va_start(argptr, fmt);
-        exception = mp_obj_new_exception_msg_vlist(&mp_type_usb_core_USBError, fmt, argptr);
-        va_end(argptr);
-    }
-    nlr_raise(exception);
+NORETURN MP_COLD void mp_raise_usb_core_USBError(int errno) {
+    mp_obj_t args[1] = {MP_OBJ_NEW_SMALL_INT(errno)};
+    nlr_raise(mp_obj_new_exception_args(&mp_type_usb_core_USBError, 1, args));
 }
 
 //| class USBTimeoutError(USBError):
@@ -50,8 +42,9 @@ NORETURN void mp_raise_usb_core_USBError(mp_rom_error_text_t fmt, ...) {
 //|
 //|
 MP_DEFINE_USB_CORE_EXCEPTION(USBTimeoutError, usb_core_USBError)
-NORETURN void mp_raise_usb_core_USBTimeoutError(void) {
-    mp_raise_type(&mp_type_usb_core_USBTimeoutError);
+NORETURN void mp_raise_usb_core_USBTimeoutError(int errno) {
+    mp_obj_t args[1] = {MP_OBJ_NEW_SMALL_INT(errno)};
+    nlr_raise(mp_obj_new_exception_args(&mp_type_usb_core_USBTimeoutError, 1, args));
 }
 
 

shared-bindings/usb/core/__init__.h

@@ -25,8 +25,8 @@ void usb_core_exception_print(const mp_print_t *print, mp_obj_t o_in, mp_print_k
 extern const mp_obj_type_t mp_type_usb_core_USBError;
 extern const mp_obj_type_t mp_type_usb_core_USBTimeoutError;
 
-NORETURN void mp_raise_usb_core_USBError(mp_rom_error_text_t fmt, ...);
-NORETURN void mp_raise_usb_core_USBTimeoutError(void);
+NORETURN void mp_raise_usb_core_USBError(int errno);
+NORETURN void mp_raise_usb_core_USBTimeoutError(int errno);
 
 // Find is all Python object oriented so we don't need a separate common-hal API
 // for it. It uses the device common-hal instead.

shared-module/usb/core/Device.c

@@ -1,6 +1,7 @@
 // This file is part of the CircuitPython project: https://circuitpython.org
 //
 // SPDX-FileCopyrightText: Copyright (c) 2022 Scott Shawcroft for Adafruit Industries
+// SPDX-FileCopyrightText: Copyright (c) 2025 Sam Blenny
 //
 // SPDX-License-Identifier: MIT
 
@@ -111,7 +112,7 @@ static void _prepare_for_transfer(void) {
 
 static size_t _handle_timed_transfer_callback(tuh_xfer_t *xfer, mp_int_t timeout) {
     if (xfer == NULL) {
-        mp_raise_usb_core_USBError(NULL);
+        mp_raise_usb_core_USBError(USB_CORE_NULL_PTR);
         return 0;
     }
     uint32_t start_time = supervisor_ticks_ms32();
@@ -134,21 +135,21 @@ static size_t _handle_timed_transfer_callback(tuh_xfer_t *xfer, mp_int_t timeout
         case XFER_RESULT_SUCCESS:
             return _actual_len;
         case XFER_RESULT_FAILED:
-            mp_raise_usb_core_USBError(NULL);
+            mp_raise_usb_core_USBError(USB_CORE_XFER_FAIL);
             break;
         case XFER_RESULT_STALLED:
-            mp_raise_usb_core_USBError(MP_ERROR_TEXT("Pipe error"));
+            mp_raise_usb_core_USBError(USB_CORE_STALLED);
             break;
         case XFER_RESULT_TIMEOUT:
             // This timeout comes from TinyUSB, so assume that it has stopped the
             // transfer (note: timeout logic may be unimplemented on TinyUSB side)
-            mp_raise_usb_core_USBTimeoutError();
+            mp_raise_usb_core_USBTimeoutError(USB_CORE_TIMEOUT);
             break;
         case XFER_RESULT_INVALID:
             // This timeout comes from CircuitPython, not TinyUSB, so tell TinyUSB
             // to stop the transfer
             tuh_edpt_abort_xfer(xfer->daddr, xfer->ep_addr);
-            mp_raise_usb_core_USBTimeoutError();
+            mp_raise_usb_core_USBTimeoutError(USB_CORE_INVALID);
             break;
     }
     return 0;
@@ -281,7 +282,7 @@ static size_t _xfer(tuh_xfer_t *xfer, mp_int_t timeout) {
     _prepare_for_transfer();
     xfer->complete_cb = _transfer_done_cb;
     if (!tuh_edpt_xfer(xfer)) {
-        mp_raise_usb_core_USBError(NULL);
+        mp_raise_usb_core_USBError(USB_CORE_EDPT_XFER);
         return 0;
     }
     return _handle_timed_transfer_callback(xfer, timeout);
@@ -303,7 +304,7 @@ static bool _open_endpoint(usb_core_device_obj_t *self, mp_int_t endpoint) {
     }
 
     if (self->configuration_descriptor == NULL) {
-        mp_raise_usb_core_USBError(MP_ERROR_TEXT("No configuration set"));
+        mp_raise_usb_core_USBError(USB_CORE_NOCONFIG);
         return false;
     }
 
@@ -338,7 +339,7 @@ static bool _open_endpoint(usb_core_device_obj_t *self, mp_int_t endpoint) {
 
 mp_int_t common_hal_usb_core_device_write(usb_core_device_obj_t *self, mp_int_t endpoint, const uint8_t *buffer, mp_int_t len, mp_int_t timeout) {
     if (!_open_endpoint(self, endpoint)) {
-        mp_raise_usb_core_USBError(NULL);
+        mp_raise_usb_core_USBError(USB_CORE_OPEN_ENDPOINT);
         return 0;
     }
     tuh_xfer_t xfer;
@@ -351,7 +352,7 @@ mp_int_t common_hal_usb_core_device_write(usb_core_device_obj_t *self, mp_int_t
 
 mp_int_t common_hal_usb_core_device_read(usb_core_device_obj_t *self, mp_int_t endpoint, uint8_t *buffer, mp_int_t len, mp_int_t timeout) {
     if (!_open_endpoint(self, endpoint)) {
-        mp_raise_usb_core_USBError(NULL);
+        mp_raise_usb_core_USBError(USB_CORE_OPEN_ENDPOINT);
         return 0;
     }
     tuh_xfer_t xfer;
@@ -385,7 +386,7 @@ mp_int_t common_hal_usb_core_device_ctrl_transfer(usb_core_device_obj_t *self,
 
     _prepare_for_transfer();
     if (!tuh_control_xfer(&xfer)) {
-        mp_raise_usb_core_USBError(NULL);
+        mp_raise_usb_core_USBError(USB_CORE_CONTROL_XFER);
         return 0;
     }
     return (mp_int_t)_handle_timed_transfer_callback(&xfer, timeout);

shared-module/usb/core/Device.h

@@ -1,6 +1,7 @@
 // This file is part of the CircuitPython project: https://circuitpython.org
 //
 // SPDX-FileCopyrightText: Copyright (c) 2022 Scott Shawcroft for Adafruit Industries
+// SPDX-FileCopyrightText: Copyright (c) 2025 Sam Blenny
 //
 // SPDX-License-Identifier: MIT
 
@@ -16,3 +17,29 @@ typedef struct {
     uint8_t open_endpoints[8];
     uint16_t first_langid;
 } usb_core_device_obj_t;
+
+
+// These values get used to set USBError.errno and USBTimeoutError.errno.
+// It would be possible to define these to more closely mimic desktop PyUSB on
+// a given OS (maybe Debian?). But, for USB error handling in CircuitPython,
+// there's an argument to be made that it's more useful to set arbitrary codes
+// here that map directly to errors coming from TinyUSB. That way, CircuitPython
+// code can have more visibility into what went wrong. POSIX errno codes are
+// pretty far removed from the details of how TinyUSB can fail, so using them
+// here would be uninformative.
+
+// Error due to attempting to open endpoint before setting configuration
+#define USB_CORE_NOCONFIG (1)
+
+// Errors from transfer callback result
+#define USB_CORE_NULL_PTR  (2)
+#define USB_CORE_XFER_FAIL (3)
+#define USB_CORE_STALLED   (4)
+#define USB_CORE_TIMEOUT   (5)
+#define USB_CORE_INVALID   (6)
+
+// Errors from a non-callback TinyUSB function returning false. Seeing one of
+// these probably means a TU_VERIFY(...) check failed in the TinyUSB code.
+#define USB_CORE_EDPT_XFER     (7)
+#define USB_CORE_OPEN_ENDPOINT (8)
+#define USB_CORE_CONTROL_XFER  (9)