usbtarginitexit.c

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

/* usbTargInitExit.c - USB Initialization/Uninitialization modules */

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

/*
Modification history
--------------------
01d,17sep04,hch  merge for windview instrumentation
01c,15jun04,hch  Merge after ISP1582 driver testing done on MIPS, SH.
01b,11may04,hch  merge after D12 driver testing
01b,19jul04,ami Coding Convention Changes
01a,30mar04,ami First
*/

/*
DESCRIPTION

This module implements the hardware-independent USB target API. It provides
the required interfaces for initializing and un-initializing the USB Target
Library and the TCD.

USB Target Library must be initialized by calling usbTargInitialize().	Before
operation can begin, at least one TCD must be attached to usb Target Library
by calling usbTargTcdAttach().	In response to a successful TCD
attachment. A handle is returned.This handle must be used in all subsequent
calls to usbTargLib to identify a given target channel.

USB devices (targets) almost never initiate activity on the USB (the
exception being RESUME signalling).  So, as part of the call to
usbTargTcdAttach(), the caller must provide a pointer to a
USB_TARG_CALLBACK_TABLE structure.  This table contains a collection of
callback function pointers initialized by the caller prior to invoking
the usbTargTcdAttach() function.  Through these callbacks, usbTargLib
notifies the calling application of various USB events and requests from
the host.

INCLUDE FILES: usb/usbPlatform.h, usb/ossLib.h, usb/usb.h, usb/usbListLib.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/usbListLib.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"     

/* globals */

UINT16		initCount = 0;	/* number of times initialization is done */

MUTEX_HANDLE	targMutex;	/* mutex for multiple TCD data structurs */

LIST_HEAD	tcdList;	/* list to hold the TCDs */


/*******************************************************************************
*
* usbTargInitialize - initializes the USB Target Library
*
* This routine is used to initialize the USB Target Library. It 
* initializes the OS library, creates the handles and mutexes.
*
* RETURNS: OK or ERROR
*
* ERRNO:
* \is
* \i S_usbTargLib_GENERAL_FAULT
* Fault occured in software layers.
*
* \i S_usbTargLib_OUT_OF_RESOURCES
* Sufficient resources are not available.
* \ie
*/

STATUS usbTargInitialize ( void )
    {
    UINT32	status = OK;

    /* WindView Instrumentation */

    USB_TARG_LOG_EVENT(USB_TARG_INIT_EXIT,
    "usbTargInitialize entered ...", USB_TARG_WV_FILTER);   

    /*
     * If initCount is not 0, USB Target Library is already initilized.
     * Initialize only if the initCount is 0
     */

    if ( initCount == 0 )
        {

        /* Initialize the OS library */

        if (ossInitialize () != OK)
            {

            /* WindView Instrumentation */

            USB_TARG_LOG_EVENT(USB_TARG_INIT_EXIT,
            "usbTargInitialize exiting: ossInitialize returned error...",
            USB_TARG_WV_FILTER);   

    	    status = ossStatus(S_usbTargLib_GENERAL_FAULT);
    	    return status;
	    }

        /* Initialize the Handles */

        if ( usbHandleInitialize (0) != OK)
	    {

            /* WindView Instrumentation */

            USB_TARG_LOG_EVENT(USB_TARG_INIT_EXIT,
            "usbTargInitialize exiting: usbHandleInitialize returned error...",
            USB_TARG_WV_FILTER);   

    	    status = ossStatus(S_usbTargLib_GENERAL_FAULT);

	    /* Release the earlier allocated resource */

	    ossShutdown ();
    	    return status;
	    }

	/* Create the mutex for handling the Data Structure */

	if ( OSS_MUTEX_CREATE ( &targMutex ) != OK )
	    {

            /* WindView Instrumentation */

            USB_TARG_LOG_EVENT(USB_TARG_INIT_EXIT,
            "usbTargInitialize exiting: error creating hutex...",
            USB_TARG_WV_FILTER);   

	    status = ossStatus(S_usbTargLib_OUT_OF_RESOURCES);

	    /* Release the earlier allocated resource */

	    usbHandleShutdown ();
	    ossShutdown ();
	    return status;
	    }
	}

    /* Increment the initCount variable */

    initCount++;

    /* WindView Instrumentation */

    USB_TARG_LOG_EVENT(USB_TARG_INIT_EXIT,
    "usbTargInitialize exiting ...", USB_TARG_WV_FILTER);   

    return OK;
    }


/*******************************************************************************
*
* usbTargShutdown - shutdown the USB target library
*
* This function is used to shutdown the USB Target Library. It frees the
* various resources alloted.
*
* RETURNS: OK or ERROR
*
* ERRNO:
* \is
* \i S_usbTargLib_NOT_INITIALIZED
* Initialized varable is used.
*
* \i S_usbTargLib_TCD_FAULT
* Fault occured in TCD.
*
* \i S_usbTargLib_APP_FAULT
* Application Specific fault occured.
* \ie
*/

STATUS usbTargShutdown (void)
    {
    pTARG_TCD	pTcd = NULL;	/* TARG_TCD */
    UINT32	status = OK;

    /* WindView Instrumentation */

    USB_TARG_LOG_EVENT(USB_TARG_INIT_EXIT,
    "usbTargShutdown entered ...", USB_TARG_WV_FILTER);   

    if (initCount == 0)
        
        /* Target library is not initialized */

        return ossStatus (S_usbTargLib_NOT_INITIALIZED);

    /* Decrement the initCount */

    if ( initCount-- != 0)
    	return OK;

    OSS_MUTEX_TAKE ( targMutex , OSS_BLOCK );

    /* Shut down all target channels */

    while ((pTcd = usbListFirst (&tcdList)) != NULL)
        {

        /* TCD is valid, Notify the target application  */

        if ((status = mngmtFunc ( pTcd, TARG_MNGMT_DETACH, NULL))!= OK )
            return ossStatus ( S_usbTargLib_APP_FAULT );

        /* Release the default control In endpoint */

        if (usbHalTcdEndpointRelease(&pTcd->tcdNexus,pTcd->defaultControlPipeIN)
            != OK)
            return ossStatus (S_usbTargLib_TCD_FAULT);

        /* Release the default control Out endpoint */

        if (usbHalTcdEndpointRelease(&pTcd->tcdNexus,pTcd->defaultControlPipeOUT)
            !=OK)
            return ossStatus (S_usbTargLib_TCD_FAULT);

        /* Detach TCD */

        if (usbHalTcdDetach (&pTcd->tcdNexus) != OK )
            return ossStatus (S_usbTargLib_TCD_FAULT );

        /* Unlink the TCD */

        usbListUnlink (&pTcd->tcdLink);

        /* Release the memory for that TCD */

        OSS_FREE ( pTcd );
        }

    /* Un-initialize the OS & Handle Library and destroy the mutex */

    usbHandleShutdown ();
    ossShutdown ();
    OSS_MUTEX_DESTROY (targMutex);

    /* WindView Instrumentation */

    USB_TARG_LOG_EVENT(USB_TARG_INIT_EXIT,
    "usbTargShutdown exiting ...", USB_TARG_WV_FILTER);   

    /* return OK */

    return OK;
    }


/*******************************************************************************
*
* usbTargTcdAttach - to attach the TCD to the target library
*
* This function is used to attach the TCD to the Target Library.In response
* to a successful TCD attachment, usbTargLib returns a USB_TARG_CHANNEL
* handle to the caller.This handle must be used in all subsequent calls to
* usbTargLib to identify a given target channel.
*
* RETURNS: OK or ERROR
*
* ERRNO:
* \is
* \i S_usbTargLib_OUT_OF_MEMORY
* Memory not present to allocate variables.
*
* \i S_usbTargLib_TCD_FAULT
* Fault occured in TCD.
*
* \i S_usbTargLib_OUT_OF_RESOURCES
* Sufficient resources not available.
*
* \i S_usbTargLib_BAD_PARAM
* Bad parameter is passed.
*
* \i S_usbTargLib_APP_FAULT
* Application Specific Fault occured.
* \ie
*/

STATUS usbTargTcdAttach
    (
    USB_TCD_EXEC_FUNC	tcdExecFunc,	/* single entry point of the TCD */
    pVOID		tcdParam,	/* parameter passed to TCD */
    pUSB_TARG_CALLBACK_TABLE	pCallbacks, /*pointer to Callback functions */
    pVOID		callbackParam,	/* parameter to callback functions */
    pUSB_TARG_CHANNEL	pTargChannel    /* target channel handle returned */
    )
    {
    pTARG_TCD		pTcd = NULL;	/* TARG_TCD */
    USB_APPLN_DEVICE_INFO  deviceInfo;	/* USB_APPLN_DEVICE_INFO */

    /* WindView Instrumentation */

    USB_TARG_LOG_EVENT(USB_TARG_INIT_EXIT,
    "usbTargTcdAttach entered ...", USB_TARG_WV_FILTER);   

    /* Validate parameters */

    if ((tcdExecFunc == NULL) || (pCallbacks == NULL) || (tcdParam == NULL))
        {

        /* WindView Instrumentation */

        USB_TARG_LOG_EVENT(USB_TARG_INIT_EXIT,
        "usbTargTcdAttach exiting: Bad Parameters Received ...",
        USB_TARG_WV_FILTER);   

        return ossStatus (S_usbTargLib_BAD_PARAM);
        }
 
    /* Allocate memory for TARG_TCD */

    if ((pTcd = OSS_CALLOC (sizeof (TARG_TCD))) == NULL)
        {

        /* WindView Instrumentation */

        USB_TARG_LOG_EVENT(USB_TARG_INIT_EXIT,
        "usbTargTcdAttach exiting: Memory allocation failed ...",
        USB_TARG_WV_FILTER);   
   
        return ossStatus (S_usbTargLib_OUT_OF_MEMORY);
        }

    /* Initialize TCD */

    pTcd->pCallbacks = pCallbacks;
    pTcd->callbackParam = callbackParam;

    /* Create the mutex */

    if (OSS_MUTEX_CREATE(&pTcd->tcdMutex) != OK)
        {

        /* WindView Instrumentation */

        USB_TARG_LOG_EVENT(USB_TARG_INIT_EXIT,
        "usbTargTcdAttach exiting: Error creatint mutex...",
        USB_TARG_WV_FILTER);