git.sur5r.net Git - freertos/blob - Demo/CORTEX_A2F200_IAR_and_Keil/MicroSemi_Code/drivers/mss_pdma/mss_pdma.h

   1 /*******************************************************************************\r
   2  * (c) Copyright 2008 Actel Corporation.  All rights reserved.\r
   3  * \r
   4  * SmartFusion microcontroller subsystem Peripheral DMA bare metal software\r
   5  * driver public API.\r
   6  *\r
   7  * SVN $Revision: 2110 $\r
   8  * SVN $Date: 2010-02-05 15:24:19 +0000 (Fri, 05 Feb 2010) $\r
   9  */\r
  10 /*=========================================================================*//**\r
  11   @mainpage SmartFusion MSS GPIO Bare Metal Driver.\r
  12 \r
  13   @section intro_sec Introduction\r
  14   The SmartFusion Microcontroller Subsystem (MSS) includes an 8 channel\r
  15   Peripheral DMA (PDMA) controller.\r
  16   This software driver provides a set of functions for controlling the MSS PDMA\r
  17   controller as part of a bare metal system where no operating system is available.\r
  18   This driver can be adapted for use as part of an operating system but the\r
  19   implementation of the adaptation layer between this driver and the operating\r
  20   system's driver model is outside the scope of this driver.\r
  21   \r
  22   @section theory_op Theory of Operation\r
  23   The MSS PDMA driver uses the SmartFusion "Cortex Microcontroler Software\r
  24   Interface Standard - Peripheral Access Layer" (CMSIS-PAL) to access MSS hardware\r
  25   registers. You must ensure that the SmartFusion CMSIS-PAL is either included\r
  26   in the software toolchain used to build your project or is included in your\r
  27   project. The most up-to-date SmartFusion CMSIS-PAL files can be obtained using\r
  28   the Actel Firmware Catalog.\r
  29   \r
  30   The MSS PDMA driver functions are grouped into the following categories:\r
  31     - Initialization\r
  32     - Configuration\r
  33     - DMA transfer control\r
  34     - Interrupt control\r
  35   \r
  36   The MSS PDMA driver is initialized through a call to the PDMA_init() function.\r
  37   The PDMA_init() function must be called before any other PDMA driver functions\r
  38   can be called.\r
  39   \r
  40   Each PDMA channel is individually configured through a call to the PDMA_configure()\r
  41   function. Configuration includes:\r
  42     - channel priority\r
  43     - transfer size\r
  44     - source and/or destination address increment\r
  45     - source or destination of the DMA transfer\r
  46   PDMA channels can be divided into high and low priority channels. High priority\r
  47   channels are given more opportunities to perform transfers than low priority\r
  48   channels when there are continuous high priority channels requests. The ratio\r
  49   of high priority to low priority PDMA transfers is configurable through the\r
  50   PDMA_set_priority() function.\r
  51   PDMA channels can be configured to perform byte (8 bits), half-word (16 bits)\r
  52   or word (32 bits) transfers.\r
  53   The source and destination address of a PDMA channel\92s transfers can be\r
  54   independently configured to increment by 0, 1, 2 or 4 bytes. For example, the\r
  55   content of a byte buffer located in RAM can be transferred into a peripheral\92s\r
  56   transmit register by configuring the source address increment to one byte and\r
  57   no increment of the destination address.\r
  58   The source or destination of a PDMA channel\92s transfers can be configured to\r
  59   be one of the MSS peripherals. This allows the PDMA controller to use some\r
  60   hardware flow control signaling with the peripheral to avoid overrunning the\r
  61   peripheral\92s data buffer when the peripheral is the destination of the DMA\r
  62   transfer, or attempting to read data from the peripheral while it is not ready\r
  63   when the peripheral is the source of the transfer.\r
  64   A PDMA channel can also be configured to transfer data between two memory\r
  65   mapped locations (memory to memory). No hardware flow control is used by the\r
  66   PDMA controller for data transfer in this configuration.\r
  67   \r
  68   A DMA transfer can be initiated by a call to the PDMA_start() function after a\r
  69   PDMA channel has been configured. Once started, further data can be pushed\r
  70   through the PDMA channel by calling the PDMA_load_next_buffer() function. The\r
  71   PDMA_load_next_buffer() function can be called every time a call to the\r
  72   PDMA_status() function indicates that the PDMA channel used for the transfer\r
  73   has a free buffer or it can be called as a result of a PDMA interrupt.\r
  74   \r
  75   A DMA transfer can be paused and resumed through calls to functions PDMA_pause()\r
  76   and PDMA_resume().\r
  77   \r
  78   Your application can manage DMA transfers using interrupts through the use of\r
  79   the following functions:\r
  80     - PDMA_set_irq_handler()\r
  81     - PDMA_enable_irq()\r
  82     - PDMA_clear_irq()\r
  83     - PDMA_disable_irq()\r
  84   The PDMA_set_irq_handler() function is used to register PDMA channel interrupt\r
  85   handler functions with the driver. You must create and register an interrupt\r
  86   handler function for each interrupt driven PDMA channel used by the application.\r
  87   Use the PDMA_enable_irq() function to enable interrupts for the PDMA channels. \r
  88   Every time a PDMA channel completes the transfer of a buffer it causes a PDMA\r
  89   interrupt to occur and the PDMA driver will call the interrupt handler\r
  90   registered by the application for that PDMA channel.\r
  91   \r
  92  *//*=========================================================================*/\r
  93 #ifndef __MSS_PERIPHERAL_DMA_H_\r
  94 #define __MSS_PERIPHERAL_DMA_H_\r
  95 \r
  96 #ifdef __cplusplus\r
  97 extern "C" {\r
  98 #endif \r
  99 \r
 100 #include "../../CMSIS/a2fxxxm3.h"\r
 101 \r
 102 /***************************************************************************//**\r
 103   The pdma_channel_id_t enumeration is used to identify peripheral DMA channels.\r
 104   It is used as function parameter to specify the PDMA channel used.\r
 105  */\r
 106 typedef enum __pdma_channel_id\r
 107 {\r
 108     PDMA_CHANNEL_0 = 0,\r
 109     PDMA_CHANNEL_1,\r
 110     PDMA_CHANNEL_2,\r
 111     PDMA_CHANNEL_3,\r
 112     PDMA_CHANNEL_4,\r
 113     PDMA_CHANNEL_5,\r
 114     PDMA_CHANNEL_6,\r
 115     PDMA_CHANNEL_7\r
 116 } pdma_channel_id_t;\r
 117 \r
 118 /***************************************************************************//**\r
 119   The pdma_src_dest_t enumeration is used to specify the source or destination\r
 120   of transfers on a PDMA channel. It specifies which hardware peripheral will be\r
 121   the source or destination of DMA transfers. This allows the PDMA controller\r
 122   to use hardware flow control signals to avoid overrunning a\r
 123   destination peripheral with data it is not ready to receive, or attempting to\r
 124   transfer data from a peripheral while it has no data ready to transfer.\r
 125   The pdma_src_dest_t enumeration can also be used to specify that a PDMA channel\r
 126   is configured to transfer data between two memory mapped locations\r
 127   (memory to memory). No hardware data flow control is used by the PDMA\r
 128   controller in this configuration.\r
 129   This enumeration is used as parameter to function PDMA_configure().\r
 130  */\r
 131 typedef enum __pdma_src_dest\r
 132 {\r
 133     PDMA_FROM_UART_0 = 0,\r
 134     PDMA_TO_UART_0,\r
 135     PDMA_FROM_UART_1,\r
 136     PDMA_TO_UART_1,\r
 137     PDMA_FROM_SPI_0,\r
 138     PDMA_TO_SPI_0,\r
 139     PDMA_FROM_SPI_1,\r
 140     PDMA_TO_SPI_1,\r
 141     PDMA_FROM_FPGA_1,\r
 142     PDMA_TO_FPGA_1,\r
 143     PDMA_FROM_FPGA_0,\r
 144     PDMA_TO_FPGA_0,\r
 145     PDMA_TO_ACE,\r
 146     PDMA_FROM_ACE,\r
 147     PDMA_MEM_TO_MEM\r
 148 } pdma_src_dest_t;\r
 149 \r
 150 /***************************************************************************//**\r
 151   The pdma_priority_ratio_t enumeration is used to configure the ratio of high\r
 152   priority to low priority PDMA channels.  This ratio specifies how many DMA\r
 153   transfer opportunities will be given to high priority channels before a DMA\r
 154   transfer opportunity is given to a low priority channel when there are\r
 155   continuous requests from high priority channels. This enumeration is used as\r
 156   parameter to function PDMA_set_priority_ratio().\r
 157  */\r
 158 typedef enum __pdma_priority_ratio_t\r
 159 {\r
 160     PDMA_ROUND_ROBIN = 0,\r
 161     PDMA_RATIO_HIGH_LOW_1_TO_1 = 1,\r
 162     PDMA_RATIO_HIGH_LOW_3_TO_1 = 3,\r
 163     PDMA_RATIO_HIGH_LOW_7_TO_1 = 7,\r
 164     PDMA_RATIO_HIGH_LOW_15_TO_1 = 15,\r
 165     PDMA_RATIO_HIGH_LOW_31_TO_1 = 31,\r
 166     PDMA_RATIO_HIGH_LOW_63_TO_1 = 63,\r
 167     PDMA_RATIO_HIGH_LOW_127_TO_1 = 127,\r
 168     PDMA_RATIO_HIGH_LOW_255_TO_1 = 255\r
 169 } pdma_priority_ratio_t;\r
 170 \r
 171 \r
 172 /***************************************************************************//**\r
 173   The pdma_channel_isr_t type is a pointer to a PDMA channel interrupt handler\r
 174   function. It specifies the function prototype of functions that can be\r
 175   registered as PDMA channel interrupt handlers. It is used as parameter to\r
 176   function PDMA_set_irq_handler().\r
 177  */\r
 178 typedef void (*pdma_channel_isr_t)( void );\r
 179 /***************************************************************************//**\r
 180   These constants are used to build the channel_cfg parameter of the\r
 181   PDMA_configure() function. They specify whether a channel is a high or low\r
 182   priority channel.\r
 183  */\r
 184 #define PDMA_LOW_PRIORITY    0x0000\r
 185 #define PDMA_HIGH_PRIORITY   0x0200\r
 186 \r
 187 /***************************************************************************//**\r
 188   These constants are used to build the channel_cfg parameter of the\r
 189   PDMA_configure() function. They specify the data width of the transfers\r
 190   performed by a PDMA channel.\r
 191  */\r
 192 #define PDMA_BYTE_TRANSFER       0x0000     /* Byte transfers (8 bits) */\r
 193 #define PDMA_HALFWORD_TRANSFER   0x0004     /* Half-word transfers (16 bits) */\r
 194 #define PDMA_WORD_TRANSFER       0x0008     /* Word transfers (32 bits) */\r
 195 \r
 196 /***************************************************************************//**\r
 197   These constants are used to build the channel_cfg parameter of the\r
 198   PDMA_configure() function. They specify the PDMA channel\92s source and\r
 199   destination address increment.\r
 200  */\r
 201 #define PDMA_NO_INC  0\r
 202 #define PDMA_INC_SRC_ONE_BYTE    0x0400\r
 203 #define PDMA_INC_SRC_TWO_BYTES   0x0800\r
 204 #define PDMA_INC_SRC_FOUR_BYTES  0x0C00\r
 205 #define PDMA_INC_DEST_ONE_BYTE   0x1000\r
 206 #define PDMA_INC_DEST_TWO_BYTES  0x2000\r
 207 #define PDMA_INC_DEST_FOUR_BYTES 0x3000\r
 208 \r
 209 /***************************************************************************//**\r
 210  * Mask for various control register bits.\r
 211  */\r
 212 #define PDMA_IRQ_ENABLE_MASK    (uint32_t)0x00000040\r
 213 #define PDMA_PAUSE_MASK         (uint32_t)0x00000010\r
 214 \r
 215 /***************************************************************************//**\r
 216   These constants are used to specify the src_addr parameter to the PDMA_start()\r
 217   and PDMA_load_next_buffer() functions. They specify the receive register\r
 218   address of peripherals that can be the source of a DMA transfer. \r
 219   When a PDMA channel is configured for DMA transfers from a peripheral to memory,\r
 220   the constant specifying that peripheral\92s receive register address must be used\r
 221   as the src_addr parameter.\r
 222  */\r
 223 #define PDMA_SPI0_RX_REGISTER       0x40001010uL\r
 224 #define PDMA_SPI1_RX_REGISTER       0x40011010uL\r
 225 #define PDMA_UART0_RX_REGISTER      0x40000000uL\r
 226 #define PDMA_UART1_RX_REGISTER      0x40010000uL\r
 227 #define PDMA_ACE_PPE_DATAOUT        0x40021308uL\r
 228 \r
 229 /***************************************************************************//**\r
 230   These constants are used to specify the dest_addr parameter to the PDMA_start()\r
 231   and PDMA_load_next_buffer() functions. They specify the transmit register\r
 232   address of peripherals that can be the destination of a DMA transfer. \r
 233   When a PDMA channel is configured for DMA transfers from memory to a peripheral,\r
 234   the constant specifying that peripheral\92s transmit register address must be used\r
 235   as the dest_addr parameter.\r
 236  */\r
 237 #define PDMA_SPI0_TX_REGISTER       0x40001014uL\r
 238 #define PDMA_SPI1_TX_REGISTER       0x40011014uL\r
 239 #define PDMA_UART0_TX_REGISTER      0x40000000uL\r
 240 #define PDMA_UART1_TX_REGISTER      0x40010000uL\r
 241 #define PDMA_ACE_SSE_DATAIN         0x40020700uL\r
 242 \r
 243 /***************************************************************************//**\r
 244   The PDMA_DEFAULT_WRITE_ADJ constant provides a suitable default value for the\r
 245   PDMA_configure() function write_adjust parameter.\r
 246  */\r
 247 #define PDMA_DEFAULT_WRITE_ADJ      10u\r
 248 \r
 249 /***************************************************************************//**\r
 250   The PDMA_init() function initializes the peripheral DMA hardware and driver\r
 251   internal data. It resets the PDMA and it also clears any pending PDMA\r
 252   interrupts in the Cortex-M3 interrupt controller. When the function exits, it\r
 253   takes the PDMA block out of reset.\r
 254  */\r
 255 void PDMA_init( void );\r
 256 \r
 257 /***************************************************************************//**\r
 258   The PDMA_configure() function configures a PDMA channel.\r
 259   It specifies:\r
 260    - The peripheral which will be the source or destination of the DMA transfer.\r
 261    - Whether the DMA channel will be a high or low priority channel\r
 262    - The source and destination address increment that will take place after\r
 263      each transfer.\r
 264  \r
 265   @param channel_id\r
 266     The channel_id parameter identifies the PDMA channel used by the function.\r
 267  \r
 268   @param src_dest\r
 269     The src_dest parameter specifies the source or destination of the DMA\r
 270     transfers that will be performed. It can be one of the following:\r
 271         - PDMA_FROM_UART_0\r
 272         - PDMA_TO_UART_0\r
 273         - PDMA_FROM_UART_1\r
 274         - PDMA_TO_UART_1\r
 275         - PDMA_FROM_SPI_0\r
 276         - PDMA_TO_SPI_0\r
 277         - PDMA_FROM_SPI_1\r
 278         - PDMA_TO_SPI_1\r
 279         - PDMA_FROM_FPGA_1\r
 280         - PDMA_TO_FPGA_1\r
 281         - PDMA_FROM_FPGA_0\r
 282         - PDMA_TO_FPGA_0\r
 283         - PDMA_TO_ACE\r
 284         - PDMA_FROM_ACE\r
 285         - PDMA_MEM_TO_MEM\r
 286  \r
 287   @param channel_cfg\r
 288     The channel_cfg parameter specifies the configuration of the PDMA channel.\r
 289     The configuration includes:\r
 290         - channel priority\r
 291         - transfer size\r
 292         - source and/or destination address increment\r
 293     The channel_cfg parameter value is a logical OR of:\r
 294         One of the following to specify the channel priority:\r
 295            - PDMA_LOW_PRIORITY\r
 296            - PDMA_HIGH_PRIORITY\r
 297         One of the following to specify the transfer size:\r
 298            - PDMA_BYTE_TRANSFER\r
 299            - PDMA_HALFWORD_TRANSFER\r
 300            - PDMA_WORD_TRANSFER\r
 301         One or two of the following to specify the source and/or destination address\r
 302         increment:\r
 303            - PDMA_NO_INC\r
 304            - PDMA_INC_SRC_ONE_BYTE\r
 305            - PDMA_INC_SRC_TWO_BYTES\r
 306            - PDMA_INC_SRC_FOUR_BYTES\r
 307            - PDMA_INC_DEST_ONE_BYTE\r
 308            - PDMA_INC_DEST_TWO_BYTES\r
 309            - PDMA_INC_DEST_FOUR_BYTES\r
 310   \r
 311   @param write_adjust\r
 312     The write_adjust parameter specifies the number of Cortex-M3 clock cycles\r
 313     the PDMA controller will wait before attempting another transfer cycle. This\r
 314     delay is necessary when peripherals are used as destination of a DMA transfer\r
 315     to ensure the DMA controller interprets the state of the peripheral\92s ready\r
 316     signal only after data has actually been written to the peripheral. This delay\r
 317     accounts for posted writes (dump and run) for write accesses to peripherals. \r
 318     The effect of posted writes is that if the PDMA performs a write operation to\r
 319     a peripheral, the data is not actually written into the peripheral until\r
 320     sometime after the PDMA controller thinks it is written.\r
 321     A suitable value for write_adjust depends on the target of the DMA transfer.\r
 322     Guidelines for choosing this value are as follows:\r
 323         \95 The PDMA_DEFAULT_WRITE_ADJ constant provides a suitable default value\r
 324           for the write_adjust parameter when the PDMA channel is configured for\r
 325           transfers with MSS peripherals.\r
 326         \95 The PDMA_DEFAULT_WRITE_ADJ constant can also be used for DMA transfers\r
 327           with FPGA fabric implemented peripherals making use of the DMAREADY0 or\r
 328           DMAREADY1fabric interface signal to indicate that the peripheral is\r
 329           ready for another DMA transfer.\r
 330         \95 The write_adjust parameter can be set to zero to achieve maximum transfer\r
 331           speed for genuine memory to memory transfers. \r
 332         \95 The internal latency of FPGA implemented peripherals will decide the\r
 333           write_adjust value for fabric peripherals that do not use the DMAREADY0\r
 334           or DMAREADY1 fabric interface signals. You need to check the fabric\r
 335           peripheral documentation for the value to use.\r
 336     \r
 337   Example:\r
 338   @code\r
 339    PDMA_configure\r
 340    (\r
 341        PDMA_CHANNEL_0,\r
 342        PDMA_TO_SPI_1,\r
 343        PDMA_LOW_PRIORITY | PDMA_BYTE_TRANSFER | PDMA_INC_SRC_ONE_BYTE,\r
 344        PDMA_DEFAULT_WRITE_ADJ\r
 345    );\r
 346   @endcode\r
 347  */\r
 348 void PDMA_configure\r
 349 (\r
 350     pdma_channel_id_t channel_id,\r
 351     pdma_src_dest_t src_dest,\r
 352     uint32_t channel_cfg,\r
 353     uint8_t write_adjust\r
 354 );\r
 355 \r
 356 \r
 357 /***************************************************************************//**\r
 358   The PDMA_set_priority_ratio() function sets the ratio of high priority to low\r
 359   priority DMA access opportunities. This ratio is used by the PDMA controller\r
 360   arbiter to decide which PDMA channel will be given the opportunity to perform\r
 361   a transfer when multiple PDMA channels are requesting to transfer data at the\r
 362   same time. The priority ratio specifies how many DMA transfer opportunities\r
 363   will be given to high priority channels before a DMA transfer opportunity is\r
 364   given to a low priority channel when there are continuous requests from high\r
 365   priority channels.\r
 366  \r
 367   @param priority_ratio\r
 368     The priority_ratio parameter specifies the ratio of DMA access opportunities\r
 369     given to high priority channels versus low priority channels.\r
 370     Allowed values for this parameter are:\r
 371        - PDMA_ROUND_ROBIN\r
 372        - PDMA_RATIO_HIGH_LOW_1_TO_1\r
 373        - PDMA_RATIO_HIGH_LOW_3_TO_1\r
 374        - PDMA_RATIO_HIGH_LOW_7_TO_1\r
 375        - PDMA_RATIO_HIGH_LOW_15_TO_1\r
 376        - PDMA_RATIO_HIGH_LOW_31_TO_1\r
 377        - PDMA_RATIO_HIGH_LOW_63_TO_1\r
 378        - PDMA_RATIO_HIGH_LOW_127_TO_1\r
 379        - PDMA_RATIO_HIGH_LOW_255_TO_1\r
 380  \r
 381   Example:\r
 382   @code\r
 383    PDMA_set_priority_ratio( PDMA_ROUND_ROBIN );\r
 384   @endcode\r
 385  */\r
 386 static __INLINE void PDMA_set_priority_ratio\r
 387 (\r
 388     pdma_priority_ratio_t priority_ratio\r
 389 )\r
 390 {\r
 391     PDMA->RATIO_HIGH_LOW = (uint32_t)priority_ratio;\r
 392 }\r
 393 \r
 394 /***************************************************************************//**\r
 395   The PDMA_start() function  initiates a DMA transfer. It specifies the source\r
 396   and destination address of the transfer as well as the number of transfers\r
 397   that must take place. The source and destination addresses can be the address\r
 398   of peripheral registers.\r
 399  \r
 400   @param channel_id\r
 401     The channel_id parameter identifies the PDMA channel used by the function.\r
 402  \r
 403   @param src_addr\r
 404     The src_addr parameter specifies the address location of the data to be\r
 405     transferred. You must ensure that this source address is consistent with the\r
 406     DMA source configured for the selected channel using the PDMA_configure()\r
 407     function.\r
 408     For DMA transfers from MSS peripheral to memory, the following src_addr\r
 409     parameter values are allowed:\r
 410         \95 PDMA_SPI0_RX_REGISTER\r
 411         \95 PDMA_SPI1_RX_REGISTER\r
 412         \95 PDMA_UART0_RX_REGISTER\r
 413         \95 PDMA_UART1_RX_REGISTER\r
 414         \95 PDMA_ACE_PPE_DATAOUT\r
 415     For DMA transfers from FPGA fabric peripheral to memory, the following\r
 416     src_addr parameter values are allowed:\r
 417         \95 An address in the FPGA fabric address space (0x40050000-0x400FFFFF)\r
 418     For DMA transfers from memory to MSS peripheral, or from memory to FPGA\r
 419     fabric peripheral, or from memory to memory, the following src_addr\r
 420     parameter values are allowed:\r
 421         \95 Any memory mapped address.\r
 422 \r
 423   @param dest_addr\r
 424     The dest_addr parameter specifies the destination address of the PDMA\r
 425     transfer. You must ensure that this matches with the DMA destination\r
 426     configured for the selected channel.\r
 427     For DMA transfers from memory to MSS peripheral, the following dest_addr parameter values are allowed:\r
 428         \95 PDMA_SPI0_TX_REGISTER\r
 429         \95 PDMA_SPI1_TX_REGISTER\r
 430         \95 PDMA_UART0_TX_REGISTER\r
 431         \95 PDMA_UART1_TX_REGISTER\r
 432         \95 PDMA_ACE_SSE_DATAIN\r
 433     For DMA transfers from memory to FPGA fabric peripheral, the following\r
 434     dest_addr parameter values are allowed:\r
 435         \95 An address in the FPGA fabric address space (0x40050000-0x400FFFFF)\r
 436     For DMA transfers from MSS peripheral to memory, or from FPGA fabric\r
 437     peripheral to memory, or from memory to memory, the following dest_addr\r
 438     parameter values are allowed:\r
 439         \95 Any memory mapped address.\r
 440 \r
 441   @param transfer_count\r
 442     The transfer_count parameter specifies the number of transfers to be\r
 443     performed. It is the number of bytes to transfer if the PDMA channel is\r
 444     configured for byte transfer, the number of half-words to transfer if the\r
 445     PDMA channel is configured for half-word transfer, or the number of words\r
 446     to transfer if the PDMA channel is configured for word transfer.\r
 447  \r
 448   Example:\r
 449   @code\r
 450     PDMA_start\r
 451       (\r
 452           PDMA_CHANNEL_3,\r
 453           PDMA_SPI1_RX_REGISTER,\r
 454           (uint32_t)slave_rx_buffer,\r
 455           sizeof(slave_rx_buffer)\r
 456       ); \r
 457   @endcode\r
 458  */\r
 459 void PDMA_start\r
 460 (\r
 461     pdma_channel_id_t channel_id,\r
 462     uint32_t src_addr,\r
 463     uint32_t dest_addr,\r
 464     uint16_t transfer_count\r
 465 );\r
 466 \r
 467 /***************************************************************************//**\r
 468   The PDMA_load_next_buffer() function sets the next buffer to be transferred.\r
 469   This function is called after a transfer has been initiated using the\r
 470   PDMA_start() function. Its purpose is to keep feeding a PDMA channel with data\r
 471   buffers.\r
 472  \r
 473   @param channel_id\r
 474     The channel_id parameter identifies the PDMA channel used by the function.\r
 475  \r
 476   @param src_addr\r
 477     The src_addr parameter specifies the address location of the data to be\r
 478     transferred. You must ensure that this source address is consistent with the\r
 479     DMA source configured for the selected channel using the PDMA_configure()\r
 480     function.\r
 481     For DMA transfers from MSS peripheral to memory, the following src_addr parameter values are allowed:\r
 482         \95 PDMA_SPI0_RX_REGISTER\r
 483         \95 PDMA_SPI1_RX_REGISTER\r
 484         \95 PDMA_UART0_RX_REGISTER\r
 485         \95 PDMA_UART1_RX_REGISTER\r
 486         \95 PDMA_ACE_PPE_DATAOUT\r
 487     For DMA transfers from FPGA fabric peripheral to memory, the following src_addr parameter values are allowed:\r
 488         \95 An address in the FPGA fabric address space (0x40050000-0x400FFFFF)\r
 489     For DMA transfers from memory to MSS peripheral, or from memory to FPGA fabric peripheral, or from memory to memory, the following src_addr parameter values are allowed:\r
 490         \95 Any memory mapped address.\r
 491 \r
 492   @param dest_addr\r
 493     The dest_addr parameter specifies the destination address of the PDMA\r
 494     transfer. You must ensure that this matches with the DMA destination\r
 495     configured for the selected channel.\r
 496     For DMA transfers from memory to MSS peripheral, the following dest_addr parameter values are allowed:\r
 497         \95 PDMA_SPI0_TX_REGISTER\r
 498         \95 PDMA_SPI1_TX_REGISTER\r
 499         \95 PDMA_UART0_TX_REGISTER\r
 500         \95 PDMA_UART1_TX_REGISTER\r
 501         \95 PDMA_ACE_SSE_DATAIN\r
 502     For DMA transfers from memory to FPGA fabric peripheral, the following dest_addr parameter values are allowed:\r
 503         \95 An address in the FPGA fabric address space (0x40050000-0x400FFFFF)\r
 504     For DMA transfers from MSS peripheral to memory, or from FPGA fabric peripheral to memory, or from memory to memory, the following dest_addr parameter values are allowed:\r
 505         \95 Any memory mapped address.\r
 506  \r
 507   @param transfer_count\r
 508     The transfer_count parameter specifies the number of transfers to be\r
 509     performed. It is the number of bytes to transfer if the PDMA channel is\r
 510     configured for byte transfer, the number of half-words to transfer if the\r
 511     PDMA channel is configured for half-word transfer or the number of words to\r
 512     transfer if the PDMA channel is configured for word transfer.\r
 513     \r
 514   Example:\r
 515   @code\r
 516   void write_cmd_data\r
 517   (\r
 518       mss_spi_instance_t * this_spi,\r
 519       const uint8_t * cmd_buffer,\r
 520       uint16_t cmd_byte_size,\r
 521       uint8_t * data_buffer,\r
 522       uint16_t data_byte_size\r
 523   )\r
 524   {\r
 525       uint32_t transfer_size;\r
 526       \r
 527       transfer_size = cmd_byte_size + data_byte_size;\r
 528   \r
 529       MSS_SPI_disable( this_spi );\r
 530       MSS_SPI_set_transfer_byte_count( this_spi, transfer_size );\r
 531   \r
 532       PDMA_start\r
 533           (\r
 534               PDMA_CHANNEL_0,\r
 535               (uint32_t)cmd_buffer,\r
 536               PDMA_SPI1_TX_REGISTER,\r
 537               cmd_byte_size\r
 538           );\r
 539       \r
 540       PDMA_load_next_buffer\r
 541           (\r
 542               PDMA_CHANNEL_0,\r
 543               (uint32_t)data_buffer,\r
 544               PDMA_SPI1_TX_REGISTER,\r
 545               data_byte_size\r
 546           );\r
 547       \r
 548       MSS_SPI_enable( this_spi );\r
 549       \r
 550       while ( !MSS_SPI_tx_done(this_spi) )\r
 551       {\r
 552           ;\r
 553       }\r
 554   }\r
 555   @endcode\r
 556  */\r
 557 void PDMA_load_next_buffer\r
 558 (\r
 559     pdma_channel_id_t channel_id,\r
 560     uint32_t src_addr,\r
 561     uint32_t dest_addr,\r
 562     uint16_t transfer_count\r
 563 );\r
 564 \r
 565 /***************************************************************************//**\r
 566   The PDMA_status() function returns the status of a DMA channel.\r
 567   The returned value indicates if transfers have been completed using buffer A\r
 568   or buffer B of the PDMA hardware block.\r
 569  \r
 570   @param channel_id\r
 571     The channel_id parameter identifies the PDMA channel used by the function.\r
 572  \r
 573   @return\r
 574     bit 0 of the return value indicates if buffer A has been trasnfered. It is\r
 575     set to 1 if the transfer has completed.\r
 576     bit 1 of the return value indicates if buffer B has been transfered. It is\r
 577     set to 1 if the transfer has completed.\r
 578  */\r
 579 uint32_t PDMA_status\r
 580 (\r
 581     pdma_channel_id_t  channel_id\r
 582 );\r
 583 \r
 584 /***************************************************************************//**\r
 585   The PDMA_pause() function temporarily pauses a PDMA transfer taking place on\r
 586   the specified PDMA channel. The transfer can later be resumed by using the\r
 587   PDMA_resume() function.\r
 588  \r
 589   @param channel_id\r
 590     The channel_id parameter identifies the PDMA channel used by the function.\r
 591  */\r
 592 static __INLINE void PDMA_pause( pdma_channel_id_t channel_id )\r
 593 {\r
 594     PDMA->CHANNEL[channel_id].CRTL |= PDMA_PAUSE_MASK;\r
 595 }\r
 596 \r
 597 /***************************************************************************//**\r
 598   The PDMA_resume() function resumes a transfer previously paused using the\r
 599   PDMA_pause() function.\r
 600  \r
 601   @param channel_id    The channel_id parameter identifies the PDMA channel\r
 602                        used by the function.\r
 603  */\r
 604 static __INLINE void PDMA_resume( pdma_channel_id_t channel_id )\r
 605 {\r
 606     PDMA->CHANNEL[channel_id].CRTL &= ~PDMA_PAUSE_MASK;\r
 607 }\r
 608 \r
 609 /***************************************************************************//**\r
 610   The PDMA_enable_irq() enables the PDMA hardware to generate an interrupt when\r
 611   a DMA transfer completes on the specified PDMA channel. This function also\r
 612   enables the PDMA interrupt in the Cortex-M3 interrupt controller.\r
 613  \r
 614   @param channel_id\r
 615     The channel_id parameter identifies the PDMA channel used by the function.\r
 616  */\r
 617 void PDMA_enable_irq( pdma_channel_id_t channel_id );\r
 618 \r
 619 /***************************************************************************//**\r
 620   The PDMA_disable_irq() disables interrupts for a specific PDMA channel.\r
 621  \r
 622   @param channel_id\r
 623     The channel_id parameter identifies the PDMA channel used by the function.\r
 624  */\r
 625 static __INLINE void PDMA_disable_irq( pdma_channel_id_t channel_id )\r
 626 {\r
 627     PDMA->CHANNEL[channel_id].CRTL &= ~PDMA_IRQ_ENABLE_MASK;\r
 628 }\r
 629 \r
 630 /***************************************************************************//**\r
 631   The PDMA_set_irq_handler() function registers a handler function for\r
 632   interrupts generated on the completion of a transfer on a specific PDMA\r
 633   channel. This function also enables the PDMA interrupt both in the PDMA\r
 634   controller and in the Cortex-M3 interrupt controller.\r
 635  \r
 636   @param channel_id\r
 637     The channel_id parameter identifies the PDMA channel used by the function.\r
 638     \r
 639   @param handler\r
 640     The handler parameter is a pointer to the function that will be called when\r
 641     a transfer completes on the PDMA channel identified by channel_id and the\r
 642     interrupt is enabled for that channel.\r
 643     \r
 644   Example:\r
 645   @code\r
 646   void slave_dma_irq_handler( void )\r
 647   {\r
 648       if ( g_spi1_rx_buffer[2] == 0x99 )\r
 649       {\r
 650           PDMA_load_next_buffer\r
 651           (\r
 652               PDMA_CHANNEL_0,\r
 653               (uint32_t)g_spi1_tx_buffer_b,\r
 654               PDMA_SPI1_TX_REGISTER,\r
 655               sizeof(g_spi1_tx_buffer_b)\r
 656           );      \r
 657       }\r
 658       PDMA_disable_irq( PDMA_CHANNEL_3 );\r
 659   }\r
 660   \r
 661   void setup_dma( void )\r
 662   {\r
 663       PDMA_init();\r
 664       PDMA_configure\r
 665       (\r
 666            PDMA_CHANNEL_0, \r
 667            PDMA_TO_SPI_1, \r
 668            PDMA_LOW_PRIORITY | PDMA_BYTE_TRANSFER | PDMA_INC_SRC_ONE_BYTE\r
 669       );\r
 670       PDMA_configure\r
 671       ( \r
 672            PDMA_CHANNEL_3,\r
 673            PDMA_FROM_SPI_1,\r
 674            PDMA_HIGH_PRIORITY | PDMA_BYTE_TRANSFER | PDMA_INC_DEST_ONE_BYTE\r
 675       );\r
 676       PDMA_set_irq_handler( PDMA_CHANNEL_3, slave_dma_irq_handler );\r
 677       PDMA_start( PDMA_CHANNEL_3, PDMA_SPI1_RX_REGISTER, (uint32_t)g_spi1_rx_buffer, 3 ); \r
 678   }\r
 679   @endcode\r
 680  */\r
 681 void PDMA_set_irq_handler\r
 682 (\r
 683     pdma_channel_id_t channel_id,\r
 684     pdma_channel_isr_t handler\r
 685 );\r
 686 \r
 687 /***************************************************************************//**\r
 688   The PDMA_clear_irq() function clears interrupts for a specific PDMA channel.\r
 689   This function also clears the PDMA interrupt in the Cortex-M3 NVIC.\r
 690  \r
 691   @param channel_id\r
 692     The channel_id parameter identifies the PDMA channel used by the function.\r
 693  */\r
 694 void PDMA_clear_irq\r
 695 (\r
 696     pdma_channel_id_t channel_id\r
 697 );\r
 698 \r
 699 #ifdef __cplusplus\r
 700 }\r
 701 #endif\r
 702 \r
 703 #endif  /* __MSS_PERIPHERAL_DMA_H_ */\r