VxWorks API Reference : USB libraries
usbPrinterLib [USB] - USB printer class drive with vxWorks SIO interface
usbPrinterDevInit( ) - initialize USB printer SIO driver
usbPrinterDevShutdown( ) - shuts down printer SIO driver
usbPrinterDynamicAttachRegister( ) - Register printer attach callback
usbPrinterDynamicAttachUnregister( ) - Unregisters printer attach callback
usbPrinterSioChanLock( ) - Marks SIO_CHAN structure as in use
usbPrinterSioChanUnlock( ) - Marks SIO_CHAN structure as unused
This module implements the USB printer 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 printers are described in the USB Printer Class definition. This class driver specification presents two kinds of printer: uni-directional printers (output only) and bi-directional printers (capable of both output and input). This class driver is capable of handling both kinds of printers. If a printer is uni-directional, then the SIO driver interface only allows characters to be written to the printer. If the printer is bi-directional, then the SIO interface allows both output and input streams to be written/read.
Unlike most SIO drivers, the number of channels supported by this driver is not fixed. Rather, USB printers 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 usbPrinterLib.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 printers, 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 usbPrinterDevInit( ). usbPrinterDevInit( ) in turn initializes its connection to the USBD and other internal resources needed for operation. Unlike some SIO drivers, there are no usbPrinterLib.c data structures which need to be initialized prior to calling usbPrinterDevInit( ).
Prior to calling usbPrinterDevInit( ), 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 printer operation can begin. However, it is not necessary for usbdHcdAttach( ) to be alled prior to initializating usbPrinterLib.c. usbPrinterLib.c uses the USBD dynamic attach services and is capable of recognizing USB printer 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.
usbPrinterLib.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 usbPrinterLib.c. For the same reason, there is no post-interrupt-connect initialization code and usbPrinterLib.c therefore also omits the "devInit2" entry point.
usbPrinterLib.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.
Additional ioctl functions have been added to allow the caller to retrieve the USB printer's "device ID" string, the type of printer (uni- or bi-directional), and the current printer status. The "device ID" string is discussed in more detail in the USB printer class specification and is based on the IEEE-1284 "device ID" string used by most 1284-compliant printers. The printer status function can be used to determine if the printer is selected, out of paper, or has an error condition.
For each USB printer connected to the system, usbPrinterLib.c sets up a USB pipe to output bulk data to the printer. This is the pipe through which printer control and page description data will be sent to the printer. Additionally, if the printer is bi-directional, usbPrinterLib.c also sets up a USB pipe to receive bulk input data from the printer. The meaining of data received from a bi-directional printer depends on the specific make/model of printer.
The USB printer SIO driver supports only the SIO "interrupt" mode of operation - SIO_MODE_INT. Any attempt to place the driver in the polled mode will return an error.
sioLib.h usbPrinterLib.h
usbPrinterDevInit( ) - initialize USB printer SIO driver
STATUS usbPrinterDevInit (void)
Initializes the USB printer SIO driver. The USB printer SIO driver maintains an initialization count, so calls to this function may be nested.
OK, or ERROR if unable to initialize.
S_usbPrinterLib_OUT_OF_RESOURCES
S_usbPrinterLib_USBD_FAULT
usbPrinterDevShutdown( ) - shuts down printer SIO driver
STATUS usbPrinterDevShutdown (void)
OK, or ERROR if unable to shutdown.
S_usbPrinterLib_NOT_INITIALIZED
usbPrinterDynamicAttachRegister( ) - Register printer attach callback
STATUS usbPrinterDynamicAttachRegister ( USB_PRN_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_PRN_ATTACH_CALLBACK) ( pVOID arg, SIO_CHAN *pSioChan, UINT16 attachCode );usbPrinterLib will invoke callback each time a USB printer 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_PRN_ATTACH or USB_PRN_REMOVE.
OK, or ERROR if unable to register callback
S_usbPrinterLib_BAD_PARAM
S_usbPrinterLib_OUT_OF_MEMORY
usbPrinterDynamicAttachUnregister( ) - Unregisters printer attach callback
STATUS usbPrinterDynamicAttachUnRegister ( USB_PRN_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 printer attachment and removal. The callback and arg paramters must exactly match those passed in a previous call to usbPrinterDynamicAttachRegister( ).
OK, or ERROR if unable to unregister callback
S_usbPrinterLib_NOT_REGISTERED
usbPrinterSioChanLock( ) - Marks SIO_CHAN structure as in use
STATUS usbPrinterSioChanLock ( SIO_CHAN * pChan /* SIO_CHAN to be marked as in use */ )
A caller uses usbPrinterSioChanLock( ) to notify usbPrinterLib that it is using the indicated SIO_CHAN structure. usbPrinterLib 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 printer is removed from the system. So long as the "lock count" is greater than zero, usbPrinterLib will not dispose of an SIO_CHAN structure.
OK, or ERROR if unable to mark SIO_CHAN structure in use.
usbPrinterSioChanUnlock( ) - Marks SIO_CHAN structure as unused
STATUS usbPrinterSioChanUnlock ( 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 usbPrinterSioChanLock( ), then it should call this function to release the lock.
If the underlying USB printer 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_usbPrinterLib_NOT_LOCKED