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.

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

enum MSDBOT_Status_TypeDef

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 , 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 122 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 271 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 229 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 334 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 409 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 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 , 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 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() .

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