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] 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 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] 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 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] 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 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] setup Pointer 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] 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 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] blockSize The 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] sectorCount Number 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] sectorSize The 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] 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 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] 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 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] 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 302 of file msdh.c .

References MSDSCSI_Write10() .