Remove make preinstall

A speciality of the RTEMS build system was the make preinstall step.  It
copied header files from arbitrary locations into the build tree.  The
header files were included via the -Bsome/build/tree/path GCC command
line option.

This has at least seven problems:

* The make preinstall step itself needs time and disk space.

* Errors in header files show up in the build tree copy.  This makes it
  hard for editors to open the right file to fix the error.

* There is no clear relationship between source and build tree header
  files.  This makes an audit of the build process difficult.

* The visibility of all header files in the build tree makes it
  difficult to enforce API barriers.  For example it is discouraged to
  use BSP-specifics in the cpukit.

* An introduction of a new build system is difficult.

* Include paths specified by the -B option are system headers.  This
  may suppress warnings.

* The parallel build had sporadic failures on some hosts.

This patch removes the make preinstall step.   All installed header
files are moved to dedicated include directories in the source tree.
Let @RTEMS_CPU@ be the target architecture, e.g. arm, powerpc, sparc,
etc.  Let @RTEMS_BSP_FAMILIY@ be a BSP family base directory, e.g.
erc32, imx, qoriq, etc.

The new cpukit include directories are:

* cpukit/include

* cpukit/score/cpu/@RTEMS_CPU@/include

* cpukit/libnetworking

The new BSP include directories are:

* bsps/include

* bsps/@RTEMS_CPU@/include

* bsps/@RTEMS_CPU@/@RTEMS_BSP_FAMILIY@/include

There are build tree include directories for generated files.

The include directory order favours the most general header file, e.g.
it is not possible to override general header files via the include path
order.

The "bootstrap -p" option was removed.  The new "bootstrap -H" option
should be used to regenerate the "headers.am" files.

Update #3254.

1 files changed, 951 insertions, 0 deletions

diff --git a/bsps/arm/altera-cyclone-v/include/bsp/alt_dma_program.h b/bsps/arm/altera-cyclone-v/include/bsp/alt_dma_program.h
new file mode 100644
index 0000000000..5fa876f237
--- /dev/null
+++ b/bsps/arm/altera-cyclone-v/include/bsp/alt_dma_program.h
@@ -0,0 +1,951 @@
+/******************************************************************************
+ *
+ * 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__ */