usbtarglib.c

This the USB source code for vxworks5.5. It has OSS library source code and also the complete targ

*
* 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;
    }


/***************************************************************************
*
* usbTargPipeCreate - Creates a pipe for communication on an endpoint
*
* This function creates a pipe attached to a specific target endpoint.
* <endpointId> is the TCD-assigned ID of the target endpoint to be used
* for this pipe and <endpointNum> is the device endpoint number to which
* the endpoint will respond.  Some TCDs allow the flexible assignment of
* endpoints to specific endpoint numbers while others do not.  The
* endpointNumMask field in the USB_TARG_ENDPOINT_INFO structure is a bit
* mask that reveals which endpoint numbers are supported by a given
* endpoint.  (e.g., If bit 0 is '1', then the corresponding endpoint can
* be assigned to endpoint #0, and so forth).
*
* By convention, each of the endpoints exposed by the TCD is unidirectional.
* Control pipes are bidirectional, and therefore logically occupy two
* endpoints, one IN endpoint and one OUT endpoint, both with the same
* endpointNum.	When creating a control pipe, the caller must specify the
* second endpoint Id in <endpointId2>.	In this case, <endpointId> must
* specify the OUT endpoint, and <endpointId2> must specify the IN endpoint.
* <endpointId2> should be 0 for other types of pipes.
*
* <configuration> and <interface> specify the device configuration and
* interface with which the endpoint (and pipe) is associated.  The 
* usbTargLib uses these values to reset pipes as appropriate when
* USB "configuration events" are detected.  (In response to a USB
* configuration event, the data toggle for a given endpoint is always
* reset to DATA0.)
*
* <transferType> specifies the type of transfers to be performed as
* USB_XFRTYPE_xxxx.  <direction> specifies the direction of the pipe as
* USB_DIR_xxxx.  Control pipes specify direction as USB_DIR_INOUT.
*
* The caller must be aware that not all endpoints are capable of all types
* of transfers.  Prior to assigning an endpoint for a particular purpose,
* the caller should interrogate the USB_TARG_ENDPOINT_INFO structure for
* the endpoint to ensure that it supports the indicated type of transfer.
*
* RETURNS: OK, or ERROR if unable to create pipe
*
* ERRNO:
*   S_usbTargLib_BAD_PARAM
*   S_usbTargLib_ENDPOINT_IN_USE
*   S_usbTargLib_OUT_OF_MEMORY
*   S_usbTargLib_OUT_OF_RESOURCES
*   S_usbTargLib_TCD_FAULT
*/

STATUS usbTargPipeCreate
    (
    USB_TARG_CHANNEL targChannel,	/* target channel */
    UINT16 endpointId,			/* endpoint ID to use for pipe */
    UINT16 endpointId2, 		/* needed for control pipes only */
    UINT16 endpointNum, 		/* endpoint number to assign */
    UINT16 configuration,		/* associated configuration */
    UINT16 interface,			/* associated interface */
    UINT16 transferType,		/* USB_XFRTYPE_xxxx */
    UINT16 direction,			/* USB_DIR_xxxx */