MSC - Memory System Controller

Description

Memory System Controller API.

Contains functions to control the MSC, primarily the Flash. Users can perform Flash memory write and erase operations, as well as optimization of the CPU instruction fetch interface for the application. Available instruction fetch features depends on the MCU or SoC family, but features such as instruction pre-fetch, cache, and configurable branch prediction are typically available.

Note
Flash wait-state configuration is handled by CMU - Clock Management Unit . When core clock configuration is changed by a call to functions such as CMU_ClockSelectSet() or CMU_HFRCOBandSet() , then Flash wait-state configuration is also updated.

MSC resets into a safe state. To initialize the instruction interface to recommended settings:

Note
The optimal configuration is highly application dependent. Performance benchmarking is supported by most families. See MSC_StartCacheMeasurement() and MSC_GetCacheMeasurement() for more details.
The flash write and erase runs from RAM on the EFM32G devices. On all other devices the flash write and erase functions run from flash.
Flash erase may add ms of delay to interrupt latency if executing from Flash.

Flash write and erase operations are supported by MSC_WriteWord() , MSC_ErasePage() , and MSC_MassErase() . Mass erase is supported for MCU and SoC families with larger Flash sizes.

Note
MSC_Init() must be called prior to any Flash write or erase operation.

The following steps are necessary to perform a page erase and write:

uint32_t * userDataPage = (uint32_t *) USERDATA_BASE;
uint32_t userData[] = {
0x01020304,
0x05060708
};
MSC_ErasePage (userDataPage);
MSC_WriteWord (userDataPage, userData, sizeof (userData));

Data Structures

struct MSC_ExecConfig_TypeDef
Code execution configuration.

Functions

void MSC_IntClear (uint32_t flags)
Clear one or more pending MSC interrupts.
void MSC_IntDisable (uint32_t flags)
Disable one or more MSC interrupts.
void MSC_IntEnable (uint32_t flags)
Enable one or more MSC interrupts.
uint32_t MSC_IntGet (void)
Get pending MSC interrupt flags.
uint32_t MSC_IntGetEnabled (void)
Get enabled and pending MSC interrupt flags.
void MSC_IntSet (uint32_t flags)
Set one or more pending MSC interrupts from SW.
void MSC_StartCacheMeasurement (void)
Starts measuring cache hit ratio.
int32_t MSC_GetCacheMeasurement (void)
Stops measuring hit rate.
void MSC_FlushCache (void)
Flush contents of instruction cache.
void MSC_EnableCache (bool enable)
Enable or disable instruction cache functionality.
void MSC_EnableCacheIRQs (bool enable)
Enable or disable instruction cache functionality in IRQs.
void MSC_EnableAutoCacheFlush (bool enable)
Enable or disable instruction cache flushing when writing to flash.
void MSC_BusStrategy (mscBusStrategy_Typedef mode)
Configure which unit should get priority on system bus.
void MSC_Init (void)
Enables the flash controller for writing.
void MSC_Deinit (void)
Disables the flash controller for writing.
void MSC_ExecConfigSet ( MSC_ExecConfig_TypeDef *execConfig)
Set the MSC code execution configuration.
MSC_RAMFUNC_DECLARATOR MSC_Status_TypeDef MSC_WriteWord (uint32_t *address, void const *data, uint32_t numBytes)
Writes data to flash memory.
MSC_RAMFUNC_DECLARATOR MSC_Status_TypeDef MSC_WriteWordFast (uint32_t *address, void const *data, uint32_t numBytes)
Writes data to flash memory.
MSC_RAMFUNC_DECLARATOR MSC_Status_TypeDef MSC_ErasePage (uint32_t *startAddress)
Erases a page in flash memory.
SL_RAMFUNC_DECLARATOR MSC_Status_TypeDef MSC_MassErase (void)
Erase the entire Flash in one operation.

Macros

#define MSC_PROGRAM_TIMEOUT 10000000ul
Timeout used while waiting for Flash to become ready after a write.
#define MSC_EXECCONFIG_DEFAULT
Default MSC ExecConfig initialization.

Enumerations

enum MSC_Status_TypeDef {
mscReturnOk = 0,
mscReturnInvalidAddr = -1,
mscReturnLocked = -2,
mscReturnTimeOut = -3,
mscReturnUnaligned = -4
}
Return codes for writing/erasing Flash.
enum MSC_BusStrategy_Typedef {
mscBusStrategyCPU = MSC_READCTRL_BUSSTRATEGY_CPU,
mscBusStrategyDMA = MSC_READCTRL_BUSSTRATEGY_DMA,
mscBusStrategyDMAEM1 = MSC_READCTRL_BUSSTRATEGY_DMAEM1,
mscBusStrategyNone = MSC_READCTRL_BUSSTRATEGY_NONE
}
Strategy for prioritized bus access.

Function Documentation

MSC_IntClear()

void MSC_IntClear ( uint32_t flags )
inline

Clear one or more pending MSC interrupts.

Parameters
[in] flags Pending MSC intterupt source to clear. Use a bitwise logic OR combination of valid interrupt flags for the MSC module (MSC_IF_nnn).

MSC_IntDisable()

void MSC_IntDisable ( uint32_t flags )
inline

Disable one or more MSC interrupts.

Parameters
[in] flags MSC interrupt sources to disable. Use a bitwise logic OR combination of valid interrupt flags for the MSC module (MSC_IF_nnn).

MSC_IntEnable()

void MSC_IntEnable ( uint32_t flags )
inline

Enable one or more MSC interrupts.

Note
Depending on the use, a pending interrupt may already be set prior to enabling the interrupt. To ignore a pending interrupt, consider using MSC_IntClear() prior to enabling the interrupt.
Parameters
[in] flags MSC interrupt sources to enable. Use a bitwise logic OR combination of valid interrupt flags for the MSC module (MSC_IF_nnn).

MSC_IntGet()

uint32_t MSC_IntGet ( void )
inline

Get pending MSC interrupt flags.

Note
The event bits are not cleared by the use of this function.
Returns
MSC interrupt sources pending. A bitwise logic OR combination of valid interrupt flags for the MSC module (MSC_IF_nnn).

MSC_IntGetEnabled()

uint32_t MSC_IntGetEnabled ( void )
inline

Get enabled and pending MSC interrupt flags.

Useful for handling more interrupt sources in the same interrupt handler.

Note
Interrupt flags are not cleared by the use of this function.
Returns
Pending and enabled MSC interrupt sources. The return value is the bitwise AND of
  • the enabled interrupt sources in MSC_IEN and
  • the pending interrupt flags MSC_IF

MSC_IntSet()

void MSC_IntSet ( uint32_t flags )
inline

Set one or more pending MSC interrupts from SW.

Parameters
[in] flags MSC interrupt sources to set to pending. Use a bitwise logic OR combination of valid interrupt flags for the MSC module (MSC_IF_nnn).

MSC_StartCacheMeasurement()

void MSC_StartCacheMeasurement ( void )
inline

Starts measuring cache hit ratio.

Starts performance counters. It is defined inline to minimize the impact of this code on the measurement itself.

MSC_GetCacheMeasurement()

int32_t MSC_GetCacheMeasurement ( void )
inline

Stops measuring hit rate.

Note
Defined inline to minimize the impact of this code on the measurement itself. Only works for relatively short sections of code. To measure longer sections of code, implement an IRQ Handler for the CHOF and CMOF overflow interrupts. These overflows need to be counted and included in the total. Functions can then be implemented as follows:
* volatile uint32_t hitOverflows
* volatile uint32_t missOverflows
*
* void MSC_IRQHandler(void)
* {
*   uint32_t flags;
*   flags = MSC->IF;
*   if (flags & MSC_IF_CHOF) {
*      MSC->IFC = MSC_IF_CHOF;
*      hitOverflows++;
*   }
*   if (flags & MSC_IF_CMOF) {
*     MSC->IFC = MSC_IF_CMOF;
*     missOverflows++;
*   }
* }
*
* void startPerformanceCounters(void)
* {
*   hitOverflows = 0;
*   missOverflows = 0;
*
*   MSC_IntEnable(MSC_IF_CHOF | MSC_IF_CMOF);
*   NVIC_EnableIRQ(MSC_IRQn);
*
*   MSC_StartCacheMeasurement();
* }
* 
Returns
Returns -1 if there has been no cache accesses. Returns -2 if there has been an overflow in the performance counters. If not, it will return the percentage of hits versus misses.

MSC_FlushCache()

void MSC_FlushCache ( void )
inline

Flush contents of instruction cache.

MSC_EnableCache()

void MSC_EnableCache ( bool enable )
inline

Enable or disable instruction cache functionality.

Parameters
[in] enable Enable instruction cache. Default is on.

MSC_EnableCacheIRQs()

void MSC_EnableCacheIRQs ( bool enable )
inline

Enable or disable instruction cache functionality in IRQs.

Parameters
[in] enable Enable instruction cache. Default is on.

MSC_EnableAutoCacheFlush()

void MSC_EnableAutoCacheFlush ( bool enable )
inline

Enable or disable instruction cache flushing when writing to flash.

Parameters
[in] enable Enable automatic cache flushing. Default is on.

MSC_BusStrategy()

void MSC_BusStrategy ( mscBusStrategy_Typedef mode )
inline

Configure which unit should get priority on system bus.

Parameters
[in] mode Unit to prioritize bus accesses for.

MSC_Init()

void MSC_Init ( void )

Enables the flash controller for writing.

Note
This function must be called before flash operations when AUXHFRCO clock has been changed from a default band.

MSC_Deinit()

void MSC_Deinit ( void )

Disables the flash controller for writing.

MSC_ExecConfigSet()

void MSC_ExecConfigSet ( MSC_ExecConfig_TypeDef * execConfig )

Set the MSC code execution configuration.

Parameters
[in] execConfig The code execution configuration.

MSC_WriteWord()

MSC_RAMFUNC_DEFINITION_END MSC_RAMFUNC_DEFINITION_BEGIN MSC_Status_TypeDef MSC_WriteWord ( uint32_t * address,
void const * data,
uint32_t numBytes
)

Writes data to flash memory.

This function is interrupt-safe, but slower than MSC_WriteWordFast() , which writes to flash with interrupts disabled. Write data must be aligned to words and contain a number of bytes that is divisible by four.

Note
It is recommended to erase the flash page before performing a write.

For the Gecko family, it is required to run this function from RAM.

For IAR Embedded Workbench, Simplicity Studio and GCC, this is done automatically by using attributes in the function proctype. For Keil uVision IDE, define a section called "ram_code" and place it manually in the project's scatter file.

This function requires a system core clock at 1 MHz or higher.

Parameters
[in] address