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