RTEMS: System Level Cache Management API

| RTEMS 5.4-rc2

Loading...
Searching...
No Matches
Macros | Functions
System Level Cache Management API
Board Support Packages » ARM » Intel Cyclone V » Contributed Code » Cache Management API

## Macros
#define | ALT_CACHE_SUPPORT_NON_FLAT_VIRTUAL_MEMORY (0)
#define | ALT_CACHE_LINE_SIZE 32

## Functions
ALT_STATUS_CODE | alt_cache_system_enable (void)
ALT_STATUS_CODE | alt_cache_system_disable (void)
ALT_STATUS_CODE | alt_cache_system_invalidate (void *vaddress, size_t length)
ALT_STATUS_CODE | alt_cache_system_clean (void *vaddress, size_t length)
ALT_STATUS_CODE | alt_cache_system_purge (void *vaddress, size_t length)

## Detailed Description

This API group provides cache maintenance operations which affects multiple cache levels.

The enable and disable functions enables and disables all caches in the system respectively. For caches shared by the CPU core(s), particularly the L2 cache, once that cache is enabled or disabled it will not be invalidated or cleaned again respectively. This allows the safe system-wide enable and disable to be used in single-core and multi-core scenarios.

For cache maintenance operations, this API implements the procedures outlined in the L2C-310 Technical Reference Manual, section 3.3.10, subsection "System cache maintenance considerations". This allows for a convenient way to invalidate, clean, or clean and invalidate cache data from the L1 to L2 to L3 while avoiding any potential race conditions in mutli-core or multi-master scenarios. It assumes that the L1 and L2 cache is set in "non-exclusive" mode. This means a segment of data can reside in both the L1 and L2 simultaneously. This is the default mode for caches in the system.

The current implementation of the system cache APIs assumes that the MMU is configured with a flat memory mapping or that every virtual address matches perfectly with the physical address. This restriction may be lifted in a future release of the cache API implementation.

## Macro Definition Documentation

## ◆ ALT_CACHE_LINE_SIZE

#define ALT_CACHE_LINE_SIZE 32

This is the system wide cache line size, given in bytes.

## ◆ ALT_CACHE_SUPPORT_NON_FLAT_VIRTUAL_MEMORY

#define ALT_CACHE_SUPPORT_NON_FLAT_VIRTUAL_MEMORY (0)

Enables support for a non-flat virtual memory. A flat virtual memory is where every virtual address matches exactly to the physical address, making the virtual to physical translation trivial. Adding support for non-flat adds some overhead for the VA to PA translation and error detection.

To enable non-flat virtual memory support, defined ALT_CACHE_SUPPORT_NON_FLAT_VIRTUAL_MEMORY=1 in your Makefile when compiling HWLibs.

## Function Documentation

## ◆ alt_cache_system_clean()

ALT_STATUS_CODE alt_cache_system_clean | ( | void * | vaddress,
|  | size_t | length
| ) |  |

Cleans the specified contents of all cache levels visible to the current CPU core for the given memory segment.

The memory segment address and length specified must align to the characteristics of the cache line. This means the address and length must be multiples of the cache line size. To determine the cache line size, use the ALT_CACHE_LINE_SIZE macro.

The following pseudocode outlines the operations carried out by this function:

1. L1 clean address(es)
2. DSB instruction
3. L2 clean address(es)
4. L2 cache sync

The current implementation of the system cache APIs assumes that the MMU is configured with a flat memory mapping or that every virtual address matches perfectly with the physical address. This restriction may be lifted in a future release of the cache API implementation.

Parameters

  vaddress | The virtual address of the memory segment to be cleaned.
  length | The length of the memory segment to be cleaned.

Return values

  ALT_E_SUCCESS | The operation was successful.
  ALT_E_ERROR | The operation failed.
  ALT_E_BAD_ARG | The memory segment is invalid.
  ALT_E_TMO | The memory operation timed out.

## ◆ alt_cache_system_disable()

ALT_STATUS_CODE alt_cache_system_disable | ( | void |  | ) |

Disables all cache controllers visible to the current CPU core. Cache controllers visible to multiple CPU cores, for example the L2, will first be checked to be enabled before being disabled. All necessary cache maintenance operations will be done automatically.

Return values

  ALT_E_SUCCESS | The operation was successful.
  ALT_E_ERROR | The operation failed.

## ◆ alt_cache_system_enable()

ALT_STATUS_CODE alt_cache_system_enable | ( | void |  | ) |

Enables all caches and features which improve reliability and speed on all cache controllers visible to the current CPU core. This includes parity error detection. Cache controllers visible to multiple CPU cores, for example the L2, will first be checked to be disabled before being enabled. All necessary cache maintenance operations will be done automatically.

Return values

  ALT_E_SUCCESS | The operation was successful.
  ALT_E_ERROR | The operation failed.

## ◆ alt_cache_system_invalidate()

ALT_STATUS_CODE alt_cache_system_invalidate | ( | void * | vaddress,
|  | size_t | length
| ) |  |

Invalidates the specified contents of all cache levels visible to the current CPU core for the given memory segment.

The memory segment address and length specified must align to the characteristics of the cache line. This means the address and length must be multiples of the cache line size. To determine the cache line size, use the ALT_CACHE_LINE_SIZE macro.

The following pseudocode outlines the operations carried out by this function:

1. L2 invalidate address(es)
2. L2 cache sync
3. L1 invalidate address(es)
4. DSB instruction

The current implementation of the system cache APIs assumes that the MMU is configured with a flat memory mapping or that every virtual address matches perfectly with the physical address. This restriction may be lifted in a future release of the cache API implementation.

Parameters

  vaddress | The virtual address of the memory segment to be invalidated.
  length | The length of the memory segment to be invalidated.

Return values

  ALT_E_SUCCESS | The operation was successful.
  ALT_E_ERROR | The operation failed.
  ALT_E_BAD_ARG | The memory segment is invalid.
  ALT_E_TMO | The memory operation timed out.

## ◆ alt_cache_system_purge()

ALT_STATUS_CODE alt_cache_system_purge | ( | void * | vaddress,
|  | size_t | length
| ) |  |

Cleans and invalidates the specified contents of all cache levels visible to the current CPU core for the given memory segment.

The memory segment address and length specified must align to the characteristics of the cache line. This means the address and length must be multiples of the cache line size. To determine the cache line size, use the ALT_CACHE_LINE_SIZE macro.

The following pseudocode outlines the operations carried out by this function:

1. L1 clean address(es)
2. DSB instruction
3. L2 clean and invalidate address(es)
4. L2 cache sync
5. L1 invalidate address(es)
6. DSB instruction

The current implementation of the system cache APIs assumes that the MMU is configured with a flat memory mapping or that every virtual address matches perfectly with the physical address. This restriction may be lifted in a future release of the cache API implementation.

Parameters

  vaddress | The virtual address of the memory segment to be purged.
  length | The length of the memory segment to be purged.

Return values

  ALT_E_SUCCESS | The operation was successful.
  ALT_E_ERROR | The operation failed.
  ALT_E_BAD_ARG | The memory segment is invalid.
  ALT_E_TMO | The memory operation timed out.