Macros | Functions | Variables
usbdmsc.c File Reference

USB Mass storage device class driver. More...

#include "types.h"
#include "usbdmsc.h"
#include "usbmsc.h"
#include "usblib.h"
#include "usbdevice.h"
#include "usblibpriv.h"
#include "usb_dev_object.h"
#include "usb_dev_dman.h"

Macros

#define USB_PACKET_LENGTH   512
 USB packet length.
 
#define MAX_TRANSFER_SIZE   USB_PACKET_LENGTH
 USB transfer size for transfer of data.
 
#define COMMAND_BUFFER_SIZE   64
 USB transfer size for transfer fo command.
 
#define USB_MSC_SUBCLASS_SCSI   0x6
 These are fields that are used by the USB descriptors for the Mass Storage Class.
 
#define DATA_IN_ENDPOINT   1
 Data In endpoitn. More...
 
#define DATA_OUT_ENDPOINT   2
 Data out endpoint.
 
#define DATA_IN_EP_MAX_SIZE   MAX_TRANSFER_SIZE
 Max packet size for bulk in endpoint.
 
#define DATA_OUT_EP_MAX_SIZE   MAX_TRANSFER_SIZE
 Max packet size for bulk out endpoint.
 
#define STATE_SCSI_IDLE   0x00
 No command in progress. More...
 
#define STATE_SCSI_SEND_BLOCKS   0x01
 Sending and reading logical blocks.
 
#define STATE_SCSI_RECEIVE_BLOCKS   0x02
 Receiving and writing logical blocks.
 
#define STATE_SCSI_SEND_STATUS   0x03
 Send the status once the previous command is complete.
 
#define STATE_SCSI_SENT_STATUS   0x04
 Status was prepared to be sent and now waiting for it to have gone out.
 
#define STATE_SCSI_COMMAND_RCVD   0x05
 Reserved SCSI command.
 

Functions

static void HandleDisconnect (void *pvInstance)
 This function is called by the USB device stack whenever the device is disconnected from the host. More...
 
static void ConfigChangeHandler (void *pvInstance, uint32_t ulValue, uint32_t ulIndex)
 This function is called by the USB device stack whenever the device configuration changes.
 
static void HandleEndpoints (struct usbGadgetObj *pGadgetObject, usbGenericEvent_t endptEvent, uint32_t length)
 This function is called to handle the interrupts on the Bulk endpoints for the mass storage class.
 
static void HandleRequests (struct usbGadgetObj *pGadgetObject, usbEndpt0event_t endptEvent, usbSetupPkt_t *setup)
 This function is called by the USB device stack whenever a non-standard request is received. More...
 
static void USBDSCSISendStatus (const tUSBDMSCDevice *psDevice, void *pUsbGadgetObj)
 This function is used to send out the response data based on the current status of the mass storage class.
 
uint32_t USBDSCSICommand (const tUSBDMSCDevice *psDevice, tMSCCBW *pSCSICBW, void *pUsbGadgetObj)
 This function is used to handle all SCSI commands.
 
static void HandleDevice (void *pvInstance, uint32_t ulRequest, void *pvRequestData)
 Device instance specific handler.
 
static void USBDSCSIModeSense6 (const tUSBDMSCDevice *psDevice, tMSCCBW *pSCSICBW, void *pUsbGadgetObj)
 This function is used to handle the SCSI Mode Sense 6 command when it is received from the host.
 
static void USBDSCSIWrite10 (const tUSBDMSCDevice *psDevice, tMSCCBW *pSCSICBW, void *pUsbGadgetObj)
 This function is used to handle the SCSI Read 10 command when it is received from the host.
 
static void USBDSCSIRead10 (const tUSBDMSCDevice *psDevice, tMSCCBW *pSCSICBW, void *pUsbGadgetObj)
 
static void USBDSCSIRequestSense (const tUSBDMSCDevice *psDevice, void *pUsbGadgetObj)
 This function is used to handle the SCSI Request Sense command when it is received from the host.
 
static void USBDSCSIReadCapacity (const tUSBDMSCDevice *psDevice, void *pUsbGadgetObj)
 This function is used to handle the SCSI Read Capacity command when it is received from the host. More...
 
static void USBDSCSIReadCapacities (const tUSBDMSCDevice *psDevice, void *pUsbGadgetObj)
 
static void USBDSCSIInquiry (const tUSBDMSCDevice *psDevice, void *pUsbGadgetObj)
 This function is used to handle the SCSI Inquiry command when it is received from the host. More...
 
uint8_t g_pucCommand[COMMAND_BUFFER_SIZE__attribute__ ((aligned(32U)))
 Local buffer to read in data and process them. More...
 
void * USBDMSCInit (void *pUsbGadgetObj, tUSBDMSCDevice *psDevice)
 This function should be called once for the mass storage class device to initialized basic operation and prepare for enumeration. More...
 
void * USBDMSCCompositeInit (void *pUsbGadgetObj, tUSBDMSCDevice *psDevice)
 This function should be called once for the mass storage class device to initialized basic operation and prepare for enumeration. More...
 
void USBDMSCMediaChange (void *pvInstance, tUSBDMSCMediaStatus eMediaStatus)
 This function is used by an application if it can detect insertion or removal of the media. More...
 

Variables

static const uint8_t g_pMSCDeviceDescriptor []
 Device Descriptor. This is stored in RAM to allow several fields to be changed at runtime based on the application requirements.
 
static uint8_t g_pMSCDescriptor []
 Mass storage device configuration descriptor. More...
 
const uint8_t g_pMSCInterface []
 The remainder of the configuration descriptor is stored in flash since we don't need to modify anything in it at runtime.
 
usbConfigSection_t g_sMSCConfigSection
 
usbConfigSection_tg_psMSCSections []
 This array lists all the sections that must be concatenated to make a single, complete bulk device configuration descriptor.
 
usbConfigHeader_tg_pMSCConfigDescriptors []
 
tDeviceInfo g_sMSCDeviceInfo
 Device information structure for USB MSC device.
 

Detailed Description

USB Mass storage device class driver.

Macro Definition Documentation

#define DATA_IN_ENDPOINT   1

Data In endpoitn.

Endpoints to use for each of the endpoints in the driver

#define STATE_SCSI_IDLE   0x00

No command in progress.

The current state for the SCSI commands that are being handled and are stored in the tMSCInstance.ucSCSIState structure member.

Function Documentation

tMSCCSW g_sSCSICSW __attribute__ ( (aligned(32U))  )

Local buffer to read in data and process them.

The current transfer state.

static void HandleDisconnect ( void *  pvInstance)
static

This function is called by the USB device stack whenever the device is disconnected from the host.

Parameters
pvInstanceInstance data for this request.
static void HandleRequests ( struct usbGadgetObj pGadgetObject,
usbEndpt0event_t  endptEvent,
usbSetupPkt_t setup 
)
static

This function is called by the USB device stack whenever a non-standard request is received.

Parameters
pGadgetObjectpointer to the gadget object.
endptEvntType of the endpoint event which has occured.
setupThe setup packet received from the host.

This call parses the provided request structure to determine the command. The only mass storage command supported over endpoint 0 is the Get Max LUN command.

Return values
None.
void* USBDMSCCompositeInit ( void *  pDcdObject,
tUSBDMSCDevice psMSCDevice 
)

This function should be called once for the mass storage class device to initialized basic operation and prepare for enumeration.

Parameters
pDcdObjectpointer to the USB DCD object.
psMSCDevicepoints to a structure containing parameters customizing the operation of the mass storage device.

An application wishing to make use of a composite USB bulk communication channel for MSC class needs to call this function. This function is used for initializing an instance related information of the MSC device.

This function returns a void pointer that must be passed in to all other APIs used by the mass storage class.

See the documentation on the tUSBDMSCDevice structure for more information on how to properly fill the structure members.

Return values
Returns0 on failure or a non-zero void pointer on success.
void* USBDMSCInit ( void *  pDcdObject,
tUSBDMSCDevice psMSCDevice 
)

This function should be called once for the mass storage class device to initialized basic operation and prepare for enumeration.

Parameters
pDcdObjectpointer to the USB DCD object.
psMSCDevicepoints to a structure containing parameters customizing the operation of the mass storage device.

In order for an application to initialize the USB device mass storage class, it must first call this function with the a valid mass storage device class structure in the psDevice parameter. This allows this function to initialize the USB controller and device code to be prepared to enumerate and function as a USB mass storage device.

This function returns a void pointer that must be passed in to all other APIs used by the mass storage class.

See the documentation on the tUSBDMSCDevice structure for more information on how to properly fill the structure members.

Return values
Returns0 on failure or a non-zero void pointer on success.
void USBDMSCMediaChange ( void *  pvInstance,
tUSBDMSCMediaStatus  eMediaStatus 
)

This function is used by an application if it can detect insertion or removal of the media.

Parameters
pvInstanceis the mass storage device instance that had a media change.
eMediaStatusis the updated status for the media.

This function should be called by an application when it detects a change in the status of the media in use by the USB mass storage class. The eMediaStatus parameter will indicate the new status of the media and can also indicate that the application has no knowledge of the media state.

There are currently the three following values for the eMediaStatus parameter:

  • USBDMSC_MEDIA_PRESENT indicates that the media is present or has been added.
  • USBDMSC_MEDIA_NOTPRESENT indicates that the media is not present or was removed.
  • USBDMSC_MEDIA_UNKNOWN indicates that the application has no knowledge of the media state and the USB mass storage class.

It will be left up to the application to call this function whenever it detects a change or simply call it once with USBDMSC_MEDIA_UNKNOWN and allow the mass storage class to infer the state from the remaining device APIs.

Note
It is recommended that the application use this function to inform the mass storage class of media state changes as it will lead to a more responsive system.
static void USBDSCSIInquiry ( const tUSBDMSCDevice psDevice,
void *  pUsbGadgetObj 
)
static

This function is used to handle the SCSI Inquiry command when it is received from the host.

Parameters
psDevicePointer to the USBMSCDevice.
pUsbGaddetObjPointer to the USB gadget object.
static void USBDSCSIRead10 ( const tUSBDMSCDevice psDevice,
tMSCCBW *  pSCSICBW,
void *  pUsbGadgetObj 
)
static

This function is used to handle the SCSI Read 10 command when it is received from the host.

static void USBDSCSIReadCapacities ( const tUSBDMSCDevice psDevice,
void *  pUsbGadgetObj 
)
static

This function is used to handle the SCSI Read Capacities command when it is received from the host.

Parameters
psDevicePointer to the USBMSCDevice.
pUsbGaddetObjPointer to the USB gadget object.
static void USBDSCSIReadCapacity ( const tUSBDMSCDevice psDevice,
void *  pUsbGadgetObj 
)
static

This function is used to handle the SCSI Read Capacity command when it is received from the host.

Parameters
psDevicePointer to the USBMSCDevice.
pUsbGaddetObjPointer to the USB gadget object.

Variable Documentation

usbConfigHeader_t* g_pMSCConfigDescriptors[]
Initial value:
=
{
&g_sMSCConfigHeader
}

Confguration descriptor

uint8_t g_pMSCDescriptor[]
static
Initial value:
=
{
9,
USB_DTYPE_CONFIGURATION,
USBShort(32),
1,
1,
0,
USB_CONF_ATTR_SELF_PWR,
250,
}
#define USBShort(usValue)
Definition: usblib.h:831

Mass storage device configuration descriptor.

It is vital that the configuration descriptor bConfigurationValue field (byte 6) is 1 for the first configuration and increments by 1 for each additional configuration defined here. This relationship is assumed in the device stack for simplicity even though the USB 2.0 specification imposes no such restriction on the bConfigurationValue values.

Note that this structure is deliberately located in RAM since we need to be able to patch some values in it based on client requirements.

usbConfigSection_t g_sMSCConfigSection
Initial value:
=
{
}
static uint8_t g_pMSCDescriptor[]
Mass storage device configuration descriptor.
Definition: usbdmsc.c:286

The mass storage configuration descriptor is defined as two sections, one containing just the 9 byte USB configuration descriptor and the other containing everything else that is sent to the host along with it.


Copyright 2016, Texas Instruments Incorporated