usbd: Refactor USBInterface

- Allows >1 USB interface to live in a single USBInterface object
  (which is confusing naming, but makes cases like MIDI much simpler.)

- Also refactors the string implementation to do less allocations,
  string descriptors are now stored in a 'strs' list of each USBInterface
  instead of holding a single _strs variable in the USBDevice object.

Author: projectgus

micropython/usbd/__init__.py

@@ -1,5 +1,5 @@
 from .device import get_usbdevice, USBInterface
 from .hid import HIDInterface, MouseInterface
-from .midi import DummyAudioInterface, MIDIInterface, MidiUSB
+from .midi import MIDIInterface, MIDIUSB
 from .cdc import CDC
 from . import utils

micropython/usbd/cdc.py

@@ -11,7 +11,6 @@
 from .device import USBInterface, get_usbdevice
 from .utils import (
     Buffer,
-    endpoint_descriptor,
     split_bmRequestType,
     STAGE_SETUP,
     STAGE_DATA,
@@ -23,7 +22,6 @@
 
 _DEV_CLASS_MISC = const(0xEF)
 _CS_DESC_TYPE = const(0x24)  # CS Interface type communication descriptor
-_ITF_ASSOCIATION_DESC_TYPE = const(0xB)  # Interface Association descriptor
 
 # CDC control interface definitions
 _INTERFACE_CLASS_CDC = const(2)
@@ -62,6 +60,7 @@
 # Other definitions
 _CDC_VERSION = const(0x0120)  # release number in binary-coded decimal
 
+# Number of endpoints in each interface
 _CDC_CONTROL_EP_NUM = const(1)
 _CDC_DATA_EP_NUM = const(2)
 
@@ -93,7 +92,8 @@ class CDC(io.IOBase):
     # with some additional methods.
     #
     # This is a standalone class, instead of a USBInterface subclass, because
-    # CDC consists of multiple interfaces (CDC control and CDC data)
+    # CDC consists of multiple interfaces (CDC control and CDC data) and also
+    # so it can derive from io.IOBase.
     def __init__(self, **kwargs):
         # For CDC to work, the device class must be set to Interface Association
         usb_device = get_usbdevice()
@@ -218,9 +218,7 @@ class CDCControlInterface(USBInterface):
     # Implements the CDC Control Interface
 
     def __init__(self):
-        super().__init__(
-            _INTERFACE_CLASS_CDC, _INTERFACE_SUBCLASS_CDC, _PROTOCOL_NONE, _CDC_CONTROL_EP_NUM
-        )
+        super().__init__()
 
         # Callbacks for particular changes initiated by the host
         self.break_cb = None  # Host sent a "break" condition
@@ -233,23 +231,12 @@ def __init__(self):
 
         self.ep_in = None  # Set when enumeration happens
 
-    def descriptor_config_cb(self, desc, itf_num, str_num, ep_num):
-        # CDC needs a Interface Association Descriptor (IAD)
-        # two interfaces in total
-        desc.pack(
-            "<BBBBBBBB",
-            8,
-            _ITF_ASSOCIATION_DESC_TYPE,
-            itf_num,
-            2,
-            _INTERFACE_CLASS_CDC,
-            _INTERFACE_SUBCLASS_CDC,
-            _PROTOCOL_NONE,
-            0,
-        )
+    def descriptor_config_cb(self, desc, itf_num, ep_num):
+        # CDC needs a Interface Association Descriptor (IAD) connecting the Control & Data interfaces
+        desc.interface_assoc(itf_num, 2, _INTERFACE_CLASS_CDC, _INTERFACE_SUBCLASS_CDC)
 
-        # Now add the standard interface descriptor
-        strs = super().descriptor_config_cb(desc, itf_num, str_num, ep_num)
+        # Now add the Control interface descriptor
+        desc.interface(itf_num, _CDC_CONTROL_EP_NUM, _INTERFACE_CLASS_CDC, _INTERFACE_SUBCLASS_CDC)
 
         # Append the CDC class-specific interface descriptor
         # see CDC120-track, p20
@@ -258,8 +245,8 @@ def descriptor_config_cb(self, desc, itf_num, str_num, ep_num):
             5,  # bFunctionLength
             _CS_DESC_TYPE,  # bDescriptorType
             _CDC_FUNC_DESC_HEADER,  # bDescriptorSubtype
-            _CDC_VERSION,
-        )  # cdc version
+            _CDC_VERSION,  # cdc version
+        )
 
         # CDC-PSTN table3 "Call Management"
         # set to No
@@ -269,8 +256,8 @@ def descriptor_config_cb(self, desc, itf_num, str_num, ep_num):
             _CS_DESC_TYPE,  # bDescriptorType
             _CDC_FUNC_DESC_CALL_MANAGEMENT,  # bDescriptorSubtype
             0,  # bmCapabilities - XXX no call managment so far
-            1,
-        )  # bDataInterface - interface 1
+            itf_num + 1,  # bDataInterface - interface 1
+        )
 
         # CDC-PSTN table4 "Abstract Control"
         # set to support line_coding and send_break
@@ -279,8 +266,8 @@ def descriptor_config_cb(self, desc, itf_num, str_num, ep_num):
             4,  # bFunctionLength
             _CS_DESC_TYPE,  # bDescriptorType
             _CDC_FUNC_DESC_ABSTRACT_CONTROL,  # bDescriptorSubtype
-            0x6,
-        )  # bmCapabilities D1, D2
+            0x6,  # bmCapabilities D1, D2
+        )
 
         # CDC-PSTN "Union"
         # set control interface / data interface number
@@ -290,15 +277,13 @@ def descriptor_config_cb(self, desc, itf_num, str_num, ep_num):
             _CS_DESC_TYPE,  # bDescriptorType
             _CDC_FUNC_DESC_UNION,  # bDescriptorSubtype
             itf_num,  # bControlInterface
-            itf_num + 1,  # data interface, assume this one will be assigned next
-        )  # bSubordinateInterface0 (data class itf number)
+            itf_num + 1,  # bSubordinateInterface0 (data class itf number)
+        )
 
         # Descriptor for a single endpoint
         self.ep_in = ep_num | EP_IN_FLAG
         desc.endpoint(self.ep_in, "interrupt", 8, 16)
 
-        return strs
-
     def handle_interface_control_xfer(self, stage, request):
         # Handle class-specific interface control transfers
         bmRequestType, bRequest, wValue, _, wLength = struct.unpack("BBHHH", request)
@@ -337,26 +322,29 @@ class CDCDataInterface(USBInterface):
     # Implements the CDC Data Interface
 
     def __init__(self):
-        super().__init__(
-            _CDC_ITF_DATA_CLASS, _CDC_ITF_DATA_SUBCLASS, _CDC_ITF_DATA_PROT, _CDC_DATA_EP_NUM
-        )
+        super().__init__()
+
         self._wb = ()  # Optional write Buffer (IN endpoint), set by CDC.init()
         self._rb = ()  # Optional read Buffer (OUT endpoint), set by CDC.init()
         self._timeout = 1000  # set from CDC.init() as well
 
         self.ep_in = self.ep_out = None  # Set when enumeration happens
 
-    def descriptor_config_cb(self, pack_fn, itf_num, str_num, ep_num):
+    def descriptor_config_cb(self, desc, itf_num, ep_num):
         # Add the standard interface descriptor
-        strs = super().descriptor_config_cb(pack_fn, itf_num, str_num, ep_num)
+        desc.interface(
+            itf_num,
+            _CDC_DATA_EP_NUM,
+            _CDC_ITF_DATA_CLASS,
+            _CDC_ITF_DATA_SUBCLASS,
+            _CDC_ITF_DATA_PROT,
+        )
 
-        # Two endpoints, bulk IN and OUT
-        self.ep_in = ep_num | EP_IN_FLAG
+        # Two endpoints, bulk OUT and IN
         self.ep_out = ep_num
-        endpoint_descriptor(pack_fn, self.ep_out, "bulk", _BULK_EP_LEN, 0)
-        endpoint_descriptor(pack_fn, self.ep_in, "bulk", _BULK_EP_LEN, 0)
-
-        return strs
+        self.ep_in = ep_num | EP_IN_FLAG
+        desc.endpoint(self.ep_out, "bulk", _BULK_EP_LEN, 0)
+        desc.endpoint(self.ep_in, "bulk", _BULK_EP_LEN, 0)
 
     def write(self, buf):
         # use a memoryview to track how much of 'buf' we've written so far

micropython/usbd/cdc_example.py

@@ -21,4 +21,4 @@
 
 old_term = os.dupterm(cdc)
 
-print("Welcome to REPL on CDC implemented in Python?")
+print("Welcome to REPL, running on CDC interface implemented in Python.")