usb: fix rx buffer overflow with proper flow control

- Check buffer space before reading USB data
- Track rx_stalled state to minimize kickoff overhead
- Only retry reading when previously stalled and space available
- Prevents data loss while maintaining USB NAK flow control
- Document ring buffer interrupt safety guarantees

Author: bkleiner

src/driver/mcu/at32/usb.c

@@ -14,6 +14,7 @@ extern volatile bool usb_device_configured;
 
 static otg_core_type otg_core_struct;
 
+static volatile bool rx_stalled = false;
 static volatile bool tx_stalled = true;
 
 static void usb_enable_clock() {
@@ -74,6 +75,14 @@ void usb_drv_init() {
 void usb_cdc_rx_handler() {
   usb_device_configured = true;
 
+  // Check if we have enough space before reading
+  if (ring_buffer_free(&usb_rx_buffer) < USBD_CDC_IN_MAXPACKET_SIZE) {
+    // Don't read data, USB will NAK automatically
+    rx_stalled = true;
+    return;
+  }
+  rx_stalled = false;
+
   static uint8_t buf[USBD_CDC_IN_MAXPACKET_SIZE];
 
   const uint16_t len = usb_vcp_get_rxdata(&otg_core_struct.dev, buf);
@@ -83,6 +92,16 @@ void usb_cdc_rx_handler() {
   ring_buffer_write_multi(&usb_rx_buffer, buf, len);
 }
 
+static void usb_cdc_kickoff_rx() {
+  if (!rx_stalled) {
+    return;
+  }
+
+  interrupt_disable(OTGFS1_IRQn);
+  usb_cdc_rx_handler();
+  interrupt_enable(OTGFS1_IRQn, USB_PRIORITY);
+}
+
 void usb_cdc_tx_handler() {
   usb_device_configured = true;
 
@@ -126,7 +145,9 @@ uint32_t usb_serial_read(uint8_t *data, uint32_t len) {
   if (data == NULL || len == 0) {
     return 0;
   }
-  return ring_buffer_read_multi(&usb_rx_buffer, data, len);
+  const uint32_t read = ring_buffer_read_multi(&usb_rx_buffer, data, len);
+  usb_cdc_kickoff_rx();
+  return read;
 }
 
 void usb_serial_write(uint8_t *data, uint32_t len) {

src/driver/mcu/stm32/usb.c

@@ -240,8 +240,8 @@ static usbd_respond cdc_control(usbd_device *dev, usbd_ctlreq *req, usbd_rqc_cal
 }
 
 static void cdc_rxonly(usbd_device *dev, uint8_t event, uint8_t ep) {
-  if (ring_buffer_free(&usb_rx_buffer) <= CDC_DATA_SZ) {
-    interrupt_disable(USB_IRQ);
+  if (ring_buffer_free(&usb_rx_buffer) < CDC_DATA_SZ) {
+    // Don't read data, USB will NAK automatically
     rx_stalled = true;
     return;
   }

src/util/ring_buffer.h

@@ -2,8 +2,18 @@
 
 #include <stdint.h>
 
-// This Ring Buffer _should_ be interrupt-safe given a single consumer/producer scenario.
-// Monitor usage closely to ensure above condition is true. All internal blocking has been removed.
+// This Ring Buffer implementation is interrupt-safe for single producer/single consumer scenarios.
+// 
+// Safety guarantees:
+// - One context writes (producer), one context reads (consumer)
+// - Head is only modified by producer, tail only by consumer
+// - ring_buffer_free() and ring_buffer_available() take atomic snapshots of volatile pointers
+// - These functions may return slightly stale values if called during concurrent access,
+//   but the values are always valid and safe (conservative for buffer overflow prevention)
+// 
+// Typical usage:
+// - ISR writes to RX buffer, main reads from RX buffer
+// - Main writes to TX buffer, ISR reads from TX buffer
 typedef struct {
   uint8_t *const buffer;
   volatile uint32_t head;