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
int	MSDBOT_Init (USBH_Ep_TypeDef out, USBH_Ep_TypeDef in)
	MSDBOT module initialization. More...

int	MSDBOT_Xfer (void cbw, void data)
	Perform an MSD Bulk Only Transfer (BOT). More...

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

bool	MSDSCSI_Init (USBH_Ep_TypeDef out, USBH_Ep_TypeDef in)
	MSDSCSI module initialization. More...

bool	MSDSCSI_Inquiry (MSDSCSI_InquiryData_TypeDef *data)
	Issue a SCSI Inquiry command. More...

bool	MSDSCSI_Read10 (uint32_t lba, uint16_t sectors, void *data)
	Issue a SCSI Read(10) command. More...

bool	MSDSCSI_ReadCapacity (MSDSCSI_ReadCapacityData_TypeDef *data)
	Issue a SCSI Read Capacity command. More...

bool	MSDSCSI_RequestSense (MSDSCSI_RequestSenseData_TypeDef *data)
	Issue a SCSI Request Sense command. More...

bool	MSDSCSI_TestUnitReady (void)
	Issue a SCSI Test Unit Ready command. More...

bool	MSDSCSI_Write10 (uint32_t lba, uint16_t sectors, const void *data)
	Perform a SCSI Write(10) command. 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

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 103 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 58 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 98 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 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] setup Pointer 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]	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 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] blockSize The 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] sectorCount Number 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] sectorSize The 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]	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 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, 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 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]	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 287 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 157 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 189 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.