shared/tinyusb,extmod/machine_usb_device: Add NCM USB networking support.

pi-anl · pi-anl · commit d626566d66c9 · 2025-11-12T12:19:03.000+11:00
This commit adds Network Control Model (NCM) USB class support to the USB
device configurability framework, enabling USB-based networking functionality.

Key features:
- NCM class flag (USB_BUILTIN_FLAG_NCM, value 0x04) for bitfield operations
- BUILTIN_NCM constant for user-level enable/disable control
- Dynamic NCM descriptor generation based on enabled state
- Automatic interface/endpoint/string counting for NCM (2 interfaces, 3 endpoints)
- Runtime NCM cleanup on disable (calls usbnet_deinit())
- Guarded by MICROPY_HW_NETWORK_USBNET compile flag

NCM support integrates with the existing CDC/MSC infrastructure, following
the same enable/disable patterns and descriptor generation logic.

Signed-off-by: Andrew Leech &lt;andrew.leech@planetinnovation.com.au&gt;
diff --git a/extmod/machine_usb_device.c b/extmod/machine_usb_device.c
@@ -43,7 +43,7 @@
 #include "device/usbd_pvt.h"
 #endif
 
-#define HAS_BUILTIN_DRIVERS (MICROPY_HW_USB_CDC || MICROPY_HW_USB_MSC)
+#define HAS_BUILTIN_DRIVERS (MICROPY_HW_USB_CDC || MICROPY_HW_USB_MSC || MICROPY_HW_USB_NCM)
 
 // USB class flags are defined in mp_usbd.h
 
@@ -92,6 +92,11 @@ static mp_obj_t usb_device_make_new(const mp_obj_type_t *type, size_t n_args, si
             if (mp_usbd_class_state.msc_enabled) {
                 flags |= USB_BUILTIN_FLAG_MSC;
             }
+            #if MICROPY_HW_NETWORK_USBNET
+            if (mp_usbd_class_state.ncm_enabled) {
+                flags |= USB_BUILTIN_FLAG_NCM;
+            }
+            #endif
 
             // Create appropriate builtin object based on current state
             if (flags == USB_BUILTIN_FLAG_NONE) {
@@ -381,6 +386,11 @@ static uint8_t mp_usbd_get_itf_max(uint8_t flags) {
     if ((flags & USB_BUILTIN_FLAG_MSC) && MICROPY_HW_USB_MSC) {
         count += 1;
     }
+    #if MICROPY_HW_NETWORK_USBNET
+    if ((flags & USB_BUILTIN_FLAG_NCM) && MICROPY_HW_NETWORK_USBNET) {
+        count += 2;  // NCM uses 2 interfaces (control + data)
+    }
+    #endif
     return count;
 }
 
@@ -392,6 +402,11 @@ static uint8_t mp_usbd_get_ep_max(uint8_t flags) {
     if ((flags & USB_BUILTIN_FLAG_MSC) && MICROPY_HW_USB_MSC) {
         ep_max = (ep_max > 2) ? ep_max : 2;  // MSC uses endpoints 1, 2
     }
+    #if MICROPY_HW_NETWORK_USBNET
+    if ((flags & USB_BUILTIN_FLAG_NCM) && MICROPY_HW_NETWORK_USBNET) {
+        ep_max = (ep_max > 3) ? ep_max : 3;  // NCM uses endpoints 1, 2, 3
+    }
+    #endif
     return ep_max;
 }
 
@@ -403,6 +418,11 @@ static uint8_t mp_usbd_get_str_max(uint8_t flags) {
     if ((flags & USB_BUILTIN_FLAG_MSC) && MICROPY_HW_USB_MSC) {
         str_max = (str_max > 2) ? str_max : 2;  // MSC uses strings 1, 2
     }
+    #if MICROPY_HW_NETWORK_USBNET
+    if ((flags & USB_BUILTIN_FLAG_NCM) && MICROPY_HW_NETWORK_USBNET) {
+        str_max = (str_max > 3) ? str_max : 3;  // NCM uses strings 1, 2, 3
+    }
+    #endif
     return str_max;
 }
 
@@ -481,6 +501,12 @@ static const mp_obj_usb_builtin_t builtin_msc_obj = {
     {&mp_type_usb_builtin}, USB_BUILTIN_FLAG_MSC
 };
 
+#if MICROPY_HW_NETWORK_USBNET
+static const mp_obj_usb_builtin_t builtin_ncm_obj = {
+    {&mp_type_usb_builtin}, USB_BUILTIN_FLAG_NCM
+};
+#endif
+
 // Create default combination based on compile-time configuration
 #if MICROPY_HW_USB_CDC && MICROPY_HW_USB_MSC
 static const mp_obj_usb_builtin_t builtin_default_obj = {
@@ -524,6 +550,10 @@ static const mp_rom_map_elem_t usb_device_locals_dict_table[] = {
     { MP_ROM_QSTR(MP_QSTR_BUILTIN_CDC), MP_ROM_PTR(&builtin_cdc_obj) },
     { MP_ROM_QSTR(MP_QSTR_BUILTIN_MSC), MP_ROM_PTR(&builtin_msc_obj) },
 
+    #if MICROPY_HW_NETWORK_USBNET
+    { MP_ROM_QSTR(MP_QSTR_BUILTIN_NCM), MP_ROM_PTR(&builtin_ncm_obj) },
+    #endif
+
     // Legacy combination constant for backward compatibility
     #if MICROPY_HW_USB_CDC && MICROPY_HW_USB_MSC
     { MP_ROM_QSTR(MP_QSTR_BUILTIN_CDC_MSC), MP_ROM_PTR(&builtin_cdc_msc_obj) },
@@ -542,6 +572,10 @@ static const mp_rom_map_elem_t usb_device_locals_dict_table[] = {
     { MP_ROM_QSTR(MP_QSTR_BUILTIN_CDC), MP_ROM_PTR(&builtin_cdc_obj) },
     { MP_ROM_QSTR(MP_QSTR_BUILTIN_MSC), MP_ROM_PTR(&builtin_msc_obj) },
 
+    #if MICROPY_HW_NETWORK_USBNET
+    { MP_ROM_QSTR(MP_QSTR_BUILTIN_NCM), MP_ROM_PTR(&builtin_ncm_obj) },
+    #endif
+
     // Legacy combination constant for backward compatibility
     #if MICROPY_HW_USB_CDC && MICROPY_HW_USB_MSC
     { MP_ROM_QSTR(MP_QSTR_BUILTIN_CDC_MSC), MP_ROM_PTR(&builtin_cdc_msc_obj) },
@@ -594,6 +628,10 @@ static void usb_device_attr(mp_obj_t self_in, qstr attr, mp_obj_t *dest) {
                 flags = USB_BUILTIN_FLAG_CDC;
             } else if (dest[1] == MP_OBJ_FROM_PTR(&builtin_msc_obj)) {
                 flags = USB_BUILTIN_FLAG_MSC;
+            #if MICROPY_HW_NETWORK_USBNET
+            } else if (dest[1] == MP_OBJ_FROM_PTR(&builtin_ncm_obj)) {
+                flags = USB_BUILTIN_FLAG_NCM;
+            #endif
             #if MICROPY_HW_USB_CDC && MICROPY_HW_USB_MSC
             } else if (dest[1] == MP_OBJ_FROM_PTR(&builtin_cdc_msc_obj)) {
                 flags = USB_BUILTIN_FLAG_CDC | USB_BUILTIN_FLAG_MSC;
diff --git a/shared/tinyusb/mp_usbd.h b/shared/tinyusb/mp_usbd.h
@@ -60,6 +60,7 @@ void mp_usbd_hex_str(char *out_str, const uint8_t *bytes, size_t bytes_len);
 typedef struct {
     bool cdc_enabled;
     bool msc_enabled;
+    bool ncm_enabled;
 } mp_usbd_class_state_t;
 
 // Global class enable state
diff --git a/shared/tinyusb/mp_usbd_descriptor.c b/shared/tinyusb/mp_usbd_descriptor.c
@@ -64,17 +64,32 @@ void mp_usbd_init_class_state(void) {
     // In runtime mode, only CDC enabled by default
     mp_usbd_class_state.cdc_enabled = (CFG_TUD_CDC == 1);
     mp_usbd_class_state.msc_enabled = false;
+    mp_usbd_class_state.ncm_enabled = false;
     #else
     // In static mode, enable all compiled classes
     mp_usbd_class_state.cdc_enabled = (CFG_TUD_CDC == 1);
     mp_usbd_class_state.msc_enabled = (CFG_TUD_MSC == 1);
+    mp_usbd_class_state.ncm_enabled = (CFG_TUD_NCM == 1);
     #endif
 }
 
 // Update class state based on bitfield flags
 void mp_usbd_update_class_state(uint8_t flags) {
+    #if MICROPY_HW_NETWORK_USBNET
+    bool prev_ncm_enabled = mp_usbd_class_state.ncm_enabled;
+    #endif
+
     mp_usbd_class_state.cdc_enabled = (flags & USB_BUILTIN_FLAG_CDC) && (CFG_TUD_CDC == 1);
     mp_usbd_class_state.msc_enabled = (flags & USB_BUILTIN_FLAG_MSC) && (CFG_TUD_MSC == 1);
+    mp_usbd_class_state.ncm_enabled = (flags & USB_BUILTIN_FLAG_NCM) && (CFG_TUD_NCM == 1);
+
+    // If NCM is being disabled and it was active, clean it up
+    #if MICROPY_HW_NETWORK_USBNET
+    if (prev_ncm_enabled && !mp_usbd_class_state.ncm_enabled) {
+        extern void usbnet_deinit(void);
+        usbnet_deinit();
+    }
+    #endif
 }
 
 // Functions to generate descriptors from flags (for new bitfield-based system)
@@ -87,6 +102,9 @@ size_t mp_usbd_get_descriptor_cfg_len_from_flags(uint8_t flags) {
     if ((flags & USB_BUILTIN_FLAG_MSC) && CFG_TUD_MSC) {
         len += TUD_MSC_DESC_LEN;
     }
+    if ((flags & USB_BUILTIN_FLAG_NCM) && CFG_TUD_NCM) {
+        len += TUD_CDC_NCM_DESC_LEN;
+    }
 
     return len;
 }
@@ -100,6 +118,9 @@ static uint8_t mp_usbd_get_interface_count_from_flags(uint8_t flags) {
     if ((flags & USB_BUILTIN_FLAG_MSC) && CFG_TUD_MSC) {
         count += 1;
     }
+    if ((flags & USB_BUILTIN_FLAG_NCM) && CFG_TUD_NCM) {
+        count += 2;  // NCM uses 2 interfaces (control + data)
+    }
 
     return count;
 }
@@ -148,6 +169,17 @@ static const uint8_t *mp_usbd_generate_desc_cfg_unified(uint8_t flags, uint8_t *
     }
     #endif
 
+    #if CFG_TUD_NCM
+    if (flags & USB_BUILTIN_FLAG_NCM) {
+        const uint8_t ncm_desc[] = {
+            TUD_CDC_NCM_DESCRIPTOR(itf_num, USBD_STR_NET, USBD_STR_NET_MAC, USBD_NET_EP_CMD, 64, USBD_NET_EP_OUT, USBD_NET_EP_IN, USBD_NET_IN_OUT_MAX_SIZE, CFG_TUD_NET_MTU)
+        };
+        memcpy(desc, ncm_desc, sizeof(ncm_desc));
+        desc += sizeof(ncm_desc);
+        itf_num += 2;  // NCM uses 2 interfaces (control + data)
+    }
+    #endif
+
     return buffer;
 }
 
@@ -170,6 +202,9 @@ size_t mp_usbd_get_descriptor_cfg_len(void) {
     if (mp_usbd_class_state.msc_enabled && CFG_TUD_MSC) {
         len += TUD_MSC_DESC_LEN;
     }
+    if (mp_usbd_class_state.ncm_enabled && CFG_TUD_NCM) {
+        len += TUD_CDC_NCM_DESC_LEN;
+    }
 
     return len;
 }
@@ -188,6 +223,10 @@ static const uint8_t mp_usbd_builtin_desc_cfg_max[MP_USBD_BUILTIN_DESC_CFG_LEN]
     #if CFG_TUD_MSC
     TUD_MSC_DESCRIPTOR(USBD_ITF_MSC, USBD_STR_MSC, USBD_MSC_EP_OUT, USBD_MSC_EP_IN, USBD_MSC_IN_OUT_MAX_SIZE),
     #endif
+    #if CFG_TUD_NCM
+    // Interface number, description string index, MAC address string index, EP notification address and size, EP data address (out, in), and size, max segment size.
+    TUD_CDC_NCM_DESCRIPTOR(USBD_ITF_NET, USBD_STR_NET, USBD_STR_NET_MAC, USBD_NET_EP_CMD, 64, USBD_NET_EP_OUT, USBD_NET_EP_IN, USBD_NET_IN_OUT_MAX_SIZE, CFG_TUD_NET_MTU),
+    #endif
 };
 #endif
 
@@ -204,6 +243,9 @@ static uint8_t mp_usbd_class_state_to_flags(void) {
     if (mp_usbd_class_state.msc_enabled) {
         flags |= USB_BUILTIN_FLAG_MSC;
     }
+    if (mp_usbd_class_state.ncm_enabled) {
+        flags |= USB_BUILTIN_FLAG_NCM;
+    }
     return flags;
 }
 
