MsdKit Drivers

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

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 35 of file msdscsi.h .

#define SCSI_INQUIRYDATA_LEN   36U

SCSI Inquiry response data length.

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

#define SCSI_READ10_LEN   10U

SCSI Read (10) CBD length.

Definition at line 42 of file msdscsi.h .

Referenced by MSDD_Init() , and MSDSCSI_Init() .

#define SCSI_READCAPACITY   0x25

SCSI Read Capacity command opcode.

Definition at line 37 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 34 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 36 of file msdscsi.h .

Referenced by MSDD_Handler() .

#define SCSI_STARTSTOPUNIT_LEN   6U

SCSI Start Stop Unit CDB length.

Definition at line 46 of file msdscsi.h .

Referenced by MSDD_Init() .

#define SCSI_TESTUNIT_READY   0x00

SCSI Test Unit Ready command opcode.

Definition at line 33 of file msdscsi.h .

#define SCSI_VERIFY10   0x2F

SCSI Verify (10) command opcode.

Definition at line 40 of file msdscsi.h .

#define SCSI_VERIFY10_LEN   10U

SCSI Verify (10) CDB length.

Definition at line 44 of file msdscsi.h .

Referenced by MSDD_Init() .

#define SCSI_WRITE10   0x2A

SCSI Write (10) command opcode.

Definition at line 39 of file msdscsi.h .

#define SCSI_WRITE10_LEN   10U

SCSI Write (10) CDB length.

Definition at line 43 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 94 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 57 of file msdbot.c .

References MSDBOT_INIT_ERROR , MSDBOT_STATUS_OK , USBH_Ep_TypeDef::parentDevice , PORT_FULL_SPEED , and USBH_Device_TypeDef::speed .

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 97 of file msdbot.c .

References MSDBOT_CSW_TypeDef::bCSWStatus , MSDBOT_CBW_TypeDef::dCBWDataTransferLength , MSDBOT_CBW_TypeDef::Direction , MSDBOT_CMD_FAILED , MSDBOT_XFER_ERROR , USB_CLASS_MSD_CSW_CMDPASSED , USB_STATUS_EP_STALLED , USBH_ReadB() , USBH_UnStallEpB() , and USBH_WriteB() .

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 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] 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 204 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] setup Pointer to an USB setup packet.
Returns
An appropriate status/error code. See USB_Status_TypeDef.

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

Definition at line 226 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 175 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 199 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 60 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 , USBH_GetPortSpeed() , USBH_QueryDeviceB() , and USBTIMER_DelayMs() .

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 256 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 277 of file msdh.c .

References MSDSCSI_Write10() .

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 155 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() .

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 187 of file msdscsi.c .

References MSDBOT_Xfer() , and SCSI_INQUIRYDATA_LEN .

Referenced by MSDH_Init() .

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 212 of file msdscsi.c .

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

Referenced by MSDH_ReadSectors() .

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() .

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

References MSDBOT_Xfer() , and SCSI_REQUESTSENSEDATA_LEN .

Referenced by MSDH_Init() .

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() .

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 308 of file msdscsi.c .

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

Referenced by MSDH_WriteSectors() .