Build USB descriptor from data structures, not code (#3107)

The USB descriptor and HID report descriptors were built in a hard-coded
mess of code with lots of very brittle logic to ensure things lined up
and were the right size.  Weak functions were used to signal the core
that different descriptors needed to be added, so things like the Keyboard
library actually had changes done in the core proper.

Move to a saner and more maintainable, global initialization stage process
where global object descriptors can call a `register` function to plug
in their own USB or HID descriptors to the core process.

Author: earlephilhower

cores/rp2040/RP2040USB.cpp

@@ -20,29 +20,33 @@
 */
 
 #include <pico/mutex.h>
+#include <limits.h>
 
-// Weak function definitions for each type of endpoint
-extern void __USBInstallSerial() __attribute__((weak));
+// Called by an object at global init time to register a HID device, returns a localID to be mapped using findHIDReportID
+// vidMask is the bits in the VID that should be XOR'd when this device is present.
+// 0 means don't invert anything, OTW select a single bitmask 1<<n.
+uint8_t usbRegisterHIDDevice(const uint8_t *descriptor, size_t len, int ordering, uint32_t vidMask = 0);
 
-extern void __USBInstallKeyboard() __attribute__((weak));
+// Called by an object at global init time to add a new interface (non-HID, like CDC or Picotool)
+uint8_t usbRegisterInterface(int interfaces, const uint8_t *descriptor, size_t len, int ordering = INT_MAX, uint32_t vidMask = 0);
 
-extern void __USBInstallJoystick() __attribute__((weak));
+// Get the USB HID actual report ID from the localid
+uint8_t usbFindHIDReportID(unsigned int localid);
 
-// One or the other allowed, not both
-extern void __USBInstallMouse() __attribute__((weak));
-extern void __USBInstallAbsoluteMouse() __attribute__((weak));
+// Get the USB interface number from the localid
+uint8_t usbFindInterfaceID(unsigned int localid);
 
-extern void __USBInstallMassStorage() __attribute__((weak));
+// Register a string for a USB descriptor
+uint8_t usbRegisterString(const char *str);
+
+// Get an unassigned in/cmd or out endpoint number
+uint8_t usbRegisterEndpointIn();
+uint8_t usbRegisterEndpointOut();
 
 // Big, global USB mutex, shared with all USB devices to make sure we don't
 // have multiple cores updating the TUSB state in parallel
 extern mutex_t __usb_mutex;
 
-// HID report ID inquiry (report ID will vary depending on the number/type of other HID)
-int __USBGetKeyboardReportID();
-int __USBGetMouseReportID();
-int __USBGetJoystickReportID();
-
 // Called by main() to init the USB HW/SW.
 void __USBStart();
 

cores/rp2040/RP2040USB.h

@@ -23,22 +23,10 @@
 #if !defined(USE_TINYUSB) && !defined(NO_USB)
 
 #include <Arduino.h>
+#include <tusb.h>
 #include "CoreMutex.h"
+#include "RP2040USB.h"
 
-#include <tusb.h>
-#include <pico/time.h>
-#include <pico/binary_info.h>
-#include <pico/bootrom.h>
-#include <hardware/irq.h>
-#include <pico/mutex.h>
-#include <hardware/watchdog.h>
-#include <pico/unique_id.h>
-#include <hardware/resets.h>
-
-#ifndef DISABLE_USB_SERIAL
-// Ensure we are installed in the USB chain
-void __USBInstallSerial() { /* noop */ }
-#endif
 
 // SerialEvent functions are weak, so when the user doesn't define them,
 // the linker just sets their address to 0 (which is checked below).
@@ -47,9 +35,22 @@ void __USBInstallSerial() { /* noop */ }
 // HardwareSerial instance if the user doesn't also refer to it.
 extern void serialEvent() __attribute__((weak));
 
-
 extern mutex_t __usb_mutex;
 
+#define USBD_CDC_CMD_MAX_SIZE (8)
+#define USBD_CDC_IN_OUT_MAX_SIZE (64)
+
+
+static const uint8_t cdc_desc[TUD_CDC_DESC_LEN] = {
+    // Interface number, string index, protocol, report descriptor len, EP In & Out address, size & polling interval
+    TUD_CDC_DESCRIPTOR(0 /* placeholder*/, usbRegisterString("Pico Serial"), usbRegisterEndpointIn(), USBD_CDC_CMD_MAX_SIZE, usbRegisterEndpointOut(), usbRegisterEndpointIn(), USBD_CDC_IN_OUT_MAX_SIZE)
+};
+
+SerialUSB::SerialUSB() {
+    _id = usbRegisterInterface(2, cdc_desc, sizeof(cdc_desc), 1, 0);
+}
+
+
 void SerialUSB::begin(unsigned long baud) {
     (void) baud; //ignored
 

cores/rp2040/SerialUSB.cpp

@@ -26,7 +26,7 @@
 
 class SerialUSB : public arduino::HardwareSerial {
 public:
-    SerialUSB() { }
+    SerialUSB();
     void begin(unsigned long baud = 115200) override;
     void begin(unsigned long baud, uint16_t config) override {
         (void) config;
@@ -56,6 +56,7 @@ class SerialUSB : public arduino::HardwareSerial {
 private:
     bool _running = false;
     bool _ignoreFlowControl = false;
+    uint8_t _id;
 };
 
 extern SerialUSB Serial;

cores/rp2040/SerialUSB.h

@@ -20,15 +20,15 @@
 #include "FatFSUSB.h"
 #include <FatFS.h>
 #include <class/msc/msc.h>
+#include <device/usbd.h>
+#include <RP2040USB.h>
 
 FatFSUSBClass FatFSUSB;
-
-// Ensure we are logged in to the USB framework
-void __USBInstallMassStorage() {
-    /* dummy */
-}
+#define USBD_MSC_EPSIZE 64
+static const uint8_t msd_desc[] = { TUD_MSC_DESCRIPTOR(1 /* placeholder */, 0, usbRegisterEndpointOut(), usbRegisterEndpointIn(), USBD_MSC_EPSIZE) };
 
 FatFSUSBClass::FatFSUSBClass() {
+    _id = usbRegisterInterface(2, msd_desc, sizeof(msd_desc), 1, 0);
 }
 
 FatFSUSBClass::~FatFSUSBClass() {

libraries/FatFSUSB/src/FatFSUSB.cpp

@@ -46,6 +46,7 @@ class FatFSUSBClass {
 
 private:
     bool _started = false;
+    uint8_t _id;
 
     int32_t _sectNum = -1;
     uint8_t *_sectBuff = nullptr;

libraries/FatFSUSB/src/FatFSUSB.h

@@ -28,20 +28,17 @@
 #include "tusb.h"
 #include "class/hid/hid_device.h"
 
-// Weak function override to add our descriptor to the TinyUSB list
-void __USBInstallJoystick() { /* noop */ }
-
+static const uint8_t desc_hid_report_joystick[] = { TUD_HID_REPORT_DESC_GAMEPAD16(HID_REPORT_ID(1)) };
 Joystick_::Joystick_(void) {
-    // Everything set up in HID_Joystick constructor
+    _id = usbRegisterHIDDevice(desc_hid_report_joystick, sizeof(desc_hid_report_joystick), 30, 0x0004);
 }
 
-
-//immediately send an HID report
+// immediately send an HID report
 void Joystick_::send_now(void) {
     CoreMutex m(&__usb_mutex);
     tud_task();
     if (__USBHIDReady()) {
-        tud_hid_n_report(0, __USBGetJoystickReportID(), &data, sizeof(data));
+        tud_hid_n_report(0, usbFindHIDReportID(_id), &data, sizeof(data));
     }
     tud_task();
 }

libraries/Joystick/src/Joystick.cpp

@@ -32,5 +32,7 @@ class Joystick_ : public HID_Joystick {
 public:
     Joystick_(void);
     virtual void send_now(void) override;
+private:
+    uint8_t _id;
 };
 extern Joystick_ Joystick;

libraries/Joystick/src/Joystick.h

@@ -26,22 +26,23 @@
 #include "tusb.h"
 #include "class/hid/hid_device.h"
 
-// Weak function override to add our descriptor to the TinyUSB list
-void __USBInstallKeyboard() { /* noop */ }
-
 //================================================================================
 //================================================================================
 //  Keyboard
 
+static const uint8_t desc_hid_report_keyboard[] = { TUD_HID_REPORT_DESC_KEYBOARD(HID_REPORT_ID(1))};
+static const uint8_t desc_hid_report_consumer[] = { TUD_HID_REPORT_DESC_CONSUMER(HID_REPORT_ID(2))};
 Keyboard_::Keyboard_(void) {
+    _id = usbRegisterHIDDevice(desc_hid_report_keyboard, sizeof(desc_hid_report_keyboard), 10, 0x0001);
+    _idConsumer = usbRegisterHIDDevice(desc_hid_report_consumer, sizeof(desc_hid_report_consumer), 11, 0x0000);
     // Base class clears the members we care about
 }
 
 void Keyboard_::sendReport(KeyReport* keys) {
     CoreMutex m(&__usb_mutex);
     tud_task();
     if (__USBHIDReady()) {
-        tud_hid_keyboard_report(__USBGetKeyboardReportID(), keys->modifiers, keys->keys);
+        tud_hid_keyboard_report(usbFindHIDReportID(_id), keys->modifiers, keys->keys);
     }
     tud_task();
 }
@@ -50,7 +51,7 @@ void Keyboard_::sendConsumerReport(uint16_t key) {
     CoreMutex m(&__usb_mutex);
     tud_task();
     if (__USBHIDReady()) {
-        tud_hid_report(__USBGetKeyboardReportID() + 1, &key, sizeof(key));
+        tud_hid_report(usbFindHIDReportID(_idConsumer), &key, sizeof(key));
     }
     tud_task();
 }

libraries/Keyboard/src/Keyboard.cpp

@@ -32,6 +32,8 @@ class Keyboard_ : public HID_Keyboard {
 protected:
     virtual void sendReport(KeyReport* keys) override;
     virtual void sendConsumerReport(uint16_t key) override;
+    uint8_t _id;
+    uint8_t _idConsumer;
 
 public:
     Keyboard_(void);