/* usbHcdLib.c - Implements HCD functional API *//* Copyright 2000 Wind River Systems, Inc. *//*Modification history--------------------01e,26jan00,rcb  Change <bytesPerFrame> parameter in usbHcdPipeCreate() to		 <bandwidth> and redefined as UINT32.01d,29nov99,rcb  Remove obsolete function usbHcdBusReset().		 Increase frame number fields to 32 bits.01c,23nov99,rcb  Replace bandwidth alloc/release functions with pipe		 create/destroy functions...generalizes approach for use		 with OHCI HCD.01b,07sep99,rcb  Add support for management callback param in attach.		 Add set-bus-state API.01a,09jun99,rcb  First.*//*DESCRIPTIONThis file implements the functional interface to the HCD.*//* includes */#include "usb/usbPlatform.h"#include "string.h"#include "usb/usbHcdLib.h"	/* our API *//* functions *//***************************************************************************** hrbInit - Initialize an HCD request block** RETURNS: N/A*/LOCAL VOID hrbInit     (    pHRB_HEADER pHrb,     pHCD_NEXUS pNexus,     UINT16 function,    UINT16 totalLen    )    {    memset (pHrb, 0, totalLen);    if (pNexus != NULL)	pHrb->handle = pNexus->handle;    pHrb->function = function;    pHrb->hrbLength = totalLen;    }/***************************************************************************** usbHcdAttach - Attach to the HCD** Attempts to connect the caller to the HCD.  The <param> value is HCD-* implementation-specific.  Returns an HCD_CLIENT_HANDLE if the HCD was* able to initialize properly.	If <pBusCount> is not NULL, also returns* number of buses managed through this nexus.** <callback> is an optional pointer to a routine which should be invoked* if the HCD detects "management events" (e.g., remote wakeup/resume).* <callbackParam> is a caller-defined parameter which will be passed to* the <callback> routine each time it is invoked.** RETURNS: OK, or ERROR if unable to initialize HCD.*/STATUS usbHcdAttach    (    HCD_EXEC_FUNC hcdExecFunc,	    /* HCD's primary entry point */    pVOID param,		    /* HCD-specific param */    USB_HCD_MNGMT_CALLBACK callback,/* management callback */    pVOID callbackParam,	    /* parameter to management callback */    pHCD_NEXUS pNexus,		    /* nexus will be initialized on return */    pUINT16 pBusCount    )    {    HRB_ATTACH hrb;    STATUS s;    /* Initialize HRB */    hrbInit (&hrb.header, NULL, HCD_FNC_ATTACH, sizeof (hrb));    hrb.param = param;    hrb.mngmtCallback = callback;    hrb.mngmtCallbackParam = callbackParam;    /* Execute HRB */    s = (*hcdExecFunc) ((pVOID) &hrb);    /* Return results */        if (pNexus != NULL)	{	pNexus->hcdExecFunc = hcdExecFunc;	pNexus->handle = hrb.header.handle;	}    if (pBusCount != NULL)	*pBusCount = hrb.busCount;    return s;    }/***************************************************************************** usbHcdDetach - Detach from the HCD** Disconnects a caller which has previously attached to an HCD.** RETURNS: OK, or ERROR if unable to shutdown HCD.*/STATUS usbHcdDetach    (    pHCD_NEXUS pNexus		    /* client's nexus */    )    {    HRB_DETACH hrb;    /* Initialize HRB */    hrbInit (&hrb.header, pNexus, HCD_FNC_DETACH, sizeof (hrb));    /* Execute HRB */    return (*pNexus->hcdExecFunc) ((pVOID) &hrb);    }/***************************************************************************** usbHcdSetBusState - sets bus suspend/resume state** Sets the state for <bus> no as specified in <busState>.  <busState>* is a bit mask.  Typically, the caller will set USB_BUS_SUSPEND or* USB_BUS_RESUME to suspend or resume the indicated bus.** RETURNS: OK, or ERROR if unable to place bus in specified state*/STATUS usbHcdSetBusState    (    pHCD_NEXUS pNexus,		    /* client's nexus */    UINT16 busNo,		    /* bus number */    UINT16 busState		    /* desired bus state */    )    {    HRB_SET_BUS_STATE hrb;    /* Initialize HRB */    hrbInit (&hrb.header, pNexus, HCD_FNC_SET_BUS_STATE, sizeof (hrb));    hrb.busNo = busNo;    hrb.busState = busState;    /* Execute HRB */    return (*pNexus->hcdExecFunc) ((pVOID) &hrb);    }/***************************************************************************** usbHcdCurrentFrameGet - Returns current frame number for a bus** Returns the current <pFrameNo> and the frame window, <pFrameWindow>* for the specified bus.** RETURNS: OK, or ERROR if unable to retrieve current frame number.*/STATUS usbHcdCurrentFrameGet    (    pHCD_NEXUS pNexus,		    /* client's nexus */    UINT16 busNo,		    /* bus number */    pUINT32 pFrameNo,		    /* current frame number */    pUINT32 pFrameWindow	    /* size of frame window */    )    {    HRB_CURRENT_FRAME_GET hrb;    STATUS s;    /* Initialize HRB */    hrbInit (&hrb.header, pNexus, HCD_FNC_CURRENT_FRAME_GET, sizeof (hrb));    hrb.busNo = busNo;    /* Execute HRB */    s = (*pNexus->hcdExecFunc) ((pVOID) &hrb);    /* return results */    if (pFrameNo != NULL)	*pFrameNo = hrb.frameNo;    if (pFrameWindow != NULL)	*pFrameWindow = hrb.frameWindow;    return s;    }/***************************************************************************** usbHcdIrpSubmit - Submits an IRP to the HCD for execution** This function passes the <pIrp> to the HCD for scheduling.  The function* returns as soon as the HCD has queued/scheduled the IRP.  The <pIrp>* must include a non-NULL <callback> which will be invoked upon IRP* completion.** RETURNS: OK, or ERROR if unable to submit IRP for transfer.*/STATUS usbHcdIrpSubmit    (    pHCD_NEXUS pNexus,		    /* client's nexus */    HCD_PIPE_HANDLE pipeHandle,     /* pipe to which IRP is directed */    pUSB_IRP pIrp		    /* IRP to be executed */    )    {    HRB_IRP_SUBMIT hrb;    /* Initialize HRB */    hrbInit (&hrb.header, pNexus, HCD_FNC_IRP_SUBMIT, sizeof (hrb));    hrb.pipeHandle = pipeHandle;    hrb.pIrp = pIrp;    /* Execute HRB */    return (*pNexus->hcdExecFunc) ((pVOID) &hrb);    }/***************************************************************************** usbHcdIrpCancel - Requests the HCD to cancel a pending IRP** This function requests the HCD to cancel the specified <pIrp>.  If* the IRP can be canceled before it completes execution normally, its * result will be set to S_usbHcdLib_IRP_CANCELED and the IRPs callback* will be invoked.** There is no guarantee that an IRP, once submitted to the HCD, can be* canceled before it otherwise completes normally (or times out).** RETURNS: OK, or ERROR if unable to cancel transfer.*/STATUS usbHcdIrpCancel    (    pHCD_NEXUS pNexus,		    /* client's nexus */    pUSB_IRP pIrp		    /* IRP to be canceled */    )    {    HRB_IRP_CANCEL hrb;    /* Initialize HRB */    hrbInit (&hrb.header, pNexus, HCD_FNC_IRP_CANCEL, sizeof (hrb));    hrb.pIrp = pIrp;    /* Execute HRB */    return (*pNexus->hcdExecFunc) ((pVOID) &hrb);    }/***************************************************************************** usbHcdPipeCreate - create a pipe and calculate / reserve bus bandwidth** The USBD calls this function to notify the HCD that it is attempting to* create a new pipe.  The USBD passes the type of pipe in <transferType>.** If the pipe is an interrupt or isochronous pipe, the HCD calculates the * amount of time a transfer of a given number of bytes will require on the * bus - measured in nanoseconds (10E-9 seconds).  The formulas used here are * taken from Section 5.9.3 of Revision 1.1 of the USB spec.** If enough bus bandwidth is available, then that amount of bandwidth will* be reserved by the HCD.  Reserved bandwidth must later be released using * usbHcdPipeDestroy().** <transferType>, <direction>, and <speed> should describe the characteristics* of the pipe/transfer as USB_XFRTYPE_xxxx, USB_DIR_xxxx, and USB_SPEED_xxxx,* repsectively.  <packetSize> is the size of packets to be used.** For interrupt pipes, <bandwidth> is the total number of bytes which will * be sent each frame.  For isochronous pipes, <bandwidth> is the number of* bytes per second.  <bandwidth> should be 0 for control and bulk pipes.** The worst-case transfer time is returned in <pTime>.** The HCD will return an HCD_PIPE_HANDLE in <pPipeHandle>.  The USBD will use* this HCD_PIPE_HANDLE to identify the pipe in the future.  ** RETURNS: OK, or ERROR if unable to reserve bandwdith.*/STATUS usbHcdPipeCreate    (    pHCD_NEXUS pNexus,		    /* client's nexus */    UINT16 busNo,		    /* bus number for IRP */    UINT16 busAddress,		    /* bus address of USB device */    UINT16 endpoint,		    /* endpoint on device */    UINT16 transferType,	    /* transfer type */    UINT16 direction,		    /* pipe/transfer direction */    UINT16 speed,		    /* transfer speed */    UINT16 maxPacketSize,	    /* packet size */    UINT32 bandwidth,		    /* bandwidth required by pipe */    UINT16 interval,		    /* service interval */    pUINT32 pTime,		    /* calculated packet time on return */    pHCD_PIPE_HANDLE pPipeHandle    /* HCD pipe handle */    )    {    HRB_PIPE_CREATE hrb;    STATUS s;    /* Initialize HRB */    hrbInit (&hrb.header, pNexus, HCD_FNC_PIPE_CREATE, sizeof (hrb));    hrb.busNo = busNo;    hrb.busAddress = busAddress;    hrb.endpoint = endpoint;    hrb.transferType = transferType;    hrb.direction = direction;    hrb.speed = speed;    hrb.maxPacketSize = maxPacketSize;    hrb.bandwidth = bandwidth;    hrb.interval = interval;    /* Execute HRB */    s = (*pNexus->hcdExecFunc) ((pVOID) &hrb);    /* return results */    if (pTime != NULL)	*pTime = hrb.time;    if (pPipeHandle != NULL)	*pPipeHandle = hrb.pipeHandle;    return s;    }    /***************************************************************************** usbHcdPipeDestroy - destroys pipe and releases previously allocated bandwidth** Destroys the pipe identified by <pipeHandle> and releases any bandwidth used* by the pipe.	** RETURNS: OK, or ERROR if HCD fails to destroy pipe.*/STATUS usbHcdPipeDestroy    (    pHCD_NEXUS pNexus,		    /* client's nexus */    HCD_PIPE_HANDLE pipeHandle	    /* pipe to be destroyed */    )    {    HRB_PIPE_DESTROY hrb;    /* Initialize HRB */    hrbInit (&hrb.header, pNexus, HCD_FNC_PIPE_DESTROY, sizeof (hrb));    hrb.pipeHandle = pipeHandle;    /* Execute HRB */    return (*pNexus->hcdExecFunc) ((pVOID) &hrb);    }	/***************************************************************************** usbHcdPipeModify - modify characteristics of an existing pipe** Two characteristics of a pipe, the device's USB bus address and the * maximum packet size, may change after a pipe is first created.  Typically,* this will happen only with the default control pipe for a given device,* which must be created before issuing SET_ADDRESS to the device and before* reading the device descriptor to determine the maximum packet size supported* by the default control endpoint.  The USBD will typically use this function* to update either the <busAddress> or the <maxPacketSize> for the indicated* <pipeHandle>.  If either <busAddress> or <maxPacketSize> is 0, then the* corresponding pipe attribute remains unchanged.  ** RETURNS: OK, or ERROR if HCD fails to modify pipe*/STATUS usbHcdPipeModify    (    pHCD_NEXUS pNexus,		    /* client's nexus */    HCD_PIPE_HANDLE pipeHandle,     /* pipe to be modified */    UINT16 busAddress,		    /* new bus address or 0 */    UINT16 maxPacketSize	    /* new max packet size or 0 */    )    {    HRB_PIPE_MODIFY hrb;    /* Initialize HRB */    hrbInit (&hrb.header, pNexus, HCD_FNC_PIPE_MODIFY, sizeof (hrb));    hrb.pipeHandle = pipeHandle;    hrb.busAddress = busAddress;    hrb.maxPacketSize = maxPacketSize;    /* Execute HRB */    return (*pNexus->hcdExecFunc) ((pVOID) &hrb);    }	/***************************************************************************** usbHcdSofIntervalGet - retrieves SOF interval for a bus** Returns the SOF interval for <busNo> in <pSofInterval>.  The SOF * interval is expressed in terms of high-speed bit times, and is typically* close to 12,000.** RETURNS: OK, or ERROR if HCD failed to retrieve SOF interval*/STATUS usbHcdSofIntervalGet    (    pHCD_NEXUS pNexus,		    /* client's nexus */    UINT16 busNo,		    /* bus number */    pUINT16 pSofInterval	    /* bfr to receive SOF interval */    )    {    HRB_SOF_INTERVAL_GET_SET hrb;    STATUS s;    /* Initialize HRB */    hrbInit (&hrb.header, pNexus, HCD_FNC_SOF_INTERVAL_GET, sizeof (hrb));    hrb.busNo = busNo;    /* Execute HRB */    s = (*pNexus->hcdExecFunc) ((pVOID) &hrb);    /* return results */    if (pSofInterval != NULL)	*pSofInterval = hrb.sofInterval;    return s;    }	/***************************************************************************** usbHcdSofIntervalSet - sets SOF interval for a bus** Sets the SOF interval for <busNo> to <sofInterval>.  <sofInterval>* must express the new SOF interval in terms of high-speed bit times, and* should be in the neighborhood of 12,000.  Certain HCD implementations* may impose narrower or wider limits on the allowable <sofInterval>.** RETURNS: OK, or ERROR if HCD failed to set SOF interval.*/STATUS usbHcdSofIntervalSet    (    pHCD_NEXUS pNexus,		    /* client's nexus */    UINT16 busNo,		    /* bus number */    UINT16 sofInterval		    /* new SOF interval */    )    {    HRB_SOF_INTERVAL_GET_SET hrb;    /* Initialize HRB */    hrbInit (&hrb.header, pNexus, HCD_FNC_SOF_INTERVAL_SET, sizeof (hrb));    hrb.busNo = busNo;    hrb.sofInterval = sofInterval;    /* Execute HRB */    return (*pNexus->hcdExecFunc) ((pVOID) &hrb);    }	/* End of file. */