LMEM Cache Driver

Overview

This section describes the programming interface of the LMEM Cache peripheral driver. 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 entire cache or on a line-basis. In addition, the the driver also allows the user to "demote" the cache mode of a region within the device's memory map.

LMEM Cache Driver Definitions and Usage

The following provides definitions to the terms commonly used in the LMEM Cache peripheral driver and how to use the various functions.

The Cortex-M4 processor has a modified 32-bit Harvard bus architecture. Processor Code (PC) bus - a 32-bit address space bus with low-order addresses (0x0000_0000 through 0x1FFF_FFFF) used normally for code access.

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, some may only have a PC bus cache, while some do not have PC or PS caches at all. Refer to the desired Kinetis reference manual for cache availability.

Cache maintenance operations: 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 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.

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.

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". For example, to perform an invalidate all on the PC bus, the API is called:

LMEM_DRV_CodeCacheInvalidateAll(uint32_t instance);

To invalidate a particular line, simple call:

LMEM_DRV_CodeCacheInvalidateLine(uint32_t instance, uint32_t addr);

Note that the parameter "addr" must be supplied which indicates the physical address of the line you wish to perform the cache maintenance operation.

In addition, if the user wishes to perform cache maintenance operations on multiple lines, there are APIs available which use the naming convention "MultiLines". For example, to perform a multi-line push on the PC bus, the API is called:

LMEM_DRV_CodeCachePushMultiLines(uint32_t instance, uint32_t addr, uint32_t length);

Note that the parameter "addr" must be supplied which indicates the starting physical address of the lines you wish to perform the cache maintenance operation. In addition, the length is the number of bytes you wish to perform the cache maintenance operation. The function will determine if the length meets or exceeds 1/2 the cache size (as the cache contains 2 WAYs, half of the cache is in WAY0 and the other half in WAY1) and if so, will perform 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, will return an error. After a region is demoted, its cache mode can only be raised by a reset, which returns it to its default state. NOTE: The address/module assignment of the 16 subregions is device-specific and are detailed in the Chip Configuration section of the Kinetis reference manual. Some of the regions may not be used (non-cacheable), and some regions may not be capable of write-back.

To demote a cache region, simple call this function:

LMEM_DRV_CodeCacheDemoteRegion(uint32_t instance, lmem_cache_region_t region,
                               lmem_cache_mode_t cacheMode);

The parameter region is of type lmem_cache_region_t. This provides typedef enums for each of the 16 regions, starting with "kCacheRegion0" and ending with "kCacheRegion15". The parameter cacheMode is of type lmem_cache_mode_t. This provides typedef enums for each of the cache modes: "kCacheNonCacheable", "kCacheWriteThrough", and "kCacheWriteBack".

Cache Enable/Disable: The cache enable function enables the PC or PS bus cache as well as the write buffer. However, before enabling these, the function first performs an invalidate all. The user should call this function if they wish to enable a particular bus cache. For example, to enable the Processor Code bus cache, call the function:

LMEM_DRV_CodeCacheEnable(uint32_t instance);

To enable the Processor System bus cache, call the function:

LMEM_DRV_SystemCacheEnable(uint32_t instance);

The cache disable function disables the PC or PS bus cache as well as the write buffer. Before disabling these, the function first performs a push all. The user should call this function if they wish to disable a particular bus cache. For example, to disable the Processor Code bus cache, call the function:

LMEM_DRV_CodeCacheDisable(uint32_t instance);

To Disable the Processor System bus cache, call the function:

LMEM_DRV_SystemCacheDisable(uint32_t instance);

Variables
LMEM_Type *const	g_lmemBase [LMEM_INSTANCE_COUNT]
	Table of base addresses for the LMEM instances. More...

Processor Code Bus Cache Control Peripheral Driver
void	LMEM_DRV_CodeCacheInvalidateAll (uint32_t instance)
	Invalidates the processor code bus cache. More...
void	LMEM_DRV_CodeCachePushAll (uint32_t instance)
	Pushes all modified lines in the processor code bus cache. More...
void	LMEM_DRV_CodeCacheClearAll (uint32_t instance)
	Cears the processor code bus cache. More...
void	LMEM_DRV_CodeCacheEnable (uint32_t instance)
	Enables the processor code bus cache. More...
void	LMEM_DRV_CodeCacheDisable (uint32_t instance)
	Disables the processor code bus cache. More...
void	LMEM_DRV_CodeCacheInvalidateLine (uint32_t instance, uint32_t addr)
	Invalidates a specific line in the processor code bus cache. More...
void	LMEM_DRV_CodeCacheInvalidateMultiLines (uint32_t instance, uint32_t addr, uint32_t length)
	Invalidates multiple lines in the processor code bus cache. More...
void	LMEM_DRV_CodeCachePushLine (uint32_t instance, uint32_t addr)
	Pushes a specific modified line in the processor code bus cache. More...
void	LMEM_DRV_CodeCachePushMultiLines (uint32_t instance, uint32_t addr, uint32_t length)
	Pushes multiple modified lines in the processor code bus cache. More...
void	LMEM_DRV_CodeCacheClearLine (uint32_t instance, uint32_t addr)
	Clears a specific line in the processor code bus cache. More...
void	LMEM_DRV_CodeCacheClearMultiLines (uint32_t instance, uint32_t addr, uint32_t length)
	Clears multiple lines in the processor code bus cache. More...
lmem_cache_status_t	LMEM_DRV_CodeCacheDemoteRegion (uint32_t instance, lmem_cache_region_t region, lmem_cache_mode_t cacheMode)
	Demotes the cache mode of a region in processor code bus cache. More...

Function Documentation

void LMEM_DRV_CodeCacheInvalidateAll

(

uint32_t

instance

)

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

Parameters

instance

The instance number of the LMEM peripheral

void LMEM_DRV_CodeCachePushAll

(

uint32_t

instance

)

This function pushes all modified lines in both ways (the entire cache). Pushes a cache entry if it is valid and modified, then clears the modify bit. If 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

instance

The instance number of the LMEM peripheral

void LMEM_DRV_CodeCacheClearAll

(

uint32_t

instance

)

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

Parameters

instance

The instance number of the LMEM peripheral

void LMEM_DRV_CodeCacheEnable

(

uint32_t

instance

)

This function enables the cache. The function first invalidates the entire cache, then enables both the cache and write buffer.

Parameters

instance

The instance number of the LMEM peripheral

void LMEM_DRV_CodeCacheDisable

(

uint32_t

instance

)

This function disables the cache and write buffer.

Parameters

instance

The instance number of the LMEM peripheral

void LMEM_DRV_CodeCacheInvalidateLine	(	uint32_t	instance,
		uint32_t	addr
	)

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

Parameters

instance	The instance number of the LMEM peripheral
addr	The physical address of the cache line

void LMEM_DRV_CodeCacheInvalidateMultiLines	(	uint32_t	instance,
		uint32_t	addr,
		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 modify bits of a cache entry

Parameters

instance	The instance number of the LMEM peripheral
addr	The physical address of the cache line
length	The length in bytes of the total amount of cache lines

void LMEM_DRV_CodeCachePushLine	(	uint32_t	instance,
		uint32_t	addr
	)

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 modify bit. If entry 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

instance	The instance number of the LMEM peripheral
addr	The physical address of the cache line

void LMEM_DRV_CodeCachePushMultiLines	(	uint32_t	instance,
		uint32_t	addr,
		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 modify bit. If entry 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

instance	The instance number of the LMEM peripheral
addr	The physical address of the cache line
length	The length in bytes of the total amount of cache lines

void LMEM_DRV_CodeCacheClearLine	(	uint32_t	instance,
		uint32_t	addr
	)

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

instance	The instance number of the LMEM peripheral
addr	The physical address of the cache line

void LMEM_DRV_CodeCacheClearMultiLines	(	uint32_t	instance,
		uint32_t	addr,
		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

instance	The instance number of the LMEM peripheral
addr	The physical address of the cache line
length	The length in bytes of the total amount of cache lines

lmem_cache_status_t LMEM_DRV_CodeCacheDemoteRegion	(	uint32_t	instance,
		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. 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

instance	The instance number of the LMEM peripheral
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

kStatus_LMEM_CACHE_Success The cache clear operation was successful, or kStatus_LMEM_CACHE_Busy The cache is busy performing another operation kStatus_LMEM_CACHE_Error The requested cache mode is higher than or equal to the current cache mode

Variable Documentation

LMEM_Type* const g_lmemBase[LMEM_INSTANCE_COUNT]