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

   1 /******************************************************************************
   2 *
   3 * Copyright (C) 2009 - 2015 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_1
  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 * 2.01  kpc    08/23/14  Fixed the IAR compiler reported errors
  78 * </pre>
  79 *
  80 *****************************************************************************/
  81
  82 #ifndef XDMAPS_H                /* prevent circular inclusions */
  83 #define XDMAPS_H                /* by using protection macros */
  84
  85 #ifdef __cplusplus
  86 extern "C" {
  87 #endif
  88
  89 /***************************** Include Files ********************************/
  90
  91 #include "xparameters.h"
  92 #include "xil_types.h"
  93 #include "xil_assert.h"
  94 #include "xstatus.h"
  95
  96 #include "xdmaps_hw.h"
  97
  98 /************************** Constant Definitions ****************************/
  99
 100 /**************************** Type Definitions ******************************/
 101
 102 /**
 103  * This typedef contains configuration information for the device.
 104  */
 105 typedef struct {
 106         u16 DeviceId;    /**< Unique ID  of device */
 107         u32 BaseAddress; /**< Base address of device (IPIF) */
 108 } XDmaPs_Config;
 109
 110
 111 /** DMA channle control structure. It's for AXI bus transaction.
 112  * This struct will be translated into a 32-bit channel control register value.
 113  */
 114 typedef struct {
 115         unsigned int EndianSwapSize;    /**< Endian swap size. */
 116         unsigned int DstCacheCtrl;      /**< Destination cache control */
 117         unsigned int DstProtCtrl;       /**< Destination protection control */
 118         unsigned int DstBurstLen;       /**< Destination burst length */
 119         unsigned int DstBurstSize;      /**< Destination burst size */
 120         unsigned int DstInc;            /**< Destination incrementing or fixed
 121                                          *   address */
 122         unsigned int SrcCacheCtrl;      /**< Source cache control */
 123         unsigned int SrcProtCtrl;       /**< Source protection control */
 124         unsigned int SrcBurstLen;       /**< Source burst length */
 125         unsigned int SrcBurstSize;      /**< Source burst size */
 126         unsigned int SrcInc;            /**< Source incrementing or fixed
 127                                          *   address */
 128 } XDmaPs_ChanCtrl;
 129
 130 /** DMA block descriptor stucture.
 131  */
 132 typedef struct {
 133         u32 SrcAddr;            /**< Source starting address */
 134         u32 DstAddr;            /**< Destination starting address */
 135         unsigned int Length;    /**< Number of bytes for the block */
 136 } XDmaPs_BD;
 137
 138 /**
 139  * A DMA command consisits of a channel control struct, a block descriptor,
 140  * a user defined program, a pointer pointing to generated DMA program, and
 141  * execution result.
 142  *
 143  */
 144 typedef struct {
 145         XDmaPs_ChanCtrl ChanCtrl;       /**< Channel Control Struct */
 146         XDmaPs_BD BD;                   /**< Together with SgLength field,
 147                                           *  it's a scatter-gather list.
 148                                           */
 149         void *UserDmaProg;              /**< If user wants the driver to
 150                                           *  execute their own DMA program,
 151                                           *  this field points to the DMA
 152                                           *  program.
 153                                           */
 154         int UserDmaProgLength;          /**< The length of user defined
 155                                           *  DMA program.
 156                                           */
 157
 158         void *GeneratedDmaProg;         /**< The DMA program genreated
 159                                          * by the driver. This field will be
 160                                          * set if a user invokes the DMA
 161                                          * program generation function. Or
 162                                          * the DMA command is finished and
 163                                          * a user informs the driver not to
 164                                          * release the program buffer.
 165                                          * This field has two purposes, one
 166                                          * is to ask the driver to generate
 167                                          * a DMA program while the DMAC is
 168                                          * performaning DMA transactions. The
 169                                          * other purpose is to debug the
 170                                          * driver.
 171                                          */
 172         int GeneratedDmaProgLength;      /**< The length of the DMA program
 173                                           * generated by the driver
 174                                           */
 175         int DmaStatus;                  /**< 0 on success, otherwise error code
 176                                          */
 177         u32 ChanFaultType;      /**< Channel fault type in case of fault
 178                                  */
 179         u32 ChanFaultPCAddr;    /**< Channel fault PC address
 180                                  */
 181 } XDmaPs_Cmd;
 182
 183 /**
 184  * It's the done handler a user can set for a channel
 185  */
 186 typedef void (*XDmaPsDoneHandler) (unsigned int Channel,
 187                                     XDmaPs_Cmd *DmaCmd,
 188                                     void *CallbackRef);
 189
 190 /**
 191  * It's the fault handler a user can set for a channel
 192  */
 193 typedef void (*XDmaPsFaultHandler) (unsigned int Channel,
 194                                      XDmaPs_Cmd *DmaCmd,
 195                                      void *CallbackRef);
 196
 197 #define XDMAPS_MAX_CHAN_BUFS    2
 198 #define XDMAPS_CHAN_BUF_LEN     128
 199
 200 /**
 201  * The XDmaPs_ProgBuf is the struct for a DMA program buffer.
 202  */
 203 typedef struct {
 204         char Buf[XDMAPS_CHAN_BUF_LEN];  /**< The actual buffer the holds the
 205                                           *  content */
 206         unsigned Len;                   /**< The actual length of the DMA
 207                                           *  program in bytes. */
 208         int Allocated;                  /**< A tag indicating whether the
 209                                           *  buffer is allocated or not */
 210 } XDmaPs_ProgBuf;
 211
 212 /**
 213  * The XDmaPs_ChannelData is a struct to book keep individual channel of
 214  * the DMAC.
 215  */
 216 typedef struct {
 217         unsigned DevId;                 /**< Device id indicating which DMAC */
 218         unsigned ChanId;                /**< Channel number of the DMAC */
 219         XDmaPs_ProgBuf ProgBufPool[XDMAPS_MAX_CHAN_BUFS]; /**< A pool of
 220                                                               program buffers*/
 221         XDmaPsDoneHandler DoneHandler;  /**< Done interrupt handler */
 222         void *DoneRef;                  /**< Done interrupt callback data */
 223         XDmaPs_Cmd *DmaCmdToHw;         /**< DMA command being executed */
 224         XDmaPs_Cmd *DmaCmdFromHw;       /**< DMA  command that is finished.
 225                                           *  This field is for debugging purpose
 226                                           */
 227         int HoldDmaProg;                /**< A tag indicating whether to hold the
 228                                           *  DMA program after the DMA is done.
 229                                           */
 230
 231 } XDmaPs_ChannelData;
 232
 233 /**
 234  * The XDmaPs driver instance data structure. A pointer to an instance data
 235  * structure is passed around by functions to refer to a specific driver
 236  * instance.
 237  */
 238 typedef struct {
 239         XDmaPs_Config Config;   /**< Configuration data structure */
 240         int IsReady;            /**< Device is Ready */
 241         int CacheLength;        /**< icache length */
 242         XDmaPsFaultHandler FaultHandler; /**< fault interrupt handler */
 243         void *FaultRef; /**< fault call back data */
 244         XDmaPs_ChannelData Chans[XDMAPS_CHANNELS_PER_DEV];
 245         /**<
 246          * channel data
 247          */
 248 } XDmaPs;
 249
 250 /*
 251  * Functions implemented in xdmaps.c
 252  */
 253 int XDmaPs_CfgInitialize(XDmaPs *InstPtr,
 254                           XDmaPs_Config *Config,
 255                           u32 EffectiveAddr);
 256
 257 int XDmaPs_Start(XDmaPs *InstPtr, unsigned int Channel,
 258                   XDmaPs_Cmd *Cmd,
 259                   int HoldDmaProg);
 260
 261 int XDmaPs_IsActive(XDmaPs *InstPtr, unsigned int Channel);
 262 int XDmaPs_GenDmaProg(XDmaPs *InstPtr, unsigned int Channel,
 263                        XDmaPs_Cmd *Cmd);
 264 int XDmaPs_FreeDmaProg(XDmaPs *InstPtr, unsigned int Channel,
 265                         XDmaPs_Cmd *Cmd);
 266 void XDmaPs_Print_DmaProg(XDmaPs_Cmd *Cmd);
 267
 268
 269 int XDmaPs_ResetManager(XDmaPs *InstPtr);
 270 int XDmaPs_ResetChannel(XDmaPs *InstPtr, unsigned int Channel);
 271
 272
 273 int XDmaPs_SetDoneHandler(XDmaPs *InstPtr,
 274                            unsigned Channel,
 275                            XDmaPsDoneHandler DoneHandler,
 276                            void *CallbackRef);
 277
 278 int XDmaPs_SetFaultHandler(XDmaPs *InstPtr,
 279                             XDmaPsFaultHandler FaultHandler,
 280                             void *CallbackRef);
 281
 282 void XDmaPs_Print_DmaProg(XDmaPs_Cmd *Cmd);
 283
 284 /**
 285  * Driver done interrupt service routines for the channels.
 286  * We need this done ISR mainly because the driver needs to release the
 287  * DMA program buffer. This is the one that connects the GIC
 288  */
 289 void XDmaPs_DoneISR_0(XDmaPs *InstPtr);
 290 void XDmaPs_DoneISR_1(XDmaPs *InstPtr);
 291 void XDmaPs_DoneISR_2(XDmaPs *InstPtr);
 292 void XDmaPs_DoneISR_3(XDmaPs *InstPtr);
 293 void XDmaPs_DoneISR_4(XDmaPs *InstPtr);
 294 void XDmaPs_DoneISR_5(XDmaPs *InstPtr);
 295 void XDmaPs_DoneISR_6(XDmaPs *InstPtr);
 296 void XDmaPs_DoneISR_7(XDmaPs *InstPtr);
 297
 298 /**
 299  * Driver fault interrupt service routine
 300  */
 301 void XDmaPs_FaultISR(XDmaPs *InstPtr);
 302
 303
 304 /*
 305  * Static loopup function implemented in xdmaps_sinit.c
 306  */
 307 XDmaPs_Config *XDmaPs_LookupConfig(u16 DeviceId);
 308
 309
 310 /*
 311  * self-test functions in xdmaps_selftest.c
 312  */
 313 int XDmaPs_SelfTest(XDmaPs *InstPtr);
 314
 315
 316 #ifdef __cplusplus
 317 }
 318 #endif
 319
 320 #endif /* end of protection macro */
 321 /** @} */