Block Media SPI Flash (rm_block_media_spi)

Functions
fsp_err_t	RM_BLOCK_MEDIA_SPI_Open (rm_block_media_ctrl_t *const p_ctrl, rm_block_media_cfg_t const *const p_cfg)
fsp_err_t	RM_BLOCK_MEDIA_SPI_InfoGet (rm_block_media_ctrl_t *const p_ctrl, rm_block_media_info_t *const p_info)
fsp_err_t	RM_BLOCK_MEDIA_SPI_MediaInit (rm_block_media_ctrl_t *const p_ctrl)
fsp_err_t	RM_BLOCK_MEDIA_SPI_Read (rm_block_media_ctrl_t *const p_ctrl, uint8_t *const p_dest, uint32_t const start_block, uint32_t const num_blocks)
fsp_err_t	RM_BLOCK_MEDIA_SPI_StatusGet (rm_block_media_ctrl_t *const p_ctrl, rm_block_media_status_t *const p_status)
fsp_err_t	RM_BLOCK_MEDIA_SPI_Write (rm_block_media_ctrl_t *const p_ctrl, uint8_t const *const p_src, uint32_t const start_block, uint32_t const num_blocks)
fsp_err_t	RM_BLOCK_MEDIA_SPI_CallbackSet (rm_block_media_ctrl_t *const p_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_SPI_Close (rm_block_media_ctrl_t *const p_ctrl)
fsp_err_t	RM_BLOCK_MEDIA_SPI_Erase (rm_block_media_ctrl_t *const p_ctrl, uint32_t const start_block, uint32_t const num_blocks)

Detailed Description

Middleware to implement the block media interface on SPI flash memory. This module implements the Block Media Interface.

Overview

Features

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

• Reading, writing, and erasing data from SPI flash memory
• Provides media information such as sector size and total number of sectors.

  Note

  By default, Block Media SPI Read, Write, and Erase are blocking operations. Non-blocking operation may be achieved by yielding control within the optional callback function.

Configuration

Build Time Configurations for rm_block_media_spi

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

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	If selected, code for parameter checking is included in the build

Configurations for Storage > Block Media SPI Flash (rm_block_media_spi)

This module can be added to the Stacks tab via New Stack > Storage > Block Media SPI Flash (rm_block_media_spi).

Configuration	Options	Default	Description
Module Instance Name	Name must be a valid C symbol	g_rm_block_media0	Module name
Block size (bytes)	Manual Entry	4096	Specify the size of a block in bytes.
Block count	Minimum block count is 1, maximum is defined by hardware and software design.	8192	Number of blocks available for use by this driver instance.
Base Address	Manual Entry	0	Base address offset (bytes) for instance memory region.
Callback Function	Name must be a valid C symbol	NULL	A user callback function can be provided. If this callback is provided, it will be called after the completion of Read, Write, and Erase operations, or anytime these functions are waiting on hardware.

Clock Configuration

This module has no required clock configurations.

Pin Configuration

This module does not use I/O pins.

Limitations

Developers should be aware of the following limitations when using RM_BLOCK_MEDIA_SPI:

• Getting and setting Block Protection or Advanced Sector Protection modes is not supported.
• Addressing QSPI memory address ranges greater than 64 MB (one bank) is not supported.

Examples

Basic Example

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

#define RM_BLOCK_MEDIA_SPI_BLOCK_SIZE    (256U)

uint8_t g_dest[RM_BLOCK_MEDIA_SPI_BLOCK_SIZE] BSP_ALIGN_VARIABLE(4);
uint8_t g_src[RM_BLOCK_MEDIA_SPI_BLOCK_SIZE]  BSP_ALIGN_VARIABLE(4);
void rm_block_media_spi_basic_example (void)
{
    /* Initialize g_src to known data */
    for (uint32_t i = 0; i < RM_BLOCK_MEDIA_SPI_BLOCK_SIZE; i++)
    {
        g_src[i] = (uint8_t) ('A' + (i % 26));
    }


    /* Open the RM_BLOCK_MEDIA_SPI driver. */
    fsp_err_t err = RM_BLOCK_MEDIA_SPI_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);


    /* Initialize the SPI flash memory. */
    err = RM_BLOCK_MEDIA_SPI_MediaInit(&g_rm_block_media0_ctrl);
    assert(FSP_SUCCESS == err);


    /* Write a block of data to block 3 of the SPI flash memory. */
    err = RM_BLOCK_MEDIA_SPI_Write(&g_rm_block_media0_ctrl, g_src, 3, 1);
    assert(FSP_SUCCESS == err);


    /* Read a block of data from block 3 of the SPI flash memory. */
    err = RM_BLOCK_MEDIA_SPI_Read(&g_rm_block_media0_ctrl, g_dest, 3, 1);
    assert(FSP_SUCCESS == err);

}

Non-Blocking Example

This is a basic example of using the optional SPI callback to impliment non-blocking operation.

#define RM_BLOCK_MEDIA_EXAMPLE_DEVICE_BLOCK_COUNT    0x1000

void rm_block_media_spi_non_blocking_example (void)
{
    /* Initialize g_src to known data */
    for (uint32_t i = 0; i < RM_BLOCK_MEDIA_SPI_BLOCK_SIZE; i++)
    {
        g_src[i] = (uint8_t) ('A' + (i % 26));
    }

    /* Open the RM_BLOCK_MEDIA_SPI driver. This enables the card detection interrupt. */
    fsp_err_t err = RM_BLOCK_MEDIA_SPI_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);

    /* Initialize the Block Media SPI driver. */
    err = RM_BLOCK_MEDIA_SPI_MediaInit(&g_rm_block_media0_ctrl);
    assert(FSP_SUCCESS == err);


    /* Erase a large quantity of data from SPI Flash Memory */
    err = RM_BLOCK_MEDIA_SPI_Erase(&g_rm_block_media0_ctrl, 0, RM_BLOCK_MEDIA_EXAMPLE_DEVICE_BLOCK_COUNT);

    assert(FSP_SUCCESS == err);
}

/* The optional callback is invoked for Read, Write, and Erase operations, whenever the operation completes or has
 * been blocked by the lower level SPI driver busy indication.
 */
void rm_block_media_spi_example_callback (rm_block_media_callback_args_t * p_args)
{
    if (RM_BLOCK_MEDIA_EVENT_OPERATION_COMPLETE == p_args->event)
    {
        /* Process operation complete. */
    }
    else if (RM_BLOCK_MEDIA_EVENT_POLL_STATUS == p_args->event)
    {
        rm_block_media_status_t status;
        rm_block_media_ctrl_t * p_ctrl = (rm_block_media_ctrl_t *) p_args->p_context;

        fsp_err_t err = RM_BLOCK_MEDIA_SPI_StatusGet(p_ctrl, &status);

        assert(FSP_SUCCESS == err);

        if (true == status.busy)
        {
            /* Run waiting tasks */
            vTaskSuspend(xTaskGetCurrentTaskHandle());
        }
    }
    else
    {
        assert(RM_BLOCK_MEDIA_EVENT_ERROR == p_args->event);

        /* Process Read, Write, or Erase error. */
    }
}

Function Documentation

RM_BLOCK_MEDIA_SPI_Open()

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

Parameter checking and Acquires mutex, then handles driver initialization at the HAL SPI layer and marking the open flag in control block.

Implements rm_block_media_api_t::open.

Return values

FSP_SUCCESS	Block media for SPI framework is successfully opened.
FSP_ERR_ASSERTION	One of the input parameters or their data references may be null.
FSP_ERR_ALREADY_OPEN	The channel specified has already been opened. See HAL driver for other possible causes.

Returns

See Common Error Codes or HAL driver for other possible return codes or causes. This function calls

• spi_flash_api_t::open

RM_BLOCK_MEDIA_SPI_InfoGet()

fsp_err_t RM_BLOCK_MEDIA_SPI_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_SUCCESS	Erase operation requested.
FSP_ERR_ASSERTION	An input parameter is invalid.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_NOT_INITIALIZED	Module has not been initialized.

RM_BLOCK_MEDIA_SPI_MediaInit()

fsp_err_t RM_BLOCK_MEDIA_SPI_MediaInit

(

rm_block_media_ctrl_t *const

p_ctrl

)

Initializes the Block Media SPI Flash device.

Implements rm_block_media_api_t::mediaInit.

Return values

FSP_SUCCESS	Module is initialized and ready to access the memory device.
FSP_ERR_ASSERTION	An input parameter is invalid.
FSP_ERR_NOT_OPEN	Module is not open.

RM_BLOCK_MEDIA_SPI_Read()

fsp_err_t RM_BLOCK_MEDIA_SPI_Read	(	rm_block_media_ctrl_t *const	p_ctrl,
		uint8_t *const	p_dest,
		uint32_t const	start_block,
		uint32_t const	num_blocks
	)

Reads a number of blocks from spi flash memory. By default, this is a function is blocking. Non-blocking operation may be achieved by yielding control within the optional callback function.

Implements rm_block_media_api_t::read.

Return values

FSP_SUCCESS	SPI data read successfully
FSP_ERR_ASSERTION	p_ctrl or p_dest is NULL, or num_blocks is zero
FSP_ERR_NOT_OPEN	Block Media SPI module is not yet open
FSP_ERR_INVALID_ADDRESS	Invalid address range for read operation
FSP_ERR_NOT_INITIALIZED	Block Media SPI module is not yet initialized

RM_BLOCK_MEDIA_SPI_StatusGet()

fsp_err_t RM_BLOCK_MEDIA_SPI_StatusGet	(	rm_block_media_ctrl_t *const	p_ctrl,
		rm_block_media_status_t *const	p_status
	)

Provides driver status.

Implements rm_block_media_api_t::statusGet.

Return values

FSP_SUCCESS	Status stored in p_status.
FSP_ERR_ASSERTION	NULL pointer.
FSP_ERR_NOT_OPEN	Module is not open.

Returns

See Common Error Codes or HAL driver for other possible return codes or causes. This function calls

• spi_flash_api_t::statusGet

RM_BLOCK_MEDIA_SPI_Write()

fsp_err_t RM_BLOCK_MEDIA_SPI_Write	(	rm_block_media_ctrl_t *const	p_ctrl,
		uint8_t const *const	p_src,
		uint32_t const	start_block,
		uint32_t const	num_blocks
	)

Writes provided data to a number of blocks of spi flash memory. By default, this is a function is blocking. Non-blocking operation may be achieved by yielding control within the optional callback function.

Implements rm_block_media_api_t::write.

Return values

FSP_SUCCESS	Flash write finished successfully.
FSP_ERR_ASSERTION	p_ctrl or p_src is NULL. Or num_blocks is zero.
FSP_ERR_NOT_OPEN	Block media SPI Framework module is not yet initialized.
FSP_ERR_INVALID_ADDRESS	Invalid address range
FSP_ERR_NOT_INITIALIZED	Block Media SPI module is not yet initialized

Returns

See Common Error Codes or HAL driver for other possible return codes or causes. This function calls

• spi_flash_api_t::write

RM_BLOCK_MEDIA_SPI_CallbackSet()

fsp_err_t RM_BLOCK_MEDIA_SPI_CallbackSet	(	rm_block_media_ctrl_t *const	p_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. API not supported.

Implements rm_block_media_api_t::callbackSet.

Return values

FSP_ERR_UNSUPPORTED

API not supported by RM_BLOCK_MEDIA_SPI.

RM_BLOCK_MEDIA_SPI_Close()

fsp_err_t RM_BLOCK_MEDIA_SPI_Close

(

rm_block_media_ctrl_t *const

p_ctrl

)

Closes the Block Media SPI device. Implements rm_block_media_api_t::close.

Return values

FSP_SUCCESS	Successful close.
FSP_ERR_ASSERTION	One of the following parameters may be null: p_ctrl.
FSP_ERR_NOT_OPEN	Block media SPI Framework module is not yet initialized.

Returns

See Common Error Codes or HAL driver for other possible return codes or causes. This function calls

• spi_flash_api_t::close

RM_BLOCK_MEDIA_SPI_Erase()

fsp_err_t RM_BLOCK_MEDIA_SPI_Erase	(	rm_block_media_ctrl_t *const	p_ctrl,
		uint32_t const	start_block,
		uint32_t const	num_blocks
	)

This function erases blocks of the SPI device. By default, this is a function is blocking. Non-blocking operation may be achieved by yielding control within the optional callback function.

Implements rm_block_media_api_t::erase.

Return values

FSP_SUCCESS	Erase operation requested.
FSP_ERR_ASSERTION	An input parameter is invalid.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_NOT_INITIALIZED	Module has not been initialized.
FSP_ERR_INVALID_ADDRESS	Invalid address range

Returns

See Common Error Codes or functions called by this function for other possible return codes. This function calls:

• spi_flash_api_t::erase
• spi_flash_api_t::statusGet