Overview

The KSDK provides a peripheral driver for the Local Memory Controller Cache Controller module of Kinetis devices.

Descriptions

The LMEM Cache peripheral driver allows the user to enable/disable the cache and to perform cache maintenance operations such as invalidate, push, and clear. These maintenance operations may be performed on the Processor Code (PC) bus or Both Processor Code (PC) and Processor System (PS) bus.

The Kinetis devices contain a Processor Code (PC) bus and a Processor System (PS) bus: The Processor Code (PC) bus - a 32-bit address space bus with low-order addresses (0x0000_0000 through 0x1FFF_FFFF) used normally for code access. The Processor System (PS) bus - a 32-bit address space bus with high-order addresses (0x2000_0000 through 0xFFFF_FFFF) used normally for data accesses.

Some Kinetic MCU devices have caches available for the PC bus and PS bus, others may only have a PC bus cache, while some do not have PC or PS caches at all. See the appropriate Kinetis reference manual for cache availability.

Cache maintenance operations:

command	description
Invalidate	Unconditionally clear valid and modify bits of a cache entry.
Push	Push a cache entry if it is valid and modified, then clear the modify bit. If entry is not valid or not modified, leave as is. A cache push is synonymous with a cache flush.
Clear	Push a cache entry if it is valid and modified, then clear the valid and modify bits. If entry is not valid or not modified, clear the valid bit.

The above cache maintenance operations may be performed on the entire cache or on a line-basis. The peripheral driver API names distinguish between the two using the terms "All" or Line".

Function groups

Local Memory Processor Code Bus Cache Control

The invalidate command can be performed on the entire cache, one line and multiple lines by calling LMEM_CodeCacheInvalidateAll(), LMEM_CodeCacheInvalidateLine(), and LMEM_CodeCacheInvalidateMultiLines().

The push command can be performed on the entire cache, one line and multiple lines by calling LMEM_CodeCachePushAll(), LMEM_CodeCachePushLine(), and LMEM_CodeCachePushMultiLines().

The clear command can be performed on the entire cache, one line and multiple lines by calling LMEM_CodeCacheClearAll(), LMEM_CodeCacheClearLine(), and LMEM_CodeCacheClearMultiLines().

Note that the parameter "address" must be supplied which indicates the physical address of the line you wish to perform the one line cache maintenance operation. In addition, the length the number of bytes should be supplied for multiple lines operation. The function determines if the length meets or exceeds 1/2 the cache size because the cache contains 2 WAYs, half of the cache is in WAY0 and the other half in WAY1 and if so, performs a cache maintenance "all" operation which is faster than performing the cache maintenance on a line-basis.

Cache Demotion: Cache region demotion - Demoting the cache mode reduces the cache function applied to a memory region from write-back to write-through to non-cacheable. The cache region demote function checks to see if the requested cache mode is higher than or equal to the current cache mode, and if so, returns an error. After a region is demoted, its cache mode can only be raised by a reset, which returns it to its default state. To demote a cache region, call the LMEM_CodeCacheDemoteRegion().

Note that the address region assignment of the 16 subregions is device-specific and is detailed in the Chip Configuration section of the SoC Kinetis reference manual. The LMEM provides typedef enums for each of the 16 regions, starting with "kLMEM_CacheRegion0" and ending with "kLMEM_CacheRegion15". The parameter cacheMode is of type lmem_cache_mode_t. This provides typedef enums for each of the cache modes, such as "kLMEM_CacheNonCacheable", "kLMEM_CacheWriteThrough", and "kLMEM_CacheWriteBack".

Cache Enable and Disable: The cache enable function enables the PC bus cache and the write buffer. However, before enabling these, the function first performs an invalidate all. The user should call LMEM_EnableCodeCache() to enable a particular bus cache.

Local Memory Processor System Bus Cache Control

The invalidate command can be performed on the entire cache, one line and multiple lines by calling LMEM_SystemCacheInvalidateAll(), LMEM_SystemCacheInvalidateLine(), and LMEM_SystemCacheInvalidateMultiLines().

The push command can be performed on the entire cache, one line and multiple lines by calling LMEM_SystemCachePushAll(), LMEM_SystemCachePushLine(), and LMEM_SystemCachePushMultiLines().

The clear command can be performed on the entire cache, one line and multiple lines by calling LMEM_SystemCacheClearAll(), LMEM_SystemCacheClearLine(), and LMEM_SystemCacheClearMultiLines().

Note that the parameter "address" must be supplied, which indicates the physical address of the line you wish to perform the one line cache maintenance operation. In addition, the length the number of bytes should be supplied for multiple lines operation. The function determines if the length meets or exceeds 1/2 the cache size because the cache contains 2 WAYs, half of the cache is in WAY0 and the other half in WAY1 and if so, performs a cache maintenance "all" operation which is faster than performing the cache maintenance on a line-basis.

Cache Demotion: Cache region demotion - Demoting the cache mode reduces the cache function applied to a memory region from write-back to write-through to non-cacheable. The cache region demote function checks to see if the requested cache mode is higher than or equal to the current cache mode, and if so, returns an error. After a region is demoted, its cache mode can only be raised by a reset, which returns it to its default state. To demote a cache region, call the LMEM_SystemCacheDemoteRegion().

Note that the address region assignment of the 16 subregions is device-specific and is detailed in the Chip Configuration section of the Kinetis SoC reference manual. The LMEM provides typedef enums for each of the 16 regions, starting with "kLMEM_CacheRegion0" and ending with "kLMEM_CacheRegion15". The parameter cacheMode is of type lmem_cache_mode_t. This provides typedef enums for each of the cache modes, such as "kLMEM_CacheNonCacheable", "kLMEM_CacheWriteThrough", and "kLMEM_CacheWriteBack".

Cache Enable and Disable: The cache enable function enables the PS bus cache and the write buffer. However, before enabling these, the function first performs an invalidate all. The user should call LMEM_EnableSystemCache() to enable a particular bus cache.

Files
file	fsl_lmem_cache.h

Macros
#define	LMEM_CACHE_LINE_SIZE (0x10U)
	Cache line is 16-bytes. More...

#define	LMEM_CACHE_SIZE_ONEWAY (4096U)
	Cache size is 4K-bytes one way. More...

Enumerations
enum	lmem_cache_mode_t { kLMEM_NonCacheable = 0x0U, kLMEM_CacheWriteThrough = 0x2U, kLMEM_CacheWriteBack = 0x3U }
	LMEM cache mode options. More...

enum	lmem_cache_region_t { kLMEM_CacheRegion15 = 0U, kLMEM_CacheRegion14, kLMEM_CacheRegion13, kLMEM_CacheRegion12, kLMEM_CacheRegion11, kLMEM_CacheRegion10, kLMEM_CacheRegion9, kLMEM_CacheRegion8, kLMEM_CacheRegion7, kLMEM_CacheRegion6, kLMEM_CacheRegion5, kLMEM_CacheRegion4, kLMEM_CacheRegion3, kLMEM_CacheRegion2, kLMEM_CacheRegion1, kLMEM_CacheRegion0 }
	LMEM cache regions. More...

enum	lmem_cache_line_command_t { kLMEM_CacheLineSearchReadOrWrite = 0U, kLMEM_CacheLineInvalidate, kLMEM_CacheLinePush, kLMEM_CacheLineClear }
	LMEM cache line command. More...

Driver version
#define	FSL_LMEM_DRIVER_VERSION (MAKE_VERSION(2, 0, 0))
	LMEM controller driver version 2.0.0. More...

Local Memory Processor Code Bus Cache Control
void	LMEM_EnableCodeCache (LMEM_Type *base, bool enable)
	Enables/disables the processor code bus cache. More...

void	LMEM_CodeCacheInvalidateAll (LMEM_Type *base)
	Invalidates the processor code bus cache. More...

void	LMEM_CodeCachePushAll (LMEM_Type *base)
	Pushes all modified lines in the processor code bus cache. More...

void	LMEM_CodeCacheClearAll (LMEM_Type *base)
	Clears the processor code bus cache. More...

void	LMEM_CodeCacheInvalidateLine (LMEM_Type *base, uint32_t address)
	Invalidates a specific line in the processor code bus cache. More...

void	LMEM_CodeCacheInvalidateMultiLines (LMEM_Type *base, uint32_t address, uint32_t length)
	Invalidates multiple lines in the processor code bus cache. More...

void	LMEM_CodeCachePushLine (LMEM_Type *base, uint32_t address)
	Pushes a specific modified line in the processor code bus cache. More...

void	LMEM_CodeCachePushMultiLines (LMEM_Type *base, uint32_t address, uint32_t length)
	Pushes multiple modified lines in the processor code bus cache. More...

void	LMEM_CodeCacheClearLine (LMEM_Type *base, uint32_t address)
	Clears a specific line in the processor code bus cache. More...

void	LMEM_CodeCacheClearMultiLines (LMEM_Type *base, uint32_t address, uint32_t length)
	Clears multiple lines in the processor code bus cache. More...

status_t	LMEM_CodeCacheDemoteRegion (LMEM_Type *base, lmem_cache_region_t region, lmem_cache_mode_t cacheMode)
	Demotes the cache mode of a region in processor code bus cache. More...

Macro Definition Documentation

#define FSL_LMEM_DRIVER_VERSION (MAKE_VERSION(2, 0, 0))

#define LMEM_CACHE_LINE_SIZE (0x10U)

#define LMEM_CACHE_SIZE_ONEWAY (4096U)

Enumeration Type Documentation

enum lmem_cache_mode_t

Enumerator
kLMEM_NonCacheable	CACHE mode: non-cacheable.
kLMEM_CacheWriteThrough	CACHE mode: write-through.
kLMEM_CacheWriteBack	CACHE mode: write-back.

enum lmem_cache_region_t

Enumerator
kLMEM_CacheRegion15	Cache Region 15.
kLMEM_CacheRegion14	Cache Region 14.
kLMEM_CacheRegion13	Cache Region 13.
kLMEM_CacheRegion12	Cache Region 12.
kLMEM_CacheRegion11	Cache Region 11.
kLMEM_CacheRegion10	Cache Region 10.
kLMEM_CacheRegion9	Cache Region 9.
kLMEM_CacheRegion8	Cache Region 8.
kLMEM_CacheRegion7	Cache Region 7.
kLMEM_CacheRegion6	Cache Region 6.
kLMEM_CacheRegion5	Cache Region 5.
kLMEM_CacheRegion4	Cache Region 4.
kLMEM_CacheRegion3	Cache Region 3.
kLMEM_CacheRegion2	Cache Region 2.
kLMEM_CacheRegion1	Cache Region 1.
kLMEM_CacheRegion0	Cache Region 0.

enum lmem_cache_line_command_t

Enumerator
kLMEM_CacheLineSearchReadOrWrite	Cache line search and read or write.
kLMEM_CacheLineInvalidate	Cache line invalidate.
kLMEM_CacheLinePush	Cache line push.
kLMEM_CacheLineClear	Cache line clear.

Function Documentation

void LMEM_EnableCodeCache	(	LMEM_Type *	base,
		bool	enable
	)

This function enables/disables the cache. The function first invalidates the entire cache and then enables/disable both the cache and write buffers.

Parameters

base	LMEM peripheral base address.
enable	The enable or disable flag. true - enable the code cache. false - disable the code cache.

void LMEM_CodeCacheInvalidateAll ( LMEM_Type * base )

This function invalidates the cache both ways, which means that it unconditionally clears valid bits and modifies bits of a cache entry.

Parameters

base	LMEM peripheral base address.

void LMEM_CodeCachePushAll ( LMEM_Type * base )

This function pushes all modified lines in both ways in the entire cache. It pushes a cache entry if it is valid and modified and clears the modified bit. If the entry is not valid or not modified, leave as is. This action does not clear the valid bit. A cache push is synonymous with a cache flush.

Parameters

base	LMEM peripheral base address.

void LMEM_CodeCacheClearAll ( LMEM_Type * base )

This function clears the entire cache and pushes (flushes) and invalidates the operation. Clear - Pushes a cache entry if it is valid and modified, then clears the valid and modified bits. If the entry is not valid or not modified, clear the valid bit.

Parameters

base	LMEM peripheral base address.

void LMEM_CodeCacheInvalidateLine	(	LMEM_Type *	base,
		uint32_t	address
	)

This function invalidates a specific line in the cache based on the physical address passed in by the user. Invalidate - Unconditionally clears valid and modified bits of a cache entry.

Parameters

base	LMEM peripheral base address.
address	The physical address of the cache line. Should be 16-byte aligned address. If not, it is changed to the 16-byte aligned memory address.

void LMEM_CodeCacheInvalidateMultiLines	(	LMEM_Type *	base,
		uint32_t	address,
		uint32_t	length
	)

This function invalidates multiple lines in the cache based on the physical address and length in bytes passed in by the user. If the function detects that the length meets or exceeds half the cache. Then the function performs an entire cache invalidate function, which is more efficient than invalidating the cache line-by-line. The need to check half the total amount of cache is due to the fact that the cache consists of two ways and that line commands based on the physical address searches both ways. Invalidate - Unconditionally clear valid and modified bits of a cache entry.

Parameters

base	LMEM peripheral base address.
address	The physical address of the cache line. Should be 16-byte aligned address. If not, it is changed to the 16-byte aligned memory address.
length	The length in bytes of the total amount of cache lines.

void LMEM_CodeCachePushLine	(	LMEM_Type *	base,
		uint32_t	address
	)

This function pushes a specific modified line based on the physical address passed in by the user. Push - Push a cache entry if it is valid and modified, then clear the modified bit. If the entry is not valid or not modified, leave as is. This action does not clear the valid bit. A cache push is synonymous with a cache flush.

Parameters

base	LMEM peripheral base address.
address	The physical address of the cache line. Should be 16-byte aligned address. If not, it is changed to the 16-byte aligned memory address.

void LMEM_CodeCachePushMultiLines	(	LMEM_Type *	base,
		uint32_t	address,
		uint32_t	length
	)

This function pushes multiple modified lines in the cache based on the physical address and length in bytes passed in by the user. If the function detects that the length meets or exceeds half of the cache, the function performs an cache push function, which is more efficient than pushing the modified lines in the cache line-by-line. The need to check half the total amount of cache is due to the fact that the cache consists of two ways and that line commands based on the physical address searches both ways. Push - Push a cache entry if it is valid and modified, then clear the modified bit. If the entry is not valid or not modified, leave as is. This action does not clear the valid bit. A cache push is synonymous with a cache flush.

Parameters

base	LMEM peripheral base address.
address	The physical address of the cache line. Should be 16-byte aligned address. If not, it is changed to the 16-byte aligned memory address.
length	The length in bytes of the total amount of cache lines.

void LMEM_CodeCacheClearLine	(	LMEM_Type *	base,
		uint32_t	address
	)

This function clears a specific line based on the physical address passed in by the user. Clear - Push a cache entry if it is valid and modified, then clear the valid and modify bits. If entry not valid or not modified, clear the valid bit.

Parameters

base	LMEM peripheral base address.
address	The physical address of the cache line. Should be 16-byte aligned address. If not, it is changed to the 16-byte aligned memory address.

void LMEM_CodeCacheClearMultiLines	(	LMEM_Type *	base,
		uint32_t	address,
		uint32_t	length
	)

This function clears multiple lines in the cache based on the physical address and length in bytes passed in by the user. If the function detects that the length meets or exceeds half the total amount of cache, the function performs a cache clear function which is more efficient than clearing the lines in the cache line-by-line. The need to check half the total amount of cache is due to the fact that the cache consists of two ways and that line commands based on the physical address searches both ways. Clear - Push a cache entry if it is valid and modified, then clear the valid and modify bits. If entry not valid or not modified, clear the valid bit.

Parameters

base	LMEM peripheral base address.
address	The physical address of the cache line. Should be 16-byte aligned address. If not, it is changed to the 16-byte aligned memory address.
length	The length in bytes of the total amount of cache lines.

status_t LMEM_CodeCacheDemoteRegion	(	LMEM_Type *	base,
		lmem_cache_region_t	region,
		lmem_cache_mode_t	cacheMode
	)

This function allows the user to demote the cache mode of a region within the device's memory map. Demoting the cache mode reduces the cache function applied to a memory region from write-back to write-through to non-cacheable. The function checks to see if the requested cache mode is higher than or equal to the current cache mode, and if so, returns an error. After a region is demoted, its cache mode can only be raised by a reset, which returns it to its default state which is the highest cache configure for each region. To maintain cache coherency, changes to the cache mode should be completed while the address space being changed is not being accessed or the cache is disabled. Before a cache mode change, this function completes a cache clear all command to push and invalidate any cache entries that may have changed.

Parameters

base	LMEM peripheral base address.
region	The desired region to demote of type lmem_cache_region_t.
cacheMode	The new, demoted cache mode of type lmem_cache_mode_t.

Returns: The execution result. kStatus_Success The cache demote operation is successful. kStatus_Fail The cache demote operation is failure.

Overview

Descriptions

Function groups

Local Memory Processor Code Bus Cache Control

Local Memory Processor System Bus Cache Control

Files

Macros

Enumerations

Driver version

Local Memory Processor Code Bus Cache Control

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation