MCUXpresso SDK API Reference Manual  Rev. 0
NXP Semiconductors
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
CACHE: CACHE Memory Controller

Overview

The MCUXpresso SDK provides Peripheral driver for the CACHE Controller of MCUXpresso SDK devices.

CACHE driver is created to help user to operate the Cache memory more easy. The APIs for basic operations are including the following three levels: 1L. The L1 cache driver API. This level provides the level 1 caches controller drivers. The L1 caches are mainly integrated in the Core memory system, Cortex-M7 L1 caches etc. For our kinetis Cortex-M4 series platforms, the L1 cache is the local memory controller (LMEM) which is not integrated in Cortex-M4 processer memory system.

2L. The L2 cache driver API. This level provides the level 2 cache controller drivers. The L2 cache could be integrated in CORE memory system or an external L2 cache memory, PL310 etc.

3L. The combined cache driver API. This level provides many APIs for combined L1 and L2 cache maintain operations. This is provided for MCUXpresso SDK drivers (DMA, ENET, USDHC etc) which should do the cache maintenance in their transactional APIs.

Function groups

L1 CACHE Operation {#L1CACHE MaintainOperation}

The L1 CACHE has both code cache and data cache. This function group provides independent two groups API for both code cache and data cache. There are Enable/Disable APIs for code cache and data cache control and cache maintenance operations as Invalidate/Clean/CleanInvalidate by all and by address range.

L2 CACHE Operation {#L2CACHE MaintainOperation}

The L2 CACHE not divide the cache to data and code. So this function group provides one group cache maintenance operations as Enable/Disable/Invalidate/Clean/CleanInvalidate by all and by address range. Except the maintenance operation APIs, the L2 CACHE has it's initialization/configure API. User can use the default configure parameter by calling L2CACHE_GetDefaultConfig() or change the parameters as they wish. Then call L2CACHE_Init to do the L2 CACHE initialization. After the Initialization, the L2 cache can be enabled then.

Note: For the core external l2 Cache, the soc usually has the control bit to select the SRAM to use as L2 Cache or normal SRAM. Please many sure this select is right when you use the L2 CACHE feature.

Data Structures

struct  L2cache_latency_config_t
 Level 2 cache controller tag/data ram latency configure structure. More...
 
struct  l2cache_config_t
 Level 2 cache controller configure structure. More...
 

Enumerations

enum  l2cache_way_num_t { kL2CACHE_8ways = 0 }
 Number of level 2 cache controller ways. More...
 
enum  l2cache_way_size {
  kL2CACHE_16KBSize = 1,
  kL2CACHE_32KBSize = 2,
  kL2CACHE_64KBSize = 3,
  kL2CACHE_128KBSize = 4,
  kL2CACHE_256KBSize = 5,
  kL2CACHE_512KBSize = 6
}
 Level 2 cache controller way size. More...
 
enum  l2cache_replacement_t {
  kL2CACHE_Pseudorandom = 0U,
  kL2CACHE_Roundrobin
}
 Level 2 cache controller replacement policy. More...
 
enum  l2cache_writealloc_t {
  kL2CACHE_UseAwcache = 0,
  kL2CACHE_NoWriteallocate,
  kL2CACHE_forceWriteallocate
}
 Level 2 cache controller force write allocate options. More...
 
enum  l2cache_latency_t {
  kL2CACHE_1CycleLate = 0,
  kL2CACHE_2CycleLate,
  kL2CACHE_3CycleLate,
  kL2CACHE_4CycleLate,
  kL2CACHE_5CycleLate,
  kL2CACHE_6CycleLate,
  kL2CACHE_7CycleLate,
  kL2CACHE_8CycleLate
}
 Level 2 cache controller tag/data ram latency. More...
 

Driver version

#define FSL_CACHE_DRIVER_VERSION   (MAKE_VERSION(2, 0, 1))
 cache driver version 2.0.1. More...
 

Control for cortex-m7 L1 cache

static void L1CACHE_EnableICache (void)
 Enables cortex-m7 L1 instruction cache.
 
static void L1CACHE_DisableICache (void)
 Disables cortex-m7 L1 instruction cache.
 
static void L1CACHE_InvalidateICache (void)
 Invalidate cortex-m7 L1 instruction cache.
 
void L1CACHE_InvalidateICacheByRange (uint32_t address, uint32_t size_byte)
 Invalidate cortex-m7 L1 instruction cache by range. More...
 
static void L1CACHE_EnableDCache (void)
 Enables cortex-m7 L1 data cache.
 
static void L1CACHE_DisableDCache (void)
 Disables cortex-m7 L1 data cache.
 
static void L1CACHE_InvalidateDCache (void)
 Invalidates cortex-m7 L1 data cache.
 
static void L1CACHE_CleanDCache (void)
 Cleans cortex-m7 L1 data cache.
 
static void L1CACHE_CleanInvalidateDCache (void)
 Cleans and Invalidates cortex-m7 L1 data cache.
 
static void L1CACHE_InvalidateDCacheByRange (uint32_t address, uint32_t size_byte)
 Invalidates cortex-m7 L1 data cache by range. More...
 
static void L1CACHE_CleanDCacheByRange (uint32_t address, uint32_t size_byte)
 Cleans cortex-m7 L1 data cache by range. More...
 
static void L1CACHE_CleanInvalidateDCacheByRange (uint32_t address, uint32_t size_byte)
 Cleans and Invalidates cortex-m7 L1 data cache by range. More...
 

Control for L2 pl310 cache

void L2CACHE_Init (l2cache_config_t *config)
 Initializes the level 2 cache controller module. More...
 
void L2CACHE_GetDefaultConfig (l2cache_config_t *config)
 Gets an available default settings for the cache controller. More...
 
void L2CACHE_Enable (void)
 Enables the level 2 cache controller. More...
 
void L2CACHE_Disable (void)
 Disables the level 2 cache controller. More...
 
void L2CACHE_Invalidate (void)
 Invalidates the Level 2 cache. More...
 
void L2CACHE_InvalidateByRange (uint32_t address, uint32_t size_byte)
 Invalidates the Level 2 cache lines in the range of two physical addresses. More...
 
void L2CACHE_Clean (void)
 Cleans the level 2 cache controller. More...
 
void L2CACHE_CleanByRange (uint32_t address, uint32_t size_byte)
 Cleans the Level 2 cache lines in the range of two physical addresses. More...
 
void L2CACHE_CleanInvalidate (void)
 Cleans and invalidates the level 2 cache controller. More...
 
void L2CACHE_CleanInvalidateByRange (uint32_t address, uint32_t size_byte)
 Cleans and invalidates the Level 2 cache lines in the range of two physical addresses. More...
 
void L2CACHE_LockdownByWayEnable (uint32_t masterId, uint32_t mask, bool enable)
 Enables or disables to lock down the data and instruction by way. More...
 

Unified Cache Control for all caches (cortex-m7 L1 cache + l2 pl310)

Mainly used for many drivers for easy cache operation.

void ICACHE_InvalidateByRange (uint32_t address, uint32_t size_byte)
 Invalidates all instruction caches by range. More...
 
void DCACHE_InvalidateByRange (uint32_t address, uint32_t size_byte)
 Invalidates all data caches by range. More...
 
void DCACHE_CleanByRange (uint32_t address, uint32_t size_byte)
 Cleans all data caches by range. More...
 
void DCACHE_CleanInvalidateByRange (uint32_t address, uint32_t size_byte)
 Cleans and Invalidates all data caches by range. More...
 

Data Structure Documentation

struct L2cache_latency_config_t

Data Fields

l2cache_latency_t tagWriteLate
 Tag write latency. More...
 
l2cache_latency_t tagReadLate
 Tag Read latency. More...
 
l2cache_latency_t tagSetupLate
 Tag setup latency. More...
 
l2cache_latency_t dataWriteLate
 Data write latency. More...
 
l2cache_latency_t dataReadLate
 Data Read latency. More...
 
l2cache_latency_t dataSetupLate
 Data setup latency. More...
 

Field Documentation

l2cache_latency_t L2cache_latency_config_t::tagWriteLate
l2cache_latency_t L2cache_latency_config_t::tagReadLate
l2cache_latency_t L2cache_latency_config_t::tagSetupLate
l2cache_latency_t L2cache_latency_config_t::dataWriteLate
l2cache_latency_t L2cache_latency_config_t::dataReadLate
l2cache_latency_t L2cache_latency_config_t::dataSetupLate
struct l2cache_config_t

Data Fields

l2cache_way_num_t wayNum
 The number of ways. More...
 
l2cache_way_size waySize
 The way size = Cache Ram size / wayNum. More...
 
l2cache_replacement_t repacePolicy
 Replacemnet policy. More...
 
L2cache_latency_config_tlateConfig
 Tag/data latency configure. More...
 
bool istrPrefetchEnable
 Instruction prefetch enable. More...
 
bool dataPrefetchEnable
 Data prefetch enable. More...
 
bool nsLockdownEnable
 None-secure lockdown enable. More...
 
l2cache_writealloc_t writeAlloc
 Write allcoate force option. More...
 

Field Documentation

l2cache_way_num_t l2cache_config_t::wayNum
l2cache_way_size l2cache_config_t::waySize
l2cache_replacement_t l2cache_config_t::repacePolicy
L2cache_latency_config_t* l2cache_config_t::lateConfig

Set NUll if not required.

bool l2cache_config_t::istrPrefetchEnable
bool l2cache_config_t::dataPrefetchEnable
bool l2cache_config_t::nsLockdownEnable
l2cache_writealloc_t l2cache_config_t::writeAlloc

Macro Definition Documentation

#define FSL_CACHE_DRIVER_VERSION   (MAKE_VERSION(2, 0, 1))

Enumeration Type Documentation

Enumerator
kL2CACHE_8ways 

8 ways.

Enumerator
kL2CACHE_16KBSize 

16 KB way size.

kL2CACHE_32KBSize 

32 KB way size.

kL2CACHE_64KBSize 

64 KB way size.

kL2CACHE_128KBSize 

128 KB way size.

kL2CACHE_256KBSize 

256 KB way size.

kL2CACHE_512KBSize 

512 KB way size.

Enumerator
kL2CACHE_Pseudorandom 

Peseudo-random replacement policy using an lfsr.

kL2CACHE_Roundrobin 

Round-robin replacemnt policy.

Enumerator
kL2CACHE_UseAwcache 

Use AWCAHE attribute for the write allocate.

kL2CACHE_NoWriteallocate 

Force no write allocate.

kL2CACHE_forceWriteallocate 

Force write allocate when write misses.

Enumerator
kL2CACHE_1CycleLate 

1 cycle of latency.

kL2CACHE_2CycleLate 

2 cycle of latency.

kL2CACHE_3CycleLate 

3 cycle of latency.

kL2CACHE_4CycleLate 

4 cycle of latency.

kL2CACHE_5CycleLate 

5 cycle of latency.

kL2CACHE_6CycleLate 

6 cycle of latency.

kL2CACHE_7CycleLate 

7 cycle of latency.

kL2CACHE_8CycleLate 

8 cycle of latency.

Function Documentation

void L1CACHE_InvalidateICacheByRange ( uint32_t  address,
uint32_t  size_byte 
)
Parameters
addressThe start address of the memory to be invalidated.
size_byteThe memory size.
Note
The start address and size_byte should be 32-byte(FSL_FEATURE_L1ICACHE_LINESIZE_BYTE) aligned. The startAddr here will be forced to align to L1 I-cache line size if startAddr is not aligned. For the size_byte, application should make sure the alignment or make sure the right operation order if the size_byte is not aligned.
static void L1CACHE_InvalidateDCacheByRange ( uint32_t  address,
uint32_t  size_byte 
)
inlinestatic
Parameters
addressThe start address of the memory to be invalidated.
size_byteThe memory size.
Note
The start address and size_byte should be 32-byte(FSL_FEATURE_L1DCACHE_LINESIZE_BYTE) aligned. The startAddr here will be forced to align to L1 D-cache line size if startAddr is not aligned. For the size_byte, application should make sure the alignment or make sure the right operation order if the size_byte is not aligned.
static void L1CACHE_CleanDCacheByRange ( uint32_t  address,
uint32_t  size_byte 
)
inlinestatic
Parameters
addressThe start address of the memory to be cleaned.
size_byteThe memory size.
Note
The start address and size_byte should be 32-byte(FSL_FEATURE_L1DCACHE_LINESIZE_BYTE) aligned. The startAddr here will be forced to align to L1 D-cache line size if startAddr is not aligned. For the size_byte, application should make sure the alignment or make sure the right operation order if the size_byte is not aligned.
static void L1CACHE_CleanInvalidateDCacheByRange ( uint32_t  address,
uint32_t  size_byte 
)
inlinestatic
Parameters
addressThe start address of the memory to be clean and invalidated.
size_byteThe memory size.
Note
The start address and size_byte should be 32-byte(FSL_FEATURE_L1DCACHE_LINESIZE_BYTE) aligned. The startAddr here will be forced to align to L1 D-cache line size if startAddr is not aligned. For the size_byte, application should make sure the alignment or make sure the right operation order if the size_byte is not aligned.
void L2CACHE_Init ( l2cache_config_t config)
Parameters
configPointer to configuration structure. See "l2cache_config_t".
void L2CACHE_GetDefaultConfig ( l2cache_config_t config)

This function initializes the cache controller configuration structure with default settings. The default values are:

* config->waysNum = kL2CACHE_8ways;
* config->waySize = kL2CACHE_32KbSize;
* config->repacePolicy = kL2CACHE_Roundrobin;
* config->lateConfig = NULL;
* config->istrPrefetchEnable = false;
* config->dataPrefetchEnable = false;
* config->nsLockdownEnable = false;
* config->writeAlloc = kL2CACHE_UseAwcache;
*
Parameters
configPointer to the configuration structure.
void L2CACHE_Enable ( void  )

This function enables the cache controller. Must be written using a secure access. If write with a Non-secure access will cause a DECERR response.

void L2CACHE_Disable ( void  )

This function disables the cache controller. Must be written using a secure access. If write with a Non-secure access will cause a DECERR response.

void L2CACHE_Invalidate ( void  )

This function invalidates all entries in cache.

void L2CACHE_InvalidateByRange ( uint32_t  address,
uint32_t  size_byte 
)

This function invalidates all cache lines between two physical addresses.

Parameters
addressThe start address of the memory to be invalidated.
size_byteThe memory size.
Note
The start address and size_byte should be 32-byte(FSL_FEATURE_L2CACHE_LINESIZE_BYTE) aligned. The startAddr here will be forced to align to L2 line size if startAddr is not aligned. For the size_byte, application should make sure the alignment or make sure the right operation order if the size_byte is not aligned.
void L2CACHE_Clean ( void  )

This function cleans all entries in the level 2 cache controller.

void L2CACHE_CleanByRange ( uint32_t  address,
uint32_t  size_byte 
)

This function cleans all cache lines between two physical addresses.

Parameters
addressThe start address of the memory to be cleaned.
size_byteThe memory size.
Note
The start address and size_byte should be 32-byte(FSL_FEATURE_L2CACHE_LINESIZE_BYTE) aligned. The startAddr here will be forced to align to L2 line size if startAddr is not aligned. For the size_byte, application should make sure the alignment or make sure the right operation order if the size_byte is not aligned.
void L2CACHE_CleanInvalidate ( void  )

This function cleans and invalidates all entries in the level 2 cache controller.

void L2CACHE_CleanInvalidateByRange ( uint32_t  address,
uint32_t  size_byte 
)

This function cleans and invalidates all cache lines between two physical addresses.

Parameters
addressThe start address of the memory to be cleaned and invalidated.
size_byteThe memory size.
Note
The start address and size_byte should be 32-byte(FSL_FEATURE_L2CACHE_LINESIZE_BYTE) aligned. The startAddr here will be forced to align to L2 line size if startAddr is not aligned. For the size_byte, application should make sure the alignment or make sure the right operation order if the size_byte is not aligned.
void L2CACHE_LockdownByWayEnable ( uint32_t  masterId,
uint32_t  mask,
bool  enable 
)

This function locks down the cached instruction/data by way and prevent the adresses from being allocated and prevent dara from being evicted out of the level 2 cache. But the normal cache maintenance operations that invalidate, clean or clean and validate cache contents affect the locked-down cache lines as normal.

Parameters
masterIdThe master id, range from 0 ~ 7.
maskThe ways to be enabled or disabled to lockdown. each bit in value is related to each way of the cache. for example: value: bit 0 ---— way 0.

value: bit 1 ---— way 1.

value: bit 15 ---— way 15. Note: please make sure the value setting is align with your supported ways.

Parameters
enableTrue enable the lockdown, false to disable the lockdown.
void ICACHE_InvalidateByRange ( uint32_t  address,
uint32_t  size_byte 
)

Both cortex-m7 L1 cache line and L2 PL310 cache line length is 32-byte.

Parameters
addressThe physical address.
size_bytesize of the memory to be invalidated.
Note
address and size should be aligned to cache line size 32-Byte due to the cache operation unit is one cache line. The startAddr here will be forced to align to the cache line size if startAddr is not aligned. For the size_byte, application should make sure the alignment or make sure the right operation order if the size_byte is not aligned.
void DCACHE_InvalidateByRange ( uint32_t  address,
uint32_t  size_byte 
)

Both cortex-m7 L1 cache line and L2 PL310 cache line length is 32-byte.

Parameters
addressThe physical address.
size_bytesize of the memory to be invalidated.
Note
address and size should be aligned to cache line size 32-Byte due to the cache operation unit is one cache line. The startAddr here will be forced to align to the cache line size if startAddr is not aligned. For the size_byte, application should make sure the alignment or make sure the right operation order if the size_byte is not aligned.
void DCACHE_CleanByRange ( uint32_t  address,
uint32_t  size_byte 
)

Both cortex-m7 L1 cache line and L2 PL310 cache line length is 32-byte.

Parameters
addressThe physical address.
size_bytesize of the memory to be cleaned.
Note
address and size should be aligned to cache line size 32-Byte due to the cache operation unit is one cache line. The startAddr here will be forced to align to the cache line size if startAddr is not aligned. For the size_byte, application should make sure the alignment or make sure the right operation order if the size_byte is not aligned.
void DCACHE_CleanInvalidateByRange ( uint32_t  address,
uint32_t  size_byte 
)

Both cortex-m7 L1 cache line and L2 PL310 cache line length is 32-byte.

Parameters
addressThe physical address.
size_bytesize of the memory to be cleaned and invalidated.
Note
address and size should be aligned to cache line size 32-Byte due to the cache operation unit is one cache line. The startAddr here will be forced to align to the cache line size if startAddr is not aligned. For the size_byte, application should make sure the alignment or make sure the right operation order if the size_byte is not aligned.