System Level 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.