diff options
Diffstat (limited to 'bsps/arm/altera-cyclone-v/include/bsp/alt_dma_program.h')
| -rw-r--r-- | bsps/arm/altera-cyclone-v/include/bsp/alt_dma_program.h | 951 |
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__ */ |