path: root/common/usbx_host_controllers/src/ux_hcd_ehci_isochronous_endpoint_create.c

/***************************************************************************
 * Copyright (c) 2024 Microsoft Corporation
 * Copyright (c) 2026-present Eclipse ThreadX contributors
 *
 * This program and the accompanying materials are made available under the
 * terms of the MIT License which is available at
 * https://opensource.org/licenses/MIT.
 *
 * SPDX-License-Identifier: MIT
 **************************************************************************/


/**************************************************************************/
/**************************************************************************/
/**                                                                       */
/** USBX Component                                                        */
/**                                                                       */
/**   EHCI Controller Driver                                              */
/**                                                                       */
/**************************************************************************/
/**************************************************************************/


/* Include necessary system files.  */

#define UX_SOURCE_CODE

#include "ux_api.h"
#include "ux_hcd_ehci.h"
#include "ux_host_stack.h"


/**************************************************************************/
/*                                                                        */
/*  FUNCTION                                               RELEASE        */
/*                                                                        */
/*    _ux_hcd_ehci_isochronous_endpoint_create            PORTABLE C      */
/*                                                           6.3.0        */
/*  AUTHOR                                                                */
/*                                                                        */
/*    Chaoqiong Xiao, Microsoft Corporation                               */
/*                                                                        */
/*  DESCRIPTION                                                           */
/*                                                                        */
/*    This function will create an isochronous endpoint.                  */
/*                                                                        */
/*  INPUT                                                                 */
/*                                                                        */
/*    hcd_ehci                              Pointer to EHCI controller    */
/*    endpoint                              Pointer to endpoint           */
/*                                                                        */
/*  OUTPUT                                                                */
/*                                                                        */
/*    Completion Status                                                   */
/*                                                                        */
/*  CALLS                                                                 */
/*                                                                        */
/*    _ux_utility_memory_allocate           Allocate memory               */
/*    _ux_utility_memory_free               Free memory                   */
/*    _ux_hcd_ehci_hsisochronous_td_obtain  Obtain a TD                   */
/*    _ux_hcd_ehci_least_traffic_list_get   Get least traffic list        */
/*    _ux_hcd_ehci_poll_rate_entry_get      Get anchor for poll rate      */
/*    _ux_utility_physical_address          Get physical address          */
/*    _ux_host_mutex_on                     Get mutex                     */
/*    _ux_host_mutex_off                    Put mutex                     */
/*    _ux_hcd_ehci_periodic_descriptor_link Link/unlink descriptor        */
/*                                                                        */
/*  CALLED BY                                                             */
/*                                                                        */
/*    EHCI Controller Driver                                              */
/*                                                                        */
/**************************************************************************/
UINT  _ux_hcd_ehci_isochronous_endpoint_create(UX_HCD_EHCI *hcd_ehci, UX_ENDPOINT *endpoint)
{
#if UX_MAX_ISO_TD == 0

    UX_PARAMETER_NOT_USED(hcd_ehci);
    UX_PARAMETER_NOT_USED(endpoint);

    /* Error trap. */
    _ux_system_error_handler(UX_SYSTEM_LEVEL_THREAD, UX_SYSTEM_CONTEXT_HCD, UX_FUNCTION_NOT_SUPPORTED);

    /* If trace is enabled, insert this event into the trace buffer.  */
    UX_TRACE_IN_LINE_INSERT(UX_TRACE_ERROR, UX_FUNCTION_NOT_SUPPORTED, 0, 0, 0, UX_TRACE_ERRORS, 0, 0)

    /* Not supported, return error.  */
    return(UX_FUNCTION_NOT_SUPPORTED);
#else

UX_DEVICE                       *device;
UX_EHCI_HSISO_ED                *ed;
UX_EHCI_PERIODIC_LINK_POINTER   itd;
UX_EHCI_ED                      *ed_list;
UX_EHCI_ED                      *ed_anchor;
UX_EHCI_PERIODIC_LINK_POINTER   lp;
UX_EHCI_POINTER                 bp;
UCHAR                           interval;
UCHAR                           interval_shift;
UINT                            poll_depth;
ULONG                           microframe_load[8];
#if defined(UX_HCD_EHCI_SPLIT_TRANSFER_ENABLE)
ULONG                           microframe_ssplit_count[8];
ULONG                           mask;
UINT                            split_count;
ULONG                           split_last_size;
#else
#define                         microframe_ssplit_count     UX_NULL
#endif
ULONG                           microframe_i;
ULONG                           endpt;
ULONG                           device_address;
ULONG                           max_packet_size;
ULONG                           max_trans_size;
ULONG                           mult;
ULONG                           io;
UINT                            i;
UINT                            status;


    /* Get the pointer to the device.  */
    device =  endpoint -> ux_endpoint_device;

    /* Get the interval value from endpoint descriptor.  */
    interval = (UCHAR)endpoint -> ux_endpoint_descriptor.bInterval;

    /* For ISO, interval 1 ~ 16, means 2^(n-1).  */
    if (interval == 0)
        interval = 1;
    if (interval > 16)
        interval = 16;

    /* Interval shift is base 0.  */
    interval_shift = (UCHAR)(interval - 1);

    /* Keep interval as number of micro-frames.  */
    interval = (UCHAR)(1u << interval_shift);

    /* Get max packet size.  */
    max_packet_size = endpoint -> ux_endpoint_descriptor.wMaxPacketSize & UX_MAX_PACKET_SIZE_MASK;

    /* Get number transactions per micro-frame.  */
    mult = endpoint -> ux_endpoint_descriptor.wMaxPacketSize & UX_MAX_NUMBER_OF_TRANSACTIONS_MASK;
    mult >>= UX_MAX_NUMBER_OF_TRANSACTIONS_SHIFT;
    if (mult < 3)
        mult ++;

    /* Get max transfer size.  */
    max_trans_size = max_packet_size * mult;

    /* We need to take into account the nature of the HCD to define the max size
       of any transfer in the transfer request.  */
    endpoint -> ux_endpoint_transfer_request.ux_transfer_request_maximum_length = max_trans_size;

    /* Get the Endpt, Device Address, I/O, Maximum Packet Size, Mult.  */
    endpt = ((ULONG)endpoint -> ux_endpoint_descriptor.bEndpointAddress << UX_EHCI_HSISO_ENDPT_SHIFT) & UX_EHCI_HSISO_ENDPT_MASK;
    device_address = device -> ux_device_address & UX_EHCI_HSISO_DEVICE_ADDRESS_MASK;
    io = (endpoint -> ux_endpoint_descriptor.bEndpointAddress & UX_ENDPOINT_DIRECTION) ? UX_EHCI_HSISO_DIRECTION_IN : UX_EHCI_HSISO_DIRECTION_OUT;

    /* Only high speed transfer supported without split transfer.  */
    if (device -> ux_device_speed != UX_HIGH_SPEED_DEVICE)
    {
#if !defined(UX_HCD_EHCI_SPLIT_TRANSFER_ENABLE)
        return(UX_FUNCTION_NOT_SUPPORTED);
#else

        /* 1 ~ N siTDs ... */
        /* OUT: only start-splits, no complete splits.  */
        /* IN : at most one start-split and one to N complete-splits.  */

        /* TBD.  */
#endif
    }
    else
    {

        /* Allocate memory for ED.  */
        ed = (UX_EHCI_HSISO_ED *)_ux_utility_memory_allocate(UX_NO_ALIGN, UX_REGULAR_MEMORY, sizeof(UX_EHCI_HSISO_ED));
        if (ed == UX_NULL)
            return(UX_MEMORY_INSUFFICIENT);

        /* Obtain iTDs for this new endpoint.
        ** For noncontinuous request address and simplify calculation, allocate
        ** one iTD for two microframes.
        ** - interval   1 (0): 8 micro-frames, 4 iTD
        ** - interval   2 (1): 4 micro-frames, 2 iTD
        ** - interval   4 (2): 2 micro-frames, 1 iTD
        ** - interval >=8 (3): 1 micro-frame , 1 iTD
        ** Two micro-frames in iTD uses BP[3,4] and BP[5,6] to avoid merging of
        ** page buffer and iTD settings.
        */

        /* Get number of iTDs should be allocated.  */
        if (interval > 2)
            ed -> ux_ehci_hsiso_ed_nb_tds = 1;
        else
            ed -> ux_ehci_hsiso_ed_nb_tds = (UCHAR)(4u >> interval_shift);

        /* Obtain iTDs.  */
        status = UX_SUCCESS;
        for (i = 0; i < ed -> ux_ehci_hsiso_ed_nb_tds; i ++)
        {

            /* Get a new free iTD.  */
            itd.itd_ptr = _ux_hcd_ehci_hsisochronous_td_obtain(hcd_ehci);
            if (itd.itd_ptr == UX_NULL)
            {
                status = UX_NO_TD_AVAILABLE;
                break;
            }

            /* Link to ED.  */
            itd.itd_ptr -> ux_ehci_hsiso_td_ed = ed;

            /* Save max transfer size.  */
            itd.itd_ptr -> ux_ehci_hsiso_td_max_trans_size = (USHORT)max_trans_size;

            /* Save the iTD for the micro-frame(s).  */
            ed -> ux_ehci_hsiso_ed_fr_td[i] = itd.itd_ptr;
        }

        /* If there is error, free allocated resources.  */
        if (status != UX_SUCCESS)
        {
            for (i = 0; i < ed -> ux_ehci_hsiso_ed_nb_tds; i ++)
                ed -> ux_ehci_hsiso_ed_fr_td[i] -> ux_ehci_hsiso_td_status = UX_UNUSED;
            _ux_utility_memory_free(ed);
            return(status);
        }

        /* Save information not related to periodic things.  */

        /* Save endpoint.  */
        ed -> ux_ehci_hsiso_ed_endpoint = endpoint;

        /* Save interval.  */
        ed -> ux_ehci_hsiso_ed_frinterval = interval;
        ed -> ux_ehci_hsiso_ed_frinterval_shift = interval_shift;

        /* Disable iTDs for now.  */
        ed -> ux_ehci_hsiso_ed_frstart = 0xFF;
    }

    /* Attach the first iTD as the endpoint container.  */
    endpoint -> ux_endpoint_ed = ed -> ux_ehci_hsiso_ed_fr_td[0];

    /* Match the interval for the endpoint to a EHCI list.
       We match anything that is > 32ms to the 32ms interval layer.
       The 32ms list is layer 0, 16ms list is 1 ... the 1ms list is depth 5.  */

    /* Match > 32ms to 32ms list.  */
    /* Poll depth deeper, interval smaller.  */
    if (interval < 4)
        poll_depth = 5;
    else if (interval > 8)
        poll_depth = 0;
    else
        poll_depth = (UINT)(8u - interval);

    /* Keep only interval < 1ms for micro-frame calculation.  */
    interval_shift &= 0x3;
    interval &= 0x7;

    /* Fill the iTDs/siTDs contents that are not related to periodic list.
       Initialize the fields to be ready for ZLPs if OUT.
       But a zero buffer to underrun IN? */
#if defined(UX_HCD_EHCI_SPLIT_TRANSFER_ENABLE)
    if (device -> ux_device_speed != UX_HIGH_SPEED_DEVICE)
    {

        /* TBD.  */
    }
    else
#endif
    {

        /* Prepare things not related to periodic things.  */

        for (i = 0; i < ed -> ux_ehci_hsiso_ed_nb_tds; i ++)
        {

            /* Get iTD.  */
            itd.itd_ptr = ed -> ux_ehci_hsiso_ed_fr_td[i];

            /* Build next link pointer, if not last one.*/
            if (i < ed -> ux_ehci_hsiso_ed_nb_tds - 1u)
            {
                lp.void_ptr = _ux_utility_physical_address(ed -> ux_ehci_hsiso_ed_fr_td[i + 1]);
                itd.itd_ptr -> ux_ehci_hsiso_td_next_lp = lp;
            }

            /* Build previous pointer, if not first one.  */
            if (i > 0)
            {
                itd.itd_ptr -> ux_ehci_hsiso_td_previous_lp.itd_ptr =
                                        ed -> ux_ehci_hsiso_ed_fr_td[i - 1];
            }

            /* Save Device Address and Endpt @ BP0.  */
            bp.value = device_address | endpt;
            itd.itd_ptr -> ux_ehci_hsiso_td_bp[0] = bp.void_ptr;

            /* Save I/O and max packet size @ BP1.  */
            bp.value = io | max_packet_size;
            itd.itd_ptr -> ux_ehci_hsiso_td_bp[1] = bp.void_ptr;

            /* Save Mult @ BP2.  */
            bp.value = mult;
            itd.itd_ptr -> ux_ehci_hsiso_td_bp[2] = bp.void_ptr;
        }

    }

    /* Lock the periodic list to update.  */
    _ux_host_mutex_on(&hcd_ehci -> ux_hcd_ehci_periodic_mutex);

    /* Get the list index with the least traffic.  */
    ed_list = _ux_hcd_ehci_least_traffic_list_get(hcd_ehci, microframe_load, microframe_ssplit_count);

    /* Now we need to scan the list of EDs from the lowest load entry until we reach the
       appropriate interval node. The depth index is the interval EHCI value and the
       1st entry is pointed by the ED list entry.  */
    ed_anchor = _ux_hcd_ehci_poll_rate_entry_get(hcd_ehci, ed_list, poll_depth);

    /* Calculate packet size with num transactions.  */
    max_packet_size *= mult;

    /* Go through the transaction loads for for start
       index of micro-frame.  */
    for (microframe_i = 0; microframe_i < interval; microframe_i ++)
    {

        /* Skip if load too much.  */
        if (microframe_load[microframe_i] + max_packet_size > UX_MAX_BYTES_PER_MICROFRAME_HS)
            continue;

#if defined(UX_HCD_EHCI_SPLIT_TRANSFER_ENABLE)
        if (device -> ux_device_speed != UX_HIGH_SPEED_DEVICE)
        {

            /* Skip Y6 since host must not use it.  */
            if (i == 6)
                continue;

            /* Skip if start split count over 16 split.  */
            if (microframe_ssplit_count[i] >= 16)
                continue;
        }
#endif

        /* Use the load.  */
        break;
    }

    /* Sanity check, bandwidth checked before endpoint creation so there should
       not be error but we check it any way.  */
    if (microframe_i >= interval)
    {
        _ux_host_mutex_off(&hcd_ehci -> ux_hcd_ehci_periodic_mutex);
        for (i = 0; i < ed -> ux_ehci_hsiso_ed_nb_tds; i ++)
            ed -> ux_ehci_hsiso_ed_fr_td[i] -> ux_ehci_hsiso_td_status = UX_UNUSED;
        _ux_utility_memory_free(ed);
        return(UX_NO_BANDWIDTH_AVAILABLE);
    }

    /* Now start microframe index is calculated, things related periodic list.  */
#if defined(UX_HCD_EHCI_SPLIT_TRANSFER_ENABLE)
    if (device -> ux_device_speed != UX_HIGH_SPEED_DEVICE)
    {
        /* OUT: each microframe budgeted, 188 (or the remaining data size) data byte.
                never complete-split.
           IN : complete-split must be scheduled for each following microframe.
                L - the last microframe in which a complete-split is scheduled.
                L < Y6, schedule additional complete-splits in microframe L+1 and L+2.
                L == Y6, schedule one complete-split in microframe Y7,
                         schedule one complete-split in microframe Y0 of the next frame,
                         unless the full speed transaction was budgeted to start in microframe Y0.
                L == Y7, schedule one complete-split in microframe Y0 of the next frame,
                         unless the full speed transaction was budgeted to start in microframe Y0.
         */

        /* Save anchor pointer.  */
        itd.sitd_ptr -> ux_ehci_fsiso_td_anchor = ed_anchor;

        /* No back pointer by default.  */
        lp.value = UX_EHCI_T;

        /* OUT or IN?  */
        if (io == 0)
        {

            /* Multiple start split based on max packet size, no complete split.  */
            split_count = (max_packet_size + 187) / 188;
            split_last_size = max_packet_size % 188;

            mask = (UX_EHCI_SMASK_0 << split_count) - UX_EHCI_SMASK_0;
            mask <<= microframe_i;
            if (microframe_i + split_count > 8)
            {
                mask |= mask >> 8;
                mask &= UX_EHCI_SMASK_MASK;

                /* Need back pointer.  */
                lp = itd;
                lp.void_ptr = _ux_utility_physical_address(lp.void_ptr);
            }

            /* Save settings.  */
            itd.sitd_ptr -> ux_ehci_fsiso_td_cap1 = mask;
            itd.sitd_ptr -> ux_ehci_fsiso_td_back_pointer = lp.void_ptr;

            /* Update anchor micro-frame loads and start splits.  */
            for (i = 0; i < 8; i ++)
            {
                if ((mask & (UX_EHCI_SMASK_0 << i)) == 0)
                    continue;

                /* Add to load.  */
                if (split_last_size &&
                    i == ((microframe_i + split_count - 1) & 7))
                {
                    ed_anchor -> REF_AS.ANCHOR.ux_ehci_ed_microframe_load[i] = (USHORT)(ed_anchor -> REF_AS.ANCHOR.ux_ehci_ed_microframe_load[i] + split_last_size);
                }
                else
                    ed_anchor -> REF_AS.ANCHOR.ux_ehci_ed_microframe_load[i] = (USHORT)(ed_anchor -> REF_AS.ANCHOR.ux_ehci_ed_microframe_load[i] + 188u);

                /* Increment SSplit count.  */
                ed_anchor -> REF_AS.ANCHOR.ux_ehci_ed_microframe_ssplit_count[i] ++;
            }
        }
        else
        {

            /* Single start split.  */
            itd.sitd_ptr -> ux_ehci_fsiso_td_cap1 = UX_EHCI_SMASK_0 << microframe_i;

            /* Multiple complete split, start +2, based on max packet size.  */
            split_count = (max_packet_size + 187) / 188;

            /* Adding extra 2 at end.  */
            split_count += 2;
            mask = (UX_EHCI_CMASK_0 << split_count) - UX_EHCI_CMASK_0;
            mask <<= microframe_i + 2;
            if (microframe_i + 2 + split_count > 8)
            {
                mask |= mask >> 8;
                mask &= UX_EHCI_CMASK_MASK;

                /* Need back pointer.  */
                lp = itd;
                lp.void_ptr = _ux_utility_physical_address(lp.void_ptr);
            }

            /* If Y0 has budget, clear complete mask of it.  */
            if (microframe_i == 7)
            {
                if (mask & UX_EHCI_CMASK_0)
                {
                    mask &= ~UX_EHCI_CMASK_0;
                    split_count --;
                }
            }

            /* Save settings.  */
            itd.sitd_ptr -> ux_ehci_fsiso_td_cap1 |= mask;
            itd.sitd_ptr -> ux_ehci_fsiso_td_back_pointer = lp.void_ptr;

            /* Update anchor micro-frame loads and complete splits.  */
            for (i = 0; i < 8; i ++)
            {
                if ((mask & (UX_EHCI_CMASK_0 << i)) == 0)
                    continue;

                /* Add to load.  */
                ed_anchor -> REF_AS.ANCHOR.ux_ehci_ed_microframe_load[i] = (USHORT)(ed_anchor -> REF_AS.ANCHOR.ux_ehci_ed_microframe_load[i] + 188u);
            }

            /* Increment SSplit count.  */
            ed_anchor -> REF_AS.ANCHOR.ux_ehci_ed_microframe_ssplit_count[microframe_i] ++;
        }

    }
    else
#endif
    {

        /* Save index base of allocated micro-frame.  */
        ed -> ux_ehci_hsiso_ed_frindex = (UCHAR)microframe_i;

        /* Save anchor pointer.  */
        ed -> ux_ehci_hsiso_ed_anchor = ed_anchor;

        /* Update micro-frames.  */
        for (i = microframe_i; i < 8; i += interval)
        {

            /* Update anchor micro-frame loads.  */
            ed_anchor -> REF_AS.ANCHOR.ux_ehci_ed_microframe_load[i] = (USHORT)(ed_anchor -> REF_AS.ANCHOR.ux_ehci_ed_microframe_load[i] + max_packet_size);

            /* Initialize control with PG -> BP (3, 5).  */
            itd.itd_ptr = ed -> ux_ehci_hsiso_ed_fr_td[i >> 1];

            /* Buffer in page 3,4 or 5,6 to avoid merging settings.  */
            if (i & 1u)
                itd.itd_ptr -> ux_ehci_hsiso_td_control[i] = UX_EHCI_HSISO_IOC |
                                                (5 << UX_EHCI_HSISO_PG_SHIFT);
            else
                itd.itd_ptr -> ux_ehci_hsiso_td_control[i] = UX_EHCI_HSISO_IOC |
                                                (3 << UX_EHCI_HSISO_PG_SHIFT);
        }
    }

    /* Link iTDs to periodic list.  */

    /* Physical LP for anchor (Typ iTD, 0).  */
    lp.void_ptr = _ux_utility_physical_address(ed -> ux_ehci_hsiso_ed_fr_td[0]);

    /* Link to periodic list.  */
    ed -> ux_ehci_hsiso_ed_fr_td[0] -> ux_ehci_hsiso_td_previous_lp.ed_ptr = ed_anchor;
    _ux_hcd_ehci_periodic_descriptor_link(ed_anchor, lp.void_ptr,
        ed -> ux_ehci_hsiso_ed_fr_td[ed -> ux_ehci_hsiso_ed_nb_tds - 1],
        ed_anchor -> ux_ehci_ed_queue_head);

    /* Simply insert all iTD[0]/siTD[0] to head of scan list.  */
#if defined(UX_HCD_EHCI_SPLIT_TRANSFER_ENABLE)
    if (device -> ux_device_speed != UX_HIGH_SPEED_DEVICE)
    {
        itd.sitd_ptr -> ux_ehci_fsiso_td_next_scan_td = hcd_ehci -> ux_hcd_ehci_fsiso_scan_list;
        hcd_ehci -> ux_hcd_ehci_fsiso_scan_list = itd.sitd_ptr;
    }
    else
#endif
    {
        itd.itd_ptr = ed -> ux_ehci_hsiso_ed_fr_td[0];
        itd.itd_ptr -> ux_ehci_hsiso_td_next_scan_td =
                                hcd_ehci -> ux_hcd_ehci_hsiso_scan_list;
        hcd_ehci -> ux_hcd_ehci_hsiso_scan_list = itd.itd_ptr;
        if (itd.itd_ptr -> ux_ehci_hsiso_td_next_scan_td)
            itd.itd_ptr -> ux_ehci_hsiso_td_next_scan_td -> ux_ehci_hsiso_td_previous_scan_td =
                                itd.itd_ptr;
    }

    /* Release the periodic table.  */
    _ux_host_mutex_off(&hcd_ehci -> ux_hcd_ehci_periodic_mutex);

    /* Return successful completion.  */
    return(UX_SUCCESS);
#endif
}