VxWorks API Reference : USB libraries
usbMouseLib [USB] - USB mouse class drive with vxWorks SIO interface
usbMouseDevInit( ) - initialize USB mouse SIO driver
usbMouseDevShutdown( ) - shuts down mouse SIO driver
usbMouseDynamicAttachRegister( ) - Register mouse attach callback
usbMouseDynamicAttachUnregister( ) - Unregisters mouse attach callback
usbMouseSioChanLock( ) - Marks SIO_CHAN structure as in use
usbMouseSioChanUnlock( ) - Marks SIO_CHAN structure as unused
This module implements the USB mouse class driver for the vxWorks operating system. This module presents an interface which is a superset of the vxWorks SIO (serial IO) driver model. That is, this driver presents the external APIs which would be expected of a standard "multi-mode serial (SIO) driver" and adds certain extensions which are needed to address adequately the requirements of the hot-plugging USB environment.
USB mice are described as part of the USB "human interface device" class specification and related documents. This driver concerns itself only with USB devices which claim to be mouses as set forth in the USB HID specification and ignores other types of human interface devices (i.e., keyboard). USB mice can operate according to either a "boot protocol" or to a "report protocol". This driver enables mouses for operation using the boot protocol.
Unlike most SIO drivers, the number of channels supported by this driver is not fixed. Rather, USB mice may be added or removed from the system at any time. This creates a situation in which the number of channels is dynamic, and clients of usbMouseLib.c need to be made aware of the appearance and disappearance of channels. Therefore, this driver adds an additional set of functions which allows clients to register for notification upon the insertion and 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). All interaction with the USB buses and devices is handled through the USBD.
As with standard SIO drivers, this driver must be initialized by calling usbMouseDevInit( ). 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 USBD has 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 function usbdHcdAttach( ) - 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 of hardware.
usbMouseLib.c does not export entry points for transmit, receive, and error interrupt entry points like traditional SIO drivers. All "interrupt" driven behavior is managed by the underlying USBD and USB HCD(s), so there is no need for a caller (or BSP) to connect interrupts on behalf of usbMouseLib.c. For the same reason, there is no post-interrupt-connect initialization code and usbKeboardLib.c therefore also omits the "devInit2" entry point.
usbMouseLib.c also supports the SIO ioctl interface. However, attempts to set parameters like baud rates and start/stop bits have no meaning in the USB environment and will be treated as no-ops.
For each USB mouse connected to the system, usbMouseLib.c sets up a USB pipe to monitor input from the mouse. usbMouseLib.c supports only the SIO "interrupt" mode of operation. In this mode, the application must install a "report callback" through the driver's callbackInstall( ) function. This callback is of the form:
typedef STATUS (*REPORT_CALLBACK) ( void *arg, pHID_MSE_BOOT_REPORT pReport );usbMouseLib.c will invoke this callback for each report received. The STATUS returned by the callback is ignored by usbMouseLib.c. If the application is unable to accept a report, the report is discarded. The report structure is defined in usbHid.h, which is included automatically by usbMouseLib.h.usbMouseLib.c does not support output to the mouse. Therefore, calls to the txStartup( ) and pollOutput( ) functions will fail.
sioLib.h usbMouseLib.h
usbMouseDevInit( ) - initialize USB mouse SIO driver
STATUS usbMouseDevInit (void)
Initializes the USB mouse SIO driver. The USB mouse SIO driver maintains an initialization count, so calls to this function may be nested.
OK, or ERROR if unable to initialize.
S_usbMouseLib_OUT_OF_RESOURCES
S_usbMouseLib_USBD_FAULT
usbMouseDevShutdown( ) - shuts down mouse SIO driver
STATUS usbMouseDevShutdown (void)
OK, or ERROR if unable to shutdown.
S_usbMouseLib_NOT_INITIALIZED
usbMouseDynamicAttachRegister( ) - Register mouse attach callback
STATUS usbMouseDynamicAttachRegister ( USB_MSE_ATTACH_CALLBACK callback, /* new callback to be registered */ pVOID arg /* user-defined arg to callback */ )
callback is a caller-supplied function of the form:
typedef (*USB_MSE_ATTACH_CALLBACK) ( pVOID arg, SIO_CHAN *pSioChan, UINT16 attachCode );usbMouseLib will invoke callback each time a USB mouse is attached to or removed from the system. arg is a caller-defined parameter which will be passed to the callback each time it is invoked. The callback will also be passed a pointer to the SIO_CHAN structure for the channel being created/destroyed and an attach code of USB_MSE_ATTACH or USB_MSE_REMOVE.
OK, or ERROR if unable to register callback
S_usbMouseLib_BAD_PARAM
S_usbMouseLib_OUT_OF_MEMORY
usbMouseDynamicAttachUnregister( ) - Unregisters mouse attach callback
STATUS usbMouseDynamicAttachUnRegister ( USB_MSE_ATTACH_CALLBACK callback, /* callback to be unregistered */ pVOID arg /* user-defined arg to callback */ )
This function cancels a previous request to be dynamically notified for mouse attachment and removal. The callback and arg paramters must exactly match those passed in a previous call to usbMouseDynamicAttachRegister( ).
OK, or ERROR if unable to unregister callback
S_usbMouseLib_NOT_REGISTERED
usbMouseSioChanLock( ) - Marks SIO_CHAN structure as in use
STATUS usbMouseSioChanLock ( SIO_CHAN * pChan /* SIO_CHAN to be marked as in use */ )
A caller uses usbMouseSioChanLock( ) to notify usbMouseLib that it is using the indicated SIO_CHAN structure. usbMouseLib maintains a count of callers using a particular SIO_CHAN structure so that it knows when it is safe to dispose of a structure when the underlying USB mouse is removed from the system. So long as the "lock count" is greater than zero, usbMouseLib will not dispose of an SIO_CHAN structure.
OK, or ERROR if unable to mark SIO_CHAN structure in use.
usbMouseSioChanUnlock( ) - Marks SIO_CHAN structure as unused
STATUS usbMouseSioChanUnlock ( SIO_CHAN * pChan /* SIO_CHAN to be marked as unused */ )
This function releases a lock placed on an SIO_CHAN structure. When a caller no longer needs an SIO_CHAN structure for which it has previously called usbMouseSioChanLock( ), then it should call this function to release the lock.
If the underlying USB mouse device has already been removed from the system, then this function will automatically dispose of the SIO_CHAN structure if this call removes the last lock on the structure. Therefore, a caller must not reference the SIO_CHAN again structure after making this call.
OK, or ERROR if unable to mark SIO_CHAN structure unused
S_usbMouseLib_NOT_LOCKED