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.

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:

       uint32_t * userDataPage = (uint32_t *) USERDATA_BASE;
      
       uint32_t userData[] = {
      
       0x01020304,
      
       0x05060708
      
       };
      
        MSC_ErasePage
       
       (userDataPage);
      
        MSC_WriteWord
       
       (userDataPage, userData,
       
        sizeof
       
       (userData));

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 (1)

#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)
	Turn off MSC flash write enable and lock MSC registers.

void	MSC_EccConfigSet ( MSC_EccConfig_TypeDef *eccConfig)
	Configure Error Correcting Code (ECC)

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

void	MSC_Init (void)
	Initialize MSC module. Puts MSC hw in a known state.

__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_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 divisable 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 (1)

EFR32XG21 incorporates 1 memory bank including ECC support.

Definition at line 211 of file em_msc.h .

Referenced by MSC_EccConfigSet() .

#define MSC_ECCCONFIG_DEFAULT

Value:

         { \
        
         {
         
          false
         
         }, \
        
         { 0, 1 }, \
        
         }

Default MSC EccConfig initialization

Definition at line 213 of file em_msc.h .

#define MSC_EXECCONFIG_DEFAULT

Value:

Default MSC ExecConfig initialization

Definition at line 157 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 .

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 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_ECC_BANKS , mscEccBankDisable() , and mscEccBankInit() .

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.

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] 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.
*

Definition at line 457 of file em_msc.c .

References FLASH_PAGE_SIZE , MSC , MSC_LOCK_LOCKKEY_LOCK , MSC_LOCK_LOCKKEY_UNLOCK , MSC_STATUS_BUSY , MSC_WRITECMD_ERASEPAGE , and MSC_WRITECTRL_WREN .

Referenced by NVMHAL_PageErase() .

void MSC_ExecConfigSet ( MSC_ExecConfig_TypeDef * execConfig )

Set MSC code execution configuration.

Parameters

[in] execConfig Code execution configuration

Definition at line 419 of file em_msc.c .

References MSC_ExecConfig_TypeDef::doutBufEn , MSC , and MSC_READCTRL_DOUTBUFEN .

__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_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 divisable by four.

Note: It is recommended to erase the flash page before performing a write.

It is recommended to run this code 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]	`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.
*

Definition at line 513 of file em_msc.c .

References FLASH_PAGE_SIZE , MSC , MSC_LOCK_LOCKKEY_LOCK , MSC_LOCK_LOCKKEY_UNLOCK , MSC_WRITECTRL_WREN , mscReturnOk , and SL_MIN .

Referenced by DBG_DisableDebugAccess() , and NVMHAL_Write() .

static void mscEccBankDisable ( const MSC_EccBank_Typedef * eccBank )

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 void mscEccBankInit	(	const MSC_EccBank_Typedef *	`eccBank,`
		uint32_t	`dmaChannels[2]`
	)

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 MSC_RAMFUNC_DEFINITION_END void mscEccReadWriteExistingDma	(	uint32_t	`start,`
		uint32_t	`size,`
		uint32_t	`channels[2]`
	)

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 , LDMA_CH_LINK_LINK , and LDMA_EN_EN .

Referenced by mscEccBankInit() .

MSCEMLIB

Detailed Description

Data Structures

Macros

Enumerations

Functions

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation