Remove make preinstall

A speciality of the RTEMS build system was the make preinstall step.  It
copied header files from arbitrary locations into the build tree.  The
header files were included via the -Bsome/build/tree/path GCC command
line option.

This has at least seven problems:

* The make preinstall step itself needs time and disk space.

* Errors in header files show up in the build tree copy.  This makes it
  hard for editors to open the right file to fix the error.

* There is no clear relationship between source and build tree header
  files.  This makes an audit of the build process difficult.

* The visibility of all header files in the build tree makes it
  difficult to enforce API barriers.  For example it is discouraged to
  use BSP-specifics in the cpukit.

* An introduction of a new build system is difficult.

* Include paths specified by the -B option are system headers.  This
  may suppress warnings.

* The parallel build had sporadic failures on some hosts.

This patch removes the make preinstall step.   All installed header
files are moved to dedicated include directories in the source tree.
Let @RTEMS_CPU@ be the target architecture, e.g. arm, powerpc, sparc,
etc.  Let @RTEMS_BSP_FAMILIY@ be a BSP family base directory, e.g.
erc32, imx, qoriq, etc.

The new cpukit include directories are:

* cpukit/include

* cpukit/score/cpu/@RTEMS_CPU@/include

* cpukit/libnetworking

The new BSP include directories are:

* bsps/include

* bsps/@RTEMS_CPU@/include

* bsps/@RTEMS_CPU@/@RTEMS_BSP_FAMILIY@/include

There are build tree include directories for generated files.

The include directory order favours the most general header file, e.g.
it is not possible to override general header files via the include path
order.

The "bootstrap -p" option was removed.  The new "bootstrap -H" option
should be used to regenerate the "headers.am" files.

Update #3254.

1 files changed, 964 insertions, 0 deletions

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