MSCEMLIB

Detailed Description

Memory System Controller API.

This module contain functions to control the MSC, primarily the Flash. The user 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 the CMU module. When the core clock configuration is changed by a calls to functions such as CMU_ClockSelectSet() or CMU_HFRCOBandSet(), then Flash wait-state configuration is also updated.

The 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.

Support for Flash write and erase runs from RAM by default. This code may be allocated to Flash by defining EM_MSC_RUN_FROM_FLASH.

Note
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_WriteWordFast(), MSC_ErasePage() and MSC_MassErase(). Fast write is not supported for EFM32G and 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
 

Macros

#define EM_MSC_RUN_FROM_FLASH
 By compiling with the define EM_MSC_RUN_FROM_FLASH, the functions performing erase or write operations will remain in and execute from Flash. This is useful for targets that don't want to allocate RAM space to hold the flash functions. Without this define, code for Flash operations will be copied into RAM at startup.
 
#define MSC_EXECCONFIG_DEFAULT
 
#define MSC_PROGRAM_TIMEOUT   10000000ul
 The timeout used while waiting for the flash to become ready after a write. This number indicates the number of iterations to perform before issuing a timeout.
 
#define MSC_RAMFUNC_DECLARATOR
 Expands to SL_RAMFUNC_DECLARATOR if EM_MSC_RUN_FROM_FLASH is undefined and to nothing if EM_MSC_RUN_FROM_FLASH is defined.
 
#define MSC_RAMFUNC_DEFINITION_BEGIN
 Expands to SL_RAMFUNC_DEFINITION_BEGIN if EM_MSC_RUN_FROM_FLASH is undefined and to nothing if EM_MSC_RUN_FROM_FLASH is defined.
 
#define MSC_RAMFUNC_DEFINITION_END
 Expands to SL_RAMFUNC_DEFINITION_END if EM_MSC_RUN_FROM_FLASH is undefined and to nothing if EM_MSC_RUN_FROM_FLASH is defined.
 

Enumerations

enum  MSC_BusStrategy_Typedef {
  mscBusStrategyCPU = MSC_READCTRL_BUSSTRATEGY_CPU,
  mscBusStrategyDMA = MSC_READCTRL_BUSSTRATEGY_DMA,
  mscBusStrategyDMAEM1 = MSC_READCTRL_BUSSTRATEGY_DMAEM1,
  mscBusStrategyNone = MSC_READCTRL_BUSSTRATEGY_NONE
}
 
enum  MSC_Status_TypeDef {
  mscReturnOk = 0,
  mscReturnInvalidAddr = -1,
  mscReturnLocked = -2,
  mscReturnTimeOut = -3,
  mscReturnUnaligned = -4
}
 

Functions

__STATIC_INLINE void MSC_BusStrategy (mscBusStrategy_Typedef mode)
 Configure which unit should get priority on system bus.
 
void MSC_Deinit (void)
 Disables the flash controller for writing.
 
__STATIC_INLINE void MSC_EnableAutoCacheFlush (bool enable)
 Enable or disable instruction cache flushing when writing to flash.
 
__STATIC_INLINE void MSC_EnableCache (bool enable)
 Enable or disable instruction cache functionality.
 
__STATIC_INLINE void MSC_EnableCacheIRQs (bool enable)
 Enable or disable instruction cache functionality in IRQs.
 
MSC_RAMFUNC_DECLARATOR MSC_Status_TypeDef MSC_ErasePage (uint32_t *startAddress)
 Erases a page in flash memory.
 
void MSC_ExecConfigSet (MSC_ExecConfig_TypeDef *execConfig)
 Set MSC code execution configuration.
 
__STATIC_INLINE void MSC_FlushCache (void)
 Flush the contents of the instruction cache.
 
__STATIC_INLINE int32_t MSC_GetCacheMeasurement (void)
 Stops measuring the hit rate.
 
void MSC_Init (void)
 Enables the flash controller for writing.
 
__STATIC_INLINE void MSC_IntClear (uint32_t flags)
 Clear one or more pending MSC interrupts.
 
__STATIC_INLINE void MSC_IntDisable (uint32_t flags)
 Disable one or more MSC interrupts.
 
__STATIC_INLINE void MSC_IntEnable (uint32_t flags)
 Enable one or more MSC interrupts.
 
__STATIC_INLINE uint32_t MSC_IntGet (void)
 Get pending MSC interrupt flags.
 
__STATIC_INLINE uint32_t MSC_IntGetEnabled (void)
 Get enabled and pending MSC interrupt flags. Useful for handling more interrupt sources in the same interrupt handler.
 
__STATIC_INLINE void MSC_IntSet (uint32_t flags)
 Set one or more pending MSC interrupts from SW.
 
MSC_RAMFUNC_DECLARATOR MSC_Status_TypeDef MSC_MassErase (void)
 Erase entire flash in one operation.
 
__STATIC_INLINE void MSC_StartCacheMeasurement (void)
 Starts measuring cache hit ratio.
 
MSC_RAMFUNC_DECLARATOR 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 divisable by four.
 
MSC_RAMFUNC_DECLARATOR MSC_Status_TypeDef MSC_WriteWordFast (uint32_t *address, void const *data, uint32_t numBytes)
 Writes data to flash memory. This function is faster than MSC_WriteWord(), but it disables interrupts. Write data must be aligned to words and contain a number of bytes that is divisable by four.
 

Macro Definition Documentation

#define EM_MSC_RUN_FROM_FLASH

By compiling with the define EM_MSC_RUN_FROM_FLASH, the functions performing erase or write operations will remain in and execute from Flash. This is useful for targets that don't want to allocate RAM space to hold the flash functions. Without this define, code for Flash operations will be copied into RAM at startup.

Note
This define is not present by default. The MSC controller API will run from RAM by default.

Definition at line 125 of file em_msc.h.

#define MSC_EXECCONFIG_DEFAULT
Value:
{ \
false, \
true, \
false, \
false, \
false, \
false, \
}

Default MSC ExecConfig initialization

Definition at line 162 of file em_msc.h.

#define MSC_PROGRAM_TIMEOUT   10000000ul

The timeout used while waiting for the flash to become ready after a write. This number indicates the number of iterations to perform before issuing a timeout.

Note
This timeout is set very large (in the order of 100x longer than necessary). This is to avoid any corner cases.

Definition at line 110 of file em_msc.h.

Referenced by MSC_ErasePage().

Enumeration Type Documentation

Strategy for prioritized bus access

Enumerator
mscBusStrategyCPU 

Prioritize CPU bus accesses

mscBusStrategyDMA 

Prioritize DMA bus accesses

mscBusStrategyDMAEM1 

Prioritize DMAEM1 for bus accesses

mscBusStrategyNone 

No unit has bus priority

Definition at line 143 of file em_msc.h.

Return codes for writing/erasing the flash

Enumerator
mscReturnOk 

Flash write/erase successful.

mscReturnInvalidAddr 

Invalid address. Write to an address that is not flash.

mscReturnLocked 

Flash address is locked.

mscReturnTimeOut 

Timeout while writing to flash.

mscReturnUnaligned 

Unaligned access to flash.

Definition at line 133 of file em_msc.h.

Function Documentation

__STATIC_INLINE void MSC_BusStrategy ( mscBusStrategy_Typedef  mode)

Configure which unit should get priority on system bus.

Parameters
[in]modeUnit to prioritize bus accesses for.

Definition at line 449 of file em_msc.h.

References _MSC_READCTRL_BUSSTRATEGY_MASK, and MSC.

__STATIC_INLINE void MSC_EnableAutoCacheFlush ( bool  enable)

Enable or disable instruction cache flushing when writing to flash.

Parameters
[in]enableEnable automatic cache flushing. Default is on.

Definition at line 436 of file em_msc.h.

References _MSC_READCTRL_AIDIS_SHIFT, BUS_RegBitWrite(), and MSC.

__STATIC_INLINE void MSC_EnableCache ( bool  enable)

Enable or disable instruction cache functionality.

Parameters
[in]enableEnable instruction cache. Default is on.

Definition at line 412 of file em_msc.h.

References _MSC_READCTRL_IFCDIS_SHIFT, BUS_RegBitWrite(), and MSC.

__STATIC_INLINE void MSC_EnableCacheIRQs ( bool  enable)

Enable or disable instruction cache functionality in IRQs.

Parameters
[in]enableEnable instruction cache. Default is on.

Definition at line 424 of file em_msc.h.

References _MSC_READCTRL_ICCDIS_SHIFT, BUS_RegBitWrite(), and MSC.

MSC_RAMFUNC_DEFINITION_BEGIN MSC_Status_TypeDef MSC_ErasePage ( uint32_t *  startAddress)

Erases a page in flash memory.

Note
It is recommended to run this code from RAM. On the Gecko family, it is required to run this function from RAM.

For IAR, Rowley, SimplicityStudio, Atollic and armgcc this will be achieved automatically by using attributes in the function proctype. For Keil uVision you must define a section called "ram_code" and place this manually in your project's scatter file.

Parameters
[in]startAddressPointer to the flash page to erase. Must be aligned to beginning of page boundary.
Returns
Returns the status of erase operation, MSC_Status_TypeDef
*   mscReturnOk - Operation completed successfully.
*   mscReturnInvalidAddr - Operation tried to erase a non-flash area.
*   mscReturnLocked - Operation tried to erase a locked area of the flash.
*   mscReturnTimeOut - Operation timed out waiting for flash operation
*       to complete.
* 

Definition at line 975 of file em_msc.c.

References EMU, FLASH_PAGE_SIZE, MSC, MSC_PROGRAM_TIMEOUT, MSC_STATUS_BUSY, MSC_STATUS_INVADDR, MSC_STATUS_LOCKED, MSC_WRITECMD_ERASEPAGE, MSC_WRITECMD_LADDRIM, MSC_WRITECTRL_WREN, mscReturnInvalidAddr, mscReturnLocked, mscReturnOk, and mscReturnTimeOut.

Referenced by nvm3_halPageErase(), and NVMHAL_PageErase().

__STATIC_INLINE int32_t MSC_GetCacheMeasurement ( void  )

Stops measuring the hit rate.

Note
This function is defined inline to minimize the impact of this code on the measurement itself. This code only works for relatively short sections of code. If you wish to measure longer sections of code you need to implement a IRQ Handler for The CHOF and CMOF overflow interrupts. Theses overflows needs to be counted and included in the total. The 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.

Definition at line 366 of file em_msc.h.

References MSC, MSC_CMD_STOPPC, MSC_IF_CHOF, and MSC_IF_CMOF.

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 default band.

Definition at line 225 of file em_msc.c.

References _MSC_TIMEBASE_BASE_MASK, _MSC_TIMEBASE_BASE_SHIFT, _MSC_TIMEBASE_PERIOD_MASK, CMU_ClockFreqGet(), cmuClock_AUX, EMU, MSC, MSC_TIMEBASE_PERIOD_1US, MSC_TIMEBASE_PERIOD_5US, MSC_UNLOCK_CODE, and MSC_WRITECTRL_WREN.

Referenced by nvm3_halOpen(), and NVMHAL_Init().

__STATIC_INLINE void MSC_IntClear ( uint32_t  flags)

Clear one or more pending MSC interrupts.

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

Definition at line 213 of file em_msc.h.

References MSC.

__STATIC_INLINE void MSC_IntDisable ( uint32_t  flags)

Disable one or more MSC interrupts.

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

Definition at line 226 of file em_msc.h.

References MSC.

__STATIC_INLINE void MSC_IntEnable ( uint32_t  flags)

Enable one or more MSC interrupts.

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

Definition at line 244 of file em_msc.h.

References MSC.

__STATIC_INLINE uint32_t MSC_IntGet ( void  )

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).

Definition at line 260 of file em_msc.h.

References MSC.

__STATIC_INLINE uint32_t MSC_IntGetEnabled ( void  )

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

Definition at line 279 of file em_msc.h.

References MSC.

__STATIC_INLINE void MSC_IntSet ( uint32_t  flags)

Set one or more pending MSC interrupts from SW.

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

Definition at line 295 of file em_msc.h.

References MSC.

Erase entire flash in one operation.

Note
This command will erase the entire contents of the device. Use with care, both a debug session and all contents of the flash will be lost. The lock bit, MLW will prevent this operation from executing and might prevent successful mass erase.

Definition at line 1127 of file em_msc.c.

References MSC, MSC_MASSLOCK_LOCKKEY_LOCK, MSC_MASSLOCK_LOCKKEY_UNLOCK, MSC_STATUS_BUSY, MSC_WRITECMD_ERASEMAIN0, MSC_WRITECMD_ERASEMAIN1, MSC_WRITECTRL_WREN, and mscReturnOk.

__STATIC_INLINE void MSC_StartCacheMeasurement ( void  )

Starts measuring cache hit ratio.

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

Definition at line 308 of file em_msc.h.

References MSC, MSC_CMD_STARTPC, MSC_IF_CHOF, and MSC_IF_CMOF.

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 divisable by four.

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

It is recommended to run this code from RAM. On the Gecko family, it is required to run this function from RAM.

For IAR, Rowley, SimplicityStudio, Atollic and armgcc this will be achieved automatically by using attributes in the function proctype. For Keil uVision you must define a section called "ram_code" and place this manually in your project's scatter file.

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

Parameters
[in]addressPointer to the flash word to write to. Must be aligned to words.
[in]dataData to write to flash.
[in]numBytesNumber of bytes to write from flash. NB: Must be divisable by four.
Returns
Returns the status of the write operation
*   flashReturnOk - Operation completed successfully.
*   flashReturnInvalidAddr - Operation tried to erase a non-flash area.
*   flashReturnLocked - Operation tried to erase a locked area of the flash.
*   flashReturnTimeOut - Operation timed out waiting for flash operation
*       to complete. Or the MSC timed out waiting for the software to write
*       the next word into the DWORD register.
* 

Definition at line 1061 of file em_msc.c.

Referenced by nvm3_halWriteWords(), and NVMHAL_Write().

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

Writes data to flash memory. This function is faster than MSC_WriteWord(), but it disables interrupts. Write data must be aligned to words and contain a number of bytes that is divisable by four.

Note
It is recommended to erase the flash page before performing a write. It is required to run this function from RAM on parts that include a flash write buffer.

For IAR, Rowley, SimplicityStudio, Atollic and armgcc this will be achieved automatically by using attributes in the function proctype. For Keil uVision you must define a section called "ram_code" and place this manually in your project's scatter file.

Parameters
[in]addressPointer to the flash word to write to. Must be aligned to words.
[in]dataData to write to flash.
[in]numBytesNumber of bytes to write from flash. NB: Must be divisable by four.
Returns
Returns the status of the write operation
*   flashReturnOk - Operation completed successfully.
*   flashReturnInvalidAddr - Operation tried to erase a non-flash area.
*   flashReturnLocked - Operation tried to erase a locked area of the flash.
*   flashReturnTimeOut - Operation timed out waiting for flash operation
*       to complete. Or the MSC timed out waiting for the software to write
*       the next word into the DWORD register.
* 

Definition at line 1104 of file em_msc.c.