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