/******************************************************************************
 *
 * 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_DMA_PROGRAM_H__
#define __ALT_DMA_PROGRAM_H__

#include "hwlib.h"
#include "alt_dma_common.h"

#ifdef __cplusplus
extern "C"
{
#endif  /* __cplusplus */

/*!
 * \addtogroup ALT_DMA_PRG DMA Controller Programming API
 *
 * This API provides functions for dynamically defining and assembling microcode
 * programs for execution on the DMA controller.
 *
 * The microcode program assembly API provides users with the ability to develop
 * highly optimized and tailored algorithms for data transfer between SoC FPGA
 * IP blocks and/or system memory.
 *
 * The same microcode program assembly facilities are also used to implement the
 * functions found in the HWLIB Common DMA Operations functional API.
 *
 * An ALT_DMA_PROGRAM_t structure is used to contain and assemble a DMA
 * microcode program. The storage for an ALT_DMA_PROGRAM_t stucture is allocated
 * from used specified system memory. Once a microcode program has been
 * assembled in a ALT_DMA_PROGRAM_t it may be excecuted on a designated DMA
 * channel thread. The microcode program may be rerun on any DMA channel thread
 * whenever required as long as the integrity of the ALT_DMA_PROGRAM_t
 * containing the program is maintained.
 *
 * @{
 */

/*!
 * This preprocessor declares the DMA channel thread microcode instruction
 * cache line width in bytes. It is recommended that the program buffers be
 * sized to a multiple of the cache line size. This will allow for the most
 * efficient microcode speed and space utilization.
 */
#define ALT_DMA_PROGRAM_CACHE_LINE_SIZE     (32)

/*!
 * This preprocessor declares the DMA channel thread microcode instruction
 * cache line count. Thus the total size of the cache is the cache line size
 * multipled by the cache line count. Programs larger than the cache size risk
 * having a cache miss while executing.
 */
#define ALT_DMA_PROGRAM_CACHE_LINE_COUNT    (16)

/*!
 * This preprocessor definition determines the size of the program buffer
 * within the ALT_DMA_PROGRAM_t structure. This size should provide adequate
 * size for most DMA microcode programs. If calls within this API are
 * reporting out of memory response codes, consider increasing the provisioned
 * program buffersize.
 *
 * To specify another DMA microcode program buffer size, redefine the macro
 * below by defining ALT_DMA_PROGRAM_PROVISION_BUFFER_SIZE to another size in
 * your Makefile. It is recommended that the size be a multiple of the
 * microcode engine cache line size. See ALT_DMA_PROGRAM_CACHE_LINE_SIZE for
 * more information. The largest supported buffer size is 65536 bytes.
 */
#ifndef ALT_DMA_PROGRAM_PROVISION_BUFFER_SIZE
#define ALT_DMA_PROGRAM_PROVISION_BUFFER_SIZE   (ALT_DMA_PROGRAM_CACHE_LINE_SIZE * ALT_DMA_PROGRAM_CACHE_LINE_COUNT)
#endif

/*!
 * This type defines the structure used to assemble and contain a microcode
 * program which can be executed by the DMA controller. The internal members
 * are undocumented and should not be altered outside of this API.
 */
typedef struct ALT_DMA_PROGRAM_s
{
    uint32_t flag;

    uint16_t buffer_start;
    uint16_t code_size;

    uint16_t loop0;
    uint16_t loop1;

    uint16_t sar;
    uint16_t dar;

    /*
     * Add a little extra space so that regardless of where this structure
     * sits in memory, a suitable start address can be aligned to the cache
     * line stride while providing the requested buffer space.
     */
    uint8_t program[ALT_DMA_PROGRAM_PROVISION_BUFFER_SIZE +
                    ALT_DMA_PROGRAM_CACHE_LINE_SIZE];
}
ALT_DMA_PROGRAM_t;

/*!
 * This type definition enumerates the DMA controller register names for use in
 * microcode program definition.
 */
typedef enum ALT_DMA_PROGRAM_REG_e
{
    /*! Source Address Register */
    ALT_DMA_PROGRAM_REG_SAR = 0x0,

    /*! Destination Address Register */
    ALT_DMA_PROGRAM_REG_DAR = 0x2,

    /*! Channel Control Register */
    ALT_DMA_PROGRAM_REG_CCR = 0x1
}
ALT_DMA_PROGRAM_REG_t;

/*!
 * This type definition enumerates the instruction modifier options available
 * for use with selected DMA microcode instructions.
 *
 * The enumerations values are context dependent upon the instruction being
 * modified.
 *
 * For the <b>DMALD[S|B]</b>, <b>DMALDP\<S|B></b>, <b>DMAST[S|B]</b>, and
 * <b>DMASTP\<S|B></b> microcode instructions, the enumeration
 * ALT_DMA_PROGRAM_INST_MOD_SINGLE specifies the <b>S</b> option modifier
 * while the enumeration ALT_DMA_PROGRAM_INST_MOD_BURST specifies the <b>B</b>
 * option modifier. The enumeration ALT_DMA_PROGRAM_INST_MOD_NONE specifies
 * that no modifier is present for instructions where use of <b>[S|B]</b> is
 * optional.
 *
 * For the <b>DMAWFP</b> microcode instruction, the enumerations
 * ALT_DMA_PROGRAM_INST_MOD_SINGLE, ALT_DMA_PROGRAM_INST_MOD_BURST, or
 * ALT_DMA_PROGRAM_INST_MOD_PERIPH each specify one of the corresponding
 * options <b>\<single|burst|periph></b>.
 */
typedef enum ALT_DMA_PROGRAM_INST_MOD_e
{
    /*!
     * This DMA instruction modifier specifies that no special modifier is
     * added to the instruction.
     */
    ALT_DMA_PROGRAM_INST_MOD_NONE,

    /*!
     * Depending on the DMA microcode instruction modified, this modifier
     * specifies <b>S</b> case for a <b>[S|B]</b> or a <b>\<single></b> for a
     * <b>\<single|burst|periph></b>.
     */
    ALT_DMA_PROGRAM_INST_MOD_SINGLE,

    /*!
     * Depending on the DMA microcode instruction modified, this modifier
     * specifies <b>B</b> case for a <b>[S|B]</b> or a <b>\<burst></b> for a
     * <b>\<single|burst|periph></b>.
     */
    ALT_DMA_PROGRAM_INST_MOD_BURST,

    /*!
     * This DMA instruction modifier specifies a <b>\<periph></b> for a
     * <b>\<single|burst|periph></b>.
     */
    ALT_DMA_PROGRAM_INST_MOD_PERIPH
}
ALT_DMA_PROGRAM_INST_MOD_t;

/*!
 * This function initializes a system memory buffer for use as a DMA microcode
 * program buffer. This should be the first API call made on the program
 * buffer type.
 *
 * \param       pgm
 *              A pointer to a DMA program buffer structure.
 *
 * \retval      ALT_E_SUCCESS   The operation was successful.
 * \retval      ALT_E_ERROR     Details about error status code
 */
ALT_STATUS_CODE alt_dma_program_init(ALT_DMA_PROGRAM_t * pgm);

/*!
 * This function verifies that the DMA microcode program buffer is no longer
 * in use and performs any needed uninitialization steps.
 *
 * \param       pgm
 *              A pointer to a DMA program buffer structure.
 *
 * \retval      ALT_E_SUCCESS   The operation was successful.
 * \retval      ALT_E_ERROR     Details about error status code
 */
ALT_STATUS_CODE alt_dma_program_uninit(ALT_DMA_PROGRAM_t * pgm);

/*!
 * This function clears the existing DMA microcode program in the given
 * program buffer.
 *
 * \param       pgm
 *              A pointer to a DMA program buffer structure.
 *
 * \retval      ALT_E_SUCCESS   The operation was successful.
 * \retval      ALT_E_ERROR     Details about error status code.
 */
ALT_STATUS_CODE alt_dma_program_clear(ALT_DMA_PROGRAM_t * pgm);

/*!
 * This function validate that the given DMA microcode program buffer contains
 * a well formed program. If caches are enabled, the program buffer contents
 * will be cleaned to RAM.
 *
 * \param       pgm
 *              A pointer to a DMA program buffer structure.
 *
 * \retval      ALT_E_SUCCESS   The given program is well formed.
 * \retval      ALT_E_ERROR     The given program is not well formed.
 * \retval      ALT_E_TMO       The cache operation timed out.
 */
ALT_STATUS_CODE alt_dma_program_validate(const ALT_DMA_PROGRAM_t * pgm);

/*!
 * This function reports the number bytes incremented for the register
 * specified. The purpose is to determine the progress of an ongoing DMA
 * transfer.
 *
 * It is implemented by calculating the difference of the programmed SAR or DAR
 * with the current channel SAR or DAR register value.
 *
 * \param       pgm
 *              A pointer to a DMA program buffer structure.
 *
 * \param       channel
 *              The channel that the program is running on.
 *
 * \param       reg
 *              Register to change the value for. Valid for only
 *              ALT_DMA_PROGRAM_REG_SAR and ALT_DMA_PROGRAM_REG_DAR.
 *
 * \param       current
 *              The current snapshot value of the register read from the DMA
 *              channel.
 *
 * \param       progress
 *              [out] A pointer to a memory location that will be used to store
 *              the number of bytes transfered.
 *
 * \retval      ALT_E_SUCCESS   The operation was successful.
 * \retval      ALT_E_ERROR     Details about error status code.
 * \retval      ALT_E_BAD_ARG   The specified channel is invalid, the specified
 *                              register is invalid, or the DMAMOV for the
 *                              specified register has not yet been assembled
 *                              in the current program buffer.
 */
ALT_STATUS_CODE alt_dma_program_progress_reg(ALT_DMA_PROGRAM_t * pgm,
                                             ALT_DMA_PROGRAM_REG_t reg,
                                             uint32_t current, uint32_t * progress);

/*!
 * This function updates a pre-existing DMAMOV value affecting the SAR or DAR
 * registers. This allows for pre-assembled programs that can be used on
 * different source and destination addresses.
 *
 * \param       pgm
 *              A pointer to a DMA program buffer structure.
 *
 * \param       reg
 *              Register to change the value for. Valid for only
 *              ALT_DMA_PROGRAM_REG_SAR and ALT_DMA_PROGRAM_REG_DAR.
 *
 * \param       val
 *              The value to update to.
 *
 * \retval      ALT_E_SUCCESS   The operation was successful.
 * \retval      ALT_E_ERROR     Details about error status code.
 * \retval      ALT_E_BAD_ARG   The specified register is invalid or the DMAMOV
 *                              for the specified register has not yet been
 *                              assembled in the current program buffer.
 */
ALT_STATUS_CODE alt_dma_program_update_reg(ALT_DMA_PROGRAM_t * pgm,
                                           ALT_DMA_PROGRAM_REG_t reg, uint32_t val);

/*!
 */

/*!
 * Assembles a DMAADDH (Add Halfword) instruction into the microcode program
 * buffer. This instruction uses 3 bytes of buffer space.
 *
 * \param       pgm
 *              The DMA program buffer to contain the assembled instruction.
 *
 * \param       addr_reg
 *              The channel address register (ALT_DMA_PROGRAM_REG_DAR or
 *              ALT_DMA_PROGRAM_REG_SAR) to add the value to.
 *
 * \param       val
 *              The 16-bit unsigned value to add to the channel address
 *              register.
 *
 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
 * \retval      ALT_E_BAD_ARG       Invalid channel register specified.
 */
// Assembler Syntax: DMAADDH <address_register>, <16-bit immediate>
ALT_STATUS_CODE alt_dma_program_DMAADDH(ALT_DMA_PROGRAM_t * pgm,
                                        ALT_DMA_PROGRAM_REG_t addr_reg, uint16_t val);

/*!
 * Assembles a DMAADNH (Add Negative Halfword) instruction into the microcode
 * program buffer. This instruction uses 3 bytes of buffer space.
 *
 * \param       pgm
 *              The DMA programm buffer to contain the assembled instruction.
 *
 * \param       addr_reg
 *              The channel address register (ALT_DMA_PROGRAM_REG_DAR or
 *              ALT_DMA_PROGRAM_REG_SAR) to add the value to.
 *
 * \param       val
 *              The 16-bit unsigned value to add to the channel address
 *              register.
 *
 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
 * \retval      ALT_E_BAD_ARG       Invalid channel register specified.
 */
// Assembler Syntax: DMAADNH <address_register>, <16-bit immediate>
ALT_STATUS_CODE alt_dma_program_DMAADNH(ALT_DMA_PROGRAM_t * pgm,
                                        ALT_DMA_PROGRAM_REG_t addr_reg, uint16_t val);

/*!
 * Assembles a DMAEND (End) instruction into the microcode program buffer.
 * This instruction uses 1 byte of buffer space.
 *
 * \param       pgm
 *              The DMA programm buffer to contain the assembled instruction.
 *
 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
 */
// Assembler Syntax: DMAEND
ALT_STATUS_CODE alt_dma_program_DMAEND(ALT_DMA_PROGRAM_t * pgm);

/*!
 * Assembles a DMAFLUSHP (Flush Peripheral) instruction into the microcode
 * program buffer. This instruction uses 2 bytes of buffer space.
 *
 * \param       pgm
 *              The DMA programm buffer to contain the assembled instruction.
 *
 * \param       periph
 *              The peripheral to flush.
 *
 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
 * \retval      ALT_E_BAD_ARG       Invalid peripheral specified.
 */
// Assembler Syntax: DMAFLUSHP <peripheral>
ALT_STATUS_CODE alt_dma_program_DMAFLUSHP(ALT_DMA_PROGRAM_t * pgm,
                                          ALT_DMA_PERIPH_t periph);

/*!
 * Assembles a DMAGO (Go) instruction into the microcode program buffer. This
 * instruction uses 6 bytes of buffer space.
 *
 * \param       pgm
 *              The DMA programm buffer to contain the assembled instruction.
 *
 * \param       channel
 *              The stopped channel to act upon.
 *
 * \param       val
 *              The value to write to the channel program counter register.
 *
 * \param       sec
 *              The security state for the operation.
 *
 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
 * \retval      ALT_E_BAD_ARG       Invalid channel or security specified.
 */
// Assembler Syntax: DMAGO <channel_number>, <32-bit_immediate> [, ns]
ALT_STATUS_CODE alt_dma_program_DMAGO(ALT_DMA_PROGRAM_t * pgm,
                                      ALT_DMA_CHANNEL_t channel, uint32_t val,
                                      ALT_DMA_SECURITY_t sec);

/*!
 * Assembles a DMAKILL (Kill) instruction into the microcode program buffer.
 * This instruction uses 1 byte of buffer space.
 *
 * \param       pgm
 *              The DMA programm buffer to contain the assembled instruction.
 *
 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
 */
// Assembler Syntax: DMAKILL
ALT_STATUS_CODE alt_dma_program_DMAKILL(ALT_DMA_PROGRAM_t * pgm);

/*!
 * Assembles a DMALD (Load) instruction into the microcode program buffer.
 * This instruction uses 1 byte of buffer space.
 *
 * \param       pgm
 *              The DMA programm buffer to contain the assembled instruction.
 *
 * \param       mod
 *              The program instruction modifier for the type of transfer.
 *              Only ALT_DMA_PROGRAM_INST_MOD_SINGLE and 
 *              ALT_DMA_PROGRAM_INST_MOD_BURST are valid options.
 *
 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
 * \retval      ALT_E_BAD_ARG       Invalid instruction modifier specified.
 */
// Assembler Syntax: DMALD[S|B]
ALT_STATUS_CODE alt_dma_program_DMALD(ALT_DMA_PROGRAM_t * pgm,
                                      ALT_DMA_PROGRAM_INST_MOD_t mod);

/*!
 * Assembles a DMALDP (Load and notify Peripheral) instruction into the
 * microcode program buffer. This instruction uses 2 bytes of buffer space.
 *
 * \param       pgm
 *              The DMA programm buffer to contain the assembled instruction.
 *
 * \param       mod
 *              The program instruction modifier for the type of transfer.
 *              Only ALT_DMA_PROGRAM_INST_MOD_SINGLE and 
 *              ALT_DMA_PROGRAM_INST_MOD_BURST are valid options.
 *
 * \param       periph
 *              The peripheral to notify.
 *
 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
 * \retval      ALT_E_BAD_ARG       Invalid instruction modifier or peripheral
 *                                  specified.
 */
// Assembler Syntax: DMALDP<S|B> <peripheral>
ALT_STATUS_CODE alt_dma_program_DMALDP(ALT_DMA_PROGRAM_t * pgm,
                                       ALT_DMA_PROGRAM_INST_MOD_t mod, ALT_DMA_PERIPH_t periph);

/*!
 * Assembles a DMALP (Loop) instruction into the microcode program buffer.
 * This instruction uses 2 bytes of buffer space.
 *
 * \param       pgm
 *              The DMA programm buffer to contain the assembled instruction.
 *
 * \param       iterations
 *              The number of iterations to run for. Valid values are 1 - 256.
 *
 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
 * \retval      ALT_E_BAD_ARG       Invalid iterations specified.
 * \retval      ALT_E_BAD_OPERATION All loop registers are in use.
 */
// Assembler Syntax: DMALP [<LC0>|<LC1>] <loop_iterations>
ALT_STATUS_CODE alt_dma_program_DMALP(ALT_DMA_PROGRAM_t * pgm,
                                      uint32_t iterations);

/*!
 * Assembles a DMALPEND (Loop End) instruction into the microcode program
 * buffer. This instruction uses 2 bytes of buffer space.
 *
 * \param       pgm
 *              The DMA programm buffer to contain the assembled instruction.
 *
 * \param       mod
 *              The program instruction modifier for the loop terminator. Only
 *              ALT_DMA_PROGRAM_INST_MOD_NONE, ALT_DMA_PROGRAM_INST_MOD_SINGLE
 *              and ALT_DMA_PROGRAM_INST_MOD_BURST are valid options.
 *
 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
 * \retval      ALT_E_BAD_ARG       Invalid instruction modifier specified.
 * \retval      ALT_E_ARG_RANGE     Loop size is too large to be supported.
 * \retval      ALT_E_BAD_OPERATION A valid DMALP or DMALPFE was not added to
 *                                  the program buffer before adding this
 *                                  DMALPEND instruction.
 */
// Assembler Syntax: DMALPEND[S|B]
ALT_STATUS_CODE alt_dma_program_DMALPEND(ALT_DMA_PROGRAM_t * pgm,
                                         ALT_DMA_PROGRAM_INST_MOD_t mod);

/*!
 * Assembles a DMALPFE (Loop Forever) instruction into the microcode program
 * buffer. No instruction is added to the buffer but a previous DMALPEND to
 * create an infinite loop.
 *
 * \param       pgm
 *              The DMA programm buffer to contain the assembled instruction.
 *
 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
 */
// Assembler Syntax: DMALPFE
ALT_STATUS_CODE alt_dma_program_DMALPFE(ALT_DMA_PROGRAM_t * pgm);

/*!
 * Assembles a DMAMOV (Move) instruction into the microcode program buffer.
 * This instruction uses 6 bytes of buffer space.
 *
 * \param       pgm
 *              The DMA programm buffer to contain the assembled instruction.
 *
 * \param       chan_reg
 *              The channel non-looping register (ALT_DMA_PROGRAM_REG_SAR,
 *              ALT_DMA_PROGRAM_REG_DAR or ALT_DMA_PROGRAM_REG_CCR) to copy
 *              the value to.
 *
 * \param       val
 *              The value to write to the specified register.
 *
 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
 * \retval      ALT_E_BAD_ARG       Invalid channel register specified.
 */
// Assembler Syntax: DMAMOV <destination_register>, <32-bit_immediate>
ALT_STATUS_CODE alt_dma_program_DMAMOV(ALT_DMA_PROGRAM_t * pgm,
                                       ALT_DMA_PROGRAM_REG_t chan_reg, uint32_t val);

/*!
 * Assembles a DMANOP (No Operation) instruction into the microcode program
 * buffer. This instruction uses 1 byte of buffer space.
 *
 * \param       pgm
 *              The DMA programm buffer to contain the assembled instruction.
 *
 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
 */
// Assembler Syntax: DMANOP
ALT_STATUS_CODE alt_dma_program_DMANOP(ALT_DMA_PROGRAM_t * pgm);

/*!
 * Assembles a DMARMB (Read Memory Barrier) instruction into the microcode
 * program buffer. This instruction uses 1 byte of buffer space.
 *
 * \param       pgm
 *              The DMA programm buffer to contain the assembled instruction.
 *
 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
 */
// Assembler Syntax: DMARMB
ALT_STATUS_CODE alt_dma_program_DMARMB(ALT_DMA_PROGRAM_t * pgm);

/*!
 * Assembles a DMASEV (Send Event) instruction into the microcode program
 * buffer. This instruction uses 2 byte of buffer space.
 *
 * \param       pgm
 *              The DMA programm buffer to contain the assembled instruction.
 *
 * \param       evt
 *              The event to send.
 *
 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
 * \retval      ALT_E_BAD_ARG       Invalid event specified.
 */
// Assembler Syntax: DMASEV <event_num>
ALT_STATUS_CODE alt_dma_program_DMASEV(ALT_DMA_PROGRAM_t * pgm,
                                       ALT_DMA_EVENT_t evt);

/*!
 * Assembles a DMAST (Store) instruction into the microcode program buffer.
 * This instruction uses 1 byte of buffer space.
 *
 * \param       pgm
 *              The DMA programm buffer to contain the assembled instruction.
 *
 * \param       mod
 *              The program instruction modifier for the type of transfer.
 *              Only ALT_DMA_PROGRAM_INST_MOD_SINGLE and 
 *              ALT_DMA_PROGRAM_INST_MOD_BURST are valid options.
 *
 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
 */
// Assembler Syntax: DMAST[S|B]
ALT_STATUS_CODE alt_dma_program_DMAST(ALT_DMA_PROGRAM_t * pgm,
                                      ALT_DMA_PROGRAM_INST_MOD_t mod);

/*!
 * Assembles a DMASTP (Store and notify Peripheral) instruction into the
 * microcode program buffer. This instruction uses 2 bytes of buffer space.
 *
 * \param       pgm
 *              The DMA programm buffer to contain the assembled instruction.
 *
 * \param       mod
 *              The program instruction modifier for the type of transfer.
 *              Only ALT_DMA_PROGRAM_INST_MOD_SINGLE and 
 *              ALT_DMA_PROGRAM_INST_MOD_BURST are valid options.
 *
 * \param       periph
 *              The peripheral to notify.
 *
 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
 * \retval      ALT_E_BAD_ARG       Invalid instruction modifier or peripheral
 *                                  specified.
 */
// Assembler Syntax: DMASTP<S|B> <peripheral>
ALT_STATUS_CODE alt_dma_program_DMASTP(ALT_DMA_PROGRAM_t * pgm,
                                       ALT_DMA_PROGRAM_INST_MOD_t mod, ALT_DMA_PERIPH_t periph);

/*!
 * Assembles a DMASTZ (Store Zero) instruction into the microcode program
 * buffer. This instruction uses 1 byte of buffer space.
 *
 * \param       pgm
 *              The DMA programm buffer to contain the assembled instruction.
 *
 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
 */
// Assembler Syntax: DMASTZ
ALT_STATUS_CODE alt_dma_program_DMASTZ(ALT_DMA_PROGRAM_t * pgm);

/*!
 * Assembles a DMAWFE (Wait For Event) instruction into the microcode program
 * buffer. This instruction uses 2 byte of buffer space.
 *
 * \param       pgm
 *              The DMA programm buffer to contain the assembled instruction.
 *
 * \param       evt
 *              The event to wait for.
 *
 * \param       invalid
 *              If invalid is set to true, the instruction will be configured
 *              to invalidate the instruction cache for the current DMA
 *              thread.
 *
 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
 * \retval      ALT_E_BAD_ARG       Invalid event specified.
 */
// Assembler Syntax: DMAWFE <event_num>[, invalid]
ALT_STATUS_CODE alt_dma_program_DMAWFE(ALT_DMA_PROGRAM_t * pgm,
                                       ALT_DMA_EVENT_t evt, bool invalid);

/*!
 * Assembles a DMAWFP (Wait for Peripheral) instruction into the microcode
 * program buffer. This instruction uses 2 bytes of buffer space.
 *
 * \param       pgm
 *              The DMA programm buffer to contain the assembled instruction.
 *
 * \param       periph
 *              The peripheral to wait on.
 *
 * \param       mod
 *              The program instruction modifier for the type of transfer.
 *              Only ALT_DMA_PROGRAM_INST_MOD_SINGLE,
 *              ALT_DMA_PROGRAM_INST_MOD_BURST, or
 *              ALT_DMA_PROGRAM_INST_MOD_PERIPH are valid options.
 *
 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
 * \retval      ALT_E_BAD_ARG       Invalid peripheral or instruction modifier
 *                                  specified.
 */
// Assembler Syntax: DMAWFP <peripheral>, <single|burst|periph>
ALT_STATUS_CODE alt_dma_program_DMAWFP(ALT_DMA_PROGRAM_t * pgm,
                                       ALT_DMA_PERIPH_t periph, ALT_DMA_PROGRAM_INST_MOD_t mod);

/*!
 * Assembles a DMAWMB (Write Memory Barrier) instruction into the microcode
 * program buffer. This instruction uses 1 byte of buffer space.
 *
 * \param       pgm
 *              The DMA programm buffer to contain the assembled instruction.
 *
 * \retval      ALT_E_SUCCESS       Successful instruction assembly status.
 * \retval      ALT_E_DMA_BUF_OVF   DMA program buffer overflow.
 */
// Assembler Syntax: DMAWMB
ALT_STATUS_CODE alt_dma_program_DMAWMB(ALT_DMA_PROGRAM_t * pgm);

/*!
 * \addtogroup DMA_CCR Support for DMAMOV CCR
 *
 * The ALT_DMA_CCR_OPT_* macro definitions are defined here to facilitate the
 * dynamic microcode programming of the assembler directive:
\verbatim

DMAMOV CCR, [SB<1-16>] [SS<8|16|32|64|128>] [SA<I|F>]
            [SP<imm3>] [SC<imm4>]
            [DB<1-16>] [DS<8|16|32|64|128>] [DA<I|F>]
            [DP<imm3>] [DC<imm4>]
            [ES<8|16|32|64|128>]

\endverbatim
* with a DMAMOV instruction (see: alt_dma_program_DMAMOV()).
*
* For example the assembler directive:
\verbatim
DMAMOV CCR SB1 SS32 DB1 DS32
\endverbatim
* would be dynamically programmed with the following API call:
\verbatim
alt_dma_program_DMAMOV( pgm,
                        ALT_DMA_PROGRAM_REG_CCR,
                        (   ALT_DMA_CCR_OPT_SB1
                          | ALT_DMA_CCR_OPT_SS32
                          | ALT_DMA_CCR_OPT_SA_DEFAULT
                          | ALT_DMA_CCR_OPT_SP_DEFAULT
                          | ALT_DMA_CCR_OPT_SC_DEFAULT
                          | ALT_DMA_CCR_OPT_DB1
                          | ALT_DMA_CCR_OPT_DS32
                          | ALT_DMA_CCR_OPT_DA_DEFAULT
                          | ALT_DMA_CCR_OPT_DP_DEFAULT
                          | ALT_DMA_CCR_OPT_DC_DEFAULT
                          | ALT_DMA_CCR_OPT_ES8
                        )
                      );
\endverbatim
*
* Each CCR option category should be specified regardless of whether it
* specifies a custom value or the normal default value (i.e. an
* ALT_DMA_CCR_OPT_*_DEFAULT.
*
* @{
*/

/*
 * Source Address {Fixed,Incrementing}
 */
/*! Source Address Fixed address burst. */
#define ALT_DMA_CCR_OPT_SAF         (0 << 0)
/*! Source Address Incrementing address burst. */
#define ALT_DMA_CCR_OPT_SAI         (1 << 0)
/*! Source Address Default value. */
#define ALT_DMA_CCR_OPT_SA_DEFAULT  ALT_DMA_CCR_OPT_SAI

/*
 * Source burst Size (in bits)
 */
/*! Source burst Size of 8 bits. */
#define ALT_DMA_CCR_OPT_SS8         (0 << 1)
/*! Source burst Size of 16 bits. */
#define ALT_DMA_CCR_OPT_SS16        (1 << 1)
/*! Source burst Size of 32 bits. */
#define ALT_DMA_CCR_OPT_SS32        (2 << 1)
/*! Source burst Size of 64 bits. */
#define ALT_DMA_CCR_OPT_SS64        (3 << 1)
/*! Source burst Size of 128 bits. */
#define ALT_DMA_CCR_OPT_SS128       (4 << 1)
/*! Source burst Size default bits. */
#define ALT_DMA_CCR_OPT_SS_DEFAULT  ALT_DMA_CCR_OPT_SS8

/*
 * Source burst Length (in transfer(s))
 */
/*! Source Burst length of 1 transfer. */
#define ALT_DMA_CCR_OPT_SB1         (0x0 << 4)
/*! Source Burst length of 2 transfers. */
#define ALT_DMA_CCR_OPT_SB2         (0x1 << 4)
/*! Source Burst length of 3 transfers. */
#define ALT_DMA_CCR_OPT_SB3         (0x2 << 4)
/*! Source Burst length of 4 transfers. */
#define ALT_DMA_CCR_OPT_SB4         (0x3 << 4)
/*! Source Burst length of 5 transfers. */
#define ALT_DMA_CCR_OPT_SB5         (0x4 << 4)
/*! Source Burst length of 6 transfers. */
#define ALT_DMA_CCR_OPT_SB6         (0x5 << 4)
/*! Source Burst length of 7 transfers. */
#define ALT_DMA_CCR_OPT_SB7         (0x6 << 4)
/*! Source Burst length of 8 transfers. */
#define ALT_DMA_CCR_OPT_SB8         (0x7 << 4)
/*! Source Burst length of 9 transfers. */
#define ALT_DMA_CCR_OPT_SB9         (0x8 << 4)
/*! Source Burst length of 10 transfers. */
#define ALT_DMA_CCR_OPT_SB10        (0x9 << 4)
/*! Source Burst length of 11 transfers. */
#define ALT_DMA_CCR_OPT_SB11        (0xa << 4)
/*! Source Burst length of 12 transfers. */
#define ALT_DMA_CCR_OPT_SB12        (0xb << 4)
/*! Source Burst length of 13 transfers. */
#define ALT_DMA_CCR_OPT_SB13        (0xc << 4)
/*! Source Burst length of 14 transfers. */
#define ALT_DMA_CCR_OPT_SB14        (0xd << 4)
/*! Source Burst length of 15 transfers. */
#define ALT_DMA_CCR_OPT_SB15        (0xe << 4)
/*! Source Burst length of 16 transfers. */
#define ALT_DMA_CCR_OPT_SB16        (0xf << 4)
/*! Source Burst length default transfers. */
#define ALT_DMA_CCR_OPT_SB_DEFAULT  ALT_DMA_CCR_OPT_SB1

/*
 * Source Protection
 */
/*! Source Protection bits for AXI bus ARPROT[2:0]. */
#define ALT_DMA_CCR_OPT_SP(imm3)    ((imm3) << 8)
/*! Source Protection bits default value. */
#define ALT_DMA_CCR_OPT_SP_DEFAULT  ALT_DMA_CCR_OPT_SP(0)

/*
 * Source cache
 */
/*! Source Cache bits for AXI bus ARCACHE[2:0]. */
#define ALT_DMA_CCR_OPT_SC(imm4)    ((imm4) << 11)
/*! Source Cache bits default value. */
#define ALT_DMA_CCR_OPT_SC_DEFAULT  ALT_DMA_CCR_OPT_SC(0)

/*
 * Destination Address {Fixed,Incrementing}
 */
/*! Destination Address Fixed address burst. */
#define ALT_DMA_CCR_OPT_DAF         (0 << 14)
/*! Destination Address Incrementing address burst. */
#define ALT_DMA_CCR_OPT_DAI         (1 << 14)
/*! Destination Address Default value. */
#define ALT_DMA_CCR_OPT_DA_DEFAULT  ALT_DMA_CCR_OPT_DAI

/*
 * Destination burst Size (in bits)
 */
/*! Destination burst Size of 8 bits. */
#define ALT_DMA_CCR_OPT_DS8         (0 << 15)
/*! Destination burst Size of 16 bits. */
#define ALT_DMA_CCR_OPT_DS16        (1 << 15)
/*! Destination burst Size of 32 bits. */
#define ALT_DMA_CCR_OPT_DS32        (2 << 15)
/*! Destination burst Size of 64 bits. */
#define ALT_DMA_CCR_OPT_DS64        (3 << 15)
/*! Destination burst Size of 128 bits. */
#define ALT_DMA_CCR_OPT_DS128       (4 << 15)
/*! Destination burst Size default bits. */
#define ALT_DMA_CCR_OPT_DS_DEFAULT  ALT_DMA_CCR_OPT_DS8

/*
 * Destination Burst length (in transfer(s))
 */
/*! Destination Burst length of 1 transfer. */
#define ALT_DMA_CCR_OPT_DB1         (0x0 << 18)
/*! Destination Burst length of 2 transfers. */
#define ALT_DMA_CCR_OPT_DB2         (0x1 << 18)
/*! Destination Burst length of 3 transfers. */
#define ALT_DMA_CCR_OPT_DB3         (0x2 << 18)
/*! Destination Burst length of 4 transfers. */
#define ALT_DMA_CCR_OPT_DB4         (0x3 << 18)
/*! Destination Burst length of 5 transfers. */
#define ALT_DMA_CCR_OPT_DB5         (0x4 << 18)
/*! Destination Burst length of 6 transfers. */
#define ALT_DMA_CCR_OPT_DB6         (0x5 << 18)
/*! Destination Burst length of 7 transfers. */
#define ALT_DMA_CCR_OPT_DB7         (0x6 << 18)
/*! Destination Burst length of 8 transfers. */
#define ALT_DMA_CCR_OPT_DB8         (0x7 << 18)
/*! Destination Burst length of 9 transfers. */
#define ALT_DMA_CCR_OPT_DB9         (0x8 << 18)
/*! Destination Burst length of 10 transfers. */
#define ALT_DMA_CCR_OPT_DB10        (0x9 << 18)
/*! Destination Burst length of 11 transfers. */
#define ALT_DMA_CCR_OPT_DB11        (0xa << 18)
/*! Destination Burst length of 12 transfers. */
#define ALT_DMA_CCR_OPT_DB12        (0xb << 18)
/*! Destination Burst length of 13 transfers. */
#define ALT_DMA_CCR_OPT_DB13        (0xc << 18)
/*! Destination Burst length of 14 transfers. */
#define ALT_DMA_CCR_OPT_DB14        (0xd << 18)
/*! Destination Burst length of 15 transfers. */
#define ALT_DMA_CCR_OPT_DB15        (0xe << 18)
/*! Destination Burst length of 16 transfers. */
#define ALT_DMA_CCR_OPT_DB16        (0xf << 18)
/*! Destination Burst length default transfers. */
#define ALT_DMA_CCR_OPT_DB_DEFAULT  ALT_DMA_CCR_OPT_DB1

/*
 * Destination Protection
 */
/*! Destination Protection bits for AXI bus AWPROT[2:0]. */
#define ALT_DMA_CCR_OPT_DP(imm3)    ((imm3) << 22)
/*! Destination Protection bits default value. */
#define ALT_DMA_CCR_OPT_DP_DEFAULT  ALT_DMA_CCR_OPT_DP(0)

/*
 * Destination Cache
 */
/*! Destination Cache bits for AXI bus AWCACHE[3,1:0]. */
#define ALT_DMA_CCR_OPT_DC(imm4)    ((imm4) << 25)
/*! Destination Cache bits default value. */
#define ALT_DMA_CCR_OPT_DC_DEFAULT  ALT_DMA_CCR_OPT_DC(0)

/*
 * Endian Swap size (in bits)
 */
/*! Endian Swap: No swap, 8-bit data. */
#define ALT_DMA_CCR_OPT_ES8         (0 << 28)
/*! Endian Swap: Swap bytes within 16-bit data. */
#define ALT_DMA_CCR_OPT_ES16        (1 << 28)
/*! Endian Swap: Swap bytes within 32-bit data. */
#define ALT_DMA_CCR_OPT_ES32        (2 << 28)
/*! Endian Swap: Swap bytes within 64-bit data. */
#define ALT_DMA_CCR_OPT_ES64        (3 << 28)
/*! Endian Swap: Swap bytes within 128-bit data. */
#define ALT_DMA_CCR_OPT_ES128       (4 << 28)
/*! Endian Swap: Default byte swap. */
#define ALT_DMA_CCR_OPT_ES_DEFAULT  ALT_DMA_CCR_OPT_ES8

/*! Default CCR register options for a DMAMOV CCR assembler directive. */
#define ALT_DMA_CCR_OPT_DEFAULT \
    (ALT_DMA_CCR_OPT_SB1 | ALT_DMA_CCR_OPT_SS8 | ALT_DMA_CCR_OPT_SAI | \
     ALT_DMA_CCR_OPT_SP(0) | ALT_DMA_CCR_OPT_SC(0) | \
     ALT_DMA_CCR_OPT_DB1 | ALT_DMA_CCR_OPT_DS8 | ALT_DMA_CCR_OPT_DAI | \
     ALT_DMA_CCR_OPT_DP(0) | ALT_DMA_CCR_OPT_DC(0) | \
     ALT_DMA_CCR_OPT_ES8)

/*!
 * @}
 */

/*!
 * @}
 */

#ifdef __cplusplus
}
#endif  /* __cplusplus */

#endif /* __ALT_DMA_PROGRAM_H__ */