VxWorks API Reference : USB libraries
usbKeyboardLib [USB] - USB keyboard class drive with vxWorks SIO interface
usbKeyboardDevInit( ) - initialize USB keyboard SIO driver
usbKeyboardDevShutdown( ) - shuts down keyboard SIO driver
usbKeyboardDynamicAttachRegister( ) - Register keyboard attach callback
usbKeyboardDynamicAttachUnregister( ) - Unregisters keyboard attach callback
usbKeyboardSioChanLock( ) - Marks SIO_CHAN structure as in use
usbKeyboardSioChanUnlock( ) - Marks SIO_CHAN structure as unused
This module implements the USB keyboard 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 keyboards 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 keyboards as set forth in the USB HID specification and ignores other types of human interface devices (i.e., mouse). USB keyboards can operate according to either a "boot protocol" or to a "report protocol". This driver enables keyboards for operation using the boot protocol.
As the SIO driver model presents a fairly limited, byte-stream oriented view of a serial device, this driver maps USB keyboard scan codes into appropriate ASCII codes. Scan codes and combinations of scan codes which do not map to the ASCII character set are suppressed.
Unlike most SIO drivers, the number of channels supported by this driver is not fixed. Rather, USB keyboards 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 usbKeyboardLib.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 keyboards, 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 usbKeyboardDevInit( ). usbKeyboardDevInit( ) in turn initializes its connection to the USBD and other internal resources needed for operation. Unlike some SIO drivers, there are no usbKeyboardLib.c data structures which need to be initialized prior to calling usbKeyboardDevInit( ).
Prior to calling usbKeyboardDevInit( ), 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 keyboard operation can begin. However, it is not necessary for usbdHcdAttach( ) to be alled prior to initializating usbKeyboardLib.c. usbKeyboardLib.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.
usbKeyboardLib.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 usbKeyboardLib.c. For the same reason, there is no post-interrupt-connect initialization code and usbKeboardLib.c therefore also omits the "devInit2" entry point.
usbKeyboardLib.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 keyboard connected to the system, usbKeyboardLib.c sets up a USB pipe to monitor input from the keyboard. Input, in the form of scan codes, is translated to ASCII codes and placed in an input queue. If SIO callbacks have been installed and usbKeyboardLib.c has been placed in the SIO "interrupt" mode of operation, then usbKeyboardLib.c will invoke the "character received" callback for each character in the queue. When usbKeyboardLib.c has been placed in the "polled" mode of operation, callbacks will not be invoked and the caller will be responsible for fetching keyboard input using the driver's pollInput( ) function.
usbKeyboardLib.c does not support output to the keyboard. Therefore, calls to the txStartup( ) and pollOutput( ) functions will fail. The only "output" supported is the control of the keyboard LEDs, and this is handled internally by usbKeyboardLib.c.
The caller needs to be aware that usbKeyboardLib.c is not capable of operating in a true "polled mode" as the underlying USBD and USB HCD always operate in an interrupt mode.
USB keyboards do not implement typematic repeat, and it is the responsibility of the host software to implement this feature. For this purpose, this module creates a task called typematicThread( ) which monitors all open channels and injects repeated characters into input queues as appropriate.
sioLib.h usbKeyboardLib.h
usbKeyboardDevInit( ) - initialize USB keyboard SIO driver
STATUS usbKeyboardDevInit (void)
Initializes the USB keyboard SIO driver. The USB keyboard SIO driver maintains an initialization count, so calls to this function may be nested.
OK, or ERROR if unable to initialize.
S_usbKeyboardLib_OUT_OF_RESOURCES
S_usbKeyboardLib_USBD_FAULT
usbKeyboardDevShutdown( ) - shuts down keyboard SIO driver
STATUS usbKeyboardDevShutdown (void)
OK, or ERROR if unable to shutdown.
S_usbKeyboardLib_NOT_INITIALIZED
usbKeyboardDynamicAttachRegister( ) - Register keyboard attach callback
STATUS usbKeyboardDynamicAttachRegister ( USB_KBD_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_KBD_ATTACH_CALLBACK) ( pVOID arg, SIO_CHAN *pSioChan, UINT16 attachCode );usbKeyboardLib will invoke callback each time a USB keyboard 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_KBD_ATTACH or USB_KBD_REMOVE.
OK, or ERROR if unable to register callback
S_usbKeyboardLib_BAD_PARAM
S_usbKeyboardLib_OUT_OF_MEMORY
usbKeyboardDynamicAttachUnregister( ) - Unregisters keyboard attach callback
STATUS usbKeyboardDynamicAttachUnRegister ( USB_KBD_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 keyboard attachment and removal. The callback and arg paramters must exactly match those passed in a previous call to usbKeyboardDynamicAttachRegister( ).
OK, or ERROR if unable to unregister callback
S_usbKeyboardLib_NOT_REGISTERED
usbKeyboardSioChanLock( ) - Marks SIO_CHAN structure as in use
STATUS usbKeyboardSioChanLock ( SIO_CHAN * pChan /* SIO_CHAN to be marked as in use */ )
A caller uses usbKeyboardSioChanLock( ) to notify usbKeyboardLib that it is using the indicated SIO_CHAN structure. usbKeyboardLib 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 keyboard is removed from the system. So long as the "lock count" is greater than zero, usbKeyboardLib will not dispose of an SIO_CHAN structure.
OK, or ERROR if unable to mark SIO_CHAN structure in use.
usbKeyboardSioChanUnlock( ) - Marks SIO_CHAN structure as unused
STATUS usbKeyboardSioChanUnlock ( 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 usbKeyboardSioChanLock( ), then it should call this function to release the lock.
If the underlying USB keyboard 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_usbKeyboardLib_NOT_LOCKED