Gecko USB MSD

Detailed Description

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 )

Data Structures

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

Macros

#define MEDIA_BUFSIZ   4096
 
#define SCSI_INQUIRY   0x12
 
#define SCSI_INQUIRYDATA_LEN   36U
 
#define SCSI_READ10   0x28
 
#define SCSI_READ10_LEN   10U
 
#define SCSI_READCAPACITY   0x25
 
#define SCSI_READCAPACITY_LEN   10U
 
#define SCSI_READCAPACITYDATA_LEN   8U
 
#define SCSI_REQUESTSENSE   0x03
 
#define SCSI_REQUESTSENSE_LEN   6U
 
#define SCSI_REQUESTSENSEDATA_LEN   18U
 
#define SCSI_STARTSTOP_UNIT   0x1B
 
#define SCSI_STARTSTOPUNIT_LEN   6U
 
#define SCSI_TESTUNIT_READY   0x00
 
#define SCSI_VERIFY10   0x2F
 
#define SCSI_VERIFY10_LEN   10U
 
#define SCSI_WRITE10   0x2A
 
#define SCSI_WRITE10_LEN   10U
 

Enumerations

enum  MSDBOT_Status_TypeDef {
  MSDBOT_STATUS_OK = 0,
  MSDBOT_INIT_ERROR = -1,
  MSDBOT_CMD_FAILED = -2,
  MSDBOT_XFER_ERROR = -3
}
 MSDBOT status enumerator.
 

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. This function should be called on a regular basis from your main loop. It cannot be called from within an interrupt handler.
 
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. This function overrides standard CLEAR_FEATURE commands, and implements MSD class commands "Bulk-Only Mass Storage Reset" and "Get Max LUN".
 
void MSDD_StateChangeEvent (USBD_State_TypeDef oldState, USBD_State_TypeDef newState)
 Called whenever the USB device has changed its device state.
 
bool MSDH_GetBlockSize (uint32_t *blockSize)
 Get blocksize from the 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_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.
 
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.
 

Macro Definition Documentation

#define MEDIA_BUFSIZ   4096

Intermediate media storage buffer size

Definition at line 47 of file msdd.h.

#define SCSI_INQUIRY   0x12

SCSI Inquiry command opcode.

Definition at line 50 of file msdscsi.h.

#define SCSI_INQUIRYDATA_LEN   36U

SCSI Inquiry response data length.

Definition at line 60 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 53 of file msdscsi.h.

#define SCSI_READ10_LEN   10U

SCSI Read (10) CBD length.

Definition at line 57 of file msdscsi.h.

Referenced by MSDD_Init(), and MSDSCSI_Init().

#define SCSI_READCAPACITY   0x25

SCSI Read Capacity command opcode.

Definition at line 52 of file msdscsi.h.

#define SCSI_READCAPACITY_LEN   10U

SCSI Read Capacity CDB length.

Definition at line 64 of file msdscsi.h.

Referenced by MSDD_Init().

#define SCSI_READCAPACITYDATA_LEN   8U

SCSI Read Capacity response data length.

Definition at line 65 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 49 of file msdscsi.h.

#define SCSI_REQUESTSENSE_LEN   6U

SCSI Request Sense CDB length.

Definition at line 62 of file msdscsi.h.

Referenced by MSDD_Init().

#define SCSI_REQUESTSENSEDATA_LEN   18U

SCSI Request Sense response data length.

Definition at line 63 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 51 of file msdscsi.h.

Referenced by MSDD_Handler().

#define SCSI_STARTSTOPUNIT_LEN   6U

SCSI Start Stop Unit CDB length.

Definition at line 61 of file msdscsi.h.

Referenced by MSDD_Init().

#define SCSI_TESTUNIT_READY   0x00

SCSI Test Unit Ready command opcode.

Definition at line 48 of file msdscsi.h.

#define SCSI_VERIFY10   0x2F

SCSI Verify (10) command opcode.

Definition at line 55 of file msdscsi.h.

#define SCSI_VERIFY10_LEN   10U

SCSI Verify (10) CDB length.

Definition at line 59 of file msdscsi.h.

Referenced by MSDD_Init().

#define SCSI_WRITE10   0x2A

SCSI Write (10) command opcode.

Definition at line 54 of file msdscsi.h.

#define SCSI_WRITE10_LEN   10U

SCSI Write (10) CDB length.

Definition at line 58 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 109 of file msdbot.h.

Function Documentation

int MSDBOT_Init ( USBH_Ep_TypeDef *  out,
USBH_Ep_TypeDef *  in 
)

MSDBOT module initialization.

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

Definition at line 82 of file msdbot.c.

References MSDBOT_INIT_ERROR, and MSDBOT_STATUS_OK.

Referenced by MSDSCSI_Init().

int MSDBOT_Xfer ( void *  cbw,
void *  data 
)

Perform an MSD Bulk Only Transfer (BOT).

Parameters
[in]cbwPointer to a Command Block Wrapper (CBW) data structure.
[in]dataData 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 122 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().

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 271 of file msdd.c.

References MSDBOT_CBW_TypeDef::CBWCB, SCSI_STARTSTOP_UNIT, and SL_MIN.

void MSDD_Init ( int  activityLedPort,
uint32_t  activityLedPin 
)

Initialize MSD device.

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

Definition at line 229 of file msdd.c.

References SCSI_INQUIRYDATA_LEN, SCSI_READ10_LEN, SCSI_READCAPACITY_LEN, SCSI_READCAPACITYDATA_LEN, SCSI_REQUESTSENSE_LEN, SCSI_REQUESTSENSEDATA_LEN, SCSI_STARTSTOPUNIT_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]setupPointer to an USB setup packet.
Returns
An appropriate status/error code. See USB_Status_TypeDef.

Definition at line 334 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]oldStateThe device USB state just leaved. See USBD_State_TypeDef.
[in]newStateNew (the current) USB device state. See USBD_State_TypeDef.

Definition at line 409 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]blockSizeThe block size of device storage memory.
Returns
Returns true on success, false otherwise.

Definition at line 251 of file msdh.c.

References MSDSCSI_ReadCapacity(), SL_ALIGN, and SL_ATTRIBUTE_ALIGN.

bool MSDH_GetSectorCount ( uint32_t *  sectorCount)

Get sectorcount from the device.

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

Definition at line 200 of file msdh.c.

References MSDSCSI_ReadCapacity(), SL_ALIGN, and SL_ATTRIBUTE_ALIGN.

bool MSDH_GetSectorSize ( uint16_t *  sectorSize)

Get sectorsize from the device.

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

Definition at line 224 of file msdh.c.

References MSDSCSI_ReadCapacity(), SL_ALIGN, and SL_ATTRIBUTE_ALIGN.

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]usbDeviceInfoPointer to USB enumeration information. usbDeviceInfo must have been initialized by a prior call to USBH_WaitForDeviceConnectionB().
[in]usbDeviceInfoSizeThe size of the usbDeviceInfo data buffer.
Returns
Returns true on success, false otherwise.

Definition at line 85 of file msdh.c.

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

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

Read sectors from device.

Parameters
[in]lbaSector address (LBA) of first sector to read.
[in]sectorsNumber of sectors to read.
[out]dataData buffer through which data is returned to caller.
Returns
Returns true on success, false otherwise.

Definition at line 281 of file msdh.c.

References MSDSCSI_Read10().

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

Write sectors to device.

Parameters
[in]lbaSector address (LBA) of first sector to write.
[in]sectorsNumber of sectors to write.
[out]dataData buffer containing data to be written.
Returns
Returns true on success, false otherwise.

Definition at line 302 of file msdh.c.

References MSDSCSI_Write10().