/*! \file | |
* Altera - SoC FPGA FPGA/HPS Bridge Management | |
*/ | |
/****************************************************************************** | |
* | |
* 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_BRG_MGR_H__ | |
#define __ALT_BRG_MGR_H__ | |
#include "hwlib.h" | |
#ifdef __cplusplus | |
extern "C" | |
{ | |
#endif /* __cplusplus */ | |
/******************************************************************************/ | |
/*! \addtogroup ALT_BRIDGE The AXI Bridge Manager | |
* | |
* The functions in this group manage access, configuration, and control of the | |
* AXI bridges between the FPGA and HPS. | |
* | |
* @{ | |
*/ | |
/******************************************************************************/ | |
/*! | |
* This type definition enumerates the AXI bridge interfaces between the FPGA | |
* and HPS. | |
*/ | |
typedef enum ALT_BRIDGE_e | |
{ | |
ALT_BRIDGE_F2H, /*!< FPGA-to-HPS AXI bridge providing a | |
* high-performance, statically configurable | |
* width interface that gives the FPGA the | |
* ability to: | |
* * master transactions to slaves in the HPS | |
* * have full visibility into the HPS address space | |
* * access the coherent memory interface (ACP) | |
* | |
* The width (32/64/128 bits) of this bridge | |
* is statically configurable at design time | |
* using \e Quartus. | |
*/ | |
ALT_BRIDGE_H2F, /*!< HPS-to-FPGA AXI bridge providing a | |
* statically configurable width, | |
* high-performance master interface to the | |
* FPGA fabric. The bridge provides a 1GB | |
* address space and gives any master in the | |
* HPS system access to logic, peripherals, | |
* and memory implemented in the FPGA. | |
*/ | |
ALT_BRIDGE_LWH2F /*!< Lightweight HPS-to-FPGA AXI bridge | |
* providing a secondary, fixed-width, smaller | |
* address space, lower-performance master | |
* interface to the FPGA fabric. The bridge | |
* provides a 2MB address space and gives any | |
* master in the HPS access to logic, | |
* peripherals, and memory implemented in the | |
* FPGA fabric. The bridge master exposed to | |
* the FPGA fabric has a fixed data width of | |
* 32 bits. | |
* | |
* The bridge provides clock crossing logic to | |
* allow the logic in the FPGA to run | |
* asynchronous to the HPS. The bridge | |
* simplifies the process of connecting the | |
* HPS to soft logic. Soft logic can even be | |
* designed to support only a subset of the | |
* full AXI protocol that the bridge | |
* supports. Use the lightweight HPS-to-FPGA | |
* bridge for high-latency, low-bandwidth | |
* traffic, such as memory-mapped register | |
* accesses of FPGA peripherals. This approach | |
* diverts traffic from the high-performance | |
* HPS-to-FPGA bridge, which can improve | |
* overall performance. | |
*/ | |
} ALT_BRIDGE_t; | |
/******************************************************************************/ | |
/*! | |
* Type definition for a callback function prototype used by the | |
* alt_bridge_init() bridge initialization function to determine whether the | |
* FPGA is ready to begin transactions across the bridge interface. | |
* | |
* The implementation of the callback function is user defined allowing the user | |
* to define a flexible signaling protocol for the FPGA to indicate its | |
* readiness to begin transactions across the initialized bridge interface. | |
* | |
* The range of values returned by the callback function may be extended per the | |
* user defined FPGA readiness signaling protocol but any return value other | |
* than ALT_E_SUCCESS will be interpreted by the alt_bridge_init() bridge | |
* initialization function as an indication that the FPGA is not ready to | |
* commence bridge interface transactions. | |
* | |
* \param user_arg | |
* This is a user defined parameter available to pass additional | |
* data that might be needed to support the user defined FPGA | |
* readiness signaling protocol. | |
* | |
* \retval ALT_E_SUCCESS The FPGA is ready to commence bridge interface | |
* transactions. | |
* \retval ALT_E_ERROR An error has occurred. The FPGA is not ready to | |
* commence bridge interface transactions. | |
* \retval ALT_E_TMO The FPGA failed to signal a ready to commence | |
* bridge interface transactions indication before | |
* the response timeout period expired. | |
*/ | |
typedef ALT_STATUS_CODE (*alt_bridge_fpga_is_ready_t)(void* user_arg); | |
/******************************************************************************/ | |
/*! | |
* Initialize the bridge for bus transactions by bringing up the interface in a | |
* safe, controlled sequence. | |
* | |
* The following actions are performed as part of the process of initializing | |
* the bridge interface for transactions: | |
* | |
* * Sets and holds bridge interface in reset. | |
* * Ensures that the bridge interface is ready by asserting that: | |
* - FPGA is powered and configured (i.e. in USER mode). | |
* - Bridge interface clock is ready and stable. | |
* - FPGA soft IP is ready for transactions across the bridge interface. | |
* * Releases bridge interface from reset. | |
* | |
* The mechanism used by alt_bridge_init() to determine whether the FPGA soft IP | |
* is ready to begin bus transactions across the interface is the user defined | |
* callback \e fpga_is_ready. | |
* | |
* \internal | |
* This process of software controlled bring-up of HPS/FPGA interfaces is | |
* detailed in <em> Hammerhead-P HPS FPGA Interface NPP, Section 4 Software | |
* Bring-up/Tear-down</em>. | |
* \endinternal | |
* | |
* \param bridge | |
* The bridge interface to initialize. | |
* | |
* \param fpga_is_ready | |
* A pointer to a user defined callback function to determine | |
* whether the FPGA is ready to commence bridge interface | |
* transactions. If NULL is passed, then bridge interface | |
* initialization proceeds without making a determination of | |
* whether the FPGA is ready to commence bridge interface | |
* transactions or not. | |
* | |
* \param user_arg | |
* A user defined argument value for passing support data to the \e | |
* fpga_is_ready callback function. | |
* | |
* \retval ALT_E_SUCCESS The operation was succesful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_bridge_init(ALT_BRIDGE_t bridge, | |
alt_bridge_fpga_is_ready_t fpga_is_ready, | |
void* user_arg); | |
/******************************************************************************/ | |
/*! | |
* Type definition for a callback function prototype used by the | |
* alt_bridge_uninit() function to conduct a handshake protocol with the FPGA | |
* notifying it that the bridge interface is being taken down. | |
* | |
* The callback function implementation is user defined and allows the user to | |
* implement a flexible handshake notification protocol with the FPGA to allow | |
* an orderly interface shutdown prior to the bridge being taken down. | |
* | |
* The handshake protocol is user defined but normally consists of two parts: | |
* * The processor notifies the FPGA soft IP that the bridge interface is being | |
* taken down. The notification mechanism used to signal the FPGA is user | |
* defined. | |
* * The process waits for an acknowledgement response from the FPGA. | |
* | |
* The range of return values for the callback function may be extended per the | |
* user defined handshake notification protocol but any return value other than | |
* ALT_E_SUCCESS will be interpreted by the alt_bridge_uninit() function as an | |
* indication that the handshake protocol was unsuccessful. | |
* | |
* \param user_arg | |
* This is a user defined parameter available to pass additional | |
* data that might be needed to support the user defined handshake | |
* notification protocol. | |
* | |
* \retval ALT_E_SUCCESS The handshake notification protocol was successful. | |
* \retval ALT_E_ERROR An error has occurred. The handshake notification | |
* protocol was unsuccessful. | |
* \retval ALT_E_TMO The handshake notification protocol failed | |
* because a response timeout period expired. | |
*/ | |
typedef ALT_STATUS_CODE (*alt_bridge_teardown_handshake_t)(void* user_arg); | |
/******************************************************************************/ | |
/*! | |
* Uninitialize the bridge by tearing down the interface in a safe and | |
* controlled sequence. | |
* | |
* The process of taking down the bridge interface entails: | |
* * Optional: Conduct teardown handshake notification protocol | |
* - Bridge Manager informs FPGA that the bridge interface is being torn down. | |
* - Bridge Manager waits for FPGA response to notification. | |
* * Processor waits for the completion of outstanding transactions on the AXI | |
* bridge. Note, that HPS has no mechanism to track outstanding AXI transactions; | |
* this needs to be provided by the customer design. | |
* * Places and holds the bridge interface in reset. | |
* | |
* The mechanism used by alt_bridge_uninit() to initiate the handshake | |
* notification to the FPGA soft IP that the bridge interface is being taken | |
* down is the user defined \e handshake callback. | |
* | |
* \internal | |
* This function implements the software controlled tear-down procedure detailed | |
* in <em> Hammerhead-P HPS FPGA Interface NPP, Section 4 Software | |
* Bring-up/Tear-down</em>. | |
* \endinternal | |
* | |
* \param bridge | |
* The bridge interface to uninitialize. | |
* | |
* \param handshake | |
* A pointer to a user defined tear-down handshake protocol. If | |
* NULL is passed, then the bridge interface take down proceeds | |
* without conducting any handshake notification protocol. | |
* | |
* \param user_arg | |
* A user defined argument value for passing support data to the | |
* \e teardown_hs callback function. | |
* | |
* \retval ALT_E_SUCCESS The operation was successful. | |
* \retval ALT_E_ERROR The operation failed. | |
*/ | |
ALT_STATUS_CODE alt_bridge_uninit(ALT_BRIDGE_t bridge, | |
alt_bridge_teardown_handshake_t handshake, | |
void* user_arg); | |
/*! @} */ | |
#ifdef __cplusplus | |
} | |
#endif /* __cplusplus */ | |
#endif /* __ALT_BRG_MGR_H__ */ |