path: root/c/src/lib/libbsp/arm/altera-cyclone-v/hwlib/include/alt_qspi.h

/******************************************************************************
*
* 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.
* 
******************************************************************************/

/******************************************************************************
* 
* !!!! Customer Be Aware, Exception!!!
*
* 1. Qspi Direct Access Mode is not working!
*
*    This is because the qspi flash memory installed on our DevKit board, Micro 
*    part N25Q00xx, 8 Gb, is not completely compatible with our embedded Synopsis 
*    QSPI controller IP. Therefore there is no viable direct access code offered
*    in the lib.  All the memory rea/write functionality is offered with indirect
*    access only.   
*
*    Should you install a different flash memory part in your custom board, and 
*    wondering wether direct access mode works, please contact with us.
* 
******************************************************************************/

/*! \file
 *  Altera - QSPI Flash Controller Module
 */

#ifndef __ALT_QSPI_H__
#define __ALT_QSPI_H__

#include <bsp/hwlib.h>

#ifdef __cplusplus
extern "C"
{
#endif  /* __cplusplus */

/******************************************************************************/
/*! \addtogroup ALT_QSPI QSPI Flash Controller Module
 *
 * This module defines a low level driver API for the hardware processor system
 * (HPS) quad serial peripheral interface (QSPI) flash controller for access to
 * serial NOR flash devices. The quad SPI flash controller supports standard SPI
 * flash devices as well as high-performance dual and quad SPI flash
 * devices.
 *
 * @{
 */

/******************************************************************************/
/*! \addtogroup ALT_QSPI_CSR General Control and Status Functions
 *
 * The declarations and functions in this group provide general purpose control
 * and status functions for the QSPI Flash Controller.
 *
 * @{
 */

/******************************************************************************/
/*!
 * Initialize the QSPI flash controller for use.
 *
 * \internal
 * Implementation Notes:
 *  * The QSPI Controller has been designed to wake up in a state that is
 *    suitable for performing basic reads and writes using the direct access
 *    controller.
 *  * Bring out of reset
 *  * QSPI reference clock validation
 *  * See Programmer's Guide, Configuring the QSPI Controller for use after
 *    reset, in QSPI_FLASH_CTRL for full initialization details.
 * \endinternal
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_init(void);

/******************************************************************************/
/*!
 * Uninitialize the QSPI flash controller.
 *
 * Uninitialize the QSPI flash controller by cancelling any indirect transfers
 * in progress and putting the QSPI controller into reset.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_uninit(void);

/******************************************************************************/
/*!
 * Disable the QSPI Controller.
 *
 * Disable the QSPI once the current transfer of the data word (FF_W) is
 * complete. All output enables are inactive and all pins are set to input 
 * mode.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_disable(void);

/******************************************************************************/
/*!
 * Enable the QSPI Controller.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_enable(void);

/******************************************************************************/
/*!
 * This type definition enumerates the interrupt status conditions for the QSPI
 * controller.
 *
 * The enumerations serve as masks for the QSPI controller events that can be
 * set when the designated conditions occur and the corresponding event is
 * enabled.  When any of these event source conditions are true, the \b
 * ALT_INT_INTERRUPT_QSPI_IRQ interrupt output is asserted high.
 *
 * Interrupt sources are cleared when software calls alt_qspi_int_clear(). The
 * interrupt sources are individually maskable using alt_qspi_int_disable() and
 * alt_qspi_int_enable().
 */
typedef enum ALT_QSPI_INT_STATUS_e
{
    /*!
     * Mode fail M - indicates the voltage on pin n_ss_in is inconsistent with
     * the SPI mode. Set = 1 if n_ss_in is low in master mode (multi-master
     * contention). These conditions will clear the spi_enable bit and disable
     * the SPI.
     *  * 0 = no mode fault has been detected.
     *  * 1 = a mode fault has occurred.
     */
    ALT_QSPI_INT_STATUS_MODE_FAIL         = (0x1 << 0),

    /*!
     * Underflow Detected.
     *  * 0 = no underflow has been detected.
     *  * 1 = underflow is detected and an attempt to transfer data is made
     *        when the small TX FIFO is empty. This may occur when AHB write
     *        data is being supplied too slowly to keep up with the requested
     *        write operation.
     */
    ALT_QSPI_INT_STATUS_UFL               = (0x1 << 1),

    /*!
     * Controller has completed last triggered indirect operation.
     */
    ALT_QSPI_INT_STATUS_IDAC_OP_COMPLETE  = (0x1 << 2),

    /*!
     * Indirect operation was requested but could not be accepted. Two indirect
     * operations already in storage.
     */
    ALT_QSPI_INT_STATUS_IDAC_OP_REJECT    = (0x1 << 3),

    /*!
     * Write to protected area was attempted and rejected.
     */
    ALT_QSPI_INT_STATUS_WR_PROT_VIOL      = (0x1 << 4),

    /*!
     * Illegal AHB Access Detected. AHB write wrapping bursts and the use of
     * SPLIT/RETRY accesses will cause this interrupt to trigger.
     */
    ALT_QSPI_INT_STATUS_ILL_AHB_ACCESS    = (0x1 << 5),

    /*!
     * Indirect Transfer Watermark Level Breached.
     */
    ALT_QSPI_INT_STATUS_IDAC_WTRMK_TRIG   = (0x1 << 6),

    /*!
     * Receive Overflow. This should only occur in Legacy SPI mode.
     *
     * Set if an attempt is made to push the RX FIFO when it is full. This bit
     * is reset only by a system reset and cleared only when this register is
     * read. If a new push to the RX FIFO occurs coincident with a register read
     * this flag will remain set.
     *  * 0 = no overflow has been detected.
     *  * 1 = an overflow has occurred.
     */
    ALT_QSPI_INT_STATUS_RX_OVF            = (0x1 << 7),

    /*!
     * Small TX FIFO not full (current FIFO status). Can be ignored in non-SPI
     * legacy mode.
     *  * 0 = FIFO has >= THRESHOLD entries.
     *  * 1 = FIFO has < THRESHOLD entries.
     */
    ALT_QSPI_INT_STATUS_TX_FIFO_NOT_FULL  = (0x1 << 8),

    /*!
     * Small TX FIFO full (current FIFO status). Can be ignored in non-SPI
     * legacy mode.
     *  * 0 = FIFO is not full.
     *  * 1 = FIFO is full.
     */
    ALT_QSPI_INT_STATUS_TX_FIFO_FULL      = (0x1 << 9),

    /*!
     * Small RX FIFO not empty (current FIFO status). Can be ignored in non-SPI
     * legacy mode.
     *  * 0 = FIFO has < RX THRESHOLD entries.
     *  * 1 = FIFO has >= THRESHOLD entries.
     */
    ALT_QSPI_INT_STATUS_RX_FIFO_NOT_EMPTY = (0x1 << 10),

    /*!
     * Small RX FIFO full (current FIFO status). Can be ignored in non-SPI
     * legacy mode.
     *  * 0 = FIFO is not full.
     *  * 1 = FIFO is full.
     */
    ALT_QSPI_INT_STATUS_RX_FIFO_FULL      = (0x1 << 11),

    /*!
     * Indirect Read partition of SRAM is full and unable to immediately
     * complete indirect operation.
     */
    ALT_QSPI_INT_STATUS_IDAC_RD_FULL      = (0x1 << 12)

} ALT_QSPI_INT_STATUS_t;

/******************************************************************************/
/*!
 * Returns the QSPI controller interrupt status register value.
 *
 * This function returns the current value of the QSPI controller interrupt
 * status register value which reflects the current QSPI controller status
 * conditions.
 *
 * \returns     The current value of the QSPI controller interrupt status
 *              register value which reflects the current QSPI controller status
 *              conditions as defined by the \ref ALT_QSPI_INT_STATUS_t mask.
 *              If the corresponding bit is set then the condition is asserted.
 */
uint32_t alt_qspi_int_status_get(void);

/******************************************************************************/
/*!
 * Clears the specified QSPI controller interrupt status conditions identified
 * in the mask.
 *
 * This function clears one or more of the status conditions as contributors to
 * the \b ALT_INT_INTERRUPT_QSPI_IRQ interrupt signal state.
 *
 * \param       mask
 *              Specifies the QSPI interrupt status conditions to clear.  \e
 *              mask is a mask of logically OR'ed \ref ALT_QSPI_INT_STATUS_t
 *              values that designate the status conditions to clear.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_int_clear(const uint32_t mask);

/******************************************************************************/
/*!
 * Disable the specified QSPI controller interrupt status conditions identified
 * in the mask.
 *
 * This function disables one or more of the status conditions as contributors
 * to the \b ALT_INT_INTERRUPT_QSPI_IRQ interrupt signal state.
 *
 * This API requires that the QSPI controller be idle, as determined by
 * alt_qspi_is_idle().
 *
 * NOTE: A cleared bit for any status condition in the mask value does not have
 * the effect of enabling it as a contributor to the \b
 * ALT_INT_INTERRUPT_QSPI_IRQ interrupt signal state. The function
 * alt_qspi_int_enable() is used to enable status source conditions.
 *
 * \param       mask
 *              Specifies the status conditions to disable as interrupt source
 *              contributors. \e mask is a mask of logically OR'ed
 *              \ref ALT_QSPI_INT_STATUS_t values that designate the status
 *              conditions to disable.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_int_disable(const uint32_t mask);

/******************************************************************************/
/*!
 * Enable the specified QSPI controller interrupt status conditions identified
 * in the mask.
 *
 * This function enables one or more of the status conditions as contributors to
 * the \b ALT_INT_INTERRUPT_QSPI_IRQ interrupt signal state.
 *
 * This API requires that the QSPI controller be idle, as determined by
 * alt_qspi_is_idle().
 *
 * NOTE: A cleared bit for any status condition in the mask value does not have
 * the effect of disabling it as a contributor to the \b
 * ALT_INT_INTERRUPT_QSPI_IRQ interrupt signal state. The function
 * alt_qspi_int_disable() is used to disable status source conditions.
 *
 * \param       mask
 *              Specifies the status conditions to enable as interrupt source
 *              contributors. \e mask is a mask of logically OR'ed
 *              \ref ALT_QSPI_INT_STATUS_t values that designate the status
 *              conditions to enable.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_int_enable(const uint32_t mask);

/******************************************************************************/
/*!
 * Returns true the serial interface and QSPI pipeline is IDLE.
 *
 * \returns     Returns true the serial interface and QSPI pipeline is IDLE.
 */
bool alt_qspi_is_idle(void);

/*! @} */

/******************************************************************************/
/*! \addtogroup ALT_QSPI_GP_BLKIO General Purpose Block I/O
 *
 * The functions in this group provide general purpose block read and
 * write flash functions.
 *
 * \internal
 * These functions use Indirect Read/Write transfers to read and write block
 * data to the flash device. An outline of the operational flow for these
 * operations can be found in:
 * //depot/soc/hhp_sw/baremetal_fw/drivers/qspi/qspi.c
 * 
 * The general flow for an indirect block read is to call
 * qspi_configure_mode_indirect_read_start() to initiate the read transfer from
 * the flash device into the SRAM buffer and follow with a call to either
 * qpsi_write_sram_fifo_poll() or qspi_read_sram_fifo_irq() to copy the data
 * from SRAM into the user's buffer.
 * 
 * The general flow for an indirect block write is to call
 * qspi_configure_mode_indirect_write_start() to initiate the write transfer
 * from the SRAM buffer to the flash device and follow with a call to either
 * qpsi_write_sram_fifo_poll() or qspi_write_sram_fifo_irq() to fill the SRAM
 * buffer with the user's data as space becomes available.
 * \endinternal
 *
 * @{
 */

/******************************************************************************/
/*!
 * Read a block of data from the specified flash address.
 *
 * Reads a block of \e n data bytes from the flash \e src address into the user
 * supplied \e dest buffer. The memory address, flash address, and size must be
 * word aligned.
 *
 * \param       dest
 *              The address of a caller supplied destination buffer large enough
 *              to contain the requested block of flash data.
 *
 * \param       src
 *              The flash device address to start reading data from.
 *
 * \param       size
 *              The requested number of data bytes to read from the flash device.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_read(void * dest, uint32_t src, size_t size);

/******************************************************************************/
/*!
 * Write a block of data to the specified flash address.
 *
 * Writes a block of \e n data bytes to the flash \e dest address from the
 * designated \e src buffer. The applicable destination flash address range
 * should have been erased prior to calling this function. The flash address,
 * memory address, and size must be word aligned.
 *
 * \param       dest
 *              The destination flash address to begin writing data to.
 *
 * \param       src
 *              The source address to start writing data from.
 *
 * \param       size
 *              The requested number of data bytes to write to the flash device.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_write(uint32_t dest, const void * src, size_t size);

/*! @} */

/******************************************************************************/
/*! \addtogroup ALT_QSPI_DEV_CFG Flash Device Configuration
 *
 * The declarations and functions in this group are used to configure the QSPI
 * controller interface to external flash devices.
 *
 * The following steps describe how to initialize and configure the
 * QSPI controller to operate with a flash device.
 *
 * * Wait until any pending QSPI operations have completed.
 * * Disable the QSPI controller using alt_qspi_disable().
 * * Configure the device for optimal read transaction performance using
 *   alt_qspi_device_read_config_set().
 * * Configure the device for optimal write transaction performance using
 *   alt_qspi_device_write_config_set().
 * * Enable (alt_qspi_mode_bit_disable()) or disable
 *   (alt_qspi_mode_bit_disable()) the mode bits per the device
 *   requirements. If mode bits are enabled, then configure the mode
 *   bit values using alt_qspi_mode_bit_config_set().
 * * Configure the device size and write protection information using
 *   alt_qspi_device_size_config_set().
 * * Configure the QSPI device delay and timing settings using
 *   alt_qspi_device_write_config_set().
 * * Configure the baud divisor setting to define the required clock frequency
 *   to the device using alt_qspi_baud_rate_div_set().
 * * Enable the QSPI controller using alt_qspi_enable().
 *
 * @{
 */

/******************************************************************************/
/*!
 * This type enumerates the operational modes the QSPI controller can be
 * configured for. It may apply to instruction, address, and/or data width
 * interactions between the QSPI controller and the flash device.
 */
typedef enum ALT_QSPI_MODE_e
{
  ALT_QSPI_MODE_SINGLE = 0,     /*!< Use Standard Single SPI (SIO-SPI) mode (bits 
                                 *   always transferred into the device on DQ0 
                                 *   only). Supported by all SPI flash devices.
                                 */
  ALT_QSPI_MODE_DUAL   = 1,     /*!< Use Dual SPI (DIO-SPI) SPI mode where bits are
                                 *   transferred on DQ0 and DQ1.
                                 */
  ALT_QSPI_MODE_QUAD   = 2      /*!< Use Dual SPI (QIO-SPI) SPI mode where bits are
                                 *   transferred on DQ0, DQ1, DQ3, and DQ3.
                                 */
} ALT_QSPI_MODE_t;

/******************************************************************************/
/*!
 * This type enumerates the mode configurations available for driving the
 * ss_n[3:0] device chip selects.  The chip selects may be controlled as either
 * in a '1 of 4' or '4 to 16 decode' mode.
 */
typedef enum ALT_QSPI_CS_MODE_e
{
  ALT_QSPI_CS_MODE_SINGLE_SELECT = 0,   /*!< Select 1 of 4 chip select ss_n[3:0]
                                         */
  ALT_QSPI_CS_MODE_DECODE        = 1    /*!< Select external 4 to 16 decode of
                                         *   ss_n[3:0].
                                         */
} ALT_QSPI_CS_MODE_t;

/******************************************************************************/
/*!
 * This type enumerates the QSPI controller master baud rate divisor selections.
 */
typedef enum ALT_QSPI_BAUD_DIV_e
{
  ALT_QSPI_BAUD_DIV_2            = 0x0, /*!< Divide by 2 */
  ALT_QSPI_BAUD_DIV_4            = 0x1, /*!< Divide by 4 */
  ALT_QSPI_BAUD_DIV_6            = 0x2, /*!< Divide by 6 */
  ALT_QSPI_BAUD_DIV_8            = 0x3, /*!< Divide by 8 */
  ALT_QSPI_BAUD_DIV_10           = 0x4, /*!< Divide by 10 */
  ALT_QSPI_BAUD_DIV_12           = 0x5, /*!< Divide by 12 */
  ALT_QSPI_BAUD_DIV_14           = 0x6, /*!< Divide by 14 */
  ALT_QSPI_BAUD_DIV_16           = 0x7, /*!< Divide by 16 */
  ALT_QSPI_BAUD_DIV_18           = 0x8, /*!< Divide by 18 */
  ALT_QSPI_BAUD_DIV_20           = 0x9, /*!< Divide by 20 */
  ALT_QSPI_BAUD_DIV_22           = 0xA, /*!< Divide by 22 */
  ALT_QSPI_BAUD_DIV_24           = 0xB, /*!< Divide by 24 */
  ALT_QSPI_BAUD_DIV_26           = 0xC, /*!< Divide by 26 */
  ALT_QSPI_BAUD_DIV_28           = 0xD, /*!< Divide by 28 */
  ALT_QSPI_BAUD_DIV_30           = 0xE, /*!< Divide by 30 */
  ALT_QSPI_BAUD_DIV_32           = 0xF  /*!< Divide by 32 */
} ALT_QSPI_BAUD_DIV_t;

/******************************************************************************/
/*!
 * Device Size Configuration
 *
 * This type defines the structure used to specify flash device size and write
 * protect regions.
 */
typedef struct ALT_QSPI_DEV_SIZE_CONFIG_s
{
  uint32_t      block_size;         /*!< Number of bytes per device block. The
                                     *   number is specified as a power of 2.
                                     *   That is 0 = 1 byte, 1 = 2 bytes, ...
                                     *   16 = 65535 bytes, etc.
                                     */
  uint32_t      page_size;          /*!< Number of bytes per device page.  This
                                     *   is required by the controller for
                                     *   performing flash writes up to and
                                     *   across page boundaries.
                                     */
  uint32_t      addr_size;          /*!< Number of bytes used for the flash
                                     *   address. The value is \e n + 1
                                     *   based. That is 0 = 1 byte, 1 = 2 bytes,
                                     *   2 = 3 bytes, 3 = 4 bytes.
                                     */
  uint32_t      lower_wrprot_block; /*!< The block number that defines the lower
                                     *   block in the range of blocks that is
                                     *   protected from writing. This field
                                     *   is ignored it write protection is 
                                     *   disabled.
                                     */
  uint32_t      upper_wrprot_block; /*!< The block number that defines the upper
                                     *   block in the range of blocks that is
                                     *   protected from writing. This field
                                     *   is ignored it write protection is 
                                     *   disabled.
                                     */
  bool          wrprot_enable;      /*!< The write region enable value. A value
                                     *   of \b true enables write protection
                                     *   on the region specified by the
                                     *   \e lower_wrprot_block and
                                     *   \e upper_wrprot_block range.
                                     */
} ALT_QSPI_DEV_SIZE_CONFIG_t;

/******************************************************************************/
/*!
 * This type enumerates the QSPI clock phase activity options outside the SPI
 * word.
 */
typedef enum ALT_QSPI_CLK_PHASE_e
{
  ALT_QSPI_CLK_PHASE_ACTIVE     = 0,    /*!< The SPI clock is active outside the
                                         *   word
                                         */
  ALT_QSPI_CLK_PHASE_INACTIVE   = 1     /*!< The SPI clock is inactive outside the
                                         *   word
                                         */
} ALT_QSPI_CLK_PHASE_t;

/******************************************************************************/
/*!
 * This type enumerates the QSPI clock polarity options outside the SPI word.
 */
typedef enum ALT_QSPI_CLK_POLARITY_e
{
  ALT_QSPI_CLK_POLARITY_LOW     = 0,    /*!< SPI clock is quiescent low outside the
                                         *   word.
                                         */
  ALT_QSPI_CLK_POLARITY_HIGH    = 1     /*!< SPI clock is quiescent high outside the
                                         *   word.
                                         */
} ALT_QSPI_CLK_POLARITY_t;

/******************************************************************************/
/*!
 * QSPI Controller Timing Configuration
 *
 * This type defines the structure used to configure timing paramaters used by
 * the QSPI controller to communicate with a target flash device.
 *
 * All timing values are defined in cycles of the SPI master ref clock.
 */
typedef struct ALT_QSPI_TIMING_CONFIG_s
{
  ALT_QSPI_CLK_PHASE_t      clk_phase;  /*!< Selects whether the clock is in an
                                         *   active or inactive phase outside the
                                         *   SPI word.
                                         */

  ALT_QSPI_CLK_POLARITY_t   clk_pol;    /*!< Selects whether the clock is quiescent
                                         *   low or high outside the SPI word.
                                         */

  uint32_t                  cs_da;      /*!< Chip Select De-Assert. Added delay in
                                         *   master reference clocks for the length
                                         *   that the master mode chip select
                                         *   outputs are de-asserted between
                                         *   transactions. If CSDA = \e X, then the
                                         *   chip select de-assert time will be: 1
                                         *   sclk_out + 1 ref_clk + \e X ref_clks.
                                         */
  uint32_t                  cs_dads;    /*!< Chip Select De-Assert Different
                                         *   Slaves. Delay in master reference
                                         *   clocks between one chip select being
                                         *   de-activated and the activation of
                                         *   another. This is used to ensure a quiet
                                         *   period between the selection of two
                                         *   different slaves.  CSDADS is only
                                         *   relevant when switching between 2
                                         *   different external flash devices. If
                                         *   CSDADS = \e X, then the delay will be:
                                         *   1 sclk_out + 3 ref_clks + \e X
                                         *   ref_clks.
                                         */
  uint32_t                  cs_eot;     /*!< Chip Select End Of Transfer. Delay in
                                         *   master reference clocks between last
                                         *   bit of current transaction and
                                         *   de-asserting the device chip select
                                         *   (n_ss_out). By default (when CSEOT=0),
                                         *   the chip select will be de-asserted on
                                         *   the last falling edge of sclk_out at
                                         *   the completion of the current
                                         *   transaction. If CSEOT = \e X, then chip
                                         *   selected will de-assert \e X ref_clks
                                         *   after the last falling edge of
                                         *   sclk_out.
                                         */
  uint32_t                  cs_sot;     /*!< Chip Select Start Of Transfer. Delay in
                                         *   master reference clocks between setting
                                         *   n_ss_out low and first bit transfer. By
                                         *   default (CSSOT=0), chip select will be
                                         *   asserted half a SCLK period before the
                                         *   first rising edge of sclk_out. If CSSOT
                                         *   = \e X, chip select will be asserted
                                         *   half an sclk_out period before the
                                         *   first rising edge of sclk_out + \e X
                                         *   ref_clks.
                                         */

  uint32_t                  rd_datacap; /*!< The additional number of read data
                                         *   capture cycles (ref_clk) that should be
                                         *   applied to the internal read data
                                         *   capture circuit.  The large
                                         *   clock-to-out delay of the flash memory
                                         *   together with trace delays as well as
                                         *   other device delays may impose a
                                         *   maximum flash clock frequency which is
                                         *   less than the flash memory device
                                         *   itself can operate at. To compensate,
                                         *   software should set this register to a
                                         *   value that guarantees robust data
                                         *   captures.
                                         */
} ALT_QSPI_TIMING_CONFIG_t;

/******************************************************************************/
/*!
 * Device Instruction Configuration
 *
 * This type defines a structure for specifying the optimal instruction set
 * configuration to use with a target flash device.
 */
typedef struct ALT_QSPI_DEV_INST_CONFIG_s
{
  uint32_t              op_code;            /*!< The read or write op code to use
                                             *   for the device transaction.
                                             */
  ALT_QSPI_MODE_t       inst_type;          /*!< Instruction mode type for the
                                             *   controller to use with the
                                             *   device. The instruction type
                                             *   applies to all instructions
                                             *   (reads and writes) issued from
                                             *   either the Direct Access
                                             *   Controller or the Indirect
                                             *   Acces Controller.
                                             */
  ALT_QSPI_MODE_t       addr_xfer_type;     /*!< Address transfer mode type. The
                                             *   value of this field is ignored
                                             *   if the \e inst_type data member
                                             *   is set to anything other than
                                             *   ALT_QSPI_MODE_SINGLE. In that
                                             *   case, the addr_xfer_type
                                             *   assumes the same mode as the \e
                                             *   inst_type.
                                             */
  ALT_QSPI_MODE_t       data_xfer_type;     /*!< Data transfer mode type. The
                                             *   value of this field is ignored
                                             *   if the \e inst_type data member
                                             *   is set to anything other than
                                             *   ALT_QSPI_MODE_SINGLE. In that
                                             *   case, the data_xfer_type
                                             *   assumes the same mode as the \e
                                             *   inst_type.
                                             */
  uint32_t              dummy_cycles;       /*!< Number of dummy clock cycles
                                             *   required by device for a read
                                             *   or write instruction.
                                             */

} ALT_QSPI_DEV_INST_CONFIG_t;

/******************************************************************************/
/*!
 * Get the current value of the QSPI master baud rate divisor.
 *
 * \returns     The value of the QSPI master baud rate divisor.
 */
ALT_QSPI_BAUD_DIV_t alt_qspi_baud_rate_div_get(void);

/******************************************************************************/
/*!
 * Set the current value of the QSPI master baud rate divisor.
 *
 * Sets the value of the QSPI master baud rate divisor.
 *
 * \param       baud_rate_div
 *              The master baud rate divisor. Valid range includes
 *              even values 2 to 32.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_baud_rate_div_set(const ALT_QSPI_BAUD_DIV_t baud_rate_div);

/******************************************************************************/
/*!
 * Get the current QSPI device peripheral chip select output and decode function
 * configuration values.
 *
 * \param       cs
 *              [out] The chip select line output values.
 *
 * \param       cs_mode
 *              [out] The decode mode to use for the chip selects.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_chip_select_config_get(uint32_t* cs, ALT_QSPI_CS_MODE_t* cs_mode);

/******************************************************************************/
/*!
 * Set the QSPI device peripheral chip select outputs and decode function
 * configuration.
 *
 * The chip select lines output values operate according to the selected chip
 * select decode mode. If \e cs_mode is ALT_QSPI_CS_MODE_SINGLE_SELECT then
 * cs[3:0] are output thus:
 *
 *  cs[3:0]  | n_ss_out[3:0]
 * :---------|:----------------------------
 *  xxx0     | 1110
 *  xx01     | 1101
 *  x011     | 1011
 *  0111     | 0111
 *  1111     | 1111 (no peripheral selected)
 *
 * Otherwise if \e cs_mode is ALT_QSPI_CS_MODE_DECODE then cs[3:0] directly
 * drives n_ss_out[3:0].
 *
 * \param       cs
 *              The chip select line output values.
 *
 * \param       cs_mode
 *              The decode mode to use for the chip selects.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_chip_select_config_set(const uint32_t cs,
                                                const ALT_QSPI_CS_MODE_t cs_mode);

/******************************************************************************/
/*!
 * Disable the mode bits from being sent after the address bytes.
 *
 * Prevent the mode bits defined in the Mode Bit Configuration register from
 * being sent following the address bytes.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_mode_bit_disable(void);

/******************************************************************************/
/*!
 * Enable the mode bits to be sent after the address bytes.
 *
 * Ensure the mode bits defined in the Mode Bit Configuration register to
 * be sent following the address bytes.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_mode_bit_enable(void);

/******************************************************************************/
/*!
 * Get the current value of the Mode Bit Configuration register.
 *
 * \returns     The 8 bit value that is sent to the device following the address
 *              bytes when the mode bit is enabled (see: alt_qspi_mode_bit_enable())
 */
uint32_t alt_qspi_mode_bit_config_get(void);

/******************************************************************************/
/*!
 * Set the value of the Mode Bit Configuration register.
 *
 * Set the value of the 8 bits that are sent to the device following the address
 * bytes when the mode bit is enabled (see: alt_qspi_mode_bit_enable())
 *
 * This API requires that the QSPI controller be idle, as determined by
 * alt_qspi_is_idle().
 *
 * \param       mode_bits
 *              The 8 bit value sent to the device following the address bytes.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_mode_bit_config_set(const uint32_t mode_bits);

/******************************************************************************/
/*!
 * Get the current flash device size and write protection configuration.
 *
 * \param       cfg
 *              [out] Pointer to a ALT_QSPI_DEV_SIZE_CONFIG_t structure to
 *              contain the returned flash device size and write protection
 *              configuration.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_device_size_config_get(ALT_QSPI_DEV_SIZE_CONFIG_t * cfg);

/******************************************************************************/
/*!
 * Set the flash device size and write protection configuration.
 *
 * \param       cfg
 *              Pointer to a ALT_QSPI_DEV_SIZE_CONFIG_t structure containing the
 *              flash device size and write protection configuration.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_device_size_config_set(const ALT_QSPI_DEV_SIZE_CONFIG_t * cfg);

/******************************************************************************/
/*!
 * Get the current QSPI device read instruction configuration.
 *
 * \param       cfg
 *              [out] Pointer to a ALT_QSPI_DEV_INST_CONFIG_t structure to
 *              contain the returned QSPI controller instruction configuration
 *              used when performing read transactions with the device.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_device_read_config_get(ALT_QSPI_DEV_INST_CONFIG_t * cfg);

/******************************************************************************/
/*!
 * Set the QSPI device read instruction configuration.
 *
 * This API requires that the QSPI controller be idle, as determined by
 * alt_qspi_is_idle().
 *
 * \param       cfg
 *              Pointer to a ALT_QSPI_DEV_INST_CONFIG_t structure specifying the
 *              desired op code, transfer widths, and dummy cycles for the QSPI
 *              controller to use when performing read transactions with the
 *              device.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_device_read_config_set(const ALT_QSPI_DEV_INST_CONFIG_t * cfg);

/******************************************************************************/
/*!
 * Get the current QSPI device write instruction configuration.
 *
 * \param       cfg
 *              [out] Pointer to a ALT_QSPI_DEV_INST_CONFIG_t structure to
 *              contain the returned QSPI controller instruction configuration
 *              used when performing write transactions with the device.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_device_write_config_get(ALT_QSPI_DEV_INST_CONFIG_t * cfg);

/******************************************************************************/
/*!
 * Set the QSPI device write instruction configuration.
 *
 * This API requires that the QSPI controller be idle, as determined by
 * alt_qspi_is_idle().
 *
 * \param       cfg
 *              Pointer to a ALT_QSPI_DEV_INST_CONFIG_t structure specifying the
 *              desired op code, transfer widths, and dummy cycles for the QSPI
 *              controller to use when performing write transactions with the
 *              device.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_device_write_config_set(const ALT_QSPI_DEV_INST_CONFIG_t * cfg);

/******************************************************************************/
/*!
 * Get the QSPI device delay and timing configuration parameters.
 *
 * This function returns the settings of the chip select delay and timing
 * configurations.
 *
 * \param       cfg
 *              [out] Pointer to a ALT_QSPI_TIMING_CONFIG_t structure to return
 *              the device timing and delay settings.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_timing_config_get(ALT_QSPI_TIMING_CONFIG_t * cfg);

/******************************************************************************/
/*!
 * Set the QSPI device delay and timing configuration parameters.
 *
 * This function allows the user to configure how the chip select is driven
 * after each flash access. This is required as each device may have different
 * timing requirements.  As the serial clock frequency is increased, these
 * timing parameters become more important and can be adjusted to meet the
 * requirements of a specific flash device.  All timings are defined in cycles
 * of the SPI master ref clock.
 *
 * This API requires that the QSPI controller be idle, as determined by
 * alt_qspi_is_idle().
 *
 * \param       cfg
 *              Pointer to a ALT_QSPI_TIMING_CONFIG_t structure specifying the
 *              desired timing and delay settings.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_timing_config_set(const ALT_QSPI_TIMING_CONFIG_t * cfg);

/*! @} */

/******************************************************************************/
/*! \addtogroup ALT_QSPI_DAC Direct Access Mode
 *
 * In direct access mode, an access to the AHB data slave triggers a read or
 * write command to the flash memory. To use the direct access mode, enable the
 * direct access controller with the alt_qspi_direct_enable() function. An
 * external master, for example a processor, triggers the direct access
 * controller with a read or write operation to the AHB data slave
 * interface. The data slave exposes a 1MB window into the flash device. You can
 * remap this window to any 1MB location within the flash device address range.
 *
 * To remap the AHB data slave to access other 1MB regions of the flash device,
 * enable address remapping by calling alt_qspi_ahb_address_remap_enable(). All
 * incoming data slave accesses remap to the offset specified in the remap
 * address register which is configured by alt_qspi_ahb_remap_address_set().
 *
 * The 20 LSBs of incoming addresses are used for accessing the 1MB region and
 * the higher bits are ignored.
 *
 * The quad SPI controller does not issue any error status for accesses that lie
 * outside the connected flash memory space.
 *
 * @{
 */

/******************************************************************************/
/*!
 * Disable the QSPI Direct Access Controller.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_direct_disable(void);

/******************************************************************************/
/*!
 * Enable the QSPI Direct Access Controller.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_direct_enable(void);

/******************************************************************************/
/*!
 * Get the current AHB address remap value.
 *
 * Returns the current value of the AHB remap address register.
 *
 * \returns     The value used to remap an incoming AHB address to a
 *              different address used by the flash device.
 */
uint32_t alt_qspi_ahb_remap_address_get(void);

/******************************************************************************/
/*!
 * Set the AHB address remap value.
 *
 * Sets the value of the AHB remap address register.
 *
 * This API requires that the QSPI controller be idle, as determined by
 * alt_qspi_is_idle().
 *
 * \param       ahb_remap_addr
 *              The value used to remap an incoming AHB address to a different
 *              address used by the flash device.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_ahb_remap_address_set(const uint32_t ahb_remap_addr);

/******************************************************************************/
/*!
 * Disable AHB address remapping.
 *
 * Disables remapping of incoming AHB addresses so they are sent unmodified to
 * the flash device. The incoming AHB address maps directly to the address
 * serially sent to the flash device.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_ahb_address_remap_disable(void);

/******************************************************************************/
/*!
 * Enable AHB address remapping.
 *
 * Enables remapping of incoming AHB addresses so they are modified to 
 * \<address\> + \e N, where \e N is the configured remap address value. 
 *
 * See: alt_qspi_ahb_remap_address_set().
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_ahb_address_remap_enable(void);

/*! @} */

/******************************************************************************/
/*! \addtogroup ALT_QSPI_INDAC Indirect Access Mode
 *
 * In indirect access mode, flash data is temporarily buffered in the QSPI
 * controller's SRAM. Software controls and triggers indirect accesses through
 * the APB register slave interface. The controller transfers data through the
 * AHB data slave interface.
 *
 * An indirect read operation reads data from the flash memory, places the data
 * into the SRAM, and transfers the data to an external master through the AHB
 * data slave interface.
 *
 * An indirect write operation programs data from the SRAM to the flash memory.
 *
 * @{
 */

/******************************************************************************/
/*!
 * Starts an indirect read transfer.
 *
 * Initiates an indirect read transfer of the requested number of bytes from the
 * designated flash address.
 *
 * After calling this function, flash data may be read from the QSPI SRAM buffer
 * as it becomes available via one of the following methods:
 *  * Directly from the AHB data slave interface at the configured AHB trigger
 *    address. If the requested data is not immediately available in the SRAM
 *    buffer then AHB wait states will be applied until the data has been read
 *    from flash into the SRAM buffer. Alternatively, data may be read from the
 *    AHB data slave as the SRAM is filled. The availability of data in the SRAM
 *    buffer may be determined by an SRAM watermark interrupt notification or by
 *    polling the SRAM fill level.
 *  * Configuring and enabling the QSPI DMA peripheral controller.
 *
 * The following is a list of restrictions:
 *  * flash_addr must be word aligned.
 *  * num_bytes must be word aligned.
 *  * The transfer must not cross the 3-byte addressing boundary. This
 *    restriction may be device specific and may be lifted in the future.
 *
 * \param       flash_addr
 *              The flash source address to read data from.
 *
 * \param       num_bytes
 *              The number of bytes to read from the flash source address.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_indirect_read_start(const uint32_t flash_addr,
                                             const size_t num_bytes);

/******************************************************************************/
/*!
 * Finish the indirect read operation that was completed or canceled. This
 * function should be called before another indirect read is started.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_indirect_read_finish(void);

/******************************************************************************/
/*!
 * Cancel all indirect read transfers in progress.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_indirect_read_cancel(void);

/******************************************************************************/
/*!
 * Get the current indirect read SRAM fill level value.
 *
 * Returns the SRAM fill level for the indirect read partition in units of SRAM
 * words (4 bytes).
 *
 * \returns     The SRAM fill level for the indirect read partition in units of 
 *              SRAM words (4 bytes).
 */
uint32_t alt_qspi_indirect_read_fill_level(void);

/******************************************************************************/
/*!
 * Get the current indirect read watermark value.
 *
 * The watermark value (in bytes) represents the minimum fill level of the SRAM
 * before a DMA peripheral access is permitted. When the SRAM fill level passes
 * the watermark, an interrupt source is also generated. This can be disabled by
 * writing a value of all zeroes.
 *
 * \returns     The current indirect read watermark value.
 */
uint32_t alt_qspi_indirect_read_watermark_get(void);

/******************************************************************************/
/*!
 * Set the indirect read watermark value.
 *
 * The watermark value (in bytes) represents the minimum fill level of the SRAM
 * before a DMA peripheral access is permitted. When the SRAM fill level passes
 * the watermark, an interrupt source is also generated. This can be disabled by
 * writing a value of all zeroes. The watermark can only be set when no indirect
 * read is in progress.
 *
 * \param       watermark
 *              The watermark value (in bytes).
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_indirect_read_watermark_set(const uint32_t watermark);

/******************************************************************************/
/*!
 * Returns true when an indirect read has completed otherwise false.
 *
 * \internal
 * Returns Indirect Read Transfer Control Register bit 5 "Indirect Completion Status".
 * \endinternal
 *
 * \returns     Returns true when an indirect read has completed otherwise false.
 */
bool alt_qspi_indirect_read_is_complete(void);

/******************************************************************************/
/*!
 * Starts an indirect write transfer.
 *
 * Initiates an indirect write transfer of the requested number of bytes to the
 * designated flash address.
 *
 * After calling this function, flash data may be written to the QSPI SRAM
 * buffer there is space via one of the following methods:
 *  * Directly from the AHB data slave interface at the configured AHB trigger
 *    address. If the requested space is not immediately available in the SRAM
 *    buffer then AHB wait states will be applied until the space becomes
 *    available. Alternatively, the data may be written to the AHB data slave
 *    as the SRAM is drained. The space in the SRAM buffer may be determined by
 *    an SRAM watermark interrupt notification or by polling the SRAM fill
 *    level and subtracting that value from the SRAM space devoted to writes.
 *  * Configuring and enabling the QSPI DMA peripheral controller.
 *
 * The following is a list of restrictions:
 *  * flash_addr must be word aligned.
 *  * num_bytes must be word aligned.
 *  * num_bytes must be 256 or below. This is due to a device specific
 *    limitation and may be lifted in the future.
 *  * The transfer must not cross the page (256 byte) addressing boundary. This
 *    restriction may be device specific and may be lifted in the future.
 *
 * \param       flash_addr
 *              The flash destination address to write data to.
 *
 * \param       num_bytes
 *              The number of bytes to write to the flash.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_indirect_write_start(const uint32_t flash_addr,
                                              const size_t num_bytes);

/******************************************************************************/
/*!
 * Finish the indirect write operation that was completed or canceled. This
 * function should be called before another indirect write is started.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_indirect_write_finish(void);

/******************************************************************************/
/*!
 * Cancel all indirect write transfers in progress.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_indirect_write_cancel(void);

/******************************************************************************/
/*!
 * Get the current indirect write SRAM fill level value.
 *
 * Returns the SRAM fill level for the indirect write partition in units of SRAM
 * words (4 bytes).
 *
 * \returns     The SRAM fill level for the indirect write partition in units of 
 *              SRAM words (4 bytes).
 */
uint32_t alt_qspi_indirect_write_fill_level(void);

/******************************************************************************/
/*!
 * Get the current indirect write watermark value.
 *
 * The watermark value (in bytes) represents the maximum fill level of the SRAM
 * before a DMA peripheral access is permitted.  When the SRAM fill level falls
 * below the watermark, an interrupt is also generated. This can be disabled by
 * writing a value of all ones.
 *
 * \returns     The current indirect write watermark value.
 */
uint32_t alt_qspi_indirect_write_watermark_get(void);

/******************************************************************************/
/*!
 * Set the indirect write watermark value.
 *
 * The watermark value (in bytes) represents the maximum fill level of the SRAM
 * before a DMA peripheral access is permitted.  When the SRAM fill level falls
 * below the watermark, an interrupt is also generated. This can be disabled by
 * writing a value of all ones. The watermark can only be set when no indirect
 * write is in progress.
 *
 * \param       watermark
 *              The watermark value (in bytes).
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_indirect_write_watermark_set(const uint32_t watermark);

/******************************************************************************/
/*!
 * Returns true when an indirect write has completed otherwise false.
 *
 * \internal
 * Returns Indirect Write Transfer Control Register bit 5 "Indirect Completion
 * Status".
 * \endinternal
 *
 * \returns     Returns true when an indirect write has completed otherwise
 *              false.
 */
bool alt_qspi_indirect_write_is_complete(void);

/******************************************************************************/
/*! \addtogroup ALT_QSPI_CFG_SRAM SRAM Partition
 *
 * The SRAM local memory buffer is a 128 by 32-bit (512 total bytes) memory. The
 * SRAM has two partitions, with the lower partition reserved for indirect read
 * operations and the upper partition for indirect write operations. The size of
 * the partitions is specified in the SRAM partition register, based on 32-bit
 * word sizes. For example, to specify four bytes of storage, write the value 1.
 * The value written to the indirect read partition size field ( addr ) defines
 * the number of entries reserved for indirect read operations. For example, write
 * the value 32 (0x20) to partition the 128-entry SRAM to 32 entries (25%) for
 * read usage and 96 entries (75%) for write usage.
 *
 * The functions in this section provide accces to configure the SRAM read
 * partition allocation.
 *
 * @{
 */

/*!
 * The size of the onboard SRAM in bytes.
 */
#define ALT_QSPI_SRAM_FIFO_SIZE           (512)

/*
 * The size of the onboard SRAM in entries. Each entry is word (32-bit) sized.
 */
#define ALT_QSPI_SRAM_FIFO_ENTRY_COUNT    (512 / sizeof(uint32_t))

/******************************************************************************/
/*!
 * Get the entry count (words) of the indirect read partition in the QSPI
 * controller SRAM.
 *
 * There is an additional word of read memory not in the SRAM but used to
 * buffer the SRAM and the AHB. As such, the total on board memory buffer for
 * indirect read is 1 more than the value reported by this function.
 *
 * \returns     The count of 32-bit words of the indirect read partition in the
 *              QSPI controller SRAM.
 *
 * \internal
 * The documentation states that the number of locations allocated to indirect
 * read = SRAM_PARTITION_REG + 1. Cadence clarified that the +1 comes from an
 * additional register slice for read's, implemented in FLOPs, which was done
 * to avoid connection the SRAM directly to the AHB interface. This was done
 * for performance / timing reasons. The +1 will not be included in the return
 * value but documented as an additional entry.
 * \endinternal
 */
uint32_t alt_qspi_sram_partition_get(void);

/******************************************************************************/
/*!
 * Set the entry count (words) of the indirect read partition in the QSPI
 * controller SRAM.
 *
 * Note: It is recommended that setting SRAM partition to 0 or 127 should be
 * avoided although it is not prohibited.
 *
 * \param       read_part_size
 *              The count of 32-bit words to allocate to the indirect read
 *              partition in the QSPI controller SRAM.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_sram_partition_set(const uint32_t read_part_size);

/*! @} */

/*! @} */

/******************************************************************************/
/*! \addtogroup ALT_QSPI_ERASE Flash Erase
 *
 * The functions in this group are used to erase selected portions of a flash
 * device.
 * @{
 */

/******************************************************************************/
/*!
 * This function erases the designated flash device subsector.
 *
 * This function erases the flash device subsector containing the designated
 * flash address. Any address within the subsector is valid.
 *
 * \param       addr
 *              A flash address contained within the the subsector to be erased.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_erase_subsector(const uint32_t addr);

/******************************************************************************/
/*!
 * This function erases the designated flash device sector.
 *
 * This function erases the flash device sector containing the designated flash
 * address. Any address within the sector is valid.
 *
 * \param       addr
 *              A flash address contained within the the sector to be erased.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_erase_sector(const uint32_t addr);

/******************************************************************************/
/*!
 * This function erases the entire flash device.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_erase_chip(void);

/*! @} */

/******************************************************************************/
/*! \addtogroup ALT_QSPI_DMA DMA Peripheral Interface
 *
 * The DMA peripheral request controller is only used for the indirect mode of
 * operation where data is temporarily stored in the SRAM. The QSPI flash
 * controller uses the DMA peripheral request interface to trigger the external
 * DMA into performing data transfers between memory and the QSPI
 * controller.
 *
 * There are two DMA peripheral request interfaces, one for indirect reads and
 * one for indirect writes. The DMA peripheral request controller can issue two
 * types of DMA requests, single or burst, to the external DMA. The number of
 * bytes for each single or burst request is specified using the
 * alt_qspi_dma_config_set(). The DMA peripheral request controller splits the
 * total amount of data to be transferred into a number of DMA burst and single
 * requests by dividing the total number of bytes by the number of bytes
 * specified in the burst request, and then dividing the remainder by the number
 * of bytes in a single request.
 *
 * When programming the DMA controller, the burst request size must match the
 * burst request size set in the quad SPI controller to avoid quickly reaching
 * an overflow or underflow condition.
 * @{
 */

/******************************************************************************/
/*!
 * Disable the QSPI DMA peripheral interface.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_dma_disable(void);

/******************************************************************************/
/*!
 * Enable the QSPI DMA peripheral interface.
 *
 * Enable the QSPI DMA handshaking logic. When enabled the QSPI will trigger DMA
 * transfer requests via the DMA peripheral interface.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_dma_enable(void);

/******************************************************************************/
/*!
 * Get the current DMA peripheral configuration.
 *
 * This function returns the QSPI DMA peripheral interface single and burst type
 * transfer size configurations.
 *
 * \param       single_type_sz
 *              [out] The number of bytes for each DMA single type
 *              request. Value must be a power of 2 between 1 and 32728.
 *
 * \param       burst_type_sz
 *              [out] The number of bytes for each DMA burst type request. Value
 *              must be a power of 2 between 1 and 32728.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_dma_config_get(uint32_t * single_type_sz,
                                        uint32_t * burst_type_sz);

/******************************************************************************/
/*!
 * Set the DMA peripheral configuration.
 *
 * This function configures the QSPI DMA peripheral interface single and burst
 * type transfer sizes.  The DMA configruation should be setup while the
 * controller is idle. Because all transfers are required to be word aligned,
 * the smallest DMA request is 4 bytes. 
 *
 * This API requires that the QSPI controller be idle, as determined by
 * alt_qspi_is_idle().
 *
 * \param       single_type_sz
 *              The number of bytes for each DMA single type request. Value must
 *              be a power of 2 between 4 and 32768.
 *
 * \param       burst_type_sz
 *              The number of bytes for each DMA burst type request. Value must
 *              be a power of 2 between 4 and 32768. Bursts must be equal or
 *              larger than single requests.
 *
 * \retval      ALT_E_SUCCESS   Indicates successful completion.
 * \retval      ALT_E_ERROR     Indicates an error occurred.
 */
ALT_STATUS_CODE alt_qspi_dma_config_set(const uint32_t single_type_sz,
                                        const uint32_t burst_type_sz);


/*! @} */

/*! @} */

#ifdef __cplusplus
}
#endif  /* __cplusplus */
#endif  /* __ALT_QSPI_H__ */