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

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#

MSC_ExecConfig_TypeDef

Enumerations#

enum
mscReturnOk = 0
mscReturnInvalidAddr = -1
mscReturnLocked = -2
mscReturnTimeOut = -3
mscReturnUnaligned = -4
}

Return codes for writing/erasing Flash.

Functions#

void
MSC_Init(void)

Enables the flash controller for writing.

void

Disables the flash controller for writing.

void
MSC_ExecConfigSet(MSC_ExecConfig_TypeDef *execConfig)

Set the MSC code execution configuration.

MSC_RAMFUNC_DEFINITION_BEGIN MSC_Status_TypeDef
MSC_ErasePage(uint32_t *startAddress)

Erases a page in flash memory.

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.

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.

MSC_RAMFUNC_DEFINITION_END MSC_Status_TypeDef
MSC_WriteWordDma(int ch, uint32_t *address, const void *data, uint32_t numBytes)

Writes data from RAM to flash memory using the DMA.

Erase the entire Flash in one operation.

bool

Get the status of the MSC register lock.

void

Set the MSC register lock to a locked state.

void

Set the MSC register lock to an unlocked state.

uint32_t

Get the current value of the read control register (MSC_READCTRL).

void
MSC_ReadCTRLSet(uint32_t value)

Write a value to the read control register (MSC_READCTRL).

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

Get pending MSC interrupt flags.

uint32_t

Get enabled and pending MSC interrupt flags.

void
MSC_IntSet(uint32_t flags)

Set one or more pending MSC interrupts from SW.

void

Start measuring the cache hit ratio.

int32_t

Stop measuring the hit rate.

void

Flush contents of instruction cache.

void
MSC_EnableCache(bool enable)

Enable or disable instruction cache functionality.

void
MSC_EnableCacheIRQs(bool enable)

Enable or disable instruction cache functionality in IRQs.

void

Enable or disable instruction cache flushing when writing to flash.

Macros#

#define

Timeout used while waiting for Flash to become ready after a write.

#define

Default MSC ExecConfig 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.


Definition at line 150 of file platform/emlib/inc/em_msc.h

Function Documentation#

MSC_Init#

void MSC_Init (void )

Enables the flash controller for writing.

Parameters
N/A

Note

  • This function must be called before flash operations when AUXHFRCO clock has been changed from a default band.


Definition at line 791 of file platform/emlib/src/em_msc.c

MSC_Deinit#

void MSC_Deinit (void )

Disables the flash controller for writing.

Parameters
N/A

Definition at line 842 of file platform/emlib/src/em_msc.c

MSC_ExecConfigSet#

void MSC_ExecConfigSet (MSC_ExecConfig_TypeDef * execConfig)

Set the MSC code execution configuration.

Parameters
[in]execConfig

The code execution configuration.


Definition at line 857 of file platform/emlib/src/em_msc.c

MSC_ErasePage#

MSC_RAMFUNC_DECLARATOR MSC_Status_TypeDef MSC_ErasePage (uint32_t * startAddress)

Erases a page in flash memory.

Parameters
[in]startAddress

A pointer to the flash page to erase. Must be aligned to the beginning of the page boundary.

Note

  • For the Gecko family, it is required to run this function from RAM.

For IAR Embedded Workbench, Simplicity Studio and GCC, 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.

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 1229 of file platform/emlib/src/em_msc.c

MSC_WriteWord#

MSC_RAMFUNC_DECLARATOR MSC_Status_TypeDef MSC_WriteWord (uint32_t * address, void const * data, uint32_t numBytes)

Writes data to flash memory.

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.

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.

For the Gecko family, it is required to run this function from RAM.

For IAR Embedded Workbench, Simplicity Studio and GCC, 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.

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 1331 of file platform/emlib/src/em_msc.c

MSC_WriteWordFast#

MSC_RAMFUNC_DECLARATOR MSC_Status_TypeDef MSC_WriteWordFast (uint32_t * address, void const * data, uint32_t numBytes)

Writes data to flash memory.

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.

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. Warnings

  • This function is only available for certain devices.

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 Embedded Workbench, Simplicity Studio and GCC, 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.

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

Definition at line 1378 of file platform/emlib/src/em_msc.c

MSC_WriteWordDma#

MSC_Status_TypeDef MSC_WriteWordDma (int ch, uint32_t * address, const void * data, uint32_t numBytes)

Writes data from RAM to flash memory using the DMA.

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. Note that this argument must be an address in RAM. This function does not support copying data from flash to flash on series-1 devices. Must 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 this function only supports writing data from RAM to flash, it does not support writing data from flash to flash.

Note

  • This function requires that the LDMA 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.
    * 

Definition at line 1422 of file platform/emlib/src/em_msc.c

MSC_MassErase#

SL_RAMFUNC_DECLARATOR MSC_Status_TypeDef MSC_MassErase (void )

Erase the entire Flash in one operation.

Parameters
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.


Definition at line 1502 of file platform/emlib/src/em_msc.c

MSC_LockGetLocked#

bool MSC_LockGetLocked (void )

Get the status of the MSC register lock.

Parameters
N/A

Returns

  • Boolean true if register lock is applied, false otherwise.


Definition at line 331 of file platform/emlib/inc/em_msc.h

MSC_LockSetLocked#

void MSC_LockSetLocked (void )

Set the MSC register lock to a locked state.

Parameters
N/A

Definition at line 348 of file platform/emlib/inc/em_msc.h

MSC_LockSetUnlocked#

void MSC_LockSetUnlocked (void )

Set the MSC register lock to an unlocked state.

Parameters
N/A

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

Parameters
N/A

Returns

  • The 32-bit value read from the MSC_READCTRL register.


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

Parameters
[in]value

The 32-bit value to write to the MSC_READCTRL register.


Definition at line 399 of file platform/emlib/inc/em_msc.h

MSC_IntClear#

void MSC_IntClear (uint32_t flags)

Clear one or more pending MSC interrupts.

Parameters
[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).


Definition at line 550 of file platform/emlib/inc/em_msc.h

MSC_IntDisable#

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 567 of file platform/emlib/inc/em_msc.h

MSC_IntEnable#

void MSC_IntEnable (uint32_t flags)

Enable one or more MSC interrupts.

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).

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.


Definition at line 589 of file platform/emlib/inc/em_msc.h

MSC_IntGet#

uint32_t MSC_IntGet (void )

Get pending MSC interrupt flags.

Parameters
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).


Definition at line 609 of file platform/emlib/inc/em_msc.h

MSC_IntGetEnabled#

uint32_t MSC_IntGetEnabled (void )

Get enabled and pending MSC interrupt flags.

Parameters
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


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

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 644 of file platform/emlib/inc/em_msc.h

MSC_StartCacheMeasurement#

void MSC_StartCacheMeasurement (void )

Start measuring the cache hit ratio.

Parameters
N/A

Starts performance counters. It is defined inline to minimize the impact of this code on the measurement itself.


Definition at line 661 of file platform/emlib/inc/em_msc.h

MSC_GetCacheMeasurement#

int32_t MSC_GetCacheMeasurement (void )

Stop measuring the hit rate.

Parameters
N/A

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 719 of file platform/emlib/inc/em_msc.h

MSC_FlushCache#

void MSC_FlushCache (void )

Flush contents of instruction cache.

Parameters
N/A

Definition at line 750 of file platform/emlib/inc/em_msc.h

MSC_EnableCache#

void MSC_EnableCache (bool enable)

Enable or disable instruction cache functionality.

Parameters
[in]enable

Enable instruction cache. Default is on.


Definition at line 765 of file platform/emlib/inc/em_msc.h

MSC_EnableCacheIRQs#

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 777 of file platform/emlib/inc/em_msc.h

MSC_EnableAutoCacheFlush#

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 789 of file platform/emlib/inc/em_msc.h

Macro Definition Documentation#

MSC_PROGRAM_TIMEOUT#

#define MSC_PROGRAM_TIMEOUT
Value:
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 128 of file platform/emlib/inc/em_msc.h

MSC_EXECCONFIG_DEFAULT#

#define MSC_EXECCONFIG_DEFAULT
Value:
{ \
false, \
true, \
false, \
false, \
false, \
false, \
}

Default MSC ExecConfig initialization.


Definition at line 239 of file platform/emlib/inc/em_msc.h