Disambiguate some lib_usb functions

[aneves]

Hello,

While working with lib_usb, I noticed a few functions that seem to do the same thing but maybe allow different ways to do so.

From xud.h:

Code: Select all

/**
 * \brief   This function will complete a reset on an endpoint. Can take
 *          one or two ``XUD_ep`` as parameters (the second parameter can be set to ``null``).
 *          The return value should be inspected to find the new bus-speed.
 *          In Endpoint 0 typically two endpoints are reset (IN and OUT).
 *          In other endpoints ``null`` can be passed as the second parameter.
 * \param   one      IN or OUT endpoint identifier to perform the reset on.
 * \param   two      Optional second IN or OUT endpoint structure to perform a reset on.
 * \return  Either ``XUD_SPEED_HS`` - the host has accepted that this device can execute
 *          at high speed, or ``XUD_SPEED_FS`` - the device is runnig at full speed.
 */
XUD_BusSpeed_t XUD_ResetEndpoint(XUD_ep one, NULLABLE_REFERENCE_PARAM(XUD_ep, two));

Code: Select all

/* USB 2.0 Spec 9.1.1.5 states that configuring a device should cause all
 * the status and configuration values associated with the endpoints in the
 * affected interfaces to be set to their default values.  This includes setting
 * the data toggle of any endpoint using data toggles to the value DATA0 */
/**
 * \brief      Reset an Endpoints state including data PID toggle
 *             Note: the IN bit of the endpoint address is used.
 * \param      epNum    Endpoint number (including IN bit)
 * \warning    Must be run on same tile as XUD core
 */
void XUD_ResetEpStateByAddr(unsigned epNum);

I've seen XUD_ResetEndpoint used in the context where ep0 in & out need to be reset when we detect a reset on the bus. XUD_ResetEpStateByAddress is used in the context of transitioning from the Address state to the Configured state when handling a SetConfiguration request from the host. Other than their parameters, are these functions functionally different? Do the both do the exact same thing via 2 different function signatures? Or should they only be used in the contexts I saw them in the example code that came with lib_usb?


I have similar questions about the following functions as well. From xud.h:

Code: Select all

**
 * \brief      Mark an endpoint as STALL based on its EP address.  Cleared automatically if a SETUP received on the endpoint.
 *             Note: the IN bit of the endpoint address is used.
 * \param      epNum    Endpoint number.
 * \warning    Must be run on same tile as XUD core
 */
void XUD_SetStallByAddr(int epNum);


/**
 * \brief      Mark an endpoint as NOT STALLed based on its EP address.
 *             Note: the IN bit of the endpoint address is used.
 * \param      epNum    Endpoint number.
 * \warning    Must be run on same tile as XUD core
 */
void XUD_ClearStallByAddr(int epNum);

/**
 * \brief   Mark an endpoint as STALLed.  It is cleared automatically if a SETUP received on the endpoint.
 * \param   ep XUD_ep type.
 * \warning Must be run on same tile as XUD core
 */
void XUD_SetStall(XUD_ep ep);


/**
 * \brief   Mark an endpoint as NOT STALLed
 * \param   ep XUD_ep type.
 * \warning Must be run on same tile as XUD core
 */
void XUD_ClearStall(XUD_ep ep);

Are XUD_Set/ClearStallByAddr and XUD_Set/ClearStall functionally the same, just giving us a different way to do the same thing?

Thanks!

[aneves]

Anybody? I figure this should pretty easy for someone to explain.