EFM32 Wonder Gecko Software Documentation  efm32wg-doc-4.2.1

Flash controller (MSC) peripheral API

. More...

Data Structures

struct  MSC_ExecConfig_TypeDef
 

Macros

#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. More...
 
#define EM_MSC_RUN_FROM_FLASH
 By compiling with the define EM_MSC_RUN_FROM_FLASH the Flash controller (MSC) peripheral 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 the MSC peripheral functions will be copied into and run out of RAM. More...
 
#define MSC_EXECCONFIG_DEFAULT
 
#define MSC_FUNC_PREFIX
 
#define MSC_FUNC_POSTFIX
 

Enumerations

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

Functions

void MSC_Init (void)
 Enables the flash controller for writing. More...
 
void MSC_Deinit (void)
 Disables the flash controller for writing.
 
void MSC_ExecConfigSet (MSC_ExecConfig_TypeDef *execConfig)
 Set MSC code execution configuration. More...
 
__STATIC_INLINE void MSC_IntClear (uint32_t flags)
 Clear one or more pending MSC interrupts. More...
 
__STATIC_INLINE void MSC_IntDisable (uint32_t flags)
 Disable one or more MSC interrupts. More...
 
__STATIC_INLINE void MSC_IntEnable (uint32_t flags)
 Enable one or more MSC interrupts. More...
 
__STATIC_INLINE uint32_t MSC_IntGet (void)
 Get pending MSC interrupt flags. More...
 
__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. More...
 
__STATIC_INLINE void MSC_IntSet (uint32_t flags)
 Set one or more pending MSC interrupts from SW. More...
 
__STATIC_INLINE void MSC_StartCacheMeasurement (void)
 Starts measuring cache hit ratio. More...
 
__STATIC_INLINE int32_t MSC_GetCacheMeasurement (void)
 Stops measuring the hit rate. More...
 
__STATIC_INLINE void MSC_FlushCache (void)
 Flush the contents of the instruction cache.
 
__STATIC_INLINE void MSC_EnableCache (bool enable)
 Enable or disable instruction cache functionality. More...
 
__STATIC_INLINE void MSC_EnableCacheIRQs (bool enable)
 Enable or disable instruction cache functionality in IRQs. More...
 
__STATIC_INLINE void MSC_EnableAutoCacheFlush (bool enable)
 Enable or disable instruction cache flushing when writing to flash. More...
 
__STATIC_INLINE void MSC_BusStrategy (mscBusStrategy_Typedef mode)
 Configure which unit should get priority on system bus. More...
 
MSC_FUNC_PREFIX 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. More...
 
MSC_FUNC_PREFIX 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. More...
 
MSC_FUNC_PREFIX MSC_Status_TypeDef MSC_ErasePage (uint32_t *startAddress)
 Erases a page in flash memory. More...
 
MSC_FUNC_PREFIX MSC_Status_TypeDef MSC_MassErase (void)
 Erase entire flash in one operation. More...
 

Detailed Description

Flash controller (MSC) Peripheral API

.

Macro Definition Documentation

#define MSC_PROGRAM_TIMEOUT   10000000ul
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 72 of file em_msc.h.

Referenced by MSC_ErasePage().

#define EM_MSC_RUN_FROM_FLASH
Note
This define is commented out by default so the MSC controller API will run from RAM by default.

Definition at line 87 of file em_msc.h.

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

Default MSC ExecConfig initialization

Definition at line 130 of file em_msc.h.

Enumeration Type Documentation

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

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

Function Documentation

void MSC_Init ( void  )
Note
IMPORTANT: This function must be called before flash operations when AUXHFRCO clock has been changed from default 14MHz band.
This function calls SystemCoreClockGet in order to set the global variable SystemCoreClock which is used in subseqent calls of MSC_WriteWord to make sure the frequency is sufficiently high for flash operations. If the clock frequency is changed then software is responsible for calling MSC_Init or SystemCoreClockGet in order to set the SystemCoreClock variable to the correct value.

Definition at line 101 of file em_msc.c.

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

Referenced by BSP_TraceProfilerEnable(), and NVMHAL_Init().

__STATIC_INLINE void MSC_IntClear ( uint32_t  flags)
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 164 of file em_msc.h.

References MSC.

__STATIC_INLINE void MSC_IntDisable ( uint32_t  flags)
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 177 of file em_msc.h.

References MSC.

__STATIC_INLINE void MSC_IntEnable ( uint32_t  flags)
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 196 of file em_msc.h.

References MSC.

__STATIC_INLINE uint32_t MSC_IntGet ( void  )
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 213 of file em_msc.h.

References MSC.

__STATIC_INLINE uint32_t MSC_IntGetEnabled ( void  )
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 233 of file em_msc.h.

References MSC.

__STATIC_INLINE void MSC_IntSet ( uint32_t  flags)
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 250 of file em_msc.h.

References MSC.

__STATIC_INLINE void MSC_StartCacheMeasurement ( void  )

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

Definition at line 264 of file em_msc.h.

References MSC, MSC_CMD_STARTPC, MSC_IF_CHOF, and MSC_IF_CMOF.

__STATIC_INLINE int32_t MSC_GetCacheMeasurement ( void  )
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 325 of file em_msc.h.

References MSC, MSC_CMD_STOPPC, MSC_IF_CHOF, and MSC_IF_CMOF.

__STATIC_INLINE void MSC_EnableCache ( bool  enable)
Parameters
[in]enableEnable instruction cache. Default is on.

Definition at line 373 of file em_msc.h.

References _MSC_READCTRL_IFCDIS_SHIFT, BUS_RegBitWrite(), and MSC.

__STATIC_INLINE void MSC_EnableCacheIRQs ( bool  enable)
Parameters
[in]enableEnable instruction cache. Default is on.

Definition at line 386 of file em_msc.h.

References _MSC_READCTRL_ICCDIS_SHIFT, BUS_RegBitWrite(), and MSC.

__STATIC_INLINE void MSC_EnableAutoCacheFlush ( bool  enable)
Parameters
[in]enableEnable automatic cache flushing. Default is on.

Definition at line 399 of file em_msc.h.

References _MSC_READCTRL_AIDIS_SHIFT, BUS_RegBitWrite(), and MSC.

__STATIC_INLINE void MSC_BusStrategy ( mscBusStrategy_Typedef  mode)
Parameters
[in]modeUnit to prioritize bus accesses for.

Definition at line 413 of file em_msc.h.

References _MSC_READCTRL_BUSSTRATEGY_MASK, and MSC.

MSC_Status_TypeDef MSC_WriteWord ( uint32_t *  address,
void const *  data,
uint32_t  numBytes 
)
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 ystem 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 738 of file em_msc.c.

Referenced by BSP_TraceProfilerEnable(), and NVMHAL_Write().

MSC_Status_TypeDef MSC_WriteWordFast ( uint32_t *  address,
void const *  data,
uint32_t  numBytes 
)
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.

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 797 of file em_msc.c.

MSC_Status_TypeDef MSC_ErasePage ( uint32_t *  startAddress)
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 637 of file em_msc.c.

References 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 BSP_TraceProfilerEnable(), and NVMHAL_PageErase().

MSC_Status_TypeDef MSC_MassErase ( void  )
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 827 of file em_msc.c.

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