arch/arm/mach-bcmring/include/csp/dmacHw.h

   1 /*****************************************************************************
   2 * Copyright 2004 - 2008 Broadcom Corporation.  All rights reserved.
   3 *
   4 * Unless you and Broadcom execute a separate written software license
   5 * agreement governing use of this software, this software is licensed to you
   6 * under the terms of the GNU General Public License version 2, available at
   7 * http://www.broadcom.com/licenses/GPLv2.php (the "GPL").
   8 *
   9 * Notwithstanding the above, under no circumstances may you combine this
  10 * software in any way with any other Broadcom software provided under a
  11 * license other than the GPL, without Broadcom's express prior written
  12 * consent.
  13 *****************************************************************************/
  14
  15 /****************************************************************************/
  16 /**
  17 *  @file    dmacHw.h
  18 *
  19 *  @brief   API definitions for low level DMA controller driver
  20 *
  21 */
  22 /****************************************************************************/
  23 #ifndef _DMACHW_H
  24 #define _DMACHW_H
  25
  26 #include <stddef.h>
  27
  28 #include <csp/stdint.h>
  29 #include <mach/csp/dmacHw_reg.h>
  30
  31 /* Define DMA Channel ID using DMA controller number (m) and channel number (c).
  32
  33    System specific channel ID should be defined as follows
  34
  35    For example:
  36
  37    #include <dmacHw.h>
  38    ...
  39    #define systemHw_LCD_CHANNEL_ID                dmacHw_MAKE_CHANNEL_ID(0,5)
  40    #define systemHw_SWITCH_RX_CHANNEL_ID          dmacHw_MAKE_CHANNEL_ID(0,0)
  41    #define systemHw_SWITCH_TX_CHANNEL_ID          dmacHw_MAKE_CHANNEL_ID(0,1)
  42    #define systemHw_APM_RX_CHANNEL_ID             dmacHw_MAKE_CHANNEL_ID(0,3)
  43    #define systemHw_APM_TX_CHANNEL_ID             dmacHw_MAKE_CHANNEL_ID(0,4)
  44    ...
  45    #define systemHw_SHARED1_CHANNEL_ID            dmacHw_MAKE_CHANNEL_ID(1,4)
  46    #define systemHw_SHARED2_CHANNEL_ID            dmacHw_MAKE_CHANNEL_ID(1,5)
  47    #define systemHw_SHARED3_CHANNEL_ID            dmacHw_MAKE_CHANNEL_ID(0,6)
  48    ...
  49 */
  50 #define dmacHw_MAKE_CHANNEL_ID(m, c)         (m << 8 | c)
  51
  52 typedef enum {
  53         dmacHw_CHANNEL_PRIORITY_0 = dmacHw_REG_CFG_LO_CH_PRIORITY_0,    /* Channel priority 0. Lowest priority DMA channel */
  54         dmacHw_CHANNEL_PRIORITY_1 = dmacHw_REG_CFG_LO_CH_PRIORITY_1,    /* Channel priority 1 */
  55         dmacHw_CHANNEL_PRIORITY_2 = dmacHw_REG_CFG_LO_CH_PRIORITY_2,    /* Channel priority 2 */
  56         dmacHw_CHANNEL_PRIORITY_3 = dmacHw_REG_CFG_LO_CH_PRIORITY_3,    /* Channel priority 3 */
  57         dmacHw_CHANNEL_PRIORITY_4 = dmacHw_REG_CFG_LO_CH_PRIORITY_4,    /* Channel priority 4 */
  58         dmacHw_CHANNEL_PRIORITY_5 = dmacHw_REG_CFG_LO_CH_PRIORITY_5,    /* Channel priority 5 */
  59         dmacHw_CHANNEL_PRIORITY_6 = dmacHw_REG_CFG_LO_CH_PRIORITY_6,    /* Channel priority 6 */
  60         dmacHw_CHANNEL_PRIORITY_7 = dmacHw_REG_CFG_LO_CH_PRIORITY_7     /* Channel priority 7. Highest priority DMA channel */
  61 } dmacHw_CHANNEL_PRIORITY_e;
  62
  63 /* Source destination master interface */
  64 typedef enum {
  65         dmacHw_SRC_MASTER_INTERFACE_1 = dmacHw_REG_CTL_SMS_1,   /* Source DMA master interface 1 */
  66         dmacHw_SRC_MASTER_INTERFACE_2 = dmacHw_REG_CTL_SMS_2,   /* Source DMA master interface 2 */
  67         dmacHw_DST_MASTER_INTERFACE_1 = dmacHw_REG_CTL_DMS_1,   /* Destination DMA master interface 1 */
  68         dmacHw_DST_MASTER_INTERFACE_2 = dmacHw_REG_CTL_DMS_2    /* Destination DMA master interface 2 */
  69 } dmacHw_MASTER_INTERFACE_e;
  70
  71 typedef enum {
  72         dmacHw_SRC_TRANSACTION_WIDTH_8 = dmacHw_REG_CTL_SRC_TR_WIDTH_8, /* Source 8 bit  (1 byte) per transaction */
  73         dmacHw_SRC_TRANSACTION_WIDTH_16 = dmacHw_REG_CTL_SRC_TR_WIDTH_16,       /* Source 16 bit (2 byte) per transaction */
  74         dmacHw_SRC_TRANSACTION_WIDTH_32 = dmacHw_REG_CTL_SRC_TR_WIDTH_32,       /* Source 32 bit (4 byte) per transaction */
  75         dmacHw_SRC_TRANSACTION_WIDTH_64 = dmacHw_REG_CTL_SRC_TR_WIDTH_64,       /* Source 64 bit (8 byte) per transaction */
  76         dmacHw_DST_TRANSACTION_WIDTH_8 = dmacHw_REG_CTL_DST_TR_WIDTH_8, /* Destination 8 bit  (1 byte) per transaction */
  77         dmacHw_DST_TRANSACTION_WIDTH_16 = dmacHw_REG_CTL_DST_TR_WIDTH_16,       /* Destination 16 bit (2 byte) per transaction */
  78         dmacHw_DST_TRANSACTION_WIDTH_32 = dmacHw_REG_CTL_DST_TR_WIDTH_32,       /* Destination 32 bit (4 byte) per transaction */
  79         dmacHw_DST_TRANSACTION_WIDTH_64 = dmacHw_REG_CTL_DST_TR_WIDTH_64        /* Destination 64 bit (8 byte) per transaction */
  80 } dmacHw_TRANSACTION_WIDTH_e;
  81
  82 typedef enum {
  83         dmacHw_SRC_BURST_WIDTH_0 = dmacHw_REG_CTL_SRC_MSIZE_0,  /* Source No burst */
  84         dmacHw_SRC_BURST_WIDTH_4 = dmacHw_REG_CTL_SRC_MSIZE_4,  /* Source 4  X dmacHw_TRANSACTION_WIDTH_xxx bytes per burst */
  85         dmacHw_SRC_BURST_WIDTH_8 = dmacHw_REG_CTL_SRC_MSIZE_8,  /* Source 8  X dmacHw_TRANSACTION_WIDTH_xxx bytes per burst */
  86         dmacHw_SRC_BURST_WIDTH_16 = dmacHw_REG_CTL_SRC_MSIZE_16,        /* Source 16 X dmacHw_TRANSACTION_WIDTH_xxx bytes per burst */
  87         dmacHw_DST_BURST_WIDTH_0 = dmacHw_REG_CTL_DST_MSIZE_0,  /* Destination No burst */
  88         dmacHw_DST_BURST_WIDTH_4 = dmacHw_REG_CTL_DST_MSIZE_4,  /* Destination 4  X dmacHw_TRANSACTION_WIDTH_xxx bytes per burst */
  89         dmacHw_DST_BURST_WIDTH_8 = dmacHw_REG_CTL_DST_MSIZE_8,  /* Destination 8  X dmacHw_TRANSACTION_WIDTH_xxx bytes per burst */
  90         dmacHw_DST_BURST_WIDTH_16 = dmacHw_REG_CTL_DST_MSIZE_16 /* Destination 16 X dmacHw_TRANSACTION_WIDTH_xxx bytes per burst */
  91 } dmacHw_BURST_WIDTH_e;
  92
  93 typedef enum {
  94         dmacHw_TRANSFER_TYPE_MEM_TO_MEM = dmacHw_REG_CTL_TTFC_MM_DMAC,  /* Memory to memory transfer */
  95         dmacHw_TRANSFER_TYPE_PERIPHERAL_TO_MEM = dmacHw_REG_CTL_TTFC_PM_DMAC,   /* Peripheral to memory transfer */
  96         dmacHw_TRANSFER_TYPE_MEM_TO_PERIPHERAL = dmacHw_REG_CTL_TTFC_MP_DMAC,   /* Memory to peripheral transfer */
  97         dmacHw_TRANSFER_TYPE_PERIPHERAL_TO_PERIPHERAL = dmacHw_REG_CTL_TTFC_PP_DMAC     /* Peripheral to peripheral transfer */
  98 } dmacHw_TRANSFER_TYPE_e;
  99
 100 typedef enum {
 101         dmacHw_TRANSFER_MODE_PERREQUEST,        /* Block transfer per DMA request */
 102         dmacHw_TRANSFER_MODE_CONTINUOUS,        /* Continuous transfer of streaming data */
 103         dmacHw_TRANSFER_MODE_PERIODIC   /* Periodic transfer of streaming data */
 104 } dmacHw_TRANSFER_MODE_e;
 105
 106 typedef enum {
 107         dmacHw_SRC_ADDRESS_UPDATE_MODE_INC = dmacHw_REG_CTL_SINC_INC,   /* Increment source address after every transaction */
 108         dmacHw_SRC_ADDRESS_UPDATE_MODE_DEC = dmacHw_REG_CTL_SINC_DEC,   /* Decrement source address after every transaction */
 109         dmacHw_DST_ADDRESS_UPDATE_MODE_INC = dmacHw_REG_CTL_DINC_INC,   /* Increment destination address after every transaction */
 110         dmacHw_DST_ADDRESS_UPDATE_MODE_DEC = dmacHw_REG_CTL_DINC_DEC,   /* Decrement destination address after every transaction */
 111         dmacHw_SRC_ADDRESS_UPDATE_MODE_NC = dmacHw_REG_CTL_SINC_NC,     /* No change in source address after every transaction */
 112         dmacHw_DST_ADDRESS_UPDATE_MODE_NC = dmacHw_REG_CTL_DINC_NC      /* No change in destination address after every transaction */
 113 } dmacHw_ADDRESS_UPDATE_MODE_e;
 114
 115 typedef enum {
 116         dmacHw_FLOW_CONTROL_DMA,        /* DMA working as flow controller (default) */
 117         dmacHw_FLOW_CONTROL_PERIPHERAL  /* Peripheral working as flow controller */
 118 } dmacHw_FLOW_CONTROL_e;
 119
 120 typedef enum {
 121         dmacHw_TRANSFER_STATUS_BUSY,    /* DMA Transfer ongoing */
 122         dmacHw_TRANSFER_STATUS_DONE,    /* DMA Transfer completed */
 123         dmacHw_TRANSFER_STATUS_ERROR    /* DMA Transfer error */
 124 } dmacHw_TRANSFER_STATUS_e;
 125
 126 typedef enum {
 127         dmacHw_INTERRUPT_DISABLE,       /* Interrupt disable  */
 128         dmacHw_INTERRUPT_ENABLE /* Interrupt enable */
 129 } dmacHw_INTERRUPT_e;
 130
 131 typedef enum {
 132         dmacHw_INTERRUPT_STATUS_NONE = 0x0,     /* No DMA interrupt */
 133         dmacHw_INTERRUPT_STATUS_TRANS = 0x1,    /* End of DMA transfer interrupt */
 134         dmacHw_INTERRUPT_STATUS_BLOCK = 0x2,    /* End of block transfer interrupt */
 135         dmacHw_INTERRUPT_STATUS_ERROR = 0x4     /* Error interrupt */
 136 } dmacHw_INTERRUPT_STATUS_e;
 137
 138 typedef enum {
 139         dmacHw_CONTROLLER_ATTRIB_CHANNEL_NUM,   /* Number of DMA channel */
 140         dmacHw_CONTROLLER_ATTRIB_CHANNEL_MAX_BLOCK_SIZE,        /* Maximum channel burst size */
 141         dmacHw_CONTROLLER_ATTRIB_MASTER_INTF_NUM,       /* Number of DMA master interface */
 142         dmacHw_CONTROLLER_ATTRIB_CHANNEL_BUS_WIDTH,     /* Channel Data bus width */
 143         dmacHw_CONTROLLER_ATTRIB_CHANNEL_FIFO_SIZE      /* Channel FIFO size */
 144 } dmacHw_CONTROLLER_ATTRIB_e;
 145
 146 typedef unsigned long dmacHw_HANDLE_t;  /* DMA channel handle */
 147 typedef uint32_t dmacHw_ID_t;   /* DMA channel Id.  Must be created using
 148                                    "dmacHw_MAKE_CHANNEL_ID" macro
 149                                  */
 150 /* DMA channel configuration parameters */
 151 typedef struct {
 152         uint32_t srcPeripheralPort;     /* Source peripheral port */
 153         uint32_t dstPeripheralPort;     /* Destination peripheral port */
 154         uint32_t srcStatusRegisterAddress;      /* Source status register address */
 155         uint32_t dstStatusRegisterAddress;      /* Destination status register address of type  */
 156
 157         uint32_t srcGatherWidth;        /* Number of bytes gathered before successive gather opearation */
 158         uint32_t srcGatherJump; /* Number of bytes jumpped before successive gather opearation */
 159         uint32_t dstScatterWidth;       /* Number of bytes sacattered before successive scatter opearation */
 160         uint32_t dstScatterJump;        /* Number of bytes jumpped  before successive scatter opearation */
 161         uint32_t maxDataPerBlock;       /* Maximum number of bytes to be transferred per block/descrptor.
 162                                            0 = Maximum possible.
 163                                          */
 164
 165         dmacHw_ADDRESS_UPDATE_MODE_e srcUpdate; /* Source address update mode */
 166         dmacHw_ADDRESS_UPDATE_MODE_e dstUpdate; /* Destination address update mode */
 167         dmacHw_TRANSFER_TYPE_e transferType;    /* DMA transfer type  */
 168         dmacHw_TRANSFER_MODE_e transferMode;    /* DMA transfer mode */
 169         dmacHw_MASTER_INTERFACE_e srcMasterInterface;   /* DMA source interface  */
 170         dmacHw_MASTER_INTERFACE_e dstMasterInterface;   /* DMA destination interface */
 171         dmacHw_TRANSACTION_WIDTH_e srcMaxTransactionWidth;      /* Source transaction width   */
 172         dmacHw_TRANSACTION_WIDTH_e dstMaxTransactionWidth;      /* Destination transaction width */
 173         dmacHw_BURST_WIDTH_e srcMaxBurstWidth;  /* Source burst width */
 174         dmacHw_BURST_WIDTH_e dstMaxBurstWidth;  /* Destination burst width */
 175         dmacHw_INTERRUPT_e blockTransferInterrupt;      /* Block trsnafer interrupt */
 176         dmacHw_INTERRUPT_e completeTransferInterrupt;   /* Complete DMA trsnafer interrupt */
 177         dmacHw_INTERRUPT_e errorInterrupt;      /* Error interrupt */
 178         dmacHw_CHANNEL_PRIORITY_e channelPriority;      /* Channel priority */
 179         dmacHw_FLOW_CONTROL_e flowControler;    /* Data flow controller */
 180 } dmacHw_CONFIG_t;
 181
 182 /****************************************************************************/
 183 /**
 184 *  @brief   Initializes DMA
 185 *
 186 *  This function initializes DMA CSP driver
 187 *
 188 *  @note
 189 *     Must be called before using any DMA channel
 190 */
 191 /****************************************************************************/
 192 void dmacHw_initDma(void);
 193
 194 /****************************************************************************/
 195 /**
 196 *  @brief   Exit function for  DMA
 197 *
 198 *  This function isolates DMA from the system
 199 *
 200 */
 201 /****************************************************************************/
 202 void dmacHw_exitDma(void);
 203
 204 /****************************************************************************/
 205 /**
 206 *  @brief   Gets a handle to a DMA channel
 207 *
 208 *  This function returns a handle, representing a control block of a particular DMA channel
 209 *
 210 *  @return  -1       - On Failure
 211 *            handle  - On Success, representing a channel control block
 212 *
 213 *  @note
 214 *     None  Channel ID must be created using "dmacHw_MAKE_CHANNEL_ID" macro
 215 */
 216 /****************************************************************************/
 217 dmacHw_HANDLE_t dmacHw_getChannelHandle(dmacHw_ID_t channelId   /* [ IN ] DMA Channel Id */
 218     );
 219
 220 /****************************************************************************/
 221 /**
 222 *  @brief   Initializes a DMA channel for use
 223 *
 224 *  This function initializes and resets a DMA channel for use
 225 *
 226 *  @return  -1     - On Failure
 227 *            0     - On Success
 228 *
 229 *  @note
 230 *     None
 231 */
 232 /****************************************************************************/
 233 int dmacHw_initChannel(dmacHw_HANDLE_t handle   /*  [ IN ] DMA Channel handle  */
 234     );
 235
 236 /****************************************************************************/
 237 /**
 238 *  @brief  Estimates number of descriptor needed to perform certain DMA transfer
 239 *
 240 *
 241 *  @return  On failure : -1
 242 *           On success : Number of descriptor count
 243 *
 244 *
 245 */
 246 /****************************************************************************/
 247 int dmacHw_calculateDescriptorCount(dmacHw_CONFIG_t *pConfig,   /*   [ IN ] Configuration settings */
 248                                     void *pSrcAddr,     /*   [ IN ] Source (Peripheral/Memory) address */
 249                                     void *pDstAddr,     /*   [ IN ] Destination (Peripheral/Memory) address */
 250                                     size_t dataLen      /*   [ IN ] Data length in bytes */
 251     );
 252
 253 /****************************************************************************/
 254 /**
 255 *  @brief   Initializes descriptor ring
 256 *
 257 *  This function will initializes the descriptor ring of a DMA channel
 258 *
 259 *
 260 *  @return   -1 - On failure
 261 *             0 - On success
 262 *  @note
 263 *     - "len" parameter should be obtained from "dmacHw_descriptorLen"
 264 *     - Descriptor buffer MUST be 32 bit aligned and uncached as it
 265 *       is accessed by ARM and DMA
 266 */
 267 /****************************************************************************/
 268 int dmacHw_initDescriptor(void *pDescriptorVirt,        /*  [ IN ] Virtual address of uncahced buffer allocated to form descriptor ring */
 269                           uint32_t descriptorPhyAddr,   /*  [ IN ] Physical address of pDescriptorVirt (descriptor buffer) */
 270                           uint32_t len, /*  [ IN ] Size of the pBuf */
 271                           uint32_t num  /*  [ IN ] Number of descriptor in the ring */
 272     );
 273
 274 /****************************************************************************/
 275 /**
 276 *  @brief  Finds amount of memory required to form a descriptor ring
 277 *
 278 *
 279 *  @return   Number of bytes required to form a descriptor ring
 280 *
 281 *
 282 *  @note
 283 *     None
 284 */
 285 /****************************************************************************/
 286 uint32_t dmacHw_descriptorLen(uint32_t descCnt  /*  [ IN ] Number of descriptor in the ring */
 287     );
 288
 289 /****************************************************************************/
 290 /**
 291 *  @brief   Configure DMA channel
 292 *
 293 *  @return  0  : On success
 294 *           -1 : On failure
 295 */
 296 /****************************************************************************/
 297 int dmacHw_configChannel(dmacHw_HANDLE_t handle,        /*  [ IN ] DMA Channel handle  */
 298                          dmacHw_CONFIG_t *pConfig       /*   [ IN ] Configuration settings */
 299     );
 300
 301 /****************************************************************************/
 302 /**
 303 *  @brief   Set descriptors for known data length
 304 *
 305 *  When DMA has to work as a flow controller, this function prepares the
 306 *  descriptor chain to transfer data
 307 *
 308 *  from:
 309 *          - Memory to memory
 310 *          - Peripheral to memory
 311 *          - Memory to Peripheral
 312 *          - Peripheral to Peripheral
 313 *
 314 *  @return   -1 - On failure
 315 *             0 - On success
 316 *
 317 */
 318 /****************************************************************************/
 319 int dmacHw_setDataDescriptor(dmacHw_CONFIG_t *pConfig,  /*  [ IN ] Configuration settings */
 320                              void *pDescriptor, /*  [ IN ] Descriptor buffer  */
 321                              void *pSrcAddr,    /*  [ IN ] Source (Peripheral/Memory) address */
 322                              void *pDstAddr,    /*  [ IN ] Destination (Peripheral/Memory) address */
 323                              size_t dataLen     /*  [ IN ] Length in bytes   */
 324     );
 325
 326 /****************************************************************************/
 327 /**
 328 *  @brief   Indicates whether DMA transfer is in progress or completed
 329 *
 330 *  @return   DMA transfer status
 331 *          dmacHw_TRANSFER_STATUS_BUSY:         DMA Transfer ongoing
 332 *          dmacHw_TRANSFER_STATUS_DONE:         DMA Transfer completed
 333 *          dmacHw_TRANSFER_STATUS_ERROR:        DMA Transfer error
 334 *
 335 */
 336 /****************************************************************************/
 337 dmacHw_TRANSFER_STATUS_e dmacHw_transferCompleted(dmacHw_HANDLE_t handle        /*   [ IN ] DMA Channel handle  */
 338     );
 339
 340 /****************************************************************************/
 341 /**
 342 *  @brief   Set descriptor carrying control information
 343 *
 344 *  This function will be used to send specific control information to the device
 345 *  using the DMA channel
 346 *
 347 *
 348 *  @return  -1 - On failure
 349 *            0 - On success
 350 *
 351 *  @note
 352 *     None
 353 */
 354 /****************************************************************************/
 355 int dmacHw_setControlDescriptor(dmacHw_CONFIG_t *pConfig,       /*  [ IN ] Configuration settings */
 356                                 void *pDescriptor,      /*  [ IN ] Descriptor buffer  */
 357                                 uint32_t ctlAddress,    /*  [ IN ] Address of the device control register  */
 358                                 uint32_t control        /*  [ IN ] Device control information */
 359     );
 360
 361 /****************************************************************************/
 362 /**
 363 *  @brief   Read data DMA transferred to memory
 364 *
 365 *  This function will read data that has been DMAed to memory while transferring from:
 366 *          - Memory to memory
 367 *          - Peripheral to memory
 368 *
 369 *  @return  0 - No more data is available to read
 370 *           1 - More data might be available to read
 371 *
 372 */
 373 /****************************************************************************/
 374 int dmacHw_readTransferredData(dmacHw_HANDLE_t handle,  /*  [ IN ] DMA Channel handle    */
 375                                dmacHw_CONFIG_t *pConfig,        /*  [ IN ]  Configuration settings */
 376                                void *pDescriptor,       /*  [ IN ] Descriptor buffer  */
 377                                void **ppBbuf,   /*  [ OUT ] Data received */
 378                                size_t *pLlen    /*  [ OUT ] Length of the data received */
 379     );
 380
 381 /****************************************************************************/
 382 /**
 383 *  @brief   Prepares descriptor ring, when source peripheral working as a flow controller
 384 *
 385 *  This function will form the descriptor ring by allocating buffers, when source peripheral
 386 *  has to work as a flow controller to transfer data from:
 387 *           - Peripheral to memory.
 388 *
 389 *  @return  -1 - On failure
 390 *            0 - On success
 391 *
 392 *
 393 *  @note
 394 *     None
 395 */
 396 /****************************************************************************/
 397 int dmacHw_setVariableDataDescriptor(dmacHw_HANDLE_t handle,    /*  [ IN ] DMA Channel handle   */
 398                                      dmacHw_CONFIG_t *pConfig,  /*  [ IN ] Configuration settings */
 399                                      void *pDescriptor, /*  [ IN ] Descriptor buffer  */
 400                                      uint32_t srcAddr,  /*  [ IN ] Source peripheral address */
 401                                      void *(*fpAlloc) (int len),        /*  [ IN ] Function pointer  that provides destination memory */
 402                                      int len,   /*  [ IN ] Number of bytes "fpAlloc" will allocate for destination */
 403                                      int num    /*  [ IN ] Number of descriptor to set */
 404     );
 405
 406 /****************************************************************************/
 407 /**
 408 *  @brief   Program channel register to initiate transfer
 409 *
 410 *  @return  void
 411 *
 412 *
 413 *  @note
 414 *     - Descriptor buffer MUST ALWAYS be flushed before calling this function
 415 *     - This function should also be called from ISR to program the channel with
 416 *       pending descriptors
 417 */
 418 /****************************************************************************/
 419 void dmacHw_initiateTransfer(dmacHw_HANDLE_t handle,    /*   [ IN ] DMA Channel handle */
 420                              dmacHw_CONFIG_t *pConfig,  /*   [ IN ] Configuration settings */
 421                              void *pDescriptor  /*   [ IN ] Descriptor buffer  */
 422     );
 423
 424 /****************************************************************************/
 425 /**
 426 *  @brief   Resets descriptor control information
 427 *
 428 *  @return  void
 429 */
 430 /****************************************************************************/
 431 void dmacHw_resetDescriptorControl(void *pDescriptor    /*   [ IN ] Descriptor buffer  */
 432     );
 433
 434 /****************************************************************************/
 435 /**
 436 *  @brief   Program channel register to stop transfer
 437 *
 438 *  Ensures the channel is not doing any transfer after calling this function
 439 *
 440 *  @return  void
 441 *
 442 */
 443 /****************************************************************************/
 444 void dmacHw_stopTransfer(dmacHw_HANDLE_t handle /*   [ IN ] DMA Channel handle */
 445     );
 446
 447 /****************************************************************************/
 448 /**
 449 *  @brief   Check the existence of pending descriptor
 450 *
 451 *  This function confirmes if there is any pending descriptor in the chain
 452 *  to program the channel
 453 *
 454 *  @return  1 : Channel need to be programmed with pending descriptor
 455 *           0 : No more pending descriptor to programe the channel
 456 *
 457 *  @note
 458 *     - This function should be called from ISR in case there are pending
 459 *       descriptor to program the channel.
 460 *
 461 *     Example:
 462 *
 463 *     dmac_isr ()
 464 *     {
 465 *         ...
 466 *         if (dmacHw_descriptorPending (handle))
 467 *         {
 468 *            dmacHw_initiateTransfer (handle);
 469 *         }
 470 *     }
 471 *
 472 */
 473 /****************************************************************************/
 474 uint32_t dmacHw_descriptorPending(dmacHw_HANDLE_t handle,       /*   [ IN ] DMA Channel handle */
 475                                   void *pDescriptor     /*   [ IN ] Descriptor buffer */
 476     );
 477
 478 /****************************************************************************/
 479 /**
 480 *  @brief   Deallocates source or destination memory, allocated
 481 *
 482 *  This function can be called to deallocate data memory that was DMAed successfully
 483 *
 484 *  @return  -1  - On failure
 485 *            0  - On success
 486 *
 487 *  @note
 488 *     This function will be called ONLY, when source OR destination address is pointing
 489 *     to dynamic memory
 490 */
 491 /****************************************************************************/
 492 int dmacHw_freeMem(dmacHw_CONFIG_t *pConfig,    /*  [ IN ] Configuration settings */
 493                    void *pDescriptor,   /*  [ IN ] Descriptor buffer  */
 494                    void (*fpFree) (void *)      /*  [ IN ] Function pointer to free data memory */
 495     );
 496
 497 /****************************************************************************/
 498 /**
 499 *  @brief   Clears the interrupt
 500 *
 501 *  This function clears the DMA channel specific interrupt
 502 *
 503 *  @return   N/A
 504 *
 505 *  @note
 506 *     Must be called under the context of ISR
 507 */
 508 /****************************************************************************/
 509 void dmacHw_clearInterrupt(dmacHw_HANDLE_t handle       /*  [ IN ] DMA Channel handle  */
 510     );
 511
 512 /****************************************************************************/
 513 /**
 514 *  @brief   Returns the cause of channel specific DMA interrupt
 515 *
 516 *  This function returns the cause of interrupt
 517 *
 518 *  @return  Interrupt status, each bit representing a specific type of interrupt
 519 *           of type dmacHw_INTERRUPT_STATUS_e
 520 *  @note
 521 *           This function should be called under the context of ISR
 522 */
 523 /****************************************************************************/
 524 dmacHw_INTERRUPT_STATUS_e dmacHw_getInterruptStatus(dmacHw_HANDLE_t handle      /*  [ IN ] DMA Channel handle  */
 525     );
 526
 527 /****************************************************************************/
 528 /**
 529 *  @brief   Indentifies a DMA channel causing interrupt
 530 *
 531 *  This functions returns a channel causing interrupt of type dmacHw_INTERRUPT_STATUS_e
 532 *
 533 *  @return  NULL   : No channel causing DMA interrupt
 534 *           ! NULL : Handle to a channel causing DMA interrupt
 535 *  @note
 536 *     dmacHw_clearInterrupt() must be called with a valid handle after calling this function
 537 */
 538 /****************************************************************************/
 539 dmacHw_HANDLE_t dmacHw_getInterruptSource(void);
 540
 541 /****************************************************************************/
 542 /**
 543 *  @brief   Sets channel specific user data
 544 *
 545 *  This function associates user data to a specific DMA channel
 546 *
 547 */
 548 /****************************************************************************/
 549 void dmacHw_setChannelUserData(dmacHw_HANDLE_t handle,  /*  [ IN ] DMA Channel handle  */
 550                                void *userData   /*  [ IN ] User data  */
 551     );
 552
 553 /****************************************************************************/
 554 /**
 555 *  @brief   Gets channel specific user data
 556 *
 557 *  This function returns user data specific to a DMA channel
 558 *
 559 *  @return   user data
 560 */
 561 /****************************************************************************/
 562 void *dmacHw_getChannelUserData(dmacHw_HANDLE_t handle  /*  [ IN ] DMA Channel handle  */
 563     );
 564
 565 /****************************************************************************/
 566 /**
 567 *  @brief   Displays channel specific registers and other control parameters
 568 *
 569 *
 570 *  @return  void
 571 *
 572 *  @note
 573 *     None
 574 */
 575 /****************************************************************************/
 576 void dmacHw_printDebugInfo(dmacHw_HANDLE_t handle,      /*  [ IN ] DMA Channel handle  */
 577                            void *pDescriptor,   /*  [ IN ] Descriptor buffer  */
 578                            int (*fpPrint) (const char *, ...)   /*  [ IN ] Print callback function */
 579     );
 580
 581 /****************************************************************************/
 582 /**
 583 *  @brief   Provides DMA controller attributes
 584 *
 585 *
 586 *  @return  DMA controller attributes
 587 *
 588 *  @note
 589 *     None
 590 */
 591 /****************************************************************************/
 592 uint32_t dmacHw_getDmaControllerAttribute(dmacHw_HANDLE_t handle,       /*  [ IN ]  DMA Channel handle  */
 593                                           dmacHw_CONTROLLER_ATTRIB_e attr       /*  [ IN ]  DMA Controller attribute of type  dmacHw_CONTROLLER_ATTRIB_e */
 594     );
 595
 596 #endif /* _DMACHW_H */