feat(usb/hal): Add support for explicit FIFO configuration

Introduce a new HAL API `usb_dwc_hal_set_fifo_config()` that allows advanced users
to manually configure RX, Non-Periodic TX, and Periodic TX FIFO sizes. This offers
fine-grained control beyond the previous bias-based sizing approach.

The HAL function no longer returns `esp_err_t`, and internal validations are enforced
via `HAL_ASSERT()`. Responsibility for input validation has been moved to the HCD layer.

FIFO configuration must be applied before any USB pipes are created or activated.
This feature is intended for use during `usb_host_install()`.

If no custom FIFO configuration is provided (i.e., all values are zero),
the driver falls back to a bias-based default layout based on Kconfig settings
(`CONFIG_USB_HOST_HW_BUFFER_BIAS_*`). Bias resolution is done inside `hcd_port_init()`.

The `port_obj_t` structure has been extended with a `fifo_config` field, which stores
the configuration to allow re-application after a USB port reset.

Obsolete FIFO bias enums (`usb_hal_fifo_bias_t`, `hcd_port_fifo_bias_t`) and related
APIs (`hcd_port_set_fifo_bias()`) have been removed in favor of the new structure-based mechanism.

The HCD initialization and port reset flow has been updated to use the explicit
FIFO configuration.

USB Host maintainer documentation (`maintainers.md`) has been updated accordingly.
Test cases were updated to remove the usage of removed bias API and now rely on default
or custom FIFO configuration.
This commit is contained in:
igor.masar
2025-05-20 16:11:40 +02:00
parent fe75355314
commit d191538f18
11 changed files with 230 additions and 143 deletions
+17 -26
View File
@@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
* SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
@@ -137,24 +137,32 @@ typedef bool (*hcd_port_callback_t)(hcd_port_handle_t port_hdl, hcd_port_event_t
*/
typedef bool (*hcd_pipe_callback_t)(hcd_pipe_handle_t pipe_hdl, hcd_pipe_event_t pipe_event, void *user_arg, bool in_isr);
typedef enum {
HCD_PORT_FIFO_BIAS_BALANCED, /**< Balanced FIFO sizing for RX, Non-periodic TX, and periodic TX */
HCD_PORT_FIFO_BIAS_RX, /**< Bias towards a large RX FIFO */
HCD_PORT_FIFO_BIAS_PTX, /**< Bias towards periodic TX FIFO */
} hcd_port_fifo_bias_t;
/**
* @brief Optional user-defined FIFO configuration (used internally by HCD)
*
* This structure is filled by the USB Host layer if the user provides
* custom FIFO values. All values must be greater than zero to activate
* the configuration. If NULL is passed, HCD will use the default
* configuration based on the Kconfig bias.
*/
typedef struct {
uint32_t nptx_fifo_lines; /**< Number of non-periodic TX FIFO lines */
uint32_t ptx_fifo_lines; /**< Number of periodic TX FIFO lines */
uint32_t rx_fifo_lines; /**< Number of RX FIFO lines */
} hcd_fifo_settings_t;
/**
* @brief HCD configuration structure
*/
typedef struct {
int intr_flags; /**< Interrupt flags for HCD interrupt */
int intr_flags; /**< Interrupt flags for HCD interrupt */
const hcd_fifo_settings_t *fifo_config;/**< Optional pointer to custom FIFO config.
If NULL, default configuration is used. */
} hcd_config_t;
/**
* @brief Port configuration structure
*/
typedef struct {
hcd_port_fifo_bias_t fifo_bias; /**< HCD port internal FIFO biasing */
hcd_port_callback_t callback; /**< HCD port event callback */
void *callback_arg; /**< User argument for HCD port callback */
void *context; /**< Context variable used to associate the port with upper layer object */
@@ -340,23 +348,6 @@ esp_err_t hcd_port_recover(hcd_port_handle_t port_hdl);
*/
void *hcd_port_get_context(hcd_port_handle_t port_hdl);
/**
* @brief Set the bias of the HCD port's internal FIFO
*
* @note This function can only be called when the following conditions are met:
* - Port is initialized
* - Port does not have any pending events
* - Port does not have any allocated pipes
*
* @param[in] port_hdl Port handle
* @param[in] bias Fifo bias
*
* @return
* - ESP_OK FIFO sizing successfully set
* - ESP_ERR_INVALID_STATE Incorrect state for FIFO sizes to be set
*/
esp_err_t hcd_port_set_fifo_bias(hcd_port_handle_t port_hdl, hcd_port_fifo_bias_t bias);
// --------------------------------------------------- HCD Pipes -------------------------------------------------------
/**