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 * (c) Copyright 2009-2013 Xilinx, Inc. All rights reserved.
   4 *
   5 * This file contains confidential and proprietary information of Xilinx, Inc.
   6 * and is protected under U.S. and international copyright and other
   7 * intellectual property laws.
   8 *
   9 * DISCLAIMER
  10 * This disclaimer is not a license and does not grant any rights to the
  11 * materials distributed herewith. Except as otherwise provided in a valid
  12 * license issued to you by Xilinx, and to the maximum extent permitted by
  13 * applicable law: (1) THESE MATERIALS ARE MADE AVAILABLE "AS IS" AND WITH ALL
  14 * FAULTS, AND XILINX HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS,
  15 * IMPLIED, OR STATUTORY, INCLUDING BUT NOT LIMITED TO WARRANTIES OF
  16 * MERCHANTABILITY, NON-INFRINGEMENT, OR FITNESS FOR ANY PARTICULAR PURPOSE;
  17 * and (2) Xilinx shall not be liable (whether in contract or tort, including
  18 * negligence, or under any other theory of liability) for any loss or damage
  19 * of any kind or nature related to, arising under or in connection with these
  20 * materials, including for any direct, or any indirect, special, incidental,
  21 * or consequential loss or damage (including loss of data, profits, goodwill,
  22 * or any type of loss or damage suffered as a result of any action brought by
  23 * a third party) even if such damage or loss was reasonably foreseeable or
  24 * Xilinx had been advised of the possibility of the same.
  25 *
  26 * CRITICAL APPLICATIONS
  27 * Xilinx products are not designed or intended to be fail-safe, or for use in
  28 * any application requiring fail-safe performance, such as life-support or
  29 * safety devices or systems, Class III medical devices, nuclear facilities,
  30 * applications related to the deployment of airbags, or any other applications
  31 * that could lead to death, personal injury, or severe property or
  32 * environmental damage (individually and collectively, "Critical
  33 * Applications"). Customer assumes the sole risk and liability of any use of
  34 * Xilinx products in Critical Applications, subject only to applicable laws
  35 * and regulations governing limitations on product liability.
  36 *
  37 * THIS COPYRIGHT NOTICE AND DISCLAIMER MUST BE RETAINED AS PART OF THIS FILE
  38 * AT ALL TIMES.
  39 *
  40 *****************************************************************************/
  41 /****************************************************************************/
  42 /**
  43 *
  44 * @file xdmaps.h
  45 *
  46 *
  47 * <pre>
  48 * MODIFICATION HISTORY:
  49 *
  50 * Ver   Who     Date     Changes
  51 * ----- ------ -------- ----------------------------------------------
  52 * 1.00  hbm    08/19/10 First Release
  53 * 1.01a nm     12/20/12 Added definition XDMAPS_CHANNELS_PER_DEV which specifies
  54 *                       the maximum number of channels.
  55 *                       Replaced the usage of XPAR_XDMAPS_CHANNELS_PER_DEV
  56 *                       with XDMAPS_CHANNELS_PER_DEV defined in xdmaps_hw.h.
  57 *                       Added the tcl file to automatically generate the
  58 *                       xparameters.h
  59 * 1.02a sg     05/16/12 Made changes for doxygen and moved some function
  60 *                       header from the xdmaps.h file to xdmaps.c file
  61 *                       Other cleanup for coding guidelines and CR 657109
  62 *                       and CR 657898
  63 *                       The xdmaps_example_no_intr.c example is removed
  64 *                       as it is using interrupts  and is similar to
  65 *                       the interrupt example - CR 652477
  66 * 1.03a sg     07/16/2012 changed inline to __inline for CR665681
  67 * 1.04a nm     10/22/2012 Fixed CR# 681671.
  68 * 1.05a nm     04/15/2013 Fixed CR# 704396. Removed warnings when compiled
  69 *                         with -Wall and -Wextra option in bsp.
  70 *              05/01/2013 Fixed CR# 700189. Changed XDmaPs_BuildDmaProg()
  71 *                         function description.
  72 *                         Fixed CR# 704396. Removed unused variables
  73 *                         UseM2MByte & MemBurstLen from XDmaPs_BuildDmaProg()
  74 *                         function.
  75 * 1.07a asa    11/02/13. Made changes to fix compilation issues for iarcc.
  76 *                          Removed the PDBG prints. By default they were always
  77 *                          defined out and never used. The PDBG is non-standard for
  78 *                          Xilinx drivers and no other driver does something similar.
  79 *                          Since there is no easy way to fix compilation issues with
  80 *                          the IARCC compiler around PDBG, it is better to remove it.
  81 *                          Users can always use xil_printfs if they want to debug.
  82 * 2.0   adk    10/12/13  Updated as per the New Tcl API's
  83 * </pre>
  84 *
  85 *****************************************************************************/
  86
  87 #ifndef XDMAPS_H                /* prevent circular inclusions */
  88 #define XDMAPS_H                /* by using protection macros */
  89
  90 #ifdef __cplusplus
  91 extern "C" {
  92 #endif
  93
  94 /***************************** Include Files ********************************/
  95
  96 #include "xparameters.h"
  97 #include "xil_types.h"
  98 #include "xil_assert.h"
  99 #include "xstatus.h"
 100
 101 #include "xdmaps_hw.h"
 102
 103 /************************** Constant Definitions ****************************/
 104
 105 /**************************** Type Definitions ******************************/
 106
 107 /**
 108  * This typedef contains configuration information for the device.
 109  */
 110 typedef struct {
 111         u16 DeviceId;    /**< Unique ID  of device */
 112         u32 BaseAddress; /**< Base address of device (IPIF) */
 113 } XDmaPs_Config;
 114
 115
 116 /** DMA channle control structure. It's for AXI bus transaction.
 117  * This struct will be translated into a 32-bit channel control register value.
 118  */
 119 typedef struct {
 120         unsigned int EndianSwapSize;    /**< Endian swap size. */
 121         unsigned int DstCacheCtrl;      /**< Destination cache control */
 122         unsigned int DstProtCtrl;       /**< Destination protection control */
 123         unsigned int DstBurstLen;       /**< Destination burst length */
 124         unsigned int DstBurstSize;      /**< Destination burst size */
 125         unsigned int DstInc;            /**< Destination incrementing or fixed
 126                                          *   address */
 127         unsigned int SrcCacheCtrl;      /**< Source cache control */
 128         unsigned int SrcProtCtrl;       /**< Source protection control */
 129         unsigned int SrcBurstLen;       /**< Source burst length */
 130         unsigned int SrcBurstSize;      /**< Source burst size */
 131         unsigned int SrcInc;            /**< Source incrementing or fixed
 132                                          *   address */
 133 } XDmaPs_ChanCtrl;
 134
 135 /** DMA block descriptor stucture.
 136  */
 137 typedef struct {
 138         u32 SrcAddr;            /**< Source starting address */
 139         u32 DstAddr;            /**< Destination starting address */
 140         unsigned int Length;    /**< Number of bytes for the block */
 141 } XDmaPs_BD;
 142
 143 /**
 144  * A DMA command consisits of a channel control struct, a block descriptor,
 145  * a user defined program, a pointer pointing to generated DMA program, and
 146  * execution result.
 147  *
 148  */
 149 typedef struct {
 150         XDmaPs_ChanCtrl ChanCtrl;       /**< Channel Control Struct */
 151         XDmaPs_BD BD;                   /**< Together with SgLength field,
 152                                           *  it's a scatter-gather list.
 153                                           */
 154         void *UserDmaProg;              /**< If user wants the driver to
 155                                           *  execute their own DMA program,
 156                                           *  this field points to the DMA
 157                                           *  program.
 158                                           */
 159         int UserDmaProgLength;          /**< The length of user defined
 160                                           *  DMA program.
 161                                           */
 162
 163         void *GeneratedDmaProg;         /**< The DMA program genreated
 164                                          * by the driver. This field will be
 165                                          * set if a user invokes the DMA
 166                                          * program generation function. Or
 167                                          * the DMA command is finished and
 168                                          * a user informs the driver not to
 169                                          * release the program buffer.
 170                                          * This field has two purposes, one
 171                                          * is to ask the driver to generate
 172                                          * a DMA program while the DMAC is
 173                                          * performaning DMA transactions. The
 174                                          * other purpose is to debug the
 175                                          * driver.
 176                                          */
 177         int GeneratedDmaProgLength;      /**< The length of the DMA program
 178                                           * generated by the driver
 179                                           */
 180         int DmaStatus;                  /**< 0 on success, otherwise error code
 181                                          */
 182         u32 ChanFaultType;      /**< Channel fault type in case of fault
 183                                  */
 184         u32 ChanFaultPCAddr;    /**< Channel fault PC address
 185                                  */
 186 } XDmaPs_Cmd;
 187
 188 /**
 189  * It's the done handler a user can set for a channel
 190  */
 191 typedef void (*XDmaPsDoneHandler) (unsigned int Channel,
 192                                     XDmaPs_Cmd *DmaCmd,
 193                                     void *CallbackRef);
 194
 195 /**
 196  * It's the fault handler a user can set for a channel
 197  */
 198 typedef void (*XDmaPsFaultHandler) (unsigned int Channel,
 199                                      XDmaPs_Cmd *DmaCmd,
 200                                      void *CallbackRef);
 201
 202 #define XDMAPS_MAX_CHAN_BUFS    2
 203 #define XDMAPS_CHAN_BUF_LEN     128
 204
 205 /**
 206  * The XDmaPs_ProgBuf is the struct for a DMA program buffer.
 207  */
 208 typedef struct {
 209         char Buf[XDMAPS_CHAN_BUF_LEN];  /**< The actual buffer the holds the
 210                                           *  content */
 211         unsigned Len;                   /**< The actual length of the DMA
 212                                           *  program in bytes. */
 213         int Allocated;                  /**< A tag indicating whether the
 214                                           *  buffer is allocated or not */
 215 } XDmaPs_ProgBuf;
 216
 217 /**
 218  * The XDmaPs_ChannelData is a struct to book keep individual channel of
 219  * the DMAC.
 220  */
 221 typedef struct {
 222         unsigned DevId;                 /**< Device id indicating which DMAC */
 223         unsigned ChanId;                /**< Channel number of the DMAC */
 224         XDmaPs_ProgBuf ProgBufPool[XDMAPS_MAX_CHAN_BUFS]; /**< A pool of
 225                                                               program buffers*/
 226         XDmaPsDoneHandler DoneHandler;  /**< Done interrupt handler */
 227         void *DoneRef;                  /**< Done interrupt callback data */
 228         XDmaPs_Cmd *DmaCmdToHw;         /**< DMA command being executed */
 229         XDmaPs_Cmd *DmaCmdFromHw;       /**< DMA  command that is finished.
 230                                           *  This field is for debugging purpose
 231                                           */
 232         int HoldDmaProg;                /**< A tag indicating whether to hold the
 233                                           *  DMA program after the DMA is done.
 234                                           */
 235
 236 } XDmaPs_ChannelData;
 237
 238 /**
 239  * The XDmaPs driver instance data structure. A pointer to an instance data
 240  * structure is passed around by functions to refer to a specific driver
 241  * instance.
 242  */
 243 typedef struct {
 244         XDmaPs_Config Config;   /**< Configuration data structure */
 245         int IsReady;            /**< Device is Ready */
 246         int CacheLength;        /**< icache length */
 247         XDmaPsFaultHandler FaultHandler; /**< fault interrupt handler */
 248         void *FaultRef; /**< fault call back data */
 249         XDmaPs_ChannelData Chans[XDMAPS_CHANNELS_PER_DEV];
 250         /**<
 251          * channel data
 252          */
 253 } XDmaPs;
 254
 255 /*
 256  * Functions implemented in xdmaps.c
 257  */
 258 int XDmaPs_CfgInitialize(XDmaPs *InstPtr,
 259                           XDmaPs_Config *Config,
 260                           u32 EffectiveAddr);
 261
 262 int XDmaPs_Start(XDmaPs *InstPtr, unsigned int Channel,
 263                   XDmaPs_Cmd *Cmd,
 264                   int HoldDmaProg);
 265
 266 int XDmaPs_IsActive(XDmaPs *InstPtr, unsigned int Channel);
 267 int XDmaPs_GenDmaProg(XDmaPs *InstPtr, unsigned int Channel,
 268                        XDmaPs_Cmd *Cmd);
 269 int XDmaPs_FreeDmaProg(XDmaPs *InstPtr, unsigned int Channel,
 270                         XDmaPs_Cmd *Cmd);
 271 void XDmaPs_Print_DmaProg(XDmaPs_Cmd *Cmd);
 272
 273
 274 int XDmaPs_ResetManager(XDmaPs *InstPtr);
 275 int XDmaPs_ResetChannel(XDmaPs *InstPtr, unsigned int Channel);
 276
 277
 278 int XDmaPs_SetDoneHandler(XDmaPs *InstPtr,
 279                            unsigned Channel,
 280                            XDmaPsDoneHandler DoneHandler,
 281                            void *CallbackRef);
 282
 283 int XDmaPs_SetFaultHandler(XDmaPs *InstPtr,
 284                             XDmaPsFaultHandler FaultHandler,
 285                             void *CallbackRef);
 286
 287 void XDmaPs_Print_DmaProg(XDmaPs_Cmd *Cmd);
 288
 289 /**
 290  * Driver done interrupt service routines for the channels.
 291  * We need this done ISR mainly because the driver needs to release the
 292  * DMA program buffer. This is the one that connects the GIC
 293  */
 294 void XDmaPs_DoneISR_0(XDmaPs *InstPtr);
 295 void XDmaPs_DoneISR_1(XDmaPs *InstPtr);
 296 void XDmaPs_DoneISR_2(XDmaPs *InstPtr);
 297 void XDmaPs_DoneISR_3(XDmaPs *InstPtr);
 298 void XDmaPs_DoneISR_4(XDmaPs *InstPtr);
 299 void XDmaPs_DoneISR_5(XDmaPs *InstPtr);
 300 void XDmaPs_DoneISR_6(XDmaPs *InstPtr);
 301 void XDmaPs_DoneISR_7(XDmaPs *InstPtr);
 302
 303 /**
 304  * Driver fault interrupt service routine
 305  */
 306 void XDmaPs_FaultISR(XDmaPs *InstPtr);
 307
 308
 309 /*
 310  * Static loopup function implemented in xdmaps_sinit.c
 311  */
 312 XDmaPs_Config *XDmaPs_LookupConfig(u16 DeviceId);
 313
 314
 315 /*
 316  * self-test functions in xdmaps_selftest.c
 317  */
 318 int XDmaPs_SelfTest(XDmaPs *InstPtr);
 319
 320
 321 #ifdef __cplusplus
 322 }
 323 #endif
 324
 325 #endif /* end of protection macro */