RA Flexible Software Package Documentation  Release v5.2.0

 
Block Media USB (rm_block_media_usb)

Functions

fsp_err_t RM_BLOCK_MEDIA_USB_Open (rm_block_media_ctrl_t *const p_ctrl, rm_block_media_cfg_t const *const p_cfg)
 
fsp_err_t RM_BLOCK_MEDIA_USB_MediaInit (rm_block_media_ctrl_t *const p_ctrl)
 
fsp_err_t RM_BLOCK_MEDIA_USB_Read (rm_block_media_ctrl_t *const p_ctrl, uint8_t *const p_dest_address, uint32_t const block_address, uint32_t const num_blocks)
 
fsp_err_t RM_BLOCK_MEDIA_USB_Write (rm_block_media_ctrl_t *const p_ctrl, uint8_t const *const p_src_address, uint32_t const block_address, uint32_t const num_blocks)
 
fsp_err_t RM_BLOCK_MEDIA_USB_Erase (rm_block_media_ctrl_t *const p_ctrl, uint32_t const block_address, uint32_t const num_blocks)
 
fsp_err_t RM_BLOCK_MEDIA_USB_CallbackSet (rm_block_media_ctrl_t *const p_api_ctrl, void(*p_callback)(rm_block_media_callback_args_t *), void const *const p_context, rm_block_media_callback_args_t *const p_callback_memory)
 
fsp_err_t RM_BLOCK_MEDIA_USB_StatusGet (rm_block_media_ctrl_t *const p_api_ctrl, rm_block_media_status_t *const p_status)
 
fsp_err_t RM_BLOCK_MEDIA_USB_InfoGet (rm_block_media_ctrl_t *const p_ctrl, rm_block_media_info_t *const p_info)
 
fsp_err_t RM_BLOCK_MEDIA_USB_Close (rm_block_media_ctrl_t *const p_ctrl)
 

Detailed Description

Middleware to implement the block media interface on USB mass storage devices. This module implements the Block Media Interface.

Overview

Features

The USB implementation of the block media interface has the following key features:

Configuration

Build Time Configurations for rm_block_media_usb

The following build time configurations are defined in driver/rm_block_media_usb_cfg.h:

ConfigurationOptionsDefaultDescription
Parameter Checking
  • Default (BSP)
  • Enabled
  • Disabled
Default (BSP) If selected code for parameter checking is included in the build.

Configurations for Storage > Block Media USB (rm_block_media_usb)

This module can be added to the Stacks tab via New Stack > Storage > Block Media USB (rm_block_media_usb). Non-secure callable guard functions can be generated for this module by right clicking the module in the RA Configuration tool and checking the "Non-secure Callable" box.

ConfigurationOptionsDefaultDescription
NameName must be a valid C symbolg_rm_block_media0 Module name.
CallbackName must be a valid C symbolNULL A user callback function can be provided. If this callback function is provided, it will be called when a device is attached or removed.
Pointer to user contextName must be a valid C symbolNULL A user context can be provided. If this context is provided, it will be passed to callback function when a device is attached or removed.

Note
RM_BLOCK_MEDIA_USB_MediaInit function must be called after receiving the insert event notification.

Clock Configuration

This module has no required clock configurations.

Pin Configuration

This module does not use I/O pins.

Examples

Basic Example

This is a basic example of minimal use of the USB mass storage block media implementation in an application.

#define RM_BLOCK_MEDIA_USB_BLOCK_SIZE (512)
volatile bool g_usb_inserted = false;
uint8_t g_dest[RM_BLOCK_MEDIA_USB_BLOCK_SIZE] BSP_ALIGN_VARIABLE(4);
uint8_t g_src[RM_BLOCK_MEDIA_USB_BLOCK_SIZE] BSP_ALIGN_VARIABLE(4);
void rm_block_media_usb_basic_example (void)
{
/* Initialize g_src to known data */
for (uint32_t i = 0; i < RM_BLOCK_MEDIA_USB_BLOCK_SIZE; i++)
{
g_src[i] = (uint8_t) ('A' + (i % 26));
}
/* Open the RM_BLOCK_MEDIA_USB driver. */
fsp_err_t err = RM_BLOCK_MEDIA_USB_Open(&g_rm_block_media0_ctrl, &g_rm_block_media0_cfg);
/* Handle any errors. This function should be defined by the user. */
assert(FSP_SUCCESS == err);
while (!g_usb_inserted)
{
/* Wait for a card insertion interrupt. */
}
/* Initialize the mass storage device. This should not be done until the device is plugged in and initialized. */
err = RM_BLOCK_MEDIA_USB_MediaInit(&g_rm_block_media0_ctrl);
assert(FSP_SUCCESS == err);
/* Write a block of data to sector 3 of an USB mass storage device. */
err = RM_BLOCK_MEDIA_USB_Write(&g_rm_block_media0_ctrl, g_src, 3, 1);
assert(FSP_SUCCESS == err);
/* Read a block of data from sector 3 of an USB mass storage device. */
err = RM_BLOCK_MEDIA_USB_Read(&g_rm_block_media0_ctrl, g_dest, 3, 1);
assert(FSP_SUCCESS == err);
}

Device Insertion

This is an example of using a callback to determine when a mass storage device is plugged in and enumerated.

/* The callback is called when a media insertion event occurs. */
void rm_block_media_usb_media_insertion_example_callback (rm_block_media_callback_args_t * p_args)
{
{
g_usb_inserted = true;
}
{
g_usb_inserted = false;
}
}

Function Documentation

◆ RM_BLOCK_MEDIA_USB_Open()

fsp_err_t RM_BLOCK_MEDIA_USB_Open ( rm_block_media_ctrl_t *const  p_ctrl,
rm_block_media_cfg_t const *const  p_cfg 
)

Opens the module.

Implements rm_block_media_api_t::open().

Return values
FSP_SUCCESSModule is available and is now open.
FSP_ERR_ASSERTIONAn input parameter is invalid.
FSP_ERR_ALREADY_OPENModule has already been opened with this instance of the control structure.
Returns
See Common Error Codes or functions called by this function for other possible return codes.

◆ RM_BLOCK_MEDIA_USB_MediaInit()

fsp_err_t RM_BLOCK_MEDIA_USB_MediaInit ( rm_block_media_ctrl_t *const  p_ctrl)

Initializes the USB device.

Implements rm_block_media_api_t::mediaInit().

Return values
FSP_SUCCESSModule is initialized and ready to access the memory device.
FSP_ERR_ASSERTIONAn input parameter is invalid.
FSP_ERR_NOT_OPENModule is not open.

◆ RM_BLOCK_MEDIA_USB_Read()

fsp_err_t RM_BLOCK_MEDIA_USB_Read ( rm_block_media_ctrl_t *const  p_ctrl,
uint8_t *const  p_dest_address,
uint32_t const  block_address,
uint32_t const  num_blocks 
)

Reads data from an USB device. Implements rm_block_media_api_t::read().

This function blocks until the data is read into the destination buffer.

Return values
FSP_SUCCESSData read successfully.
FSP_ERR_ASSERTIONAn input parameter is invalid.
FSP_ERR_NOT_OPENModule is not open.
FSP_ERR_NOT_INITIALIZEDModule has not been initialized.
FSP_ERR_USB_FAILEDThe message could not received completed successfully.
Returns
See Common Error Codes or functions called by this function for other possible return codes.

◆ RM_BLOCK_MEDIA_USB_Write()

fsp_err_t RM_BLOCK_MEDIA_USB_Write ( rm_block_media_ctrl_t *const  p_ctrl,
uint8_t const *const  p_src_address,
uint32_t const  block_address,
uint32_t const  num_blocks 
)

Writes data to an USB device. Implements rm_block_media_api_t::write().

This function blocks until the write operation completes.

Return values
FSP_SUCCESSWrite finished successfully.
FSP_ERR_ASSERTIONAn input parameter is invalid.
FSP_ERR_NOT_OPENModule is not open.
FSP_ERR_NOT_INITIALIZEDModule has not been initialized.
FSP_ERR_USB_FAILEDThe message could not received completed successfully.
Returns
See Common Error Codes or functions called by this function for other possible return codes.

◆ RM_BLOCK_MEDIA_USB_Erase()

fsp_err_t RM_BLOCK_MEDIA_USB_Erase ( rm_block_media_ctrl_t *const  p_ctrl,
uint32_t const  block_address,
uint32_t const  num_blocks 
)

Erases sectors of an USB device. Implements rm_block_media_api_t::erase().

This function blocks until erase is complete.

Return values
FSP_SUCCESSErase operation requested.
FSP_ERR_ASSERTIONAn input parameter is invalid.
FSP_ERR_NOT_OPENModule is not open.
FSP_ERR_NOT_INITIALIZEDModule has not been initialized.
Returns
See Common Error Codes or functions called by this function for other possible return codes.

◆ RM_BLOCK_MEDIA_USB_CallbackSet()

fsp_err_t RM_BLOCK_MEDIA_USB_CallbackSet ( rm_block_media_ctrl_t *const  p_api_ctrl,
void(*)(rm_block_media_callback_args_t *)  p_callback,
void const *const  p_context,
rm_block_media_callback_args_t *const  p_callback_memory 
)

Updates the user callback with the option to provide memory for the callback argument structure. Implements rm_block_media_api_t::callbackSet.

Note
This function is currently unsupported for Block Media over USB.
Return values
FSP_ERR_UNSUPPORTEDCallbackSet is not currently supported for Block Media over USB.

◆ RM_BLOCK_MEDIA_USB_StatusGet()

fsp_err_t RM_BLOCK_MEDIA_USB_StatusGet ( rm_block_media_ctrl_t *const  p_api_ctrl,
rm_block_media_status_t *const  p_status 
)

Provides driver status. Implements rm_block_media_api_t::statusGet().

Return values
FSP_SUCCESSStatus stored in p_status.
FSP_ERR_ASSERTIONNULL pointer.
FSP_ERR_NOT_OPENModule is not open.
FSP_ERR_NOT_INITIALIZEDModule has not been initialized.
Returns
See Common Error Codes or functions called by this function for other possible return codes.

◆ RM_BLOCK_MEDIA_USB_InfoGet()

fsp_err_t RM_BLOCK_MEDIA_USB_InfoGet ( rm_block_media_ctrl_t *const  p_ctrl,
rm_block_media_info_t *const  p_info 
)

Retrieves module information. Implements rm_block_media_api_t::infoGet().

Return values
FSP_SUCCESSErase operation requested.
FSP_ERR_ASSERTIONAn input parameter is invalid.
FSP_ERR_NOT_OPENModule is not open.
FSP_ERR_NOT_INITIALIZEDModule has not been initialized.

◆ RM_BLOCK_MEDIA_USB_Close()

fsp_err_t RM_BLOCK_MEDIA_USB_Close ( rm_block_media_ctrl_t *const  p_ctrl)

Closes an open USB device. Implements rm_block_media_api_t::close().

Return values
FSP_SUCCESSSuccessful close.
FSP_ERR_ASSERTIONAn input parameter is invalid.
FSP_ERR_NOT_OPENModule is not open.