Functions | Variables
Usblib_host_class

Functions

static void USBHMSCClose (void *pvInstance)
 
void USBHCDConfigureEndpoints (uint32_t ulIndex, tUSBHostDevice *pDevice, uint32_t *inPipe, uint32_t *outPipe)
 
static void USBHMSCGetMaxLUN (uint32_t ulIndex, uint32_t ulAddress, uint32_t ulInterface, unsigned char *pucMaxLUN)
 
int USBHMSCDriveReady (uint32_t ulInstance)
 
uint32_t USBHMSCDriveOpen (uint32_t ulIndex, uint32_t ulDrive, tUSBHMSCCallback pfnCallback)
 
void USBHMSCDriveClose (uint32_t ulInstance)
 
int USBHMSCBlockRead (uint32_t ulInstance, uint32_t ulLBA, unsigned char *pucData, uint32_t ulNumBlocks)
 
int USBHMSCBlockWrite (uint32_t ulInstance, uint32_t ulLBA, unsigned char *pucData, uint32_t ulNumBlocks)
 
static uint32_t USBHSCSISendCommand (uint32_t ulIndex, uint32_t ulInPipe, uint32_t ulOutPipe, tMSCCBW *pSCSICmd, unsigned char *pucData, uint32_t *pulSize)
 
uint32_t USBHSCSIInquiry (uint32_t ulIndex, uint32_t ulInPipe, uint32_t ulOutPipe, unsigned char *pucData, uint32_t *pulSize)
 
uint32_t USBHSCSIReadCapacity (uint32_t ulIndex, uint32_t ulInPipe, uint32_t ulOutPipe, unsigned char *pucData, uint32_t *pulSize)
 
uint32_t USBHSCSIReadCapacities (uint32_t ulIndex, uint32_t ulInPipe, uint32_t ulOutPipe, unsigned char *pucData, uint32_t *pulSize)
 
uint32_t USBHSCSIModeSense6 (uint32_t ulIndex, uint32_t ulInPipe, uint32_t ulOutPipe, uint32_t ulFlags, unsigned char *pucData, uint32_t *pulSize)
 
uint32_t USBHSCSITestUnitReady (uint32_t ulIndex, uint32_t ulInPipe, uint32_t ulOutPipe)
 
uint32_t USBHSCSIRequestSense (uint32_t ulIndex, uint32_t ulInPipe, uint32_t ulOutPipe, unsigned char *pucData, uint32_t *pulSize)
 
uint32_t USBHSCSIRead10 (uint32_t ulIndex, uint32_t ulInPipe, uint32_t ulOutPipe, uint32_t ulLBA, unsigned char *pucData, uint32_t *pulSize, uint32_t ulNumBlocks)
 
uint32_t USBHSCSIWrite10 (uint32_t ulIndex, uint32_t ulInPipe, uint32_t ulOutPipe, uint32_t ulLBA, unsigned char *pucData, uint32_t *pulSize, uint32_t ulNumBlocks)
 

Variables

const tUSBHostClassDriver g_USBHostMSCClassDriver
 

Detailed Description

Copyright (c) Texas Instruments Incorporated 2015-2016

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

Neither the name of Texas Instruments Incorporated nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Function Documentation

void USBHCDConfigureEndpoints ( uint32_t  ulIndex,
tUSBHostDevice pDevice,
uint32_t *  inPipe,
uint32_t *  outPipe 
)

This function is used to open an instance of the MSC driver.

Parameters
pDeviceis a pointer to the device information structure.

This function will attempt to open an instance of the MSC driver based on the information contained in the pDevice structure. This call can fail if there are not sufficient resources to open the device. The function will return a value that should be passed back into USBMSCClose() when the driver is no longer needed.

Returns
The function will return a pointer to a MSC driver instance.
none
int USBHMSCBlockRead ( uint32_t  ulInstance,
uint32_t  ulLBA,
unsigned char *  pucData,
uint32_t  ulNumBlocks 
)

This function performs a block read to an MSC device.

Parameters
ulInstanceis the device instance to use for this read.
ulLBAis the logical block address to read on the device.
pucDatais a pointer to the returned data buffer.
ulNumBlocksis the number of blocks to read from the device.

This function will perform a block sized read from the device associated with the ulInstance parameter. The ulLBA parameter specifies the logical block address to read on the device. This function will only perform ulNumBlocks block sized reads. In most cases this is a read of 512 bytes of data. The *pucData buffer should be at least ulNumBlocks * 512 bytes in size.

Returns
The function returns zero for success and any negative value indicates a failure.
int USBHMSCBlockWrite ( uint32_t  ulInstance,
uint32_t  ulLBA,
unsigned char *  pucData,
uint32_t  ulNumBlocks 
)

This function performs a block write to an MSC device.

Parameters
ulInstanceis the device instance to use for this write.
ulLBAis the logical block address to write on the device.
pucDatais a pointer to the data to write out.
ulNumBlocksis the number of blocks to write to the device.

This function will perform a block sized write to the device associated with the ulInstance parameter. The ulLBA parameter specifies the logical block address to write on the device. This function will only perform ulNumBlocks block sized writes. In most cases this is a write of 512 bytes of data. The *pucData buffer should contain at least ulNumBlocks * 512 bytes in size to prevent unwanted data being written to the device.

Returns
The function returns zero for success and any negative value indicates a failure.
static void USBHMSCClose ( void *  pvInstance)
static

This function is used to release an instance of the MSC driver.

Parameters
pvInstanceis an instance pointer that needs to be released.

This function will free up any resources in use by the MSC driver instance that is passed in. The pvInstance pointer should be a valid value that was returned from a call to USBMSCOpen().

Returns
None.
void USBHMSCDriveClose ( uint32_t  ulInstance)

This function should be called to release a drive instance.

Parameters
ulInstanceis the device instance that is to be released.

This function is called when an MSC drive is to be released in preparation for shutdown or a switch to USB device mode, for example. Following this call, the drive is available for other clients who may open it again using a call to USBHMSCDriveOpen().

Returns
None.
uint32_t USBHMSCDriveOpen ( uint32_t  ulIndex,
uint32_t  ulDrive,
tUSBHMSCCallback  pfnCallback 
)

This function should be called before any devices are present to enable the mass storage device class driver.

Parameters
ulDriveis the drive number to open.
pfnCallbackis the driver callback for any mass storage events.

This function is called to open an instance of a mass storage device. It should be called before any devices are connected to allow for proper notification of drive connection and disconnection. The ulDrive parameter is a zero based index of the drives present in the system. There are a constant number of drives, and this number should only be greater than 0 if there is a USB hub present in the system. The application should also provide the pfnCallback to be notified of mass storage related events like device enumeration and device removal.

Returns
This function will return the driver instance to use for the other mass storage functions. If there is no driver available at the time of this call, this function will return zero.
int USBHMSCDriveReady ( uint32_t  ulInstance)

This function checks if a drive is ready to be accessed.

Parameters
ulInstanceis the device instance to use for this read.

This function checks if the current device is ready to be accessed. It uses the ulInstance parameter to determine which device to check and will return zero when the device is ready. Any non-zero return code indicates that the device was not ready.

Returns
This function will return zero if the device is ready and it will return a other value if the device is not ready or if an error occurred.
static void USBHMSCGetMaxLUN ( uint32_t  ulIndex,
uint32_t  ulAddress,
uint32_t  ulInterface,
unsigned char *  pucMaxLUN 
)
static

This function retrieves the maximum number of the logical units on a mass storage device.

Parameters
ulAddressis the device address on the USB bus.
ulInterfaceis the interface number on the device specified by the ulAddress parameter.
pucMaxLUNis the byte value returned from the device for the device's maximum logical unit.

The device will return one byte of data that contains the maximum LUN supported by the device. For example, if the device supports four LUNs then the LUNs would be numbered from 0 to 3 and the return value would be

  1. If no LUN is associated with the device, the value returned shall be 0.
Returns
None.
uint32_t USBHSCSIInquiry ( uint32_t  ulIndex,
uint32_t  ulInPipe,
uint32_t  ulOutPipe,
unsigned char *  pucData,
uint32_t *  pulSize 
)

This will issue the SCSI inquiry command to a device.

Parameters
ulInPipeis the USB IN pipe to use for this command.
ulOutPipeis the USB OUT pipe to use for this command.
pucDatais the data buffer to return the results into.
pulSizeis the size of buffer that was passed in on entry and the number of bytes returned.

This function should be used to issue a SCSI Inquiry command to a mass storage device. To allow for multiple devices, the ulInPipe and ulOutPipe parameters indicate which USB pipes to use for this call.

Note
The pucData buffer pointer should have at least SCSI_INQUIRY_DATA_SZ bytes of data or this function will overflow the buffer.
Returns
This function returns the SCSI status from the command. The value will be either SCSI_CMD_STATUS_PASS or SCSI_CMD_STATUS_FAIL.
uint32_t USBHSCSIModeSense6 ( uint32_t  ulIndex,
uint32_t  ulInPipe,
uint32_t  ulOutPipe,
uint32_t  ulFlags,
unsigned char *  pucData,
uint32_t *  pulSize 
)

This will issue the SCSI Mode Sense(6) command to a device.

Parameters
ulInPipeis the USB IN pipe to use for this command.
ulOutPipeis the USB OUT pipe to use for this command.
ulFlagsis a combination of flags defining the exact query that is to be made.
pucDatais the data buffer to return the results into.
pulSizeis the size of the buffer on entry and number of bytes read on exit.

This function should be used to issue a SCSI Mode Sense(6) command to a mass storage device. To allow for multiple devices,the ulInPipe and ulOutPipe parameters indicate which USB pipes to use for this call. The call will return at most the number of bytes in the pulSize parameter, however it can return less and change the pulSize parameter to the number of valid bytes in the *pulSize buffer.

The ulFlags parameter is a combination of the following three sets of definitions:

One of the following values must be specified:

  • SCSI_MS_PC_CURRENT request for current settings.
  • SCSI_MS_PC_CHANGEABLE request for changeable settings.
  • SCSI_MS_PC_DEFAULT request for default settings.
  • SCSI_MS_PC_SAVED request for the saved values.

One of these following values must also be specified to determine the page code for the request:

  • SCSI_MS_PC_VENDOR is the vendor specific page code.
  • SCSI_MS_PC_DISCO is the disconnect/reconnect page code.
  • SCSI_MS_PC_CONTROL is the control page code.
  • SCSI_MS_PC_LUN is the protocol specific LUN page code.
  • SCSI_MS_PC_PORT is the protocol specific port page code.
  • SCSI_MS_PC_POWER is the power condition page code.
  • SCSI_MS_PC_INFORM is the informational exceptions page code.
  • SCSI_MS_PC_ALL will request all pages codes supported by the device.

The last value is optional and supports the following global flag:

  • SCSI_MS_DBD disables returning block descriptors.

Example: Request for all current settings.

//! SCSIModeSense6(ulInPipe, ulOutPipe,
//!                SCSI_MS_PC_CURRENT | SCSI_MS_PC_ALL,
//!                pucData, pulSize);
//! 
\return This function returns the SCSI status from the command.  The value
will be either \b SCSI_CMD_STATUS_PASS or \b SCSI_CMD_STATUS_FAIL.  
uint32_t USBHSCSIRead10 ( uint32_t  ulIndex,
uint32_t  ulInPipe,
uint32_t  ulOutPipe,
uint32_t  ulLBA,
unsigned char *  pucData,
uint32_t *  pulSize,
uint32_t  ulNumBlocks 
)

This function issues a SCSI Read(10) command to a device.

Parameters
ulInPipeis the USB IN pipe to use for this command.
ulOutPipeis the USB OUT pipe to use for this command.
ulLBAis the logical block address to read.
pucDatais the data buffer to return the data.
pulSizeis the size of the buffer on entry and number of bytes read on exit.
ulNumBlocksis the number of contiguous blocks to read from the device.

This function is used to issue a SCSI Read(10) command to a device. The ulLBA parameter specifies the logical block address to read from the device. The data from this block will be returned in the buffer pointed to by pucData. The parameter pulSize should indicate enough space to hold a full block size, or only the first pulSize bytes of the LBA will be returned.

Returns
This function returns the results of the SCSI Read(10) command. The value will be either SCSI_CMD_STATUS_PASS or SCSI_CMD_STATUS_FAIL.
uint32_t USBHSCSIReadCapacities ( uint32_t  ulIndex,
uint32_t  ulInPipe,
uint32_t  ulOutPipe,
unsigned char *  pucData,
uint32_t *  pulSize 
)

This will issue the SCSI read capacities command to a device.

Parameters
ulInPipeis the USB IN pipe to use for this command.
ulOutPipeis the USB OUT pipe to use for this command.
pucDatais the data buffer to return the results into.
pulSizeis the size of buffer that was passed in on entry and the number of bytes returned.

This function should be used to issue a SCSI Read Capacities command to a mass storage device that is connected. To allow for multiple devices, the ulInPipe and ulOutPipe parameters indicate which USB pipes to use for this call.

Returns
This function returns the SCSI status from the command. The value will be either SCSI_CMD_STATUS_PASS or SCSI_CMD_STATUS_FAIL.
uint32_t USBHSCSIReadCapacity ( uint32_t  ulIndex,
uint32_t  ulInPipe,
uint32_t  ulOutPipe,
unsigned char *  pucData,
uint32_t *  pulSize 
)

This will issue the SCSI read capacity command to a device.

Parameters
ulInPipeis the USB IN pipe to use for this command.
ulOutPipeis the USB OUT pipe to use for this command.
pucDatais the data buffer to return the results into.
pulSizeis the size of buffer that was passed in on entry and the number of bytes returned.

This function should be used to issue a SCSI Read Capacity command to a mass storage device that is connected. To allow for multiple devices, the ulInPipe and ulOutPipe parameters indicate which USB pipes to use for this call.

Note
The pucData buffer pointer should have at least SCSI_READ_CAPACITY_SZ bytes of data or this function will overflow the buffer.
Returns
This function returns the SCSI status from the command. The value will be either SCSI_CMD_STATUS_PASS or SCSI_CMD_STATUS_FAIL.
uint32_t USBHSCSIRequestSense ( uint32_t  ulIndex,
uint32_t  ulInPipe,
uint32_t  ulOutPipe,
unsigned char *  pucData,
uint32_t *  pulSize 
)

This function issues a SCSI Request Sense command to a device.

Parameters
ulInPipeis the USB IN pipe to use for this command.
ulOutPipeis the USB OUT pipe to use for this command.
pucDatais the data buffer to return the results into.
pulSizeis the size of the buffer on entry and number of bytes read on exit.

This function is used to issue a SCSI Request Sense command to a device. It will return the data in the buffer pointed to by pucData. The parameter pulSize should have the allocation size in bytes of the buffer pointed to by pucData.

Returns
This function returns the results of the SCSI Request Sense command. The value will be either SCSI_CMD_STATUS_PASS or SCSI_CMD_STATUS_FAIL.
static uint32_t USBHSCSISendCommand ( uint32_t  ulIndex,
uint32_t  ulInPipe,
uint32_t  ulOutPipe,
tMSCCBW *  pSCSICmd,
unsigned char *  pucData,
uint32_t *  pulSize 
)
static

This function is used to issue SCSI commands via USB.

Parameters
ulInPipeis the USB IN pipe to use for this command.
ulOutPipeis the USB OUT pipe to use for this command.
pSCSICmdis the SCSI command structure to send.
pucDatais pointer to the command data to be sent.
pulSizeis the number of bytes is the number of bytes expected or sent by the command.

This internal function is used to handle SCSI commands sent by other functions. It serves as a layer between the SCSI command and the USB interface being used to send the command. The pSCSI parameter contains the SCSI command to send. For commands that expect data back, the pucData is the buffer to store the data into and pulSize is used to store the amount of data to request as well as used to indicate how many bytes were filled into the pucData buffer on return. For commands that are sending data, pucData is the data to be sent and pulSize is the number of bytes to send.

Returns
This function returns the SCSI status from the command. The value will be either SCSI_CMD_STATUS_PASS or SCSI_CMD_STATUS_FAIL.
uint32_t USBHSCSITestUnitReady ( uint32_t  ulIndex,
uint32_t  ulInPipe,
uint32_t  ulOutPipe 
)

This function issues a SCSI Test Unit Ready command to a device.

Parameters
ulInPipeis the USB IN pipe to use for this command.
ulOutPipeis the USB OUT pipe to use for this command.

This function is used to issue a SCSI Test Unit Ready command to a device. This call will simply return the results of issuing this command.

Returns
This function returns the results of the SCSI Test Unit Ready command. The value will be either SCSI_CMD_STATUS_PASS or SCSI_CMD_STATUS_FAIL.
uint32_t USBHSCSIWrite10 ( uint32_t  ulIndex,
uint32_t  ulInPipe,
uint32_t  ulOutPipe,
uint32_t  ulLBA,
unsigned char *  pucData,
uint32_t *  pulSize,
uint32_t  ulNumBlocks 
)

This function issues a SCSI Write(10) command to a device.

This function is used to issue a SCSI Write(10) command to a device. The ulLBA parameter specifies the logical block address on the device. The data to write to this block should be in the buffer pointed to by pucData parameter. The parameter pulSize should indicate the amount of data to write to the specified LBA.

Parameters
ulInPipeis the USB IN pipe to use for this command.
ulOutPipeis the USB OUT pipe to use for this command.
ulLBAis the logical block address to read.
pucDatais the data buffer to write out.
pulSizeis the size of the buffer.
ulNumBlocksis the number of contiguous blocks to write to the device.
Returns
This function returns the results of the SCSI Write(10) command. The value will be either SCSI_CMD_STATUS_PASS or SCSI_CMD_STATUS_FAIL.

Variable Documentation

const tUSBHostClassDriver g_USBHostMSCClassDriver
Initial value:
=
{
USB_CLASS_MASS_STORAGE,
USBHMSCOpen,
0
}
static void USBHMSCClose(void *pvInstance)
Definition: usbhmsc.c:172

This constant global structure defines the Mass Storage Class Driver that is provided with the USB library.


Copyright 2016, Texas Instruments Incorporated