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