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