include/bsp/alt_cache.h

0001 /**
0002  * @file
0003  *
0004  * @ingroup RTEMSBSPsARMCycVContrib
0005  */
0006
0007 /******************************************************************************
0008  *
0009  * Copyright 2013 Altera Corporation. All Rights Reserved.
0010  *
0011  * Redistribution and use in source and binary forms, with or without
0012  * modification, are permitted provided that the following conditions are met:
0013  *
0014  * 1. Redistributions of source code must retain the above copyright notice,
0015  * this list of conditions and the following disclaimer.
0016  *
0017  * 2. Redistributions in binary form must reproduce the above copyright notice,
0018  * this list of conditions and the following disclaimer in the documentation
0019  * and/or other materials provided with the distribution.
0020  *
0021  * 3. The name of the author may not be used to endorse or promote products
0022  * derived from this software without specific prior written permission.
0023  *
0024  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER "AS IS" AND ANY EXPRESS OR
0025  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
0026  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE DISCLAIMED. IN NO
0027  * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
0028  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
0029  * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0030  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0031  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
0032  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
0033  * OF SUCH DAMAGE.
0034  *
0035  ******************************************************************************/
0036
0037 #ifndef __ALT_CACHE_H__
0038 #define __ALT_CACHE_H__
0039
0040 #include "hwlib.h"
0041
0042 #ifdef __cplusplus
0043 extern "C"
0044 {
0045 #endif
0046
0047 /*!
0048  * \addtogroup CACHE_MGR Cache Management API
0049  *
0050  * This module defines the cache management API for enabling and disabling L1
0051  * data cache, L1 instruction cache, L1 dynamic branch prediction caches, L1
0052  * TLB cache, and L2 cache in the SoC. As well, many it allows users to perform
0053  * cache maintenance operations on these caches. This includes the following
0054  * operations:
0055  *  * Invalidate: Marks the cache line as being invalid, freeing up the space
0056  *    to cache other data. All APIs which enable caches invalidates the memory
0057  *    before being enabling the cache.
0058  *  * Clean: If the cache line is dirty, it synchronizes the cache line data
0059  *    with the upper level memory system and marks that line as clean. All APIs
0060  *    which disable caches cleans the memory before disabling the cache.
0061  *  * Purge: A term used in this API as a short form for clean and invalidate.
0062  *    This operation cleans and invalidates a cache line in that order, as a
0063  *    single command to the cache controller.
0064  *
0065  * The following reference materials were used in the design of this API:
0066  *  * ARM&reg; Architecture Reference Manual, ARMv7-A and ARMv7-R edition
0067  *  * Cortex&trade;-A9 Technical Reference Manual
0068  *  * Cortex&trade;-A9 MPCore Technical Reference Manual
0069  *  * CoreLink&trade; Level 2 Cache Controller L2C-310 Technical Reference
0070  *    Manual
0071  *
0072  * @{
0073  */
0074
0075 /*!
0076  * \addtogroup CACHE_SYS System Level Cache Management API
0077  *
0078  * This API group provides cache maintenance operations which affects multiple
0079  * cache levels.
0080  *
0081  * The enable and disable functions enables and disables all caches in the
0082  * system respectively. For caches shared by the CPU core(s), particularly the
0083  * L2 cache, once that cache is enabled or disabled it will not be invalidated
0084  * or cleaned again respectively. This allows the safe system-wide enable and
0085  * disable to be used in single-core and multi-core scenarios.
0086  *
0087  * For cache maintenance operations, this API implements the procedures
0088  * outlined in the L2C-310 Technical Reference Manual, section 3.3.10,
0089  * subsection "System cache maintenance considerations". This allows for a
0090  * convenient way to invalidate, clean, or clean and invalidate cache data from
0091  * the L1 to L2 to L3 while avoiding any potential race conditions in
0092  * mutli-core or multi-master scenarios. It assumes that the L1 and L2 cache is
0093  * set in "non-exclusive" mode. This means a segment of data can reside in both
0094  * the L1 and L2 simultaneously. This is the default mode for caches in the
0095  * system.
0096  *
0097  * The current implementation of the system cache APIs assumes that the MMU is
0098  * configured with a flat memory mapping or that every virtual address matches
0099  * perfectly with the physical address. This restriction may be lifted in a
0100  * future release of the cache API implementation.
0101  *
0102  * @{
0103  */
0104
0105 /*!
0106  * Enables support for a non-flat virtual memory. A flat virtual memory is
0107  * where every virtual address matches exactly to the physical address, making
0108  * the virtual to physical translation trivial. Adding support for non-flat
0109  * adds some overhead for the VA to PA translation and error detection.
0110  *
0111  * To enable non-flat virtual memory support, defined
0112  * ALT_CACHE_SUPPORT_NON_FLAT_VIRTUAL_MEMORY=1 in your Makefile when compiling
0113  * HWLibs.
0114  */
0115 #ifndef ALT_CACHE_SUPPORT_NON_FLAT_VIRTUAL_MEMORY
0116 #define ALT_CACHE_SUPPORT_NON_FLAT_VIRTUAL_MEMORY (0)
0117 #endif
0118
0119 /*!
0120  * This is the system wide cache line size, given in bytes.
0121  */
0122 #define ALT_CACHE_LINE_SIZE         32
0123
0124 /*!
0125  * Enables all caches and features which improve reliability and speed on all
0126  * cache controllers visible to the current CPU core. This includes parity
0127  * error detection. Cache controllers visible to multiple CPU cores, for
0128  * example the L2, will first be checked to be disabled before being enabled.
0129  * All necessary cache maintenance operations will be done automatically.
0130  *
0131  * \retval      ALT_E_SUCCESS   The operation was successful.
0132  * \retval      ALT_E_ERROR     The operation failed.
0133  */
0134 ALT_STATUS_CODE alt_cache_system_enable(void);
0135
0136 /*!
0137  * Disables all cache controllers visible to the current CPU core. Cache
0138  * controllers visible to multiple CPU cores, for example the L2, will first
0139  * be checked to be enabled before being disabled. All necessary cache
0140  * maintenance operations will be done automatically.
0141  *
0142  * \retval      ALT_E_SUCCESS   The operation was successful.
0143  * \retval      ALT_E_ERROR     The operation failed.
0144  */
0145 ALT_STATUS_CODE alt_cache_system_disable(void);
0146
0147 /*!
0148  * Invalidates the specified contents of all cache levels visible to the
0149  * current CPU core for the given memory segment.
0150  *
0151  * The memory segment address and length specified must align to the
0152  * characteristics of the cache line. This means the address and length must be
0153  * multiples of the cache line size. To determine the cache line size, use the
0154  * \b ALT_CACHE_LINE_SIZE macro.
0155  *
0156  * The following pseudocode outlines the operations carried out by this
0157  * function:
0158  *  -# L2 invalidate address(es)
0159  *  -# L2 cache sync
0160  *  -# L1 invalidate address(es)
0161  *  -# DSB instruction
0162  *
0163  * The current implementation of the system cache APIs assumes that the MMU is
0164  * configured with a flat memory mapping or that every virtual address matches
0165  * perfectly with the physical address. This restriction may be lifted in a
0166  * future release of the cache API implementation.
0167  *
0168  * \param       vaddress
0169  *              The virtual address of the memory segment to be invalidated.
0170  *
0171  * \param       length
0172  *              The length of the memory segment to be invalidated.
0173  *
0174  * \retval      ALT_E_SUCCESS   The operation was successful.
0175  * \retval      ALT_E_ERROR     The operation failed.
0176  * \retval      ALT_E_BAD_ARG   The memory segment is invalid.
0177  * \retval      ALT_E_TMO       The memory operation timed out.
0178  */
0179 ALT_STATUS_CODE alt_cache_system_invalidate(void * vaddress, size_t length);
0180
0181 /*!
0182  * Cleans the specified contents of all cache levels visible to the current
0183  * CPU core for the given memory segment.
0184  *
0185  * The memory segment address and length specified must align to the
0186  * characteristics of the cache line. This means the address and length must be
0187  * multiples of the cache line size. To determine the cache line size, use the
0188  * \b ALT_CACHE_LINE_SIZE macro.
0189  *
0190  * The following pseudocode outlines the operations carried out by this
0191  * function:
0192  *  -# L1 clean address(es)
0193  *  -# DSB instruction
0194  *  -# L2 clean address(es)
0195  *  -# L2 cache sync
0196  *
0197  * The current implementation of the system cache APIs assumes that the MMU is
0198  * configured with a flat memory mapping or that every virtual address matches
0199  * perfectly with the physical address. This restriction may be lifted in a
0200  * future release of the cache API implementation.
0201  *
0202  * \param       vaddress
0203  *              The virtual address of the memory segment to be cleaned.
0204  *
0205  * \param       length
0206  *              The length of the memory segment to be cleaned.
0207  *
0208  * \retval      ALT_E_SUCCESS   The operation was successful.
0209  * \retval      ALT_E_ERROR     The operation failed.
0210  * \retval      ALT_E_BAD_ARG   The memory segment is invalid.
0211  * \retval      ALT_E_TMO       The memory operation timed out.
0212  */
0213 ALT_STATUS_CODE alt_cache_system_clean(void * vaddress, size_t length);
0214
0215 /*!
0216  * Cleans and invalidates the specified contents of all cache levels visible
0217  * to the current CPU core for the given memory segment.
0218  *
0219  * The memory segment address and length specified must align to the
0220  * characteristics of the cache line. This means the address and length must be
0221  * multiples of the cache line size. To determine the cache line size, use the
0222  * \b ALT_CACHE_LINE_SIZE macro.
0223  *
0224  * The following pseudocode outlines the operations carried out by this
0225  * function:
0226  *  -# L1 clean address(es)
0227  *  -# DSB instruction
0228  *  -# L2 clean and invalidate address(es)
0229  *  -# L2 cache sync
0230  *  -# L1 invalidate address(es)
0231  *  -# DSB instruction
0232  *
0233  * The current implementation of the system cache APIs assumes that the MMU is
0234  * configured with a flat memory mapping or that every virtual address matches
0235  * perfectly with the physical address. This restriction may be lifted in a
0236  * future release of the cache API implementation.
0237  *
0238  * \param       vaddress
0239  *              The virtual address of the memory segment to be purged.
0240  *
0241  * \param       length
0242  *              The length of the memory segment to be purged.
0243  *
0244  * \retval      ALT_E_SUCCESS   The operation was successful.
0245  * \retval      ALT_E_ERROR     The operation failed.
0246  * \retval      ALT_E_BAD_ARG   The memory segment is invalid.
0247  * \retval      ALT_E_TMO       The memory operation timed out.
0248  */
0249 ALT_STATUS_CODE alt_cache_system_purge(void * vaddress, size_t length);
0250
0251 /*!
0252  * @}
0253  */
0254
0255 /*!
0256  * \addtogroup CACHE_L1 L1 Cache Management API
0257  *
0258  * This API group provides functions to interact with various components of the
0259  * L1 cache on the SoCFPGA. This includes the following cache components:
0260  *  * Instruction Cache
0261  *  * Data Cache
0262  *  * Parity error detection
0263  *  * Dynamic branch prediction
0264  *  * Data prefetching
0265  *
0266  * The API within this group only affects the L1 cache on the current CPU. To
0267  * interact the L1 cache on another CPU, the API must be called from that other
0268  * CPU.
0269  *
0270  * With respect to bring-up, the L1 and L2 cache controller setups are fully
0271  * independent. The L2 can be setup at any time, before or after the L1 is setup.
0272  * \internal
0273  * Source: Cortex-A9 MPCore TRM, section 5.3.4 "Multiprocessor bring-up".
0274  * \endinternal
0275  *
0276  * @{
0277  */
0278
0279 /*!
0280  * Enables all L1 caches and features on the current CPU core. This includes
0281  * the instruction cache, data cache, parity error detection, branch target
0282  * address cache, global history buffer, and data prefetching. All necessary
0283  * maintenance tasks will be taken care of.
0284  *
0285  * This function should not be mixed with other L1 cache related functions
0286  * which enable or disable caches individually.
0287  *
0288  * \retval      ALT_E_SUCCESS   The operation was successful.
0289  * \retval      ALT_E_ERROR     The operation failed.
0290  */
0291 ALT_STATUS_CODE alt_cache_l1_enable_all(void);
0292
0293 /*!
0294  * Disables all L1 caches and features on the current CPU core. This includes
0295  * the instruction cache, data cache, parity error detection, branch target
0296  * address cache, global history buffer, and data prefetching. All necessary
0297  * maintenance tasks will be taken care of.
0298  *
0299  * This function should not be mixed with other L1 cache related functions
0300  * which enable or disable caches individually.
0301  *
0302  * \retval      ALT_E_SUCCESS   The operation was successful.
0303  * \retval      ALT_E_ERROR     The operation failed.
0304  */
0305 ALT_STATUS_CODE alt_cache_l1_disable_all(void);
0306
0307 /*!
0308  * Enables the L1 instruction cache on the current CPU core. If the cache is
0309  * already enabled, nothing is done. Otherwise the instruction cache is first
0310  * invalidated before being enabled.
0311  *
0312  * \retval      ALT_E_SUCCESS   The operation was successful.
0313  * \retval      ALT_E_ERROR     The operation failed.
0314  */
0315 ALT_STATUS_CODE alt_cache_l1_instruction_enable(void);
0316
0317 /*!
0318  * Disables the L1 instruction cache on the current CPU core.
0319  *
0320  * \retval      ALT_E_SUCCESS   The operation was successful.
0321  * \retval      ALT_E_ERROR     The operation failed.
0322  */
0323 ALT_STATUS_CODE alt_cache_l1_instruction_disable(void);
0324
0325 /*!
0326  * Returns \b true when the L1 instruction cache is enabled and \b false when
0327  * it is disabled on the current CPU core.
0328  *
0329  * \retval      true            The L1 instruction cache is enabled.
0330  * \retval      false           The L1 instruction cache is disabled.
0331  */
0332 bool alt_cache_l1_instruction_is_enabled(void);
0333
0334 /*!
0335  * Invalidates the contents of the L1 instruction cache on the current CPU
0336  * core.
0337  *
0338  * Normally this is done automatically as part of
0339  * alt_cache_l1_instruction_enable(), but in certain circumstances it may be
0340  * necessary to invalidate it manually. An example of this situation is when
0341  * the address space is remapped and the processor executes instructions from
0342  * the new memory area.
0343  *
0344  * \retval      ALT_E_SUCCESS   The operation was successful.
0345  * \retval      ALT_E_ERROR     The operation failed.
0346  */
0347 ALT_STATUS_CODE alt_cache_l1_instruction_invalidate(void);
0348
0349 /*!
0350  * Enables the L1 data cache on the current CPU core.
0351  *
0352  * If the cache is already enabled nothing is done. Otherwise the data cache is
0353  * first invalidated before being enabled.
0354  *
0355  * \retval      ALT_E_SUCCESS   The operation was successful.
0356  * \retval      ALT_E_ERROR     The operation failed.
0357  */
0358 ALT_STATUS_CODE alt_cache_l1_data_enable(void);
0359
0360 /*!
0361  * Disables the L1 data cache on the current CPU core.
0362  *
0363  * If the cache is already disabled nothing is done. Otherwise the data cache
0364  * is first cleaned before being disabled.
0365  *
0366  * \retval      ALT_E_SUCCESS   The operation was successful.
0367  * \retval      ALT_E_ERROR     The operation failed.
0368  */
0369 ALT_STATUS_CODE alt_cache_l1_data_disable(void);
0370
0371 /*!
0372  * Returns \b true when the L1 data cache is enabled and \b false when it is
0373  * disabled on the current CPU core.
0374  *
0375  * \retval      true            The L1 data cache is enabled.
0376  * \retval      false           The L1 data cache is disabled.
0377  */
0378 bool alt_cache_l1_data_is_enabled(void);
0379
0380 /*!
0381  * Invalidates the specified contents of the L1 data cache on the current CPU
0382  * core for the given memory segment.
0383  *
0384  * The memory segment address and length specified must align to the
0385  * characteristics of the cache line. This means the address and length must be
0386  * multiples of the cache line size. To determine the cache line size, use the
0387  * \b ALT_CACHE_LINE_SIZE macro.
0388  *
0389  * \param       vaddress
0390  *              The virtual address of the memory segment to be invalidated.
0391  *
0392  * \param       length
0393  *              The length of the memory segment to be invalidated.
0394  *
0395  * \retval      ALT_E_SUCCESS   The operation was successful.
0396  * \retval      ALT_E_ERROR     The operation failed.
0397  * \retval      ALT_E_BAD_ARG   The memory segment is invalid.
0398  */
0399 ALT_STATUS_CODE alt_cache_l1_data_invalidate(void * vaddress, size_t length);
0400
0401 /*!
0402  * Invalidates the entire contents of the L1 data cache on the current CPU
0403  * core.
0404  *
0405  * Normally this is done automatically as part of alt_cache_l1_data_enable(),
0406  * but in certain circumstances it may be necessary to invalidate it manually.
0407  * An example of this situation is when the address space is remapped and the
0408  * processor accesses memory from the new memory area.
0409  *
0410  * \retval      ALT_E_SUCCESS   The operation was successful.
0411  * \retval      ALT_E_ERROR     The operation failed.
0412  */
0413 ALT_STATUS_CODE alt_cache_l1_data_invalidate_all(void);
0414
0415 /*!
0416  * Cleans the specified contents of the L1 data cache on the current CPU core
0417  * for the given memory segment.
0418  *
0419  * The memory segment address and length specified must align to the
0420  * characteristics of the cache line. This means the address and length must be
0421  * multiples of the cache line size. To determine the cache line size, use the
0422  * \b ALT_CACHE_LINE_SIZE macro.
0423  *
0424  * \param       vaddress
0425  *              The virtual address of the memory segment to be cleaned.
0426  *
0427  * \param       length
0428  *              The length of the memory segment to be cleaned.
0429  *
0430  * \retval      ALT_E_SUCCESS   The operation was successful.
0431  * \retval      ALT_E_ERROR     The operation failed.
0432  * \retval      ALT_E_BAD_ARG   The memory segment is invalid.
0433  */
0434 ALT_STATUS_CODE alt_cache_l1_data_clean(void * vaddress, size_t length);
0435
0436 /*!
0437  * Cleans the entire L1 data cache for the current CPU core.
0438  *
0439  * \retval      ALT_E_SUCCESS   The operation was successful.
0440  * \retval      ALT_E_ERROR     The operation failed.
0441  */
0442 ALT_STATUS_CODE alt_cache_l1_data_clean_all(void);
0443
0444 /*!
0445  * Cleans and invalidates the specified contents of the L1 data cache on the
0446  * current CPU core for the given memory segment.
0447  *
0448  * The memory segment address and length specified must align to the
0449  * characteristics of the cache line. This means the address and length must be
0450  * multiples of the cache line size. To determine the cache line size, use the
0451  * \b ALT_CACHE_LINE_SIZE macro.
0452  *
0453  * Normally this is done automatically as part of alt_cache_l1_data_disable(),
0454  * but in certain circumstances it may be necessary to purged it manually.
0455  * An example of this situation is when the address space is remapped and the
0456  * processor accesses memory from the new memory area.
0457  *
0458  * \param       vaddress
0459  *              The virtual address of the memory segment to be purged.
0460  *
0461  * \param       length
0462  *              The length of the memory segment to be purged.
0463  *
0464  * \retval      ALT_E_SUCCESS   The operation was successful.
0465  * \retval      ALT_E_ERROR     The operation failed.
0466  * \retval      ALT_E_BAD_ARG   The memory segment is invalid.
0467  */
0468 ALT_STATUS_CODE alt_cache_l1_data_purge(void * vaddress, size_t length);
0469
0470 /*!
0471  * Cleans and invalidates the entire L1 data cache for the current CPU core.
0472  *
0473  * \retval      ALT_E_SUCCESS   The operation was successful.
0474  * \retval      ALT_E_ERROR     The operation failed.
0475  */
0476 ALT_STATUS_CODE alt_cache_l1_data_purge_all(void);
0477
0478 /*!
0479  * Enables the parity error detection feature in the L1 caches on the current
0480  * CPU core.
0481  *
0482  * Ideally parity should be enabled before any L1 caches are enabled. If the
0483  * instruction, data, and / or dynamic branch predictor caches are already
0484  * enabled, they will first be cleaned (if needed) and disabled before parity
0485  * is enabled in hardware. Afterwards, the affected caches will be invalidated
0486  * and enabled.
0487  *
0488  * Parity and TLB interaction deserves special attention. The TLB is considered
0489  * to be a L1 cache but is enabled when the MMU, which is grouped in another
0490  * API, is enabled. Due to the system-wide influence of the MMU, it cannot be
0491  * disabled and enabled with impunity as the other L1 caches, which are
0492  * designed to operate as transparently as possible. Thus parity error
0493  * detection must be enabled before the L1 TLB cache, and by extension the MMU,
0494  * is enabled.
0495  *
0496  * For a parity error to be reported, the appropriate CPU PARITYFAIL interrupt
0497  * for the current CPU core must be enabled using the interrupt controller API.
0498  * For CPU0, ALT_INT_INTERRUPT_CPU0_PARITYFAIL is asserted if any parity error
0499  * is detected while the other PARITYFAIL interrupts are for parity errors in a
0500  * specific memory. Refer to the interrupt controller API for more details
0501  * about programming the interrupt controller.
0502  *
0503  * In the event of a parity error is detected, the appropriate CPU parity
0504  * interrupt will be raised. CPU parity interrupts are all edge triggered and
0505  * are cleared by acknowledging them in the interrupt controller API.
0506  *
0507  * \retval      ALT_E_SUCCESS   The operation was successful.
0508  * \retval      ALT_E_ERROR     The operation failed.
0509  */
0510 ALT_STATUS_CODE alt_cache_l1_parity_enable(void);
0511
0512 /*!
0513  * Disables parity error detection in the L1 caches.
0514  *
0515  * \retval      ALT_E_SUCCESS   The operation was successful.
0516  * \retval      ALT_E_ERROR     The operation failed.
0517  */
0518 ALT_STATUS_CODE alt_cache_l1_parity_disable(void);
0519
0520 /*!
0521  * Returns \b true when parity error detection is enabled and \b false when it
0522  * is disabled on the current CPU core.
0523  *
0524  * \retval      true            Parity error detection for L1 caches is
0525  *                              enabled.
0526  * \retval      false           Parity error detection for L1 caches is
0527  *                              disabled.
0528  */
0529 bool alt_cache_l1_parity_is_enabled(void);
0530
0531 /*!
0532  * Enables the dynamic branch predictor features on the current CPU core.
0533  *
0534  * This operation enables both the Branch Target Address Cache (BTAC) and
0535  * the Global History Buffer (GHB). Affected caches are automatically
0536  * invalidated before use.
0537  *
0538  * \retval      ALT_E_SUCCESS   The operation was successful.
0539  * \retval      ALT_E_ERROR     The operation failed.
0540  */
0541 ALT_STATUS_CODE alt_cache_l1_branch_enable(void);
0542
0543 /*!
0544  * Disables the dynamic branch predictor features on the current CPU core.
0545  *
0546  * This operation disables both the Branch Target Address Cache (BTAC) and
0547  * the Global History Buffer (GHB).
0548  *
0549  * \retval      ALT_E_SUCCESS   The operation was successful.
0550  * \retval      ALT_E_ERROR     The operation failed.
0551  */
0552 ALT_STATUS_CODE alt_cache_l1_branch_disable(void);
0553
0554 /*!
0555  * Returns \b true when both the dynamic predictor features are enabled and
0556  * \b false when they are disabled on the current CPU core.
0557  *
0558  * \retval      true            The L1 branch predictor caches are all enabled.
0559  * \retval      false           Some or all L1 branch predictor caches are
0560  *                              disabled.
0561  */
0562 bool alt_cache_l1_branch_is_enabled(void);
0563
0564 /*!
0565  * Invalidates the dynamic branch predictor feature caches on the current CPU
0566  * core.
0567  *
0568  * \retval      ALT_E_SUCCESS   The operation was successful.
0569  * \retval      ALT_E_ERROR     The operation failed.
0570  */
0571 ALT_STATUS_CODE alt_cache_l1_branch_invalidate(void);
0572
0573 /*!
0574  * Enables the L1 cache data prefetch feature on the current CPU core.
0575  *
0576  * This allows data to be prefetched into the data cache before it is to be
0577  * used. For example in a loop the current iteration may want to preload the
0578  * data which will be used in the next teration. This is done by using the PLD
0579  * instructions.
0580  *
0581  * \retval      ALT_E_SUCCESS   The operation was successful.
0582  * \retval      ALT_E_ERROR     The operation failed.
0583  */
0584 ALT_STATUS_CODE alt_cache_l1_prefetch_enable(void);
0585
0586 /*!
0587  * Disables the L1 cache data prefetch feature on the current CPU core.
0588  *
0589  * \retval      ALT_E_SUCCESS   The operation was successful.
0590  * \retval      ALT_E_ERROR     The operation failed.
0591  */
0592 ALT_STATUS_CODE alt_cache_l1_prefetch_disable(void);
0593
0594 /*!
0595  * Returns \b true if the L1 cache data prefetch feature is enabled and
0596  * \b false if it is disabled on the current CPU core.
0597  *
0598  * \retval      true            The L1 data cache prefetch feature is enabled.
0599  * \retval      false           The L1 data cache prefetch feature is disabled.
0600  */
0601 bool alt_cache_l1_prefetch_is_enabled(void);
0602
0603 /*!
0604  * @}
0605  */
0606
0607 /*!
0608  * \addtogroup CACHE_L2 L2 Cache Management API
0609  *
0610  * This API group provides functions to interact with various features of the
0611  * L2 cache on the SoCFPGA. This includes the following features:
0612  *  * L2 cache
0613  *  * Parity error detection
0614  *  * Data prefetching
0615  *  * Interrupt Management
0616  *
0617  * \internal
0618  * Additional features that may be implemented in the future:
0619  *  * Lockdown
0620  *  * Event counter
0621  * \endinternal
0622  *
0623  * The API within this group affects the L2 cache which is visible to all CPUs
0624  * on the system.
0625  *
0626  * With respect to bring-up, the L1 and L2 cache controller setups are fully
0627  * independent. The L2 can be setup at any time, before or after the L1 is setup.
0628  * \internal
0629  * Source: Cortex-A9 MPCore TRM, section 5.3.4 "Multiprocessor bring-up".
0630  * \endinternal
0631  *
0632  * @{
0633  */
0634
0635 /*!
0636  * Initializes the L2 cache controller.
0637  *
0638  * \retval      ALT_E_SUCCESS   Successful status.
0639  * \retval      ALT_E_ERROR     Details about error status code
0640  */
0641 ALT_STATUS_CODE alt_cache_l2_init(void);
0642
0643 /*!
0644  * Uninitializes the L2 cache controller.
0645  *
0646  * \retval      ALT_E_SUCCESS   Successful status.
0647  * \retval      ALT_E_ERROR     Details about error status code
0648  */
0649 ALT_STATUS_CODE alt_cache_l2_uninit(void);
0650
0651 /*!
0652  * Enables the L2 cache features for data and instruction prefetching.
0653  *
0654  * Prefetching can be enabled or disabled while the L2 cache is enabled.
0655  * \internal
0656  * Source: Use the Prefetch Control Register.
0657  * \endinternal
0658  *
0659  * \retval      ALT_E_SUCCESS   The operation was successful.
0660  * \retval      ALT_E_ERROR     The operation failed.
0661  */
0662 ALT_STATUS_CODE alt_cache_l2_prefetch_enable(void);
0663
0664 /*!
0665  * Disables the L2 cache features for data and instruction prefetching.
0666  *
0667  * Prefetching can be enabled or disabled while the L2 cache is enabled.
0668  * \internal
0669  * Source: Use the Prefetch Control Register.
0670  * \endinternal
0671  *
0672  * \retval      ALT_E_SUCCESS   The operation was successful.
0673  * \retval      ALT_E_ERROR     The operation failed.
0674  */
0675 ALT_STATUS_CODE alt_cache_l2_prefetch_disable(void);
0676
0677 /*!
0678  * Returns \b true if either L2 cache data or instruction prefetch features are
0679  * enabled and \b false if no prefetching features are enabled.
0680  *
0681  * \retval      true            The L2 data and instruction prefetch features
0682  *                              are enabled.
0683  * \retval      false           Some L2 data and instruction prefetch features
0684  *                              are disabled.
0685  */
0686 bool alt_cache_l2_prefetch_is_enabled(void);
0687
0688 /*!
0689  * Enables parity error detection in the L2 cache.
0690  *
0691  * Ideally parity should be enabled before the L2 cache is enabled. If the
0692  * cache is already enabled, it will first be cleaned and disabled before
0693  * parity is enabled in hardware. Afterwards, the cache will be invalidated and
0694  * enabled.
0695  *
0696  * For a parity error to be reported, the ALT_CACHE_L2_INTERRUPT_PARRD and / or
0697  * ALT_CACHE_L2_INTERRUPT_PARRT interrupt condition(s) must be enabled. This is
0698  * done by calling alt_cache_l2_int_enable(). As well, the L2 cache interrupt
0699  * must be enabled using the interrupt controller API. Refer to the interrupt
0700  * controller API for more details about programming the interrupt controller.
0701  *
0702  * In the event of a parity error is detected, the appropriate L2 cache parity
0703  * interrupt will be raised. To clear the parity interrupt(s), the appropriate
0704  * L2 cache parity interrupt must be cleared by calling
0705  * alt_cache_l2_int_status_clear().
0706  *
0707  * For ECC support, refer to the ECC related API documentation for more
0708  * information.
0709  *
0710  * \retval      ALT_E_SUCCESS   The operation was successful.
0711  * \retval      ALT_E_ERROR     The operation failed.
0712  */
0713 ALT_STATUS_CODE alt_cache_l2_parity_enable(void);
0714
0715 /*!
0716  * Disables parity error detection in the L2 cache.
0717  *
0718  * \retval      ALT_E_SUCCESS   The operation was successful.
0719  * \retval      ALT_E_ERROR     The operation failed.
0720  */
0721 ALT_STATUS_CODE alt_cache_l2_parity_disable(void);
0722
0723 /*!
0724  * Returns \b true when parity error detection is enabled and \b false when it
0725  * is disabled.
0726  *
0727  * \retval      true            The L2 cache parity error detection feature is
0728  *                              enabled.
0729  * \retval      false           The L2 cache parity error detection feature is
0730  *                              disabled.
0731  */
0732 bool alt_cache_l2_parity_is_enabled(void);
0733
0734 /*!
0735  * Enables the L2 cache.
0736  *
0737  * If the L2 cache is already enabled, nothing is done. Otherwise the entire
0738  * contents of the cache is first invalidated before being enabled.
0739  *
0740  * \retval      ALT_E_SUCCESS   The operation was successful.
0741  * \retval      ALT_E_ERROR     The operation failed.
0742  */
0743 ALT_STATUS_CODE alt_cache_l2_enable(void);
0744
0745 /*!
0746  * Disables the L2 cache.
0747  *
0748  * If the L2 cache is already disabled, nothing is done. Otherwise the entire
0749  * contents of the cache is first cleaned before being disabled.
0750  *
0751  * \retval      ALT_E_SUCCESS   The operation was successful.
0752  * \retval      ALT_E_ERROR     The operation failed.
0753  */
0754 ALT_STATUS_CODE alt_cache_l2_disable(void);
0755
0756 /*!
0757  * Returns \b true when the L2 cache is enabled and \b false when it is
0758  * disabled.
0759  *
0760  * \retval      true            The L2 cache is enabled.
0761  * \retval      false           The L2 cache is disabled.
0762  */
0763 bool alt_cache_l2_is_enabled(void);
0764
0765 /*!
0766  * Flushes the L2 cache controller hardware buffers.
0767  *
0768  * \retval      ALT_E_SUCCESS   The operation was successful.
0769  * \retval      ALT_E_ERROR     The operation failed.
0770  * \retval      ALT_E_TMO       The memory operation timed out.
0771  */
0772 ALT_STATUS_CODE alt_cache_l2_sync(void);
0773
0774 /*!
0775  * Invalidates the specified contents of the L2 cache for the given memory
0776  * segment.
0777  *
0778  * The memory segment address and length specified must align to the
0779  * characteristics of the cache line. This means the address and length must be
0780  * multiples of the cache line size. To determine the cache line size, use the
0781  * \b ALT_CACHE_LINE_SIZE macro.
0782  *
0783  * \param       paddress
0784  *              The physical address of the memory segment to be invalidated.
0785  *
0786  * \param       length
0787  *              The length of the memory segment to be invalidated.
0788  *
0789  * \retval      ALT_E_SUCCESS   The operation was successful.
0790  * \retval      ALT_E_ERROR     The operation failed.
0791  * \retval      ALT_E_BAD_ARG   The memory segment is invalid.
0792  * \retval      ALT_E_TMO       The memory operation timed out.
0793  */
0794 ALT_STATUS_CODE alt_cache_l2_invalidate(void * paddress, size_t length);
0795
0796 /*!
0797  * Invalidates th entire contents of the L2 cache.
0798  *
0799  * Normally this is done automatically as part of alt_cache_l2_enable(), but
0800  * in certain circumstances it may be necessary to invalidate it manually. An
0801  * example of this situation is when the address space is remapped and the
0802  * processor accesses memory from the new memory area.
0803
0804  * \retval      ALT_E_SUCCESS   The operation was successful.
0805  * \retval      ALT_E_ERROR     The operation failed.
0806  * \retval      ALT_E_TMO       The memory operation timed out.
0807  */
0808 ALT_STATUS_CODE alt_cache_l2_invalidate_all(void);
0809
0810 /*!
0811  * Cleans the specified contents of the L2 cache for the given memory segment.
0812  *
0813  * The memory segment address and length specified must align to the
0814  * characteristics of the cache line. This means the address and length must be
0815  * multiples of the cache line size. To determine the cache line size, use the
0816  * \b ALT_CACHE_LINE_SIZE macro.
0817  *
0818  * \param       paddress
0819  *              The physical address of the memory segment to be cleaned.
0820  *
0821  * \param       length
0822  *              The length of the memory segment to be cleaned.
0823  *
0824  * \retval      ALT_E_SUCCESS   The operation was successful.
0825  * \retval      ALT_E_ERROR     The operation failed.
0826  * \retval      ALT_E_BAD_ARG   The memory segment is invalid.
0827  * \retval      ALT_E_TMO       The memory operation timed out.
0828  */
0829 ALT_STATUS_CODE alt_cache_l2_clean(void * paddress, size_t length);
0830
0831 /*!
0832  * Cleans the entire L2 cache. All L2 cache controller interrupts will be
0833  * temporarily disabled while the clean operation is in progress and restored
0834  * once the it is finished.
0835  *
0836  * \retval      ALT_E_SUCCESS   The operation was successful.
0837  * \retval      ALT_E_ERROR     The operation failed.
0838  * \retval      ALT_E_TMO       The memory operation timed out.
0839  */
0840 ALT_STATUS_CODE alt_cache_l2_clean_all(void);
0841
0842 /*!
0843  * Cleans and invalidates the specified contents of the L2 cache for the
0844  * given memory segment.
0845  *
0846  * The memory segment address and length specified must align to the
0847  * characteristics of the cache line. This means the address and length must be
0848  * multiples of the cache line size. To determine the cache line size, use the
0849  * \b ALT_CACHE_LINE_SIZE macro.
0850  *
0851  * \param       paddress
0852  *              The physical address of the memory segment to be purged.
0853  *
0854  * \param       length
0855  *              The length of the memory segment to be purged.
0856  *
0857  * \retval      ALT_E_SUCCESS   The operation was successful.
0858  * \retval      ALT_E_ERROR     The operation failed.
0859  * \retval      ALT_E_BAD_ARG   The memory segment is invalid.
0860  */
0861 ALT_STATUS_CODE alt_cache_l2_purge(void * paddress, size_t length);
0862
0863 /*!
0864  * Cleans and invalidates the entire L2 cache. All L2 cache controller
0865  * interrupts will be temporarily disabled while the clean and invalidate
0866  * operation is in progress and restored once the it is finished.
0867  *
0868  * \retval      ALT_E_SUCCESS   The operation was successful.
0869  * \retval      ALT_E_ERROR     The operation failed.
0870  * \retval      ALT_E_TMO       The memory operation timed out.
0871  */
0872 ALT_STATUS_CODE alt_cache_l2_purge_all(void);
0873
0874 /*!
0875  * This type definition enumerates all the interrupt conditions that can be
0876  * generated by the L2 cache controller as register mask values.
0877  */
0878 enum ALT_CACHE_L2_INTERRUPT_e
0879 {
0880     /*! Decode error received on the master ports from L3. */
0881     ALT_CACHE_L2_INTERRUPT_DECERR = 1 << 8,
0882
0883     /*! Slave error received on the master ports from L3.  */
0884     ALT_CACHE_L2_INTERRUPT_SLVERR = 1 << 7,
0885
0886     /*! Error on the L2 data RAM read.                     */
0887     ALT_CACHE_L2_INTERRUPT_ERRRD  = 1 << 6,
0888
0889     /*! Error on the L2 tag RAM read.                      */
0890     ALT_CACHE_L2_INTERRUPT_ERRRT  = 1 << 5,
0891
0892     /*! Error on the L2 data RAM write.                    */
0893     ALT_CACHE_L2_INTERRUPT_ERRWD  = 1 << 4,
0894
0895     /*! Error on the L2 tag RAM write.                     */
0896     ALT_CACHE_L2_INTERRUPT_ERRWT  = 1 << 3,
0897
0898     /*! Parity error on the L2 data RAM read.              */
0899     ALT_CACHE_L2_INTERRUPT_PARRD  = 1 << 2,
0900
0901     /*! Parity error on the L2 tag RAM read.               */
0902     ALT_CACHE_L2_INTERRUPT_PARRT  = 1 << 1,
0903
0904     /*! Event counter overflow or increment.               */
0905     ALT_CACHE_L2_INTERRUPT_ECNTR  = 1 << 0
0906 };
0907 typedef enum ALT_CACHE_L2_INTERRUPT_e ALT_CACHE_L2_INTERRUPT_t;
0908
0909 /*!
0910  * Enables the L2 cache controller interrupts for the specified set of
0911  * condition(s).
0912  *
0913  * \param       interrupt
0914  *              A register mask of the selected L2 cache controller
0915  *              interrupting conditions.
0916  *
0917  * \retval      ALT_E_SUCCESS   The operation was successful.
0918  * \retval      ALT_E_ERROR     The operation failed.
0919  */
0920 ALT_STATUS_CODE alt_cache_l2_int_enable(uint32_t interrupt);
0921
0922 /*!
0923  * Disables the L2 cache controller interrupts for the specified set of
0924  * condition(s).
0925  *
0926  * \param       interrupt
0927  *              A register mask of the selected L2 cache controller
0928  *              interrupting conditions.
0929  *
0930  * \retval      ALT_E_SUCCESS   The operation was successful.
0931  * \retval      ALT_E_ERROR     The operation failed.
0932  */
0933 ALT_STATUS_CODE alt_cache_l2_int_disable(uint32_t interrupt);
0934
0935 /*!
0936  * Gets the condition(s) causing the L2 cache controller to interrupt as a
0937  * register mask.
0938  *
0939  * \returns     A register mask of the currently asserted and enabled
0940  *              conditions resulting in an interrupt being generated.
0941  */
0942 uint32_t alt_cache_l2_int_status_get(void);
0943
0944 /*!
0945  * Clears the specified conditon(s) causing the L2 cache controller to
0946  * interrupt as a mask. Condition(s) specified which are not causing an
0947  * interrupt or condition(s) specified which are not enabled are ignored.
0948  *
0949  * \param       interrupt
0950  *              A register mask of the selected L2 cache controller
0951  *              interrupting conditions.
0952  *
0953  * \retval      ALT_E_SUCCESS   The operation was successful.
0954  * \retval      ALT_E_ERROR     The operation failed.
0955  */
0956 ALT_STATUS_CODE alt_cache_l2_int_status_clear(uint32_t interrupt);
0957
0958 /*!
0959  * @}
0960  */
0961
0962 /*!
0963  * @}
0964  */
0965
0966 #ifdef __cplusplus
0967 }
0968 #endif
0969
0970 #endif /* __ALT_CACHE_H__ */