User API

User API reference of the Mass Storage Class. More...

Functions
void	USBD_MSCn_Initialize (void)
	Callback function called during USBD_Initialize to initialize all Logical Units of the USB MSC class instance. More...
void	USBD_MSCn_Uninitialize (void)
	Callback function called during USBD_Uninitialize to de-initialize all Logical Units of the USB MSC class instance. More...
bool	USBD_MSCn_GetCacheInfo (uint32_t *buffer, uint32_t *size)
	Callback function called to get cache information. More...
bool	USBD_MSCn_GetMediaCapacity (uint32_t *block_count, uint32_t *block_size)
	Callback function called to get media capacity. More...
bool	USBD_MSCn_Read (uint32_t lba, uint32_t cnt, uint8_t *buf)
	Callback function called to read data from media. More...
bool	USBD_MSCn_Write (uint32_t lba, uint32_t cnt, const uint8_t *buf)
	Callback function called to write data to media. More...
uint32_t	USBD_MSCn_CheckMedia (void)
	Callback function called to check media presence and write protect status. More...
uint8_t	USBD_MSCn_GetMaxLUN (void)
	Callback function called to get maximum number of logical units. More...
bool	USBD_MSCn_LUN_GetMediaCapacity (uint8_t lun, uint32_t *block_count, uint32_t *block_size)
	Callback function called to get media capacity of a logical unit. More...
bool	USBD_MSCn_LUN_Read (uint8_t lun, uint32_t lba, uint32_t cnt, uint8_t *buf)
	Callback function called to read data from media of a logical unit. More...
bool	USBD_MSCn_LUN_Write (uint8_t lun, uint32_t lba, uint32_t cnt, const uint8_t *buf)
	Callback function called to write data to media of a logical unit. More...
uint32_t	USBD_MSCn_LUN_CheckMedia (uint8_t lun)
	Callback function called to check media presence and write protect status of a logical unit. More...
int32_t	USBD_MSCn_SetMediaOwnerUSB (void)
	Set USB as media owner. More...
int32_t	USBD_MSCn_SetMediaOwnerFS (void)
	Set File System as media owner. More...

Description

User API reference of the Mass Storage Class.

Function Documentation

USBD_MSCn_Initialize()

void USBD_MSCn_Initialize

(

void

)

Callback function called during USBD_Initialize to initialize all Logical Units of the USB MSC class instance.

Returns

none.

The function USBD_MSCn_Initialize is called automatically upon initialization of a Mass Storage Class Device and needs no invocation in the user code.

Modify this function to the application's needs to allocate resources and initialize additional peripherals.

Code Example

#include "rl_usb.h"
  
void USBD_MSC0_Initialize (void) {
 
  uint32_t param_status;
 
  usbd_mscn_media_own = MEDIA_OWN_USB;  // Initially media is owned by USB
  media_ok            = false;          // Current media status (not initialized = not ok)
 
  if (finit (MEDIA_DRIVE) != fsOK) {    // Initialize File System
    return;                             // Exit if failed
  }
 
  param_status = 0U;                    // Parameter for function call is 0
                                        // Initialize media
  if (fs_ioc_device_ctrl (drv_id, fsDevCtrlCodeControlMedia, &param_status) != fsOK) {
    return;                             // Exit if failed
  }
 
  drv_id = fs_ioc_get_id (MEDIA_DRIVE); // Get ID of media drive
  if (drv_id < 0U)          { return; } // If ID is invalid exit
  if (fs_ioc_lock (drv_id)) {           // Lock media for USB usage
    return;                             // Exit if failed
  }
 
  media_ok = true;                      // Media was initialized and is ok
}

USBD_MSCn_Uninitialize()

void USBD_MSCn_Uninitialize

(

void

)

Callback function called during USBD_Uninitialize to de-initialize all Logical Units of the USB MSC class instance.

Returns

none.

The function USBD_MSCn_Uninitialize is called automatically upon de-initialization of a Mass Storage Class Device and needs no invocation in the user code. If USBD_MSCn_Initialize has been adapted to the application, USBD_MSCn_Uninitialize should release resources and should de-initialize peripherals.

Code Example

#include "rl_usb.h"
 
int main (void)  {
  ..
  USBD_Initialize (0);         // USB Device 0 Initialization
  ...
  USBD_Uninitialize (0);       // USB Device 0 De-Initialization
  ..
}

USBD_MSCn_GetCacheInfo()

bool USBD_MSCn_GetCacheInfo	(	uint32_t *	buffer,
		uint32_t *	size
	)

Callback function called to get cache information.

Parameters

[out]	buffer	cache buffer address.
[out]	size	cache buffer size. operation execution status : value true : operation succeeded value false : operation failed

The function USBD_MSCn_GetCacheInfo enables an MSC device to reuse RAM used by the File System for caching purposes as USB cache. This is required when a USB Host has control over the media so that it cannot be accessed by File System.

The argument buffer returns the cache buffer address, while the argument size returns the size of the cache buffer.

Code Example

#include "rl_usb.h"
 
bool USBD_MSC0_GetCacheInfo (uint32_t *buffer, uint32_t *size) {
 
  fsIOC_Cache cache_info;
 
  // Get cache settings of File System
  if (fs_ioc_get_cache(drv_id, &cache_info) != fsOK) {
    return false;                       // Exit if failed
  }
 
  // Use File Systems cache for MSC
  *buffer = (uint32_t)cache_info.buffer;// Cache buffer from File System
  *size   = cache_info.size;            // Cache size
 
  return true;
}

USBD_MSCn_GetMediaCapacity()

bool USBD_MSCn_GetMediaCapacity	(	uint32_t *	block_count,
		uint32_t *	block_size
	)

Callback function called to get media capacity.

Parameters

[out]	block_count	total number of blocks on media.
[out]	block_size	media block size. operation execution status : value true : operation succeeded value false : operation failed

The function USBD_MSCn_GetMediaCapacity can be used to determine the geometry of the attached storage media.

The argument block_count returns the total number of blocks on the media, while the argument block_size returns the block size of the media.

Code Example

#include "rl_usb.h"
 
bool USBD_MSC0_GetMediaCapacity (uint32_t *block_count, uint32_t *block_size) {
 
  fsMediaInfo media_info;
 
  // Read media information of actual media
  if (fs_ioc_read_info(drv_id, &media_info) != fsOK) {
    return false;                       // Exit if failed
  }
 
  *block_count = media_info.block_cnt;  // Total number of blocks on media
  *block_size  = media_info.read_blen;  // Block size of blocks on media
 
  return true;
}

USBD_MSCn_Read()

bool USBD_MSCn_Read	(	uint32_t	lba,
		uint32_t	cnt,
		uint8_t *	buf
	)

Callback function called to read data from media.

Parameters

[in]	lba	logical address of first block to read.
[in]	cnt	number of contiguous blocks to read from media.
[out]	buf	data buffer for data read from media. operation execution status : value true : operation succeeded value false : operation failed

The function USBD_MSCn_Read reads the data that should be returned to the USB Host that requested it.

The argument lba specifies the logical address of the first block that is to be read.

The argument cnt specifies the number of contiguous blocks to be read from the media.

The argument buf is pointing to the buffer where the read data should be stored.

Modify this function to the application's needs.

Code Example

#include rl_usb.h
 
bool USBD_MSC0_Read (uint32_t lba, uint32_t cnt, uint8_t *buf) {
 
                                        // Read data directly from media
  if (fs_ioc_read_sector (drv_id, lba, buf, cnt) != fsOK) {
    return false;
  }
 
  return true;
}

USBD_MSCn_Write()

bool USBD_MSCn_Write	(	uint32_t	lba,
		uint32_t	cnt,
		const uint8_t *	buf
	)

Callback function called to write data to media.

Parameters

[in]	lba	logical address of first block to write.
[in]	cnt	number of contiguous blocks to write to media.
[in]	buf	data buffer containing data to write to media. operation execution status : value true : operation succeeded value false : operation failed

The function USBD_MSCn_Write writes data received from the USB Host.

The argument lba specifies the logical address of the first block that is to be written.

The argument cnt specifies the number of contiguous blocks to be written to the media.

The argument buf is pointing to the buffer containing the data to be written.

Modify this function to the application's needs.

Code Example

#include rl_usb.h
 
bool USBD_MSC0_Write (uint32_t lba, uint32_t cnt, const uint8_t *buf) {
 
                                        // Write data directly to media
  if (fs_ioc_write_sector (drv_id, lba, buf, cnt) != fsOK) {
    return false;
  }
 
  return true;
}

USBD_MSCn_CheckMedia()

uint32_t USBD_MSCn_CheckMedia

(

void

)

Callback function called to check media presence and write protect status.

Returns

media presence and write protected status :

• bit 1: write protect bit
  • value 1 : media is write protected
  • value 0 : media is not write protected
• bit 0: media presence bit
  • value 1 : media is present
  • value 0 : media is not present

The function USBD_MSCn_CheckMedia is called automatically upon specific USB Host requests (like Test Unit Ready) to check if media is ready for read/write operations. It needs no invocation in the user code. If media check is not available in hardware this function can be omitted.

Modify this function to the application's needs.

Code Example

#include "rl_usb.h"
 
uint32_t USBD_MSC0_CheckMedia (void) {
 
       uint32_t param_status;
       uint8_t  media_state;            // Bit 0. media ready, Bit 1. media write protect
static uint8_t  media_ready_ex = 0U;    // Previous media ready state
       uint8_t  own;
 
  // Get current media status
  media_state = 0U;
  switch (fs_ioc_device_ctrl (drv_id, fsDevCtrlCodeCheckMedia, &param_status)) {
    case fsOK:
      if (param_status & FS_MEDIA_NOCHKMEDIA) {
        // If check media not available on hardware layer
        media_state  =  USBD_MSC_MEDIA_READY;
        break;
      }
      if (param_status & FS_MEDIA_INSERTED) {
        media_state  =  USBD_MSC_MEDIA_READY;
      }
      if (param_status & FS_MEDIA_PROTECTED) {
        media_state |=  USBD_MSC_MEDIA_PROTECTED;
      }
      break;
    default:
      break;
  }
 
  // Store current owner so no new request can interfere
  own = usbd_msc0_media_own;
 
  // De-initialize media according to previous owner
  if (own & MEDIA_OWN_CHG) {                    // If owner change requested
    if (own & MEDIA_OWN_USB) {                  // If new requested owner is USB (previous owner was File System)
      funmount (MEDIA_DRIVE);                   // De-initialize media and dismount Drive
    } else {                                    // If new requested owner is File System (previous owner was USB)
      fs_ioc_unlock (drv_id);                   // Un-lock media
    }
  }
 
  // Initialize media according to current owner
  if ((own & MEDIA_OWN_CHG)        ||           // If owner change requested or
      (media_state ^ media_ready_ex)) {         // if media ready state has changed (disconnect(SD remove)/connect(SD insert))
    if (media_state & USBD_MSC_MEDIA_READY) {   // If media is ready
      if (own & MEDIA_OWN_USB){                 // If current owner is USB
        media_ok     = false;                   // Invalidate current media status (not initialized = not ok)
        param_status = 0U;                      // Parameter for function call is 0
        if (fs_ioc_device_ctrl (drv_id, fsDevCtrlCodeControlMedia, &param_status) == fsOK) {
                                                // Initialization of media has succeeded
          if (fs_ioc_lock (drv_id) == 0) {      // If lock media for USB usage has succeeded
            media_ok = true;                    // Media was initialized and is ok
          }
        }
      } else {                                  // If current owner is File System
        if (fmount (MEDIA_DRIVE) == fsOK) {     // Initialize media and Mount Drive for File System usage
          media_ok = true;                      // Media was initialized and is ok
        }
      }
    }
    if (own & MEDIA_OWN_CHG) {
      usbd_msc0_media_own &= ~MEDIA_OWN_CHG;    // Clear request to change media owner if it was handled
    }
    media_ready_ex = media_state & USBD_MSC_MEDIA_READY;
  }
 
  // If media is not ok or owned by File System return that it is not ready for USB
  if ((!media_ok) || (!(usbd_msc0_media_own & MEDIA_OWN_USB))) {
    return 0U;
  }
 
  return media_state;
}

USBD_MSCn_GetMaxLUN()

uint8_t USBD_MSCn_GetMaxLUN

(

void

)

Callback function called to get maximum number of logical units.

Returns

number of logical units that device contains

• value > 0 and <= 4 : maximum number of logical units
• value 0 : use setting from configuration file

The callback function USBD_MSCn_GetMaxLUN returns maximum logical units (LUN) that device contains.

Code Example

uint8_t USBD_MSC0_GetMaxLUN (void) {
 
  return 2U;                            // Device contains 2 logical units
}

USBD_MSCn_LUN_GetMediaCapacity()

bool USBD_MSCn_LUN_GetMediaCapacity	(	uint8_t	lun,
		uint32_t *	block_count,
		uint32_t *	block_size
	)

Callback function called to get media capacity of a logical unit.

Parameters

[in]	lun	logical unit number.
[out]	block_count	total number of blocks on media.
[out]	block_size	media block size. operation execution status : value true : operation succeeded value false : operation failed

The callback function USBD_MSCn_LUN_GetMediaCapacity retrieves the capacity of a logical unit (LUN).

The argument lun specifies the number of the logical unit.

The argument block_count specifies the number of available blocks on the media.

The argument block_size specifies the block size of the media.

Code Example

bool USBD_MSC0_LUN_GetMediaCapacity (uint8_t lun, uint32_t *block_count, uint32_t *block_size) {
 
  (void)lun;
 
  *block_count = sizeof(memory)/2/512U; // Total number of blocks on media
  *block_size  = 512U;                  // Block size of blocks on media
 
  return true;
}

USBD_MSCn_LUN_Read()

bool USBD_MSCn_LUN_Read	(	uint8_t	lun,
		uint32_t	lba,
		uint32_t	cnt,
		uint8_t *	buf
	)

Callback function called to read data from media of a logical unit.

Parameters

[in]	lun	logical unit number.
[in]	lba	logical address of first block to read.
[in]	cnt	number of contiguous blocks to read from media.
[out]	buf	data buffer for data read from media. operation execution status : value true : operation succeeded value false : operation failed

The callback function USBD_MSCn_LUN_Read reads data from a logical unit (LUN).

The argument lun specifies the number of the logical unit.

The argument lba specifies the logical address of the first block on the media to be read.

The argument cnt specifies the number of contiguous blocks to read from media.

The argument buf specifies the buffer for storing the data that is read from the media.

Code Example

bool USBD_MSC0_LUN_Read (uint8_t lun, uint32_t lba, uint32_t cnt, uint8_t *buf) {
 
                                        // Read data from dummy image in RAM
  memcpy (buf, &memory[lun][lba * (512U/4U)], cnt * 512U);
 
  return true;
}

USBD_MSCn_LUN_Write()

bool USBD_MSCn_LUN_Write	(	uint8_t	lun,
		uint32_t	lba,
		uint32_t	cnt,
		const uint8_t *	buf
	)

Callback function called to write data to media of a logical unit.

Parameters

[in]	lun	logical unit number.
[in]	lba	logical address of first block to write.
[in]	cnt	number of contiguous blocks to write to media.
[in]	buf	data buffer containing data to write to media. operation execution status : value true : operation succeeded value false : operation failed

The callback function USBD_MSCn_LUN_Write writes data to a logical unit (LUN).

The argument lun specifies the number of the logical unit.

The argument lba specifies the logical address of the first block on the media to be written.

The argument cnt specifies the number of contiguous blocks to be written to the media.

The argument buf specifies the buffer storing the data that is to be written to the media.

Code Example

bool USBD_MSC0_LUN_Write (uint8_t lun, uint32_t lba, uint32_t cnt, const uint8_t *buf) {
 
                                        // Write data to image in RAM
  memcpy (&memory[lun][lba * (512U/4U)], buf, cnt * 512U);
 
  return true;
}

USBD_MSCn_LUN_CheckMedia()

uint32_t USBD_MSCn_LUN_CheckMedia

(

uint8_t

lun

)

Callback function called to check media presence and write protect status of a logical unit.

Parameters

[in]

lun

logical unit number.

Returns

media presence and write protected status :

• bit 1: write protect bit
  • value 1 : media is write protected
  • value 0 : media is not write protected
• bit 0: media presence bit
  • value 1 : media is present
  • value 0 : media is not present

The callback function USBD_MSCn_LUN_CheckMedia checks the media presence and write protection status of a logical unit (LUN).

The argument lun specifies the number of the logical unit.

Code Example

uint32_t USBD_MSC0_LUN_CheckMedia (uint8_t lun) {
 
  (void)lun;
 
  return USBD_MSC_MEDIA_READY;
}

USBD_MSCn_SetMediaOwnerUSB()

int32_t USBD_MSCn_SetMediaOwnerUSB

(

void

)

Set USB as media owner.

Returns

execution status

• USBD_MSCn_OK = Media ownership changed successfully
• USBD_MSCn_ERROR = Media ownership change has failed (due timeout)

The function USBD_MSCn_SetMediaOwnerUSB sets the USB Bus to the media owner of the attached media (drive). This will make the media unavailable to the File System Component. Use USBD_MSCn_SetMediaOwnerFS to enable ownership of the media for the File System Component.

Code Example

int32_t USBD_MSC0_SetMediaOwnerUSB (void) {
  uint32_t timeout_cnt;
 
  timeout_cnt = 300U;                   // 3 second timeout (300 * 10 ms)
  usbd_msc0_media_own = USBD_MSC0_MEDIA_OWN_CHG | USBD_MSC0_MEDIA_OWN_USB;
  while (usbd_msc0_media_own & USBD_MSC0_MEDIA_OWN_CHG) {
    osDelay(10);
    if ((--timeout_cnt) == 0) { return USBD_MSC0_ERROR; }
  }
 
  return USBD_MSC0_OK;
}

This function can be modified in the user code template file USBD_MSC_n.c.

USBD_MSCn_SetMediaOwnerFS()

int32_t USBD_MSCn_SetMediaOwnerFS

(

void

)

Set File System as media owner.

Returns

execution status

• USBD_MSCn_OK = Media ownership changed successfully
• USBD_MSCn_ERROR = Media ownership change has failed (due timeout)

The function USBD_MSCn_SetMediaOwnerFS sets the File System Component to the media owner of the attached media (drive). This will make the media unavailable to the USB Bus. Use USBD_MSCn_SetMediaOwnerUSB to enable ownership of the media for the USB Bus.

Code Example

int32_t USBD_MSC0_SetMediaOwnerFS (void) {
  uint32_t timeout_cnt;
 
  timeout_cnt = 300U;                   // 3 second timeout (300 * 10 ms)
  usbd_msc0_media_own = USBD_MSC0_MEDIA_OWN_CHG;
  while (usbd_msc0_media_own & USBD_MSC0_MEDIA_OWN_CHG) {
    osDelay(10);
    if ((--timeout_cnt) == 0) { return USBD_MSC0_ERROR; }
  }
 
  return USBD_MSC0_OK;
}

This function can be modified in the user code template file USBD_MSC_n.c.