MSCEMLIB
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:
- 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:
Data Structures |
|
struct | MSC_EccConfig_TypeDef |
struct | MSC_ExecConfig_TypeDef |
Macros |
|
#define | EM_MSC_RUN_FROM_FLASH |
By compiling with define EM_MSC_RUN_FROM_FLASH, 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_ECC_BANKS (3) |
#define | MSC_ECCCONFIG_DEFAULT |
#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.
|
|
#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_Status_TypeDef
{
mscReturnOk = 0, mscReturnInvalidAddr = -1, mscReturnLocked = -2, mscReturnTimeOut = -3, mscReturnUnaligned = -4 } |
Functions |
|
void | MSC_Deinit (void) |
Disables the flash controller for writing.
|
|
void | MSC_EccConfigSet ( MSC_EccConfig_TypeDef *eccConfig) |
Configure Error Correcting Code (ECC)
|
|
__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.
|
|
MSC_RAMFUNC_DECLARATOR MSC_Status_TypeDef | MSC_MassErase (void) |
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.
|
|
__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.
|
|
static void | mscEccBankDisable (const MSC_EccBank_Typedef *eccBank) |
Disable ECC for a given memory bank.
|
|
static void | mscEccBankInit (const MSC_EccBank_Typedef *eccBank, uint32_t dmaChannels[2]) |
Initialize ECC for a given memory bank.
|
|
static MSC_RAMFUNC_DEFINITION_END void | mscEccReadWriteExistingDma (uint32_t start, uint32_t size, uint32_t channels[2]) |
DMA read and write existing values (for ECC initializaion).
|
|
Macro Definition Documentation
#define EM_MSC_RUN_FROM_FLASH |
By compiling with define EM_MSC_RUN_FROM_FLASH, 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
124
of file
em_msc.h
.
#define MSC_ECC_BANKS (3) |
EFM32GG12B incorporates 3 memory banks including ECC support.
Definition at line
200
of file
em_msc.h
.
Referenced by MSC_EccConfigSet() .
#define MSC_ECCCONFIG_DEFAULT |
Default MSC EccConfig initialization.
Definition at line
203
of file
em_msc.h
.
#define MSC_EXECCONFIG_DEFAULT |
Default MSC ExecConfig initialization.
Definition at line
174
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
109
of file
em_msc.h
.
Referenced by MSC_ErasePage() .
Enumeration Type Documentation
enum MSC_Status_TypeDef |
Return codes for writing/erasing Flash.
Definition at line
132
of file
em_msc.h
.
Function Documentation
void MSC_EccConfigSet | ( | MSC_EccConfig_TypeDef * |
eccConfig
|
) |
Configure Error Correcting Code (ECC)
This function configures ECC support according to the configuration input parameter. If the user requests enabling ECC for a given RAM bank this function will initialize ECC memory (syndromes) for the bank by reading and writing the existing values in memory. I.e. all data is preserved. The initialization process runs in a critical section disallowing interrupts and thread scheduling, and will consume a considerable amount of clock cycles. Therefore the user should carefully assess where to call this function. The user can consider to increase the clock frequency in order to reduce the execution time. This function makes use of 2 DMA channels to move data to/from RAM in an efficient way. The user can select which 2 DMA channels to use in order to avoid conflicts with the application. However the user must make sure that no other DMA operations takes place while this function is executing. If the application has been using the DMA controller prior to calling this function, the application will need to reinitialize DMA registers after this function has completed.
- Note
-
This function protects the ECC initialization procedure from interrupts and other threads by using a critical section (defined by
em_core.h
) When running on RTOS the user may need to override CORE_EnterCritical CORE_ExitCritical which are declared as 'SL_WEAK' in em_core.c .
- Parameters
-
[in] eccConfig
ECC configuration
Definition at line
1565
of file
em_msc.c
.
References MSC_EccConfig_TypeDef::dmaChannels , MSC_EccConfig_TypeDef::enableEccBank , MSC , MSC_CTRL_RAMECCERRFAULTEN , MSC_ECC_BANKS , mscEccBankDisable() , and mscEccBankInit() .
__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
487
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] enable
Enable instruction cache. Default is on.
Definition at line
463
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] enable
Enable instruction cache. Default is on.
Definition at line
475
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 IDE, Rowley IDE, SimplicityStudio IDE, Atollic IDE, and ARM GCC IDE, 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
1140
of file
em_msc.c
.
References _EMU_STATUS_VSCALE_MASK , _EMU_STATUS_VSCALEBUSY_MASK , EMU , EMU_STATUS_VSCALE_VSCALE2 , FLASH_PAGE_SIZE , MSC , MSC_LOCK_LOCKKEY_LOCK , MSC_LOCK_LOCKKEY_UNLOCK , 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 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
661
of file
em_msc.c
.
References _MSC_READCTRL_MODE_MASK , MSC_ExecConfig_TypeDef::aiDis , MSC_ExecConfig_TypeDef::iccDis , MSC_ExecConfig_TypeDef::ifcDis , MSC , MSC_READCTRL_AIDIS , MSC_READCTRL_ICCDIS , MSC_READCTRL_IFCDIS , MSC_READCTRL_MODE_WS0 , MSC_READCTRL_MODE_WS1 , MSC_READCTRL_PREFETCH , MSC_READCTRL_SCBTP , MSC_READCTRL_USEHPROT , 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
417
of file
em_msc.h
.
References MSC , MSC_CACHECMD_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 a default band.
Definition at line
595
of file
em_msc.c
.
References _EMU_STATUS_VSCALE_MASK , _EMU_STATUS_VSCALEBUSY_MASK , CMU_ClockFreqGet() , cmuClock_AUX , EMU , EMU_STATUS_VSCALE_VSCALE2 , MSC , MSC_UNLOCK_CODE , and MSC_WRITECTRL_WREN .
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
248
of file
em_msc.h
.
References MSC .
__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
265
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. 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
287
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
307
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
326
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] 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
342
of file
em_msc.h
.
References MSC .
MSC_RAMFUNC_DEFINITION_END MSC_RAMFUNC_DEFINITION_BEGIN MSC_Status_TypeDef MSC_MassErase | ( | void |
|
) |
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.
- 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 IDE, Rowley IDE, SimplicityStudio IDE, Atollic IDE, and ARM GCC IDE, 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.
- 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. *
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
1308
of file
em_msc.c
.
References MSC , MSC_LOCK_LOCKKEY_LOCK , MSC_LOCK_LOCKKEY_UNLOCK , 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.
Starts performance counters. It is defined inline to minimize the impact of this code on the measurement itself.
Definition at line
359
of file
em_msc.h
.
References MSC , MSC_CACHECMD_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 divisible 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 IDE, Rowley IDE, SimplicityStudio IDE, Atollic IDE, and ARM GCC IDE, 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
1243
of file
em_msc.c
.
Referenced by DBG_DisableDebugAccess() , and NVMHAL_Write() .
|
static |
Disable ECC for a given memory bank.
This function disables ECC for a given memory bank which is specified with the MSC_EccBank_Typedef structure input parameter.
- Parameters
-
[in] eccBank
ECC memory bank device structure.
Definition at line
1528
of file
em_msc.c
.
Referenced by MSC_EccConfigSet() .
|
static |
Initialize ECC for a given memory bank.
This function initializes ECC for a given memory bank which is specified with the MSC_EccBank_Typedef structure input parameter.
- Parameters
-
[in] eccBank
ECC memory bank device structure. [in] dmaChannels
Array of 2 DMA channels that may be used during ECC initialization.
Definition at line
1487
of file
em_msc.c
.
References CORE_DECLARE_IRQ_STATE , CORE_ENTER_CRITICAL , CORE_EXIT_CRITICAL , and mscEccReadWriteExistingDma() .
Referenced by MSC_EccConfigSet() .
|
static |
DMA read and write existing values (for ECC initializaion).
This function uses DMA to read and write the existing data values in the RAM region specified by start and size. The function will use the 2 DMA channels specified by the channels[2] array.
- Parameters
-
[in] start
Start address of address range in RAM to read/write. [in] size
Size of address range in RAM to read/write. [in] channels[2]
Array of 2 DMA channels to use.
Definition at line
1374
of file
em_msc.c
.
References _LDMA_CH_CTRL_XFERCNT_MASK , _LDMA_CH_LINK_LINKADDR_MASK , _LDMA_CTRL_NUMFIXED_SHIFT , BUS_RegMaskedClear() , CMU_ClockEnable() , cmuClock_LDMA , LDMA , LDMA_CH_CTRL_BLOCKSIZE_ALL , LDMA_CH_CTRL_DSTINC_ONE , LDMA_CH_CTRL_REQMODE_ALL , LDMA_CH_CTRL_SIZE_WORD , LDMA_CH_CTRL_SRCINC_ONE , LDMA_CH_CTRL_STRUCTREQ , LDMA_CH_CTRL_STRUCTTYPE_TRANSFER , and LDMA_CH_LINK_LINK .
Referenced by mscEccBankInit() .