/****************************************************************************** | |
* | |
* Copyright 2013 Altera Corporation. All Rights Reserved. | |
* | |
* Redistribution and use in source and binary forms, with or without | |
* modification, are permitted provided that the following conditions are met: | |
* | |
* 1. Redistributions of source code must retain the above copyright notice, | |
* this list of conditions and the following disclaimer. | |
* | |
* 2. Redistributions in binary form must reproduce the above copyright notice, | |
* this list of conditions and the following disclaimer in the documentation | |
* and/or other materials provided with the distribution. | |
* | |
* 3. The name of the author may not be used to endorse or promote products | |
* derived from this software without specific prior written permission. | |
* | |
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER "AS IS" AND ANY EXPRESS OR | |
* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF | |
* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE DISCLAIMED. IN NO | |
* EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, | |
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT | |
* OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS | |
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN | |
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING | |
* IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY | |
* OF SUCH DAMAGE. | |
* | |
******************************************************************************/ | |
#ifndef __ALT_CACHE_H__ | |
#define __ALT_CACHE_H__ | |
#include "hwlib.h" | |
#ifdef __cplusplus | |
extern "C" | |
{ | |
#endif | |
/*! | |
* \addtogroup CACHE_MGR Cache Management API | |
* | |
* This module defines the cache management API for enabling and disabling L1 | |
* data cache, L1 instruction cache, L1 dynamic branch prediction caches, L1 | |
* TLB cache, and L2 cache in the SoC. As well, many it allows users to perform | |
* cache maintenance operations on these caches. This includes the following | |
* operations: | |
* * Invalidate: Marks the cache line as being invalid, freeing up the space | |
* to cache other data. All APIs which enable caches invalidates the memory | |
* before being enabling the cache. | |
* * Clean: If the cache line is dirty, it synchronizes the cache line data | |
* with the upper level memory system and marks that line as clean. All APIs | |
* which disable caches cleans the memory before disabling the cache. | |
* * Purge: A term used in this API as a short form for clean and invalidate. | |
* This operation cleans and invalidates a cache line in that order, as a | |
* single command to the cache controller. | |
* | |
* The following reference materials were used in the design of this API: | |
* * ARM® Architecture Reference Manual, ARMv7-A and ARMv7-R edition | |
* * Cortex™-A9 Technical Reference Manual | |
* * Cortex™-A9 MPCore Technical Reference Manual | |
* * CoreLink™ Level 2 Cache Controller L2C-310 Technical Reference | |
* Manual | |
* | |
* @{ | |
*/ | |
/*! | |
* \addtogroup CACHE_SYS System Level Cache Management API | |
* | |
* 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. | |
* | |
* @{ | |
*/ | |
/*! | |
* 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. | |
*/ | |
#ifndef ALT_CACHE_SUPPORT_NON_FLAT_VIRTUAL_MEMORY | |
#define ALT_CACHE_SUPPORT_NON_FLAT_VIRTUAL_MEMORY (0) | |
#endif | |
/*! | |
* This is the system wide cache line size, given in bytes. | |
*/ | |
#define ALT_CACHE_LINE_SIZE 32 | |
/*! | |
* 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. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_system_enable(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. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_system_disable(void); | |
/*! | |
* 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 | |
* \b ALT_CACHE_LINE_SIZE macro. | |
* | |
* The following pseudocode outlines the operations carried out by this | |
* function: | |
* -# L2 invalidate address(es) | |
* -# L2 cache sync | |
* -# L1 invalidate address(es) | |
* -# 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. | |
* | |
* \param vaddress | |
* The virtual address of the memory segment to be invalidated. | |
* | |
* \param length | |
* The length of the memory segment to be invalidated. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
* \retval ALT_E_BAD_ARG The memory segment is invalid. | |
* \retval ALT_E_TMO The memory operation timed out. | |
*/ | |
ALT_STATUS_CODE alt_cache_system_invalidate(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 | |
* \b ALT_CACHE_LINE_SIZE macro. | |
* | |
* The following pseudocode outlines the operations carried out by this | |
* function: | |
* -# L1 clean address(es) | |
* -# DSB instruction | |
* -# L2 clean address(es) | |
* -# 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. | |
* | |
* \param vaddress | |
* The virtual address of the memory segment to be cleaned. | |
* | |
* \param length | |
* The length of the memory segment to be cleaned. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
* \retval ALT_E_BAD_ARG The memory segment is invalid. | |
* \retval ALT_E_TMO The memory operation timed out. | |
*/ | |
ALT_STATUS_CODE alt_cache_system_clean(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 | |
* \b ALT_CACHE_LINE_SIZE macro. | |
* | |
* The following pseudocode outlines the operations carried out by this | |
* function: | |
* -# L1 clean address(es) | |
* -# DSB instruction | |
* -# L2 clean and invalidate address(es) | |
* -# L2 cache sync | |
* -# L1 invalidate address(es) | |
* -# 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. | |
* | |
* \param vaddress | |
* The virtual address of the memory segment to be purged. | |
* | |
* \param length | |
* The length of the memory segment to be purged. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
* \retval ALT_E_BAD_ARG The memory segment is invalid. | |
* \retval ALT_E_TMO The memory operation timed out. | |
*/ | |
ALT_STATUS_CODE alt_cache_system_purge(void * vaddress, size_t length); | |
/*! | |
* @} | |
*/ | |
/*! | |
* \addtogroup CACHE_L1 L1 Cache Management API | |
* | |
* This API group provides functions to interact with various components of the | |
* L1 cache on the SoCFPGA. This includes the following cache components: | |
* * Instruction Cache | |
* * Data Cache | |
* * Parity error detection | |
* * Dynamic branch prediction | |
* * Data prefetching | |
* | |
* The API within this group only affects the L1 cache on the current CPU. To | |
* interact the L1 cache on another CPU, the API must be called from that other | |
* CPU. | |
* | |
* With respect to bring-up, the L1 and L2 cache controller setups are fully | |
* independent. The L2 can be setup at any time, before or after the L1 is setup. | |
* \internal | |
* Source: Cortex-A9 MPCore TRM, section 5.3.4 "Multiprocessor bring-up". | |
* \endinternal | |
* | |
* @{ | |
*/ | |
/*! | |
* Enables all L1 caches and features on the current CPU core. This includes | |
* the instruction cache, data cache, parity error detection, branch target | |
* address cache, global history buffer, and data prefetching. All necessary | |
* maintenance tasks will be taken care of. | |
* | |
* This function should not be mixed with other L1 cache related functions | |
* which enable or disable caches individually. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l1_enable_all(void); | |
/*! | |
* Disables all L1 caches and features on the current CPU core. This includes | |
* the instruction cache, data cache, parity error detection, branch target | |
* address cache, global history buffer, and data prefetching. All necessary | |
* maintenance tasks will be taken care of. | |
* | |
* This function should not be mixed with other L1 cache related functions | |
* which enable or disable caches individually. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l1_disable_all(void); | |
/*! | |
* Enables the L1 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. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l1_instruction_enable(void); | |
/*! | |
* Disables the L1 instruction cache on the current CPU core. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l1_instruction_disable(void); | |
/*! | |
* Returns \b true when the L1 instruction cache is enabled and \b false when | |
* it is disabled on the current CPU core. | |
* | |
* \retval true The L1 instruction cache is enabled. | |
* \retval false The L1 instruction cache is disabled. | |
*/ | |
bool alt_cache_l1_instruction_is_enabled(void); | |
/*! | |
* Invalidates the contents of the L1 instruction cache on the current CPU | |
* core. | |
* | |
* Normally this is done automatically as part of | |
* alt_cache_l1_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. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l1_instruction_invalidate(void); | |
/*! | |
* Enables the L1 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. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l1_data_enable(void); | |
/*! | |
* Disables the L1 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. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l1_data_disable(void); | |
/*! | |
* Returns \b true when the L1 data cache is enabled and \b false when it is | |
* disabled on the current CPU core. | |
* | |
* \retval true The L1 data cache is enabled. | |
* \retval false The L1 data cache is disabled. | |
*/ | |
bool alt_cache_l1_data_is_enabled(void); | |
/*! | |
* Invalidates the specified contents of the L1 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 | |
* \b ALT_CACHE_LINE_SIZE macro. | |
* | |
* \param vaddress | |
* The virtual address of the memory segment to be invalidated. | |
* | |
* \param length | |
* The length of the memory segment to be invalidated. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
* \retval ALT_E_BAD_ARG The memory segment is invalid. | |
*/ | |
ALT_STATUS_CODE alt_cache_l1_data_invalidate(void * vaddress, size_t length); | |
/*! | |
* Invalidates the entire contents of the L1 data cache on the current CPU | |
* core. | |
* | |
* Normally this is done automatically as part of alt_cache_l1_data_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 accesses memory from the new memory area. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l1_data_invalidate_all(void); | |
/*! | |
* Cleans the specified contents of the L1 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 | |
* \b ALT_CACHE_LINE_SIZE macro. | |
* | |
* \param vaddress | |
* The virtual address of the memory segment to be cleaned. | |
* | |
* \param length | |
* The length of the memory segment to be cleaned. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
* \retval ALT_E_BAD_ARG The memory segment is invalid. | |
*/ | |
ALT_STATUS_CODE alt_cache_l1_data_clean(void * vaddress, size_t length); | |
/*! | |
* Cleans the entire L1 data cache for the current CPU core. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l1_data_clean_all(void); | |
/*! | |
* Cleans and invalidates the specified contents of the L1 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 | |
* \b ALT_CACHE_LINE_SIZE macro. | |
* | |
* Normally this is done automatically as part of alt_cache_l1_data_disable(), | |
* but in certain circumstances it may be necessary to purged it manually. | |
* An example of this situation is when the address space is remapped and the | |
* processor accesses memory from the new memory area. | |
* | |
* \param vaddress | |
* The virtual address of the memory segment to be purged. | |
* | |
* \param length | |
* The length of the memory segment to be purged. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
* \retval ALT_E_BAD_ARG The memory segment is invalid. | |
*/ | |
ALT_STATUS_CODE alt_cache_l1_data_purge(void * vaddress, size_t length); | |
/*! | |
* Cleans and invalidates the entire L1 data cache for the current CPU core. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l1_data_purge_all(void); | |
/*! | |
* Enables the parity error detection feature in the L1 caches on the current | |
* CPU core. | |
* | |
* Ideally parity should be enabled before any L1 caches are enabled. If the | |
* instruction, data, and / or dynamic branch predictor caches are already | |
* enabled, they will first be cleaned (if needed) and disabled before parity | |
* is enabled in hardware. Afterwards, the affected caches will be invalidated | |
* and enabled. | |
* | |
* Parity and TLB interaction deserves special attention. The TLB is considered | |
* to be a L1 cache but is enabled when the MMU, which is grouped in another | |
* API, is enabled. Due to the system-wide influence of the MMU, it cannot be | |
* disabled and enabled with impunity as the other L1 caches, which are | |
* designed to operate as transparently as possible. Thus parity error | |
* detection must be enabled before the L1 TLB cache, and by extension the MMU, | |
* is enabled. | |
* | |
* For a parity error to be reported, the appropriate CPU PARITYFAIL interrupt | |
* for the current CPU core must be enabled using the interrupt controller API. | |
* For CPU0, ALT_INT_INTERRUPT_CPU0_PARITYFAIL is asserted if any parity error | |
* is detected while the other PARITYFAIL interrupts are for parity errors in a | |
* specific memory. Refer to the interrupt controller API for more details | |
* about programming the interrupt controller. | |
* | |
* In the event of a parity error is detected, the appropriate CPU parity | |
* interrupt will be raised. CPU parity interrupts are all edge triggered and | |
* are cleared by acknowledging them in the interrupt controller API. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l1_parity_enable(void); | |
/*! | |
* Disables parity error detection in the L1 caches. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l1_parity_disable(void); | |
/*! | |
* Returns \b true when parity error detection is enabled and \b false when it | |
* is disabled on the current CPU core. | |
* | |
* \retval true Parity error detection for L1 caches is | |
* enabled. | |
* \retval false Parity error detection for L1 caches is | |
* disabled. | |
*/ | |
bool alt_cache_l1_parity_is_enabled(void); | |
/*! | |
* Enables the dynamic branch predictor features on the current CPU core. | |
* | |
* This operation enables both the Branch Target Address Cache (BTAC) and | |
* the Global History Buffer (GHB). Affected caches are automatically | |
* invalidated before use. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l1_branch_enable(void); | |
/*! | |
* Disables the dynamic branch predictor features on the current CPU core. | |
* | |
* This operation disables both the Branch Target Address Cache (BTAC) and | |
* the Global History Buffer (GHB). | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l1_branch_disable(void); | |
/*! | |
* Returns \b true when both the dynamic predictor features are enabled and | |
* \b false when they are disabled on the current CPU core. | |
* | |
* \retval true The L1 branch predictor caches are all enabled. | |
* \retval false Some or all L1 branch predictor caches are | |
* disabled. | |
*/ | |
bool alt_cache_l1_branch_is_enabled(void); | |
/*! | |
* Invalidates the dynamic branch predictor feature caches on the current CPU | |
* core. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l1_branch_invalidate(void); | |
/*! | |
* Enables the L1 cache data prefetch feature on the current CPU core. | |
* | |
* This allows data to be prefetched into the data cache before it is to be | |
* used. For example in a loop the current iteration may want to preload the | |
* data which will be used in the next teration. This is done by using the PLD | |
* instructions. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l1_prefetch_enable(void); | |
/*! | |
* Disables the L1 cache data prefetch feature on the current CPU core. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l1_prefetch_disable(void); | |
/*! | |
* Returns \b true if the L1 cache data prefetch feature is enabled and | |
* \b false if it is disabled on the current CPU core. | |
* | |
* \retval true The L1 data cache prefetch feature is enabled. | |
* \retval false The L1 data cache prefetch feature is disabled. | |
*/ | |
bool alt_cache_l1_prefetch_is_enabled(void); | |
/*! | |
* @} | |
*/ | |
/*! | |
* \addtogroup CACHE_L2 L2 Cache Management API | |
* | |
* This API group provides functions to interact with various features of the | |
* L2 cache on the SoCFPGA. This includes the following features: | |
* * L2 cache | |
* * Parity error detection | |
* * Data prefetching | |
* * Interrupt Management | |
* | |
* \internal | |
* Additional features that may be implemented in the future: | |
* * Lockdown | |
* * Event counter | |
* \endinternal | |
* | |
* The API within this group affects the L2 cache which is visible to all CPUs | |
* on the system. | |
* | |
* With respect to bring-up, the L1 and L2 cache controller setups are fully | |
* independent. The L2 can be setup at any time, before or after the L1 is setup. | |
* \internal | |
* Source: Cortex-A9 MPCore TRM, section 5.3.4 "Multiprocessor bring-up". | |
* \endinternal | |
* | |
* @{ | |
*/ | |
/*! | |
* Initializes the L2 cache controller. | |
* | |
* \retval ALT_E_SUCCESS Successful status. | |
* \retval ALT_E_ERROR Details about error status code | |
*/ | |
ALT_STATUS_CODE alt_cache_l2_init(void); | |
/*! | |
* Uninitializes the L2 cache controller. | |
* | |
* \retval ALT_E_SUCCESS Successful status. | |
* \retval ALT_E_ERROR Details about error status code | |
*/ | |
ALT_STATUS_CODE alt_cache_l2_uninit(void); | |
/*! | |
* Enables the L2 cache features for data and instruction prefetching. | |
* | |
* Prefetching can be enabled or disabled while the L2 cache is enabled. | |
* \internal | |
* Source: Use the Prefetch Control Register. | |
* \endinternal | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l2_prefetch_enable(void); | |
/*! | |
* Disables the L2 cache features for data and instruction prefetching. | |
* | |
* Prefetching can be enabled or disabled while the L2 cache is enabled. | |
* \internal | |
* Source: Use the Prefetch Control Register. | |
* \endinternal | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l2_prefetch_disable(void); | |
/*! | |
* Returns \b true if either L2 cache data or instruction prefetch features are | |
* enabled and \b false if no prefetching features are enabled. | |
* | |
* \retval true The L2 data and instruction prefetch features | |
* are enabled. | |
* \retval false Some L2 data and instruction prefetch features | |
* are disabled. | |
*/ | |
bool alt_cache_l2_prefetch_is_enabled(void); | |
/*! | |
* Enables parity error detection in the L2 cache. | |
* | |
* Ideally parity should be enabled before the L2 cache is enabled. If the | |
* cache is already enabled, it will first be cleaned and disabled before | |
* parity is enabled in hardware. Afterwards, the cache will be invalidated and | |
* enabled. | |
* | |
* For a parity error to be reported, the ALT_CACHE_L2_INTERRUPT_PARRD and / or | |
* ALT_CACHE_L2_INTERRUPT_PARRT interrupt condition(s) must be enabled. This is | |
* done by calling alt_cache_l2_int_enable(). As well, the L2 cache interrupt | |
* must be enabled using the interrupt controller API. Refer to the interrupt | |
* controller API for more details about programming the interrupt controller. | |
* | |
* In the event of a parity error is detected, the appropriate L2 cache parity | |
* interrupt will be raised. To clear the parity interrupt(s), the appropriate | |
* L2 cache parity interrupt must be cleared by calling | |
* alt_cache_l2_int_status_clear(). | |
* | |
* For ECC support, refer to the ECC related API documentation for more | |
* information. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l2_parity_enable(void); | |
/*! | |
* Disables parity error detection in the L2 cache. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l2_parity_disable(void); | |
/*! | |
* Returns \b true when parity error detection is enabled and \b false when it | |
* is disabled. | |
* | |
* \retval true The L2 cache parity error detection feature is | |
* enabled. | |
* \retval false The L2 cache parity error detection feature is | |
* disabled. | |
*/ | |
bool alt_cache_l2_parity_is_enabled(void); | |
/*! | |
* Enables the L2 cache. | |
* | |
* If the L2 cache is already enabled, nothing is done. Otherwise the entire | |
* contents of the cache is first invalidated before being enabled. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l2_enable(void); | |
/*! | |
* Disables the L2 cache. | |
* | |
* If the L2 cache is already disabled, nothing is done. Otherwise the entire | |
* contents of the cache is first cleaned before being disabled. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l2_disable(void); | |
/*! | |
* Returns \b true when the L2 cache is enabled and \b false when it is | |
* disabled. | |
* | |
* \retval true The L2 cache is enabled. | |
* \retval false The L2 cache is disabled. | |
*/ | |
bool alt_cache_l2_is_enabled(void); | |
/*! | |
* Flushes the L2 cache controller hardware buffers. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
* \retval ALT_E_TMO The memory operation timed out. | |
*/ | |
ALT_STATUS_CODE alt_cache_l2_sync(void); | |
/*! | |
* Invalidates the specified contents of the L2 cache 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 | |
* \b ALT_CACHE_LINE_SIZE macro. | |
* | |
* \param paddress | |
* The physical address of the memory segment to be invalidated. | |
* | |
* \param length | |
* The length of the memory segment to be invalidated. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
* \retval ALT_E_BAD_ARG The memory segment is invalid. | |
* \retval ALT_E_TMO The memory operation timed out. | |
*/ | |
ALT_STATUS_CODE alt_cache_l2_invalidate(void * paddress, size_t length); | |
/*! | |
* Invalidates th entire contents of the L2 cache. | |
* | |
* Normally this is done automatically as part of alt_cache_l2_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 accesses memory from the new memory area. | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
* \retval ALT_E_TMO The memory operation timed out. | |
*/ | |
ALT_STATUS_CODE alt_cache_l2_invalidate_all(void); | |
/*! | |
* Cleans the specified contents of the L2 cache 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 | |
* \b ALT_CACHE_LINE_SIZE macro. | |
* | |
* \param paddress | |
* The physical address of the memory segment to be cleaned. | |
* | |
* \param length | |
* The length of the memory segment to be cleaned. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
* \retval ALT_E_BAD_ARG The memory segment is invalid. | |
* \retval ALT_E_TMO The memory operation timed out. | |
*/ | |
ALT_STATUS_CODE alt_cache_l2_clean(void * paddress, size_t length); | |
/*! | |
* Cleans the entire L2 cache. All L2 cache controller interrupts will be | |
* temporarily disabled while the clean operation is in progress and restored | |
* once the it is finished. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
* \retval ALT_E_TMO The memory operation timed out. | |
*/ | |
ALT_STATUS_CODE alt_cache_l2_clean_all(void); | |
/*! | |
* Cleans and invalidates the specified contents of the L2 cache 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 | |
* \b ALT_CACHE_LINE_SIZE macro. | |
* | |
* \param paddress | |
* The physical address of the memory segment to be purged. | |
* | |
* \param length | |
* The length of the memory segment to be purged. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
* \retval ALT_E_BAD_ARG The memory segment is invalid. | |
*/ | |
ALT_STATUS_CODE alt_cache_l2_purge(void * paddress, size_t length); | |
/*! | |
* Cleans and invalidates the entire L2 cache. All L2 cache controller | |
* interrupts will be temporarily disabled while the clean and invalidate | |
* operation is in progress and restored once the it is finished. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
* \retval ALT_E_TMO The memory operation timed out. | |
*/ | |
ALT_STATUS_CODE alt_cache_l2_purge_all(void); | |
/*! | |
* This type definition enumerates all the interrupt conditions that can be | |
* generated by the L2 cache controller as register mask values. | |
*/ | |
enum ALT_CACHE_L2_INTERRUPT_e | |
{ | |
/*! Decode error received on the master ports from L3. */ | |
ALT_CACHE_L2_INTERRUPT_DECERR = 1 << 8, | |
/*! Slave error received on the master ports from L3. */ | |
ALT_CACHE_L2_INTERRUPT_SLVERR = 1 << 7, | |
/*! Error on the L2 data RAM read. */ | |
ALT_CACHE_L2_INTERRUPT_ERRRD = 1 << 6, | |
/*! Error on the L2 tag RAM read. */ | |
ALT_CACHE_L2_INTERRUPT_ERRRT = 1 << 5, | |
/*! Error on the L2 data RAM write. */ | |
ALT_CACHE_L2_INTERRUPT_ERRWD = 1 << 4, | |
/*! Error on the L2 tag RAM write. */ | |
ALT_CACHE_L2_INTERRUPT_ERRWT = 1 << 3, | |
/*! Parity error on the L2 data RAM read. */ | |
ALT_CACHE_L2_INTERRUPT_PARRD = 1 << 2, | |
/*! Parity error on the L2 tag RAM read. */ | |
ALT_CACHE_L2_INTERRUPT_PARRT = 1 << 1, | |
/*! Event counter overflow or increment. */ | |
ALT_CACHE_L2_INTERRUPT_ECNTR = 1 << 0 | |
}; | |
typedef enum ALT_CACHE_L2_INTERRUPT_e ALT_CACHE_L2_INTERRUPT_t; | |
/*! | |
* Enables the L2 cache controller interrupts for the specified set of | |
* condition(s). | |
* | |
* \param interrupt | |
* A register mask of the selected L2 cache controller | |
* interrupting conditions. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l2_int_enable(uint32_t interrupt); | |
/*! | |
* Disables the L2 cache controller interrupts for the specified set of | |
* condition(s). | |
* | |
* \param interrupt | |
* A register mask of the selected L2 cache controller | |
* interrupting conditions. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l2_int_disable(uint32_t interrupt); | |
/*! | |
* Gets the condition(s) causing the L2 cache controller to interrupt as a | |
* register mask. | |
* | |
* \returns A register mask of the currently asserted and enabled | |
* conditions resulting in an interrupt being generated. | |
*/ | |
uint32_t alt_cache_l2_int_status_get(void); | |
/*! | |
* Clears the specified conditon(s) causing the L2 cache controller to | |
* interrupt as a mask. Condition(s) specified which are not causing an | |
* interrupt or condition(s) specified which are not enabled are ignored. | |
* | |
* \param interrupt | |
* A register mask of the selected L2 cache controller | |
* interrupting conditions. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_cache_l2_int_status_clear(uint32_t interrupt); | |
/*! | |
* @} | |
*/ | |
/*! | |
* @} | |
*/ | |
#ifdef __cplusplus | |
} | |
#endif | |
#endif /* __ALT_CACHE_H__ */ |