diff options
Diffstat (limited to 'bsps/arm/altera-cyclone-v/include/bsp/alt_cache.h')
| -rw-r--r-- | bsps/arm/altera-cyclone-v/include/bsp/alt_cache.h | 964 |
1 files changed, 964 insertions, 0 deletions
diff --git a/bsps/arm/altera-cyclone-v/include/bsp/alt_cache.h b/bsps/arm/altera-cyclone-v/include/bsp/alt_cache.h new file mode 100644 index 0000000000..8d088ab744 --- /dev/null +++ b/bsps/arm/altera-cyclone-v/include/bsp/alt_cache.h @@ -0,0 +1,964 @@ +/****************************************************************************** + * + * 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__ */ |