git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_R5_UltraScale_MPSoC/RTOSDemo_R5_bsp/psu_cortexr5_0/libsrc/qspipsu_v1_7/src/xqspipsu.h

   1 /******************************************************************************
   2 *
   3 * Copyright (C) 2018 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 * @addtogroup qspipsu_v1_7
  37 * @{
  38 * @details
  39 *
  40 * This is the header file for the implementation of QSPIPSU driver.
  41 * Generic QSPI interface allows for communication to any QSPI slave device.
  42 * GQSPI contains a GENFIFO into which the bus transfers required are to be
  43 * pushed with appropriate configuration. The controller provides TX and RX
  44 * FIFO's and a DMA to be used for RX transfers. The controller executes each
  45 * GENFIFO entry noting the configuration and places data on the bus as required
  46 *
  47 * The different options in GENFIFO are as follows:
  48 * IMM_DATA : Can be one byte of data to be transmitted, number of clocks or
  49 *            number of bytes in transfer.
  50 * DATA_XFER : Indicates that data/clocks need to be transmitted or received.
  51 * EXPONENT : e when 2^e bytes are involved in transfer.
  52 * SPI_MODE : SPI/Dual SPI/Quad SPI
  53 * CS : Lower or Upper CS or Both
  54 * Bus : Lower or Upper Bus or Both
  55 * TX : When selected, controller transmits data in IMM or fetches number of
  56 *      bytes mentioned form TX FIFO. If not selected, dummies are pumped.
  57 * RX : When selected, controller receives and fills the RX FIFO/allows RX DMA
  58 *      of requested number of bytes. If not selected, RX data is discarded.
  59 * Stripe : Byte stripe over lower and upper bus or not.
  60 * Poll : Polls response to match for to a set value (used along with POLL_CFG
  61 *        registers) and then proceeds to next GENFIFO entry.
  62 *        This feature is not currently used in the driver.
  63 *
  64 * GENFIFO has manual and auto start options.
  65 * All DMA requests need a 4-byte aligned destination address buffer and
  66 * size of transfer should also be a multiple of 4.
  67 * This driver supports DMA RX and IO RX.
  68 *
  69 * Initialization:
  70 * This driver uses the GQSPI controller with RX DMA. It supports both
  71 * interrupt and polled transfers. Manual start of GENFIFO is used.
  72 * XQspiPsu_CfgInitialize() initializes the instance variables.
  73 * Additional setting can be done using SetOptions/ClearOptions functions
  74 * and SelectSlave function.
  75 *
  76 * Transfer:
  77 * Polled or Interrupt transfers can be done. The transfer function needs the
  78 * message(s) to be transmitted in the form of an array of type XQspiPsu_Msg.
  79 * This is supposed to contain the byte count and any TX/RX buffers as required.
  80 * Flags can be used indicate further information such as whether the message
  81 * should be striped. The transfer functions form and write GENFIFO entries,
  82 * check the status of the transfer and report back to the application
  83 * when done.
  84 *
  85 * <pre>
  86 * MODIFICATION HISTORY:
  87 *
  88 * Ver   Who Date     Changes
  89 * ----- --- -------- -----------------------------------------------.
  90 * 1.0   hk  08/21/14 First release
  91 *       sk  03/13/15 Added IO mode support.
  92 *       hk  03/18/15 Switch to I/O mode before clearing RX FIFO.
  93 *                    Clear and disbale DMA interrupts/status in abort.
  94 *                    Use DMA DONE bit instead of BUSY as recommended.
  95 *       sk  04/24/15 Modified the code according to MISRAC-2012.
  96 *       sk  06/17/15 Removed NULL checks for Rx/Tx buffers. As
  97 *                    writing/reading from 0x0 location is permitted.
  98 * 1.1   sk  04/12/16 Added debug message prints.
  99 * 1.2   nsk 07/01/16 Added LQSPI support
 100 *                    Modified XQspiPsu_Select() macro in xqspipsu.h
 101 *                    Added XQspiPsu_GetLqspiConfigReg() in xqspipsu.h
 102 *                    Added required macros in xqspipsu_hw.h
 103 *                    Modified XQspiPsu_SetOptions() to support
 104 *                    LQSPI options and updated OptionsTable in
 105 *                    xqspipsu_options.c
 106 *       rk  07/15/16 Added support for TapDelays at different frequencies.
 107 *       nsk 08/05/16 Added example support PollData and PollTimeout
 108 *                    Added  XQSPIPSU_MSG_FLAG_POLL macro in xqspipsu.h
 109 *                    Added XQspiPsu_Create_PollConfigData and
 110 *                    XQspiPsu_PollData() functions in xqspipsu.c
 111 * 1.3   nsk 09/16/16 Update PollData and Polltimeout support for dual parallel
 112 *                    configuration. Updated XQspiPsu_PollData() and
 113 *                    XQspiPsu_Create_PollConfigData() functions in xqspipsu.c
 114 *                    and also modified the polldata example
 115 *       ms  03/17/17 Added readme.txt file in examples folder for doxygen
 116 *                    generation.
 117 *       ms  04/05/17 Modified Comment lines in functions of qspipsu
 118 *                    examples to recognize it as documentation block
 119 *                    and modified filename tag to include them in
 120 *                    doxygen examples.
 121 * 1.4   tjs 05/26/17 Added support for accessing upper DDR (0x800000000)
 122 *                    while booting images from QSPI
 123 * 1.5   tjs     08/08/17 Added index.html file for importing examples from system.mss
 124 * 1.5   nsk 08/14/17 Added CCI support
 125 * 1.5   tjs 09/14/17 Modified the checks for 4 byte addressing and commands.
 126 * 1.6   tjs 10/16/17 Flow for accessing flash is made similar to u-boot and linux
 127 *                                        For CR-984966
 128 * 1.6   tjs 11/02/17 Resolved the compilation errors for ICCARM. CR-988625
 129 * 1.7   tjs 11/16/17 Removed the unsupported 4 Byte write and sector erase
 130 *                    commands.
 131 * 1.7   tjs     12/01/17 Added support for MT25QL02G Flash from Micron. CR-990642
 132 * 1.7   tjs 12/19/17 Added support for S25FL064L from Spansion. CR-990724
 133 * 1.7   tjs 01/11/18 Added support for MX66L1G45G flash from Macronix CR-992367
 134 * 1.7   tjs     01/16/18 Removed the check for DMA MSB to be written. (CR#992560)
 135 * 1.7   tjs     01/17/18 Added support to toggle the WP pin of flash. (PR#2448)
 136 *                    Added XQspiPsu_SetWP() in xqspipsu_options.c
 137 *                    Added XQspiPsu_WriteProtectToggle() in xqspipsu.c and
 138 *                    also added write protect example.
 139 * 1.7   tjs     03/14/18 Added support in EL1 NS mode (CR#974882)
 140 * 1.7   tjs 26/03/18 In dual parallel mode enable both CS when issuing Write
 141 *                                enable command. CR-998478
 142 * </pre>
 143 *
 144 ******************************************************************************/
 145 #ifndef XQSPIPSU_H_             /* prevent circular inclusions */
 146 #define XQSPIPSU_H_             /* by using protection macros */
 147
 148 #ifdef __cplusplus
 149 extern "C" {
 150 #endif
 151
 152 /***************************** Include Files *********************************/
 153
 154 #include "xstatus.h"
 155 #include "xqspipsu_hw.h"
 156 #include "xil_cache.h"
 157
 158 /**************************** Type Definitions *******************************/
 159 /**
 160  * The handler data type allows the user to define a callback function to
 161  * handle the asynchronous processing for the QSPIPSU device.  The application
 162  * using this driver is expected to define a handler of this type to support
 163  * interrupt driven mode.  The handler executes in an interrupt context, so
 164  * only minimal processing should be performed.
 165  *
 166  * @param       CallBackRef is the callback reference passed in by the upper
 167  *              layer when setting the callback functions, and passed back to
 168  *              the upper layer when the callback is invoked. Its type is
 169  *              not important to the driver, so it is a void pointer.
 170  * @param       StatusEvent holds one or more status events that have occurred.
 171  *              See the XQspiPsu_SetStatusHandler() for details on the status
 172  *              events that can be passed in the callback.
 173  * @param       ByteCount indicates how many bytes of data were successfully
 174  *              transferred.  This may be less than the number of bytes
 175  *              requested if the status event indicates an error.
 176  */
 177 typedef void (*XQspiPsu_StatusHandler) (void *CallBackRef, u32 StatusEvent,
 178                                         u32 ByteCount);
 179
 180 /**
 181  * This typedef contains configuration information for a flash message.
 182  */
 183 typedef struct {
 184         u8 *TxBfrPtr;
 185         u8 *RxBfrPtr;
 186         u32 ByteCount;
 187         u32 BusWidth;
 188         u32 Flags;
 189         u8 PollData;
 190         u32 PollTimeout;
 191         u8 PollStatusCmd;
 192         u8 PollBusMask;
 193 } XQspiPsu_Msg;
 194
 195 /**
 196  * This typedef contains configuration information for the device.
 197  */
 198 typedef struct {
 199         u16 DeviceId;           /**< Unique ID  of device */
 200         u32 BaseAddress;        /**< Base address of the device */
 201         u32 InputClockHz;       /**< Input clock frequency */
 202         u8  ConnectionMode; /**< Single, Stacked and Parallel mode */
 203         u8  BusWidth;   /**< Bus width available on board */
 204         u8 IsCacheCoherent; /**< Describes whether Cache Coherent or not */
 205 } XQspiPsu_Config;
 206
 207 /**
 208  * The XQspiPsu driver instance data. The user is required to allocate a
 209  * variable of this type for every QSPIPSU device in the system. A pointer
 210  * to a variable of this type is then passed to the driver API functions.
 211  */
 212 typedef struct {
 213         XQspiPsu_Config Config;  /**< Configuration structure */
 214         u32 IsReady;             /**< Device is initialized and ready */
 215
 216         u8 *SendBufferPtr;       /**< Buffer to send (state) */
 217         u8 *RecvBufferPtr;       /**< Buffer to receive (state) */
 218         u8 *GenFifoBufferPtr;    /**< Gen FIFO entries */
 219         s32 TxBytes;     /**< Number of bytes to transfer (state) */
 220         s32 RxBytes;     /**< Number of bytes left to transfer(state) */
 221         s32 GenFifoEntries;      /**< Number of Gen FIFO entries remaining */
 222         u32 IsBusy;              /**< A transfer is in progress (state) */
 223         u32 ReadMode;            /**< DMA or IO mode */
 224         u32 GenFifoCS;
 225         u32 GenFifoBus;
 226         s32 NumMsg;
 227         s32 MsgCnt;
 228         s32 IsUnaligned;
 229         u8 IsManualstart;
 230         XQspiPsu_Msg *Msg;
 231         XQspiPsu_StatusHandler StatusHandler;
 232         void *StatusRef;         /**< Callback reference for status handler */
 233 } XQspiPsu;
 234
 235 /***************** Macros (Inline Functions) Definitions *********************/
 236
 237 #define XQSPIPSU_READMODE_DMA   0x0U
 238 #define XQSPIPSU_READMODE_IO    0x1U
 239
 240 #define XQSPIPSU_SELECT_FLASH_CS_LOWER  0x1U
 241 #define XQSPIPSU_SELECT_FLASH_CS_UPPER  0x2U
 242 #define XQSPIPSU_SELECT_FLASH_CS_BOTH   0x3U
 243
 244 #define XQSPIPSU_SELECT_FLASH_BUS_LOWER 0x1U
 245 #define XQSPIPSU_SELECT_FLASH_BUS_UPPER 0x2U
 246 #define XQSPIPSU_SELECT_FLASH_BUS_BOTH  0x3U
 247
 248 #define XQSPIPSU_SELECT_MODE_SPI        0x1U
 249 #define XQSPIPSU_SELECT_MODE_DUALSPI    0x2U
 250 #define XQSPIPSU_SELECT_MODE_QUADSPI    0x4U
 251
 252 #define XQSPIPSU_GENFIFO_CS_SETUP       0x05U
 253 #define XQSPIPSU_GENFIFO_CS_HOLD        0x04U
 254
 255 #define XQSPIPSU_CLK_ACTIVE_LOW_OPTION  0x2U
 256 #define XQSPIPSU_CLK_PHASE_1_OPTION     0x4U
 257 #define XQSPIPSU_MANUAL_START_OPTION    0x8U
 258 #define XQSPIPSU_LQSPI_MODE_OPTION      0x20U
 259
 260 #define XQSPIPSU_GENFIFO_EXP_START      0x100U
 261
 262 #define XQSPIPSU_DMA_BYTES_MAX          0x10000000U
 263
 264 #define XQSPIPSU_CLK_PRESCALE_2         0x00U
 265 #define XQSPIPSU_CLK_PRESCALE_4         0x01U
 266 #define XQSPIPSU_CLK_PRESCALE_8         0x02U
 267 #define XQSPIPSU_CLK_PRESCALE_16                0x03U
 268 #define XQSPIPSU_CLK_PRESCALE_32                0x04U
 269 #define XQSPIPSU_CLK_PRESCALE_64                0x05U
 270 #define XQSPIPSU_CLK_PRESCALE_128       0x06U
 271 #define XQSPIPSU_CLK_PRESCALE_256       0x07U
 272 #define XQSPIPSU_CR_PRESC_MAXIMUM       7U
 273
 274 #define XQSPIPSU_CONNECTION_MODE_SINGLE         0U
 275 #define XQSPIPSU_CONNECTION_MODE_STACKED        1U
 276 #define XQSPIPSU_CONNECTION_MODE_PARALLEL       2U
 277
 278 /*QSPI Frequencies*/
 279 #define XQSPIPSU_FREQ_40MHZ 40000000
 280 #define XQSPIPSU_FREQ_100MHZ 100000000
 281 #define XQSPIPSU_FREQ_150MHZ 150000000
 282
 283 /* Add more flags as required */
 284 #define XQSPIPSU_MSG_FLAG_STRIPE        0x1U
 285 #define XQSPIPSU_MSG_FLAG_RX            0x2U
 286 #define XQSPIPSU_MSG_FLAG_TX            0x4U
 287 #define XQSPIPSU_MSG_FLAG_POLL          0x8U
 288
 289 /* GQSPI configuration to toggle WP of flash*/
 290 #define XQSPIPSU_SET_WP                                 1
 291
 292 #define XQspiPsu_Select(InstancePtr, Mask)      XQspiPsu_Out32(((InstancePtr)->Config.BaseAddress) + XQSPIPSU_SEL_OFFSET, Mask)
 293
 294 #define XQspiPsu_Enable(InstancePtr)    XQspiPsu_Out32(((InstancePtr)->Config.BaseAddress) + XQSPIPSU_EN_OFFSET, XQSPIPSU_EN_MASK)
 295
 296 #define XQspiPsu_Disable(InstancePtr)   XQspiPsu_Out32(((InstancePtr)->Config.BaseAddress) + XQSPIPSU_EN_OFFSET, 0x0U)
 297
 298 #define XQspiPsu_GetLqspiConfigReg(InstancePtr)   XQspiPsu_In32((XQSPIPS_BASEADDR) + XQSPIPSU_LQSPI_CR_OFFSET)
 299
 300
 301 /************************** Function Prototypes ******************************/
 302
 303 /* Initialization and reset */
 304 XQspiPsu_Config *XQspiPsu_LookupConfig(u16 DeviceId);
 305 s32 XQspiPsu_CfgInitialize(XQspiPsu *InstancePtr, XQspiPsu_Config *ConfigPtr,
 306                                 u32 EffectiveAddr);
 307 void XQspiPsu_Reset(XQspiPsu *InstancePtr);
 308 void XQspiPsu_Abort(XQspiPsu *InstancePtr);
 309
 310 /* Transfer functions and handlers */
 311 s32 XQspiPsu_PolledTransfer(XQspiPsu *InstancePtr, XQspiPsu_Msg *Msg,
 312                                 u32 NumMsg);
 313 s32 XQspiPsu_InterruptTransfer(XQspiPsu *InstancePtr, XQspiPsu_Msg *Msg,
 314                                 u32 NumMsg);
 315 s32 XQspiPsu_InterruptHandler(XQspiPsu *InstancePtr);
 316 void XQspiPsu_SetStatusHandler(XQspiPsu *InstancePtr, void *CallBackRef,
 317                                 XQspiPsu_StatusHandler FuncPointer);
 318
 319 /* Configuration functions */
 320 s32 XQspiPsu_SetClkPrescaler(XQspiPsu *InstancePtr, u8 Prescaler);
 321 void XQspiPsu_SelectFlash(XQspiPsu *InstancePtr, u8 FlashCS, u8 FlashBus);
 322 s32 XQspiPsu_SetOptions(XQspiPsu *InstancePtr, u32 Options);
 323 s32 XQspiPsu_ClearOptions(XQspiPsu *InstancePtr, u32 Options);
 324 u32 XQspiPsu_GetOptions(XQspiPsu *InstancePtr);
 325 s32 XQspiPsu_SetReadMode(XQspiPsu *InstancePtr, u32 Mode);
 326 void XQspiPsu_SetWP(XQspiPsu *InstancePtr, u8 Value);
 327 void XQspiPsu_WriteProtectToggle(XQspiPsu *InstancePtr, u32 Toggle);
 328
 329 #ifdef __cplusplus
 330 }
 331 #endif
 332
 333
 334 #endif /* XQSPIPSU_H_ */
 335 /** @} */