usbtarglib.c

VxWorks下USB驱动的源代码！

                          pCHAR pMfg    /* usbTargLib manufacturer */
    )
{
    /* return version info */

    if (pVersion != NULL)
        *pVersion = TARG_VERSION;

    if (pMfg != NULL)
        strncpy (pMfg, TARG_MFG, USBT_NAME_LEN);

    return OK;
}


/***************************************************************************
*
* doShutdown - shut down usbTargLib
*
* RETURNS: N/A
*/

LOCAL VOID
doShutdown (void)
{
    pTARG_TCD pTcd;

    /* Shut down all target channels */

    while ((pTcd = usbListFirst (&tcdList)) != NULL)
        destroyTcd (pTcd);

    /* Release other resources. */

    if (targMutex != NULL) {
        OSS_MUTEX_DESTROY (targMutex);
        targMutex = NULL;
    }

    /* Shut down handle library */

    if (handleInitialized) {
        usbHandleShutdown ();
        handleInitialized = FALSE;
    }

    /* Shut down ossLib */

    if (ossInitialized) {
        ossShutdown ();
        ossInitialized = FALSE;
    }
}


/***************************************************************************
*
* usbTargInitialize - Initializes usbTargLib
*
* usbTargInitialize() must be called at least once prior to calling other
* usbTargLib functions except for usbTargVersionGet().	usbTargLib maintains
* an internal initialization count, so calls to usbTargInitialize() may be 
* nested.  
*
* RETURNS: OK, or ERROR if unable to initialize usbTargLib.
*
* ERRNO:
*   S_usbTargLib_OUT_OF_RESOURCES
*   S_usbTargLib_GENERAL_FAULT;
*/

STATUS
usbTargInitialize (void)
{
    int status = OK;


    if (initCount == 0) {
        /* Initialize local data */

        memset (&tcdList, 0, sizeof (tcdList));
        ossInitialized = FALSE;
        handleInitialized = FALSE;

        /* Initialize ossLib */

        if (ossInitialize () != OK)
            status = S_usbTargLib_GENERAL_FAULT;
        else {
            ossInitialized = TRUE;

            /* Intialize usbHandleLib */

            if (usbHandleInitialize (0) != OK)
                status = S_usbTargLib_GENERAL_FAULT;
            else {
                handleInitialized = TRUE;

                if (OSS_MUTEX_CREATE (&targMutex) != OK)
                    status = S_usbTargLib_OUT_OF_RESOURCES;
            }
        }
    }

    if (status == OK)
        initCount++;
    else
        doShutdown ();

    return ossStatus (status);
}


/***************************************************************************
*
* usbTargShutdown - Shuts down usbTargLib
*
* usbTargShutdown() should be called once for every successful call to
* usbTargInitialize().	usbTargShutdown() closes any open target channels
* and releases resources allocated by the usbTargLib.
*
* RETURNS: OK, or ERROR if unable to shut down usbTargLib.
*
* ERRNO:
*   S_usbTargLib_NOT_INITIALIZED
*/

STATUS
usbTargShutdown (void)
{
    /* Are we initialized? */

    if (initCount == 0)
        return ossStatus (S_usbTargLib_NOT_INITIALIZED);

    if (--initCount == 0)
        doShutdown ();

    return OK;
}


/***************************************************************************
*
* usbTargTcdAttach - Attaches and initializes a USB target controller driver
*
* This function attaches a USB TCD (Target Controller Driver) to usbTargLib.
* A TCD needs to be attached to usbTargLib before any other USB operations
* may be performed on the target channel it manages.
*
* <tcdExecFunc> is the primary entry point of the TCD being attached and
* <tcdParam> is a TCD-defined parameter which is passed to the TCD's attach
* function.  Generally, the <tcdParam> is points to a TCD-defined structure
* which identifies the characteristics of the target controller hardware
* (i.e., base I/O address, IRQ channel, etc.).	Each call to usbTargTcdAttach()
* enables one and only one target channel.
*
* <pCallbacks> points to a USB_TARG_CALLBACK_TABLE structure in which the
* caller has stored the addresses of callbacks for events in which it is
* interested in being notified.  <callbackParam> is a caller-defined parameter 
* which is passed to each callback function when the callbacks are invoked by
* usbTargLib.
*
* <pTargChannel> points to a USB_TARG_CHANNEL variable allocated by the caller
* which receives a handle to the target channel created by this call to
* usbTargTcdAttach().
*
* <pNumEndpoints> and <ppEndpoints> receive the count of target endpoints and
* a pointer to an array of USB_TARG_ENDPOINT_INFO structures, respectively.
* The caller can use this information to assign endpoints to pipes.
*
* RETURNS: OK, or ERROR if unable to attach/initialize TCD.
*
* ERRNO:
*   S_usbTargLib_BAD_PARAM
*   S_usbTargLib_OUT_OF_MEMORY
*   S_usbTargLib_OUT_OF_RESOURCES
*   S_usbTargLib_TCD_FAULT
*   S_usbTargLib_APP_FAULT
*/

STATUS usbTargTcdAttach (USB_TCD_EXEC_FUNC tcdExecFunc, /* TCD entry point */
                         pVOID tcdParam,    /* TCD parameter */
                         pUSB_TARG_CALLBACK_TABLE pCallbacks,   /* caller-supplied callbacks */
                         pVOID callbackParam,   /* caller-defined callback param */
                         pUSB_TARG_CHANNEL pTargChannel,    /* handle to target on return */
                         pUINT16 pNumEndpoints, /* bfr to receive nbr of endpoints */
                         pUSB_TARG_ENDPOINT_INFO * ppEndpoints  /* bfr to rcv ptr to endpt array */
    )
{
    pTARG_TCD pTcd;
    int status;

    /* Validate parameters */

    if (tcdExecFunc == NULL || pCallbacks == NULL || pTargChannel == NULL ||
        pNumEndpoints == NULL || ppEndpoints == NULL)
        return ossStatus (S_usbTargLib_BAD_PARAM);

    if ((status = validateTarg (NULL, NULL)) != OK)
        return status;


    OSS_MUTEX_TAKE (targMutex, OSS_BLOCK);

    /* Allocate a TARG_TCD to manage this channel */

    if ((pTcd = OSS_CALLOC (sizeof (*pTcd))) == NULL)
        status = S_usbTargLib_OUT_OF_MEMORY;

    if (status == OK) {
        /* Initialize TCD */

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

        if (usbHandleCreate (TARG_TCD_SIG, pTcd, &pTcd->targChannel) != OK)
            status = S_usbTargLib_OUT_OF_RESOURCES;
    }

    if (status == OK) {
        /* Try to initialize the TCD */

        if (usbTcdAttach (tcdExecFunc, tcdParam, &pTcd->tcdNexus,
                          usbTargManagementCallback, pTcd, &pTcd->speed,
                          &pTcd->numEndpoints, &pTcd->pEndpoints) != OK) {
            status = S_usbTargLib_TCD_FAULT;
        } else {
            /* Make sure the target exposed at least two endpoints, aka, the
             * OUT and IN endpoints we need for the default control chanenl. */

            if (pTcd->numEndpoints < 2 || pTcd->pEndpoints == NULL)
                status = S_usbTargLib_TCD_FAULT;
        }
    }

    if (status == OK) {
        /* Create a default control channel for this target.
         *
         * NOTE: By convention, the target always places the endpoints which
         * are best suited for the default control channel at the beginning
         * of the endpoint array, with the USB_DIR_OUT (host->device) endpoint
         * first, followed by the USB_DIR_IN endpoint.
         */

        if ((status = usbTargPipeCreate (pTcd->targChannel,
                                         pTcd->pEndpoints[0].endpointId,
                                         pTcd->pEndpoints[1].endpointId,
                                         USB_ENDPOINT_DEFAULT_CONTROL, NO_CONFIGURATION,
                                         NO_INTERFACE, USB_XFRTYPE_CONTROL, USB_DIR_INOUT,
                                         &pTcd->controlPipe)) == OK) {
            /* Start listening for requests on the default control pipe. */

            status = initSetupErp (pTcd);
        }
    }

    if (status == OK) {
        /* Link the TCD to the list of managed TCDs. */

        usbListLink (&tcdList, pTcd, &pTcd->tcdLink, LINK_TAIL);

        *pTargChannel = pTcd->targChannel;
        *pNumEndpoints = pTcd->numEndpoints;
        *ppEndpoints = pTcd->pEndpoints;
    }

    if (status == OK) {
        /* Invoke the target application's mngmtFunc to notify it that 
         * the attach is complete. 
         */

        if (mngmtFunc (pTcd, TCD_MNGMT_ATTACH) != OK)
            status = S_usbTargLib_APP_FAULT;
    }

    /* If we failed to initialized, clean up the TCD. */

    if (status != OK)
        destroyTcd (pTcd);


    OSS_MUTEX_RELEASE (targMutex);

    return ossStatus (status);
}


/***************************************************************************
*
* usbTargTcdDetach - Detaches a USB target controller driver
*
* This function detaches a USB TCD which was previously attached to the
* usbTargLib by calling usbTargTcdAttach().  <targChannel> is the handle
* of the target channel originally returned by usbTargTcdAttach().
*
* The usbTargLib automatically terminates any pending transactions on the
* target channel being detached and releases all internal usbTargLib
* resources allocated on behalf of the channel.  Once a target channel
* has been detached by calling this function, the <targChannel> is no
* longer valid.
*
* RETURNS: OK, or ERROR if unable to detach TCD.
*/

STATUS usbTargTcdDetach (USB_TARG_CHANNEL targChannel   /* target to detach */
    )
{
    pTARG_TCD pTcd;
    STATUS status;


    OSS_MUTEX_TAKE (targMutex, OSS_BLOCK);

    /* Validate parameters */

    if ((status = validateTarg (targChannel, &pTcd)) == OK) {
        /* Destroy target channel */

        destroyTcd (pTcd);
    }

    OSS_MUTEX_RELEASE (targMutex);

    return status;
}


/***************************************************************************
*
* usbTargEndpointInfoGet - Retrieves endpoint information for channel
*
* This function retrieves the number of endpoints on <targChannel> and
* returns a pointer to the base of the USB_TARG_ENDPOINT_INFO array.
*
* RETURNS: OK, or ERROR if unable to return target endpoint information
*/

STATUS usbTargEndpointInfoGet (USB_TARG_CHANNEL targChannel,    /* target channel */
                               pUINT16 pNumEndpoints,   /* receives nbr of endpoints */
                               pUSB_TARG_ENDPOINT_INFO * ppEndpoints    /* receives ptr to array */
    )
{
    pTARG_TCD pTcd;
    STATUS status;


    OSS_MUTEX_TAKE (targMutex, OSS_BLOCK);

    /* Validate parameters */

    if ((status = validateTarg (targChannel, &pTcd)) == OK) {
        if (pNumEndpoints != NULL)
            *pNumEndpoints = pTcd->numEndpoints;

        if (ppEndpoints != NULL)
            *ppEndpoints = pTcd->pEndpoints;
    }


    OSS_MUTEX_RELEASE (targMutex);

    return ossStatus (status);
}


/***************************************************************************
*
* usbTargEnable - Enables target channel onto USB
*
* After attaching a TCD to usbTargLib and performing any other application-
* specific initialization that might be necessary, this function should be
* called to enable a target channel.  The USB target controlled by the TCD
* will not appear as a device on the USB until this function has been called.
*
* RETURNS: OK, or ERROR if unable to enable target channel.
*
* ERRNO:
*   S_usbTargLib_TCD_FAULT
*/

STATUS usbTargEnable (USB_TARG_CHANNEL targChannel  /* target to enable */
    )
{
    pTARG_TCD pTcd;
    STATUS status;


    OSS_MUTEX_TAKE (targMutex, OSS_BLOCK);

    /* Validate parameters */

    if ((status = validateTarg (targChannel, &pTcd)) == OK) {
        /* Enable target channel */

        if (usbTcdEnable (&pTcd->tcdNexus) != OK)
            status = S_usbTargLib_TCD_FAULT;
    }

    OSS_MUTEX_RELEASE (targMutex);

    return status;
}


/***************************************************************************
*
* usbTargDisable - Disables a target channel
*
* This function is the counterpart to the usbTargEnable() function.  This
* function disables the indicated target channel.
*
* RETURNS: OK, or ERROR if unable to disable the target channel.
*
* ERRNO:
*   S_usbTargLib_TCD_FAULT
*/

STATUS usbTargDisable (USB_TARG_CHANNEL targChannel /* target to disable */
    )
{
    pTARG_TCD pTcd;
    STATUS status;


    OSS_MUTEX_TAKE (targMutex, OSS_BLOCK);

    /* Validate parameters */

    if ((status = validateTarg (targChannel, &pTcd)) == OK) {
        /* Enable target channel */

        if (usbTcdDisable (&pTcd->tcdNexus) != OK)
            status = S_usbTargLib_TCD_FAULT;
    }

    OSS_MUTEX_RELEASE (targMutex);

    return status;
}