/******************************************************************************
*
* 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_FPGA_MGR_H__
#define __ALT_FPGA_MGR_H__

#include "hwlib.h"
#include "alt_dma.h"
#include <stdio.h>

#ifdef __cplusplus
extern "C"
{
#endif /* __cplusplus */

/*!
 * \addtogroup FPGA_MGR The FPGA Manager
 *
 * This module defines the FPGA Manager API for accessing, configuring, and
 * controlling the FPGA fabric and the FPGA/HPS interface.
 *
 * @{
 */


/*!
 * This preprocessor definition determines if DMA support for FPGA programming
 * is enabled or not. Enabling DMA support enables the following API:
 *  * alt_fpga_configure_dma()
 *  * alt_fpga_istream_configure_dma()
 *
 * To enable DMA support, define ALT_FPGA_ENABLE_DMA_SUPPORT=1 in the Makefile.
 */
#ifndef ALT_FPGA_ENABLE_DMA_SUPPORT
#define ALT_FPGA_ENABLE_DMA_SUPPORT (0)
#endif

/*!
 * Initializes the FPGA manager. This should be the first API called when using
 * the FPGA manager API.
 *
 * \retval      ALT_E_SUCCESS   The operation was successful.
 * \retval      ALT_E_ERROR     The operation failed.
 */
ALT_STATUS_CODE alt_fpga_init(void);

/*!
 * Uninitializes the FPGA manager
 *
 * \retval      ALT_E_SUCCESS   The operation was successful.
 * \retval      ALT_E_ERROR     The operation failed.
 */
ALT_STATUS_CODE alt_fpga_uninit(void);

/*!
 * \addtogroup FPGA_MGR_STATUS FPGA Manager Status and Control
 *
 * This group provides functions for controlling and determining status of the
 * FPGA Manager.
 *
 * @{
 */

/*!
 * Instructs the CPU core to acquire control of the FPGA control block. This
 * must API must be called before any other API is issued.
 *
 * \retval      ALT_E_SUCCESS       Successful status.
 * \retval      ALT_E_ERROR         Error acquiring control of the FPGA control
 *                                  block. This is likely due to another device
 *                                  on the system controlling the FPGA control
 *                                  block or a repeat call to this API without
 *                                  first being released.
 */
ALT_STATUS_CODE alt_fpga_control_enable(void);

/*!
 * Instructs the CPU core to release control of the FPGA control block. This
 * API should be called after all FPGA related operations are completed. This
 * will allow another device on the system to configure the FPGA.
 *
 * \retval      ALT_E_SUCCESS       Successful status.
 * \retval      ALT_E_ERROR         Failure status.
 */
ALT_STATUS_CODE alt_fpga_control_disable(void);

/*!
 * Returns \b true if the HPS currently has control of the FPGA control block
 * and \b false otherwise.
 *
 * \retval      true                HPS has control of the FPGA control block.
 * \retval      false               HPS does not have control of the FPGA
 *                                  control block.
 */
bool alt_fpga_control_is_enabled(void);

/*!
 * This type definition enumerates the possible states the FPGA can be in at
 * any one time.
 */
typedef enum ALT_FPGA_STATE_e
{
    /*!
     * FPGA in Power Up Phase. This is the state of the FPGA just after
     * powering up.
     *
     * \internal
     * Register documentation calls it "PWR_OFF" which is really a misnomer as
     * the FPGA is powered as evident from alt_fpga_mon_status_get() and
     * looking at the ALT_FPGA_MON_FPGA_POWER_ON bit.
     * \endinternal
     */
    ALT_FPGA_STATE_POWER_UP = 0x0,

    /*!
     * FPGA in Reset Phase. In this phase, the FPGA resets, clears the FPGA
     * configuration RAM bits, tri-states all FPGA user I/O pins, pulls the
     * nSTATUS and CONF_DONE pins low, and determines the configuration mode
     * by reading the value of the MSEL pins.
     */
    ALT_FPGA_STATE_RESET = 0x1,

    /*!
     * FPGA in Configuration Phase. This state represents the phase when the
     * configuration bitstream is loaded into the FPGA fabric. The
     * configuration phase is complete after the FPGA has received all the
     * configuration data.
     */
    ALT_FPGA_STATE_CFG = 0x2,

    /*!
     * FPGA in Initialization Phase. In this state the FPGA prepares to enter
     * User Mode. In Configuration via PCI Express (CVP), this state indicates
     * I/O configuration has completed.
     */
    ALT_FPGA_STATE_INIT = 0x3,

    /*!
     * FPGA in User Mode. In this state, the FPGA performs the function loaded
     * during the configuration phase. The FPGA user I/O are functional as
     * determined at design time.
     */
    ALT_FPGA_STATE_USER_MODE = 0x4,

    /*!
     * FPGA state has not yet been determined. This only occurs briefly after
     * reset.
     */
    ALT_FPGA_STATE_UNKNOWN = 0x5,

    /*!
     * FPGA is powered off.
     *
     * \internal
     * This is a software only state which is determined by
     * alt_fpga_mon_status_get() and looking at the ALT_FPGA_MON_FPGA_POWER_ON
     * bit. The hardware register sourced for ALT_FPGA_STATE_t is only 3 bits
     * wide so this will never occur in hardware.
     * \endinternal
     */
    ALT_FPGA_STATE_POWER_OFF = 0xF

} ALT_FPGA_STATE_t;

/*!
 * Returns the current operational state of the FPGA fabric.
 *
 * \returns     The current operational state of the FPGA.
 */
ALT_FPGA_STATE_t alt_fpga_state_get(void);

/*!
 * This type definition enumerates the monitored status conditions for the FPGA
 * Control Block (CB).
 */
typedef enum ALT_FPGA_MON_STATUS_e
{
    /*!
     * 0 if the FPGA is in Reset Phase or if the FPGA detected an error during
     * the Configuration Phase.
     */
    ALT_FPGA_MON_nSTATUS = 0x0001,

    /*!
     * 0 during the FPGA Reset Phase and 1 when the FPGA Configuration Phase is
     * done.
     */
    ALT_FPGA_MON_CONF_DONE = 0x0002,

    /*!
     * 0 during the FPGA Configuration Phase and 1 when the FPGA Initialization
     * Phase is done.
     */
    ALT_FPGA_MON_INIT_DONE = 0x0004,

    /*!
     * CRC error indicator. A 1 indicates that the FPGA detected a CRC error
     * while in User Mode.
     */
    ALT_FPGA_MON_CRC_ERROR = 0x0008,

    /*!
     * Configuration via PCIe (CVP) Done indicator. A 1 indicates that CVP is
     * done.
     */
    ALT_FPGA_MON_CVP_CONF_DONE = 0x0010,

    /*!
     * Partial Reconfiguration ready indicator. A 1 indicates that the FPGA is
     * ready to receive partial reconfiguration or external scrubbing data.
     */
    ALT_FPGA_MON_PR_READY = 0x0020,

    /*!
     * Partial Reconfiguration error indicator. A 1 indicates that the FPGA
     * detected an error during partial reconfiguration or external scrubbing.
     */
    ALT_FPGA_MON_PR_ERROR = 0x0040,

    /*!
     * Partial Reconfiguration done indicator. A 1 indicates partial
     * reconfiguration or external scrubbing is done.
     */
    ALT_FPGA_MON_PR_DONE = 0x0080,

    /*!
     * Value of the nCONFIG pin. This can be pulled-down by the FPGA in this
     * device or logic external to this device connected to the nCONFIG pin.
     * See the description of the nCONFIG field in this register to understand
     * when the FPGA in this device pulls-down the nCONFIG pin. Logic external
     * to this device pulls-down the nCONFIG pin to put the FPGA into the Reset
     * Phase.
     */
    ALT_FPGA_MON_nCONFIG_PIN = 0x0100,

    /*!
     * Value of the nSTATUS pin. This can be pulled-down by the FPGA in this
     * device or logic external to this device connected to the nSTATUS pin.
     * See the description of the nSTATUS field in this register to understand
     * when the FPGA in this device pulls-down the nSTATUS pin. Logic external
     * to this device pulls-down the nSTATUS pin during Configuration Phase or
     * Initialization Phase if it detected an error.
     */
    ALT_FPGA_MON_nSTATUS_PIN = 0x0200,

    /*!
     * Value of the CONF_DONE pin. This can be pulled-down by the FPGA in this
     * device or logic external to this device connected to the CONF_DONE pin.
     * See the description of the CONF_DONE field in this register to
     * understand when the FPGA in this device pulls-down the CONF_DONE pin.
     * See FPGA documentation to determine how logic external to this device
     * drives CONF_DONE.
     */
    ALT_FPGA_MON_CONF_DONE_PIN = 0x0400,

    /*!
     * FPGA powered on indicator.
     */
    ALT_FPGA_MON_FPGA_POWER_ON = 0x0800,

} ALT_FPGA_MON_STATUS_t;

/*!
 * Returns the FPGA Control Block monitor status conditions.
 *
 * This function returns the current value of the FPGA Control Block monitor
 * status conditions.
 *
 * \returns     The current values of the FPGA Control Block monitor status
 *              conditions as defined by the \ref ALT_FPGA_MON_STATUS_t mask
 *              bits. If the corresponding bit is set then the condition is
 *              asserted.
 *
 * \internal
 * Use the Raw Interrupt Status Register \b hps::fpgamgrregs::mon::gpio_ext_porta
 * to retrieve the monitor status conditions.
 * \endinternal
 */
uint32_t alt_fpga_mon_status_get(void);

/*!
 * Assert and hold the FPGA in reset.
 *
 * This function asserts and holds the FPGA in reset. Any FPGA configuration is
 * cleared. The FPGA must be reconfigured to resume operation.
 * 
 * The FPGA is reset by the assertion of the nCONFIG signal. The signal remains
 * asserted until alt_fgpa_reset_deassert() is called.
 *
 * \retval      ALT_E_SUCCESS           Successful status.
 * \retval      ALT_E_FPGA_PWR_OFF      FPGA is not powered on.
 * \retval      ALT_E_FPGA_NO_SOC_CTRL  SoC software is not in control of the
 *                                      FPGA. Use alt_fpga_control_enable() to
 *                                      gain control.
 */
ALT_STATUS_CODE alt_fgpa_reset_assert(void);

/*!
 * Deassert and release the FPGA from reset.
 *
 * This function deasserts the FPGA from reset. The FPGA must be reconfigured to
 * resume operation.
 * 
 * The FPGA is reset by the deassertion of the nCONFIG signal. 
 *
 * \retval      ALT_E_SUCCESS           Successful status.
 * \retval      ALT_E_FPGA_PWR_OFF      FPGA is not powered on.
 * \retval      ALT_E_FPGA_NO_SOC_CTRL  SoC software is not in control of the
 *                                      FPGA. Use alt_fpga_control_enable() to
 *                                      gain control.
 */
ALT_STATUS_CODE alt_fgpa_reset_deassert(void);

/*!
 * @}
 */

/*!
 * \addtogroup FPGA_MGR_CFG FPGA Configuration
 *
 * This functional group provides the following services:
 *  * Determination of the FPGA configuration mode.
 *  * Software control for full configuration of the FPGA.
 *  * Software control for partial reconfiguration of the FPGA \e (Future).
 *
 * @{
 */

/*!
 * This type definition enumerates the available modes for configuring the
 * FPGA.
 */
typedef enum ALT_FPGA_CFG_MODE_e
{
    /*!
     * 16-bit Passive Parallel with Fast Power on Reset Delay; No AES
     * Encryption; No Data Compression. CDRATIO must be programmed to x1.
     */
    ALT_FPGA_CFG_MODE_PP16_FAST_NOAES_NODC = 0x0,

    /*!
     * 16-bit Passive Parallel with Fast Power on Reset Delay; With AES
     * Encryption; No Data Compression. CDRATIO must be programmed to x4.
     */
    ALT_FPGA_CFG_MODE_PP16_FAST_AES_NODC = 0x1,

    /*!
     * 16-bit Passive Parallel with Fast Power on Reset Delay; AES Optional;
     * With Data Compression. CDRATIO must be programmed to x8.
     */
    ALT_FPGA_CFG_MODE_PP16_FAST_AESOPT_DC = 0x2,

    /*!
     * 16-bit Passive Parallel with Slow Power on Reset Delay; No AES
     * Encryption; No Data Compression. CDRATIO must be programmed to x1.
     */
    ALT_FPGA_CFG_MODE_PP16_SLOW_NOAES_NODC = 0x4,

    /*!
     * 16-bit Passive Parallel with Slow Power on Reset Delay; With AES
     * Encryption; No Data Compression. CDRATIO must be programmed to x4.
     */
    ALT_FPGA_CFG_MODE_PP16_SLOW_AES_NODC = 0x5,

    /*!
     * 16-bit Passive Parallel with Slow Power on Reset Delay; AES Optional;
     * With Data Compression. CDRATIO must be programmed to x8.
     */
    ALT_FPGA_CFG_MODE_PP16_SLOW_AESOPT_DC = 0x6,

    /*!
     * 32-bit Passive Parallel with Fast Power on Reset Delay; No AES
     * Encryption; No Data Compression. CDRATIO must be programmed to x1.
     */
    ALT_FPGA_CFG_MODE_PP32_FAST_NOAES_NODC = 0x8,

    /*!
     * 32-bit Passive Parallel with Fast Power on Reset Delay; With AES
     * Encryption; No Data Compression. CDRATIO must be programmed to x4.
     */
    ALT_FPGA_CFG_MODE_PP32_FAST_AES_NODC = 0x9,

    /*!
     * 32-bit Passive Parallel with Fast Power on Reset Delay; AES Optional;
     * With Data Compression. CDRATIO must be programmed to x8.
     */
    ALT_FPGA_CFG_MODE_PP32_FAST_AESOPT_DC = 0xa,

    /*!
     * 32-bit Passive Parallel with Slow Power on Reset Delay; No AES
     * Encryption; No Data Compression. CDRATIO must be programmed to x1.
         */
    ALT_FPGA_CFG_MODE_PP32_SLOW_NOAES_NODC = 0xc,

    /*!
     * 32-bit Passive Parallel with Slow Power on Reset Delay; With AES
     * Encryption; No Data Compression. CDRATIO must be programmed to x4.
     */
    ALT_FPGA_CFG_MODE_PP32_SLOW_AES_NODC = 0xd,

    /*!
     * 32-bit Passive Parallel with Slow Power on Reset Delay; AES Optional;
     * With Data Compression. CDRATIO must be programmed to x8.
     */
    ALT_FPGA_CFG_MODE_PP32_SLOW_AESOPT_DC = 0xe,

    /*!
     * Unknown FPGA Configuration Mode.
     */
    ALT_FPGA_CFG_MODE_UNKNOWN = 0x20,

} ALT_FPGA_CFG_MODE_t;

/*!
 * Gets the FPGA configuration mode currently in effect.
 *
 * Presently, the FPGA configuration mode is statically set by the external MSEL
 * pin values and cannot be programmatically overridden by HPS software.
 *
 * \returns     The current FPGA configuration mode as determined by the MSEL
 *              pin values.
 */
ALT_FPGA_CFG_MODE_t alt_fpga_cfg_mode_get(void);

/*!
 * Sets the FPGA configuration mode.
 *
 * Presently, the FPGA configuration mode is statically set by the external
 * MSEL pin values and cannot be programmatically overridden by HPS software.
 * This function should always return ALT_E_ERROR at least for Hammerhead-P.
 * This may change with future SoCFPGA devices.
 *
 * \param       cfg_mode
 *              The desired FPGA configuration mode.
 *
 * \retval      ALT_E_SUCCESS   Successful status.
 * \retval      ALT_E_ERROR     Failed to set the FPGA configuration mode.
 *
 * \internal
 * This should set the fpgamgrregs::stat::msel. The full configuration reads
 * this to program the fpgamgrregs::ctrl with the appropriate parameters
 * decoded from msel.
 * \endinternal
 */
ALT_STATUS_CODE alt_fpga_cfg_mode_set(ALT_FPGA_CFG_MODE_t cfg_mode);

/*!
 * Type definition for the callback function prototype used by the FPGA Manager
 * to read configuration bitstream data from a user defined input source
 * stream.
 *
 * The purpose of this callback function declaration is to provide a prototype
 * for a user defined method of sequentially reading FPGA configuration
 * bitstream data from an arbitrary input source. Example input sources include
 * a file resident on a file system, a network stream socket, or a fixed
 * address block in flash memory. The only requirement on the input source is
 * that it is capable of supplying consecutive blocks of data of the requested
 * size from the FPGA configuration bitstream as demanded by the FPGA Manager.
 *
 * During FPGA configuration, the FPGA Manager periodically calls the user
 * defined callback function to fetch the next \e buf_len consecutive
 * configuration data bytes from the user defined input stream. The callback
 * function fills the FPGA Manager supplied buffer \e buf with up to the next
 * \e buf_len bytes of configuration bitsteam data as read from the input
 * source stream. The callback function returns the number of configuration
 * bytes read into \e buf or 0 upon reaching the end of the configuration
 * bitstream data.
 *
 * If an error occurs on the configuration bitstream input source, then the
 * callback function should return an error code value less than 0.
 *
 * \param       buf
 *              A pointer to a buffer to fill with FPGA configuration bitstream
 *              data bytes.
 *
 * \param       buf_len
 *              The length of the input buffer \e buf in bytes. The number of
 *              FPGA configuration bitstream data bytes copied into \e buf
 *              should not exceed \e buf_len.
 *
 * \param       user_data
 *              A 32-bit data word for passing user defined data. The content
 *              of this parameter is user defined. The FPGA Manager merely
 *              forwards the \e user_data value when it invokes the callback.
 * 
 * \retval      >0      The number of bytes returned in buf.
 * \retval      =0      The end of the input stream has been reached.
 * \retval      <0      An error occurred on the input stream.
 */
typedef int32_t (*alt_fpga_istream_t)(void* buf, size_t buf_len, void* user_data);

/*!
 * \addtogroup FPGA_MGR_CFG_FULL FPGA Full Configuration
 *
 * These functions manage full configuration of the FPGA fabric from HPS
 * software.
 *
 * @{
 */

/*!
 * Perform a full configuration of the FPGA from the specified configuration
 * bitstream located in addressable memory.
 *
 * Due to the nature of FPGA configuration, there may be intermittent and
 * recoverable errors during the process. When the API returns ALT_E_FPGA_CFG,
 * it is advisable to retry configuration up to 5 times. If the error still
 * persists, there may be an unrecoverable configuration error or a problem
 * with configuration image bitstream data.
 *
 * \internal
 * Source: FPGA Manager NPP, section 4.2.1.3 "Error handling and corrupted
 * configuration file"
 * \endinternal
 *
 * \param       cfg_buf
 *              A pointer to a buffer containing FPGA configuration bitstream
 *              data.
 *
 * \param       cfg_buf_len
 *              The length of the configuration bitstream data in bytes.
 *
 * \retval      ALT_E_SUCCESS           FPGA configuration was successful.
 * \retval      ALT_E_FPGA_CFG          FPGA configuration error detected.
 * \retval      ALT_E_FPGA_CRC          FPGA CRC error detected.
 * \retval      ALT_E_FPGA_PWR_OFF      FPGA is not powered on.
 * \retval      ALT_E_FPGA_NO_SOC_CTRL  SoC software is not in control of the
 *                                      FPGA. Use alt_fpga_control_enable() to
 *                                      gain control.
 */
ALT_STATUS_CODE alt_fpga_configure(const void* cfg_buf,
                                   size_t cfg_buf_len);

#if ALT_FPGA_ENABLE_DMA_SUPPORT

/*!
 * Perform a full configuration of the FPGA from the specified configuration
 * bitstream located in addressable memory using the DMA engine. Using DMA can
 * have a large performance benefit in FPGA programming time.
 *
 * Due to the nature of FPGA configuration, there may be intermittent and
 * recoverable errors during the process. When the API returns ALT_E_FPGA_CFG,
 * it is advisable to retry configuration up to 5 times. If the error still
 * persists, there may be an unrecoverable configuration error or a problem
 * with configuration image bitstream data.
 *
 * \internal
 * Source: FPGA Manager NPP, section 4.2.1.3 "Error handling and corrupted
 * configuration file"
 * \endinternal
 *
 * \param       cfg_buf
 *              A pointer to a buffer containing FPGA configuration bitstream
 *              data.
 *
 * \param       cfg_buf_len
 *              The length of the configuration bitstream data in bytes.
 *
 * \retval      ALT_E_SUCCESS           FPGA configuration was successful.
 * \retval      ALT_E_FPGA_CFG          FPGA configuration error detected.
 * \retval      ALT_E_FPGA_CRC          FPGA CRC error detected.
 * \retval      ALT_E_FPGA_PWR_OFF      FPGA is not powered on.
 * \retval      ALT_E_FPGA_NO_SOC_CTRL  SoC software is not in control of the
 *                                      FPGA. Use alt_fpga_control_enable() to
 *                                      gain control.
 * \retval      ALT_E_BAD_ARG           The user provided buffer is unaligned
 *                                      to the 32-bit boundary.
 */

ALT_STATUS_CODE alt_fpga_configure_dma(const void* cfg_buf,
                                       size_t cfg_buf_len,
                                       ALT_DMA_CHANNEL_t dma_channel);

#endif

/*!
 * Perform a full configuration of the FPGA from the user defined configuration
 * bitstream input source.
 *
 * Due to the nature of FPGA configuration, there may be intermittent and
 * recoverable errors during the process. When the API returns ALT_E_FPGA_CFG,
 * it is advisable to retry configuration up to 5 times. If the error still
 * persists, there may be an unrecoverable configuration error or a problem
 * with configuration image bitstream data.
 *
 * \internal
 * Source: FPGA Manager NPP, section 4.2.1.3 "Error handling and corrupted
 * configuration file"
 * \endinternal
 *
 * \param       cfg_stream
 *              A pointer to a callback function used to consecutively read
 *              configuration bitstream data from a user defined input stream.
 * 
 * \param       user_data
 *              A 32-bit user defined data word. The content of this parameter
 *              is user defined. The FPGA Manager merely forwards the \e
 *              user_data value when it invokes the \e cfg_stream callback.
 *
 * \retval      ALT_E_SUCCESS           FPGA configuration FPGA was successful.
 * \retval      ALT_E_FPGA_CFG          FPGA configuration error detected.
 * \retval      ALT_E_FPGA_CRC          FPGA CRC error detected.
 * \retval      ALT_E_FPGA_CFG_STM      An error occurred on the FPGA
 *                                      configuration bitstream input source.
 * \retval      ALT_E_FPGA_PWR_OFF      FPGA is not powered on.
 * \retval      ALT_E_FPGA_NO_SOC_CTRL  SoC software is not in control of the
 *                                      FPGA. Use alt_fpga_control_enable() to
 *                                      gain control.
 */
ALT_STATUS_CODE alt_fpga_istream_configure(alt_fpga_istream_t cfg_stream,
                                           void * user_data);

#if ALT_FPGA_ENABLE_DMA_SUPPORT

/*!
 * Perform a full configuration of the FPGA from the user defined configuration
 * bitstream input source using the DMA engine. Using DMA can have a large
 * performance benefit in FPGA programming time.
 *
 * Due to the nature of FPGA configuration, there may be intermittent and
 * recoverable errors during the process. When the API returns ALT_E_FPGA_CFG,
 * it is advisable to retry configuration up to 5 times. If the error still
 * persists, there may be an unrecoverable configuration error or a problem
 * with configuration image bitstream data.
 *
 * \internal
 * Source: FPGA Manager NPP, section 4.2.1.3 "Error handling and corrupted
 * configuration file"
 * \endinternal
 *
 * \param       cfg_stream
 *              A pointer to a callback function used to consecutively read
 *              configuration bitstream data from a user defined input stream.
 * 
 * \param       user_data
 *              A 32-bit user defined data word. The content of this parameter
 *              is user defined. The FPGA Manager merely forwards the \e
 *              user_data value when it invokes the \e cfg_stream callback.
 *
 * \retval      ALT_E_SUCCESS           FPGA configuration FPGA was successful.
 * \retval      ALT_E_FPGA_CFG          FPGA configuration error detected.
 * \retval      ALT_E_FPGA_CRC          FPGA CRC error detected.
 * \retval      ALT_E_FPGA_CFG_STM      An error occurred on the FPGA
 *                                      configuration bitstream input source.
 * \retval      ALT_E_FPGA_PWR_OFF      FPGA is not powered on.
 * \retval      ALT_E_FPGA_NO_SOC_CTRL  SoC software is not in control of the
 *                                      FPGA. Use alt_fpga_control_enable() to
 *                                      gain control.
 * \retval      ALT_E_BAD_ARG           The user provided buffer is unaligned
 *                                      to the 32-bit boundary.
 */
ALT_STATUS_CODE alt_fpga_istream_configure_dma(alt_fpga_istream_t cfg_stream,
                                               void * user_data,
                                               ALT_DMA_CHANNEL_t dma_channel);

#endif

/*!
 * @}
 */

/*!
 * @}
 */

/*!
 * \addtogroup FPGA_MGR_INT FPGA Manager Interrupt Control
 *
 * The functions in this group provide management of interrupts originating
 * from the FPGA Manager.
 *
 * The following interrupt request (IRQ) signal is sourced from the FPGA
 * Manager:
 *
 * * \b fpga_man_IRQ - FPGA Manager control block interrupt output. Provides
 *                     monitoring of the configuration and operational status
 *                     of the FPGA.  The interrupt signal assertion value is
 *                     the logical \e OR of twelve sources that monitor the
 *                     status of the FPGA control block (CB).  The twelve FPGA
 *                     CB interrupt sources are enumerated and described by the
 *                     type \ref ALT_FPGA_MON_STATUS_t.
 *
 *                     Each FPGA monitor status condition may be individually
 *                     disabled/enabled as a contributor to the determination
 *                     of the \b fpga_man_IRQ assertion status.
 *
 *                     The \b fpga_man_IRQ and its contributing FPGA monitor
 *                     status conditions are treated as a level sensitive
 *                     interrupt. As as consequence, there are no explicit
 *                     functions to explicitly clear an asserted FPGA monitor
 *                     status conditions.
 *
 * @{
 */

/*!
 * Disable the \b fpga_man_IRQ interrupt signal source monitor status
 * condition(s).
 *
 * This function disables one or more of the monitor status conditions as
 * contributors to the \b fpga_man_IRQ interrupt signal state.
 *
 * NOTE: A set bit for a monitor status condition in the mask value does not
 * have the effect of enabling it as a contributor to the \b fpga_man_IRQ
 * interrupt signal state. The function alt_fpga_man_irq_enable() is used to
 * enable monitor status source condition(s).
 *
 * \param       mon_stat_mask
 *              Specifies the monitor status conditions to disable as interrupt
 *              source contributors. \e mon_stat_mask is a mask of logically
 *              OR'ed ALT_FPGA_MON_STATUS_t values that designate the monitor
 *              status conditions to disable.
 *
 * \retval      ALT_E_SUCCESS   Successful status.
 * \retval      ALT_E_BAD_ARG   The \e mon_stat_mask argument contains an
 *                              unknown monitor status value.
 */
ALT_STATUS_CODE alt_fpga_man_irq_disable(ALT_FPGA_MON_STATUS_t mon_stat_mask);

/*!
 * Enable the \b fpga_man_IRQ interrupt signal source monitor status
 * condition(s).
 *
 * This function enables one or more of the monitor status conditions as
 * contributors to the \b fpga_man_IRQ interrupt signal state.
 *
 * NOTE: A cleared bit for any monitor status condition in the mask value does
 * not have the effect of disabling it as a contributor to the \b fpga_man_IRQ
 * interrupt signal state. The function alt_fpga_man_irq_disable() is used to
 * disable monitor status source condition(s).
 *
 * \param       mon_stat_mask
 *              Specifies the monitor status conditions to enable as interrupt
 *              source contributors. \e mon_stat_mask is a mask of logically
 *              OR'ed ALT_FPGA_MON_STATUS_t values that designate the monitor
 *              conditions to enable.
 *
 * \retval      ALT_E_SUCCESS   Successful status.
 * \retval      ALT_E_BAD_ARG   The \e mon_stat_mask argument contains an
 *                              unknown monitor status value.
 */
ALT_STATUS_CODE alt_fpga_man_irq_enable(ALT_FPGA_MON_STATUS_t mon_stat_mask);

/*!
 * @}
 */

/*!
 * \addtogroup FPGA_MGR_GPIO SoC to FPGA General Purpose I/O Signals
 *
 * These functions provide a simple, low-latency, low-performance signal
 * interface between the SoC and the FPGA.  There is a General Purpose Output
 * (GPO) register that provides a path to drive up to 32 signals from the SoC
 * to the FPGA.  There is a General Purpose Input (GPI) register that provides
 * a path to read up to 32 signals driven from the FPGA to the SoC.
 *
 * @{
 */

/*!
 * This type definition enumerates the signal mask selections for the General
 * Purpose Input (GPI) signals driven from the FPGA to the SoC.
 */
typedef enum ALT_FPGA_GPI_e
{
    /*! Signal driven from the FPGA fabric on f2s_gp[0] */
    ALT_FPGA_GPI_0  = (int32_t)(1UL <<  0),

    /*! Signal driven from the FPGA fabric on f2s_gp[1] */
    ALT_FPGA_GPI_1  = (int32_t)(1UL <<  1),

    /*! Signal driven from the FPGA fabric on f2s_gp[2] */
    ALT_FPGA_GPI_2  = (int32_t)(1UL <<  2),

    /*! Signal driven from the FPGA fabric on f2s_gp[3] */
    ALT_FPGA_GPI_3  = (int32_t)(1UL <<  3),

    /*! Signal driven from the FPGA fabric on f2s_gp[4] */
    ALT_FPGA_GPI_4  = (int32_t)(1UL <<  4),

    /*! Signal driven from the FPGA fabric on f2s_gp[5] */
    ALT_FPGA_GPI_5  = (int32_t)(1UL <<  5),

    /*! Signal driven from the FPGA fabric on f2s_gp[6] */
    ALT_FPGA_GPI_6  = (int32_t)(1UL <<  6),

    /*! Signal driven from the FPGA fabric on f2s_gp[7] */
    ALT_FPGA_GPI_7  = (int32_t)(1UL <<  7),

    /*! Signal driven from the FPGA fabric on f2s_gp[8] */
    ALT_FPGA_GPI_8  = (int32_t)(1UL <<  8),

    /*! Signal driven from the FPGA fabric on f2s_gp[9] */
    ALT_FPGA_GPI_9  = (int32_t)(1UL <<  9),

    /*! Signal driven from the FPGA fabric on f2s_gp[10] */
    ALT_FPGA_GPI_10 = (int32_t)(1UL << 10),

    /*! Signal driven from the FPGA fabric on f2s_gp[11] */
    ALT_FPGA_GPI_11 = (int32_t)(1UL << 11),

    /*! Signal driven from the FPGA fabric on f2s_gp[12] */
    ALT_FPGA_GPI_12 = (int32_t)(1UL << 12),

    /*! Signal driven from the FPGA fabric on f2s_gp[13] */
    ALT_FPGA_GPI_13 = (int32_t)(1UL << 13),

    /*! Signal driven from the FPGA fabric on f2s_gp[14] */
    ALT_FPGA_GPI_14 = (int32_t)(1UL << 14),

    /*! Signal driven from the FPGA fabric on f2s_gp[15] */
    ALT_FPGA_GPI_15 = (int32_t)(1UL << 15),

    /*! Signal driven from the FPGA fabric on f2s_gp[16] */
    ALT_FPGA_GPI_16 = (int32_t)(1UL << 16),

    /*! Signal driven from the FPGA fabric on f2s_gp[17] */
    ALT_FPGA_GPI_17 = (int32_t)(1UL << 17),

    /*! Signal driven from the FPGA fabric on f2s_gp[18] */
    ALT_FPGA_GPI_18 = (int32_t)(1UL << 18),

    /*! Signal driven from the FPGA fabric on f2s_gp[19] */
    ALT_FPGA_GPI_19 = (int32_t)(1UL << 19),

    /*! Signal driven from the FPGA fabric on f2s_gp[20] */
    ALT_FPGA_GPI_20 = (int32_t)(1UL << 20),

    /*! Signal driven from the FPGA fabric on f2s_gp[21] */
    ALT_FPGA_GPI_21 = (int32_t)(1UL << 21),

    /*! Signal driven from the FPGA fabric on f2s_gp[22] */
    ALT_FPGA_GPI_22 = (int32_t)(1UL << 22),

    /*! Signal driven from the FPGA fabric on f2s_gp[23] */
    ALT_FPGA_GPI_23 = (int32_t)(1UL << 23),

    /*! Signal driven from the FPGA fabric on f2s_gp[24] */
    ALT_FPGA_GPI_24 = (int32_t)(1UL << 24),

    /*! Signal driven from the FPGA fabric on f2s_gp[25] */
    ALT_FPGA_GPI_25 = (int32_t)(1UL << 25),

    /*! Signal driven from the FPGA fabric on f2s_gp[26] */
    ALT_FPGA_GPI_26 = (int32_t)(1UL << 26),

    /*! Signal driven from the FPGA fabric on f2s_gp[27] */
    ALT_FPGA_GPI_27 = (int32_t)(1UL << 27),

    /*! Signal driven from the FPGA fabric on f2s_gp[28] */
    ALT_FPGA_GPI_28 = (int32_t)(1UL << 28),

    /*! Signal driven from the FPGA fabric on f2s_gp[29] */
    ALT_FPGA_GPI_29 = (int32_t)(1UL << 29),

    /*! Signal driven from the FPGA fabric on f2s_gp[30] */
    ALT_FPGA_GPI_30 = (int32_t)(1UL << 30),

    /*! Signal driven from the FPGA fabric on f2s_gp[31] */
    ALT_FPGA_GPI_31 = (int32_t)(1UL << 31)

} ALT_FPGA_GPI_t;

/*!
 * Reads the General Purpose Input (GPI) register value.
 *
 * Returns the GPI register value that is the masked selection of the 32 \b
 * f2s_gp signal values driven by the FPGA. The \e mask may be defined by the
 * logical OR of \ref ALT_FPGA_GPI_t values.
 *
 * NOTE: If the FPGA is not in User Mode then the value of this register
 *       undefined.
 *
 * \param       mask
 *              The set of signals (where mask bits equal one) to read.  Other
 *              signals values (where mask bits equal zero) are returned as 0.
 *
 * \returns     Returns the GPI register value that is the masked selection of
 *              the 32 \b f2s_gp signals from the FPGA.
 */
uint32_t alt_fpga_gpi_read(uint32_t mask);

/*!
 * This type definition enumerates the signal mask selections for the General
 * Purpose Output (GPO) signals driven from the SoC to the FPGA.
 */
typedef enum ALT_FPGA_GPO_e
{
    /*! Signal driven from the FPGA fabric on s2f_gp[0] */
    ALT_FPGA_GPO_0  = (int32_t)(1UL <<  0),

    /*! Signal driven from the FPGA fabric on s2f_gp[1] */
    ALT_FPGA_GPO_1  = (int32_t)(1UL <<  1),

    /*! Signal driven from the FPGA fabric on s2f_gp[2] */
    ALT_FPGA_GPO_2  = (int32_t)(1UL <<  2),

    /*! Signal driven from the FPGA fabric on s2f_gp[3] */
    ALT_FPGA_GPO_3  = (int32_t)(1UL <<  3),

    /*! Signal driven from the FPGA fabric on s2f_gp[4] */
    ALT_FPGA_GPO_4  = (int32_t)(1UL <<  4),

    /*! Signal driven from the FPGA fabric on s2f_gp[5] */
    ALT_FPGA_GPO_5  = (int32_t)(1UL <<  5),

    /*! Signal driven from the FPGA fabric on s2f_gp[6] */
    ALT_FPGA_GPO_6  = (int32_t)(1UL <<  6),

    /*! Signal driven from the FPGA fabric on s2f_gp[7] */
    ALT_FPGA_GPO_7  = (int32_t)(1UL <<  7),

    /*! Signal driven from the FPGA fabric on s2f_gp[8] */
    ALT_FPGA_GPO_8  = (int32_t)(1UL <<  8),

    /*! Signal driven from the FPGA fabric on s2f_gp[9] */
    ALT_FPGA_GPO_9  = (int32_t)(1UL <<  9),

    /*! Signal driven from the FPGA fabric on s2f_gp[10] */
    ALT_FPGA_GPO_10 = (int32_t)(1UL << 10),

    /*! Signal driven from the FPGA fabric on s2f_gp[11] */
    ALT_FPGA_GPO_11 = (int32_t)(1UL << 11),

    /*! Signal driven from the FPGA fabric on s2f_gp[12] */
    ALT_FPGA_GPO_12 = (int32_t)(1UL << 12),

    /*! Signal driven from the FPGA fabric on s2f_gp[13] */
    ALT_FPGA_GPO_13 = (int32_t)(1UL << 13),

    /*! Signal driven from the FPGA fabric on s2f_gp[14] */
    ALT_FPGA_GPO_14 = (int32_t)(1UL << 14),

    /*! Signal driven from the FPGA fabric on s2f_gp[15] */
    ALT_FPGA_GPO_15 = (int32_t)(1UL << 15),

    /*! Signal driven from the FPGA fabric on s2f_gp[16] */
    ALT_FPGA_GPO_16 = (int32_t)(1UL << 16),

    /*! Signal driven from the FPGA fabric on s2f_gp[17] */
    ALT_FPGA_GPO_17 = (int32_t)(1UL << 17),

    /*! Signal driven from the FPGA fabric on s2f_gp[18] */
    ALT_FPGA_GPO_18 = (int32_t)(1UL << 18),

    /*! Signal driven from the FPGA fabric on s2f_gp[19] */
    ALT_FPGA_GPO_19 = (int32_t)(1UL << 19),

    /*! Signal driven from the FPGA fabric on s2f_gp[20] */
    ALT_FPGA_GPO_20 = (int32_t)(1UL << 20),

    /*! Signal driven from the FPGA fabric on s2f_gp[21] */
    ALT_FPGA_GPO_21 = (int32_t)(1UL << 21),

    /*! Signal driven from the FPGA fabric on s2f_gp[22] */
    ALT_FPGA_GPO_22 = (int32_t)(1UL << 22),

    /*! Signal driven from the FPGA fabric on s2f_gp[23] */
    ALT_FPGA_GPO_23 = (int32_t)(1UL << 23),

    /*! Signal driven from the FPGA fabric on s2f_gp[24] */
    ALT_FPGA_GPO_24 = (int32_t)(1UL << 24),

    /*! Signal driven from the FPGA fabric on s2f_gp[25] */
    ALT_FPGA_GPO_25 = (int32_t)(1UL << 25),

    /*! Signal driven from the FPGA fabric on s2f_gp[26] */
    ALT_FPGA_GPO_26 = (int32_t)(1UL << 26),

    /*! Signal driven from the FPGA fabric on s2f_gp[27] */
    ALT_FPGA_GPO_27 = (int32_t)(1UL << 27),

    /*! Signal driven from the FPGA fabric on s2f_gp[28] */
    ALT_FPGA_GPO_28 = (int32_t)(1UL << 28),

    /*! Signal driven from the FPGA fabric on s2f_gp[29] */
    ALT_FPGA_GPO_29 = (int32_t)(1UL << 29),

    /*! Signal driven from the FPGA fabric on s2f_gp[30] */
    ALT_FPGA_GPO_30 = (int32_t)(1UL << 30),

    /*! Signal driven from the FPGA fabric on s2f_gp[31] */
    ALT_FPGA_GPO_31 = (int32_t)(1UL << 31)

} ALT_FPGA_GPO_t;

/*!
 * Writes the General Purpose Output (GPO) register value.
 *
 * Writes the GPO data outputs with the specified values. The GPO drives the 32
 * \b s2f_gp signal values to the FPGA. Output signals are only written if
 * their corresponding mask bits are set.
 *
 * NOTE: If the FPGA is not in User Mode then the effect of this operation is 
 *       undefined.
 *
 * \param       mask
 *              The set of signals (where mask bits equal one) to write.  Other
 *              signals (where mask bits equal zero) are not changed. The \e
 *              mask may be defined by the logical OR of \ref ALT_FPGA_GPO_t
 *              values.
 *
 * \param       value
 *              The 32-bit aggregate GPO register value. Values for the
 *              corressponding signal bits specified in the \e mask are written
 *              to the FPGA signals.
 *
 * \retval      ALT_E_SUCCESS   Successful status.
 * \retval      ALT_E_ERROR     The write failed.
 */
ALT_STATUS_CODE alt_fpga_gpo_write(uint32_t mask, uint32_t value);

/*!
 * @}
 */

/*!
 * @}
 */

#ifdef __cplusplus
}
#endif  /* __cplusplus */

#endif  /* __ALT_FPGA_MGR_H__ */