| Kinetis SDK v.2.0 API Reference Manual Rev. 0 Freescale Semiconductor, Inc.

- Main Page
- Related Pages
- API Reference

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Files | Macros | Enumerations
LMEM: Local Memory Controller Cache Control Driver

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