MSC - Memory System Controller
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 - 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:
- 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:
Data Structures |
|
struct | MSC_ExecConfig_TypeDef |
Code execution configuration.
|
|
struct | MSC_EccConfig_TypeDef |
ECC configuration.
|
|
Functions |
|
void | MSC_IntClear (uint32_t flags) |
Clear one or more pending MSC interrupts.
|
|
void | MSC_IntDisable (uint32_t flags) |
Disable one or more MSC interrupts.
|
|
void | MSC_IntEnable (uint32_t flags) |
Enable one or more MSC interrupts.
|
|
uint32_t | MSC_IntGet (void) |
Get pending MSC interrupt flags.
|
|
uint32_t | MSC_IntGetEnabled (void) |
Get enabled and pending MSC interrupt flags.
|
|
void | MSC_IntSet (uint32_t flags) |
Set one or more pending MSC interrupts from SW.
|
|
void | MSC_Init (void) |
Initialize MSC module.
|
|
void | MSC_Deinit (void) |
Turn off MSC flash write enable and lock MSC registers.
|
|
void | MSC_ExecConfigSet ( MSC_ExecConfig_TypeDef *execConfig) |
Set MSC code execution configuration.
|
|
void | MSC_EccConfigSet ( MSC_EccConfig_TypeDef *eccConfig) |
Configure Error Correcting Code (ECC).
|
|
void | MSC_DmemPortMapSet ( MSC_DmemMaster_TypeDef master, uint8_t port) |
Set MPAHBRAM port to use to access DMEM.
|
|
void | MSC_PortSetPriority ( MSC_PortPriority_TypeDef portPriority) |
Set MPAHBRAM port priority for arbitration when multiples concurrents transactions to DMEM.
|
|
MSC_PortPriority_TypeDef | MSC_PortGetCurrentPriority (void) |
Get MPAHBRAM port arbitration priority selection.
|
|
MSC_RAMFUNC_DECLARATOR MSC_Status_TypeDef | MSC_WriteWord (uint32_t *address, void const *data, uint32_t numBytes) |
Writes data to flash memory.
|
|
MSC_RAMFUNC_DECLARATOR MSC_Status_TypeDef | MSC_ErasePage (uint32_t *startAddress) |
Erases a page in flash memory.
|
|
SL_RAMFUNC_DECLARATOR MSC_Status_TypeDef | MSC_MassErase (void) |
Erase the entire Flash in one operation.
|
|
MSC_Status_TypeDef | MSC_WriteWordDma (int ch, uint32_t *address, const void *data, uint32_t numBytes) |
Writes data to flash memory using the DMA.
|
|
Macros |
|
#define | MSC_PROGRAM_TIMEOUT 10000000UL |
Timeout used while waiting for Flash to become ready after a write.
|
|
#define | MSC_EXECCONFIG_DEFAULT |
Default MSC ExecConfig initialization.
|
|
#define | MSC_ECC_BANKS (1) |
Series 2 chips incorporate 1 memory bank including ECC support.
|
|
#define | MSC_ECCCONFIG_DEFAULT |
Default MSC EccConfig initialization.
|
|
Enumerations |
|
enum |
MSC_Status_TypeDef
{
mscReturnOk = 0, mscReturnInvalidAddr = -1, mscReturnLocked = -2, mscReturnTimeOut = -3, mscReturnUnaligned = -4 } |
Return codes for writing/erasing Flash.
|
|
enum |
MSC_DmemMaster_TypeDef
{
mscDmemMasterLDMA = _SYSCFG_DMEM0PORTMAPSEL_LDMAPORTSEL_SHIFT, mscDmemMasterSRWAES = _SYSCFG_DMEM0PORTMAPSEL_SRWAESPORTSEL_SHIFT, mscDmemMasterAHBSRW = _SYSCFG_DMEM0PORTMAPSEL_AHBSRWPORTSEL_SHIFT, mscDmemMasterSRWECA0 = _SYSCFG_DMEM0PORTMAPSEL_SRWECA0PORTSEL_SHIFT, mscDmemMasterSRWECA1 = _SYSCFG_DMEM0PORTMAPSEL_SRWECA1PORTSEL_SHIFT } |
AHBHOST masters that can use alternate MPAHBRAM ports.
|
|
enum |
MSC_PortPriority_TypeDef
{
mscPortPriorityNone = _MPAHBRAM_CTRL_AHBPORTPRIORITY_NONE, mscPortPriorityPort0 = _MPAHBRAM_CTRL_AHBPORTPRIORITY_PORT0, mscPortPriorityPort1 = _MPAHBRAM_CTRL_AHBPORTPRIORITY_PORT1 } |
AHB port given priority.
|
|
Function Documentation
◆ MSC_IntClear()
|
inline |
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).
◆ MSC_IntDisable()
|
inline |
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).
◆ MSC_IntEnable()
|
inline |
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).
◆ MSC_IntGet()
|
inline |
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).
◆ MSC_IntGetEnabled()
|
inline |
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
◆ MSC_IntSet()
|
inline |
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).
◆ MSC_Init()
void MSC_Init | ( | void |
|
) |
Initialize MSC module.
Puts MSC hw in a known state.
◆ MSC_Deinit()
void MSC_Deinit | ( | void |
|
) |
Turn off MSC flash write enable and lock MSC registers.
◆ MSC_ExecConfigSet()
void MSC_ExecConfigSet | ( | MSC_ExecConfig_TypeDef * |
execConfig
|
) |
Set MSC code execution configuration.
- Parameters
-
[in] execConfig
Code execution configuration
◆ MSC_EccConfigSet()
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
◆ MSC_DmemPortMapSet()
void MSC_DmemPortMapSet | ( | MSC_DmemMaster_TypeDef |
master,
|
uint8_t |
port
|
||
) |
Set MPAHBRAM port to use to access DMEM.
This function configures which MPAHBRAM slave port is used to access DMEM. Depending on the use case, it might improve performance by spreading the load over the two ports, instead of starving because a port is used by another master.
- Parameters
-
[in] master
AHBHOST master to be configured. [in] port
AHBHOST slave port to use.
◆ MSC_PortSetPriority()
void MSC_PortSetPriority | ( | MSC_PortPriority_TypeDef |
portPriority
|
) |
Set MPAHBRAM port priority for arbitration when multiples concurrents transactions to DMEM.
This function configures which MPAHBRAM slave port will have priority. The AHB port arbitration default scheme, round-robin arbitration, is selected when portPriority == mscPortPriorityNone.
- Note
- Doing this can potentially starve the others AHB port(s).
- Parameters
-
[in] portPriority
AHBHOST slave port having elevated priority.
◆ MSC_PortGetCurrentPriority()
MSC_PortPriority_TypeDef MSC_PortGetCurrentPriority | ( | void |
|
) |
Get MPAHBRAM port arbitration priority selection.
This function returns the AHBHOST slave with raised priority.
- Returns
- Returns the AHBHOST slave port given priority or none.
◆ 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.
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.
- Parameters
-
[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.
- 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. *
◆ MSC_ErasePage()
MSC_RAMFUNC_DEFINITION_BEGIN MSC_Status_TypeDef MSC_ErasePage | ( | uint32_t * |
startAddress
|
) |
Erases a page in flash memory.
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.
- Parameters
-
[in] startAddress
Pointer 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. * flashReturnLocked - MSC registers are locked or the operation tried to * erase a locked area of the flash. * flashReturnTimeOut - Operation timed out. *
◆ MSC_MassErase()
MSC_RAMFUNC_DEFINITION_END MSC_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.
- Returns
- Returns the status of the operation.
◆ 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.
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.
- Parameters
-
[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. [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. *
Macro Definition Documentation
◆ MSC_PROGRAM_TIMEOUT
#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.
◆ MSC_EXECCONFIG_DEFAULT
#define MSC_EXECCONFIG_DEFAULT |
Default MSC ExecConfig initialization.
◆ MSC_ECC_BANKS
#define MSC_ECC_BANKS (1) |
Series 2 chips incorporate 1 memory bank including ECC support.
◆ MSC_ECCCONFIG_DEFAULT
#define MSC_ECCCONFIG_DEFAULT |
Default MSC EccConfig initialization.
Enumeration Type Documentation
◆ MSC_Status_TypeDef
enum MSC_Status_TypeDef |
Return codes for writing/erasing Flash.
◆ MSC_DmemMaster_TypeDef
AHBHOST masters that can use alternate MPAHBRAM ports.
◆ MSC_PortPriority_TypeDef
AHB port given priority.