EFM32 Happy Gecko Software Documentation  efm32hg-doc-5.1.2

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 )

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_Read10_TypeDef
 SCSI Read 10 Command Descriptor Block (CDB) 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_RequestSense_TypeDef
 SCSI Request Sense Command Descriptor Block (CDB) typedef. More...
 
struct  MSDSCSI_RequestSenseData_TypeDef
 SCSI Request Sense response data typedef. More...
 
struct  MSDSCSI_StartStopUnit_TypeDef
 SCSI Start Stop Unit Command Descriptor Block (CDB) typedef. More...
 
struct  MSDSCSI_Verify10_TypeDef
 SCSI Verify 10 Command Descriptor Block (CDB) typedef. More...
 
struct  MSDSCSI_Write10_TypeDef
 SCSI Write 10 Command Descriptor Block (CDB) typedef. More...
 

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. More...
 

Functions

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. More...
 
void MSDD_Init (int activityLedPort, uint32_t activityLedPin)
 Initialize MSD device. More...
 
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". More...
 
void MSDD_StateChangeEvent (USBD_State_TypeDef oldState, USBD_State_TypeDef newState)
 Called whenever the USB device has changed its device state. More...
 
bool MSDH_GetBlockSize (uint32_t *blockSize)
 Get blocksize from the device. More...
 
bool MSDH_GetSectorCount (uint32_t *sectorCount)
 Get sectorcount from the device. More...
 
bool MSDH_GetSectorSize (uint16_t *sectorSize)
 Get sectorsize from the device. More...
 
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. More...
 
bool MSDH_ReadSectors (uint32_t lba, uint16_t sectors, void *data)
 Read sectors from device. More...
 
bool MSDH_WriteSectors (uint32_t lba, uint16_t sectors, const void *data)
 Write sectors to device. More...
 

Macro Definition 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 50 of file msdscsi.h.

Referenced by MSDD_Init().

#define SCSI_READCAPACITYDATA_LEN   8U

SCSI Read Capacity response data length.

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

Referenced by MSDD_Init().

#define SCSI_REQUESTSENSEDATA_LEN   18U

SCSI Request Sense response data length.

Definition at line 49 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_STARTSTOPUNIT_LEN   6U

SCSI Start Stop Unit CDB length.

Definition at line 47 of file msdscsi.h.

Referenced by MSDD_Init().

#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

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

References MSDBOT_CBW_TypeDef::CBWCB, SCSI_STARTSTOP_UNIT, SL_MIN, and USBD_StallEp().

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

References CMU_ClockEnable(), cmuClock_GPIO, GPIO_PinModeSet(), gpioModePushPull, 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 319 of file msdd.c.

References USB_Setup_TypeDef::bRequest, CLEAR_FEATURE, USB_Setup_TypeDef::Direction, USB_Setup_TypeDef::Recipient, USB_Setup_TypeDef::Type, USB_FEATURE_ENDPOINT_HALT, USB_MSD_BOTRESET, USB_MSD_GETMAXLUN, USB_SETUP_DIR_IN, USB_SETUP_DIR_OUT, USB_SETUP_RECIPIENT_ENDPOINT, USB_SETUP_RECIPIENT_INTERFACE, USB_SETUP_TYPE_CLASS, USB_SETUP_TYPE_STANDARD, USB_STATUS_OK, USB_STATUS_REQ_UNHANDLED, USBD_UnStallEp(), USBD_Write(), USB_Setup_TypeDef::wIndex, USB_Setup_TypeDef::wLength, and USB_Setup_TypeDef::wValue.

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

References USBD_STATE_CONFIGURED, and USBD_STATE_SUSPENDED.

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 237 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 188 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 211 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 61 of file msdh.c.

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

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 266 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 287 of file msdh.c.

References MSDSCSI_Write10().