esp-idf/components/usb/hcd_dwc.c

/*
 * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
 *
 * SPDX-License-Identifier: Apache-2.0
 */

#include <stdint.h>
#include <string.h>
#include <sys/queue.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "freertos/semphr.h"
#include "esp_heap_caps.h"
#include "esp_dma_utils.h"
#include "esp_intr_alloc.h"
#include "soc/interrupts.h" // For interrupt index
#include "esp_err.h"
#include "esp_log.h"
#include "hal/usb_dwc_hal.h"
#include "hal/usb_dwc_types.h"
#include "hcd.h"
#include "usb_private.h"
#include "usb/usb_types_ch9.h"

#include "soc/soc_caps.h"
#if SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE
#include "esp_cache.h"
#include "esp_private/esp_cache_private.h"
#endif // SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE

// ----------------------------------------------------- Macros --------------------------------------------------------

// ------------------ Target specific ----------------------
// TODO: Remove target specific section after support for multiple USB peripherals is implemented
#include "sdkconfig.h"
#if (CONFIG_IDF_TARGET_ESP32P4)
#define USB_INTR ETS_USB_OTG_INTR_SOURCE
#else
#define USB_INTR ETS_USB_INTR_SOURCE
#endif

// --------------------- Constants -------------------------

#define INIT_DELAY_MS                           30  // A delay of at least 25ms to enter Host mode. Make it 30ms to be safe
#define DEBOUNCE_DELAY_MS                       CONFIG_USB_HOST_DEBOUNCE_DELAY_MS
#define RESET_HOLD_MS                           CONFIG_USB_HOST_RESET_HOLD_MS
#define RESET_RECOVERY_MS                       CONFIG_USB_HOST_RESET_RECOVERY_MS
#define RESUME_HOLD_MS                          30  // Spec requires at least 20ms, Make it 30ms to be safe
#define RESUME_RECOVERY_MS                      20  // Resume recovery of at least 10ms. Make it 20 ms to be safe. This will include the 3 LS bit times of the EOP

#define CTRL_EP_MAX_MPS_LS                      8   // Largest Maximum Packet Size for Low Speed control endpoints
#define CTRL_EP_MAX_MPS_HSFS                    64  // Largest Maximum Packet Size for High & Full Speed control endpoints

#define NUM_PORTS                               1   // The controller only has one port.

// ----------------------- Configs -------------------------

#define FRAME_LIST_LEN                          USB_HAL_FRAME_LIST_LEN_32
#define NUM_BUFFERS                             2

#define XFER_LIST_LEN_CTRL                      3   // One descriptor for each stage
#define XFER_LIST_LEN_BULK                      2   // One descriptor for transfer, one to support an extra zero length packet
// Same length as the frame list makes it easier to schedule. Must be power of 2
// FS: Must be 2-64. HS: Must be 8-256. See USB-OTG databook Table 5-47
#define XFER_LIST_LEN_INTR                      FRAME_LIST_LEN
#define XFER_LIST_LEN_ISOC                      FRAME_LIST_LEN

// ------------------------ Flags --------------------------

/**
 * @brief Bit masks for the HCD to use in the URBs reserved_flags field
 *
 * The URB object has a reserved_flags member for host stack's internal use. The following flags will be set in
 * reserved_flags in order to keep track of state of an URB within the HCD.
 */
#define URB_HCD_STATE_IDLE                      0   // The URB is not enqueued in an HCD pipe
#define URB_HCD_STATE_PENDING                   1   // The URB is enqueued and pending execution
#define URB_HCD_STATE_INFLIGHT                  2   // The URB is currently in flight
#define URB_HCD_STATE_DONE                      3   // The URB has completed execution or is retired, and is waiting to be dequeued

#define URB_HCD_STATE_SET(reserved_flags, state)    (reserved_flags = (reserved_flags & ~URB_HCD_STATE_MASK) | state)
#define URB_HCD_STATE_GET(reserved_flags)           (reserved_flags & URB_HCD_STATE_MASK)

// -------------------- Convenience ------------------------

const char *HCD_DWC_TAG = "HCD DWC";

#define HCD_ENTER_CRITICAL_ISR()                portENTER_CRITICAL_ISR(&hcd_lock)
#define HCD_EXIT_CRITICAL_ISR()                 portEXIT_CRITICAL_ISR(&hcd_lock)
#define HCD_ENTER_CRITICAL()                    portENTER_CRITICAL(&hcd_lock)
#define HCD_EXIT_CRITICAL()                     portEXIT_CRITICAL(&hcd_lock)

#define HCD_CHECK(cond, ret_val) ({                                         \
            if (!(cond)) {                                                  \
                return (ret_val);                                           \
            }                                                               \
})
#define HCD_CHECK_FROM_CRIT(cond, ret_val) ({                               \
            if (!(cond)) {                                                  \
                HCD_EXIT_CRITICAL();                                        \
                return ret_val;                                             \
            }                                                               \
})

// ----------------------- Cache sync ----------------------

/**
 * @brief Cache sync macros
 *
 * This macros are relevant only for SOCs that have L1 cache for internal memory
 * For other SOCs this is no-operation
 */
#if SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE
#define ALIGN_UP_BY(num, align)                     (((num) + ((align) - 1)) & ~((align) - 1))
#define CACHE_SYNC_FRAME_LIST(frame_list)           cache_sync_frame_list(frame_list)
#define CACHE_SYNC_XFER_DESCRIPTOR_LIST_M2C(buffer) cache_sync_xfer_descriptor_list(buffer, true)
#define CACHE_SYNC_XFER_DESCRIPTOR_LIST_C2M(buffer) cache_sync_xfer_descriptor_list(buffer, false)
#define CACHE_SYNC_DATA_BUFFER_M2C(pipe, urb)       cache_sync_data_buffer(pipe, urb, true)
#define CACHE_SYNC_DATA_BUFFER_C2M(pipe, urb)       cache_sync_data_buffer(pipe, urb, false)
#else // SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE
#define CACHE_SYNC_FRAME_LIST(frame_list)
#define CACHE_SYNC_XFER_DESCRIPTOR_LIST_M2C(buffer)
#define CACHE_SYNC_XFER_DESCRIPTOR_LIST_C2M(buffer)
#define CACHE_SYNC_DATA_BUFFER_M2C(pipe, urb)
#define CACHE_SYNC_DATA_BUFFER_C2M(pipe, urb)
#endif // SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE

// ------------------------------------------------------ Types --------------------------------------------------------

typedef struct pipe_obj pipe_t;
typedef struct port_obj port_t;

/**
 * @brief Object representing a single buffer of a pipe's multi buffer implementation
 */
typedef struct {
    void *xfer_desc_list;
    int xfer_desc_list_len_bytes;           // Only for cache msync
    urb_t *urb;
    union {
        struct {
            uint32_t data_stg_in: 1;        // Data stage of the control transfer is IN
            uint32_t data_stg_skip: 1;      // Control transfer has no data stage
            uint32_t cur_stg: 2;            // Index of the current stage (e.g., 0 is setup stage, 2 is status stage)
            uint32_t reserved28: 28;
        } ctrl;                             // Control transfer related
        struct {
            uint32_t zero_len_packet: 1;    // Added a zero length packet, so transfer consists of 2 QTDs
            uint32_t reserved31: 31;
        } bulk;                             // Bulk transfer related
        struct {
            uint32_t num_qtds: 8;           // Number of transfer descriptors filled (excluding zero length packet)
            uint32_t zero_len_packet: 1;    // Added a zero length packet, so true number descriptors is num_qtds + 1
            uint32_t reserved23: 23;
        } intr;                             // Interrupt transfer related
        struct {
            uint32_t num_qtds: 8;           // Number of transfer descriptors filled (including NULL descriptors)
            uint32_t interval: 8;           // Interval (in number of SOF i.e., ms)
            uint32_t start_idx: 8;          // Index of the first transfer descriptor in the list
            uint32_t next_start_idx: 8;     // Index for the first descriptor of the next buffer
        } isoc;
        uint32_t val;
    } flags;
    union {
        struct {
            uint32_t executing: 1;          // The buffer is currently executing
            uint32_t was_canceled: 1;      // Buffer was done due to a cancellation (i.e., a halt request)
            uint32_t reserved6: 6;
            uint32_t stop_idx: 8;           // The descriptor index when the channel was halted
            hcd_pipe_event_t pipe_event: 8; // The pipe event when the buffer was done
            uint32_t reserved8: 8;
        };
        uint32_t val;
    } status_flags;                         // Status flags for the buffer
} dma_buffer_block_t;

/**
 * @brief Object representing a pipe in the HCD layer
 */
struct pipe_obj {
    // URB queuing related
    TAILQ_HEAD(tailhead_urb_pending, urb_s) pending_urb_tailq;
    TAILQ_HEAD(tailhead_urb_done, urb_s) done_urb_tailq;
    int num_urb_pending;
    int num_urb_done;
    // Multi-buffer control
    dma_buffer_block_t *buffers[NUM_BUFFERS];  // Double buffering scheme
    union {
        struct {
            uint32_t buffer_num_to_fill: 2; // Number of buffers that can be filled
            uint32_t buffer_num_to_exec: 2; // Number of buffers that are filled and need to be executed
            uint32_t buffer_num_to_parse: 2;// Number of buffers completed execution and waiting to be parsed
            uint32_t reserved2: 2;
            uint32_t wr_idx: 1;             // Index of the next buffer to fill. Bit width must allow NUM_BUFFERS to wrap automatically
            uint32_t rd_idx: 1;             // Index of the current buffer in-flight. Bit width must allow NUM_BUFFERS to wrap automatically
            uint32_t fr_idx: 1;             // Index of the next buffer to parse. Bit width must allow NUM_BUFFERS to wrap automatically
            uint32_t buffer_is_executing: 1;// One of the buffers is in flight
            uint32_t reserved20: 20;
        };
        uint32_t val;
    } multi_buffer_control;
    // HAL related
    usb_dwc_hal_chan_t *chan_obj;
    usb_dwc_hal_ep_char_t ep_char;
    // Port related
    port_t *port;                           // The port to which this pipe is routed through
    TAILQ_ENTRY(pipe_obj) tailq_entry;      // TailQ entry for port's list of pipes
    // Pipe status/state/events related
    hcd_pipe_state_t state;
    hcd_pipe_event_t last_event;
    volatile TaskHandle_t task_waiting_pipe_notif;  // Task handle used for internal pipe events. Set by waiter, cleared by notifier
    union {
        struct {
            uint32_t waiting_halt: 1;
            uint32_t pipe_cmd_processing: 1;
            uint32_t has_urb: 1;            // Indicates there is at least one URB either pending, in-flight, or done
            uint32_t reserved29: 29;
        };
        uint32_t val;
    } cs_flags;
    // Pipe callback and context
    hcd_pipe_callback_t callback;
    void *callback_arg;
    void *context;
};

/**
 * @brief Object representing a port in the HCD layer
 */
struct port_obj {
    usb_dwc_hal_context_t *hal;
    void *frame_list;
    // Pipes routed through this port
    TAILQ_HEAD(tailhead_pipes_idle, pipe_obj) pipes_idle_tailq;
    TAILQ_HEAD(tailhead_pipes_queued, pipe_obj) pipes_active_tailq;
    int num_pipes_idle;
    int num_pipes_queued;
    // Port status, state, and events
    hcd_port_state_t state;
    usb_speed_t speed;
    hcd_port_event_t last_event;
    volatile TaskHandle_t task_waiting_port_notif;  // Task handle used for internal port events. Set by waiter, cleared by notifier
    union {
        struct {
            uint32_t event_pending: 1;              // The port has an event that needs to be handled
            uint32_t event_processing: 1;           // The port is current processing (handling) an event
            uint32_t cmd_processing: 1;             // Used to indicate command handling is ongoing
            uint32_t disable_requested: 1;
            uint32_t conn_dev_ena: 1;               // Used to indicate the port is connected to a device that has been reset
            uint32_t periodic_scheduling_enabled: 1;
            uint32_t reserved26: 26;
        };
        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
    // Port callback and context
    hcd_port_callback_t callback;
    void *callback_arg;
    SemaphoreHandle_t port_mux;
    void *context;
};

/**
 * @brief Object representing the HCD
 */
typedef struct {
    // Ports (Hardware only has one)
    port_t *port_obj;
    intr_handle_t isr_hdl;
} hcd_obj_t;

static portMUX_TYPE hcd_lock = portMUX_INITIALIZER_UNLOCKED;
static hcd_obj_t *s_hcd_obj = NULL;     // Note: "s_" is for the static pointer

// ------------------------------------------------- Forward Declare ---------------------------------------------------

// --------------------- Cache sync ------------------------

#if SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE
/**
 * @brief Sync Frame List from cache to memory
 */
static inline void cache_sync_frame_list(void *frame_list)
{
    esp_err_t ret = esp_cache_msync(frame_list, FRAME_LIST_LEN * sizeof(uint32_t), 0);
    assert(ret == ESP_OK);
}

/**
 * @brief Sync Transfer Descriptor List
 *
 * @param[in] buffer       Buffer that holds the Transfer Descriptor List
 * @param[in] mem_to_cache Direction of cache sync
 */
static inline void cache_sync_xfer_descriptor_list(dma_buffer_block_t *buffer, bool mem_to_cache)
{
    esp_err_t ret = esp_cache_msync(buffer->xfer_desc_list, buffer->xfer_desc_list_len_bytes, mem_to_cache ? ESP_CACHE_MSYNC_FLAG_DIR_M2C : 0);
    assert(ret == ESP_OK);
}

/**
 * @brief Sync Transfer data buffer
 *
 * This function must be called before a URB is enqueued or dequeued.
 * Based on transfer direction (IN/OUT), this function will msync the data buffer associated with this URB.
 *
 * @note Here we also accept UNALIGNED data, for cases where the class drivers force overwrite the allocated data buffers
 *
 * @param[in] pipe Pipe belonging to this data buffer
 * @param[in] urb  URB belonging to this data buffer
 * @param[in] done Whether data buffer was just processed or is about to be processed
 */
static inline void cache_sync_data_buffer(pipe_t *pipe, urb_t *urb, bool done)
{
    const bool is_in = pipe->ep_char.bEndpointAddress & USB_B_ENDPOINT_ADDRESS_EP_DIR_MASK;
    const bool is_ctrl = (pipe->ep_char.type == USB_DWC_XFER_TYPE_CTRL);
    if ((is_in == done) || is_ctrl) {
        uint32_t flags = (done) ? ESP_CACHE_MSYNC_FLAG_DIR_M2C : ESP_CACHE_MSYNC_FLAG_UNALIGNED;
        esp_err_t ret = esp_cache_msync(urb->transfer.data_buffer, urb->transfer.data_buffer_size, flags);
        assert(ret == ESP_OK);
    }
}
#endif // SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE

// --------------------- Allocation ------------------------

/**
 * @brief Allocate Frame List
 *
 * - Frame list is allocated in DMA capable memory
 * - Frame list is aligned to 512 and cache line size
 *
 * @note Free the memory with heap_caps_free() call
 *
 * @param[in] frame_list_len Length of the Frame List
 * @return Pointer to allocated frame list
 */
static void *frame_list_alloc(size_t frame_list_len);

/**
 * @brief Allocate Transfer Descriptor List
 *
 * - Frame list is allocated in DMA capable memory
 * - Frame list is aligned to 512 and cache line size
 *
 * @note Free the memory with heap_caps_free() call
 *
 * @param[in]  list_len           Required length
 * @param[out] list_len_bytes_out Allocated length in bytes (can be greater than required)
 * @return Pointer to allocated transfer descriptor list
 */
static void *transfer_descriptor_list_alloc(size_t list_len, size_t *list_len_bytes_out);

// ------------------- Buffer Control ----------------------

/**
 * @brief Check if an inactive buffer can be filled with a pending URB
 *
 * @param pipe Pipe object
 * @return true There are one or more pending URBs, and the inactive buffer is yet to be filled
 * @return false Otherwise
 */
static inline bool _buffer_can_fill(pipe_t *pipe)
{
    // We can only fill if there are pending URBs and at least one unfilled buffer
    if (pipe->num_urb_pending > 0 && pipe->multi_buffer_control.buffer_num_to_fill > 0) {
        return true;
    } else {
        return false;
    }
}

/**
 * @brief Fill an empty buffer with
 *
 * This function will:
 * - Remove an URB from the pending tailq
 * - Fill that URB into the inactive buffer
 *
 * @note _buffer_can_fill() must return true before calling this function
 *
 * @param pipe Pipe object
 */
static void _buffer_fill(pipe_t *pipe);

/**
 * @brief Check if there are more filled buffers than can be executed
 *
 * @param pipe Pipe object
 * @return true There are more filled buffers to be executed
 * @return false No more buffers to execute
 */
static inline bool _buffer_can_exec(pipe_t *pipe)
{
    // We can only execute if there is not already a buffer executing and if there are filled buffers awaiting execution
    if (!pipe->multi_buffer_control.buffer_is_executing && pipe->multi_buffer_control.buffer_num_to_exec > 0) {
        return true;
    } else {
        return false;
    }
}

/**
 * @brief Execute the next filled buffer
 *
 * - Must have called _buffer_can_exec() before calling this function
 * - Will start the execution of the buffer
 *
 * @param pipe Pipe object
 */
static void _buffer_exec(pipe_t *pipe);

/**
 * @brief Check if a buffer as completed execution
 *
 * This should only be called after receiving a USB_DWC_HAL_CHAN_EVENT_CPLT event to check if a buffer is actually
 * done.
 *
 * @param pipe Pipe object
 * @return true Buffer complete
 * @return false Buffer not complete
 */
static inline bool _buffer_check_done(pipe_t *pipe)
{
    if (pipe->ep_char.type != USB_DWC_XFER_TYPE_CTRL) {
        return true;
    }
    // Only control transfers need to be continued
    dma_buffer_block_t *buffer_inflight = pipe->buffers[pipe->multi_buffer_control.rd_idx];
    return (buffer_inflight->flags.ctrl.cur_stg == 2);
}

/**
 * @brief Continue execution of a buffer
 *
 * This should only be called after checking if a buffer has completed execution using _buffer_check_done()
 *
 * @param pipe Pipe object
 */
static void _buffer_exec_cont(pipe_t *pipe);

/**
 * @brief Marks the last executed buffer as complete
 *
 * This should be called on a pipe that has confirmed that a buffer is completed via _buffer_check_done()
 *
 * @param pipe Pipe object
 * @param stop_idx Descriptor index when the buffer stopped execution
 * @param pipe_event Pipe event that caused the buffer to be complete. Use HCD_PIPE_EVENT_NONE for halt request of disconnections
 * @param canceled Whether the buffer was done due to a canceled (i.e., halt request). Must set pipe_event to HCD_PIPE_EVENT_NONE
 */
static inline void _buffer_done(pipe_t *pipe, int stop_idx, hcd_pipe_event_t pipe_event, bool canceled)
{
    // Store the stop_idx and pipe_event for later parsing
    dma_buffer_block_t *buffer_done = pipe->buffers[pipe->multi_buffer_control.rd_idx];
    buffer_done->status_flags.executing = 0;
    buffer_done->status_flags.was_canceled = canceled;
    buffer_done->status_flags.stop_idx = stop_idx;
    buffer_done->status_flags.pipe_event = pipe_event;
    pipe->multi_buffer_control.rd_idx++;
    pipe->multi_buffer_control.buffer_num_to_exec--;
    pipe->multi_buffer_control.buffer_num_to_parse++;
    pipe->multi_buffer_control.buffer_is_executing = 0;
}

/**
 * @brief Checks if a pipe has one or more completed buffers to parse
 *
 * @param pipe Pipe object
 * @return true There are one or more buffers to parse
 * @return false There are no more buffers to parse
 */
static inline bool _buffer_can_parse(pipe_t *pipe)
{
    if (pipe->multi_buffer_control.buffer_num_to_parse > 0) {
        return true;
    } else {
        return false;
    }
}

/**
 * @brief Parse a completed buffer
 *
 * This function will:
 * - Parse the results of an URB from a completed buffer
 * - Put the URB into the done tailq
 *
 * @note This function should only be called on the completion of a buffer
 *
 * @param pipe Pipe object
 * @param stop_idx (For INTR pipes only) The index of the descriptor that follows the last descriptor of the URB. Set to 0 otherwise
 */
static void _buffer_parse(pipe_t *pipe);

/**
 * @brief Marks all buffers pending execution as completed, then parses those buffers
 *
 * @note This should only be called on pipes do not have any currently executing buffers.
 *
 * @param pipe Pipe object
 * @param canceled Whether this flush is due to cancellation
 * @return true One or more buffers were flushed
 * @return false There were no buffers that needed to be flushed
 */
static bool _buffer_flush_all(pipe_t *pipe, bool canceled);

// ------------------------ Pipe ---------------------------

/**
 * @brief Decode a HAL channel error to the corresponding pipe event
 *
 * @param chan_error The HAL channel error
 * @return hcd_pipe_event_t The corresponding pipe error event
 */
static inline hcd_pipe_event_t pipe_decode_error_event(usb_dwc_hal_chan_error_t chan_error);

/**
 * @brief Halt a pipe
 *
 * - Attempts to halt a pipe. Pipe must be active in order to be halted
 * - If the underlying channel has an ongoing transfer, a halt will be requested, then the function will block until the
 *   channel indicates it is halted
 * - If the channel is no on-going transfer, the pipe will simply be marked has halted (thus preventing any further URBs
 *   from being enqueued)
 *
 * @note This function can block
 * @param pipe Pipe object
 * @return esp_err_t
 */
static esp_err_t _pipe_cmd_halt(pipe_t *pipe);

/**
 * @brief Flush a pipe
 *
 * - Flushing a pipe causes all of its pending URBs to be become done, thus allowing them to be dequeued
 * - The pipe must be halted in order to be flushed
 * - The pipe callback will be run if one or more URBs become done
 *
 * @param pipe Pipe object
 * @return esp_err_t
 */
static esp_err_t _pipe_cmd_flush(pipe_t *pipe);

/**
 * @brief Clear a pipe from its halt
 *
 * - Pipe must be halted in order to be cleared
 * - Clearing a pipe makes it active again
 * - If there are any enqueued URBs, they will executed
 *
 * @param pipe Pipe object
 * @return esp_err_t
 */
static esp_err_t _pipe_cmd_clear(pipe_t *pipe);

// ------------------------ Port ---------------------------

/**
 * @brief Checks if all pipes are in the halted state
 *
 * @param port Port object
 * @return true All pipes are halted
 * @return false Not all pipes are halted
 */
static bool _port_check_all_pipes_halted(port_t *port);

/**
 * @brief Debounce port after a connection or disconnection event
 *
 * This function should be called after a port connection or disconnect event. This function will execute a debounce
 * delay then check the actual connection/disconnections state.
 *
 * @note This function can block
 * @param port Port object
 * @return true A device is connected
 * @return false No device connected
 */
static bool _port_debounce(port_t *port);

/**
 * @brief Power ON the port
 *
 * @param port Port object
 * @return esp_err_t
 */
static esp_err_t _port_cmd_power_on(port_t *port);

/**
 * @brief Power OFF the port
 *
 * - If a device is currently connected, this function will cause a disconnect event
 *
 * @param port Port object
 * @return esp_err_t
 */
static esp_err_t _port_cmd_power_off(port_t *port);

/**
 * @brief Reset the port
 *
 * - This function issues a reset signal using the timings specified by the USB2.0 spec
 *
 * @note This function can block
 * @param port Port object
 * @return esp_err_t
 */
static esp_err_t _port_cmd_reset(port_t *port);

/**
 * @brief Suspend the port
 *
 * - Port must be enabled in order to to be suspended
 * - All pipes must be halted for the port to be suspended
 * - Suspending the port stops Keep Alive/SOF from being sent to the connected device
 *
 * @param port Port object
 * @return esp_err_t
 */
static esp_err_t _port_cmd_bus_suspend(port_t *port);

/**
 * @brief Resume the port
 *
 * - Port must be suspended in order to be resumed
 *
 * @note This function can block
 * @param port Port object
 * @return esp_err_t
 */
static esp_err_t _port_cmd_bus_resume(port_t *port);

/**
 * @brief Disable the port
 *
 * - All pipes must be halted for the port to be disabled
 * - The port must be enabled or suspended in order to be disabled
 *
 * @note This function can block
 * @param port Port object
 * @return esp_err_t
 */
static esp_err_t _port_cmd_disable(port_t *port);

// ----------------------- Events --------------------------

/**
 * @brief Wait for an internal event from a port
 *
 * @note For each port, there can only be one thread/task waiting for an internal port event
 * @note This function is blocking (will exit and re-enter the critical section to do so)
 *
 * @param port Port object
 */
static void _internal_port_event_wait(port_t *port);

/**
 * @brief Notify (from an ISR context) the thread/task waiting for the internal port event
 *
 * @param port Port object
 * @return true A yield is required
 * @return false Whether a yield is required or not
 */
static bool _internal_port_event_notify_from_isr(port_t *port);

/**
 * @brief Wait for an internal event from a particular pipe
 *
 * @note For each pipe, there can only be one thread/task waiting for an internal port event
 * @note This function is blocking (will exit and re-enter the critical section to do so)
 *
 * @param pipe Pipe object
 */
static void _internal_pipe_event_wait(pipe_t *pipe);

/**
 * @brief Notify (from an ISR context) the thread/task waiting for an internal pipe event
 *
 * @param pipe Pipe object
 * @param from_isr Whether this is called from an ISR or not
 * @return true A yield is required
 * @return false Whether a yield is required or not. Always false when from_isr is also false
 */
static bool _internal_pipe_event_notify(pipe_t *pipe, bool from_isr);

// ----------------------------------------------- Interrupt Handling --------------------------------------------------

// ------------------- Internal Event ----------------------

static void _internal_port_event_wait(port_t *port)
{
    // There must NOT be another thread/task already waiting for an internal event
    assert(port->task_waiting_port_notif == NULL);
    port->task_waiting_port_notif = xTaskGetCurrentTaskHandle();
    /* We need to loop as task notifications can come from anywhere. If we this
    was a port event notification, task_waiting_port_notif will have been cleared
    by the notifier. */
    while (port->task_waiting_port_notif != NULL) {
        HCD_EXIT_CRITICAL();
        // Wait to be notified from ISR
        ulTaskNotifyTake(pdTRUE, portMAX_DELAY);
        HCD_ENTER_CRITICAL();
    }
}

static bool _internal_port_event_notify_from_isr(port_t *port)
{
    // There must be a thread/task waiting for an internal event
    assert(port->task_waiting_port_notif != NULL);
    TaskHandle_t task_to_unblock = port->task_waiting_port_notif;
    // Clear task_waiting_port_notif to indicate to the waiter that the unblock was indeed an port event notification
    port->task_waiting_port_notif = NULL;
    // Unblock the thread/task waiting for the notification
    BaseType_t xTaskWoken = pdFALSE;
    // Note: We don't exit the critical section to be atomic. vTaskNotifyGiveFromISR() doesn't block anyways
    vTaskNotifyGiveFromISR(task_to_unblock, &xTaskWoken);
    return (xTaskWoken == pdTRUE);
}

static void _internal_pipe_event_wait(pipe_t *pipe)
{
    // There must NOT be another thread/task already waiting for an internal event
    assert(pipe->task_waiting_pipe_notif == NULL);
    pipe->task_waiting_pipe_notif = xTaskGetCurrentTaskHandle();
    /* We need to loop as task notifications can come from anywhere. If we this
    was a pipe event notification, task_waiting_pipe_notif will have been cleared
    by the notifier. */
    while (pipe->task_waiting_pipe_notif != NULL) {
        // Wait to be unblocked by notified
        HCD_EXIT_CRITICAL();
        ulTaskNotifyTake(pdTRUE, portMAX_DELAY);
        HCD_ENTER_CRITICAL();
    }
}

static bool _internal_pipe_event_notify(pipe_t *pipe, bool from_isr)
{
    // There must be a thread/task waiting for an internal event
    assert(pipe->task_waiting_pipe_notif != NULL);
    TaskHandle_t task_to_unblock = pipe->task_waiting_pipe_notif;
    // Clear task_waiting_pipe_notif to indicate to the waiter that the unblock was indeed an pipe event notification
    pipe->task_waiting_pipe_notif = NULL;
    bool ret;
    if (from_isr) {
        BaseType_t xTaskWoken = pdFALSE;
        // Note: We don't exit the critical section to be atomic. vTaskNotifyGiveFromISR() doesn't block anyways
        // Unblock the thread/task waiting for the pipe notification
        vTaskNotifyGiveFromISR(task_to_unblock, &xTaskWoken);
        ret = (xTaskWoken == pdTRUE);
    } else {
        HCD_EXIT_CRITICAL();
        xTaskNotifyGive(task_to_unblock);
        HCD_ENTER_CRITICAL();
        ret = false;
    }
    return ret;
}

// ----------------- HAL <-> USB helpers --------------------

static usb_speed_t get_usb_port_speed(usb_dwc_speed_t priv)
{
    switch (priv) {
    case USB_DWC_SPEED_LOW: return USB_SPEED_LOW;
    case USB_DWC_SPEED_FULL: return USB_SPEED_FULL;
    case USB_DWC_SPEED_HIGH: return USB_SPEED_HIGH;
    default: abort();
    }
}

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 --------------------

/**
 * @brief Handle a HAL port interrupt and obtain the corresponding port event
 *
 * @param[in] port Port object
 * @param[in] hal_port_event The HAL port event
 * @param[out] yield Set to true if a yield is required as a result of handling the interrupt
 * @return hcd_port_event_t  Returns a port event, or HCD_PORT_EVENT_NONE if no port event occurred
 */
static hcd_port_event_t _intr_hdlr_hprt(port_t *port, usb_dwc_hal_port_event_t hal_port_event, bool *yield)
{
    hcd_port_event_t port_event = HCD_PORT_EVENT_NONE;
    switch (hal_port_event) {
    case USB_DWC_HAL_PORT_EVENT_CONN: {
        // Don't update state immediately, we still need to debounce.
        port_event = HCD_PORT_EVENT_CONNECTION;
        break;
    }
    case USB_DWC_HAL_PORT_EVENT_DISCONN: {
        port->state = HCD_PORT_STATE_RECOVERY;
        port_event = HCD_PORT_EVENT_DISCONNECTION;
        port->flags.conn_dev_ena = 0;
        break;
    }
    case USB_DWC_HAL_PORT_EVENT_ENABLED: {
        usb_dwc_hal_port_enable(port->hal);  // Initialize remaining host port registers
        port->speed = get_usb_port_speed(usb_dwc_hal_port_get_conn_speed(port->hal));
        port->state = HCD_PORT_STATE_ENABLED;
        port->flags.conn_dev_ena = 1;
        // This was triggered by a command, so no event needs to be propagated.
        break;
    }
    case USB_DWC_HAL_PORT_EVENT_DISABLED: {
        port->flags.conn_dev_ena = 0;
        // Disabled could be due to a disable request or reset request, or due to a port error
        if (port->state != HCD_PORT_STATE_RESETTING) {  // Ignore the disable event if it's due to a reset request
            if (port->flags.disable_requested) {
                // Disabled by request (i.e. by port command). Generate an internal event
                port->state = HCD_PORT_STATE_DISABLED;
                port->flags.disable_requested = 0;
                *yield |= _internal_port_event_notify_from_isr(port);
            } else {
                // Disabled due to a port error
                port->state = HCD_PORT_STATE_RECOVERY;
                port_event = HCD_PORT_EVENT_ERROR;
            }
        }
        break;
    }
    case USB_DWC_HAL_PORT_EVENT_OVRCUR:
    case USB_DWC_HAL_PORT_EVENT_OVRCUR_CLR: {  // Could occur if a quick overcurrent then clear happens
        if (port->state != HCD_PORT_STATE_NOT_POWERED) {
            // We need to power OFF the port to protect it
            usb_dwc_hal_port_toggle_power(port->hal, false);
            port->state = HCD_PORT_STATE_RECOVERY;
            port_event = HCD_PORT_EVENT_OVERCURRENT;
        }
        port->flags.conn_dev_ena = 0;
        break;
    }
    default: {
        abort();
        break;
    }
    }
    return port_event;
}

/**
 * @brief Handles a HAL channel interrupt
 *
 * This function should be called on a HAL channel when it has an interrupt. Most HAL channel events will correspond to
 * to a pipe event, but not always. This function will store the pipe event and return a pipe object pointer if a pipe
 * event occurred, or return NULL otherwise.
 *
 * @param[in] chan_obj Pointer to HAL channel object with interrupt
 * @param[out] yield Set to true if a yield is required as a result of handling the interrupt
 * @return hcd_pipe_event_t The pipe event
 */
static hcd_pipe_event_t _intr_hdlr_chan(pipe_t *pipe, usb_dwc_hal_chan_t *chan_obj, bool *yield)
{
    usb_dwc_hal_chan_event_t chan_event = usb_dwc_hal_chan_decode_intr(chan_obj);
    hcd_pipe_event_t event = HCD_PIPE_EVENT_NONE;

    switch (chan_event) {
    case USB_DWC_HAL_CHAN_EVENT_CPLT: {
        if (!_buffer_check_done(pipe)) {
            _buffer_exec_cont(pipe);
            break;
        }
        pipe->last_event = HCD_PIPE_EVENT_URB_DONE;
        event = pipe->last_event;
        // Mark the buffer as done
        int stop_idx = usb_dwc_hal_chan_get_qtd_idx(chan_obj);
        _buffer_done(pipe, stop_idx, pipe->last_event, false);
        // First check if there is another buffer we can execute. But we only want to execute if there's still a valid device
        if (_buffer_can_exec(pipe) && pipe->port->flags.conn_dev_ena) {
            // If the next buffer is filled and ready to execute, execute it
            _buffer_exec(pipe);
        }
        // Handle the previously done buffer
        _buffer_parse(pipe);
        // Check to see if we can fill another buffer. But we only want to fill if there is still a valid device
        if (_buffer_can_fill(pipe) && pipe->port->flags.conn_dev_ena) {
            // Now that we've parsed a buffer, see if another URB can be filled in its place
            _buffer_fill(pipe);
        }
        break;
    }
    case USB_DWC_HAL_CHAN_EVENT_ERROR: {
        // Get and store the pipe error event
        usb_dwc_hal_chan_error_t chan_error = usb_dwc_hal_chan_get_error(chan_obj);
        pipe->last_event = pipe_decode_error_event(chan_error);
        event = pipe->last_event;
        pipe->state = HCD_PIPE_STATE_HALTED;
        // Mark the buffer as done with an error
        int stop_idx = usb_dwc_hal_chan_get_qtd_idx(chan_obj);
        _buffer_done(pipe, stop_idx, pipe->last_event, false);
        // Parse the buffer
        _buffer_parse(pipe);
        break;
    }
    case USB_DWC_HAL_CHAN_EVENT_HALT_REQ: {
        assert(pipe->cs_flags.waiting_halt);
        // We've halted a transfer, so we need to trigger the pipe callback
        pipe->last_event = HCD_PIPE_EVENT_URB_DONE;
        event = pipe->last_event;
        // Halt request event is triggered when packet is successful completed. But just treat all halted transfers as errors
        pipe->state = HCD_PIPE_STATE_HALTED;
        int stop_idx = usb_dwc_hal_chan_get_qtd_idx(chan_obj);
        _buffer_done(pipe, stop_idx, HCD_PIPE_EVENT_NONE, true);
        // Parse the buffer
        _buffer_parse(pipe);
        // Notify the task waiting for the pipe halt
        *yield |= _internal_pipe_event_notify(pipe, true);
        break;
    }
    case USB_DWC_HAL_CHAN_EVENT_NONE: {
        break;  // Nothing to do
    }
    default:
        abort();
        break;
    }
    return event;
}

/**
 * @brief Main interrupt handler
 *
 * - Handle all HPRT (Host Port) related interrupts first as they may change the
 *   state of the driver (e.g., a disconnect event)
 * - If any channels (pipes) have pending interrupts, handle them one by one
 * - The HCD has not blocking functions, so the user's ISR callback is run to
 *   allow the users to send whatever OS primitives they need.
 *
 * @param arg Interrupt handler argument
 */
static void intr_hdlr_main(void *arg)
{
    port_t *port = (port_t *) arg;
    bool yield = false;

    HCD_ENTER_CRITICAL_ISR();
    usb_dwc_hal_port_event_t hal_port_evt = usb_dwc_hal_decode_intr(port->hal);
    if (hal_port_evt == USB_DWC_HAL_PORT_EVENT_CHAN) {
        // Channel event. Cycle through each pending channel
        usb_dwc_hal_chan_t *chan_obj = usb_dwc_hal_get_chan_pending_intr(port->hal);
        while (chan_obj != NULL) {
            pipe_t *pipe = (pipe_t *)usb_dwc_hal_chan_get_context(chan_obj);
            hcd_pipe_event_t event = _intr_hdlr_chan(pipe, chan_obj, &yield);
            // Run callback if a pipe event has occurred and the pipe also has a callback
            if (event != HCD_PIPE_EVENT_NONE && pipe->callback != NULL) {
                HCD_EXIT_CRITICAL_ISR();
                yield |= pipe->callback((hcd_pipe_handle_t)pipe, event, pipe->callback_arg, true);
                HCD_ENTER_CRITICAL_ISR();
            }
            // Check for more channels with pending interrupts. Returns NULL if there are no more
            chan_obj = usb_dwc_hal_get_chan_pending_intr(port->hal);
        }
    } else if (hal_port_evt != USB_DWC_HAL_PORT_EVENT_NONE) {  // Port event
        hcd_port_event_t port_event = _intr_hdlr_hprt(port, hal_port_evt, &yield);
        if (port_event != HCD_PORT_EVENT_NONE) {
            port->last_event = port_event;
            port->flags.event_pending = 1;
            if (port->callback != NULL) {
                HCD_EXIT_CRITICAL_ISR();
                yield |= port->callback((hcd_port_handle_t)port, port_event, port->callback_arg, true);
                HCD_ENTER_CRITICAL_ISR();
            }
        }
    }
    HCD_EXIT_CRITICAL_ISR();

    if (yield) {
        portYIELD_FROM_ISR();
    }
}

// --------------------------------------------- Host Controller Driver ------------------------------------------------

static port_t *port_obj_alloc(void)
{
    port_t *port = calloc(1, sizeof(port_t));
    usb_dwc_hal_context_t *hal = malloc(sizeof(usb_dwc_hal_context_t));
    void *frame_list = frame_list_alloc(FRAME_LIST_LEN);
    SemaphoreHandle_t port_mux = xSemaphoreCreateMutex();
    if (port == NULL || hal == NULL || frame_list == NULL || port_mux == NULL) {
        free(port);
        free(hal);
        free(frame_list);
        if (port_mux != NULL) {
            vSemaphoreDelete(port_mux);
        }
        return NULL;
    }
    port->hal = hal;
    port->frame_list = frame_list;
    port->port_mux = port_mux;
    return port;
}

static void port_obj_free(port_t *port)
{
    if (port == NULL) {
        return;
    }
    vSemaphoreDelete(port->port_mux);
    free(port->frame_list);
    free(port->hal);
    free(port);
}

void *frame_list_alloc(size_t frame_list_len)
{
    esp_err_t ret;
    void *frame_list = NULL;
    size_t actual_size = 0;
    esp_dma_mem_info_t dma_mem_info = {
        .dma_alignment_bytes = USB_DWC_FRAME_LIST_MEM_ALIGN,
    };
    ret = esp_dma_capable_calloc(frame_list_len, sizeof(uint32_t), &dma_mem_info, &frame_list, &actual_size);
    assert(ret == ESP_OK);

    // Both Frame List start address and size should be already cache aligned so this is only a sanity check
    if (frame_list) {
        if (!esp_dma_is_buffer_alignment_satisfied(frame_list, actual_size, dma_mem_info)) {
            // This should never happen
            heap_caps_free(frame_list);
            frame_list = NULL;
        }
    }
    return frame_list;
}

void *transfer_descriptor_list_alloc(size_t list_len, size_t *list_len_bytes_out)
{
#if SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE
    // Required Transfer Descriptor List size (in bytes) might not be aligned to cache line size, align the size up
    size_t data_cache_line_size = 0;
    esp_cache_get_alignment(MALLOC_CAP_DMA, &data_cache_line_size);
    const size_t required_list_len_bytes = list_len * sizeof(usb_dwc_ll_dma_qtd_t);
    *list_len_bytes_out = ALIGN_UP_BY(required_list_len_bytes, data_cache_line_size);
#else
    *list_len_bytes_out = list_len * sizeof(usb_dwc_ll_dma_qtd_t);
#endif // SOC_CACHE_INTERNAL_MEM_VIA_L1CACHE

    esp_err_t ret;
    void *qtd_list = NULL;
    size_t actual_size = 0;
    esp_dma_mem_info_t dma_mem_info = {
        .dma_alignment_bytes = USB_DWC_QTD_LIST_MEM_ALIGN,
    };
    ret = esp_dma_capable_calloc(*list_len_bytes_out, 1, &dma_mem_info, &qtd_list, &actual_size);
    assert(ret == ESP_OK);

    if (qtd_list) {
        if (!esp_dma_is_buffer_alignment_satisfied(qtd_list, actual_size, dma_mem_info)) {
            // This should never happen
            heap_caps_free(qtd_list);
            qtd_list = NULL;
        }
    }
    return qtd_list;
}

// ----------------------- Public --------------------------

esp_err_t hcd_install(const hcd_config_t *config)
{
    HCD_ENTER_CRITICAL();
    HCD_CHECK_FROM_CRIT(s_hcd_obj == NULL, ESP_ERR_INVALID_STATE);
    HCD_EXIT_CRITICAL();

    esp_err_t err_ret;
    // Allocate memory for the driver object
    hcd_obj_t *p_hcd_obj_dmy = calloc(1, sizeof(hcd_obj_t));
    if (p_hcd_obj_dmy == NULL) {
        return ESP_ERR_NO_MEM;
    }
    // Allocate each port object (the hardware currently only has one port)
    p_hcd_obj_dmy->port_obj = port_obj_alloc();
    if (p_hcd_obj_dmy->port_obj == NULL) {
        err_ret = ESP_ERR_NO_MEM;
        goto port_alloc_err;
    }
    // Allocate interrupt
    err_ret = esp_intr_alloc(USB_INTR,
                             config->intr_flags | ESP_INTR_FLAG_INTRDISABLED,  // The interrupt must be disabled until the port is initialized
                             intr_hdlr_main,
                             (void *)p_hcd_obj_dmy->port_obj,
                             &p_hcd_obj_dmy->isr_hdl);
    if (err_ret != ESP_OK) {
        goto intr_alloc_err;
    }
    HCD_ENTER_CRITICAL();
    if (s_hcd_obj != NULL) {
        HCD_EXIT_CRITICAL();
        err_ret = ESP_ERR_INVALID_STATE;
        goto assign_err;
    }
    s_hcd_obj = p_hcd_obj_dmy;
    HCD_EXIT_CRITICAL();
    return ESP_OK;

assign_err:
    esp_intr_free(p_hcd_obj_dmy->isr_hdl);
intr_alloc_err:
    port_obj_free(p_hcd_obj_dmy->port_obj);
port_alloc_err:
    free(p_hcd_obj_dmy);
    return err_ret;
}

esp_err_t hcd_uninstall(void)
{
    HCD_ENTER_CRITICAL();
    // Check that all ports have been disabled (there's only one port)
    if (s_hcd_obj == NULL || s_hcd_obj->port_obj->initialized) {
        HCD_EXIT_CRITICAL();
        return ESP_ERR_INVALID_STATE;
    }
    hcd_obj_t *p_hcd_obj_dmy = s_hcd_obj;
    s_hcd_obj = NULL;
    HCD_EXIT_CRITICAL();

    // Free resources
    port_obj_free(p_hcd_obj_dmy->port_obj);
    esp_intr_free(p_hcd_obj_dmy->isr_hdl);
    free(p_hcd_obj_dmy);
    return ESP_OK;
}

// ------------------------------------------------------ Port ---------------------------------------------------------

// ----------------------- Helpers -------------------------

static bool _port_check_all_pipes_halted(port_t *port)
{
    bool all_halted = true;
    pipe_t *pipe;
    TAILQ_FOREACH(pipe, &port->pipes_active_tailq, tailq_entry) {
        if (pipe->state != HCD_PIPE_STATE_HALTED) {
            all_halted = false;
            break;
        }
    }
    TAILQ_FOREACH(pipe, &port->pipes_idle_tailq, tailq_entry) {
        if (pipe->state != HCD_PIPE_STATE_HALTED) {
            all_halted = false;
            break;
        }
    }
    return all_halted;
}

static bool _port_debounce(port_t *port)
{
    if (port->state == HCD_PORT_STATE_NOT_POWERED) {
        // Disconnect event due to power off, no need to debounce or update port state.
        return false;
    }
    HCD_EXIT_CRITICAL();
    vTaskDelay(pdMS_TO_TICKS(DEBOUNCE_DELAY_MS));
    HCD_ENTER_CRITICAL();
    // Check the post-debounce state of the bus (i.e., whether it's actually connected/disconnected)
    bool is_connected = usb_dwc_hal_port_check_if_connected(port->hal);
    if (is_connected) {
        port->state = HCD_PORT_STATE_DISABLED;
    } else {
        port->state = HCD_PORT_STATE_DISCONNECTED;
    }
    // Disable debounce lock
    usb_dwc_hal_disable_debounce_lock(port->hal);
    return is_connected;
}

// ---------------------- Commands -------------------------

static esp_err_t _port_cmd_power_on(port_t *port)
{
    esp_err_t ret;
    // Port can only be powered on if it's currently unpowered
    if (port->state == HCD_PORT_STATE_NOT_POWERED) {
        port->state = HCD_PORT_STATE_DISCONNECTED;
        usb_dwc_hal_port_init(port->hal);
        usb_dwc_hal_port_toggle_power(port->hal, true);
        ret = ESP_OK;
    } else {
        ret = ESP_ERR_INVALID_STATE;
    }
    return ret;
}

static esp_err_t _port_cmd_power_off(port_t *port)
{
    esp_err_t ret;
    // Port can only be unpowered if already powered
    if (port->state != HCD_PORT_STATE_NOT_POWERED) {
        port->state = HCD_PORT_STATE_NOT_POWERED;
        usb_dwc_hal_port_deinit(port->hal);
        usb_dwc_hal_port_toggle_power(port->hal, false);
        // If a device is currently connected, this should trigger a disconnect event
        ret = ESP_OK;
    } else {
        ret = ESP_ERR_INVALID_STATE;
    }
    return ret;
}

static esp_err_t _port_cmd_reset(port_t *port)
{
    esp_err_t ret;

    // Port can only a reset when it is in the enabled or disabled (in the case of a new connection)states.
    if (port->state != HCD_PORT_STATE_ENABLED && port->state != HCD_PORT_STATE_DISABLED) {
        ret = ESP_ERR_INVALID_STATE;
        goto exit;
    }
    // Port can only be reset if all pipes are idle
    if (port->num_pipes_queued > 0) {
        ret = ESP_ERR_INVALID_STATE;
        goto exit;
    }
    /*
    Proceed to resetting the bus
    - Update the port's state variable
    - Hold the bus in the reset state for RESET_HOLD_MS.
    - Return the bus to the idle state for RESET_RECOVERY_MS
    */
    port->state = HCD_PORT_STATE_RESETTING;

    // Place the bus into the reset state. If the port was previously enabled, a disabled event will occur after this
    usb_dwc_hal_port_toggle_reset(port->hal, true);
    HCD_EXIT_CRITICAL();
    vTaskDelay(pdMS_TO_TICKS(RESET_HOLD_MS));
    HCD_ENTER_CRITICAL();
    if (port->state != HCD_PORT_STATE_RESETTING) {
        // The port state has unexpectedly changed
        ret = ESP_ERR_INVALID_RESPONSE;
        goto bailout;
    }

    // Return the bus to the idle state. Port enabled event should occur
    usb_dwc_hal_port_toggle_reset(port->hal, false);
    HCD_EXIT_CRITICAL();
    vTaskDelay(pdMS_TO_TICKS(RESET_RECOVERY_MS));
    HCD_ENTER_CRITICAL();
    if (port->state != HCD_PORT_STATE_ENABLED || !port->flags.conn_dev_ena) {
        // The port state has unexpectedly changed
        ret = ESP_ERR_INVALID_RESPONSE;
        goto bailout;
    }

    // Reinitialize port registers.
    usb_dwc_hal_set_fifo_bias(port->hal, port->fifo_bias);  // Set FIFO biases
    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

    ret = ESP_OK;
bailout:
    // Reinitialize channel registers
    pipe_t *pipe;
    TAILQ_FOREACH(pipe, &port->pipes_idle_tailq, tailq_entry) {
        usb_dwc_hal_chan_set_ep_char(port->hal, pipe->chan_obj, &pipe->ep_char);
    }
    CACHE_SYNC_FRAME_LIST(port->frame_list);
exit:
    return ret;
}

static esp_err_t _port_cmd_bus_suspend(port_t *port)
{
    esp_err_t ret;
    // Port must have been previously enabled, and all pipes must already be halted
    if (port->state == HCD_PORT_STATE_ENABLED && !_port_check_all_pipes_halted(port)) {
        ret = ESP_ERR_INVALID_STATE;
        goto exit;
    }
    // All pipes are guaranteed halted at this point. Proceed to suspend the port
    usb_dwc_hal_port_suspend(port->hal);
    port->state = HCD_PORT_STATE_SUSPENDED;
    ret = ESP_OK;
exit:
    return ret;
}

static esp_err_t _port_cmd_bus_resume(port_t *port)
{
    esp_err_t ret;
    // Port can only be resumed if it was previously suspended
    if (port->state != HCD_PORT_STATE_SUSPENDED) {
        ret = ESP_ERR_INVALID_STATE;
        goto exit;
    }
    // Put and hold the bus in the K state.
    usb_dwc_hal_port_toggle_resume(port->hal, true);
    port->state = HCD_PORT_STATE_RESUMING;
    HCD_EXIT_CRITICAL();
    vTaskDelay(pdMS_TO_TICKS(RESUME_HOLD_MS));
    HCD_ENTER_CRITICAL();
    // Return and hold the bus to the J state (as port of the LS EOP)
    usb_dwc_hal_port_toggle_resume(port->hal, false);
    if (port->state != HCD_PORT_STATE_RESUMING || !port->flags.conn_dev_ena) {
        // Port state unexpectedly changed
        ret = ESP_ERR_INVALID_RESPONSE;
        goto exit;
    }
    HCD_EXIT_CRITICAL();
    vTaskDelay(pdMS_TO_TICKS(RESUME_RECOVERY_MS));
    HCD_ENTER_CRITICAL();
    if (port->state != HCD_PORT_STATE_RESUMING || !port->flags.conn_dev_ena) {
        // Port state unexpectedly changed
        ret = ESP_ERR_INVALID_RESPONSE;
        goto exit;
    }
    port->state = HCD_PORT_STATE_ENABLED;
    ret = ESP_OK;
exit:
    return ret;
}

static esp_err_t _port_cmd_disable(port_t *port)
{
    esp_err_t ret;
    if (port->state != HCD_PORT_STATE_ENABLED && port->state != HCD_PORT_STATE_SUSPENDED) {
        ret = ESP_ERR_INVALID_STATE;
        goto exit;
    }
    // All pipes must be halted before disabling the port
    if (!_port_check_all_pipes_halted(port)) {
        ret = ESP_ERR_INVALID_STATE;
        goto exit;
    }
    // All pipes are guaranteed to be halted or freed at this point. Proceed to disable the port
    port->flags.disable_requested = 1;
    usb_dwc_hal_port_disable(port->hal);
    _internal_port_event_wait(port);
    if (port->state != HCD_PORT_STATE_DISABLED) {
        // Port state unexpectedly changed
        ret = ESP_ERR_INVALID_RESPONSE;
        goto exit;
    }
    ret = ESP_OK;
exit:
    return ret;
}

// ----------------------- Public --------------------------

esp_err_t hcd_port_init(int port_number, const hcd_port_config_t *port_config, hcd_port_handle_t *port_hdl)
{
    HCD_CHECK(port_number > 0 && port_config != NULL && port_hdl != NULL, ESP_ERR_INVALID_ARG);
    HCD_CHECK(port_number <= NUM_PORTS, ESP_ERR_NOT_FOUND);

    HCD_ENTER_CRITICAL();
    HCD_CHECK_FROM_CRIT(s_hcd_obj != NULL && !s_hcd_obj->port_obj->initialized, ESP_ERR_INVALID_STATE);
    // Port object memory and resources (such as the mutex) already be allocated. Just need to initialize necessary fields only
    port_t *port_obj = s_hcd_obj->port_obj;
    TAILQ_INIT(&port_obj->pipes_idle_tailq);
    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;
    usb_dwc_hal_init(port_obj->hal);
    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));
    esp_intr_enable(s_hcd_obj->isr_hdl);
    *port_hdl = (hcd_port_handle_t)port_obj;
    HCD_EXIT_CRITICAL();

    vTaskDelay(pdMS_TO_TICKS(INIT_DELAY_MS));    // Need a short delay before host mode takes effect
    return ESP_OK;
}

esp_err_t hcd_port_deinit(hcd_port_handle_t port_hdl)
{
    port_t *port = (port_t *)port_hdl;

    HCD_ENTER_CRITICAL();
    HCD_CHECK_FROM_CRIT(s_hcd_obj != NULL && port->initialized
                        && port->num_pipes_idle == 0 && port->num_pipes_queued == 0
                        && (port->state == HCD_PORT_STATE_NOT_POWERED || port->state == HCD_PORT_STATE_RECOVERY)
                        && port->task_waiting_port_notif == NULL,
                        ESP_ERR_INVALID_STATE);
    port->initialized = false;
    esp_intr_disable(s_hcd_obj->isr_hdl);
    usb_dwc_hal_deinit(port->hal);
    HCD_EXIT_CRITICAL();

    return ESP_OK;
}

esp_err_t hcd_port_command(hcd_port_handle_t port_hdl, hcd_port_cmd_t command)
{
    esp_err_t ret = ESP_ERR_INVALID_STATE;
    port_t *port = (port_t *)port_hdl;
    xSemaphoreTake(port->port_mux, portMAX_DELAY);
    HCD_ENTER_CRITICAL();
    if (port->initialized && !port->flags.event_pending) { // Port events need to be handled first before issuing a command
        port->flags.cmd_processing = 1;
        switch (command) {
        case HCD_PORT_CMD_POWER_ON: {
            ret = _port_cmd_power_on(port);
            break;
        }
        case HCD_PORT_CMD_POWER_OFF: {
            ret = _port_cmd_power_off(port);
            break;
        }
        case HCD_PORT_CMD_RESET: {
            ret = _port_cmd_reset(port);
            break;
        }
        case HCD_PORT_CMD_SUSPEND: {
            ret = _port_cmd_bus_suspend(port);
            break;
        }
        case HCD_PORT_CMD_RESUME: {
            ret = _port_cmd_bus_resume(port);
            break;
        }
        case HCD_PORT_CMD_DISABLE: {
            ret = _port_cmd_disable(port);
            break;
        }
        }
        port->flags.cmd_processing = 0;
    }
    HCD_EXIT_CRITICAL();
    xSemaphoreGive(port->port_mux);
    return ret;
}

hcd_port_state_t hcd_port_get_state(hcd_port_handle_t port_hdl)
{
    port_t *port = (port_t *)port_hdl;
    hcd_port_state_t ret;
    HCD_ENTER_CRITICAL();
    ret = port->state;
    HCD_EXIT_CRITICAL();
    return ret;
}

esp_err_t hcd_port_get_speed(hcd_port_handle_t port_hdl, usb_speed_t *speed)
{
    port_t *port = (port_t *)port_hdl;
    HCD_CHECK(speed != NULL, ESP_ERR_INVALID_ARG);
    HCD_ENTER_CRITICAL();
    // Device speed is only valid if there is device connected to the port that has been reset
    HCD_CHECK_FROM_CRIT(port->flags.conn_dev_ena, ESP_ERR_INVALID_STATE);
    *speed = get_usb_port_speed(usb_dwc_hal_port_get_conn_speed(port->hal));
    HCD_EXIT_CRITICAL();
    return ESP_OK;
}

hcd_port_event_t hcd_port_handle_event(hcd_port_handle_t port_hdl)
{
    port_t *port = (port_t *)port_hdl;
    hcd_port_event_t ret = HCD_PORT_EVENT_NONE;
    xSemaphoreTake(port->port_mux, portMAX_DELAY);
    HCD_ENTER_CRITICAL();
    if (port->initialized && port->flags.event_pending) {
        port->flags.event_pending = 0;
        port->flags.event_processing = 1;
        ret = port->last_event;
        switch (ret) {
        case HCD_PORT_EVENT_CONNECTION: {
            if (_port_debounce(port)) {
                ret = HCD_PORT_EVENT_CONNECTION;
            }
            break;
        }
        case HCD_PORT_EVENT_DISCONNECTION:
        case HCD_PORT_EVENT_ERROR:
        case HCD_PORT_EVENT_OVERCURRENT: {
            break;
        }
        default: {
            break;
        }
        }
        port->flags.event_processing = 0;
    } else {
        ret = HCD_PORT_EVENT_NONE;
    }
    HCD_EXIT_CRITICAL();
    xSemaphoreGive(port->port_mux);
    return ret;
}

esp_err_t hcd_port_recover(hcd_port_handle_t port_hdl)
{
    port_t *port = (port_t *)port_hdl;
    HCD_ENTER_CRITICAL();
    HCD_CHECK_FROM_CRIT(s_hcd_obj != NULL && port->initialized && port->state == HCD_PORT_STATE_RECOVERY
                        && port->num_pipes_idle == 0 && port->num_pipes_queued == 0
                        && port->flags.val == 0 && port->task_waiting_port_notif == NULL,
                        ESP_ERR_INVALID_STATE);
    // We are about to do a soft reset on the peripheral. Disable the peripheral throughout
    esp_intr_disable(s_hcd_obj->isr_hdl);
    usb_dwc_hal_core_soft_reset(port->hal);
    port->state = HCD_PORT_STATE_NOT_POWERED;
    port->last_event = HCD_PORT_EVENT_NONE;
    port->flags.val = 0;
    // Soft reset wipes all registers so we need to reinitialize the HAL
    usb_dwc_hal_init(port->hal);
    // Clear the frame list. We set the frame list register and enable periodic scheduling after a successful reset
    memset(port->frame_list, 0, FRAME_LIST_LEN * sizeof(uint32_t));
    esp_intr_enable(s_hcd_obj->isr_hdl);
    HCD_EXIT_CRITICAL();
    return ESP_OK;
}

void *hcd_port_get_context(hcd_port_handle_t port_hdl)
{
    port_t *port = (port_t *)port_hdl;
    void *ret;
    HCD_ENTER_CRITICAL();
    ret = port->context;
    HCD_EXIT_CRITICAL();
    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 -------------------------

static inline hcd_pipe_event_t pipe_decode_error_event(usb_dwc_hal_chan_error_t chan_error)
{
    hcd_pipe_event_t event = HCD_PIPE_EVENT_NONE;
    switch (chan_error) {
    case USB_DWC_HAL_CHAN_ERROR_XCS_XACT:
        event = HCD_PIPE_EVENT_ERROR_XFER;
        break;
    case USB_DWC_HAL_CHAN_ERROR_BNA:
        event = HCD_PIPE_EVENT_ERROR_URB_NOT_AVAIL;
        break;
    case USB_DWC_HAL_CHAN_ERROR_PKT_BBL:
        event = HCD_PIPE_EVENT_ERROR_OVERFLOW;
        break;
    case USB_DWC_HAL_CHAN_ERROR_STALL:
        event = HCD_PIPE_EVENT_ERROR_STALL;
        break;
    }
    return event;
}

static dma_buffer_block_t *buffer_block_alloc(usb_transfer_type_t type)
{
    int desc_list_len;
    switch (type) {
    case USB_TRANSFER_TYPE_CTRL:
        desc_list_len = XFER_LIST_LEN_CTRL;
        break;
    case USB_TRANSFER_TYPE_ISOCHRONOUS:
        desc_list_len = XFER_LIST_LEN_ISOC;
        break;
    case USB_TRANSFER_TYPE_BULK:
        desc_list_len = XFER_LIST_LEN_BULK;
        break;
    default:    // USB_TRANSFER_TYPE_INTR:
        desc_list_len = XFER_LIST_LEN_INTR;
        break;
    }
    dma_buffer_block_t *buffer = calloc(1, sizeof(dma_buffer_block_t));
    size_t real_len = 0;
    void *xfer_desc_list = transfer_descriptor_list_alloc(desc_list_len, &real_len);
    if (buffer == NULL || xfer_desc_list == NULL) {
        free(buffer);
        heap_caps_free(xfer_desc_list);
        return NULL;
    }
    buffer->xfer_desc_list = xfer_desc_list;
    buffer->xfer_desc_list_len_bytes = real_len;
    return buffer;
}

static void buffer_block_free(dma_buffer_block_t *buffer)
{
    if (buffer == NULL) {
        return;
    }
    heap_caps_free(buffer->xfer_desc_list);
    free(buffer);
}

static bool pipe_args_usb_compliance_verification(const hcd_pipe_config_t *pipe_config, usb_speed_t port_speed, usb_transfer_type_t type)
{
    // Check if pipe can be supported
    if (port_speed == USB_SPEED_LOW && pipe_config->dev_speed == USB_SPEED_FULL) {
        ESP_LOGE(HCD_DWC_TAG, "Low speed port does not support full speed pipe");
        return false;
    }

    if (pipe_config->dev_speed == USB_SPEED_LOW && (type == USB_TRANSFER_TYPE_BULK || type == USB_TRANSFER_TYPE_ISOCHRONOUS)) {
        ESP_LOGE(HCD_DWC_TAG, "Low speed does not support Bulk or Isochronous pipes");
        return false;
    }

    return true;
}

static bool pipe_alloc_hcd_support_verification(usb_dwc_hal_context_t *hal, const usb_ep_desc_t * ep_desc)
{
    assert(hal != NULL);
    assert(ep_desc != NULL);

    usb_hal_fifo_mps_limits_t mps_limits = {0};
    usb_dwc_hal_get_mps_limits(hal, &mps_limits);
    const usb_transfer_type_t type = USB_EP_DESC_GET_XFERTYPE(ep_desc);

    // Check the pipe's interval is not zero
    if ((type == USB_TRANSFER_TYPE_INTR || type == USB_TRANSFER_TYPE_ISOCHRONOUS) &&
            (ep_desc->bInterval == 0)) {
        ESP_LOGE(HCD_DWC_TAG, "bInterval value (%d) invalid for pipe type INTR/ISOC",
                 ep_desc->bInterval);
        return false;
    }

    // Check if pipe MPS exceeds HCD MPS limits (due to DWC FIFO sizing)
    int limit;
    if (USB_EP_DESC_GET_EP_DIR(ep_desc)) { // IN
        limit = mps_limits.in_mps;
    } else {    // OUT
        if (type == USB_TRANSFER_TYPE_CTRL || type == USB_TRANSFER_TYPE_BULK) {
            limit = mps_limits.non_periodic_out_mps;
        } else {
            limit = mps_limits.periodic_out_mps;
        }
    }

    if (USB_EP_DESC_GET_MPS(ep_desc) > limit) {
        ESP_LOGE(HCD_DWC_TAG, "EP MPS (%d) exceeds supported limit (%d)",
                 USB_EP_DESC_GET_MPS(ep_desc),
                 limit);
        return false;
    }

    return true;
}

static void pipe_set_ep_char(const hcd_pipe_config_t *pipe_config, usb_transfer_type_t type, bool is_default_pipe, int pipe_idx, usb_speed_t port_speed, usb_dwc_hal_ep_char_t *ep_char)
{
    // Initialize EP characteristics
    usb_dwc_xfer_type_t hal_xfer_type;
    switch (type) {
    case USB_TRANSFER_TYPE_CTRL:
        hal_xfer_type = USB_DWC_XFER_TYPE_CTRL;
        break;
    case USB_TRANSFER_TYPE_ISOCHRONOUS:
        hal_xfer_type = USB_DWC_XFER_TYPE_ISOCHRONOUS;
        break;
    case USB_TRANSFER_TYPE_BULK:
        hal_xfer_type = USB_DWC_XFER_TYPE_BULK;
        break;
    default:    // USB_TRANSFER_TYPE_INTR
        hal_xfer_type = USB_DWC_XFER_TYPE_INTR;
        break;
    }
    ep_char->type = hal_xfer_type;
    if (is_default_pipe) {
        ep_char->bEndpointAddress = 0;
        // Set the default pipe's MPS to the worst case MPS for the device's speed
        ep_char->mps = (pipe_config->dev_speed == USB_SPEED_LOW) ? CTRL_EP_MAX_MPS_LS : CTRL_EP_MAX_MPS_HSFS;
    } else {
        ep_char->bEndpointAddress = pipe_config->ep_desc->bEndpointAddress;
        ep_char->mps = USB_EP_DESC_GET_MPS(pipe_config->ep_desc);
    }
    ep_char->dev_addr = pipe_config->dev_addr;
    ep_char->ls_via_fs_hub = (port_speed == USB_SPEED_FULL && pipe_config->dev_speed == USB_SPEED_LOW);
    // Calculate the pipe's interval in terms of USB frames
    // @see USB-OTG programming guide chapter 6.5 for more information
    if (type == USB_TRANSFER_TYPE_INTR || type == USB_TRANSFER_TYPE_ISOCHRONOUS) {
        // Convert bInterval field to real value
        // @see USB 2.0 specs, Table 9-13
        unsigned int interval_value;
        if (type == USB_TRANSFER_TYPE_INTR && pipe_config->dev_speed != USB_SPEED_HIGH) {
            interval_value = pipe_config->ep_desc->bInterval;
        } else {
            interval_value = (1 << (pipe_config->ep_desc->bInterval - 1));
        }
        ep_char->periodic.interval = interval_value;
        // We are the Nth pipe to be allocated. Use N as a phase offset
        unsigned int xfer_list_len = (type == USB_TRANSFER_TYPE_INTR) ? XFER_LIST_LEN_INTR : XFER_LIST_LEN_ISOC;
        ep_char->periodic.offset = (pipe_idx % xfer_list_len) % interval_value;
        ep_char->periodic.is_hs = (pipe_config->dev_speed == USB_SPEED_HIGH);
    } else {
        ep_char->periodic.interval = 0;
        ep_char->periodic.offset = 0;
    }
}

// ---------------------- Commands -------------------------

static esp_err_t _pipe_cmd_halt(pipe_t *pipe)
{
    esp_err_t ret;

    // If pipe is already halted, just return.
    if (pipe->state == HCD_PIPE_STATE_HALTED) {
        ret = ESP_OK;
        goto exit;
    }
    // If the pipe's port is invalid, we just mark the pipe as halted without needing to halt the underlying channel
    if (pipe->port->flags.conn_dev_ena // Skip halting the underlying channel if the port is invalid
            && !usb_dwc_hal_chan_request_halt(pipe->chan_obj)) {   // Check if the channel is already halted
        // Channel is not halted, we need to request and wait for a haltWe need to wait for channel to be halted.
        pipe->cs_flags.waiting_halt = 1;
        _internal_pipe_event_wait(pipe);
        // State should have been updated in the ISR
        assert(pipe->state == HCD_PIPE_STATE_HALTED);
    } else {
        // We are already halted, just need to update the state
        usb_dwc_hal_chan_mark_halted(pipe->chan_obj);
        pipe->state = HCD_PIPE_STATE_HALTED;
    }
    ret = ESP_OK;
exit:
    return ret;
}

static esp_err_t _pipe_cmd_flush(pipe_t *pipe)
{
    esp_err_t ret;
    // The pipe must be halted in order to be flushed
    if (pipe->state != HCD_PIPE_STATE_HALTED) {
        ret = ESP_ERR_INVALID_STATE;
        goto exit;
    }
    // If the port is still valid, we are canceling transfers. Otherwise, we are flushing due to a port error
    bool canceled = pipe->port->flags.conn_dev_ena;
    bool call_pipe_cb;
    // Flush any filled buffers
    call_pipe_cb = _buffer_flush_all(pipe, canceled);
    // Move all URBs from the pending tailq to the done tailq
    if (pipe->num_urb_pending > 0) {
        // Process all remaining pending URBs
        urb_t *urb;
        TAILQ_FOREACH(urb, &pipe->pending_urb_tailq, tailq_entry) {
            // Update the URB's current state
            urb->hcd_var = URB_HCD_STATE_DONE;
            // URBs were never executed, Update the actual_num_bytes and status
            urb->transfer.actual_num_bytes = 0;
            urb->transfer.status = (canceled) ? USB_TRANSFER_STATUS_CANCELED : USB_TRANSFER_STATUS_NO_DEVICE;
            if (pipe->ep_char.type == USB_DWC_XFER_TYPE_ISOCHRONOUS) {
                // Update the URB's isoc packet descriptors as well
                for (int pkt_idx = 0; pkt_idx < urb->transfer.num_isoc_packets; pkt_idx++) {
                    urb->transfer.isoc_packet_desc[pkt_idx].actual_num_bytes = 0;
                    urb->transfer.isoc_packet_desc[pkt_idx].status = (canceled) ? USB_TRANSFER_STATUS_CANCELED : USB_TRANSFER_STATUS_NO_DEVICE;
                }
            }
        }
        // Concatenated pending tailq to the done tailq
        TAILQ_CONCAT(&pipe->done_urb_tailq, &pipe->pending_urb_tailq, tailq_entry);
        pipe->num_urb_done += pipe->num_urb_pending;
        pipe->num_urb_pending = 0;
        call_pipe_cb = true;
    }
    if (call_pipe_cb) {
        // One or more URBs can be dequeued as a result of the flush. We need to call the callback
        HCD_EXIT_CRITICAL();
        pipe->callback((hcd_pipe_handle_t)pipe, HCD_PIPE_EVENT_URB_DONE, pipe->callback_arg, false);
        HCD_ENTER_CRITICAL();
    }
    ret = ESP_OK;
exit:
    return ret;
}

static esp_err_t _pipe_cmd_clear(pipe_t *pipe)
{
    esp_err_t ret;
    // Pipe must be in the halted state in order to be made active, and there must be an enabled device on the port
    if (pipe->state != HCD_PIPE_STATE_HALTED || !pipe->port->flags.conn_dev_ena) {
        ret = ESP_ERR_INVALID_STATE;
        goto exit;
    }
    // Update the pipe's state
    pipe->state = HCD_PIPE_STATE_ACTIVE;
    if (pipe->num_urb_pending > 0) {
        // Fill as many buffers as possible
        while (_buffer_can_fill(pipe)) {
            _buffer_fill(pipe);
        }
    }
    // Execute any filled buffers
    if (_buffer_can_exec(pipe)) {
        _buffer_exec(pipe);
    }
    ret = ESP_OK;
exit:
    return ret;
}

// ----------------------- Public --------------------------

esp_err_t hcd_pipe_alloc(hcd_port_handle_t port_hdl, const hcd_pipe_config_t *pipe_config, hcd_pipe_handle_t *pipe_hdl)
{
    HCD_CHECK(port_hdl != NULL && pipe_config != NULL && pipe_hdl != NULL, ESP_ERR_INVALID_ARG);
    port_t *port = (port_t *)port_hdl;
    HCD_ENTER_CRITICAL();
    // Can only allocate a pipe if the target port is initialized and connected to an enabled device
    HCD_CHECK_FROM_CRIT(port->initialized && port->flags.conn_dev_ena, ESP_ERR_INVALID_STATE);
    usb_speed_t port_speed = port->speed;
    int pipe_idx = port->num_pipes_idle + port->num_pipes_queued;
    HCD_EXIT_CRITICAL();

    usb_transfer_type_t type;
    bool is_default;
    if (pipe_config->ep_desc == NULL) {
        // Default CTRL pipe allocation
        type = USB_TRANSFER_TYPE_CTRL;
        is_default = true;
    } else {
        type = USB_EP_DESC_GET_XFERTYPE(pipe_config->ep_desc);
        is_default = false;
    }

    esp_err_t ret;
    // Check if pipe configuration can be supported
    if (!pipe_args_usb_compliance_verification(pipe_config, port_speed, type)) {
        return ESP_ERR_NOT_SUPPORTED;
    }
    // Default pipes have a NULL ep_desc thus should skip the HCD support verification
    if (!is_default && !pipe_alloc_hcd_support_verification(port->hal, pipe_config->ep_desc)) {
        return ESP_ERR_NOT_SUPPORTED;
    }
    // Allocate the pipe resources
    pipe_t *pipe = calloc(1, sizeof(pipe_t));
    usb_dwc_hal_chan_t *chan_obj = calloc(1, sizeof(usb_dwc_hal_chan_t));
    dma_buffer_block_t *buffers[NUM_BUFFERS] = {0};
    if (pipe == NULL || chan_obj == NULL) {
        ret = ESP_ERR_NO_MEM;
        goto err;
    }
    for (int i = 0; i < NUM_BUFFERS; i++) {
        buffers[i] = buffer_block_alloc(type);
        if (buffers[i] == NULL) {
            ret = ESP_ERR_NO_MEM;
            goto err;
        }
    }

    // Initialize pipe object
    TAILQ_INIT(&pipe->pending_urb_tailq);
    TAILQ_INIT(&pipe->done_urb_tailq);
    for (int i = 0; i < NUM_BUFFERS; i++) {
        pipe->buffers[i] = buffers[i];
    }
    pipe->multi_buffer_control.buffer_num_to_fill = NUM_BUFFERS;
    pipe->port = port;
    pipe->chan_obj = chan_obj;
    usb_dwc_hal_ep_char_t ep_char;
    pipe_set_ep_char(pipe_config, type, is_default, pipe_idx, port_speed, &ep_char);
    memcpy(&pipe->ep_char, &ep_char, sizeof(usb_dwc_hal_ep_char_t));
    pipe->state = HCD_PIPE_STATE_ACTIVE;
    pipe->callback = pipe_config->callback;
    pipe->callback_arg = pipe_config->callback_arg;
    pipe->context = pipe_config->context;

    // Allocate channel
    HCD_ENTER_CRITICAL();
    if (!port->initialized || !port->flags.conn_dev_ena) {
        HCD_EXIT_CRITICAL();
        ret = ESP_ERR_INVALID_STATE;
        goto err;
    }
    bool chan_allocated = usb_dwc_hal_chan_alloc(port->hal, pipe->chan_obj, (void *) pipe);
    if (!chan_allocated) {
        HCD_EXIT_CRITICAL();
        ret = ESP_ERR_NOT_SUPPORTED;
        goto err;
    }
    usb_dwc_hal_chan_set_ep_char(port->hal, pipe->chan_obj, &pipe->ep_char);
    CACHE_SYNC_FRAME_LIST(port->frame_list);
    // Add the pipe to the list of idle pipes in the port object
    TAILQ_INSERT_TAIL(&port->pipes_idle_tailq, pipe, tailq_entry);
    port->num_pipes_idle++;
    HCD_EXIT_CRITICAL();

    *pipe_hdl = (hcd_pipe_handle_t)pipe;
    return ESP_OK;

err:
    for (int i = 0; i < NUM_BUFFERS; i++) {
        buffer_block_free(buffers[i]);
    }
    free(chan_obj);
    free(pipe);
    return ret;
}

int hcd_pipe_get_mps(hcd_pipe_handle_t pipe_hdl)
{
    pipe_t *pipe = (pipe_t *)pipe_hdl;
    int mps;
    HCD_ENTER_CRITICAL();
    mps = pipe->ep_char.mps;
    HCD_EXIT_CRITICAL();
    return mps;
}

esp_err_t hcd_pipe_free(hcd_pipe_handle_t pipe_hdl)
{
    pipe_t *pipe = (pipe_t *)pipe_hdl;
    HCD_ENTER_CRITICAL();
    // Check that all URBs have been removed and pipe has no pending events
    HCD_CHECK_FROM_CRIT(!pipe->multi_buffer_control.buffer_is_executing
                        && !pipe->cs_flags.has_urb,
                        ESP_ERR_INVALID_STATE);
    // Remove pipe from the list of idle pipes (it must be in the idle list because it should have no queued URBs)
    TAILQ_REMOVE(&pipe->port->pipes_idle_tailq, pipe, tailq_entry);
    pipe->port->num_pipes_idle--;
    usb_dwc_hal_chan_free(pipe->port->hal, pipe->chan_obj);
    HCD_EXIT_CRITICAL();

    // Free pipe resources
    for (int i = 0; i < NUM_BUFFERS; i++) {
        buffer_block_free(pipe->buffers[i]);
    }
    free(pipe->chan_obj);
    free(pipe);
    return ESP_OK;
}

esp_err_t hcd_pipe_update_mps(hcd_pipe_handle_t pipe_hdl, int mps)
{
    pipe_t *pipe = (pipe_t *)pipe_hdl;
    HCD_ENTER_CRITICAL();
    // Check if pipe is in the correct state to be updated
    HCD_CHECK_FROM_CRIT(!pipe->cs_flags.pipe_cmd_processing &&
                        !pipe->cs_flags.has_urb,
                        ESP_ERR_INVALID_STATE);
    pipe->ep_char.mps = mps;
    // Update the underlying channel's registers
    usb_dwc_hal_chan_set_ep_char(pipe->port->hal, pipe->chan_obj, &pipe->ep_char);
    HCD_EXIT_CRITICAL();
    return ESP_OK;
}

esp_err_t hcd_pipe_update_dev_addr(hcd_pipe_handle_t pipe_hdl, uint8_t dev_addr)
{
    pipe_t *pipe = (pipe_t *)pipe_hdl;
    HCD_ENTER_CRITICAL();
    // Check if pipe is in the correct state to be updated
    HCD_CHECK_FROM_CRIT(!pipe->cs_flags.pipe_cmd_processing &&
                        !pipe->cs_flags.has_urb,
                        ESP_ERR_INVALID_STATE);
    pipe->ep_char.dev_addr = dev_addr;
    // Update the underlying channel's registers
    usb_dwc_hal_chan_set_ep_char(pipe->port->hal, pipe->chan_obj, &pipe->ep_char);
    HCD_EXIT_CRITICAL();
    return ESP_OK;
}

void *hcd_pipe_get_context(hcd_pipe_handle_t pipe_hdl)
{
    pipe_t *pipe = (pipe_t *)pipe_hdl;
    void *ret;
    HCD_ENTER_CRITICAL();
    ret = pipe->context;
    HCD_EXIT_CRITICAL();
    return ret;
}

hcd_pipe_state_t hcd_pipe_get_state(hcd_pipe_handle_t pipe_hdl)
{
    hcd_pipe_state_t ret;
    pipe_t *pipe = (pipe_t *)pipe_hdl;
    HCD_ENTER_CRITICAL();
    ret = pipe->state;
    HCD_EXIT_CRITICAL();
    return ret;
}

unsigned int hcd_pipe_get_num_urbs(hcd_pipe_handle_t pipe_hdl)
{
    unsigned int ret;
    pipe_t *pipe = (pipe_t *)pipe_hdl;
    HCD_ENTER_CRITICAL();
    ret = pipe->num_urb_pending + pipe->num_urb_done;
    HCD_EXIT_CRITICAL();
    return ret;
}

esp_err_t hcd_pipe_command(hcd_pipe_handle_t pipe_hdl, hcd_pipe_cmd_t command)
{
    pipe_t *pipe = (pipe_t *)pipe_hdl;
    esp_err_t ret = ESP_OK;

    HCD_ENTER_CRITICAL();
    pipe->cs_flags.pipe_cmd_processing = 1;
    switch (command) {
    case HCD_PIPE_CMD_HALT: {
        ret = _pipe_cmd_halt(pipe);
        break;
    }
    case HCD_PIPE_CMD_FLUSH: {
        ret = _pipe_cmd_flush(pipe);
        break;
    }
    case HCD_PIPE_CMD_CLEAR: {
        ret = _pipe_cmd_clear(pipe);
        break;
    }
    }
    pipe->cs_flags.pipe_cmd_processing = 0;
    HCD_EXIT_CRITICAL();
    return ret;
}

hcd_pipe_event_t hcd_pipe_get_event(hcd_pipe_handle_t pipe_hdl)
{
    pipe_t *pipe = (pipe_t *)pipe_hdl;
    hcd_pipe_event_t ret;
    HCD_ENTER_CRITICAL();
    ret = pipe->last_event;
    pipe->last_event = HCD_PIPE_EVENT_NONE;
    HCD_EXIT_CRITICAL();
    return ret;
}

// ------------------------------------------------- Buffer Control ----------------------------------------------------

static inline void _buffer_fill_ctrl(dma_buffer_block_t *buffer, usb_transfer_t *transfer)
{
    // Get information about the control transfer by analyzing the setup packet (the first 8 bytes of the URB's data)
    usb_setup_packet_t *setup_pkt = (usb_setup_packet_t *)transfer->data_buffer;
    bool data_stg_in = (setup_pkt->bmRequestType & USB_BM_REQUEST_TYPE_DIR_IN);
    bool data_stg_skip = (setup_pkt->wLength == 0);
    // Fill setup stage
    usb_dwc_hal_xfer_desc_fill(buffer->xfer_desc_list, 0, transfer->data_buffer, sizeof(usb_setup_packet_t),
                               USB_DWC_HAL_XFER_DESC_FLAG_SETUP | USB_DWC_HAL_XFER_DESC_FLAG_HOC);
    // Fill data stage
    if (data_stg_skip) {
        // Not data stage. Fill with an empty descriptor
        usb_dwc_hal_xfer_desc_clear(buffer->xfer_desc_list, 1);
    } else {
        // Fill data stage. Note that we still fill with transfer->num_bytes instead of setup_pkt->wLength as it's possible to require more bytes than wLength
        usb_dwc_hal_xfer_desc_fill(buffer->xfer_desc_list, 1, transfer->data_buffer + sizeof(usb_setup_packet_t), transfer->num_bytes - sizeof(usb_setup_packet_t),
                                   ((data_stg_in) ? USB_DWC_HAL_XFER_DESC_FLAG_IN : 0) | USB_DWC_HAL_XFER_DESC_FLAG_HOC);
    }
    // Fill status stage (i.e., a zero length packet). If data stage is skipped, the status stage is always IN.
    usb_dwc_hal_xfer_desc_fill(buffer->xfer_desc_list, 2, NULL, 0,
                               ((data_stg_in && !data_stg_skip) ? 0 : USB_DWC_HAL_XFER_DESC_FLAG_IN) | USB_DWC_HAL_XFER_DESC_FLAG_HOC);
    // Update buffer flags
    buffer->flags.ctrl.data_stg_in = data_stg_in;
    buffer->flags.ctrl.data_stg_skip = data_stg_skip;
    buffer->flags.ctrl.cur_stg = 0;
}

static inline void _buffer_fill_bulk(dma_buffer_block_t *buffer, usb_transfer_t *transfer, bool is_in, int mps)
{
    // Only add a zero length packet if OUT, flag is set, and transfer length is multiple of EP's MPS
    // Minor optimization: Do the mod operation last
    bool zero_len_packet = !is_in && (transfer->flags & USB_TRANSFER_FLAG_ZERO_PACK) && (transfer->num_bytes % mps == 0);
    if (is_in) {
        usb_dwc_hal_xfer_desc_fill(buffer->xfer_desc_list, 0, transfer->data_buffer, transfer->num_bytes,
                                   USB_DWC_HAL_XFER_DESC_FLAG_IN | USB_DWC_HAL_XFER_DESC_FLAG_HOC);
    } else { // OUT
        if (zero_len_packet) {
            // Adding a zero length packet, so two descriptors are used.
            usb_dwc_hal_xfer_desc_fill(buffer->xfer_desc_list, 0, transfer->data_buffer, transfer->num_bytes, 0);
            usb_dwc_hal_xfer_desc_fill(buffer->xfer_desc_list, 1, NULL, 0, USB_DWC_HAL_XFER_DESC_FLAG_HOC);
        } else {
            // Zero length packet not required. One descriptor is enough
            usb_dwc_hal_xfer_desc_fill(buffer->xfer_desc_list, 0, transfer->data_buffer, transfer->num_bytes, USB_DWC_HAL_XFER_DESC_FLAG_HOC);
        }
    }
    // Update buffer flags
    buffer->flags.bulk.zero_len_packet = zero_len_packet;
}

static inline void _buffer_fill_intr(dma_buffer_block_t *buffer, usb_transfer_t *transfer, bool is_in, int mps)
{
    int num_qtds;
    int mod_mps = transfer->num_bytes % mps;
    // Only add a zero length packet if OUT, flag is set, and transfer length is multiple of EP's MPS
    bool zero_len_packet = !is_in && (transfer->flags & USB_TRANSFER_FLAG_ZERO_PACK) && (mod_mps == 0);
    if (is_in) {
        assert(mod_mps == 0);  // IN transfers MUST be integer multiple of MPS
        num_qtds = transfer->num_bytes / mps;   // Can just floor divide as it's already multiple of MPS
    } else {
        num_qtds = transfer->num_bytes / mps;   // Floor division to get the number of MPS sized packets
        if (mod_mps > 0) {
            num_qtds++; // Add a short packet for the remainder
        }
    }
    assert((zero_len_packet) ? num_qtds + 1 : num_qtds <= XFER_LIST_LEN_INTR); // Check that the number of QTDs doesn't exceed the QTD list's length

    uint32_t xfer_desc_flags = (is_in) ? USB_DWC_HAL_XFER_DESC_FLAG_IN : 0;
    int bytes_filled = 0;
    // Fill all but last QTD
    for (int i = 0; i < num_qtds - 1; i++) {
        usb_dwc_hal_xfer_desc_fill(buffer->xfer_desc_list, i, &transfer->data_buffer[bytes_filled], mps, xfer_desc_flags);
        bytes_filled += mps;
    }
    // Fill last QTD and zero length packet
    if (zero_len_packet) {
        // Fill in last data packet without HOC flag
        usb_dwc_hal_xfer_desc_fill(buffer->xfer_desc_list, num_qtds - 1, &transfer->data_buffer[bytes_filled], transfer->num_bytes - bytes_filled,
                                   xfer_desc_flags);
        // HOC flag goes to zero length packet instead
        usb_dwc_hal_xfer_desc_fill(buffer->xfer_desc_list, num_qtds, NULL, 0, USB_DWC_HAL_XFER_DESC_FLAG_HOC);
    } else {
        // Zero length packet not required. Fill in last QTD with HOC flag
        usb_dwc_hal_xfer_desc_fill(buffer->xfer_desc_list, num_qtds - 1, &transfer->data_buffer[bytes_filled], transfer->num_bytes - bytes_filled,
                                   xfer_desc_flags | USB_DWC_HAL_XFER_DESC_FLAG_HOC);
    }

    // Update buffer members and flags
    buffer->flags.intr.num_qtds = num_qtds;
    buffer->flags.intr.zero_len_packet = zero_len_packet;
}

static inline void IRAM_ATTR _buffer_fill_isoc(dma_buffer_block_t *buffer, usb_transfer_t *transfer, bool is_in, int mps, int interval, int start_idx)
{
    assert(interval > 0);
    assert(__builtin_popcount(interval) == 1); // Isochronous interval must be power of 2 according to USB2.0 specification
    int total_num_desc = transfer->num_isoc_packets * interval;
    assert(total_num_desc <= XFER_LIST_LEN_ISOC);
    int desc_idx = start_idx;
    int bytes_filled = 0;
    // Zeroize the whole QTD, so we can focus only on the active descriptors
    memset(buffer->xfer_desc_list, 0, XFER_LIST_LEN_ISOC * sizeof(usb_dwc_ll_dma_qtd_t));
    for (int pkt_idx = 0; pkt_idx < transfer->num_isoc_packets; pkt_idx++) {
        int xfer_len = transfer->isoc_packet_desc[pkt_idx].num_bytes;
        uint32_t flags = (is_in) ? USB_DWC_HAL_XFER_DESC_FLAG_IN : 0;
        if (pkt_idx == transfer->num_isoc_packets - 1) {
            // Last packet, set the the HOC flag
            flags |= USB_DWC_HAL_XFER_DESC_FLAG_HOC;
        }
        usb_dwc_hal_xfer_desc_fill(buffer->xfer_desc_list, desc_idx, &transfer->data_buffer[bytes_filled], xfer_len, flags);
        bytes_filled += xfer_len;
        desc_idx += interval;
        desc_idx %= XFER_LIST_LEN_ISOC;
    }
    // Update buffer members and flags
    buffer->flags.isoc.num_qtds = total_num_desc;
    buffer->flags.isoc.interval = interval;
    buffer->flags.isoc.start_idx = start_idx;
    buffer->flags.isoc.next_start_idx = desc_idx;
}

static void IRAM_ATTR _buffer_fill(pipe_t *pipe)
{
    // Get an URB from the pending tailq
    urb_t *urb = TAILQ_FIRST(&pipe->pending_urb_tailq);
    assert(pipe->num_urb_pending > 0 && urb != NULL);
    TAILQ_REMOVE(&pipe->pending_urb_tailq, urb, tailq_entry);
    pipe->num_urb_pending--;

    // Select the inactive buffer
    assert(pipe->multi_buffer_control.buffer_num_to_exec <= NUM_BUFFERS);
    dma_buffer_block_t *buffer_to_fill = pipe->buffers[pipe->multi_buffer_control.wr_idx];
    buffer_to_fill->status_flags.val = 0;   // Clear the buffer's status flags
    assert(buffer_to_fill->urb == NULL);
    bool is_in = pipe->ep_char.bEndpointAddress & USB_B_ENDPOINT_ADDRESS_EP_DIR_MASK;
    int mps = pipe->ep_char.mps;
    usb_transfer_t *transfer = &urb->transfer;
    switch (pipe->ep_char.type) {
    case USB_DWC_XFER_TYPE_CTRL: {
        _buffer_fill_ctrl(buffer_to_fill, transfer);
        break;
    }
    case USB_DWC_XFER_TYPE_ISOCHRONOUS: {
        uint16_t start_idx;
        // Interval in frames (FS) or microframes (HS). But it does not matter here, as each QTD represents one transaction in a frame or microframe
        unsigned int interval = pipe->ep_char.periodic.interval;
        if (interval > XFER_LIST_LEN_ISOC) {
            // Each QTD in the list corresponds to one frame/microframe. Interval > Descriptor_list does not make sense here.
            interval = XFER_LIST_LEN_ISOC;
        }
        if (pipe->multi_buffer_control.buffer_num_to_exec == 0) {
            // There are no more previously filled buffers to execute. We need to calculate a new start index based on HFNUM and the pipe's schedule
            uint16_t cur_frame_num = usb_dwc_hal_port_get_cur_frame_num(pipe->port->hal);
            start_idx = cur_frame_num + 1; // This is the next frame that the periodic scheduler will fetch
            uint16_t rem_time = usb_dwc_ll_hfnum_get_frame_time_rem(pipe->port->hal->dev);

            // If there is not enough time remaining in this frame, consider the next frame as start index
            // The remaining time is in USB PHY clocks. The threshold value is time between buffer fill and execute (6-11us) = 180 + 5 x num_packets
            if (rem_time < 195 + 5 * transfer->num_isoc_packets) {
                if (rem_time > 165 + 5 * transfer->num_isoc_packets) {
                    // If the remaining time is +-15 PHY clocks around the threshold value we cannot be certain whether we will schedule it in time for this frame
                    // Busy wait 10us to be sure that we are at the beginning of next frame/microframe
                    esp_rom_delay_us(10);
                }
                start_idx++;
            }

            // Only every (interval + offset) transfer belongs to this channel
            // Following calculation effectively rounds up to nearest (interval + offset)
            if (interval > 1) {
                uint32_t interval_offset = (start_idx - pipe->ep_char.periodic.offset) % interval; // Can be <0, interval)
                if (interval_offset > 0) {
                    start_idx += interval - interval_offset;
                }
            }
            start_idx %= XFER_LIST_LEN_ISOC;
        } else {
            // Start index is based on previously filled buffer
            uint32_t prev_buffer_idx = (pipe->multi_buffer_control.wr_idx - 1) & (NUM_BUFFERS - 1);
            dma_buffer_block_t *prev_filled_buffer = pipe->buffers[prev_buffer_idx];
            start_idx = prev_filled_buffer->flags.isoc.next_start_idx;
        }
        _buffer_fill_isoc(buffer_to_fill, transfer, is_in, mps, (int)interval, start_idx);
        break;
    }
    case USB_DWC_XFER_TYPE_BULK: {
        _buffer_fill_bulk(buffer_to_fill, transfer, is_in, mps);
        break;
    }
    case USB_DWC_XFER_TYPE_INTR: {
        _buffer_fill_intr(buffer_to_fill, transfer, is_in, mps);
        break;
    }
    default: {
        abort();
        break;
    }
    }
    // Sync transfer descriptor list to memory
    CACHE_SYNC_XFER_DESCRIPTOR_LIST_C2M(buffer_to_fill);
    buffer_to_fill->urb = urb;
    urb->hcd_var = URB_HCD_STATE_INFLIGHT;
    // Update multi buffer flags
    pipe->multi_buffer_control.wr_idx++;
    pipe->multi_buffer_control.buffer_num_to_fill--;
    pipe->multi_buffer_control.buffer_num_to_exec++;
}

static void IRAM_ATTR _buffer_exec(pipe_t *pipe)
{
    assert(pipe->multi_buffer_control.rd_idx != pipe->multi_buffer_control.wr_idx || pipe->multi_buffer_control.buffer_num_to_exec > 0);
    dma_buffer_block_t *buffer_to_exec = pipe->buffers[pipe->multi_buffer_control.rd_idx];
    assert(buffer_to_exec->urb != NULL);

    uint32_t start_idx;
    int desc_list_len;
    switch (pipe->ep_char.type) {
    case USB_DWC_XFER_TYPE_CTRL: {
        start_idx = 0;
        desc_list_len = XFER_LIST_LEN_CTRL;
        // Set the channel's direction to OUT and PID to 0 respectively for the the setup stage
        usb_dwc_hal_chan_set_dir(pipe->chan_obj, false);   // Setup stage is always OUT
        usb_dwc_hal_chan_set_pid(pipe->chan_obj, 0);   // Setup stage always has a PID of DATA0
        break;
    }
    case USB_DWC_XFER_TYPE_ISOCHRONOUS: {
        start_idx = buffer_to_exec->flags.isoc.start_idx;
        desc_list_len = XFER_LIST_LEN_ISOC;
        break;
    }
    case USB_DWC_XFER_TYPE_BULK: {
        start_idx = 0;
        desc_list_len = (buffer_to_exec->flags.bulk.zero_len_packet) ? XFER_LIST_LEN_BULK : 1;
        break;
    }
    case USB_DWC_XFER_TYPE_INTR: {
        start_idx = 0;
        desc_list_len = (buffer_to_exec->flags.intr.zero_len_packet) ? buffer_to_exec->flags.intr.num_qtds + 1 : buffer_to_exec->flags.intr.num_qtds;
        break;
    }
    default: {
        start_idx = 0;
        desc_list_len = 0;
        abort();
        break;
    }
    }
    // Update buffer and multi buffer flags
    buffer_to_exec->status_flags.executing = 1;
    pipe->multi_buffer_control.buffer_is_executing = 1;
    usb_dwc_hal_chan_activate(pipe->chan_obj, buffer_to_exec->xfer_desc_list, desc_list_len, start_idx);
}

static void _buffer_exec_cont(pipe_t *pipe)
{
    // This should only ever be called on control transfers
    assert(pipe->ep_char.type == USB_DWC_XFER_TYPE_CTRL);
    dma_buffer_block_t *buffer_inflight = pipe->buffers[pipe->multi_buffer_control.rd_idx];
    bool next_dir_is_in;
    int next_pid;
    assert(buffer_inflight->flags.ctrl.cur_stg != 2);
    if (buffer_inflight->flags.ctrl.cur_stg == 0) { // Just finished control stage
        if (buffer_inflight->flags.ctrl.data_stg_skip) {
            // Skipping data stage. Go straight to status stage
            next_dir_is_in = true;     // With no data stage, status stage must be IN
            next_pid = 1;       // Status stage always has a PID of DATA1
            buffer_inflight->flags.ctrl.cur_stg = 2;    // Skip over the null descriptor representing the skipped data stage
        } else {
            // Go to data stage
            next_dir_is_in = buffer_inflight->flags.ctrl.data_stg_in;
            next_pid = 1;   // Data stage always starts with a PID of DATA1
            buffer_inflight->flags.ctrl.cur_stg = 1;
        }
    } else {        // cur_stg == 1. // Just finished data stage. Go to status stage
        next_dir_is_in = !buffer_inflight->flags.ctrl.data_stg_in;  // Status stage is always the opposite direction of data stage
        next_pid = 1;   // Status stage always has a PID of DATA1
        buffer_inflight->flags.ctrl.cur_stg = 2;
    }
    // Continue the control transfer
    usb_dwc_hal_chan_set_dir(pipe->chan_obj, next_dir_is_in);
    usb_dwc_hal_chan_set_pid(pipe->chan_obj, next_pid);
    usb_dwc_hal_chan_activate(pipe->chan_obj, buffer_inflight->xfer_desc_list, XFER_LIST_LEN_CTRL, buffer_inflight->flags.ctrl.cur_stg);
}

static inline void _buffer_parse_ctrl(dma_buffer_block_t *buffer)
{
    usb_transfer_t *transfer = &buffer->urb->transfer;
    // Update URB's actual number of bytes
    if (buffer->flags.ctrl.data_stg_skip)     {
        // There was no data stage. Just set the actual length to the size of the setup packet
        transfer->actual_num_bytes = sizeof(usb_setup_packet_t);
    } else {
        // Parse the data stage for the remaining length
        int rem_len;
        int desc_status;
        usb_dwc_hal_xfer_desc_parse(buffer->xfer_desc_list, 1, &rem_len, &desc_status);
        assert(desc_status == USB_DWC_HAL_XFER_DESC_STS_SUCCESS);
        assert(rem_len <= (transfer->num_bytes - sizeof(usb_setup_packet_t)));
        transfer->actual_num_bytes = transfer->num_bytes - rem_len;
    }
    // Update URB status
    transfer->status = USB_TRANSFER_STATUS_COMPLETED;
    // Clear the descriptor list
    memset(buffer->xfer_desc_list, 0, XFER_LIST_LEN_CTRL * sizeof(usb_dwc_ll_dma_qtd_t));
}

static inline void _buffer_parse_bulk(dma_buffer_block_t *buffer)
{
    usb_transfer_t *transfer = &buffer->urb->transfer;
    // Update URB's actual number of bytes
    int rem_len;
    int desc_status;
    usb_dwc_hal_xfer_desc_parse(buffer->xfer_desc_list, 0, &rem_len, &desc_status);
    assert(desc_status == USB_DWC_HAL_XFER_DESC_STS_SUCCESS);
    assert(rem_len <= transfer->num_bytes);
    transfer->actual_num_bytes = transfer->num_bytes - rem_len;
    // Update URB's status
    transfer->status = USB_TRANSFER_STATUS_COMPLETED;
    // Clear the descriptor list
    memset(buffer->xfer_desc_list, 0, XFER_LIST_LEN_BULK * sizeof(usb_dwc_ll_dma_qtd_t));
}

static inline void _buffer_parse_intr(dma_buffer_block_t *buffer, bool is_in, int mps)
{
    usb_transfer_t *transfer = &buffer->urb->transfer;
    int intr_stop_idx = buffer->status_flags.stop_idx;
    if (is_in) {
        if (intr_stop_idx > 0) { // This is an early stop (short packet)
            assert(intr_stop_idx <= buffer->flags.intr.num_qtds);
            int rem_len;
            int desc_status;
            for (int i = 0; i < intr_stop_idx - 1; i++) {    // Check all packets before the short
                usb_dwc_hal_xfer_desc_parse(buffer->xfer_desc_list, i, &rem_len, &desc_status);
                assert(rem_len == 0 && desc_status == USB_DWC_HAL_XFER_DESC_STS_SUCCESS);
            }
            // Check the short packet
            usb_dwc_hal_xfer_desc_parse(buffer->xfer_desc_list, intr_stop_idx - 1, &rem_len, &desc_status);
            assert(rem_len > 0 && desc_status == USB_DWC_HAL_XFER_DESC_STS_SUCCESS);
            // Update actual bytes
            transfer->actual_num_bytes = (mps * intr_stop_idx - 2) + (mps - rem_len);
        } else {
            // Check that all but the last packet transmitted MPS
            for (int i = 0; i < buffer->flags.intr.num_qtds - 1; i++) {
                int rem_len;
                int desc_status;
                usb_dwc_hal_xfer_desc_parse(buffer->xfer_desc_list, i, &rem_len, &desc_status);
                assert(rem_len == 0 && desc_status == USB_DWC_HAL_XFER_DESC_STS_SUCCESS);
            }
            // Check the last packet
            int last_packet_rem_len;
            int last_packet_desc_status;
            usb_dwc_hal_xfer_desc_parse(buffer->xfer_desc_list, buffer->flags.intr.num_qtds - 1, &last_packet_rem_len, &last_packet_desc_status);
            assert(last_packet_desc_status == USB_DWC_HAL_XFER_DESC_STS_SUCCESS);
            // All packets except last MUST be MPS. So just deduct the remaining length of the last packet to get actual number of bytes
            transfer->actual_num_bytes = transfer->num_bytes - last_packet_rem_len;
        }
    } else {
        // OUT INTR transfers can only complete successfully if all packets have been transmitted. Double check
        for (int i = 0 ; i < buffer->flags.intr.num_qtds; i++) {
            int rem_len;
            int desc_status;
            usb_dwc_hal_xfer_desc_parse(buffer->xfer_desc_list, i, &rem_len, &desc_status);
            assert(rem_len == 0 && desc_status == USB_DWC_HAL_XFER_DESC_STS_SUCCESS);
        }
        transfer->actual_num_bytes = transfer->num_bytes;
    }
    // Update URB's status
    transfer->status = USB_TRANSFER_STATUS_COMPLETED;
    // Clear the descriptor list
    memset(buffer->xfer_desc_list, 0, XFER_LIST_LEN_INTR * sizeof(usb_dwc_ll_dma_qtd_t));
}

static inline void _buffer_parse_isoc(dma_buffer_block_t *buffer, bool is_in)
{
    usb_transfer_t *transfer = &buffer->urb->transfer;
    int desc_idx = buffer->flags.isoc.start_idx;    // Descriptor index tracks which descriptor in the QTD list
    int total_actual_num_bytes = 0;
    for (int pkt_idx = 0; pkt_idx < transfer->num_isoc_packets; pkt_idx++) {
        // Clear the filled descriptor
        int rem_len;
        int desc_status;
        usb_dwc_hal_xfer_desc_parse(buffer->xfer_desc_list, desc_idx, &rem_len, &desc_status);
        usb_dwc_hal_xfer_desc_clear(buffer->xfer_desc_list, desc_idx);
        switch (desc_status) {
        case USB_DWC_HAL_XFER_DESC_STS_SUCCESS:
            transfer->isoc_packet_desc[pkt_idx].status = USB_TRANSFER_STATUS_COMPLETED;
            break;
        case USB_DWC_HAL_XFER_DESC_STS_NOT_EXECUTED:
            transfer->isoc_packet_desc[pkt_idx].status = USB_TRANSFER_STATUS_SKIPPED;
            break;
        case USB_DWC_HAL_XFER_DESC_STS_PKTERR:
            transfer->isoc_packet_desc[pkt_idx].status = USB_TRANSFER_STATUS_ERROR;
            break;
        case USB_DWC_HAL_XFER_DESC_STS_BUFFER_ERR:
            transfer->isoc_packet_desc[pkt_idx].status = USB_TRANSFER_STATUS_ERROR;
            break;
        default:
            assert(false);
            break;
        }

        assert(rem_len <= transfer->isoc_packet_desc[pkt_idx].num_bytes);    // Check for DMA errata
        // Update ISO packet actual length and status
        transfer->isoc_packet_desc[pkt_idx].actual_num_bytes = transfer->isoc_packet_desc[pkt_idx].num_bytes - rem_len;
        total_actual_num_bytes += transfer->isoc_packet_desc[pkt_idx].actual_num_bytes;
        // A descriptor is also allocated for unscheduled frames. We need to skip over them
        desc_idx += buffer->flags.isoc.interval;
        if (desc_idx >= XFER_LIST_LEN_INTR) {
            desc_idx -= XFER_LIST_LEN_INTR;
        }
    }
    // Write back the actual_num_bytes and statue of entire transfer
    assert(total_actual_num_bytes <= transfer->num_bytes);
    transfer->actual_num_bytes = total_actual_num_bytes;
    transfer->status = USB_TRANSFER_STATUS_COMPLETED;
}

static inline void _buffer_parse_error(dma_buffer_block_t *buffer)
{
    // The URB had an error in one of its packet, or a port error), so we the entire URB an error.
    usb_transfer_t *transfer = &buffer->urb->transfer;
    transfer->actual_num_bytes = 0;
    // Update the overall status of URB. Status will depend on the pipe_event
    switch (buffer->status_flags.pipe_event) {
    case HCD_PIPE_EVENT_NONE:
        transfer->status = (buffer->status_flags.was_canceled) ? USB_TRANSFER_STATUS_CANCELED : USB_TRANSFER_STATUS_NO_DEVICE;
        break;
    case HCD_PIPE_EVENT_ERROR_XFER:
        transfer->status = USB_TRANSFER_STATUS_ERROR;
        break;
    case HCD_PIPE_EVENT_ERROR_OVERFLOW:
        transfer->status = USB_TRANSFER_STATUS_OVERFLOW;
        break;
    case HCD_PIPE_EVENT_ERROR_STALL:
        transfer->status = USB_TRANSFER_STATUS_STALL;
        break;
    default:
        // HCD_PIPE_EVENT_URB_DONE and HCD_PIPE_EVENT_ERROR_URB_NOT_AVAIL should not occur here
        abort();
        break;
    }
}

static void _buffer_parse(pipe_t *pipe)
{
    assert(pipe->multi_buffer_control.buffer_num_to_parse > 0);
    dma_buffer_block_t *buffer_to_parse = pipe->buffers[pipe->multi_buffer_control.fr_idx];
    assert(buffer_to_parse->urb != NULL);
    bool is_in = pipe->ep_char.bEndpointAddress & USB_B_ENDPOINT_ADDRESS_EP_DIR_MASK;
    int mps = pipe->ep_char.mps;

    // Sync transfer descriptor list to cache
    CACHE_SYNC_XFER_DESCRIPTOR_LIST_M2C(buffer_to_parse);

    // Parsing the buffer will update the buffer's corresponding URB
    if (buffer_to_parse->status_flags.pipe_event == HCD_PIPE_EVENT_URB_DONE) {
        // URB was successful
        switch (pipe->ep_char.type) {
        case USB_DWC_XFER_TYPE_CTRL: {
            _buffer_parse_ctrl(buffer_to_parse);
            break;
        }
        case USB_DWC_XFER_TYPE_ISOCHRONOUS: {
            _buffer_parse_isoc(buffer_to_parse, is_in);
            break;
        }
        case USB_DWC_XFER_TYPE_BULK: {
            _buffer_parse_bulk(buffer_to_parse);
            break;
        }
        case USB_DWC_XFER_TYPE_INTR: {
            _buffer_parse_intr(buffer_to_parse, is_in, mps);
            break;
        }
        default: {
            abort();
            break;
        }
        }
    } else {
        // URB failed
        _buffer_parse_error(buffer_to_parse);
    }
    urb_t *urb = buffer_to_parse->urb;
    urb->hcd_var = URB_HCD_STATE_DONE;
    buffer_to_parse->urb = NULL;
    buffer_to_parse->flags.val = 0; // Clear flags
    // Move the URB to the done tailq
    TAILQ_INSERT_TAIL(&pipe->done_urb_tailq, urb, tailq_entry);
    pipe->num_urb_done++;
    // Update multi buffer flags
    pipe->multi_buffer_control.fr_idx++;
    pipe->multi_buffer_control.buffer_num_to_parse--;
    pipe->multi_buffer_control.buffer_num_to_fill++;
}

static bool _buffer_flush_all(pipe_t *pipe, bool canceled)
{
    int cur_num_to_mark_done = pipe->multi_buffer_control.buffer_num_to_exec;
    for (int i = 0; i < cur_num_to_mark_done; i++) {
        // Mark any filled buffers as done
        _buffer_done(pipe, 0, HCD_PIPE_EVENT_NONE, canceled);
    }
    int cur_num_to_parse = pipe->multi_buffer_control.buffer_num_to_parse;
    for (int i = 0; i < cur_num_to_parse; i++) {
        _buffer_parse(pipe);
    }
    // At this point, there should be no more filled buffers. Only URBs in the pending or done tailq
    return (cur_num_to_parse > 0);
}

// ---------------------------------------------- HCD Transfer Descriptors ---------------------------------------------

// ----------------------- Public --------------------------

esp_err_t hcd_urb_enqueue(hcd_pipe_handle_t pipe_hdl, urb_t *urb)
{
    // Check that URB has not already been enqueued
    HCD_CHECK(urb->hcd_ptr == NULL && urb->hcd_var == URB_HCD_STATE_IDLE, ESP_ERR_INVALID_STATE);
    pipe_t *pipe = (pipe_t *)pipe_hdl;
    // Check if the ISOC pipe can handle all packets:
    // In case the pipe's interval is too long and there are too many ISOC packets, they might not fit into the transfer descriptor list
    HCD_CHECK(
        !((pipe->ep_char.type == USB_DWC_XFER_TYPE_ISOCHRONOUS) && (urb->transfer.num_isoc_packets * pipe->ep_char.periodic.interval > XFER_LIST_LEN_ISOC)),
        ESP_ERR_INVALID_SIZE
    );

    // Sync user's data from cache to memory. For OUT and CTRL transfers
    CACHE_SYNC_DATA_BUFFER_C2M(pipe, urb);

    HCD_ENTER_CRITICAL();
    // Check that pipe and port are in the correct state to receive URBs
    HCD_CHECK_FROM_CRIT(pipe->port->state == HCD_PORT_STATE_ENABLED         // The pipe's port must be in the correct state
                        && pipe->state == HCD_PIPE_STATE_ACTIVE             // The pipe must be in the correct state
                        && !pipe->cs_flags.pipe_cmd_processing,             // Pipe cannot currently be processing a pipe command
                        ESP_ERR_INVALID_STATE);
    // Use the URB's reserved_ptr to store the pipe's
    urb->hcd_ptr = (void *)pipe;
    // Add the URB to the pipe's pending tailq
    urb->hcd_var = URB_HCD_STATE_PENDING;
    TAILQ_INSERT_TAIL(&pipe->pending_urb_tailq, urb, tailq_entry);
    pipe->num_urb_pending++;
    // use the URB's reserved_flags to store the URB's current state
    if (_buffer_can_fill(pipe)) {
        _buffer_fill(pipe);
    }
    if (_buffer_can_exec(pipe)) {
        _buffer_exec(pipe);
    }
    if (!pipe->cs_flags.has_urb) {
        // This is the first URB to be enqueued into the pipe. Move the pipe to the list of active pipes
        TAILQ_REMOVE(&pipe->port->pipes_idle_tailq, pipe, tailq_entry);
        TAILQ_INSERT_TAIL(&pipe->port->pipes_active_tailq, pipe, tailq_entry);
        pipe->port->num_pipes_idle--;
        pipe->port->num_pipes_queued++;
        pipe->cs_flags.has_urb = 1;
    }
    HCD_EXIT_CRITICAL();
    return ESP_OK;
}

urb_t *hcd_urb_dequeue(hcd_pipe_handle_t pipe_hdl)
{
    pipe_t *pipe = (pipe_t *)pipe_hdl;
    urb_t *urb;

    HCD_ENTER_CRITICAL();
    if (pipe->num_urb_done > 0) {
        urb = TAILQ_FIRST(&pipe->done_urb_tailq);
        TAILQ_REMOVE(&pipe->done_urb_tailq, urb, tailq_entry);
        pipe->num_urb_done--;
        // Check the URB's reserved fields then reset them
        assert(urb->hcd_ptr == (void *)pipe && urb->hcd_var == URB_HCD_STATE_DONE);  // The URB's reserved field should have been set to this pipe
        urb->hcd_ptr = NULL;
        urb->hcd_var = URB_HCD_STATE_IDLE;
        if (pipe->cs_flags.has_urb
                && pipe->num_urb_pending == 0 && pipe->num_urb_done == 0
                && pipe->multi_buffer_control.buffer_num_to_exec == 0 && pipe->multi_buffer_control.buffer_num_to_parse == 0) {
            // This pipe has no more enqueued URBs. Move the pipe to the list of idle pipes
            TAILQ_REMOVE(&pipe->port->pipes_active_tailq, pipe, tailq_entry);
            TAILQ_INSERT_TAIL(&pipe->port->pipes_idle_tailq, pipe, tailq_entry);
            pipe->port->num_pipes_idle++;
            pipe->port->num_pipes_queued--;
            pipe->cs_flags.has_urb = 0;
        }
        // Sync user's data in memory to cache. For IN and CTRL transfers
        CACHE_SYNC_DATA_BUFFER_M2C(pipe, urb);
    } else {
        // No more URBs to dequeue from this pipe
        urb = NULL;
    }
    HCD_EXIT_CRITICAL();
    return urb;
}

esp_err_t hcd_urb_abort(urb_t *urb)
{
    HCD_ENTER_CRITICAL();
    // Check that the URB was enqueued to begin with
    HCD_CHECK_FROM_CRIT(urb->hcd_ptr != NULL && urb->hcd_var != URB_HCD_STATE_IDLE, ESP_ERR_INVALID_STATE);
    if (urb->hcd_var == URB_HCD_STATE_PENDING) {
        // URB has not been executed so it can be aborted
        pipe_t *pipe = (pipe_t *)urb->hcd_ptr;
        // Remove it form the pending queue
        TAILQ_REMOVE(&pipe->pending_urb_tailq, urb, tailq_entry);
        pipe->num_urb_pending--;
        // Add it to the done queue
        TAILQ_INSERT_TAIL(&pipe->done_urb_tailq, urb, tailq_entry);
        pipe->num_urb_done++;
        // Update the URB's current state, status, and actual length
        urb->hcd_var = URB_HCD_STATE_DONE;
        if (urb->transfer.num_isoc_packets == 0) {
            urb->transfer.actual_num_bytes = 0;
            urb->transfer.status = USB_TRANSFER_STATUS_CANCELED;
        } else {
            // If this is an ISOC URB, update the ISO packet descriptors instead
            for (int i = 0; i < urb->transfer.num_isoc_packets; i++) {
                urb->transfer.isoc_packet_desc[i].actual_num_bytes = 0;
                urb->transfer.isoc_packet_desc[i].status = USB_TRANSFER_STATUS_CANCELED;
            }
        }
    }   // Otherwise, the URB is in-flight or already done thus cannot be aborted
    HCD_EXIT_CRITICAL();
    return ESP_OK;
}