Detailed 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 module. 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:

MSC_ExecConfig_TypeDef execConfig = MSC_EXECCONFIG_DEFAULT ;

MSC_ExecConfigSet (&execConfig);

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

Deprecated:: The configuration called EM_MSC_RUN_FROM_FLASH is deprecated. This was previously used for allocating the flash write functions in either flash or RAM. Flash write functions are now placed in flash on all devices except the EFM32G automatically.

Deprecated:: The function called MSC_WriteWordFast() is deprecated.

Data Structures
struct	MSC_ExecConfig_TypeDef

Macros
#define	MSC_EXECCONFIG_DEFAULT

#define	MSC_PROGRAM_TIMEOUT 10000000ul
	Timeout used while waiting for Flash to become ready after a write. This number indicates the number of iterations to perform before issuing a timeout.

Enumerations
enum	MSC_Status_TypeDef { mscReturnOk = 0, mscReturnInvalidAddr = -1, mscReturnLocked = -2, mscReturnTimeOut = -3, mscReturnUnaligned = -4 }

Functions
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 the MSC code execution configuration.

__STATIC_INLINE void	MSC_FlushCache (void)
	Flush contents of instruction cache.

__STATIC_INLINE int32_t	MSC_GetCacheMeasurement (void)
	Stops measuring 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.

SL_RAMFUNC_DECLARATOR MSC_Status_TypeDef	MSC_MassErase (void)
	Erase the 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 divisible 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 divisible by four.

Macro Definition Documentation

#define MSC_EXECCONFIG_DEFAULT

Value:

         { \
        
         false, \
        
         true, \
        
         false, \
        
         false, \
        
         false, \
        
         false, \
        
         }

Default MSC ExecConfig initialization.

Definition at line 179 of file em_msc.h .

#define MSC_PROGRAM_TIMEOUT 10000000ul

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

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

Definition at line 118 of file em_msc.h .

Referenced by MSC_ErasePage() .

Enumeration Type Documentation

enum MSC_Status_TypeDef

Return codes for writing/erasing 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 137 of file em_msc.h .

Function Documentation

__STATIC_INLINE void MSC_EnableAutoCacheFlush ( bool enable )

Enable or disable instruction cache flushing when writing to flash.

Parameters

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

Definition at line 501 of file em_msc.h .

References BUS_RegBitWrite() .

__STATIC_INLINE void MSC_EnableCache ( bool enable )

Enable or disable instruction cache functionality.

Parameters

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

Definition at line 477 of file em_msc.h .

References BUS_RegBitWrite() .

__STATIC_INLINE void MSC_EnableCacheIRQs ( bool enable )

Enable or disable instruction cache functionality in IRQs.

Parameters

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

Definition at line 489 of file em_msc.h .

References BUS_RegBitWrite() .

MSC_RAMFUNC_DEFINITION_BEGIN MSC_Status_TypeDef MSC_ErasePage ( uint32_t * startAddress )

Erases a page in flash memory.

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

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

Parameters

[in] startAddress A pointer to the flash page to erase. Must be aligned to the beginning of the page boundary.

Returns

Returns the status of erase operation, MSC_Status_TypeDef

*   mscReturnOk - The operation completed successfully.
*   mscReturnInvalidAddr - The operation tried to erase a non-flash area.
*   mscReturnLocked - The operation tried to erase a locked area of the flash.
*   mscReturnTimeOut - The operation timed out waiting for the flash operation
*       to complete.
*

Definition at line 1011 of file em_msc.c .

References MSC_PROGRAM_TIMEOUT , mscReturnInvalidAddr , mscReturnLocked , mscReturnOk , and mscReturnTimeOut .

Referenced by NVMHAL_PageErase() .

void MSC_ExecConfigSet ( MSC_ExecConfig_TypeDef * execConfig )

Set the MSC code execution configuration.

Parameters

[in] execConfig The code execution configuration.

Definition at line 639 of file em_msc.c .

References MSC_ExecConfig_TypeDef::aiDis , MSC_ExecConfig_TypeDef::iccDis , MSC_ExecConfig_TypeDef::ifcDis , MSC_ExecConfig_TypeDef::prefetchEn , MSC_ExecConfig_TypeDef::scbtEn , and MSC_ExecConfig_TypeDef::useHprot .

__STATIC_INLINE int32_t MSC_GetCacheMeasurement ( void )

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.

Definition at line 431 of file em_msc.h .

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.

Definition at line 573 of file em_msc.c .

References CMU_ClockFreqGet() , and cmuClock_AUX .

Referenced by DBG_DisableDebugAccess() , and NVMHAL_Init() .

__STATIC_INLINE void MSC_IntClear ( uint32_t flags )

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

Definition at line 262 of file em_msc.h .

__STATIC_INLINE void MSC_IntDisable ( uint32_t flags )

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

Definition at line 279 of file em_msc.h .

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

Definition at line 301 of file em_msc.h .

__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 321 of file em_msc.h .

__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 340 of file em_msc.h .

__STATIC_INLINE void MSC_IntSet ( uint32_t flags )

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

Definition at line 356 of file em_msc.h .

MSC_RAMFUNC_DEFINITION_END SL_RAMFUNC_DEFINITION_BEGIN MSC_Status_TypeDef MSC_MassErase ( void )

Erase the 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 a successful mass erase.

Definition at line 1180 of file em_msc.c .

References mscReturnOk .

__STATIC_INLINE void MSC_StartCacheMeasurement ( void )

Starts measuring cache hit ratio.

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

Definition at line 373 of file em_msc.h .

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`	A pointer to the flash word to write to. Must be aligned to words.
[in]	`data`	Data to write to flash.
[in]	`numBytes`	A number of bytes to write from flash. NB: Must be divisible by four.

Returns

Returns the status of the write operation.

*   flashReturnOk - The operation completed successfully.
*   flashReturnInvalidAddr - The operation tried to erase a non-flash area.
*   flashReturnLocked - The operation tried to erase a locked area of the Flash.
*   flashReturnTimeOut - The operation timed out waiting for the flash operation
*       to complete, or the MSC module timed out waiting for the software to write
*       the next word into the DWORD register.
*

Definition at line 1113 of file em_msc.c .

Referenced by DBG_DisableDebugAccess() , MSC_WriteWordFast() , 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 divisible by four.

Warning: This function is only available for certain devices.

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 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 this manually in the project's scatter file.

Deprecated:: This function is deprecated, the functionality is the same as calling MSC_WriteWord() .

Parameters

[in]	`address`	A pointer to the flash word to write to. Must be aligned to words.
[in]	`data`	Data to write to flash.
[in]	`numBytes`	A number of bytes to write from the Flash. NB: Must be divisible by four.

Returns

Returns the status of the write operation.

*   flashReturnOk - The operation completed successfully.
*   flashReturnInvalidAddr - The operation tried to erase a non-flash area.
*   flashReturnLocked - The operation tried to erase a locked area of the flash.
*   flashReturnTimeOut - The 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 1160 of file em_msc.c .

References MSC_WriteWord() .

MSC EMLIB

Detailed Description

Data Structures

Macros

Enumerations

Functions

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation

MSC
EMLIB