USB Component  Version 6.4
MDK-Professional Middleware for USB Device and Host
 All Data Structures Functions Variables Enumerations Enumerator Groups Pages
MSC: Mass Storage Class Functions

USB Host functions to support Mass Storage Class (MSC) USB Devices. More...

Content

 Configuration
 Configuration of the USB Host MSC Class in µVision.
 

Functions

usbStatus USBH_MSC_GetDeviceStatus (uint8_t instance)
 Get status of Mass Storage Device.
 
usbStatus USBH_MSC_Read (uint8_t instance, uint32_t lba, uint32_t cnt, uint8_t *buf)
 Read requested number of blocks from Mass Storage Device.
 
usbStatus USBH_MSC_Write (uint8_t instance, uint32_t lba, uint32_t cnt, const uint8_t *buf)
 Write requested number of blocks to Mass Storage Device.
 
usbStatus USBH_MSC_ReadCapacity (uint8_t instance, uint32_t *block_count, uint32_t *block_size)
 Read capacity of Mass Storage Device.
 

Description

USB Host functions to support Mass Storage Class (MSC) USB Devices.

The Mass Storage Class (MSC) in the USB Host Component provides physical access to a data storage device. The USB MSC drive in the File System Component gives file I/O access to that data storage.

Software Stack
The following picture shows how the software stack is built-up for MSC device support:

usbh_msc_sw_stack.png

Refer to:

Software Structure
The application starts the USB Host by calling USBH_Initialize. The USB Host Core will wait until an USB MSC device is attached to the system. As soon as this happens it will enumerate the device and it will be ready to be used by the application. The handling of the MSC class events is implemented in USBH_MSC_Thread.

The data functions USBH_MSC_Read and USBH_MSC_Write can be either called by the user thread directly or called indirectly when the user thread is using file system routines like fread/fwrite which use the USB MSC Device as media for data storage.

msc_inline_mscgraph_8

Implementation

Steps to create an USB Host application with MSC support:

User Code Template USBH_MSC.c

/*------------------------------------------------------------------------------
* MDK Middleware - Component ::USB:Host:MSC
* Copyright (c) 2004-2015 ARM Germany GmbH. All rights reserved.
*------------------------------------------------------------------------------
* Name: USBH_MSC.c
* Purpose: Functions to access USB storage device via USB Host
* Rev.: V6.3
*----------------------------------------------------------------------------*/
/*
* USBH_MSC.c is a code template for the application specific functionality of
* the USB Host MSC class. It implements the access to a USB storage device and
* allows file I/O via the File System component.
*
* USBH_MSC.h is the related header file.
*
* First to enable USB Host Controller (if not already enabled) call:
* USBH_Initialize (ctrl_num);
*
* To access files on a USB storage device use below code sample:
* int32_t media_status, media_status_previous = USBH_MSC_ERROR_DRIVE;
* for (;;) {
* media_status = USBH_MSC_DriveGetMediaStatus (drive_name);
* if ((media_status == USBH_MSC_OK) &&
* (media_status_previous != USBH_MSC_OK)) {
* switch (USBH_MSC_DriveMount (drive_name)) {
* case USBH_MSC_OK:
* fopen (...);
* break;
* case USBH_MSC_ERROR_FORMAT:
* fformat (drive_name, "/FAT32");
* fopen (...);
* break;
* case USBH_MSC_ERROR:
* // Mount error
* break;
* }
* }
* media_status_previous = media_status;
* osWait (1000); // polling interval for media status (1 second)
* }
*
* Now file I/O can be performed using fopen, fread, fwrite, fclose and other
* functions of the File System component
*
* When drive is not to be used any more call:
* USBH_MSC_DriveUnmount (drive_name);
*
* When USB Host Controller is not to be used any more call:
* USBH_Uninitialize (ctrl_num);
*/
#include "RTE_Components.h" // Component selection
#include "USBH_MSC.h" // Access storage via USB Host
#if (!defined (RTE_FileSystem_Drive_USB_0) && !defined (RTE_FileSystem_Drive_USB_1))
#error "Project does not contain USB storage device support"
#endif
int32_t USBH_MSC_DriveGetMediaStatus (const char *drive_name) {
usbStatus ustatus;
uint8_t drive_num;
drive_num = drive_name[1] - '0'; // get drive number from drive name
ustatus = USBH_MSC_GetDeviceStatus (drive_num);
if (ustatus != usbOK) return USBH_MSC_ERROR_DRIVE;
return USBH_MSC_OK;
}
int32_t USBH_MSC_DriveMount (const char *drive_name) {
fsStatus fstatus;
fstatus = finit (drive_name);
if (fstatus != fsOK) return USBH_MSC_ERROR;
fstatus = fmount (drive_name);
switch (fstatus) {
case fsOK: break;
case fsNoFileSystem: return USBH_MSC_ERROR_FORMAT;
default: return USBH_MSC_ERROR;
}
return USBH_MSC_OK;
}
int32_t USBH_MSC_DriveUnmount (const char *drive_name) {
fsStatus fstatus;
fstatus = funmount (drive_name);
if (fstatus != fsOK) return USBH_MSC_ERROR;
fstatus = funinit (drive_name);
if (fstatus != fsOK) return USBH_MSC_ERROR;
return USBH_MSC_OK;
}
uint64_t USBH_MSC_DriveGetCapacity (const char *drive_name) {
usbStatus ustatus;
uint32_t block_count;
uint32_t block_size;
uint8_t drive_num;
drive_num = drive_name[1] - '0'; // get drive number from drive name
ustatus = USBH_MSC_GetDeviceStatus (drive_num);
if (ustatus != usbOK) return 0;
ustatus = USBH_MSC_ReadCapacity (drive_num, &block_count, &block_size);
if (ustatus != usbOK) return 0;
return (((uint64_t)block_count) * ((uint64_t)block_size));
}

Function Documentation

usbStatus USBH_MSC_GetDeviceStatus ( uint8_t  instance)

Get status of Mass Storage Device.

Parameters
[in]instanceinstance of MSC Device.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_MSC_GetDeviceStatus checks if a mass storage device is connected and initialized.

The argument instance specifies the MSC device instance.

Code Example

int32_t USBH_MSC_DriveGetMediaStatus (const char *drive_name) {
usbStatus ustatus;
uint8_t drive_num;
drive_num = drive_name[1] - '0'; // get drive number from drive name
ustatus = USBH_MSC_GetDeviceStatus (drive_num);
if (ustatus != usbOK) return USBH_MSC_ERROR_DRIVE;
return USBH_MSC_OK;
}
usbStatus USBH_MSC_Read ( uint8_t  instance,
uint32_t  lba,
uint32_t  cnt,
uint8_t *  buf 
)

Read requested number of blocks from Mass Storage Device.

Parameters
[in]instanceinstance of MSC Device.
[in]lbalogical block address of first block to read.
[in]cntnumber of contiguous blocks to read.
[out]bufdata buffer in which to read data.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_MSC_Read reads data from physical memory blocks of a mass storage device.

The argument instance specifies the MSC device instance.

The argument lba is the physical address of the first block to be read.

The argument cnt is the number of blocks to be read.

The argument buf is a pointer to the location where the data will be stored.

Note
This function is typically used by the File System Component to provide file I/O access.

Code Example

unsigned char buf[0x10000];
usbStatus ustatus;
ustatus = USBH_MSC_Read (0, 10, 1, buf);
if (ustatus == usbOK) {
// data successfully written
}
usbStatus USBH_MSC_ReadCapacity ( uint8_t  instance,
uint32_t *  block_count,
uint32_t *  block_size 
)

Read capacity of Mass Storage Device.

Parameters
[in]instanceinstance of MSC Device.
[out]block_countpointer to where total number of blocks available will be read.
[out]block_sizepointer to where block size will be read.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_MSC_ReadCapacity gets information about the capacity of a mass storage device.

The argument instance specifies the MSC device instance.

The argument block_count is a pointer to a variable that stores the total number of available blocks.

The argument block_size is a pointer to a variable that stores the block size (in bytes).

Code Example

uint64_t USBH_MSC_DriveGetCapacity (const char *drive_name) {
usbStatus ustatus;
uint32_t block_count;
uint32_t block_size;
uint8_t drive_num;
drive_num = drive_name[1] - '0'; // get drive number from drive name
ustatus = USBH_MSC_GetDeviceStatus (drive_num);
if (ustatus != usbOK) return 0;
ustatus = USBH_MSC_ReadCapacity (drive_num, &block_count, &block_size);
if (ustatus != usbOK) return 0;
return (((uint64_t)block_count) * ((uint64_t)block_size));
}
usbStatus USBH_MSC_Write ( uint8_t  instance,
uint32_t  lba,
uint32_t  cnt,
const uint8_t *  buf 
)

Write requested number of blocks to Mass Storage Device.

Parameters
[in]instanceinstance of MSC Device.
[in]lbalogical address of first block to write.
[in]cntnumber of contiguous blocks to write.
[in]bufdata buffer containing data to write.
Returns
status code that indicates the execution status of the function as defined with usbStatus.

The function USBH_MSC_Write writes data to physical memory blocks of the mass storage device.

The argument instance specifies the MSC device instance.

The argument lba is the physical address of the first block to be written.

The argument cnt is the number of blocks to be written.

The argument buf is a pointer to the location that contains the data to be written.

Note
This function is typically used by the File System Component to provide file I/O access.

Code Example

unsigned char buf[0x10000];
usbStatus ustatus;
memset (buf, 0x55, sizeof (buf));
ustatus = USBH_MSC_Write (0, 10, 1, buf);
if (ustatus == usbOK) {
// data successfully written
}