git.sur5r.net Git - freertos/blob

   1 /******************************************************************************
   2 *
   3 * Copyright (C) 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 xqspipsu.h
  36 *
  37 * This is the header file for the implementation of QSPIPSU driver.
  38 * Generic QSPI interface allows for communication to any QSPI slave device.
  39 * GQSPI contains a GENFIFO into which the bus transfers required are to be
  40 * pushed with appropriate configuration. The controller provides TX and RX
  41 * FIFO's and a DMA to be used for RX transfers. The controller executes each
  42 * GENFIFO entry noting the configuration and places data on the bus as required
  43 *
  44 * The different options in GENFIFO are as follows:
  45 * IMM_DATA : Can be one byte of data to be transmitted, number of clocks or
  46 *            number of bytes in transfer.
  47 * DATA_XFER : Indicates that data/clocks need to be transmitted or received.
  48 * EXPONENT : e when 2^e bytes are involved in transfer.
  49 * SPI_MODE : SPI/Dual SPI/Quad SPI
  50 * CS : Lower or Upper CS or Both
  51 * Bus : Lower or Upper Bus or Both
  52 * TX : When selected, controller transmits data in IMM or fetches number of
  53 *      bytes mentioned form TX FIFO. If not selected, dummies are pumped.
  54 * RX : When selected, controller receives and fills the RX FIFO/allows RX DMA
  55 *      of requested number of bytes. If not selected, RX data is discarded.
  56 * Stripe : Byte stripe over lower and upper bus or not.
  57 * Poll : Polls response to match for to a set value (used along with POLL_CFG
  58 *        registers) and then proceeds to next GENFIFO entry.
  59 *        This feature is not currently used in the driver.
  60 *
  61 * GENFIFO has manual and auto start options.
  62 * All DMA requests need a 4-byte aligned destination address buffer and
  63 * size of transfer should also be a multiple of 4.
  64 * This driver supports DMA RX and IO RX.
  65 *
  66 * Initialization:
  67 * This driver uses the GQSPI controller with RX DMA. It supports both
  68 * interrupt and polled transfers. Manual start of GENFIFO is used.
  69 * XQspiPsu_CfgInitialize() initializes the instance variables.
  70 * Additional setting can be done using SetOptions/ClearOptions functions
  71 * and SelectSlave function.
  72 *
  73 * Transfer:
  74 * Polled or Interrupt transfers can be done. The transfer function needs the
  75 * message(s) to be transmitted in the form of an array of type XQspiPsu_Msg.
  76 * This is supposed to contain the byte count and any TX/RX buffers as required.
  77 * Flags can be used indicate further information such as whether the message
  78 * should be striped. The transfer functions form and write GENFIFO entries,
  79 * check the status of the transfer and report back to the application
  80 * when done.
  81 *
  82 * <pre>
  83 * MODIFICATION HISTORY:
  84 *
  85 * Ver   Who Date     Changes
  86 * ----- --- -------- -----------------------------------------------.
  87 * 1.0   hk  08/21/14 First release
  88 *       sk  03/13/15 Added IO mode support.
  89 *       hk  03/18/15 Switch to I/O mode before clearing RX FIFO.
  90 *                    Clear and disbale DMA interrupts/status in abort.
  91 *                    Use DMA DONE bit instead of BUSY as recommended.
  92 *
  93 * </pre>
  94 *
  95 ******************************************************************************/
  96 #ifndef _XQSPIPSU_H_            /* prevent circular inclusions */
  97 #define _XQSPIPSU_H_            /* by using protection macros */
  98
  99 #ifdef __cplusplus
 100 extern "C" {
 101 #endif
 102
 103 /***************************** Include Files *********************************/
 104
 105 #include "xstatus.h"
 106 #include "xqspipsu_hw.h"
 107
 108 /**************************** Type Definitions *******************************/
 109 /**
 110  * The handler data type allows the user to define a callback function to
 111  * handle the asynchronous processing for the QSPIPSU device.  The application
 112  * using this driver is expected to define a handler of this type to support
 113  * interrupt driven mode.  The handler executes in an interrupt context, so
 114  * only minimal processing should be performed.
 115  *
 116  * @param       CallBackRef is the callback reference passed in by the upper
 117  *              layer when setting the callback functions, and passed back to
 118  *              the upper layer when the callback is invoked. Its type is
 119  *              not important to the driver, so it is a void pointer.
 120  * @param       StatusEvent holds one or more status events that have occurred.
 121  *              See the XQspiPsu_SetStatusHandler() for details on the status
 122  *              events that can be passed in the callback.
 123  * @param       ByteCount indicates how many bytes of data were successfully
 124  *              transferred.  This may be less than the number of bytes
 125  *              requested if the status event indicates an error.
 126  */
 127 typedef void (*XQspiPsu_StatusHandler) (void *CallBackRef, u32 StatusEvent,
 128                                         unsigned ByteCount);
 129
 130 /**
 131  * This typedef contains configuration information for a flash message.
 132  */
 133 typedef struct {
 134         u8 *TxBfrPtr;
 135         u8 *RxBfrPtr;
 136         u32 ByteCount;
 137         u32 BusWidth;
 138         u32 Flags;
 139 } XQspiPsu_Msg;
 140
 141 /**
 142  * This typedef contains configuration information for the device.
 143  */
 144 typedef struct {
 145         u16 DeviceId;           /**< Unique ID  of device */
 146         u32 BaseAddress;        /**< Base address of the device */
 147         u32 InputClockHz;       /**< Input clock frequency */
 148         u8  ConnectionMode; /**< Single, Stacked and Parallel mode */
 149         u8  BusWidth;   /**< Bus width available on board */
 150 } XQspiPsu_Config;
 151
 152 /**
 153  * The XQspiPsu driver instance data. The user is required to allocate a
 154  * variable of this type for every QSPIPSU device in the system. A pointer
 155  * to a variable of this type is then passed to the driver API functions.
 156  */
 157 typedef struct {
 158         XQspiPsu_Config Config;  /**< Configuration structure */
 159         u32 IsReady;             /**< Device is initialized and ready */
 160
 161         u8 *SendBufferPtr;       /**< Buffer to send (state) */
 162         u8 *RecvBufferPtr;       /**< Buffer to receive (state) */
 163         u8 *GenFifoBufferPtr;    /**< Gen FIFO entries */
 164         int TxBytes;     /**< Number of bytes to transfer (state) */
 165         int RxBytes;     /**< Number of bytes left to transfer(state) */
 166         int GenFifoEntries;      /**< Number of Gen FIFO entries remaining */
 167         u32 IsBusy;              /**< A transfer is in progress (state) */
 168         u32 ReadMode;            /**< DMA or IO mode */
 169         u32 GenFifoCS;
 170         u32 GenFifoBus;
 171         int NumMsg;
 172         int MsgCnt;
 173         int IsUnaligned;
 174         XQspiPsu_Msg *Msg;
 175         XQspiPsu_StatusHandler StatusHandler;
 176         void *StatusRef;         /**< Callback reference for status handler */
 177 } XQspiPsu;
 178
 179 /***************** Macros (Inline Functions) Definitions *********************/
 180
 181 #define XQSPIPSU_READMODE_DMA   0x0
 182 #define XQSPIPSU_READMODE_IO    0x1
 183
 184 #define XQSPIPSU_SELECT_FLASH_CS_LOWER  0x1
 185 #define XQSPIPSU_SELECT_FLASH_CS_UPPER  0x2
 186 #define XQSPIPSU_SELECT_FLASH_CS_BOTH   0x3
 187
 188 #define XQSPIPSU_SELECT_FLASH_BUS_LOWER 0x1
 189 #define XQSPIPSU_SELECT_FLASH_BUS_UPPER 0x2
 190 #define XQSPIPSU_SELECT_FLASH_BUS_BOTH  0x3
 191
 192 #define XQSPIPSU_SELECT_MODE_SPI        0x1
 193 #define XQSPIPSU_SELECT_MODE_DUALSPI    0x2
 194 #define XQSPIPSU_SELECT_MODE_QUADSPI    0x4
 195
 196 #define XQSPIPSU_GENFIFO_CS_SETUP       0x04
 197 #define XQSPIPSU_GENFIFO_CS_HOLD        0x03
 198
 199 #define XQSPIPSU_CLK_ACTIVE_LOW_OPTION  0x2
 200 #define XQSPIPSU_CLK_PHASE_1_OPTION     0x4
 201 #define XQSPIPSU_MANUAL_START_OPTION    0x8
 202
 203 #define XQSPIPSU_GENFIFO_EXP_START      0x100
 204
 205 #define XQSPIPSU_DMA_BYTES_MAX          0x10000000
 206
 207 #define XQSPIPSU_CLK_PRESCALE_2         0x00
 208 #define XQSPIPSU_CLK_PRESCALE_4         0x01
 209 #define XQSPIPSU_CLK_PRESCALE_8         0x02
 210 #define XQSPIPSU_CLK_PRESCALE_16                0x03
 211 #define XQSPIPSU_CLK_PRESCALE_32                0x04
 212 #define XQSPIPSU_CLK_PRESCALE_64                0x05
 213 #define XQSPIPSU_CLK_PRESCALE_128       0x06
 214 #define XQSPIPSU_CLK_PRESCALE_256       0x07
 215 #define XQSPIPSU_CR_PRESC_MAXIMUM       7
 216
 217 #define XQSPIPSU_CONNECTION_MODE_SINGLE         0
 218 #define XQSPIPSU_CONNECTION_MODE_STACKED        1
 219 #define XQSPIPSU_CONNECTION_MODE_PARALLEL       2
 220
 221 /* Add more flags as required */
 222 #define XQSPIPSU_MSG_FLAG_STRIPE        0x1
 223
 224 #define XQspiPsu_Select(InstancePtr)    XQspiPsu_Out32((InstancePtr->Config.BaseAddress) + XQSPIPSU_SEL_OFFSET, XQSPIPSU_SEL_MASK)
 225
 226 #define XQspiPsu_Enable(InstancePtr)    XQspiPsu_Out32((InstancePtr->Config.BaseAddress) + XQSPIPSU_EN_OFFSET, XQSPIPSU_EN_MASK)
 227
 228 #define XQspiPsu_Disable(InstancePtr)   XQspiPsu_Out32((InstancePtr->Config.BaseAddress) + XQSPIPSU_EN_OFFSET, 0x0)
 229
 230 #define XQspiPsu_IsManualStart(InstancePtr) ((XQspiPsu_GetOptions(InstancePtr) & XQSPIPSU_MANUAL_START_OPTION) ? TRUE : FALSE)
 231
 232 /************************** Function Prototypes ******************************/
 233
 234 /* Initialization and reset */
 235 XQspiPsu_Config *XQspiPsu_LookupConfig(u16 DeviceId);
 236 int XQspiPsu_CfgInitialize(XQspiPsu *InstancePtr, XQspiPsu_Config *ConfigPtr,
 237                                 u32 EffectiveAddr);
 238 void XQspiPsu_Reset(XQspiPsu *InstancePtr);
 239 void XQspiPsu_Abort(XQspiPsu *InstancePtr);
 240
 241 /* Transfer functions and handlers */
 242 int XQspiPsu_PolledTransfer(XQspiPsu *InstancePtr, XQspiPsu_Msg *Msg,
 243                                 unsigned NumMsg);
 244 int XQspiPsu_InterruptTransfer(XQspiPsu *InstancePtr, XQspiPsu_Msg *Msg,
 245                                 unsigned NumMsg);
 246 int XQspiPsu_InterruptHandler(XQspiPsu *InstancePtr);
 247 void XQspiPsu_SetStatusHandler(XQspiPsu *InstancePtr, void *CallBackRef,
 248                                 XQspiPsu_StatusHandler FuncPtr);
 249
 250 /* Configuration functions */
 251 int XQspiPsu_SetClkPrescaler(XQspiPsu *InstancePtr, u8 Prescaler);
 252 void XQspiPsu_SelectFlash(XQspiPsu *InstancePtr, u8 FlashCS, u8 FlashBus);
 253 int XQspiPsu_SetOptions(XQspiPsu *InstancePtr, u32 Options);
 254 int XQspiPsu_ClearOptions(XQspiPsu *InstancePtr, u32 Options);
 255 u32 XQspiPsu_GetOptions(XQspiPsu *InstancePtr);
 256 int XQspiPsu_SetReadMode(XQspiPsu *InstancePtr, u32 Mode);
 257
 258 #ifdef __cplusplus
 259 }
 260 #endif
 261
 262
 263 #endif /* _XQSPIPSU_H_ */