MSC - Memory System Controller#
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:
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));
Note
The configuration EM_MSC_RUN_FROM_RAM is used to allocate the flash write functions in RAM. By default, flash write functions are placed in RAM on EFM32G and Series 2 devices unless SL_RAMFUNC_DISABLE is defined. For other devices, flash write functions are placed in FLASH by default unless EM_MSC_RUN_FROM_RAM is defined and SL_RAMFUNC_DISABLE is not defined.
Modules#
Enumerations#
Return codes for writing/erasing Flash.
Functions#
Get the status of the MSC register lock.
Set the MSC register lock to a locked state.
Set the MSC register lock to an unlocked state.
Get the current value of the read control register (MSC_READCTRL).
Write a value to the read control register (MSC_READCTRL).
Set the lockbit for a flash page in order to prevent page writes/erases to the corresponding page.
Get the value of the lockbit for a flash page.
Get the size of the user data region in flash.
Get the current value of the mass erase and user data page lock word (MSC_MISCLOCKWORD).
Write a value to the mass erase and user data page lock word (MSC_MISCLOCKWORD).
Clear one or more pending MSC interrupts.
Disable one or more MSC interrupts.
Enable one or more MSC interrupts.
Get pending MSC interrupt flags.
Get enabled and pending MSC interrupt flags.
Set one or more pending MSC interrupts from SW.
Set MSC code execution configuration.
Configure Error Correcting Code (ECC).
Erase the entire Flash in one operation.
Erases a page in flash memory.
Writes data to flash memory.
Writes data to flash memory using the DMA.
Initialize MSC module.
Turn off MSC flash write enable and lock MSC registers.
Read and write existing values in RAM (for ECC initialization).
Initialize ECC for a given memory bank.
Disable ECC for a given memory bank.
Macros#
Timeout used while waiting for Flash to become ready after a write.
Default MSC ExecConfig initialization.
Series 2 chips incorporate 1 memory bank including ECC support.
Default MSC EccConfig initialization.
Enumeration Documentation#
MSC_Status_TypeDef#
MSC_Status_TypeDef
Return codes for writing/erasing Flash.
Enumerator | |
---|---|
mscReturnOk | Flash write/erase successful. |
mscReturnInvalidAddr | Invalid address. |
mscReturnLocked | Flash address is locked. |
mscReturnTimeOut | Timeout while writing to Flash. |
mscReturnUnaligned | Unaligned access to Flash. |
150
of file platform/emlib/inc/em_msc.h
Function Documentation#
MSC_LockGetLocked#
bool MSC_LockGetLocked (void )
Get the status of the MSC register lock.
N/A |
Returns
Boolean true if register lock is applied, false otherwise.
331
of file platform/emlib/inc/em_msc.h
MSC_LockSetLocked#
void MSC_LockSetLocked (void )
Set the MSC register lock to a locked state.
N/A |
348
of file platform/emlib/inc/em_msc.h
MSC_LockSetUnlocked#
void MSC_LockSetUnlocked (void )
Set the MSC register lock to an unlocked state.
N/A |
363
of file platform/emlib/inc/em_msc.h
MSC_ReadCTRLGet#
uint32_t MSC_ReadCTRLGet (void )
Get the current value of the read control register (MSC_READCTRL).
N/A |
Returns
The 32-bit value read from the MSC_READCTRL register.
381
of file platform/emlib/inc/em_msc.h
MSC_ReadCTRLSet#
void MSC_ReadCTRLSet (uint32_t value)
Write a value to the read control register (MSC_READCTRL).
[in] | value | The 32-bit value to write to the MSC_READCTRL register. |
399
of file platform/emlib/inc/em_msc.h
MSC_PageLockSetLocked#
void MSC_PageLockSetLocked (uint32_t page_number)
Set the lockbit for a flash page in order to prevent page writes/erases to the corresponding page.
[in] | page_number | The index of the page to apply the pagelock to. Must be in the range [0, (flash_size / page_size) - 1]. |
422
of file platform/emlib/inc/em_msc.h
MSC_PageLockGetLocked#
bool MSC_PageLockGetLocked (uint32_t page_number)
Get the value of the lockbit for a flash page.
[in] | page_number | The index of the page to get the lockbit value from. Must be in the range [0, (flash_size / page_size) - 1]. |
Returns
Boolean true if the page is locked, false otherwise.
453
of file platform/emlib/inc/em_msc.h
MSC_UserDataGetSize#
uint32_t MSC_UserDataGetSize (void )
Get the size of the user data region in flash.
N/A |
Returns
The size of the user data region divided by 256.
484
of file platform/emlib/inc/em_msc.h
MSC_MiscLockWordGet#
uint32_t MSC_MiscLockWordGet (void )
Get the current value of the mass erase and user data page lock word (MSC_MISCLOCKWORD).
N/A |
Returns
The 32-bit value read from the MSC_MISCLOCKWORD register.
507
of file platform/emlib/inc/em_msc.h
MSC_MiscLockWordSet#
void MSC_MiscLockWordSet (uint32_t value)
Write a value to the mass erase and user data page lock word (MSC_MISCLOCKWORD).
[in] | value | The 32-bit value to write to the MSC_MISCLOCKWORD register. |
526
of file platform/emlib/inc/em_msc.h
MSC_IntClear#
void MSC_IntClear (uint32_t flags)
Clear one or more pending MSC interrupts.
[in] | flags | Pending MSC interrupt source to clear. Use a bitwise logic OR combination of valid interrupt flags for the MSC module (MSC_IF_nnn). |
550
of file platform/emlib/inc/em_msc.h
MSC_IntDisable#
void MSC_IntDisable (uint32_t flags)
Disable one or more MSC interrupts.
[in] | flags | MSC interrupt sources to disable. Use a bitwise logic OR combination of valid interrupt flags for the MSC module (MSC_IF_nnn). |
567
of file platform/emlib/inc/em_msc.h
MSC_IntEnable#
void MSC_IntEnable (uint32_t flags)
Enable one or more MSC interrupts.
[in] | flags | MSC interrupt sources to enable. Use a bitwise logic OR combination of valid interrupt flags for the MSC module (MSC_IF_nnn). |
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.
589
of file platform/emlib/inc/em_msc.h
MSC_IntGet#
uint32_t MSC_IntGet (void )
Get pending MSC interrupt flags.
N/A |
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).
609
of file platform/emlib/inc/em_msc.h
MSC_IntGetEnabled#
uint32_t MSC_IntGetEnabled (void )
Get enabled and pending MSC interrupt flags.
N/A |
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
628
of file platform/emlib/inc/em_msc.h
MSC_IntSet#
void MSC_IntSet (uint32_t flags)
Set one or more pending MSC interrupts from SW.
[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). |
644
of file platform/emlib/inc/em_msc.h
MSC_ExecConfigSet#
void MSC_ExecConfigSet (MSC_ExecConfig_TypeDef * execConfig)
Set MSC code execution configuration.
[in] | execConfig | Code execution configuration |
487
of file platform/emlib/src/em_msc.c
MSC_EccConfigSet#
void MSC_EccConfigSet (MSC_EccConfig_TypeDef * eccConfig)
Configure Error Correcting Code (ECC).
[in] | eccConfig | ECC configuration |
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.
1926
of file platform/emlib/src/em_msc.c
MSC_MassErase#
MSC_RAMFUNC_DEFINITION_END MSC_RAMFUNC_DEFINITION_BEGIN MSC_Status_TypeDef MSC_MassErase (void )
Erase the entire Flash in one operation.
N/A |
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.
Returns
Returns the status of the operation.
657
of file platform/emlib/src/em_msc.c
MSC_ErasePage#
MSC_RAMFUNC_DEFINITION_BEGIN MSC_Status_TypeDef MSC_ErasePage (uint32_t * startAddress)
Erases a page in flash memory.
[in] | startAddress | Pointer to the flash page to erase. Must be aligned to beginning of page boundary. |
For IAR Embedded Workbench, Simplicity Studio and GCC 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.
Returns
Returns the status of erase operation, MSC_Status_TypeDef
* mscReturnOk - Operation completed successfully. * mscReturnInvalidAddr - Operation tried to erase a non-flash area. * flashReturnLocked - MSC registers are locked or the operation tried to * erase a locked area of the flash. * flashReturnTimeOut - Operation timed out. *
532
of file platform/emlib/src/em_msc.c
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.
[in] | address | Pointer to the flash word to write to. Must be aligned to words. |
[in] | data | Data to write to flash. |
[in] | numBytes | Number of bytes to write to flash. NB: Must be divisable by four. |
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 IAR Embedded Workbench, Simplicity Studio and GCC 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.
The Flash memory is organized into 64-bit wide double-words. Each 64-bit double-word can be written only twice using burst write operation between erasing cycles. The user's application must store data in RAM to sustain burst write operation.
EFR32XG21 RevC is not able to program every word twice before the next erase.
Returns
Returns the status of the write operation, MSC_Status_TypeDef
* flashReturnOk - Operation completed successfully. * flashReturnInvalidAddr - Operation tried to write to a non-flash area. * flashReturnLocked - MSC registers are locked or the operation tried to * program a locked area of the flash. * flashReturnTimeOut - Operation timed out. *
603
of file platform/emlib/src/em_msc.c
MSC_WriteWordDma#
MSC_RAMFUNC_DEFINITION_END MSC_Status_TypeDef MSC_WriteWordDma (int ch, uint32_t * address, const void * data, uint32_t numBytes)
Writes data to flash memory using the DMA.
[in] | ch | DMA channel to use |
[in] | address | A pointer to the flash word to write to. Must be aligned to words. |
[in] | data | Data to write to flash and be aligned to words. |
[in] | numBytes | A number of bytes to write from flash. NB: Must be divisible by four. |
This function uses the LDMA to write data to the internal flash memory. This is the fastest way to write data to the flash and should be used when the application wants to achieve write speeds like they are reported in the datasheet. Note that copying data from flash to flash will be slower than copying from RAM to flash. So the source data must be in RAM in order to see the write speeds similar to the datasheet numbers.
Note
This function requires that the LDMA and LDMAXBAR clock is enabled.
Returns
Returns the status of the write operation.
* flashReturnOk - The operation completed successfully. * flashReturnInvalidAddr - The operation tried to erase a non-flash area. *
710
of file platform/emlib/src/em_msc.c
MSC_Init#
void MSC_Init (void )
Initialize MSC module.
N/A |
Puts MSC hw in a known state.
452
of file platform/emlib/src/em_msc.c
MSC_Deinit#
void MSC_Deinit (void )
Turn off MSC flash write enable and lock MSC registers.
N/A |
467
of file platform/emlib/src/em_msc.c
mscEccReadWriteExistingPio#
static void mscEccReadWriteExistingPio (const MSC_EccBank_Typedef * eccBank)
Read and write existing values in RAM (for ECC initialization).
[in] | eccBank | Pointer to ECC RAM bank (MSC_EccBank_Typedef) |
This function uses core to load and store the existing data values in the given RAM bank.
1570
of file platform/emlib/src/em_msc.c
mscEccBankInit#
static void mscEccBankInit (const MSC_EccBank_Typedef * eccBank, uint32_t dmaChannels)
Initialize ECC for a given memory bank.
[in] | eccBank | ECC memory bank device structure. |
[in] | dmaChannels | Array of 2 DMA channels that may be used during ECC initialization. |
This function initializes ECC for a given memory bank which is specified with the MSC_EccBank_Typedef structure input parameter.
1822
of file platform/emlib/src/em_msc.c
mscEccBankDisable#
static void mscEccBankDisable (const MSC_EccBank_Typedef * eccBank)
Disable ECC for a given memory bank.
[in] | eccBank | ECC memory bank device structure. |
This function disables ECC for a given memory bank which is specified with the MSC_EccBank_Typedef structure input parameter.
1881
of file platform/emlib/src/em_msc.c
Macro Definition Documentation#
MSC_PROGRAM_TIMEOUT#
#define MSC_PROGRAM_TIMEOUTValue:
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.
128
of file platform/emlib/inc/em_msc.h
MSC_EXECCONFIG_DEFAULT#
#define MSC_EXECCONFIG_DEFAULTValue:
Default MSC ExecConfig initialization.
222
of file platform/emlib/inc/em_msc.h
MSC_ECC_BANKS#
#define MSC_ECC_BANKSValue:
(1)
Series 2 chips incorporate 1 memory bank including ECC support.
290
of file platform/emlib/inc/em_msc.h
MSC_ECCCONFIG_DEFAULT#
#define MSC_ECCCONFIG_DEFAULTValue:
Default MSC EccConfig initialization.
292
of file platform/emlib/inc/em_msc.h