/* usbMouseLib.c - USB mouse class drive with vxWorks SIO interface *//* Copyright 2000-2002 Wind River Systems, Inc. *//*modification history--------------------01g,30oct04,hch  SPR #101127 and 9873101f,15oct04,ami  Apigen Changes01e,03aug04,ami  Warning Messages Removed01e,12jan04,cfc  merge synchronization fix01d,23sep03,cfc  Fixed Idle timeout issue01c,29oct01,wef  Remove automatic buffer creations and repalce with OSS_MALLOC.01b,20mar00,rcb  Re-write code to fetch maxPacketSize from endpoint descriptor	 	 on machines which don't support non-aligned word access.	 	 Allocate "report" structure separately from SIO_CHAN in order	 	 to avoid cache problems on MIPS platform.01a,07oct99,rcb  written.*//*DESCRIPTIONThis module implements the USB mouse class driver for the vxWorks operatingsystem.  This module presents an interface which is a superset of the vxWorksSIO (serial IO) driver model.  That is, this driver presents the external APIswhich would be expected of a standard "multi-mode serial (SIO) driver" andadds certain extensions which are needed to address adequately the requirementsof the hot-plugging USB environment.USB mice are described as part of the USB "human interface device" classspecification and related documents.  This driver concerns itself only with USBdevices which claim to be mouses as set forth in the USB HID specificationand ignores other types of human interface devices (i.e., keyboard).  USBmice can operate according to either a "boot protocol" or to a "reportprotocol".  This driver enables mouses for operation using the bootprotocol.Unlike most SIO drivers, the number of channels supported by this driver is notfixed.	Rather, USB mice may be added or removed from the system at anytime.  This creates a situation in which the number of channels is dynamic, andclients of usbMouseLib.c need to be made aware of the appearance and disappearance of channels.  Therefore, this driver adds an additional set offunctions which allows clients to register for notification upon the insertionand removal of USB mice, and hence the creation and deletion of channels.This module itself is a client of the Universal Serial Bus Driver (USBD).  Allinteraction with the USB buses and devices is handled through the USBD.INITIALIZATIONAs with standard SIO drivers, this driver must be initialized by callingusbMouseDevInit().  usbMouseDevInit() in turn initializes its connection to the USBD and other internal resources needed for operation.  Unlike some SIO drivers, there are no usbMouseLib.c data structures which need to be initialized prior to calling usbMouseDevInit().Prior to calling usbMouseDevInit(), the caller must ensure that the USBDhas been properly initialized by calling - at a minimum - usbdInitialize().It is also the caller's responsibility to ensure that at least one USB HCD(USB Host Controller Driver) is attached to the USBD - using the USBD functionusbdHcdAttach() - before mouse operation can begin.  However, it is not necessary for usbdHcdAttach() to be alled prior to initializating usbMouseLib.c.usbMouseLib.c uses the USBD dynamic attach services and is capable of recognizing USB keboard attachment and removal on the fly.  Therefore, it is possible for USB HCDs to be attached to or detached from the USBD at run time- as may be required, for example, in systems supporting hot swapping ofhardware.usbMouseLib.c does not export entry points for transmit, receive, and errorinterrupt entry points like traditional SIO drivers.  All "interrupt" drivenbehavior is managed by the underlying USBD and USB HCD(s), so there is noneed for a caller (or BSP) to connect interrupts on behalf of usbMouseLib.c.For the same reason, there is no post-interrupt-connect initialization codeand usbKeboardLib.c therefore also omits the "devInit2" entry point.OTHER FUNCTIONSusbMouseLib.c also supports the SIO ioctl interface.  However, attempts toset parameters like baud rates and start/stop bits have no meaning in the USBenvironment and will be treated as no-ops.  DATA FLOWFor each USB mouse connected to the system, usbMouseLib.c sets up aUSB pipe to monitor input from the mouse.  usbMouseLib.c supports only theSIO "interrupt" mode of operation.  In this mode, the application must install a "report callback" through the driver's callbackInstall() function.  Thiscallback is of the form:\cstypedef STATUS (*REPORT_CALLBACK)    (    void *arg,    pHID_MSE_BOOT_REPORT pReport    );\ceusbMouseLib.c will invoke this callback for each report received.  The STATUSreturned by the callback is ignored by usbMouseLib.c.  If the application isunable to accept a report, the report is discarded.  The report structure isdefined in usbHid.h, which is included automatically by usbMouseLib.h.usbMouseLib.c does not support output to the mouse.  Therefore, calls tothe txStartup() and pollOutput() functions will fail.  INCLUDE FILES: sioLib.h, usbMouseLib.h*//* includes */#include "vxWorks.h"#include "string.h"#include "sioLib.h"#include "errno.h"#include "ctype.h"#include "usb/usbPlatform.h"#include "usb/ossLib.h" 	/* operations system srvcs */#include "usb/usb.h"		/* general USB definitions */#include "usb/usbListLib.h"	/* linked list functions */#include "usb/usbdLib.h"	/* USBD interface */#include "usb/usbLib.h" 	/* USB utility functions */#include "usb/usbHid.h" 	/* USB HID definitions */#include "drv/usb/usbMouseLib.h"    /* our API *//* defines */#define MSE_CLIENT_NAME "usbMouseLib"	    /* our USBD client name *//* If your hardware platform has problems sharing cache lines, then define * CACHE_LINE_SIZE below so that critical buffers can be allocated within * their own cache lines. */#define CACHE_LINE_SIZE     16/* typedefs *//* * ATTACH_REQUEST */typedef struct attach_request    {    LINK reqLink;	    /* linked list of requests */    USB_MSE_ATTACH_CALLBACK callback;	/* client callback routine */    pVOID callbackArg;		/* client callback argument */    } ATTACH_REQUEST, *pATTACH_REQUEST;/* USB_MSE_SIO_CHAN is the internal data structure we use to track each USB * mouse. */typedef struct usb_mse_sio_chan    {    SIO_CHAN sioChan;		/* must be first field */    LINK sioLink;	    /* linked list of mouse structs */    UINT16 lockCount;		/* Count of times structure locked */    USBD_NODE_ID nodeId;	/* mouse node Id */    UINT16 configuration;	/* configuration/interface reported as */    UINT16 interface;		/* a mouse by this device */    BOOL connected;	    /* TRUE if mouse currently connected */    UINT16 intMaxPacketSize;	    /* max pkt size for interrupt pipe */    USBD_PIPE_HANDLE pipeHandle;    /* USBD pipe handle for interrupt pipe */    USB_IRP irp;	    /* IRP to monitor interrupt pipe */    BOOL irpInUse;	    /* TRUE while IRP is outstanding */    pUINT8 pIrpBfr;	    /* bfr for boot report */    pHID_MSE_BOOT_REPORT pReport;   /* points to pIrpBfr */    int mode;		    /* SIO_MODE_INT or SIO_MODE_POLL */    STATUS (*getTxCharCallback) (void *,...); /* tx callback */    void *getTxCharArg; 	/* tx callback argument */    STATUS (*putRxCharCallback) (void *, ...); /* rx callback */    void *putRxCharArg; 	/* rx callback argument */    STATUS (*putReportCallback) (void *,...); /* report callback */    void *putReportArg; 	/* report callback argument */    } USB_MSE_SIO_CHAN, *pUSB_MSE_SIO_CHAN;/* forward static declarations */LOCAL int usbMouseTxStartup (SIO_CHAN * pSioChan);LOCAL int usbMouseCallbackInstall (SIO_CHAN *pSioChan, int callbackType,    STATUS (*callback)(void *, ...), void *callbackArg);LOCAL int usbMousePollOutput (SIO_CHAN *pSioChan, char	outChar);LOCAL int usbMousePollInput (SIO_CHAN *pSioChan, char *thisChar);LOCAL int usbMouseIoctl (SIO_CHAN *pSioChan, int request, void *arg);LOCAL VOID usbMouseIrpCallback (pVOID p);/* locals */LOCAL UINT16 initCount = 0;	/* Count of init nesting */LOCAL MUTEX_HANDLE mseMutex;	    /* mutex used to protect internal structs */LOCAL LIST_HEAD sioList;	/* linked list of USB_MSE_SIO_CHAN */LOCAL LIST_HEAD reqList;	/* Attach callback request list */LOCAL USBD_CLIENT_HANDLE usbdHandle; /* our USBD client handle *//* Channel function table. */LOCAL SIO_DRV_FUNCS usbMouseSioDrvFuncs =    {    usbMouseIoctl,    usbMouseTxStartup,    usbMouseCallbackInstall,    usbMousePollInput,    usbMousePollOutput    };/***************************************************************************** interpMseReport - interprets USB mouse BOOT report** Interprets a mouse boot report and updates channel state as* appropriate.** RETURNS: N/A** ERRNO: none**\NOMANUAL*/LOCAL VOID interpMseReport    (    pUSB_MSE_SIO_CHAN pSioChan    )    {    pHID_MSE_BOOT_REPORT pReport = pSioChan->pReport;    /* Validate report */    if (pSioChan->irp.bfrList [0].actLen >= sizeof (HID_MSE_BOOT_REPORT))    {    /* invoke receive callback */    if (pSioChan->putReportCallback != NULL)	{	(*pSioChan->putReportCallback) (pSioChan->putReportArg, pReport);	}    }    }/***************************************************************************** usbMouseIoctl - special device control** This routine is largely a no-op for the usbMouseLib.	The only ioctls* which are used by this module are the SIO_AVAIL_MODES_GET and SIO_MODE_SET.** RETURNS: OK on success, ENOSYS on unsupported request, EIO on failed* request.** ERRNO: none**\NOMANUAL*/LOCAL int usbMouseIoctl    (    SIO_CHAN *pChan,	    /* device to control */    int request,	/* request code */    void *someArg	/* some argument */    )    {    pUSB_MSE_SIO_CHAN pSioChan = (pUSB_MSE_SIO_CHAN) pChan;    int arg = (int) someArg;    switch (request)    {    case SIO_MODE_SET:	/* Set driver operating mode: must be interrupt */	if (arg != SIO_MODE_INT)	return EIO;	pSioChan->mode = arg;	return OK;    case SIO_MODE_GET:	/* Return current driver operating mode for channel */	*((int *) arg) = pSioChan->mode;	return OK;    case SIO_AVAIL_MODES_GET:	/* Return modes supported by driver. */	*((int *) arg) = SIO_MODE_INT;	return OK;    case SIO_OPEN:	/* Channel is always open. */	return OK;    case SIO_BAUD_SET:    case SIO_BAUD_GET:    case SIO_HW_OPTS_SET:   /* optional, not supported */    case SIO_HW_OPTS_GET:   /* optional, not supported */    case SIO_HUP:	/* hang up is not supported */    default:	    /* unknown/unsupported command. */	return ENOSYS;    }    }/***************************************************************************** usbMouseTxStartup - start the interrupt transmitter** The USB mouse SIO driver does not support output to the mouse.** RETURNS: EIO** ERRNO: none**\NOMANUAL*/LOCAL int usbMouseTxStartup    (    SIO_CHAN *pChan	/* channel to start */    )    {    return EIO;    }/***************************************************************************** usbMouseCallbackInstall - install ISR callbacks to get/put chars** This driver allows interrupt callbacks for transmitting characters* and receiving characters.=** RETURNS: OK on success, or ENOSYS for an unsupported callback type.** ERRNO: none**\NOMANUAL*/ LOCAL int usbMouseCallbackInstall    (    SIO_CHAN *pChan,	    /* channel */    int callbackType,	    /* type of callback */    STATUS (*callback) (void *, ...),  /* callback */    void *callbackArg	    /* parameter to callback */    )    {    pUSB_MSE_SIO_CHAN pSioChan = (pUSB_MSE_SIO_CHAN) pChan;    switch (callbackType)    {    case SIO_CALLBACK_GET_TX_CHAR:	pSioChan->getTxCharCallback = callback;	pSioChan->getTxCharArg = callbackArg;	return OK;    case SIO_CALLBACK_PUT_RCV_CHAR:	pSioChan->putRxCharCallback = callback;	pSioChan->putRxCharArg = callbackArg;	return OK;    case SIO_CALLBACK_PUT_MOUSE_REPORT:	pSioChan->putReportCallback = callback;	pSioChan->putReportArg = callbackArg;	return OK;    default:	return ENOSYS;    }    }/***************************************************************************** usbMousePollOutput - output a character in polled mode** The USB mouse SIO driver does not support output to the mouse.** RETURNS: EIO** ERRNO: none**\NOMANUAL*/LOCAL int usbMousePollOutput    (    SIO_CHAN *pChan,    char outChar    )    {    return EIO;    }/***************************************************************************** usbMousePollInput - poll the device for input** This function polls the mouse device for input** RETURNS: ENOSYS** ERRNO: none**\NOMANUAL*/LOCAL int usbMousePollInput    (    SIO_CHAN *pChan,    char *thisChar    )    {    return ENOSYS;    }/***************************************************************************** initMseIrp - Initialize IRP to listen for input on interrupt pipe** This function initializes the IRP to listen tn interrupt pipe for input** RETURNS: TRUE if able to submit IRP successfully, else FALSE** ERRNO: none**\NOMANUAL*/LOCAL BOOL initMseIrp    (    pUSB_MSE_SIO_CHAN pSioChan    )    {    pUSB_IRP pIrp = &pSioChan->irp;    /* Initialize IRP */    memset (pIrp, 0, sizeof (*pIrp));    pIrp->userPtr = pSioChan;    pIrp->irpLen = sizeof (*pIrp);    pIrp->userCallback = usbMouseIrpCallback;    pIrp->timeout = USB_TIMEOUT_NONE;    pIrp->transferLen = sizeof (HID_MSE_BOOT_REPORT);