source: rtems/bsps/arm/altera-cyclone-v/include/bsp/alt_cache.h @ 2afb22b

/******************************************************************************
 *
 * 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__ */