usbtargpipefunc.c

USB source code of Vxworks 5.6. It has device and the host stack.

/* usbTargPipeFunc.c - modules for handling pipe specific requests */

/* Copyright 2004 Wind River Systems, Inc. */

/*
Modification history
--------------------
01f,17sep04,ami  WindView Instrumentation Changes
01e,03aug04,mta  Modification History Changes
01d,20jul04,mta  ISP1582 Mass Storage testing on Mips
01c,19jul04,ami Coding Convnetion Changes
01b,27apr04,ami Testing bug fixes
01a,31mar04,ami First
*/

/*
DESCRIPTION

This module provides interfaces for handling the various pipe specific 
requests.

It provides interfaces for creating and destroying pipes, submit and cancel
ERPs and to get and set the pipe status information.

INCLUDE FILES: usb/usbPlatform.h, string.h, usb/ossLib.h, usb/usb.h, 
               usb/usbHandleLib.h, usb/target/HalLib.h,
               usb/target/usbHalCommon.h, usb/target/usbTargLib.h,
               usb/target/usbTargUtil.h, usb/target/usbPeriphInstr.h

*/

/* includes */

#include "usb/usbPlatform.h"	
#include "usb/ossLib.h"                 
#include "usb/usb.h"                     
#include "usb/usbHandleLib.h"           
#include "usb/target/usbHalLib.h"      
#include "usb/target/usbHalCommon.h"
#include "usb/target/usbTargLib.h"  
#include "usb/target/usbTargUtil.h"     
#include "usb/target/usbPeriphInstr.h"     

extern MUTEX_HANDLE targMutex;

/* forward declarations */

LOCAL VOID usbTargErpCallback (pVOID pErp);

LOCAL STATUS validatePipe (USB_TARG_PIPE pipeHandle, pTARG_PIPE *ppPipe);


/*******************************************************************************
*
* usbTargPipeCreate - creates a pipe for communication on an endpoint
*
* This function creates a pipe for communication on an endpoint attached to
* a specific target endpoint. In return we get the pipe handle which is
* used by that endpoint for communication.
*
* RETURNS: OK, or ERROR if unable to create pipe
*
* ERRNO:
* \is
* \i S_usbTargLib_TCD_FAULT
* Fault occured in TCD.
*
* \i S_usbTargLib_BAD_PARAM
* Bad parameter is passed.
* 
* \i S_usbTargLib_OUT_OF_RESOURCES
* Sufficient resources not available.
* \ie  
*/

STATUS usbTargPipeCreate
    (
    USB_TARG_CHANNEL	targChannel,		/* target channel */
    pUSB_ENDPOINT_DESCR	pEndpointDesc,		/* USB_ENDPOINT_DESCR */
    UINT16		uConfigurationValue,    /* configuration value */
    UINT16		uInterface,             /* Number of interface which */
                                                /* holds this endpoint */
    UINT16		uAltSetting,		/* alternate Setting */
    pUSB_TARG_PIPE	pPipeHandle		/* pointer to pipe handle */
    )
    {
    pTARG_TCD	pTcd = NULL;			/* TARG_TCD */
    UINT32	status = OK;
    pTARG_PIPE	pPipe = NULL;			/* TARG_PIPE */

    /* WindView Instrumentation */

    USB_TARG_LOG_EVENT(USB_TARG_PIPE_FUNC,
    "usbTargPipeCreate entered ...", USB_TARG_WV_FILTER);   

    /* Validate the endpoint descriptor */

    if ( pEndpointDesc == NULL )
        {

        /* WindView Instrumentation */

        USB_TARG_LOG_EVENT(USB_TARG_PIPE_FUNC,
        "usbTargPipeCreate exiting: Invalid Endpoint Descriptor...",
        USB_TARG_WV_FILTER);   

        return ossStatus (S_usbTargLib_BAD_PARAM);
        }  

    /* Validate  the channel */

    if (validateTarg(targChannel, &pTcd) != OK)
        {

        /* WindView Instrumentation */

        USB_TARG_LOG_EVENT(USB_TARG_PIPE_FUNC,
        "usbTargPipeCreate exiting: Wrong Target Channel...",
        USB_TARG_WV_FILTER);   

        return ossStatus (S_usbTargLib_BAD_PARAM);
        }  

    /* Allocate memory for TARG_PIPE */

    if ((pPipe = OSS_CALLOC (sizeof (*pPipe))) == NULL)
        {

        /* WindView Instrumentation */

        USB_TARG_LOG_EVENT(USB_TARG_PIPE_FUNC,
        "usbTargPipeCreate exiting: Failed to allocated memory for pPipe...",
        USB_TARG_WV_FILTER);   

        return ossStatus (S_usbTargLib_OUT_OF_RESOURCES);
        }

    /* Assign the endpoint */

    if ((status = usbHalTcdEndpointAssign (&pTcd->tcdNexus,pEndpointDesc,
                                           uConfigurationValue, uInterface,
                                           uAltSetting,&pPipe->pHalPipeHandle))
                                           !=OK)
        {

        /* WindView Instrumentation */

        USB_TARG_LOG_EVENT(USB_TARG_PIPE_FUNC,
        "usbTargPipeCreate exiting: Error assigning endpoint...",
        USB_TARG_WV_FILTER);   

        OSS_FREE(pPipe);
        return ossStatus (S_usbTargLib_TCD_FAULT);
        }

    /* Store pointer to TARG_TCD in TARG_PIPE */

    pPipe->pTargTcd = pTcd;

    /* Create a Pipe Handle */

    if ((status = usbHandleCreate (TARG_PIPE_SIG,pPipe,&pPipe->pipeHandle))!=OK)
        status = ossStatus (S_usbTargLib_OUT_OF_RESOURCES);
    else
        *pPipeHandle = pPipe->pipeHandle;

    /* WindView Instrumentation */

    USB_TARG_LOG_EVENT(USB_TARG_PIPE_FUNC,
    "usbTargPipeCreate exiting...", USB_TARG_WV_FILTER);   

    return status;
    }

/*******************************************************************************
*
* usbTargPipeDestroy - destroys an endpoint pipe
*
* This function tears down a pipe previously created by calling
* usbTargPipeCreate().
*
* RETURNS: OK, or ERROR if unable to destroy pipe.
* 
* ERRNO:
* \is
* \i S_usbTargLib_TCD_FAULT
* Error occured in TCD.
* \ie
*/

STATUS usbTargPipeDestroy
    (
    USB_TARG_PIPE pipeHandle		/* pipe to be destroyed */
    )
    {
    pTARG_TCD	pTcd = NULL;		/* TARG_TCD */
    pTARG_PIPE	pPipe = NULL;		/* TARG_PIPE */
    STATUS	status = ERROR;

    /* WindView Instrumentation */

    USB_TARG_LOG_EVENT(USB_TARG_PIPE_FUNC,
    "usbTargPipeDestroy entered ...", USB_TARG_WV_FILTER);   

    /* Validate parameters */

    if ((status = validatePipe (pipeHandle, &pPipe)) == OK)
        {
        pTcd = pPipe->pTargTcd;
        if ((status = usbHalTcdEndpointRelease (&pTcd->tcdNexus,
                                                pPipe->pHalPipeHandle)) != OK)
            {

            /* WindView Instrumentation */

            USB_TARG_LOG_EVENT(USB_TARG_PIPE_FUNC,
            "usbTargPipeDestroy exiting: Error releasing endpoint...",
            USB_TARG_WV_FILTER);   

            return ossStatus (S_usbTargLib_TCD_FAULT);
            }
        /* Destroy the handle */

        usbHandleDestroy (pPipe->pipeHandle);

        /* Free memory */

        OSS_FREE (pPipe);
        }

    /* WindView Instrumentation */

    USB_TARG_LOG_EVENT(USB_TARG_PIPE_FUNC,
    "usbTargPipeDestroy exiting...", USB_TARG_WV_FILTER);   

    return status;
    }

/*******************************************************************************
*
* usbTargTransfer - to transfer data through a pipe
*
* This function is used to initiate an transfer on the pipe indicated
* by <pipeHandle>.  The transfer is described by an ERP, or endpoint
* request packet, which must be allocated and initialized by the caller
* prior to invoking usbdTargTransfer().
*
* RETURNS: OK or Error if not able to transfer data.
*
* ERRNO:
* \is
* \i S_usbTargLib_TCD_FAULT
* Fault occured in TCD.
*
* \i S_usbTargLib_BAD_PARAM
* Bad parameter is passed.
* \ie
*/

STATUS usbTargTransfer
    (
    USB_TARG_PIPE	pipeHandle,	/* handle to the pipe */
    pUSB_ERP		pErp		/* ERP to be transfered */
    )
    {
    pTARG_PIPE	pPipe = NULL;		/* TARG_PIPE */
    pTARG_TCD	pTcd = NULL;		/* TARG_TCD */
    STATUS	status = OK;

    /* WindView Instrumentation */

    USB_TARG_LOG_EVENT(USB_TARG_PIPE_FUNC,
    "usbTargTransfer entered ...", USB_TARG_WV_FILTER);   

    /* Validate parameters */

    if (pErp == NULL)
        {

        /* WindView Instrumentation */

        USB_TARG_LOG_EVENT(USB_TARG_PIPE_FUNC,
        "usbTargTransfer exiting: No ERP to transfer",
        USB_TARG_WV_FILTER);   

        return ossStatus (S_usbTargLib_BAD_PARAM);
        }  

    /* Retrieve the TARG_PIPE pointer from pipeHandle */

    if ((status = validatePipe (pipeHandle, &pPipe)) != OK)
        {

        /* WindView Instrumentation */

        USB_TARG_LOG_EVENT(USB_TARG_PIPE_FUNC,
        "usbTargTransfer exiting: Wrong Pipe Handle...",
        USB_TARG_WV_FILTER);   

        return ossStatus (S_usbTargLib_BAD_PARAM);
        }  

    pTcd = pPipe->pTargTcd;

    /* Populate pipeHandle & targCallback of the ERP structure */

    pErp->pPipeHandle = pPipe->pHalPipeHandle;
    pErp->targCallback = usbTargErpCallback;

    /* call usbTcdSubmit to submit the TCD */

    if ((status = usbHalTcdErpSubmit (&pTcd->tcdNexus , pErp)) != OK)
        status = ossStatus ( S_usbTargLib_TCD_FAULT);

    /* WindView Instrumentation */

    USB_TARG_LOG_EVENT(USB_TARG_PIPE_FUNC,
    "usbTargTransfer exiting...", USB_TARG_WV_FILTER);   

    return status;
    }


/*************************************************************************
*
* usbTargTransferAbort - cancels a previously submitted USB_ERP
*
* This function aborts an ERP which was previously submitted through
* a call to usbTargTransfer().
*
* RETURNS: OK, or ERROR if unable to cancel USB_ERP
*
* ERRNO:
* \is
* \i S_usbTargLib_TCD_FAULT
* Fault occured in TCD.
*
* \i S_usbTargLib_BAD_PARAM
* Bad parameter is passed.
* \ie
*/


STATUS usbTargTransferAbort
    (
    USB_TARG_PIPE	pipeHandle,	/* pipe for transfer to abort */
    pUSB_ERP		pErp		/* ERP to be aborted */
    )
    {
    pTARG_PIPE	pPipe = NULL;		/* TARG_PIPE */
    pTARG_TCD	pTcd = NULL;		/* TARG_TCD */
    STATUS	status = ERROR;

    /* WindView Instrumentation */

    USB_TARG_LOG_EVENT(USB_TARG_PIPE_FUNC,
    "usbTargTransferAbort entered ...", USB_TARG_WV_FILTER);   

    /* Validate parameters */

    if (pErp == NULL)
        {

        /* WindView Instrumentation */

        USB_TARG_LOG_EVENT(USB_TARG_PIPE_FUNC,
        "usbTargTransferAbort exiting: No ERP to transfer",
        USB_TARG_WV_FILTER);   

        return ossStatus (S_usbTargLib_BAD_PARAM);
        }  

    if ((status = validatePipe (pipeHandle, &pPipe)) == OK)
        {
        pTcd = pPipe->pTargTcd;

        /* cancel the ERP */

        if ((status = usbHalTcdErpCancel (&pTcd->tcdNexus, pErp)) != OK)
            status = ossStatus (S_usbTargLib_TCD_FAULT);
        }

    /* WindView Instrumentation */

    USB_TARG_LOG_EVENT(USB_TARG_PIPE_FUNC,
    "usbTargTransferAbort exiting...", USB_TARG_WV_FILTER);   

    return status;
    }


/*******************************************************************************
*
* usbTargPipeStatusSet - sets pipe stalled/unstalled status
*
* If the target application detects an error while servicing a pipe,
* it may choose to stall the endpoint(s) associated with that pipe.
*  This function allows the caller to set the state of a pipe as
* "stalled" or "un-stalled".
*
* RETURNS: OK, or ERROR if unable to set indicated state
*
* ERRNO:
* \is
* \i S_usbTargLib_TCD_FAULT
* Fault occured in TCD.
* \ie
*/

STATUS usbTargPipeStatusSet
    (
    USB_TARG_PIPE	pipeHandle,	/* Handle to the pipe */
    UINT16		state		/* State of the pipe to be set */
    )
    {
    pTARG_TCD	pTcd = NULL;		/* TARG_TCD */
    pTARG_PIPE	pPipe = NULL;		/* TARG_PIPE */
    STATUS	status = ERROR;

    /* WindView Instrumentation */

    USB_TARG_LOG_EVENT(USB_TARG_PIPE_FUNC,
    "usbTargPipeStatusSet entered ...", USB_TARG_WV_FILTER);   

    /* Validate parameters */

    if ((status = validatePipe (pipeHandle , &pPipe)) == OK)
        {

        /* Call usbTcdEndpointStateSet to set the state of the pipe */

        pTcd = pPipe->pTargTcd;
        if (usbHalTcdEndpointStateSet (&pTcd->tcdNexus, 
                                       pPipe->pHalPipeHandle, state)!= OK)
  
            status = ossStatus (S_usbTargLib_TCD_FAULT);
        }

    /* WindView Instrumentation */

    USB_TARG_LOG_EVENT(USB_TARG_PIPE_FUNC,
    "usbTargPipeStatusSet exiting...", USB_TARG_WV_FILTER);   

    return status;
    }

/*******************************************************************************
*
* usbTargPipeStatusGet - returns the endpoint status
*
* This function is used to get the status of the pipeas per GET_STATUS
* request. The status of the pipe is stored in the pointer variable pBuf
*
* RETURNS: OK, or ERROR if unable to get  state
*
* ERRNO:
* \is
* \i S_usbTargLib_TCD_FAULT
* Fault occured in TCD.
* \ie
*/

STATUS usbTargPipeStatusGet
    (
    USB_TARG_PIPE	pipeHandle,	/* Handle to the pipe */
    pUINT8		pBuf		/* Buffer to hold the pipe status */
    )
    {
    pTARG_TCD	pTcd = NULL;		/* TARG_TCD */
    pTARG_PIPE	pPipe = NULL;		/* TARG_PIPE */
    STATUS	status = ERROR;

    /* WindView Instrumentation */

    USB_TARG_LOG_EVENT(USB_TARG_PIPE_FUNC,
    "usbTargPipeStatusGet entered ...", USB_TARG_WV_FILTER);   

    /* Validate parameters */

    if ((status = validatePipe (pipeHandle , &pPipe)) == OK)
	{

        /* Call usbTcdEndpointStatusGet to get the state of the pipe */

        pTcd = pPipe->pTargTcd;
        if (usbHalTcdEndpointStatusGet ( &pTcd->tcdNexus,
                                         pPipe->pHalPipeHandle , pBuf)!= OK)
            status = ossStatus ( S_usbTargLib_TCD_FAULT);
        }

    /* WindView Instrumentation */

    USB_TARG_LOG_EVENT(USB_TARG_PIPE_FUNC,
    "usbTargPipeStatusGet exiting...", USB_TARG_WV_FILTER);   

    return status;
    }

/*******************************************************************************
*
* usbTargErpCallback - invoked when ERP completes
*
* The TCD invokes this callback when an ERP completes.	This gives us the
* opportunity to monitor ERP execution.  We reflect the callback to the
* calling application after we finish our processing.
*
* RETURNS: N/A
*
* ERRNO:
*   None.
*
* \NOMANUAL
*/

LOCAL VOID usbTargErpCallback
    (
    pVOID	pErp			/* ptr to ERP */
    )
    {
    pUSB_ERP	pErpCallback = (pUSB_ERP) pErp;

    /* Validate Parameter */

    if (pErp == NULL)
        return;

    /* Invoke the user's callback routine */

    if (pErpCallback->userCallback != NULL)
        (*pErpCallback->userCallback) (pErpCallback);

    return;
    }


/*******************************************************************************
*
* validatePipe - validates a pipe handle
*
* This function is used to validate the pipe handle.
* RETURNS: OK or ERROR if unable to validate pipe handle
*
* ERRNO:
* \is
* \i S_usbTargLib_BAD_HANDLE
* Wrong handle value obtained.
* \ie
*
* \NOMANUAL
*/

LOCAL STATUS validatePipe
    (
    USB_TARG_PIPE	pipeHandle,	/* handle to be validated */
    struct targPipe	** ppPipe	/* handle parameter on return */
    )
    {
    if (usbHandleValidate (pipeHandle, TARG_PIPE_SIG, (pVOID *) ppPipe) != OK)
        return ossStatus (S_usbTargLib_BAD_HANDLE);

    return OK;
    }