VxWorks API Reference : USB libraries
usbBulkDevLib [USB] - USB Bulk Only Mass Storage class driver
usbBulkDevShutDown( ) - shuts down the USB bulk-only class driver.
usbBulkDevInit( ) - registers USB Bulk only mass storage class driver.
usbBulkDevIoctl( ) - perform a device-specific control.
usbBulkBlkDevCreate( ) - create a block device.
usbBulkDynamicAttachRegister( ) - Register SCSI/BULK-ONLY device attach callback.
usbBulkDynamicAttachUnregister( ) - Unregisters SCSI/BULK-ONLY attach callback.
usbBulkDevLock( ) - Marks USB_BULK_DEV structure as in use.
usbBulkDevUnlock( ) - Marks USB_BULK_DEV structure as unused.
This module implements the USB Mass Storage class driver for the vxWorks operating system. This module presents an interface which is a superset of the vxWorks Block Device driver model. This driver implements external APIs which would be expected of a standard block device driver.
This class driver restricts to Mass Storage class devices that follow bulk-only transport. For bulk-only devices transport of command, data and status occurs solely via bulk endpoints. The default control pipe is only used to set configuration, clear STALL condition on endpoints and to issue class-specific requests.
The class driver is a client of the Universal Serial Bus Driver (USBD). All interaction with the USB buses and devices is handled through the USBD.
The class driver must be initialized with usbBulkDevInit( ). It is assumed that USBD is already initialized and attached to atleast one USB Host Controller. usbBulkDevInit( ) registers the class driver as a client module with USBD. It also registers a callback routine to get notified whenever a USB MSC/SCSI/ BULK-ONLY device is attached or removed from the system. The callback routine creates a USB_BULK_DEV structure to represent the USB device attached. It also sets device configuration, interface settings and creates pipes for BULK_IN and BULK_OUT transfers.
usbBulkBlkDevCreate( ) is the entry point to define a logical block device. This routine initializes the fields with in the vxWorks block device structure BLK_DEV. This BLK_DEV structure is part of the USB_BULK_DEV structure. Memory is allocated for USB_BULK_DEV by the dynamic attach notification callback routine. So, this create routine just initializes the BLK_DEV structure and returns a pointer to it, which is used during file system initializtion call.
usbBulkDevIoctl( ) implements functions which are beyond basic file handling. Class-specific requests, Descriptor show, are some of the functions. Function code parameter identifies the IO operation requested.
For each USB MSC/SCSI/BULK-ONLY device detected, usbBulkPhysDevCreate( ) will create pipes to BULK_IN and a BULK_OUT endpoints of the device. A pipe is a channel between USBD client i,e usbBulkDevLib and a specific endpoint. All SCSI commands are encapsulated with in a Command Block Wrapper (CBW) and transferred across the BULK_OUT endpoint through the out pipe created. This is followed by a data transfer phase. Depending on the SCSI command sent to the device, the direction bit in the CBW will indicate whether data is transferred to or from the device. This bit has no significance if no data transfer is expected. Data is transferred to the device through BULK_OUT endpoint and if the device is required to transfer data, it does through the BULK_IN endpoint. The device shall send Command Status Wrapper (CSW) via BULK_IN endpoint. This will indicate the success or failure of the CBW. The data to be transferred to device will be pointed by the file system launched on the device.
usbBulkDevLib.h, blkIo.h
USB Mass Storage Class - Bulk Only Transport Specification Version 1.0, SCSI-2 Standard specification 10L - Direct Access device commands
usbBulkDevShutDown( ) - shuts down the USB bulk-only class driver.
STATUS usbBulkDevShutDown ( int errCode /* Error code - reason for shutdown */ )
This routine unregisters the driver from USBD and releases any resources allocated for the devices.
OK or ERROR.
usbBulkDevInit( ) - registers USB Bulk only mass storage class driver.
STATUS usbBulkDevInit (void)
This routine registers the mass storage class driver with USB driver. It also registers attach callback routine to get notified of the USB/MSC/BULK ONLY devices.
OK, or ERROR if unable to register with USBD.
S_usbbulkDevLib_OUT_OF_RESOURCES
S_usbbulkDevLib_USBD_FAULT
usbBulkDevIoctl( ) - perform a device-specific control.
STATUS usbBulkDevIoctl ( BLK_DEV * pBlkDev, /* pointer to bulk device */ int request, /* request type */ int someArg /* arguments related to request */ )
Typically called to invoke device-specific functions which are not needed by a file system.
The status of the request, or ERROR if the request is unsupported.
usbBulkBlkDevCreate( ) - create a block device.
BLK_DEV * usbBulkBlkDevCreate ( USBD_NODE_ID nodeId, /* nodeId of the bulk-only device */ UINT32 numBlks, /* number of logical blocks on device */ UINT32 blkOffset, /* offset of the starting block */ UINT32 flags /* optional flags */ )
This routine initializes a BLK_DEV structure, which describes a logical partition on a USB_BULK_DEV device. A logical partition is an array of contiguously addressed blocks; it can be completely described by the number of blocks and the address of the first block in the partition.
If numBlocks is 0, the rest of device is used.
This routine supplies an additional parameter called flags. This bitfield currently only uses bit 1. This bit determines whether the driver will use a SCSI READ6 or SCSI READ10 for read access.
A pointer to the BLK_DEV, or NULL if parameters exceed physical device boundaries, or if no bulk device exists.
usbBulkDynamicAttachRegister( ) - Register SCSI/BULK-ONLY device attach callback.
STATUS usbBulkDynamicAttachRegister ( USB_BULK_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_BULK_ATTACH_CALLBACK) ( pVOID arg, USBD_NODE_ID bulkDevId, UINT16 attachCode );usbBulkDevLib will invoke callback each time a MSC/SCSI/BULK-ONLY device 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 the nodeID of the device being created/destroyed and an attach code of USB_BULK_ATTACH or USB_BULK_REMOVE.
The user callback routine should not invoke any driver function that submits IRPs. Further processing must be done from a different task context. As the driver routines wait for IRP completion, they cannot be invoked from USBD client task's context created for this driver.
OK, or ERROR if unable to register callback
S_usbBulkDevLib_BAD_PARAM
S_usbBulkDevLib_OUT_OF_MEMORY
usbBulkDynamicAttachUnregister( ) - Unregisters SCSI/BULK-ONLY attach callback.
STATUS usbBulkDynamicAttachUnregister ( USB_BULK_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 SCSI/BULK-ONLY device attachment and removal. The callback and arg paramters must exactly match those passed in a previous call to usbBulkDynamicAttachRegister( ).
OK, or ERROR if unable to unregister callback
S_usbBulkDevLib_NOT_REGISTERED
usbBulkDevLock( ) - Marks USB_BULK_DEV structure as in use.
STATUS usbBulkDevLock ( USBD_NODE_ID nodeId /* NodeId of the BLK_DEV to be marked as in use */ )
A caller uses usbBulkDevLock( ) to notify usbBulkDevLib that it is using the indicated USB_BULK_DEV structure. usbBulkDevLib maintains a count of callers using a particular USB_BULK_DEV structure so that it knows when it is safe to dispose of a structure when the underlying USB_BULK_DEV is removed from the system. So long as the "lock count" is greater than zero, usbBulkDevLib will not dispose of an USB_BULK_DEV structure.
OK, or ERROR if unable to mark USB_BULK_DEV structure in use.
usbBulkDevUnlock( ) - Marks USB_BULK_DEV structure as unused.
STATUS usbBulkDevUnlock ( USBD_NODE_ID nodeId /* NodeId of the BLK_DEV to be marked as unused */ )
This function releases a lock placed on an USB_BULK_DEV structure. When a caller no longer needs an USB_BULK_DEV structure for which it has previously called usbBulkDevLock( ), then it should call this function to release the lock.
If the underlying SCSI/BULK-ONLY device has already been removed from the system, then this function will automatically dispose of the USB_BULK_DEV structure if this call removes the last lock on the structure. Therefore, a caller must not reference the USB_BULK_DEV structure after making this call.
OK, or ERROR if unable to mark USB_BULK_DEV structure unused
S_usbBulkDevLib_NOT_LOCKED