EFM32 Happy Gecko Software Documentation
efm32hg-doc-5.1.2
|
Memory System Controller API.
This module contain functions to control the MSC, primarily the Flash. The user 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.
The MSC resets into a safe state. To initialize the instruction interface to recommended settings:
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.
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.
The following steps are necessary to perform a page erase and write:
Data Structures | |
struct | MSC_ExecConfig_TypeDef |
Macros | |
#define | EM_MSC_RUN_FROM_FLASH |
By compiling with the define EM_MSC_RUN_FROM_FLASH, the 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. More... | |
#define | MSC_EXECCONFIG_DEFAULT |
#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 | 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. | |
__STATIC_INLINE void | MSC_EnableAutoCacheFlush (bool enable) |
Enable or disable instruction cache flushing when writing to flash. More... | |
__STATIC_INLINE void | MSC_EnableCache (bool enable) |
Enable or disable instruction cache functionality. More... | |
MSC_RAMFUNC_DECLARATOR MSC_Status_TypeDef | MSC_ErasePage (uint32_t *startAddress) |
Erases a page in flash memory. More... | |
void | MSC_ExecConfigSet (MSC_ExecConfig_TypeDef *execConfig) |
Set MSC code execution configuration. More... | |
__STATIC_INLINE void | MSC_FlushCache (void) |
Flush the contents of the instruction cache. | |
__STATIC_INLINE int32_t | MSC_GetCacheMeasurement (void) |
Stops measuring the hit rate. More... | |
void | MSC_Init (void) |
Enables the flash controller for writing. 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... | |
MSC_RAMFUNC_DECLARATOR MSC_Status_TypeDef | MSC_MassErase (void) |
Erase entire flash in one operation. More... | |
__STATIC_INLINE void | MSC_StartCacheMeasurement (void) |
Starts measuring cache hit ratio. More... | |
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 divisable by four. More... | |
MSC_RAMFUNC_DECLARATOR 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... | |
#define EM_MSC_RUN_FROM_FLASH |
By compiling with the define EM_MSC_RUN_FROM_FLASH, the 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_EXECCONFIG_DEFAULT |
#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.
Definition at line 110 of file em_msc.h.
Referenced by MSC_ErasePage().
enum MSC_Status_TypeDef |
Return codes for writing/erasing the flash
__STATIC_INLINE void MSC_EnableAutoCacheFlush | ( | bool | enable | ) |
Enable or disable instruction cache flushing when writing to flash.
[in] | enable | Enable automatic cache flushing. Default is on. |
Definition at line 428 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.
[in] | enable | Enable instruction cache. Default is on. |
Definition at line 402 of file em_msc.h.
References _MSC_READCTRL_IFCDIS_SHIFT, BUS_RegBitWrite(), and MSC.
MSC_RAMFUNC_DEFINITION_BEGIN MSC_Status_TypeDef MSC_ErasePage | ( | uint32_t * | startAddress | ) |
Erases a page in flash memory.
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.
[in] | startAddress | Pointer to the flash page to erase. Must be aligned to beginning of page boundary. |
* 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 748 of file em_msc.c.
References EMU, 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 NVMHAL_PageErase().
void MSC_ExecConfigSet | ( | MSC_ExecConfig_TypeDef * | execConfig | ) |
Set MSC code execution configuration.
[in] | execConfig | Code execution configuration |
Definition at line 234 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_IFCDIS, MSC_READCTRL_MODE_WS0, MSC_READCTRL_MODE_WS1, MSC_ExecConfig_TypeDef::prefetchEn, MSC_ExecConfig_TypeDef::scbtEn, and MSC_ExecConfig_TypeDef::useHprot.
__STATIC_INLINE int32_t MSC_GetCacheMeasurement | ( | void | ) |
Stops measuring the hit rate.
* 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(); * } *
Definition at line 352 of file em_msc.h.
References MSC, MSC_CMD_STOPPC, MSC_IF_CHOF, and MSC_IF_CMOF.
void MSC_Init | ( | void | ) |
Enables the flash controller for writing.
Definition at line 157 of file em_msc.c.
References _MSC_TIMEBASE_BASE_MASK, _MSC_TIMEBASE_BASE_SHIFT, _MSC_TIMEBASE_PERIOD_MASK, CMU_ClockFreqGet(), cmuClock_AUX, EMU, MSC, MSC_TIMEBASE_PERIOD_1US, MSC_TIMEBASE_PERIOD_5US, MSC_UNLOCK_CODE, MSC_WRITECTRL_WREN, and SystemCoreClockGet().
Referenced by NVMHAL_Init().
__STATIC_INLINE void MSC_IntClear | ( | uint32_t | flags | ) |
__STATIC_INLINE void MSC_IntDisable | ( | uint32_t | flags | ) |
__STATIC_INLINE 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). |
Definition at line 223 of file em_msc.h.
References MSC.
__STATIC_INLINE uint32_t MSC_IntGet | ( | void | ) |
__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.
Definition at line 260 of file em_msc.h.
References MSC.
__STATIC_INLINE void MSC_IntSet | ( | uint32_t | flags | ) |
MSC_RAMFUNC_DEFINITION_END MSC_RAMFUNC_DEFINITION_BEGIN MSC_Status_TypeDef MSC_MassErase | ( | void | ) |
Erase entire flash in one operation.
Definition at line 906 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.
__STATIC_INLINE void MSC_StartCacheMeasurement | ( | void | ) |
Starts measuring cache hit ratio.
This function starts the performance counters. It is defined inline to minimize the impact of this code on the measurement itself.
Definition at line 291 of file em_msc.h.
References MSC, MSC_CMD_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 divisable by four.
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 system core clock at 1MHz or higher.
[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 from flash. NB: Must be divisable by four. |
* 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 839 of file em_msc.c.
Referenced by NVMHAL_Write().
MSC_RAMFUNC_DEFINITION_END MSC_RAMFUNC_DEFINITION_BEGIN 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.
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.
[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 from flash. NB: Must be divisable by four. |
* 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. *