Msd
[Drivers]

Implements USB Mass Storage Class (MSC). More...

Collaboration diagram for Msd:

Data Structures

struct  MSDBOT_CBW_TypeDef
 Bulk Only Transport (BOT) Command Block Wrapper (CBW) typedef. More...
struct  MSDBOT_CSW_TypeDef
 Bulk Only Transport (BOT) Command Status Wrapper (CSW) typedef. More...
struct  MSDD_CmdStatus_TypeDef
 Status info for one BOT CBW -> Data I/O -> CSW cycle. More...
struct  MSDSCSI_Inquiry_TypeDef
 SCSI Inquiry Command Descriptor Block (CDB) typedef. More...
struct  MSDSCSI_InquiryData_TypeDef
 SCSI Inquiry response data typedef. More...
struct  MSDSCSI_RequestSense_TypeDef
 SCSI Request Sense Command Descriptor Block (CDB) typedef. More...
struct  MSDSCSI_RequestSenseData_TypeDef
 SCSI Request Sense response data typedef. More...
struct  MSDSCSI_ReadCapacity_TypeDef
 SCSI Read Capacity Command Descriptor Block (CDB) typedef. More...
struct  MSDSCSI_ReadCapacityData_TypeDef
 SCSI Read Capacity response data typedef. More...
struct  MSDSCSI_Read10_TypeDef
 SCSI Read 10 Command Descriptor Block (CDB) typedef. More...
struct  MSDSCSI_Write10_TypeDef
 SCSI Write 10 Command Descriptor Block (CDB) typedef. More...
struct  MSDSCSI_Verify10_TypeDef
 SCSI Verify 10 Command Descriptor Block (CDB) typedef. More...

Defines

#define MEDIA_BUFSIZ   4096
 Intermediate media storage buffer size.
#define SCSI_TESTUNIT_READY   0x00
 SCSI Test Unit Ready command opcode.
#define SCSI_REQUESTSENSE   0x03
 SCSI Request Sense command opcode.
#define SCSI_INQUIRY   0x12
 SCSI Inquiry command opcode.
#define SCSI_STARTSTOP_UNIT   0x1B
 SCSI Start Stop Unit command opcode.
#define SCSI_READCAPACITY   0x25
 SCSI Read Capacity command opcode.
#define SCSI_READ10   0x28
 SCSI Read (10) command opcode.
#define SCSI_WRITE10   0x2A
 SCSI Write (10) command opcode.
#define SCSI_VERIFY10   0x2F
 SCSI Verify (10) command opcode.
#define SCSI_READ10_LEN   10U
 SCSI Read (10) CBD length.
#define SCSI_WRITE10_LEN   10U
 SCSI Write (10) CDB length.
#define SCSI_VERIFY10_LEN   10U
 SCSI Verify (10) CDB length.
#define SCSI_INQUIRYDATA_LEN   36U
 SCSI Inquiry response data length.
#define SCSI_REQUESTSENSE_LEN   6U
 SCSI Request Sense CDB length.
#define SCSI_REQUESTSENSEDATA_LEN   18U
 SCSI Request Sense response data length.
#define SCSI_READCAPACITY_LEN   10U
 SCSI Read Capacity CDB length.
#define SCSI_READCAPACITYDATA_LEN   8U
 SCSI Read Capacity response data length.

Enumerations

enum  MSDBOT_Status_TypeDef {
  MSDBOT_STATUS_OK = 0,
  MSDBOT_INIT_ERROR = -1,
  MSDBOT_CMD_FAILED = -2,
  MSDBOT_XFER_ERROR = -3
}
 

MSDBOT status enumerator.

More...

Functions

int MSDBOT_Init (USBH_Ep_TypeDef *out, USBH_Ep_TypeDef *in)
 MSDBOT module initialization.
int MSDBOT_Xfer (void *cbw, void *data)
 Perform an MSD Bulk Only Transfer (BOT).
bool MSDD_Handler (void)
 Serve the MSD state machine.
void MSDD_Init (int activityLedPort, uint32_t activityLedPin)
 Initialize MSD device.
int MSDD_SetupCmd (const USB_Setup_TypeDef *setup)
 Called whenever a USB setup command is received.
void MSDD_StateChangeEvent (USBD_State_TypeDef oldState, USBD_State_TypeDef newState)
 Called whenever the USB device has changed its device state.
bool MSDH_Init (uint8_t *usbDeviceInfo, int usbDeviceInfoSize)
 Initialize an USB connected Mass Storage Device.
bool MSDH_GetSectorCount (uint32_t *sectorCount)
 Get sectorcount from the device.
bool MSDH_GetSectorSize (uint16_t *sectorSize)
 Get sectorsize from the device.
bool MSDH_GetBlockSize (uint32_t *blockSize)
 Get blocksize from the device.
bool MSDH_ReadSectors (uint32_t lba, uint16_t sectors, void *data)
 Read sectors from device.
bool MSDH_WriteSectors (uint32_t lba, uint16_t sectors, const void *data)
 Write sectors to device.
bool MSDSCSI_Init (USBH_Ep_TypeDef *out, USBH_Ep_TypeDef *in)
 MSDSCSI module initialization.
bool MSDSCSI_Inquiry (MSDSCSI_InquiryData_TypeDef *data)
 Issue a SCSI Inquiry command.
bool MSDSCSI_Read10 (uint32_t lba, uint16_t sectors, void *data)
 Issue a SCSI Read(10) command.
bool MSDSCSI_ReadCapacity (MSDSCSI_ReadCapacityData_TypeDef *data)
 Issue a SCSI Read Capacity command.
bool MSDSCSI_RequestSense (MSDSCSI_RequestSenseData_TypeDef *data)
 Issue a SCSI Request Sense command.
bool MSDSCSI_TestUnitReady (void)
 Issue a SCSI Test Unit Ready command.
bool MSDSCSI_Write10 (uint32_t lba, uint16_t sectors, const void *data)
 Perform a SCSI Write(10) command.

Detailed Description

Implements USB Mass Storage Class (MSC).

MSC implementation for device.

The source code of the device implementation resides in kits/common/drivers/msdd.c and msdd.h. The driver includes "msddmedia.h" to get the API definitions needed for media access. The drivers use the Bulk-Only Transport (BOT) mode of the MSC specification.

MSC device configuration options.

This section contains a description of the configuration options for the driver. The options are #define's which are expected to be found in the application "usbconfig.h" header file.

// USB interface number. Interfaces are numbered from zero to one less than
// the number of concurrent interfaces supported by the configuration.
// The interface number must be 0 for a standalone MSC device, for a
// composite device which includes a MSC interface it must not be in conflict
// with other device interfaces.
#define MSD_INTERFACE_NO ( 0 )

// Endpoint address for data reception.
#define MSD_BULK_OUT ( 0x01 )

// Endpoint address for data transmission.
#define MSD_BULK_IN ( 0x81 )
  

Define Documentation

#define MEDIA_BUFSIZ   4096

Intermediate media storage buffer size.

Definition at line 32 of file msdd.h.

#define SCSI_INQUIRY   0x12

SCSI Inquiry command opcode.

Definition at line 36 of file msdscsi.h.

#define SCSI_INQUIRYDATA_LEN   36U

SCSI Inquiry response data length.

Definition at line 46 of file msdscsi.h.

Referenced by MSDD_Init(), MSDSCSI_Init(), and MSDSCSI_Inquiry().

#define SCSI_READ10   0x28

SCSI Read (10) command opcode.

Definition at line 39 of file msdscsi.h.

#define SCSI_READ10_LEN   10U

SCSI Read (10) CBD length.

Definition at line 43 of file msdscsi.h.

Referenced by MSDD_Init(), and MSDSCSI_Init().

#define SCSI_READCAPACITY   0x25

SCSI Read Capacity command opcode.

Definition at line 38 of file msdscsi.h.

#define SCSI_READCAPACITY_LEN   10U

SCSI Read Capacity CDB length.

Definition at line 49 of file msdscsi.h.

Referenced by MSDD_Init().

#define SCSI_READCAPACITYDATA_LEN   8U

SCSI Read Capacity response data length.

Definition at line 50 of file msdscsi.h.

Referenced by MSDD_Init(), MSDSCSI_Init(), and MSDSCSI_ReadCapacity().

#define SCSI_REQUESTSENSE   0x03

SCSI Request Sense command opcode.

Definition at line 35 of file msdscsi.h.

#define SCSI_REQUESTSENSE_LEN   6U

SCSI Request Sense CDB length.

Definition at line 47 of file msdscsi.h.

Referenced by MSDD_Init().

#define SCSI_REQUESTSENSEDATA_LEN   18U

SCSI Request Sense response data length.

Definition at line 48 of file msdscsi.h.

Referenced by MSDD_Init(), MSDSCSI_Init(), and MSDSCSI_RequestSense().

#define SCSI_STARTSTOP_UNIT   0x1B

SCSI Start Stop Unit command opcode.

Definition at line 37 of file msdscsi.h.

Referenced by MSDD_Handler().

#define SCSI_TESTUNIT_READY   0x00

SCSI Test Unit Ready command opcode.

Definition at line 34 of file msdscsi.h.

#define SCSI_VERIFY10   0x2F

SCSI Verify (10) command opcode.

Definition at line 41 of file msdscsi.h.

#define SCSI_VERIFY10_LEN   10U

SCSI Verify (10) CDB length.

Definition at line 45 of file msdscsi.h.

Referenced by MSDD_Init().

#define SCSI_WRITE10   0x2A

SCSI Write (10) command opcode.

Definition at line 40 of file msdscsi.h.

#define SCSI_WRITE10_LEN   10U

SCSI Write (10) CDB length.

Definition at line 44 of file msdscsi.h.

Referenced by MSDD_Init(), and MSDSCSI_Init().


Enumeration Type Documentation

MSDBOT status enumerator.

Enumerator:
MSDBOT_STATUS_OK 

MSDBOT status, no error.

MSDBOT_INIT_ERROR 

MSDBOT initialization failure.

MSDBOT_CMD_FAILED 

MSDBOT command failure.

MSDBOT_XFER_ERROR 

MSDBOT transfer error.

Definition at line 103 of file msdbot.h.


Function Documentation

int MSDBOT_Init ( USBH_Ep_TypeDef *  out,
USBH_Ep_TypeDef *  in 
)

MSDBOT module initialization.

Parameters:
[in] out Pointer to an MSD bulk OUT endpoint structure.
[in] in Pointer to an MSD bulk IN endpoint structure.
Returns:
MSDBOT_STATUS_OK on success, else MSDBOT_INIT_ERROR.

Definition at line 58 of file msdbot.c.

References MSDBOT_INIT_ERROR, and MSDBOT_STATUS_OK.

Referenced by MSDSCSI_Init().

Here is the caller graph for this function:

int MSDBOT_Xfer ( void *  cbw,
void *  data 
)

Perform an MSD Bulk Only Transfer (BOT).

Parameters:
[in] cbw Pointer to a Command Block Wrapper (CBW) data structure.
[in] data Data buffer for data to be transferred.
Returns:
A positive (or zero) value indicating the number of bytes transferred.
A negative value indicates a transfer error code enumerated in MSDBOT_Status_TypeDef.

Definition at line 98 of file msdbot.c.

References MSDBOT_CSW_TypeDef::bCSWStatus, MSDBOT_CBW_TypeDef::dCBWDataTransferLength, MSDBOT_CBW_TypeDef::Direction, MSDBOT_CMD_FAILED, and MSDBOT_XFER_ERROR.

Referenced by MSDSCSI_Inquiry(), MSDSCSI_Read10(), MSDSCSI_ReadCapacity(), MSDSCSI_RequestSense(), MSDSCSI_TestUnitReady(), and MSDSCSI_Write10().

Here is the caller graph for this function:

bool MSDD_Handler ( void   ) 

Serve the MSD state machine.

This function should be called on a regular basis from your main loop. It cannot be called from within an interrupt handler.

Returns:
Returns true if there is no pending tasks to perform. This means that energymodes (sleep) functionality can be used.

Definition at line 244 of file msdd.c.

References MSDBOT_CBW_TypeDef::CBWCB, and SCSI_STARTSTOP_UNIT.

void MSDD_Init ( int  activityLedPort,
uint32_t  activityLedPin 
)

Initialize MSD device.

Parameters:
[in] activityLedPort Specify a GPIO port for a LED activity indicator (i.e. enum gpioPortX) Pass -1 if no indicator LED is available.
[in] activityLedPin Pin number on activityLedPort for the LED activity indicator.

Definition at line 202 of file msdd.c.

References SCSI_INQUIRYDATA_LEN, SCSI_READ10_LEN, SCSI_READCAPACITY_LEN, SCSI_READCAPACITYDATA_LEN, SCSI_REQUESTSENSE_LEN, SCSI_REQUESTSENSEDATA_LEN, SCSI_VERIFY10_LEN, and SCSI_WRITE10_LEN.

int MSDD_SetupCmd ( const USB_Setup_TypeDef *  setup  ) 

Called whenever a USB setup command is received.

This function overrides standard CLEAR_FEATURE commands, and implements MSD class commands "Bulk-Only Mass Storage Reset" and "Get Max LUN".

Parameters:
[in] setup Pointer to an USB setup packet.
Returns:
An appropriate status/error code. See USB_Status_TypeDef.

Definition at line 317 of file msdd.c.

void MSDD_StateChangeEvent ( USBD_State_TypeDef  oldState,
USBD_State_TypeDef  newState 
)

Called whenever the USB device has changed its device state.

Parameters:
[in] oldState The device USB state just leaved. See USBD_State_TypeDef.
[in] newState New (the current) USB device state. See USBD_State_TypeDef.

Definition at line 408 of file msdd.c.

bool MSDH_GetBlockSize ( uint32_t *  blockSize  ) 

Get blocksize from the device.

Note:
This function assumes that block size equals sector size.
Parameters:
[out] blockSize The block size of device storage memory.
Returns:
Returns true on success, false otherwise.

Definition at line 211 of file msdh.c.

References MSDSCSI_ReadCapacity().

Here is the call graph for this function:

bool MSDH_GetSectorCount ( uint32_t *  sectorCount  ) 

Get sectorcount from the device.

Parameters:
[out] sectorCount Number of sectors on the device.
Returns:
Returns true on success, false otherwise.

Definition at line 162 of file msdh.c.

References MSDSCSI_ReadCapacity().

Here is the call graph for this function:

bool MSDH_GetSectorSize ( uint16_t *  sectorSize  ) 

Get sectorsize from the device.

Parameters:
[out] sectorSize The size of device sectors.
Returns:
Returns true on success, false otherwise.

Definition at line 185 of file msdh.c.

References MSDSCSI_ReadCapacity().

Here is the call graph for this function:

bool MSDH_Init ( uint8_t *  usbDeviceInfo,
int  usbDeviceInfoSize 
)

Initialize an USB connected Mass Storage Device.

Checks if the device is a valid MSD device. Will perform all necessary MSD initialization.

Note:
This function assumes that prior calls to USBH_Init() and USBH_WaitForDeviceConnectionB() have been performed. The contents of the usbDeviceInfo data buffer will be overwritten.
Parameters:
[in] usbDeviceInfo Pointer to USB enumeration information. usbDeviceInfo must have been initialized by a prior call to USBH_WaitForDeviceConnectionB().
[in] usbDeviceInfoSize The size of the usbDeviceInfo data buffer.
Returns:
Returns true on success, false otherwise.

Definition at line 59 of file msdh.c.

References MSDSCSI_Init(), MSDSCSI_Inquiry(), MSDSCSI_ReadCapacity(), MSDSCSI_RequestSense(), and MSDSCSI_TestUnitReady().

Here is the call graph for this function:

bool MSDH_ReadSectors ( uint32_t  lba,
uint16_t  sectors,
void *  data 
)

Read sectors from device.

Parameters:
[in] lba Sector address (LBA) of first sector to read.
[in] sectors Number of sectors to read.
[out] data Data buffer through which data is returned to caller.
Returns:
Returns true on success, false otherwise.

Definition at line 240 of file msdh.c.

References MSDSCSI_Read10().

Here is the call graph for this function:

bool MSDH_WriteSectors ( uint32_t  lba,
uint16_t  sectors,
const void *  data 
)

Write sectors to device.

Parameters:
[in] lba Sector address (LBA) of first sector to write.
[in] sectors Number of sectors to write.
[out] data Data buffer containing data to be written.
Returns:
Returns true on success, false otherwise.

Definition at line 261 of file msdh.c.

References MSDSCSI_Write10().

Here is the call graph for this function:

bool MSDSCSI_Init ( USBH_Ep_TypeDef *  out,
USBH_Ep_TypeDef *  in 
)

MSDSCSI module initialization.

Parameters:
[in] out Pointer to an MSD bulk OUT endpoint structure.
[in] in Pointer to an MSD bulk IN endpoint structure.
Returns:
Returns true on success, false otherwise.

Definition at line 157 of file msdscsi.c.

References MSDBOT_Init(), MSDBOT_STATUS_OK, SCSI_INQUIRYDATA_LEN, SCSI_READ10_LEN, SCSI_READCAPACITYDATA_LEN, SCSI_REQUESTSENSEDATA_LEN, and SCSI_WRITE10_LEN.

Referenced by MSDH_Init().

Here is the call graph for this function:

Here is the caller graph for this function:

bool MSDSCSI_Inquiry ( MSDSCSI_InquiryData_TypeDef data  ) 

Issue a SCSI Inquiry command.

Parameters:
[out] data Inquiry response data buffer.
Returns:
Returns true on success, false otherwise.

Definition at line 189 of file msdscsi.c.

References MSDBOT_Xfer(), and SCSI_INQUIRYDATA_LEN.

Referenced by MSDH_Init().

Here is the call graph for this function:

Here is the caller graph for this function:

bool MSDSCSI_Read10 ( uint32_t  lba,
uint16_t  sectors,
void *  data 
)

Issue a SCSI Read(10) command.

Parameters:
[in] lba Sector address (LBA) of first sector to read.
[in] sectors Number of sectors to read.
[out] data Data buffer through which data is returned to caller.
Returns:
Returns true on success, false otherwise.

Definition at line 213 of file msdscsi.c.

References MSDSCSI_Read10_TypeDef::Lba, MSDBOT_Xfer(), and MSDSCSI_Read10_TypeDef::TransferLength.

Referenced by MSDH_ReadSectors().

Here is the call graph for this function:

Here is the caller graph for this function:

bool MSDSCSI_ReadCapacity ( MSDSCSI_ReadCapacityData_TypeDef data  ) 

Issue a SCSI Read Capacity command.

Parameters:
[out] data Read Capacity response data buffer.
Returns:
Returns true on success, false otherwise.

Definition at line 240 of file msdscsi.c.

References MSDSCSI_ReadCapacityData_TypeDef::LogicalBlockAddress, MSDSCSI_ReadCapacityData_TypeDef::LogicalBlockLength, MSDBOT_Xfer(), and SCSI_READCAPACITYDATA_LEN.

Referenced by MSDH_GetBlockSize(), MSDH_GetSectorCount(), MSDH_GetSectorSize(), and MSDH_Init().

Here is the call graph for this function:

Here is the caller graph for this function:

bool MSDSCSI_RequestSense ( MSDSCSI_RequestSenseData_TypeDef data  ) 

Issue a SCSI Request Sense command.

Parameters:
[out] data Request Sense response data buffer.
Returns:
Returns true on success, false otherwise.

Definition at line 267 of file msdscsi.c.

References MSDBOT_Xfer(), and SCSI_REQUESTSENSEDATA_LEN.

Referenced by MSDH_Init().

Here is the call graph for this function:

Here is the caller graph for this function:

bool MSDSCSI_TestUnitReady ( void   ) 

Issue a SCSI Test Unit Ready command.

Returns:
Returns true if device ready, false if device not ready or cmd transfer error.

Definition at line 283 of file msdscsi.c.

References MSDBOT_STATUS_OK, and MSDBOT_Xfer().

Referenced by MSDH_Init().

Here is the call graph for this function:

Here is the caller graph for this function:

bool MSDSCSI_Write10 ( uint32_t  lba,
uint16_t  sectors,
const void *  data 
)

Perform a SCSI Write(10) command.

Parameters:
[in] lba Sector address (LBA) of first sector to write.
[in] sectors Number of sectors to write.
[out] data Data buffer containing data to be written.
Returns:
Returns true on success, false otherwise.

Definition at line 307 of file msdscsi.c.

References MSDSCSI_Write10_TypeDef::Lba, MSDBOT_Xfer(), and MSDSCSI_Write10_TypeDef::TransferLength.

Referenced by MSDH_WriteSectors().

Here is the call graph for this function:

Here is the caller graph for this function: