Hardware Libraries  20.1
Stratix 10 SoC Hardware Manager
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
CPU Cache Management API

Description

This API group provides functions to interact with various components of the cache on the SoCFPGA. This includes the following cache components:

Functions

ALT_STATUS_CODE alt_cache_cpu_enable_all (void)
 
ALT_STATUS_CODE alt_cache_cpu_disable_all (void)
 
ALT_STATUS_CODE alt_cache_cpu_instruction_enable (void)
 
ALT_STATUS_CODE alt_cache_cpu_instruction_disable (void)
 
bool alt_cache_cpu_instruction_is_enabled (void)
 
ALT_STATUS_CODE alt_cache_cpu_instruction_invalidate (void)
 
ALT_STATUS_CODE alt_cache_cpu_data_enable (void)
 
ALT_STATUS_CODE alt_cache_cpu_data_disable (void)
 
bool alt_cache_cpu_data_is_enabled (void)
 
ALT_STATUS_CODE alt_cache_cpu_data_invalidate (void *va, size_t length)
 
ALT_STATUS_CODE alt_cache_cpu_data_clean (void *va, size_t length)
 
ALT_STATUS_CODE alt_cache_cpu_data_purge (void *va, size_t length)
 

Function Documentation

ALT_STATUS_CODE alt_cache_cpu_enable_all ( void  )

Enables all caches and features on the current CPU core. This includes the instruction cache and data cache. All necessary maintenance tasks are taken care of.

The MMU must be enabled before calling this API.

Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_STATUS_CODE alt_cache_cpu_disable_all ( void  )

Disables all caches and features on the current CPU core. This includes the instruction cache and data cache. All necessary maintenance tasks are taken care of.

Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_STATUS_CODE alt_cache_cpu_instruction_enable ( void  )

Enables the instruction cache on the current CPU core. If the cache is already enabled, nothing is done. Otherwise the instruction cache is first invalidated before being enabled.

Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_STATUS_CODE alt_cache_cpu_instruction_disable ( void  )

Disables the instruction cache on the current CPU core.

Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
bool alt_cache_cpu_instruction_is_enabled ( void  )

Returns true when the instruction cache is enabled and false when it is disabled on the current CPU core.

Return values
trueThe L1 instruction cache is enabled.
falseThe L1 instruction cache is disabled.
ALT_STATUS_CODE alt_cache_cpu_instruction_invalidate ( void  )

Invalidates the contents of the instruction cache on the current CPU core.

Normally this is done automatically as part of alt_cache_cpu_instruction_enable(), but in certain circumstances it may be necessary to invalidate it manually. An example of this situation is when the address space is remapped and the processor executes instructions from the new memory area.

Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_STATUS_CODE alt_cache_cpu_data_enable ( void  )

Enables the data cache on the current CPU core.

If the cache is already enabled nothing is done. Otherwise the data cache is first invalidated before being enabled.

The MMU must be enabled before calling this API.

Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_STATUS_CODE alt_cache_cpu_data_disable ( void  )

Disables the data cache on the current CPU core.

If the cache is already disabled nothing is done. Otherwise the data cache is first cleaned before being disabled.

Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
bool alt_cache_cpu_data_is_enabled ( void  )

Returns true when the data cache is enabled and false when it is disabled on the current CPU core.

Return values
trueThe L1 data cache is enabled.
falseThe L1 data cache is disabled.
ALT_STATUS_CODE alt_cache_cpu_data_invalidate ( void *  va,
size_t  length 
)

Invalidates the specified contents of the data cache on 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.

For the most part, calling this API on memory backed by SDRAM and OCRAM is unnecessary because the CCU (Cache Coherency Unit), which is part of the interconnect, will automatically maintain cache coherency with the Cortex-A53. If memory is backed with another RAM, such as FPGA memory, calling this API is required with the default CCU setup.

Parameters
vaThe virtual address of the memory segment to be invalidated.
lengthThe length of the memory segment to be invalidated.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe memory segment is invalid.
ALT_STATUS_CODE alt_cache_cpu_data_clean ( void *  va,
size_t  length 
)

Cleans the specified contents of the data cache on 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.

For the most part, calling this API on memory backed by SDRAM and OCRAM is unnecessary because the CCU (Cache Coherency Unit), which is part of the interconnect, will automatically maintain cache coherency with the Cortex-A53. If memory is backed with another RAM, such as FPGA memory, calling this API is required with the default CCU setup.

Parameters
vaThe virtual address of the memory segment to be cleaned.
lengthThe length of the memory segment to be cleaned.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe memory segment is invalid.
ALT_STATUS_CODE alt_cache_cpu_data_purge ( void *  va,
size_t  length 
)

Cleans and invalidates the specified contents of the data cache on 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.

For the most part, calling this API on memory backed by SDRAM and OCRAM is unnecessary because the CCU (Cache Coherency Unit), which is part of the interconnect, will automatically maintain cache coherency with the Cortex-A53. If memory is backed with another RAM, such as FPGA memory, calling this API is required with the default CCU setup.

Parameters
vaThe virtual address of the memory segment to be purged.
lengthThe length of the memory segment to be purged.
Return values
ALT_E_SUCCESSThe operation was successful.
ALT_E_ERRORThe operation failed.
ALT_E_BAD_ARGThe memory segment is invalid.