git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_A9_Zynq_ZC702/RTOSDemo_bsp/ps7_cortexa9_0/libsrc/dmaps_v2_0/src/xdmaps.h

   1 /******************************************************************************
   2 *
   3 * Copyright (C) 2009 - 2014 Xilinx, Inc.  All rights reserved.
   4 *
   5 * Permission is hereby granted, free of charge, to any person obtaining a copy
   6 * of this software and associated documentation files (the "Software"), to deal
   7 * in the Software without restriction, including without limitation the rights
   8 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
   9 * copies of the Software, and to permit persons to whom the Software is
  10 * furnished to do so, subject to the following conditions:
  11 *
  12 * The above copyright notice and this permission notice shall be included in
  13 * all copies or substantial portions of the Software.
  14 *
  15 * Use of the Software is limited solely to applications:
  16 * (a) running on a Xilinx device, or
  17 * (b) that interact with a Xilinx device through a bus or interconnect.
  18 *
  19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  20 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  21 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
  22 * XILINX  BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  23 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
  24 * OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  25 * SOFTWARE.
  26 *
  27 * Except as contained in this notice, the name of the Xilinx shall not be used
  28 * in advertising or otherwise to promote the sale, use or other dealings in
  29 * this Software without prior written authorization from Xilinx.
  30 *
  31 ******************************************************************************/
  32 /****************************************************************************/
  33 /**
  34 *
  35 * @file xdmaps.h
  36 * @addtogroup dmaps_v2_0
  37 * @{
  38 * @details
  39 *
  40 *
  41 * <pre>
  42 * MODIFICATION HISTORY:
  43 *
  44 * Ver   Who     Date     Changes
  45 * ----- ------ -------- ----------------------------------------------
  46 * 1.00  hbm    08/19/10 First Release
  47 * 1.01a nm     12/20/12 Added definition XDMAPS_CHANNELS_PER_DEV which specifies
  48 *                       the maximum number of channels.
  49 *                       Replaced the usage of XPAR_XDMAPS_CHANNELS_PER_DEV
  50 *                       with XDMAPS_CHANNELS_PER_DEV defined in xdmaps_hw.h.
  51 *                       Added the tcl file to automatically generate the
  52 *                       xparameters.h
  53 * 1.02a sg     05/16/12 Made changes for doxygen and moved some function
  54 *                       header from the xdmaps.h file to xdmaps.c file
  55 *                       Other cleanup for coding guidelines and CR 657109
  56 *                       and CR 657898
  57 *                       The xdmaps_example_no_intr.c example is removed
  58 *                       as it is using interrupts  and is similar to
  59 *                       the interrupt example - CR 652477
  60 * 1.03a sg     07/16/2012 changed inline to __inline for CR665681
  61 * 1.04a nm     10/22/2012 Fixed CR# 681671.
  62 * 1.05a nm     04/15/2013 Fixed CR# 704396. Removed warnings when compiled
  63 *                         with -Wall and -Wextra option in bsp.
  64 *              05/01/2013 Fixed CR# 700189. Changed XDmaPs_BuildDmaProg()
  65 *                         function description.
  66 *                         Fixed CR# 704396. Removed unused variables
  67 *                         UseM2MByte & MemBurstLen from XDmaPs_BuildDmaProg()
  68 *                         function.
  69 * 1.07a asa    11/02/13. Made changes to fix compilation issues for iarcc.
  70 *                          Removed the PDBG prints. By default they were always
  71 *                          defined out and never used. The PDBG is non-standard for
  72 *                          Xilinx drivers and no other driver does something similar.
  73 *                          Since there is no easy way to fix compilation issues with
  74 *                          the IARCC compiler around PDBG, it is better to remove it.
  75 *                          Users can always use xil_printfs if they want to debug.
  76 * 2.0   adk    10/12/13  Updated as per the New Tcl API's
  77 * </pre>
  78 *
  79 *****************************************************************************/
  80
  81 #ifndef XDMAPS_H                /* prevent circular inclusions */
  82 #define XDMAPS_H                /* by using protection macros */
  83
  84 #ifdef __cplusplus
  85 extern "C" {
  86 #endif
  87
  88 /***************************** Include Files ********************************/
  89
  90 #include "xparameters.h"
  91 #include "xil_types.h"
  92 #include "xil_assert.h"
  93 #include "xstatus.h"
  94
  95 #include "xdmaps_hw.h"
  96
  97 /************************** Constant Definitions ****************************/
  98
  99 /**************************** Type Definitions ******************************/
 100
 101 /**
 102  * This typedef contains configuration information for the device.
 103  */
 104 typedef struct {
 105         u16 DeviceId;    /**< Unique ID  of device */
 106         u32 BaseAddress; /**< Base address of device (IPIF) */
 107 } XDmaPs_Config;
 108
 109
 110 /** DMA channle control structure. It's for AXI bus transaction.
 111  * This struct will be translated into a 32-bit channel control register value.
 112  */
 113 typedef struct {
 114         unsigned int EndianSwapSize;    /**< Endian swap size. */
 115         unsigned int DstCacheCtrl;      /**< Destination cache control */
 116         unsigned int DstProtCtrl;       /**< Destination protection control */
 117         unsigned int DstBurstLen;       /**< Destination burst length */
 118         unsigned int DstBurstSize;      /**< Destination burst size */
 119         unsigned int DstInc;            /**< Destination incrementing or fixed
 120                                          *   address */
 121         unsigned int SrcCacheCtrl;      /**< Source cache control */
 122         unsigned int SrcProtCtrl;       /**< Source protection control */
 123         unsigned int SrcBurstLen;       /**< Source burst length */
 124         unsigned int SrcBurstSize;      /**< Source burst size */
 125         unsigned int SrcInc;            /**< Source incrementing or fixed
 126                                          *   address */
 127 } XDmaPs_ChanCtrl;
 128
 129 /** DMA block descriptor stucture.
 130  */
 131 typedef struct {
 132         u32 SrcAddr;            /**< Source starting address */
 133         u32 DstAddr;            /**< Destination starting address */
 134         unsigned int Length;    /**< Number of bytes for the block */
 135 } XDmaPs_BD;
 136
 137 /**
 138  * A DMA command consisits of a channel control struct, a block descriptor,
 139  * a user defined program, a pointer pointing to generated DMA program, and
 140  * execution result.
 141  *
 142  */
 143 typedef struct {
 144         XDmaPs_ChanCtrl ChanCtrl;       /**< Channel Control Struct */
 145         XDmaPs_BD BD;                   /**< Together with SgLength field,
 146                                           *  it's a scatter-gather list.
 147                                           */
 148         void *UserDmaProg;              /**< If user wants the driver to
 149                                           *  execute their own DMA program,
 150                                           *  this field points to the DMA
 151                                           *  program.
 152                                           */
 153         int UserDmaProgLength;          /**< The length of user defined
 154                                           *  DMA program.
 155                                           */
 156
 157         void *GeneratedDmaProg;         /**< The DMA program genreated
 158                                          * by the driver. This field will be
 159                                          * set if a user invokes the DMA
 160                                          * program generation function. Or
 161                                          * the DMA command is finished and
 162                                          * a user informs the driver not to
 163                                          * release the program buffer.
 164                                          * This field has two purposes, one
 165                                          * is to ask the driver to generate
 166                                          * a DMA program while the DMAC is
 167                                          * performaning DMA transactions. The
 168                                          * other purpose is to debug the
 169                                          * driver.
 170                                          */
 171         int GeneratedDmaProgLength;      /**< The length of the DMA program
 172                                           * generated by the driver
 173                                           */
 174         int DmaStatus;                  /**< 0 on success, otherwise error code
 175                                          */
 176         u32 ChanFaultType;      /**< Channel fault type in case of fault
 177                                  */
 178         u32 ChanFaultPCAddr;    /**< Channel fault PC address
 179                                  */
 180 } XDmaPs_Cmd;
 181
 182 /**
 183  * It's the done handler a user can set for a channel
 184  */
 185 typedef void (*XDmaPsDoneHandler) (unsigned int Channel,
 186                                     XDmaPs_Cmd *DmaCmd,
 187                                     void *CallbackRef);
 188
 189 /**
 190  * It's the fault handler a user can set for a channel
 191  */
 192 typedef void (*XDmaPsFaultHandler) (unsigned int Channel,
 193                                      XDmaPs_Cmd *DmaCmd,
 194                                      void *CallbackRef);
 195
 196 #define XDMAPS_MAX_CHAN_BUFS    2
 197 #define XDMAPS_CHAN_BUF_LEN     128
 198
 199 /**
 200  * The XDmaPs_ProgBuf is the struct for a DMA program buffer.
 201  */
 202 typedef struct {
 203         char Buf[XDMAPS_CHAN_BUF_LEN];  /**< The actual buffer the holds the
 204                                           *  content */
 205         unsigned Len;                   /**< The actual length of the DMA
 206                                           *  program in bytes. */
 207         int Allocated;                  /**< A tag indicating whether the
 208                                           *  buffer is allocated or not */
 209 } XDmaPs_ProgBuf;
 210
 211 /**
 212  * The XDmaPs_ChannelData is a struct to book keep individual channel of
 213  * the DMAC.
 214  */
 215 typedef struct {
 216         unsigned DevId;                 /**< Device id indicating which DMAC */
 217         unsigned ChanId;                /**< Channel number of the DMAC */
 218         XDmaPs_ProgBuf ProgBufPool[XDMAPS_MAX_CHAN_BUFS]; /**< A pool of
 219                                                               program buffers*/
 220         XDmaPsDoneHandler DoneHandler;  /**< Done interrupt handler */
 221         void *DoneRef;                  /**< Done interrupt callback data */
 222         XDmaPs_Cmd *DmaCmdToHw;         /**< DMA command being executed */
 223         XDmaPs_Cmd *DmaCmdFromHw;       /**< DMA  command that is finished.
 224                                           *  This field is for debugging purpose
 225                                           */
 226         int HoldDmaProg;                /**< A tag indicating whether to hold the
 227                                           *  DMA program after the DMA is done.
 228                                           */
 229
 230 } XDmaPs_ChannelData;
 231
 232 /**
 233  * The XDmaPs driver instance data structure. A pointer to an instance data
 234  * structure is passed around by functions to refer to a specific driver
 235  * instance.
 236  */
 237 typedef struct {
 238         XDmaPs_Config Config;   /**< Configuration data structure */
 239         int IsReady;            /**< Device is Ready */
 240         int CacheLength;        /**< icache length */
 241         XDmaPsFaultHandler FaultHandler; /**< fault interrupt handler */
 242         void *FaultRef; /**< fault call back data */
 243         XDmaPs_ChannelData Chans[XDMAPS_CHANNELS_PER_DEV];
 244         /**<
 245          * channel data
 246          */
 247 } XDmaPs;
 248
 249 /*
 250  * Functions implemented in xdmaps.c
 251  */
 252 int XDmaPs_CfgInitialize(XDmaPs *InstPtr,
 253                           XDmaPs_Config *Config,
 254                           u32 EffectiveAddr);
 255
 256 int XDmaPs_Start(XDmaPs *InstPtr, unsigned int Channel,
 257                   XDmaPs_Cmd *Cmd,
 258                   int HoldDmaProg);
 259
 260 int XDmaPs_IsActive(XDmaPs *InstPtr, unsigned int Channel);
 261 int XDmaPs_GenDmaProg(XDmaPs *InstPtr, unsigned int Channel,
 262                        XDmaPs_Cmd *Cmd);
 263 int XDmaPs_FreeDmaProg(XDmaPs *InstPtr, unsigned int Channel,
 264                         XDmaPs_Cmd *Cmd);
 265 void XDmaPs_Print_DmaProg(XDmaPs_Cmd *Cmd);
 266
 267
 268 int XDmaPs_ResetManager(XDmaPs *InstPtr);
 269 int XDmaPs_ResetChannel(XDmaPs *InstPtr, unsigned int Channel);
 270
 271
 272 int XDmaPs_SetDoneHandler(XDmaPs *InstPtr,
 273                            unsigned Channel,
 274                            XDmaPsDoneHandler DoneHandler,
 275                            void *CallbackRef);
 276
 277 int XDmaPs_SetFaultHandler(XDmaPs *InstPtr,
 278                             XDmaPsFaultHandler FaultHandler,
 279                             void *CallbackRef);
 280
 281 void XDmaPs_Print_DmaProg(XDmaPs_Cmd *Cmd);
 282
 283 /**
 284  * Driver done interrupt service routines for the channels.
 285  * We need this done ISR mainly because the driver needs to release the
 286  * DMA program buffer. This is the one that connects the GIC
 287  */
 288 void XDmaPs_DoneISR_0(XDmaPs *InstPtr);
 289 void XDmaPs_DoneISR_1(XDmaPs *InstPtr);
 290 void XDmaPs_DoneISR_2(XDmaPs *InstPtr);
 291 void XDmaPs_DoneISR_3(XDmaPs *InstPtr);
 292 void XDmaPs_DoneISR_4(XDmaPs *InstPtr);
 293 void XDmaPs_DoneISR_5(XDmaPs *InstPtr);
 294 void XDmaPs_DoneISR_6(XDmaPs *InstPtr);
 295 void XDmaPs_DoneISR_7(XDmaPs *InstPtr);
 296
 297 /**
 298  * Driver fault interrupt service routine
 299  */
 300 void XDmaPs_FaultISR(XDmaPs *InstPtr);
 301
 302
 303 /*
 304  * Static loopup function implemented in xdmaps_sinit.c
 305  */
 306 XDmaPs_Config *XDmaPs_LookupConfig(u16 DeviceId);
 307
 308
 309 /*
 310  * self-test functions in xdmaps_selftest.c
 311  */
 312 int XDmaPs_SelfTest(XDmaPs *InstPtr);
 313
 314
 315 #ifdef __cplusplus
 316 }
 317 #endif
 318
 319 #endif /* end of protection macro */
 320 /** @} */