Merge branch 'feat/usb-explicit-fifo-config' into 'master'

feat(usb/hal): Add HAL API to configure custom FIFO layout

Closes IDF-9042

See merge request espressif/esp-idf!38404

Author: igi540

components/hal/include/hal/usb_dwc_hal.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2020-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -29,15 +29,6 @@ extern "C" {
 
 // ----------------------- Configs -------------------------
 
-/**
- * @brief Possible FIFO biases
- */
-typedef enum {
-    USB_HAL_FIFO_BIAS_DEFAULT,           /**< Default (balanced) FIFO sizes */
-    USB_HAL_FIFO_BIAS_RX,                /**< Bigger RX FIFO for IN transfers */
-    USB_HAL_FIFO_BIAS_PTX,               /**< Bigger periodic TX FIFO for ISOC OUT transfers */
-} usb_hal_fifo_bias_t;
-
 /**
  * @brief MPS limits based on FIFO configuration
  *
@@ -261,20 +252,35 @@ void usb_dwc_hal_deinit(usb_dwc_hal_context_t *hal);
 void usb_dwc_hal_core_soft_reset(usb_dwc_hal_context_t *hal);
 
 /**
- * @brief Set FIFO bias
+ * @brief Check if FIFO configuration is valid
+ *
+ * This function checks that the sum of FIFO sizes does not exceed available space.
+ * It does not modify hardware state and is safe to call from HAL or upper layers.
+ *
+ * @param[in] hal     Pointer to HAL context (must be initialized)
+ * @param[in] config  Pointer to FIFO config to validate
+ * @return true if config is valid, false otherwise
+ */
+bool usb_dwc_hal_fifo_config_is_valid(const usb_dwc_hal_context_t *hal, const usb_dwc_hal_fifo_config_t *config);
+
+
+/**
+ * @brief Set the FIFO sizes of the USB-DWC core
+ *
+ * This function programs the FIFO sizing registers (RX FIFO, Non-Periodic TX FIFO,
+ * and Periodic TX FIFO) based on the provided configuration. It must be called
+ * during USB initialization, before any channels are allocated or transfers started.
  *
- * This function will set the sizes of each of the FIFOs (RX FIFO, Non-periodic TX FIFO, Periodic TX FIFO) and must be
- * called at least once before allocating the channel. Based on the type of endpoints (and the endpoints' MPS), there
- * may be situations where this function may need to be called again to resize the FIFOs. If resizing FIFOs dynamically,
- * it is the user's responsibility to ensure there are no active channels when this function is called.
+ * The sum of all FIFO sizes must not exceed the hardware-defined limit
+ * (see HWCFG3.DfifoDepth and EPINFO_CTL).
  *
- * @note After a port reset, the FIFO size registers will reset to their default values, so this function must be called
- *       again post reset.
+ * @note This function must be called exactly once during initialization and after
+ *       each USB port reset. It is typically used internally by the USB Host stack.
  *
- * @param[in] hal       Context of the HAL layer
- * @param[in] fifo_bias FIFO bias configuration
+ * @param[inout] hal     Pointer to the HAL context
+ * @param[in]    config  Pointer to the FIFO configuration to apply (must be valid)
  */
-void usb_dwc_hal_set_fifo_bias(usb_dwc_hal_context_t *hal, const usb_hal_fifo_bias_t fifo_bias);
+void usb_dwc_hal_set_fifo_config(usb_dwc_hal_context_t *hal, const usb_dwc_hal_fifo_config_t *config);
 
 /**
  * @brief Get MPS limits

components/hal/usb_dwc_hal.c

@@ -185,64 +185,53 @@ void usb_dwc_hal_core_soft_reset(usb_dwc_hal_context_t *hal)
     }
 }
 
-void usb_dwc_hal_set_fifo_bias(usb_dwc_hal_context_t *hal, const usb_hal_fifo_bias_t fifo_bias)
+bool usb_dwc_hal_fifo_config_is_valid(const usb_dwc_hal_context_t *hal, const usb_dwc_hal_fifo_config_t *config)
 {
-    HAL_ASSERT(hal->channels.hdls);
-    const uint16_t fifo_size_lines = hal->constant_config.fifo_size;
-    /*
-    * Recommended FIFO sizes (see 2.1.2.4 for programming guide)
-    *
-    * RXFIFO:   ((LPS/4) * 2) + 2
-    * NPTXFIFO: (LPS/4) * 2
-    * PTXFIFO:  (LPS/4) * 2
-    *
-    * Recommended sizes fit 2 packets of each type. For S2 and S3 we can't fit even one MPS ISOC packet (1023 FS and 1024 HS).
-    * So the calculations below are compromises between the available FIFO size and optimal performance.
-    */
-
-    // Information for maintainers: this calculation is here for backward compatibility
-    // It should be removed when we allow HAL users to configure the FIFO sizes IDF-9042
-    const int otg_dfifo_depth = hal->constant_config.hsphy_type ? 1024 : 256;
-
-    usb_dwc_hal_fifo_config_t fifo_config;
-    switch (fifo_bias) {
-        // Define minimum viable (fits at least 1 MPS) FIFO sizes for non-biased FIFO types
-        // Allocate the remaining size to the biased FIFO type
-        case USB_HAL_FIFO_BIAS_DEFAULT:
-            fifo_config.nptx_fifo_lines = otg_dfifo_depth / 4;
-            fifo_config.ptx_fifo_lines  = otg_dfifo_depth / 8;
-            fifo_config.rx_fifo_lines   = fifo_size_lines - fifo_config.ptx_fifo_lines - fifo_config.nptx_fifo_lines;
-            break;
-        case USB_HAL_FIFO_BIAS_RX:
-            fifo_config.nptx_fifo_lines = otg_dfifo_depth / 16;
-            fifo_config.ptx_fifo_lines  = otg_dfifo_depth / 8;
-            fifo_config.rx_fifo_lines   = fifo_size_lines - fifo_config.ptx_fifo_lines - fifo_config.nptx_fifo_lines;
-            break;
-        case USB_HAL_FIFO_BIAS_PTX:
-            fifo_config.rx_fifo_lines   = otg_dfifo_depth / 8 + 2; // 2 extra lines are allocated for status information. See USB-OTG Programming Guide, chapter 2.1.2.1
-            fifo_config.nptx_fifo_lines = otg_dfifo_depth / 16;
-            fifo_config.ptx_fifo_lines  = fifo_size_lines - fifo_config.nptx_fifo_lines - fifo_config.rx_fifo_lines;
-            break;
-        default:
-            abort();
+    if (!hal || !config) {
+        return false;
     }
+    uint32_t used_lines = config->rx_fifo_lines + config->nptx_fifo_lines + config->ptx_fifo_lines;
+    return (used_lines <= hal->constant_config.fifo_size);
+}
+
+
+void usb_dwc_hal_set_fifo_config(usb_dwc_hal_context_t *hal, const usb_dwc_hal_fifo_config_t *config)
+{
+    // Check internal HAL state
+    HAL_ASSERT(hal != NULL);
+    HAL_ASSERT(hal->channels.hdls != NULL);
 
-    HAL_ASSERT((fifo_config.rx_fifo_lines + fifo_config.nptx_fifo_lines + fifo_config.ptx_fifo_lines) <= fifo_size_lines);
-    //Check that none of the channels are active
+    // Validate provided config
+    HAL_ASSERT(config != NULL);
+
+    // Check if configuration exceeds available FIFO memory
+    HAL_ASSERT(usb_dwc_hal_fifo_config_is_valid(hal, config));
+
+    // Ensure no active channels (must only be called before USB install completes)
     for (int i = 0; i < hal->constant_config.chan_num_total; i++) {
         if (hal->channels.hdls[i] != NULL) {
             HAL_ASSERT(!hal->channels.hdls[i]->flags.active);
         }
     }
-    //Set the new FIFO lengths
-    usb_dwc_ll_grxfsiz_set_fifo_size(hal->dev, fifo_config.rx_fifo_lines);
-    usb_dwc_ll_gnptxfsiz_set_fifo_size(hal->dev, fifo_config.rx_fifo_lines, fifo_config.nptx_fifo_lines);
-    usb_dwc_ll_hptxfsiz_set_ptx_fifo_size(hal->dev, fifo_config.rx_fifo_lines + fifo_config.nptx_fifo_lines, fifo_config.ptx_fifo_lines);
-    //Flush the FIFOs
+
+    // Program FIFO size registers
+    usb_dwc_ll_grxfsiz_set_fifo_size(hal->dev, config->rx_fifo_lines);// Set RX FIFO size (GRXFSIZ)
+    // Set Non-Periodic TX FIFO (GNPTXFSIZ)
+    // Offset = RX FIFO lines
+    usb_dwc_ll_gnptxfsiz_set_fifo_size(hal->dev, config->rx_fifo_lines, config->nptx_fifo_lines);
+    // Set Periodic TX FIFO (HPTXFSIZ)
+    // Offset = RX + NPTX
+    usb_dwc_ll_hptxfsiz_set_ptx_fifo_size(hal->dev,
+                                          config->rx_fifo_lines + config->nptx_fifo_lines,
+                                          config->ptx_fifo_lines);
+
+    // Flush all FIFOs
     usb_dwc_ll_grstctl_flush_nptx_fifo(hal->dev);
     usb_dwc_ll_grstctl_flush_ptx_fifo(hal->dev);
     usb_dwc_ll_grstctl_flush_rx_fifo(hal->dev);
-    hal->fifo_config = fifo_config; // Implicit struct copy
+
+    // Save configuration to HAL context
+    hal->fifo_config = *config;
     hal->flags.fifo_sizes_set = 1;
 }
 

components/usb/hcd_dwc.c

@@ -250,8 +250,8 @@ struct port_obj {
         uint32_t val;
     } flags;
     bool initialized;
-    // FIFO biasing related
-    usb_hal_fifo_bias_t fifo_bias;                  // Bias is saved so it can be reconfigured upon reset
+    // FIFO related
+    usb_dwc_hal_fifo_config_t fifo_config;          // FIFO config to be applied at HAL level
     // Port callback and context
     hcd_port_callback_t callback;
     void *callback_arg;
@@ -554,6 +554,23 @@ static bool _port_check_all_pipes_halted(port_t *port);
  */
 static bool _port_debounce(port_t *port);
 
+/**
+ * @brief Convert user-provided FIFO configuration to HAL format
+ *
+ * This function validates and converts a user-defined FIFO configuration
+ * (provided via `hcd_config_t.fifo_config`) into the format expected by the HAL.
+ * It ensures that both RX FIFO and Non-Periodic TX FIFO sizes are non-zero.
+ *
+ * @param[in]  src Pointer to user-defined FIFO settings (HCD format)
+ * @param[out] dst Pointer to HAL-compatible FIFO configuration structure
+ *
+ * @return
+ *      - ESP_OK: Conversion successful and values copied
+ *      - ESP_ERR_INVALID_SIZE: Either RX FIFO or Non-Periodic TX FIFO is zero
+ */
+
+static esp_err_t convert_fifo_config_to_hal_config(const hcd_fifo_settings_t *src, usb_dwc_hal_fifo_config_t *dst);
+
 /**
  * @brief Power ON the port
  *
@@ -744,16 +761,6 @@ static usb_speed_t get_usb_port_speed(usb_dwc_speed_t priv)
     }
 }
 
-static usb_hal_fifo_bias_t get_hal_fifo_bias(hcd_port_fifo_bias_t public)
-{
-    switch (public) {
-    case HCD_PORT_FIFO_BIAS_BALANCED: return USB_HAL_FIFO_BIAS_DEFAULT;
-    case HCD_PORT_FIFO_BIAS_RX: return USB_HAL_FIFO_BIAS_RX;
-    case HCD_PORT_FIFO_BIAS_PTX: return USB_HAL_FIFO_BIAS_PTX;
-    default: abort();
-    }
-}
-
 // ----------------- Interrupt Handlers --------------------
 
 /**
@@ -954,6 +961,46 @@ static void intr_hdlr_main(void *arg)
     }
 }
 
+// ----------------------- FIFO Config -------------------------
+
+/**
+ * @brief Calculate default FIFO configuration based on bias preference
+ *
+ * This function calculates the FIFO configuration (RX, non-periodic TX, and periodic TX)
+ * according to the selected bias mode from Kconfig:
+ *
+ * - CONFIG_USB_HOST_HW_BUFFER_BIAS_IN: Prioritize RX FIFO space, useful for IN-heavy traffic.
+ * - CONFIG_USB_HOST_HW_BUFFER_BIAS_PERIODIC_OUT: Prioritize periodic TX FIFO, suitable for periodic OUT transfers.
+ * - USB_HOST_HW_BUFFER_BIAS_BALANCED: Balanced configuration between RX and both TX FIFOs.
+ *
+ * @param[inout] port Pointer to the port object whose fifo_config will be filled
+ * @param[in] hal Pointer to an initialized HAL context providing hardware FIFO limits
+ */
+static void  _calculate_fifo_from_bias(port_t *port, const usb_dwc_hal_context_t *hal)
+{
+    const int otg_dfifo_depth = hal->constant_config.hsphy_type ? 1024 : 256;
+    const uint16_t fifo_size_lines = hal->constant_config.fifo_size;
+
+#if CONFIG_USB_HOST_HW_BUFFER_BIAS_IN
+    // Prioritize RX FIFO (best for IN-heavy workloads)
+    port->fifo_config.nptx_fifo_lines = otg_dfifo_depth / 16;
+    port->fifo_config.ptx_fifo_lines = otg_dfifo_depth / 8;
+    port->fifo_config.rx_fifo_lines = fifo_size_lines - port->fifo_config.ptx_fifo_lines - port->fifo_config.nptx_fifo_lines;
+
+#elif CONFIG_USB_HOST_HW_BUFFER_BIAS_PERIODIC_OUT
+    // Prioritize periodic TX FIFO (useful for high throughput periodic endpoints)
+    port->fifo_config.rx_fifo_lines = otg_dfifo_depth / 8 + 2; // 2 extra lines are allocated for status information. See USB-OTG Programming Guide, chapter 2.1.2.1
+    port->fifo_config.nptx_fifo_lines = otg_dfifo_depth / 16;
+    port->fifo_config.ptx_fifo_lines = fifo_size_lines - port->fifo_config.nptx_fifo_lines - port->fifo_config.rx_fifo_lines;
+
+#else // USB_HOST_HW_BUFFER_BIAS_BALANCED
+    // Balanced configuration (default)
+    port->fifo_config.nptx_fifo_lines = otg_dfifo_depth / 4;
+    port->fifo_config.ptx_fifo_lines = otg_dfifo_depth / 8;
+    port->fifo_config.rx_fifo_lines = fifo_size_lines - port->fifo_config.ptx_fifo_lines - port->fifo_config.nptx_fifo_lines;
+#endif
+}
+
 // --------------------------------------------- Host Controller Driver ------------------------------------------------
 
 static port_t *port_obj_alloc(void)
@@ -1018,6 +1065,15 @@ esp_err_t hcd_install(const hcd_config_t *config)
         ESP_LOGE(HCD_DWC_TAG, "Interrupt alloc error: %s", esp_err_to_name(err_ret));
         goto intr_alloc_err;
     }
+    // Apply custom FIFO config if provided, otherwise mark as default (all zeros)
+    memset(&p_hcd_obj_dmy->port_obj->fifo_config, 0, sizeof(p_hcd_obj_dmy->port_obj->fifo_config));
+    if (config->fifo_config != NULL) {
+        // Convert and validate user-provided config
+        err_ret = convert_fifo_config_to_hal_config(config->fifo_config, &p_hcd_obj_dmy->port_obj->fifo_config);
+        if (err_ret != ESP_OK) {
+            goto assign_err;
+        }
+    }
     HCD_ENTER_CRITICAL();
     if (s_hcd_obj != NULL) {
         HCD_EXIT_CRITICAL();
@@ -1100,6 +1156,34 @@ static bool _port_debounce(port_t *port)
     return is_connected;
 }
 
+static esp_err_t convert_fifo_config_to_hal_config(const hcd_fifo_settings_t *src, usb_dwc_hal_fifo_config_t *dst)
+{
+    // Check at least RX and NPTX are non-zero
+    if (src->rx_fifo_lines == 0 || src->nptx_fifo_lines == 0) {
+        ESP_LOGE(HCD_DWC_TAG, "RX and Non-Periodic TX FIFO must be > 0");
+        return ESP_ERR_INVALID_SIZE;
+    }
+    // Assign valid values
+    dst->rx_fifo_lines   = src->rx_fifo_lines;
+    dst->nptx_fifo_lines = src->nptx_fifo_lines;
+    dst->ptx_fifo_lines  = src->ptx_fifo_lines; // OK even if zero
+
+    return ESP_OK;
+}
+
+/**
+ * @brief Check if the FIFO config is marked to use bias-based default values.
+ *
+ * If all FIFO line sizes are zero, the configuration is considered uninitialized,
+ * and default values will be calculated based on bias settings.
+ */
+static inline bool _is_fifo_config_by_bias(const usb_dwc_hal_fifo_config_t *cfg)
+{
+    return (cfg->rx_fifo_lines == 0 &&
+            cfg->nptx_fifo_lines == 0 &&
+            cfg->ptx_fifo_lines == 0);
+}
+
 // ---------------------- Commands -------------------------
 
 static esp_err_t _port_cmd_power_on(port_t *port)
@@ -1177,8 +1261,16 @@ static esp_err_t _port_cmd_reset(port_t *port)
         goto bailout;
     }
 
-    // Reinitialize port registers.
-    usb_dwc_hal_set_fifo_bias(port->hal, port->fifo_bias);  // Set FIFO biases
+    // Reinitialize port registers
+    if (!usb_dwc_hal_fifo_config_is_valid(port->hal, &port->fifo_config)) {
+        HCD_EXIT_CRITICAL();
+        ret = ESP_ERR_INVALID_SIZE;
+        ESP_LOGE(HCD_DWC_TAG, "Invalid FIFO config");
+        HCD_ENTER_CRITICAL();
+        goto bailout;
+    }
+    usb_dwc_hal_set_fifo_config(port->hal, &port->fifo_config);// Apply FIFO settings
+
     usb_dwc_hal_port_set_frame_list(port->hal, port->frame_list, FRAME_LIST_LEN);   // Set periodic frame list
     usb_dwc_hal_port_periodic_enable(port->hal);    // Enable periodic scheduling
 
@@ -1287,7 +1379,6 @@ esp_err_t hcd_port_init(int port_number, const hcd_port_config_t *port_config, h
     TAILQ_INIT(&port_obj->pipes_active_tailq);
     port_obj->state = HCD_PORT_STATE_NOT_POWERED;
     port_obj->last_event = HCD_PORT_EVENT_NONE;
-    port_obj->fifo_bias = get_hal_fifo_bias(port_config->fifo_bias);
     port_obj->callback = port_config->callback;
     port_obj->callback_arg = port_config->callback_arg;
     port_obj->context = port_config->context;
@@ -1297,10 +1388,18 @@ esp_err_t hcd_port_init(int port_number, const hcd_port_config_t *port_config, h
     port_obj->initialized = true;
     // Clear the frame list. We set the frame list register and enable periodic scheduling after a successful reset
     memset(port_obj->frame_list, 0, FRAME_LIST_LEN * sizeof(uint32_t));
+    // If FIFO config is zeroed -> calculate from bias
+    if (_is_fifo_config_by_bias(&port_obj->fifo_config)) {
+        // Calculate default FIFO sizes based on Kconfig bias settings
+        _calculate_fifo_from_bias(port_obj, port_obj->hal);
+    }
     esp_intr_enable(s_hcd_obj->isr_hdl);
     *port_hdl = (hcd_port_handle_t)port_obj;
     HCD_EXIT_CRITICAL();
-
+    ESP_LOGD(HCD_DWC_TAG, "FIFO config lines: RX=%u, PTX=%u, NPTX=%u",
+             port_obj->fifo_config.rx_fifo_lines,
+             port_obj->fifo_config.ptx_fifo_lines,
+             port_obj->fifo_config.nptx_fifo_lines);
     vTaskDelay(pdMS_TO_TICKS(INIT_DELAY_MS));    // Need a short delay before host mode takes effect
     return ESP_OK;
 }
@@ -1455,28 +1554,6 @@ void *hcd_port_get_context(hcd_port_handle_t port_hdl)
     return ret;
 }
 
-esp_err_t hcd_port_set_fifo_bias(hcd_port_handle_t port_hdl, hcd_port_fifo_bias_t bias)
-{
-    esp_err_t ret;
-    usb_hal_fifo_bias_t hal_bias = get_hal_fifo_bias(bias);
-
-    // Configure the new FIFO sizes and store the pointers
-    port_t *port = (port_t *)port_hdl;
-    xSemaphoreTake(port->port_mux, portMAX_DELAY);
-    HCD_ENTER_CRITICAL();
-    // Check that port is in the correct state to update FIFO sizes
-    if (port->initialized && !port->flags.event_pending && port->num_pipes_idle == 0 && port->num_pipes_queued == 0) {
-        usb_dwc_hal_set_fifo_bias(port->hal, hal_bias);
-        port->fifo_bias = hal_bias;
-        ret = ESP_OK;
-    } else {
-        ret = ESP_ERR_INVALID_STATE;
-    }
-    HCD_EXIT_CRITICAL();
-    xSemaphoreGive(port->port_mux);
-    return ret;
-}
-
 // --------------------------------------------------- HCD Pipes -------------------------------------------------------
 
 // ----------------------- Private -------------------------