1 /******************************************************************************
3 * Copyright (C) 2018 Xilinx, Inc. All rights reserved.
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:
12 * The above copyright notice and this permission notice shall be included in
13 * all copies or substantial portions of the Software.
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.
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
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.
31 ******************************************************************************/
32 /*****************************************************************************/
36 * @addtogroup qspipsu_v1_7
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
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.
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.
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.
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
86 * MODIFICATION HISTORY:
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
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
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
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
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
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
144 ******************************************************************************/
145 #ifndef XQSPIPSU_H_ /* prevent circular inclusions */
146 #define XQSPIPSU_H_ /* by using protection macros */
152 /***************************** Include Files *********************************/
155 #include "xqspipsu_hw.h"
156 #include "xil_cache.h"
158 /**************************** Type Definitions *******************************/
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.
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.
177 typedef void (*XQspiPsu_StatusHandler) (void *CallBackRef, u32 StatusEvent,
181 * This typedef contains configuration information for a flash message.
196 * This typedef contains configuration information for the device.
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 */
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.
213 XQspiPsu_Config Config; /**< Configuration structure */
214 u32 IsReady; /**< Device is initialized and ready */
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 */
231 XQspiPsu_StatusHandler StatusHandler;
232 void *StatusRef; /**< Callback reference for status handler */
235 /***************** Macros (Inline Functions) Definitions *********************/
237 #define XQSPIPSU_READMODE_DMA 0x0U
238 #define XQSPIPSU_READMODE_IO 0x1U
240 #define XQSPIPSU_SELECT_FLASH_CS_LOWER 0x1U
241 #define XQSPIPSU_SELECT_FLASH_CS_UPPER 0x2U
242 #define XQSPIPSU_SELECT_FLASH_CS_BOTH 0x3U
244 #define XQSPIPSU_SELECT_FLASH_BUS_LOWER 0x1U
245 #define XQSPIPSU_SELECT_FLASH_BUS_UPPER 0x2U
246 #define XQSPIPSU_SELECT_FLASH_BUS_BOTH 0x3U
248 #define XQSPIPSU_SELECT_MODE_SPI 0x1U
249 #define XQSPIPSU_SELECT_MODE_DUALSPI 0x2U
250 #define XQSPIPSU_SELECT_MODE_QUADSPI 0x4U
252 #define XQSPIPSU_GENFIFO_CS_SETUP 0x05U
253 #define XQSPIPSU_GENFIFO_CS_HOLD 0x04U
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
260 #define XQSPIPSU_GENFIFO_EXP_START 0x100U
262 #define XQSPIPSU_DMA_BYTES_MAX 0x10000000U
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
274 #define XQSPIPSU_CONNECTION_MODE_SINGLE 0U
275 #define XQSPIPSU_CONNECTION_MODE_STACKED 1U
276 #define XQSPIPSU_CONNECTION_MODE_PARALLEL 2U
279 #define XQSPIPSU_FREQ_40MHZ 40000000
280 #define XQSPIPSU_FREQ_100MHZ 100000000
281 #define XQSPIPSU_FREQ_150MHZ 150000000
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
289 /* GQSPI configuration to toggle WP of flash*/
290 #define XQSPIPSU_SET_WP 1
292 #define XQspiPsu_Select(InstancePtr, Mask) XQspiPsu_Out32(((InstancePtr)->Config.BaseAddress) + XQSPIPSU_SEL_OFFSET, Mask)
294 #define XQspiPsu_Enable(InstancePtr) XQspiPsu_Out32(((InstancePtr)->Config.BaseAddress) + XQSPIPSU_EN_OFFSET, XQSPIPSU_EN_MASK)
296 #define XQspiPsu_Disable(InstancePtr) XQspiPsu_Out32(((InstancePtr)->Config.BaseAddress) + XQSPIPSU_EN_OFFSET, 0x0U)
298 #define XQspiPsu_GetLqspiConfigReg(InstancePtr) XQspiPsu_In32((XQSPIPS_BASEADDR) + XQSPIPSU_LQSPI_CR_OFFSET)
301 /************************** Function Prototypes ******************************/
303 /* Initialization and reset */
304 XQspiPsu_Config *XQspiPsu_LookupConfig(u16 DeviceId);
305 s32 XQspiPsu_CfgInitialize(XQspiPsu *InstancePtr, XQspiPsu_Config *ConfigPtr,
307 void XQspiPsu_Reset(XQspiPsu *InstancePtr);
308 void XQspiPsu_Abort(XQspiPsu *InstancePtr);
310 /* Transfer functions and handlers */
311 s32 XQspiPsu_PolledTransfer(XQspiPsu *InstancePtr, XQspiPsu_Msg *Msg,
313 s32 XQspiPsu_InterruptTransfer(XQspiPsu *InstancePtr, XQspiPsu_Msg *Msg,
315 s32 XQspiPsu_InterruptHandler(XQspiPsu *InstancePtr);
316 void XQspiPsu_SetStatusHandler(XQspiPsu *InstancePtr, void *CallBackRef,
317 XQspiPsu_StatusHandler FuncPointer);
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);
334 #endif /* XQSPIPSU_H_ */