1 /*
2 * Copyright 2023-2024 NXP
3 * All rights reserved.
4 *
5 * SPDX-License-Identifier: BSD-3-Clause
6 */
7
8 #ifndef FSL_XSPI_H_
9 #define FSL_XSPI_H_
10
11 #include "fsl_common.h"
12
13 /*!
14 * @addtogroup xspi
15 * @{
16 */
17
18 /*******************************************************************************
19 * Definitions
20 ******************************************************************************/
21
22 /*! @name Driver version */
23 #define FSL_XSPI_DRIVER_VERSION (MAKE_VERSION(2, 2, 1))
24 /*@{*/
25
26 /*! @brief Formula to form XSPI instructions in LUT table. */
27 #define XSPI_LUT_SEQ(cmd0, pad0, op0, cmd1, pad1, op1) \
28 (XSPI_LUT_INSTR0(cmd0) | XSPI_LUT_PAD0(pad0) | XSPI_LUT_OPRND0(op0) | XSPI_LUT_INSTR1(cmd1) | \
29 XSPI_LUT_PAD1(pad1) | XSPI_LUT_OPRND1(op1))
30
31 /*! @brief Status structure of XSPI.*/
32 enum
33 {
34 kStatus_XSPI_Busy = MAKE_STATUS(kStatusGroup_XSPI, 0), /*!< XSPI is Busy */
35 kStatus_XSPI_IpCommandUsageError = MAKE_STATUS(kStatusGroup_XSPI, 1), /*!< XSPI Ip Command Usage Error*/
36 kStatus_XSPI_IpCommandtriggerError = MAKE_STATUS(kStatusGroup_XSPI, 2), /*!< XSPI Ip Command Trigger Error*/
37 kStatus_XSPI_IllegalInstructionError = MAKE_STATUS(kStatusGroup_XSPI, 3), /*!< XSPI Illegal Instruction Error*/
38 kStatus_XSPI_SequenceExecutionTimeout = MAKE_STATUS(kStatusGroup_XSPI, 4), /*!< XSPI Sequence Execution Timeout*/
39 kStatus_XSPI_FradCheckError = MAKE_STATUS(kStatusGroup_XSPI, 5), /*!< XSPI Frad Check Error*/
40 kStatus_XSPI_TgQueueWritingError = MAKE_STATUS(kStatusGroup_XSPI, 6), /*!< XSPI Tg Queue Writing Error*/
41 kStatus_XSPI_IpsBusTransError = MAKE_STATUS(kStatusGroup_XSPI, 7), /*!< XSPI Ip Bus Transfer Error*/
42 kStatus_XSPI_AhbReadAccessAsserted = MAKE_STATUS(kStatusGroup_XSPI, 8), /*!< AHB read access is asserted. */
43 kStatus_XSPI_AhbWriteAccessAsserted = MAKE_STATUS(kStatusGroup_XSPI, 9), /*!< AHB write access is asserted. */
44 kStatus_XSPI_IPAccessAsserted = MAKE_STATUS(kStatusGroup_XSPI, 10), /*!< IP access is asserted. */
45 kStatus_XSPI_AhbSubBufferFactorError = MAKE_STATUS(kStatusGroup_XSPI, 11), /*!< Wrong sub buffer factor input. */
46 kStatus_XSPI_RegWriteLocked = MAKE_STATUS(kStatusGroup_XSPI, 12), /*!< Fail to write register
47 due to write operation is locked. */
48 kStatus_XSPI_WaterMarkIllegal = MAKE_STATUS(kStatusGroup_XSPI, 13), /*!< The watermark value to
49 set is not in multiple of 4 bytes. */
50 kStatus_XSPI_PageProgramWaitFlagAsserted = MAKE_STATUS(kStatusGroup_XSPI, 14), /*!< The page program
51 wait flag already asserted. */
52 kStatus_XSPI_IpAccessAddrSettingInvalid = MAKE_STATUS(kStatusGroup_XSPI, 15), /*!< The input address for
53 Ip access is invalid. */
54 kStatus_XSPI_RxBufferEntriesCountError = MAKE_STATUS(kStatusGroup_XSPI, 16), /*!< The count of entries
55 of RX buffer is incorrect. */
56 kStatus_XSPI_IpAccessIPCRInvalid = MAKE_STATUS(kStatusGroup_XSPI, 17), /*!< Access attributes to write
57 IPCR are not correct. */
58 };
59
60 /*! @brief CMD definition of XSPI, use to form LUT instruction, xspi_lut_instr_t. */
61 typedef enum _xspi_lut_instr
62 {
63 kXSPI_Command_STOP = 0x00U, /*!< Stop execution, de-assert CS. */
64 kXSPI_Command_SDR = 0x01U, /*!< Transmit Command code to Flash, using SDR mode. */
65 kXSPI_Command_RADDR_SDR = 0x02U, /*!< Transmit Row Address to Flash, using SDR mode. */
66 kXSPI_Command_DUMMY_SDR = 0x03U, /*!< Leave data lines un-driven by xSPI controller, using SDR mode. */
67 kXSPI_Command_MODE_SDR = 0x04U, /*!< Transmit 8-bit Mode bits to Flash, using SDR mode. */
68 kXSPI_Command_MODE2_SDR = 0x05U, /*!< Transmit 2-bit Mode bits to Flash, using SDR mode. */
69 kXSPI_Command_MODE4_SDR = 0x06U, /*!< Transmit 4-bit Mode bits to Flash, using SDR mode. */
70 kXSPI_Command_READ_SDR = 0x07U, /*!< Receive Read Data from Flash, using SDR mode. */
71 kXSPI_Command_WRITE_SDR = 0x08U, /*!< Transmit Programming Data to Flash, using SDR mode. */
72 kXSPI_Command_JMP_ON_CS = 0x09U, /*!< Stop execution, de-assert CS and save operand[7:0] as the
73 instruction start pointer for next sequence*/
74 kXSPI_Command_RADDR_DDR = 0x0AU, /*!< Transmit Row Address to Flash, using DDR mode. */
75 kXSPI_Command_MODE_DDR = 0x0BU, /*!< Transmit 8-bit Mode bits to Flash, using DDR mode. */
76 kXSPI_Command_MODE2_DDR = 0x0CU, /*!< Transmit 2-bit Mode bits to Flash, using DDR mode. */
77 kXSPI_Command_MODE4_DDR = 0x0DU, /*!< Transmit 4-bit Mode bits to Flash, using DDR mode. */
78 kXSPI_Command_READ_DDR = 0x0EU, /*!< Receive Read Data from Flash, using DDR mode. */
79 kXSPI_Command_WRITE_DDR = 0x0FU, /*!< Transmit Programming Data to Flash, using DDR mode. */
80 kXSPI_Command_LEARN_DDR = 0x10U, /*!< Receive Read Data or Preamble bit from Flash, DDR mode. */
81 kXSPI_Command_DDR = 0x11U, /*!< Transmit Command code to Flash, using DDR mode. */
82 kXSPI_Command_CADDR_SDR = 0x12U, /*!< Transmit Column Address to Flash, using SDR mode. */
83 kXSPI_Command_CADDR_DDR = 0x13U, /*!< Transmit Column Address to Flash, using DDR mode. */
84 kXSPI_Command_JUMP_TO_SEQ = 0x14U, /*!< Jump the LUT sequence pointed to by the operand. */
85 } xspi_lut_instr_t;
86
87 /*! @brief pad definition of XSPI, use to form LUT instruction. */
88 typedef enum _xspi_pad
89 {
90 kXSPI_1PAD = 0x00U, /*!< Transmit command/address and transmit/receive data only through DATA0/DATA1. */
91 kXSPI_2PAD = 0x01U, /*!< Transmit command/address and transmit/receive data only through DATA[1:0]. */
92 kXSPI_4PAD = 0x02U, /*!< Transmit command/address and transmit/receive data only through DATA[3:0]. */
93 kXSPI_8PAD = 0x03U, /*!< Transmit command/address and transmit/receive data only through DATA[7:0]. */
94 } xspi_pad_t;
95
96 /*! @brief XSPI interrupt status flags.*/
97 typedef enum _xspi_flags
98 {
99 kXSPI_DataLearningFailedFlag = XSPI_FR_DLPFF_MASK, /*!< Data learning failed. */
100 kXSPI_DllAbortFlag = XSPI_FR_DLLABRT_MASK, /*!< DLL Abort. */
101 kXSPI_DllUnlockFlag = XSPI_FR_DLLUNLCK_MASK, /*!< This field is set whenever DLL unlock event occurs,
102 irrespective of flash memory access.*/
103 kXSPI_TxBufferFillFlag = XSPI_FR_TBFF_MASK, /*!< If the field remains cleared,
104 the TX buffer can be considered as full.*/
105 kXSPI_TxBufferUnderrunFlag = XSPI_FR_TBUF_MASK, /*!< This field is set if the module tries to pull data
106 when the TX buffer is empty*/
107 kXSPI_RxBufferOverflowFlag = XSPI_FR_RBOF_MASK, /*!< This field is set when no more data can be pushed
108 into the RX buffer from the serial flash memory device.*/
109 kXSPI_RxBufferDrainFlag = XSPI_FR_RBDF_MASK, /*!< This field is set if SR[RXWE] is asserted.*/
110 kXSPI_AhbAbortErrorFlag = XSPI_FR_AAEF_MASK, /*!< This flag can be set when AHB transaction error*/
111 kXSPI_AhbIllegalTransactionErrorFlag = XSPI_FR_AITEF_MASK,
112 kXSPI_AhbIllegalBurstSizeErrorFlag = XSPI_FR_AIBSEF_MASK, /*!< The total burst size is more than prefetch size. */
113 kXSPI_AhbBufferOverflowFlag = XSPI_FR_ABOF_MASK, /*!< The size of the AHB access exceed the size of
114 the AHB buffer. */
115 kXSPI_AhbPerformanceMonitorOverflowFlag = XSPI_FR_PERFOVF_MASK, /*!< AHB performance hit or
116 miss counter overflow. */
117 kXSPI_AhbReadAddressErrorFlag = XSPI_FR_RDADDR_MASK, /*!< The master send an AHB read address to that
118 buffer is not within the address range of any
119 sub-buffers or the address within multiple sub-buffers. */
120 kXSPI_IllegalInstructionErrorFlag = XSPI_FR_ILLINE_MASK, /*!< This field is set when an illegal instruction is
121 encountered by the controller in any of the sequences.*/
122 kXSPI_IpCmdtriggerErrorFlag = XSPI_FR_IPIEF_MASK, /*!< Write access to Rx buffer control reg when
123 IP-triggered command is executing. */
124 kXSPI_PageProgramWaitFlag = XSPI_FR_PPWF_MASK, /*!< Indicates assertion of the page-program wait flag
125 after writing to flash memory. */
126 #if defined(XSPI_FR_IPEDERR_MASK)
127 kXSPI_IPEDRxDecryptionErrorFlag = XSPI_FR_IPEDERR_MASK, /*!< only support XSPI0 XSPI1*/
128 #endif /* defined(XSPI_FR_IPEDERR_MASK) */
129 kXSPI_IpCommandExecutionDoneFlag = XSPI_FR_TFF_MASK, /*!< Indicates XSPI has completed a running IP command. */
130 kXSPI_SequenceExecutionTimeoutFlag = XSPI_INT_EN_TO_ERR_MASK, /*!< Sequence execution timeout. */
131 kXSPI_FradMatchErrorFlag = XSPI_INT_EN_FRADMTCH_MASK, /*Transaction address does not lie within address range of
132 any FRAD descriptor.*/
133 kXSPI_Frad0AccessErrorFlag = XSPI_INT_EN_FRAD0ACC_MASK, /*<! FRAD 0 access error. */
134 kXSPI_Frad1AccessErrorFlag = XSPI_INT_EN_FRAD1ACC_MASK, /*<! FRAD 1 access error. */
135 kXSPI_Frad2AccessErrorFlag = XSPI_INT_EN_FRAD0ACC_MASK, /*<! FRAD 2 access error. */
136 kXSPI_Frad3AccessErrorFlag = XSPI_INT_EN_FRAD1ACC_MASK, /*<! FRAD 3 access error. */
137 kXSPI_Frad4AccessErrorFlag = XSPI_INT_EN_FRAD0ACC_MASK, /*<! FRAD 4 access error. */
138 kXSPI_Frad5AccessErrorFlag = XSPI_INT_EN_FRAD1ACC_MASK, /*<! FRAD 5 access error. */
139 kXSPI_Frad6AccessErrorFlag = XSPI_INT_EN_FRAD0ACC_MASK, /*<! FRAD 6 access error. */
140 kXSPI_Frad7AccessErrorFlag = XSPI_INT_EN_FRAD1ACC_MASK, /*<! FRAD 7 access error. */
141 kXSPI_FradnAccErrorFlag = XSPI_INT_EN_FRAD0ACC_MASK | XSPI_INT_EN_FRAD1ACC_MASK | XSPI_INT_EN_FRAD2ACC_MASK |
142 XSPI_INT_EN_FRAD3ACC_MASK | XSPI_INT_EN_FRAD4ACC_MASK | XSPI_INT_EN_FRAD5ACC_MASK |
143 XSPI_INT_EN_FRAD6ACC_MASK | XSPI_INT_EN_FRAD7ACC_MASK, /*!< ORed value of all frad
144 error flag,. */
145 kXSPI_IpsErrorFlag = XSPI_INT_EN_IPS_ERR_MASK,
146 kXSPI_Tg0SfarErrorFlag = XSPI_INT_EN_TG0SFAR_MASK,
147 kXSPI_Tg1SfarErrorFlag = XSPI_INT_EN_TG1SFAR_MASK,
148 kXSPI_TgnIpcrErrorFlag = XSPI_INT_EN_TG0IPCR_MASK | XSPI_INT_EN_TG1IPCR_MASK,
149 kXSPI_LockRegErrorFlag = XSPI_INT_EN_LCK_ERR_IE_MASK,
150 kXSPI_ArbLockTimeoutFlag = XSPI_INT_EN_ARB_TO_IE_MASK,
151 kXSPI_ArbWinEventFlag = XSPI_INT_EN_ARB_WIN_IE_MASK,
152 } xspi_flags_t;
153
154 /************************** External Device Control Structures and Enumerations Start *******************************/
155 /*! @brief The enumeration of Idle signal drive IOFA[3] and IOFA[2]
156 */
157 enum _xspi_external_signal
158 {
159 XSPI_SignalIOFA2 = XSPI_MCR_ISD2FA_MASK, /*!< Idle signal drive IOFA[2]. */
160 XSPI_SignalIOFA3 = XSPI_MCR_ISD3FA_MASK /*!< Idle signal drive IOFA[3]. */
161 };
162
163 /*!
164 * @brief The structure of external device's status register information(location, priority).
165 * @note Only useful when AHB write to flash device is enabled, and use hardware to clear ppw flag.
166 */
167 typedef struct _xspi_device_status_reg_info
168 {
169 uint8_t wipLocation; /*!< WIP bit field's location. */
170 bool upperHalfWordSelected; /*!< Specify which half word(upper or lower) is selected. */
171 bool value1Expired; /*!< Specify the value to be check o selected wip location to
172 determine if the page progame wait period is expired,
173 true means expected value is 1, false means expected value
174 is 0. */
175 } xspi_device_status_reg_info_t;
176
177 /*! @brief Dll Mode enumerations. */
178 typedef enum _xspi_dll_mode
179 {
180 kXSPI_AutoUpdateMode, /*!< Dll mode : Auto update mode. */
181 kXSPI_BypassMode, /*!< Dll mode : Bypass mode. */
182 } xspi_dll_mode_t;
183
184 /*!
185 * @brief The union of user custommed DLL parameters, in case of #kXSPI_BypassMode bypassModePara is used, in case of
186 * #kXSPI_AutoUpdateMode autoUpdateModoPara is used.
187 */
188 typedef union _xspi_dll_para
189 {
190 struct
191 {
192 uint16_t delayElementCoarseValue : 4U; /*!< Delay element coarse adjustment value, range from 0 to 15. */
193 uint16_t delayElementFineValue : 3U; /*!< Delay element fine adjustment value, range from 0 to 7. */
194 uint16_t offsetDelayElementCount : 4U; /*!< Specify the number of offset delay elements,
195 range from 0 to 15. */
196 uint16_t enableHighFreq : 1U; /*!< If set as true, high frequency used for delay chain operations,
197 otherwise low frequency is used. */
198 uint16_t bypassModeReserved : 4U; /*!< Reserved. */
199 } bypassModePara;
200 struct
201 {
202 uint16_t referenceCounter : 4U; /*!< Specify count of interval for DLL phase detection, range from
203 0 to 15. */
204 uint16_t resolution : 4U; /*!< Specify minimum resolution for the DLL phase detctor,
205 range from 0 to 15. */
206 uint16_t offsetDelayElementCount : 4U; /*!< Specify the number of offset delay elements,
207 range from 0 to 15. */
208 uint16_t tDiv16OffsetDelayElementCount : 3U; /*!< Specify the number of T/16 offset elements in the incoming
209 DQS, range from 0 to 15. */
210 uint16_t enableHighFreq : 1U; /*!< If set as true, high frequency used for delay chain operations,
211 otherwise low frequency is used. */
212 } autoUpdateModoPara;
213 } xspi_dll_para_t;
214
215 /*!
216 * @brief The structure of Delay-lock-loop configuration.
217 */
218 typedef struct _xspi_dll_config
219 {
220 xspi_dll_mode_t dllMode; /*!< Dll mode auto update mode or bypass mode */
221 bool useRefValue; /*!< Specify to use reference value or not, if the reference code do not
222 satisfy the specific usecase, it is application's responsibility to
223 set custom parameters
224 - \b true: following inputs are ignored, use the reference values
225 provided by NXP as instead;
226 - \b false: following inputs take effect. */
227
228 xspi_dll_para_t dllCustomPara; /*!< User custommed parameter to configure DLL, different DLL mode
229 corresponding to different parameters, please refer to the union
230 @ref xspi_dll_para_t. */
231 uint8_t dllCustomDelayTapNum; /*!< User custommed number of delay elements for each delay tap. */
232 bool enableCdl8; /*!< Enable course delay line 8. */
233 } xspi_dll_config_t;
234
235 /*!
236 * @brief The enumeration of sample clock source which is used to sample data from external devices.
237 *
238 * @note If external device support Data strobe signal, the sample clock
239 * should selected as kXSPI_SampleClkFromExternalDQS.
240 */
241 typedef enum _xspi_sample_clk_source
242 {
243 kXSPI_SampleClkFromNonInvertedFullySpeedDummyPadLoopback = 0x1U, /*!< Sample clock from non inverted
244 fully speed dummy pad loopback. */
245 kXSPI_SampleClkFromInvertedFullySpeedDummyPadLoopback = 0x5U, /*!< Sample clock from inverted
246 fully speed dummy pad loopback. */
247 kXSPI_SampleClkFromHalfSpeedDummyPadLoopback = 0x9U, /*!< Sample clock from half
248 fully speed dummy pad loopback. */
249 kXSPI_SampleClkFromDqsPadLoopback = 0x2U, /*!< Sample clock from Dqs pad loopback. */
250 kXSPI_SampleClkFromExternalDQS = 0x3U, /*!< Sample clock from external DQS signal. */
251 } xspi_sample_clk_source_t;
252
253 /*!
254 * @brief The selection of data learning pad.
255 */
256 typedef enum _xspi_data_learning_pad_select
257 {
258 kXSPI_OnlyIO1 = 1U, /*!< IO1 selected as pad to use for pattern matching IO. */
259 kXSPI_BothIO1IO3 = 3U, /*!< IO1 and IO3 selected as pad to use for pattern matching IO. */
260 } xspi_data_learning_pad_select_t;
261
262 /*!
263 * @brief The configuration of data learning.
264 *
265 * @note Data learning feature only supported in the DQS sampling method(kXSPI_SampleClkFromExternalDQS).
266 */
267 typedef struct _xspi_data_learning_config
268 {
269 uint32_t pattern; /*!< Pre-defiend pattern to match. */
270 bool deviceSupported; /*!< Specify if external device support data learning feature. */
271 xspi_data_learning_pad_select_t padSelected; /*!< Used to select pad which use for pattern matching IO. */
272 } xspi_data_learning_config_t;
273
274 /*!
275 * @brief Sample clock configuration, which used to sample data from external device.
276 */
277 typedef struct _xspi_sample_clk_config
278 {
279 xspi_sample_clk_source_t sampleClkSource; /*!< Specify the sample clock source. */
280 bool enableDQSLatency; /*!< Enable DQS latency or not. */
281 xspi_dll_config_t dllConfig; /*!< Specify the DLL configuration, to improve data accuracy, please adjust
282 DLL settings based on specific use. */
283 } xspi_sample_clk_config_t;
284
285 /*!
286 * @brief External device's address mode.
287 */
288 typedef enum _xspi_device_addr_mode
289 {
290 kXSPI_DeviceByteAddressable = 0U, /*!< Byte addressable. */
291 kXSPI_Device2ByteAddressable = 1U, /*!< Two bytes addressable. */
292 kXSPI_Device4ByteAddressable = 2U, /*!< Four bytes addressable. */
293 } xspi_device_addr_mode_t;
294
295 /*!
296 * @brief The enumeration of external device's interface type, hyper bus or SPI(including strandard and extended).
297 *
298 * @note Different interface result different settings.
299 */
300 typedef enum _xspi_device_interface_type
301 {
302 kXSPI_StrandardExtendedSPI = 0U, /*!< External device follow SPI protocol, DQS_OUT_EN must be 0 */
303 kXSPI_HyperBus = 1U, /*!< External device follow hyper Bus protocol, DQS_OUT_EN must be 1 */
304 } xspi_device_interface_type_t;
305
306 /*!
307 * @brief The enumeration of hyper bus X16 mode
308 */
309 typedef enum _xspi_hyper_bus_x16_mode
310 {
311 kXSPI_x16ModeDisable = 0U, /*!< X16 mode is disabled. */
312 kXSPI_x16ModeEnabledOnlyData = 2U, /*!< X16 mode is enabled only for data. */
313 kXSPI_x16ModeEnabledAddrCmdData = 3U, /*!< X16 mode is enabled for address, command, and data. */
314 } xspi_hyper_bus_x16_mode_t;
315
316 /*!
317 * @brief The union of external device's settings, if external device following hyper bus protocol #hyperBusSettings
318 * take effects, if external device following SPI protocol #strandardExtendedSPISettings take effects.
319 */
320 typedef union _xspi_device_interface_settings
321 {
322 struct
323 {
324 uint32_t pageSize; /*!< The size of page to program, the unit is byte. */
325 } strandardExtendedSPISettings;
326
327 struct
328 {
329 xspi_hyper_bus_x16_mode_t x16Mode; /*!< Specify hyper bus X16 mode. */
330 bool enableVariableLatency; /*!< If enabled, the count of latency is depends on hyper bus device. */
331 bool forceBit10To1; /*!< Force bit 10 to logic one or not. */
332 } hyperBusSettings;
333 } xspi_device_interface_settings_t;
334
335 /*!
336 * @brief Enumeration defining the alignment modes of XSPI DDR data with respect to the internal reference clock.
337 */
338 typedef enum _xspi_ddr_data_aligned_clk
339 {
340 kXSPI_DDRDataAlignedWithInternalRefClk = 0U, /*!< DDR data aligned with internal reference clock. */
341 kXSPI_DDRDataAlignedWith2xInternalRefClk, /*!< DDR data aligned with 2X internal reference clock. */
342 } xspi_ddr_data_aligned_clk_t;
343
344 /*!
345 * @brief The structure of device DDR configuration.
346 */
347 typedef struct _xspi_device_ddr_config
348 {
349 bool enableDdr; /*!< Used to enable/disable DDR mode. */
350 xspi_ddr_data_aligned_clk_t ddrDataAlignedClk; /*!< Specify the DDR data aligned clock. */
351 bool enableByteSwapInOctalMode; /*!< Swap byte order in octal mode. */
352 } xspi_device_ddr_config_t;
353
354 /*! @brief External device configuration items. */
355 typedef struct _xspi_device_config
356 {
357 uint32_t xspiRootClk; /*!< XSPI serial root clock. */
358 bool enableCknPad; /*!< Enable/disable clock on differential CKN pad for flash memory A.*/
359
360 xspi_device_interface_type_t deviceInterface; /*!< Type of external device's interface:
361 hyperBus or Strandard/Extended SPI. */
362 xspi_device_interface_settings_t interfaceSettings; /*!< Settings of specified interface. */
363
364 uint8_t CSHoldTime; /*!< CS line hold time. */
365 uint8_t CSSetupTime; /*!< CS line setup time. */
366
367 xspi_sample_clk_config_t sampleClkConfig; /*!< Configuration of sample clock. */
368
369 xspi_device_ddr_config_t *ptrDeviceDdrConfig; /*!< Set as NULL to set device as SDR mode, to change to DDR mode,
370 this member should be populated. */
371
372 xspi_device_addr_mode_t addrMode; /*!< Address mode of external device. */
373 uint8_t columnAddrWidth; /*!< Width of column address. */
374 bool enableCASInterleaving; /*!< Usually enabled in dual-die device. */
375 uint32_t deviceSize[XSPI_SFAD_COUNT2]; /*!< Size of external device, the unit is KB. */
376
377 xspi_device_status_reg_info_t *ptrDeviceRegInfo; /*!< Pointer to the structure to store external device's WIP
378 register information, should set as NULL if AHB page write
379 is not used or if AHB page write is used but use software
380 policy to clear flag. */
381 } xspi_device_config_t;
382 /************************** External Device Control Structures and Enumerations End *******************************/
383
384 /**************************** IP Access Control Structures and Enumerations Start *********************************/
385 /*! @brief Command type. */
386 typedef enum _xspi_command_type
387 {
388 kXSPI_Command, /*!< XSPI operation: Only command, both TX and Rx buffer are ignored. */
389 kXSPI_Config, /*!< XSPI operation: Configure device mode, the TX fifo size is fixed in LUT. */
390 kXSPI_Read, /*!< XSPI operation: Read, only Rx Buffer is effective. */
391 kXSPI_Write, /*!< XSPI operation: Read, only Tx Buffer is effective. */
392 } xspi_command_type_t;
393
394 /*!
395 * @brief The enumeration of SFP MDAD mask type.
396 */
397 typedef enum _xspi_mdad_mask_type
398 {
399 kXSPI_MdadMaskTypeAnd = 0U, /*!< Target master is mask & reference. */
400 kXSPI_MdadMaskTypeOr, /*!< Target master is mask | reference. */
401 } xspi_mdad_mask_type_t;
402
403 /*!
404 * @brief The enumeration of MDAD error reasons.
405 */
406 typedef enum _xspi_mdad_error_reason
407 {
408 kXSPI_ErrorOnlyDataSize = 1U, /*!< Error reason: Only Data size without required attributes. */
409 kXSPI_ErrorOnlySeqId, /*!< Error reason: Only sequence ID without required attributes. */
410 kXSPI_ErrorBothDataSizeSeqId, /*!< Error reason: Both Data size and sequence ID without required attributes. */
411 } xspi_mdad_error_reason_t;
412
413 /*! @brief Exclusive access lock. */
414 typedef enum _xspi_exclusive_access_lock_mode
415 {
416 kXSPI_ExclusiveAccessLockDisabled = 0x0U, /*!< Write permissions available for all masters
417 based on their MDxACP evaluation.*/
418 kXSPI_ExclusiveAccessLockEnabled = 0x2U, /*!< Write permissions revoked for all domains, Any write
419 transaction coming to this flash address will result in an error..*/
420 kXSPI_ExclusiveAccessLockExceptMasterId = 0x3U, /*!< Write permissions are revoked for all masters except the master
421 ID specified by FRADn_WORD2[EALO] fields.*/
422 } xspi_exclusive_access_lock_mode_t;
423
424 /*! @brief XSPI defines the secure attribute selection criteria for entry into descriptor queue...*/
425 typedef enum _xspi_secure_attribute
426 {
427 kXSPI_AttributeMasterNonsecureOnly = 0x1U, /*!< Allow the bus attribute for this master to
428 non-secure only*/
429 kXSPI_AttributeMasterSecureOnly = 0x2U, /*!< Allow the bus attribute for this master to secure only*/
430 kXSPI_AttributeMasterNonsecureSecureBoth = 0x3U, /*!< Allow the bus master's attribute: Both secure and
431 non-secure*/
432 } xspi_secure_attribute_t;
433
434 /*! @brief MDAD configuration. */
435 typedef struct _xspi_mdad_config
436 {
437 bool assignIsValid; /*!< Specify if the MDAD configuration for the target group is valid */
438
439 bool enableDescriptorLock; /*!< This field provides a means to make the MDAD descriptor read-only.
440 Once written '1' this field will remain '1' until hard reset*/
441 uint8_t maskType; /*!< 0b - ANDed mask 1b - ORed mask*/
442 uint8_t mask; /*!< Defines the 6-bit mask value for the ID-Match comparison*/
443 uint8_t masterIdReference; /*!< Specifies the reference value of the Master-ID for MID-comparison*/
444 xspi_secure_attribute_t secureAttribute; /*!< Defines the secure attribute selection criteria for entry into
445 descriptor queue*/
446 } xspi_mdad_config_t;
447
448 #define XSPI_TARGET_GROUP_COUNT (2U)
449
450 /*!
451 * @brief The structure of SFP MDAD configurations for all target groups.
452 */
453 typedef struct _xspi_sfp_mdad_config
454 {
455 xspi_mdad_config_t tgMdad[XSPI_TARGET_GROUP_COUNT]; /*!< Specify MDAD configurations for each target group. */
456 } xspi_sfp_mdad_config_t;
457
458 /*! @brief Descriptor lock. */
459 typedef enum _xspi_descriptor_lock
460 {
461 kXSPI_DescriptorLockDisabled = 0x0U, /*!< Descriptor registers can be written by any master*/
462 kXSPI_DescriptorLockEnabledTillHardReset = 0x1U, /*!< FRAD descriptor is read-only till next hard reset.*/
463 kXSPI_DescriptorLockEnabledExceptMasterId = 0x2U, /*!< Descriptors are read-only. MDnACP fields can be programmed
464 only by the master with ID matching the MID.*/
465 kXSPI_DescriptorLockEnabled = 0x3U, /*!< Descriptor registers are read-only.*/
466 } xspi_descriptor_lock_t;
467
468 /*! @brief FRAD configuration. */
469 typedef struct _xspi_frad_config_t
470 {
471 uint32_t startAddress; /*!< Specifies the specific flash memory region starting address*/
472 uint32_t endAddress; /*!< Specifies the specific flash memory region end address*/
473 uint8_t tg0MasterAccess; /*!< This field define the access restrictions for respective Master Domain
474 corresponding to this FRAD region. Access permissions are decided based on secure
475 an privilege attributes of current transaction. Read access is not restricted.*/
476 uint8_t tg1MasterAccess;
477 bool assignIsValid; /*!< This field indicates whether the FRAD Descriptor for a specific flash region
478 is valid.*/
479 xspi_descriptor_lock_t descriptorLock; /*!< This field enables masking of accidental write on FRAD registers.
480 Lock is enabled/disabled by Secure/ Privileged master.*/
481 xspi_exclusive_access_lock_mode_t exclusiveAccessLock; /*!< This field provides exclusive write lock over a
482 FRAD region based on MDnACP.*/
483 } xspi_frad_config_t;
484
485 #define XSPI_SFP_FRAD_COUNT (8U)
486 /*!
487 * @brief The structure of SFP FRAD configurations.
488 */
489 typedef struct _xspi_sfp_frad_config
490 {
491 xspi_frad_config_t fradConfig[XSPI_SFP_FRAD_COUNT]; /*!< Specify FRAD configuration for each item. */
492 } xspi_sfp_frad_config_t;
493
494 /*!
495 * @brief The structure of latest FRAD transaction information.
496 */
497 typedef struct _xspi_frad_transaction_info
498 {
499 uint32_t startAddr; /*!< Latest IP access start address. */
500 uint8_t masterId; /*!< Latest IP access master Id. */
501 bool isSecureAccess; /*!< Latest IP access is secure access or not. */
502 bool isPrivilegeAccess; /*!< Latest IP access is privilege access or not. */
503 bool isCompError; /*!< Indicates the error status of the flash region specific comparision check for
504 the latest transaction. */
505 bool isCompValid; /*!< Indicates availability of the result or status of a flash region-specific
506 comparison check. */
507 } xspi_frad_transaction_info_t;
508
509 /*!
510 * @brief Configurations of IP access(including IP read and write).
511 */
512 typedef struct _xspi_ip_access_config
513 {
514 xspi_sfp_mdad_config_t *ptrSfpMdadConfig; /*!< Pointer to the variable in type of @ref xspi_sfp_mdad_config_t to
515 set SFP MDAD feature, set as NULL to disable SFP MDAD feature. */
516 xspi_sfp_frad_config_t *ptrSfpFradConfig; /*!< Pointer to the variable in type of @ref xspi_sfp_frad_config_t to
517 set SFP FRAD feature, set as NULL to disable SFP FRAD */
518 uint32_t sfpArbitrationLockTimeoutValue; /*!< Specify the time in IPS clock cycles before an unreleased
519 arbitration triggers a timeout error. */
520 uint32_t ipAccessTimeoutValue; /*!< Specify the maximum time in IPS clock cycles for XSPI to wait fro an
521 ongoing write or read command to complete before terminating the command. */
522 } xspi_ip_access_config_t;
523
524 #define XSPI_IP_RX_BUFFER_SIZE (512U)
525
526 /*! @brief The enumeration of target group. */
527 typedef enum _xspi_target_group
528 {
529 kXSPI_TargetGroup0 = 0x0U, /*!< Target groupe queue 0*/
530 kXSPI_TargetGroup1 = 0x1U, /*!< Target groupe queue 1*/
531 } xspi_target_group_t;
532
533 /*!
534 * @brief The status of latest target group address write operation.
535 */
536 typedef struct _xspi_tg_add_write_status
537 {
538 uint8_t managerId; /*!< Manager Id of TG address write operation. */
539 bool secureWrite; /*!< TG address write operation is secure write. */
540 bool privilegedWrite; /*!< TG address write operation is privileged. */
541 } xspi_tg_add_write_status_t;
542
543 /*! @brief Transfer structure used for XSPI functional interface. */
544 typedef struct _xspi_transfer
545 {
546 uint32_t deviceAddress; /*!< Operation device address. */
547 xspi_command_type_t cmdType; /*!< Execution command type. */
548 uint8_t seqIndex; /*!< Sequence ID for command. */
549 uint32_t *data; /*!< Data buffer. */
550 size_t dataSize; /*!< Data size in bytes. */
551 xspi_target_group_t targetGroup; /*!< Target group. include targetGroup[0] targetGroup[1]*/
552 bool lockArbitration;
553 } xspi_transfer_t;
554
555 /* Forward declaration of the handle typedef. */
556 typedef struct _xspi_handle xspi_handle_t;
557
558 /*! @brief XSPI transfer callback function. */
559 typedef void (*xspi_transfer_callback_t)(XSPI_Type *base, xspi_handle_t *handle, status_t status, void *userData);
560
561 /*! @brief Transfer handle structure for XSPI. */
562 struct _xspi_handle
563 {
564 uint32_t state; /*!< Internal state for XSPI transfer */
565 uint8_t *data; /*!< Data buffer. */
566 size_t dataSize; /*!< Remaining Data size in bytes. */
567 size_t transferTotalSize; /*!< Total Data size in bytes. */
568 xspi_transfer_callback_t completionCallback; /*!< Callback for users while transfer finish or error occurred */
569 void *userData; /*!< XSPI callback function parameter.*/
570 };
571 /**************************** IP Access Control Structures and Enumerations End *********************************/
572
573 /**************************** AHB Access Control Structures and Enumerations Start *********************************/
574 /*! @brief Subbuffer division factor. */
575 typedef enum _xspi_subbuffer_division_factor
576 {
577 kXSPI_Division0 = 0x0U, /*!< division factor 0*/
578 kXSPI_Division2 = 0x1U, /*!< division factor 2 subbuffer size/2*/
579 kXSPI_Division4 = 0x2U, /*!< division factor 4 subbuffer size/4*/
580 kXSPI_Division8 = 0x3U, /*!< division factor 8 subbuffer size/8*/
581 kXSPI_Division16 = 0x4U, /*!< division factor 16 subbuffer size/16*/
582 } xspi_subbuffer_division_factor_t;
583
584 /*!
585 * @brief The structure of sub-buffer configurations.
586 */
587 typedef struct _xspi_ahbBuffer_sub_buffer_config
588 {
589 xspi_subbuffer_division_factor_t divFactor; /*!< Specify the divide factor for current sub-buffer. */
590 uint32_t startAddr; /*!< Specify the start address of current sub-buffer. */
591 uint32_t endAddr; /*!< Specify the end address of current sub-buffer. */
592 bool enableAhbMonitor; /*!< Enable/disable AHB performance monitor for current sub-buffer. */
593 } xspi_ahbBuffer_sub_buffer_config_t;
594
595 /*!
596 * @brief Structure of AHB buffer configurations.
597 *
598 * @note When an AHB read access comes it is assigned to a buffer based on its master ID. Then
599 * it further assigned to a sub-buffer based on which sub-buffer address range this transaction lies into.
600 *
601 * @note When sub-buffer division is hit, in case of a buffer miss the controller will fetch the data equal to the size
602 * of that sub-buffer.
603 *
604 * @note If sub-buffer division is enabled for a buffer the hit/miss check is done at sub-buffer level. And if prefetch
605 * is enable, the prefetch takes place for individual sub-buffers.
606 */
607 typedef struct _xspi_ahbBuffer_config
608 {
609 uint8_t masterId; /*!< Specify the ID of the AHB master to be associated with buffer. */
610 union
611 {
612 bool enablePriority; /*!< High Priority Enable, it can be written '1' only when OTFAD is disabled,
613 the AHB prefetch feature must be enabled if priority mechanism is enabled.
614 */
615 bool enableAllMaster; /*!< When set, buffer3 acts as an all-master buffer.buff[i] routed to buffer3*/
616 } enaPri;
617
618 uint16_t bufferSize; /* Specify the AHB buffer size and transfer size(8 byte as unit),
619 * in range of 512, 256, 128, 64, 32, 16, 8, 4, 2, 0.
620 */
621 xspi_ahbBuffer_sub_buffer_config_t *ptrSubBuffer0Config; /*!< Pointer to sub buffer0's configuration. */
622 xspi_ahbBuffer_sub_buffer_config_t *ptrSubBuffer1Config; /*!< Pointer to sub buffer1's configuration. */
623 xspi_ahbBuffer_sub_buffer_config_t *ptrSubBuffer2Config; /*!< Pointer to sub buffer2's configuration. */
624 xspi_ahbBuffer_sub_buffer_config_t *ptrSubBuffer3Config; /*!< Pointer to sub buffer3's configuration. */
625 } xspi_ahbBuffer_config_t;
626
627 /*!
628 * @brief The enumeration of sub buffer status, empty, full, or partially full.
629 */
630 typedef enum _xspi_ahb_sub_buffer_status
631 {
632 kXSPI_AhbSubBufferEmpty = 0U, /*!< Current sub buffer is empty. */
633 kXSPI_AhbSubBufferFull, /*!< Current sub buffer is full. */
634 kXSPI_AhbSubBufferPartiallyFull, /*!< Current sub buffer contains some entries. */
635 } xspi_ahb_sub_buffer_status_t;
636
637 /*!
638 * @brief The result of AHB buffer performance monitor, including buffer miss count and buffer hit count.
639 */
640 typedef struct _xspi_ahbBuffer_perf_monitor_result
641 {
642 uint16_t bufferMissCount; /*!< Count of AHB read buffer miss events. */
643 uint16_t bufferHitCount; /*!< Count of AHB read buffer hit events. */
644 } xspi_ahbBuffer_perf_monitor_result_t;
645
646 /*!
647 * @brief The enumeration of XSPI page program waiting flag clear policy.
648 */
649 typedef enum _xspi_ppw_flag_clear_policy
650 {
651 kXSPI_SoftwareClearPPWFlag = 0U, /*!< Application should clear the flag manually, after check the WIP of external
652 flag is cleared. */
653 kXSPI_HardwareClearPPWFlag, /*!< The flag is cleared by hardware automatically, the variable in type of
654 @ref xspi_device_status_reg_info_t should be defined. */
655 } xspi_ppw_flag_clear_policy_t;
656
657 /*!
658 * @brief The configuration of AHB write access.
659 */
660 typedef struct _xspi_ahb_write_config
661 {
662 bool blockSequenceWrite; /*!< Enable/disable sequence write operation after page program start. */
663 bool blockRead; /*!< Enable/disable read operation after page program start,
664 can be false for RWW extern device. */
665 xspi_ppw_flag_clear_policy_t policy; /*!< Specify the policy to clear ppw flag, hardware or software. */
666 uint32_t pageWaitTimeoutValue; /*!< Specify, in AHB clock cycles, how long XSPI waits before triggering a read of
667 the device status register, only useful in hardare policy. */
668 uint8_t AWRSeqIndex; /*!< Specify the sequence index for AHB write. */
669 uint8_t ARDSRSeqIndex; /*!< Specify the sequence index for AHB read status, only useful if
670 either sequence write or read is blocked. */
671 } xspi_ahb_write_config_t;
672
673 /*! @brief XSPI AHB Split Size These bits are used to control the split size when split function is enabled
674 * BFGENCR[SPLITEN] is '1'.*/
675 typedef enum _xspi_ahb_split_size
676 {
677 kXSPI_AhbSplitSize8b = 0x0U, /*!< Enable AHB transaction split and split size is 8 bytes. */
678 kXSPI_AhbSplitSize16b = 0x1U, /*!< Enable AHB transaction split and split size is 16 bytes. */
679 kXSPI_AhbSplitSize32b = 0x2U, /*!< Enable AHB transaction split and split size is 32 bytes. */
680 kXSPI_AhbSplitSize64b = 0x3U, /*!< Enable AHB transaction split and split size is 64 bytes. */
681 kXSPI_AhbSplitSizeDisabled = 0xFU, /*!< Disable AHB Transaction Split feature. */
682 } xspi_ahb_split_size_t;
683
684 /*! @brief XSPI AHB access towards flash is broken if this AHB alignment boundary is crossed.
685 This field is only supported XSPI0 XSPI1.*/
686 typedef enum _xspi_ahb_alignment
687 {
688 kXSPI_AhbAlignmentNoLimit = 0x0U, /*!< no limit*/
689 kXSPI_AhbAlignment256BLimit = 0x1U, /*!< 256B limit*/
690 kXSPI_AhbAlignment512BLimit = 0x2U, /*!< 512B limit*/
691 kXSPI_AhbAlignment1KBLimit = 0x3U, /*!< 1KB limit*/
692 } xspi_ahb_alignment_t;
693
694 /*!
695 * @brief The structure of AHB access configurations, including AHB buffer settings, AHB Read Seq ID, AHB write
696 * settings.
697 */
698 typedef struct _xspi_ahb_access_config
699 {
700 xspi_ahbBuffer_config_t buffer[4]; /*!< AHB buffer size. */
701 uint8_t ARDSeqIndex; /*!< Specify the sequence index for AHB read data. */
702
703 bool enableAHBPrefetch; /*!< Enable/disable AHB read prefetch feature, when enabled, XSPI
704 will fetch more data than current AHB burst. */
705 bool enableAHBBufferWriteFlush; /*!< Set true to enable flush of AHB buffer, due to either AHB write or IP
706 access to avoid stable data in AHB buffer. */
707 xspi_ahb_split_size_t ahbSplitSize; /*!< Specify ahb split size, set as kXSPI_AhbSplitSizeDisabled if do not
708 want to use this feature. */
709 xspi_ahb_alignment_t ahbAlignment; /*!< AHB access towards flash is broken if this AHB alignment boundary is
710 crossed, only support XSPI0 XSPI1 */
711
712 xspi_ahb_write_config_t *ptrAhbWriteConfig; /*!< Set as NULL if AHB write feature is not used. */
713 struct
714 {
715 uint32_t highPayload; /*!< High 32bit error payload. */
716 uint32_t lowPayload; /*!< Low 32bit error payload. */
717 } ahbErrorPayload;
718 } xspi_ahb_access_config_t;
719
720 /*!
721 * @brief The structure of information when AHB read error occur.
722 */
723 typedef struct _xspi_ahb_read_error_info
724 {
725 uint32_t errorAddr; /*!< AHB read error address. */
726 uint8_t errMasterId; /*!< AHB read error master Id. */
727 } xspi_ahb_read_error_info_t;
728
729 /*!
730 * @brief The enumeration of AHB request suspend state.
731 */
732 typedef enum _xspi_ahb_request_suspend_state
733 {
734 kXSPI_AhbRequestNoSuspended = 0U, /*!< None of AHB request is suspended. */
735 kXSPI_AhbRequestSuspended, /*!< The AHB request is suspended. */
736 kXSPI_AhbRequestNotApplicable, /*!< The AHB request is not applicable. */
737 kXSPI_AhbReqestResumed, /*!< The AHB request is resumed. */
738 } xspi_ahb_request_suspend_state_t;
739
740 /*!
741 * @brief The structure of information when AHB reqest is suspended.
742 */
743 typedef struct _xspi_ahb_request_suspend_info
744 {
745 xspi_ahb_request_suspend_state_t state; /*!< Current AHB request state. */
746 uint8_t subBufferId; /*!< Suspended AHB request's sub buffer Id. */
747 uint8_t ahbBufferId; /*!< Suspended AHB request's buffer Id. */
748 uint16_t dataLeft; /*!< How many data left to transfer. */
749 uint32_t address; /*!< Current address of suspended AHB request. */
750 } xspi_ahb_request_suspend_info_t;
751
752 /*!
753 * @brief The enumeration of OTFAD prefetch address boundary.
754 */
755 typedef enum _xspi_otfad_prefetch_boundary
756 {
757 kXSPI_OTFADPrefetchNoBoundary = 0U, /*!< No prefetch address boundary. */
758 kXSPI_OTFADPrefetchBoundary1K = 1U, /*!< Prefetch address boundary is 1K. */
759 } xspi_otfad_prefetch_boundary_t;
760 /**************************** AHB Access Control Structures and Enumerations End *********************************/
761
762 /**************************** XSPI Controller Structures and Enumerations Start *********************************/
763
764 /*! @brief Byte ordering endianness. */
765 typedef enum _xspi_byte_order
766 {
767 kXSPI_64BitBE = 0x0U, /*!< 64 bit big endian*/
768 kXSPI_32BitLE = 0x1U, /*!< 32 bit little endian*/
769 kXSPI_32BitBE = 0x2U, /*!< 32 bit big endian*/
770 kXSPI_64BitLE = 0x3U, /*!< 64 bit little endian*/
771 } xspi_byte_order_t;
772
773 /*! @brief XSPI configuration structure. */
774 typedef struct _xspi_config
775 {
776 xspi_byte_order_t byteOrder; /*!< Byte ordering endianness*/
777 bool enableDoze; /*!< Enable/disable doze mode support. */
778 xspi_ahb_access_config_t *ptrAhbAccessConfig; /*!< Pointer to AHB access configuration,
779 can be NULL is AHB access is not used. */
780 xspi_ip_access_config_t *ptrIpAccessConfig; /*!< Pointer to IP access configuration,
781 can be NULL is IP access is not used. */
782 } xspi_config_t;
783 /**************************** XSPI Controller Structures and Enumerations End *********************************/
784
785 /*******************************************************************************
786 * API
787 ******************************************************************************/
788
789 #if defined(__cplusplus)
790 extern "C" {
791 #endif /*_cplusplus. */
792
793 /*!
794 * @name Initialization And Deinitialization Functional Interfaces
795 * @{
796 */
797
798 /*!
799 * @brief Get the instance number for XSPI.
800 *
801 * @param base XSPI base pointer.
802 */
803 uint32_t XSPI_GetInstance(XSPI_Type *base);
804
805 /*!
806 * @brief Check and clear IP command execution errors.
807 *
808 * @param base XSPI base pointer.
809 * @param status interrupt status.
810 */
811 status_t XSPI_CheckAndClearError(XSPI_Type *base, uint32_t status);
812
813 /*!
814 * @brief Initializes the XSPI module and internal state.
815 *
816 * This function configures the XSPI with the
817 * input configure parameters. Users should call this function before any XSPI operations.
818 *
819 * @param base XSPI peripheral base address.
820 * @param ptrConfig XSPI configure structure.
821 */
822 void XSPI_Init(XSPI_Type *base, const xspi_config_t *ptrConfig);
823
824 /*!
825 * @brief Gets default settings for XSPI.
826 *
827 * @warning The parameter \b devconfig will be removed in next release.
828 *
829 * @param base XSPI peripheral base address.
830 * @param ptrConfig XSPI configuration structure.
831 */
832 void XSPI_GetDefaultConfig(xspi_config_t *ptrConfig);
833
834 /*!
835 * @brief Deinitialize the XSPI module.
836 *
837 * Clears the XSPI state and XSPI module registers.
838 * @param base XSPI peripheral base address.
839 * @param devconfig Flash configuration parameters.
840 */
841 void XSPI_Deinit(XSPI_Type *base);
842
843 /*! @brief Updates the LUT table.
844 *
845 * @param base XSPI peripheral base address.
846 * @param index From which index start to update. It could be any index of the LUT table, which
847 * also allows user to update command content inside a command. Each command consists of up to
848 * 10 instructions and occupy 5*32-bit memory.
849 * @param cmd Command sequence array.
850 * @param count Number of instruction-operand pairs
851 */
852 void XSPI_UpdateLUT(XSPI_Type *base, uint8_t index, const uint32_t *cmd, uint8_t count);
853
854 /*!
855 * @brief Set OTFAD prefetch boundary.
856 *
857 * @param base XSPI peripheral base address.
858 * @param boundary Prefetch boundary to set, in type of @ref xspi_otfad_prefetch_boundary_t.
859 */
XSPI_SetOTFADPrefetchBoundary(XSPI_Type * base,xspi_otfad_prefetch_boundary_t boundary)860 static inline void XSPI_SetOTFADPrefetchBoundary(XSPI_Type *base, xspi_otfad_prefetch_boundary_t boundary)
861 {
862 base->SPTRCLR = (base->SPTRCLR & (~XSPI_SPTRCLR_OTFAD_BNDRY_MASK)) | XSPI_SPTRCLR_OTFAD_BNDRY(boundary);
863 }
864 /* @} */
865
866 /*!
867 * @name XSPI Controller Low-Level Inferfaces
868 */
869
XSPI_UpdateByteOrder(XSPI_Type * base,xspi_byte_order_t byteOrder)870 static inline void XSPI_UpdateByteOrder(XSPI_Type *base, xspi_byte_order_t byteOrder)
871 {
872 base->MCR = ((base->MCR) & (~XSPI_MCR_END_CFG_MASK)) | XSPI_MCR_END_CFG(byteOrder);
873 }
874
875 /*!
876 * @brief Enable or disable the XSPI module.
877 *
878 * @param base XSPI peripheral base address.
879 * @param enable true means enable XSPI, false means disable.
880 */
XSPI_EnableModule(XSPI_Type * base,bool enable)881 static inline void XSPI_EnableModule(XSPI_Type *base, bool enable)
882 {
883 if (enable)
884 {
885 base->MCR &= ~XSPI_MCR_MDIS_MASK;
886 }
887 else
888 {
889 base->MCR |= XSPI_MCR_MDIS_MASK;
890 }
891 }
892
893 /*!
894 * @brief Check if the XSPI module is enabled.
895 *
896 * @param base XSPI peripheral base address.
897 *
898 * @retval true XSPI module is enabled.
899 * @retval false XSPI module is disabled.
900 */
XSPI_CheckModuleEnabled(XSPI_Type * base)901 static inline bool XSPI_CheckModuleEnabled(XSPI_Type *base)
902 {
903 return ((base->MCR & XSPI_MCR_MDIS_MASK) == 0UL);
904 }
905
906 /*!
907 * @brief Reset Serial flash memory domain and AHB domain at the same time.
908 *
909 * @note Resetting only the Serial flash memory domain and AHB domain may cause undesirable side effects.
910 *
911 * @param base XSPI peripheral base address.
912 */
913 void XSPI_ResetSfmAndAhbDomain(XSPI_Type *base);
914
915 /*!
916 * @brief Reset IPS target group queue.
917 *
918 * @param base XSPI peripheral base address.
919 */
XSPI_ResetTgQueue(XSPI_Type * base)920 static inline void XSPI_ResetTgQueue(XSPI_Type *base)
921 {
922 base->MCR |= XSPI_MCR_IPS_TG_RST_MASK;
923 }
924
925 /*!
926 * @brief Software reset flash memory domain, AHB domain, and Target group at the same time.
927 *
928 * @param base XSPI peripheral base address.
929 */
XSPI_SoftwareReset(XSPI_Type * base)930 static inline void XSPI_SoftwareReset(XSPI_Type *base)
931 {
932 XSPI_ResetTgQueue(base);
933 XSPI_ResetSfmAndAhbDomain(base);
934 }
935
936 /*!
937 * @brief Check if write access to registers(MGC, MRC, MTO, SFP_ARB_TIMEOUT, SFP_LUT_ENn, LUTn, BFGENCR) is locked.
938 *
939 * @param base XSPI peripheral base address.
940 *
941 * @retval false Write access to listed registers is not locked.
942 * @retval true Write access to listed registers is locked.
943 */
XSPI_CheckGlobalConfigLocked(XSPI_Type * base)944 static inline bool XSPI_CheckGlobalConfigLocked(XSPI_Type *base)
945 {
946 return (bool)((base->MGC & XSPI_MGC_GCLCK_MASK) != 0UL);
947 }
948 /* @} */
949
950 /*!
951 * @name External Device Control Low-Level Interfaces
952 * @{
953 */
954
955 /*!
956 * @brief Set Hyper bus X16 mode.
957 *
958 * @param base XSPI peripheral base address.
959 * @param x16Mode Specify X16 mode.
960 */
961 void XSPI_SetHyperBusX16Mode(XSPI_Type *base, xspi_hyper_bus_x16_mode_t x16Mode);
962
963 /*!
964 * @brief Update address mode to access external device.
965 *
966 * @param base XSPI peripheral base address.
967 * @param addrMode Specify the address mode to update.
968 *
969 * @retval kStatus_XSPI_AhbReadAccessAsserted Fail to update address mode due to AHB read access asserted.
970 * @retval kStatus_XSPI_IPAccessAsserted Fail to update address mode due to a IP access already asserted.
971 * @retval kStatus_XSPI_AhbWriteAccessAsserted Fail to update address mode due to AHB write access asserted.
972 * @retval kStatus_Success Successfully to update address mode.
973 */
974 status_t XSPI_UpdateDeviceAddrMode(XSPI_Type *base, xspi_device_addr_mode_t addrMode);
975
976 /*!
977 * @brief Enable/disable variable latency for XSPI.
978 *
979 * @note Only useful for hyper bus device.
980 * @note It is application responsibility to enable variable latency for external hyper bus
981 * device(by change device's register).
982 *
983 * @param base XSPI peripheral base address.
984 * @param enable Specify operation:
985 - \b true Enable variable latency;
986 - \b false Disable variable latency.
987 */
XSPI_EnableVariableLatency(XSPI_Type * base,bool enable)988 static inline void XSPI_EnableVariableLatency(XSPI_Type *base, bool enable)
989 {
990 if (enable)
991 {
992 base->MCR |= XSPI_MCR_VAR_LAT_EN_MASK;
993 }
994 else
995 {
996 base->MCR &= ~XSPI_MCR_VAR_LAT_EN_MASK;
997 }
998 }
999
1000 /*!
1001 * @brief Enable/disable Doze mode for XSPI controller.
1002 *
1003 * @note Once doze mode is enabled, the XSPI controller will enter disable mode when system in low power modes.
1004 *
1005 * @param base XSPI peripheral base address
1006 * @param enable Specify operation:
1007 * - \b true Enable Doze mode;
1008 * - \b false Disable Doze mode.
1009 */
XSPI_EnableDozeMode(XSPI_Type * base,bool enable)1010 static inline void XSPI_EnableDozeMode(XSPI_Type *base, bool enable)
1011 {
1012 if (enable)
1013 {
1014 base->MCR |= XSPI_MCR_DOZE_MASK;
1015 }
1016 else
1017 {
1018 base->MCR &= ~XSPI_MCR_DOZE_MASK;
1019 }
1020 }
1021
1022 /*!
1023 * @brief Specify the logic level of the XSPI IOFA[3] and IOFA[2] output in the inactive state.
1024 *
1025 * @param base XSPI peripheral base address
1026 * @param signalMask Should be the OR'ed value of _xspi_external_signal.
1027 * @param outputLogic Output logic of selected signals,
1028 * - \b false Output logic 0;
1029 * - \b true Output logic 1.
1030 */
XSPI_SetSignalOutputValue(XSPI_Type * base,uint32_t signalMask,bool outputLogic)1031 static inline void XSPI_SetSignalOutputValue(XSPI_Type *base, uint32_t signalMask, bool outputLogic)
1032 {
1033 bool moduleEnabled = false;
1034
1035 if (XSPI_CheckModuleEnabled(base))
1036 {
1037 moduleEnabled = true;
1038 XSPI_EnableModule(base, false);
1039 }
1040
1041 if (outputLogic)
1042 {
1043 /* Output logic High for input mask of signals. */
1044 base->MCR |= signalMask;
1045 }
1046 else
1047 {
1048 /* Output logic Low for input mask of signals. */
1049 base->MCR &= ~signalMask;
1050 }
1051
1052 if (moduleEnabled)
1053 {
1054 XSPI_EnableModule(base, true);
1055 }
1056 }
1057
1058 /*!
1059 * @brief Enable/disable inverted serial clock output for XSPI controller.
1060 *
1061 * @note It is application responsibility to enable CLKn for external device(by change device's register).
1062 *
1063 * @param[in] base XSPI peripheral base address
1064 * @param[in] enable Enable/disable inverted serial clock output:
1065 * - \b true Enable inverted serial clock output;
1066 * - \b false Disable inverted serial clock output.
1067 */
XSPI_EnableInvertedSerialClockOutput(XSPI_Type * base,bool enable)1068 static inline void XSPI_EnableInvertedSerialClockOutput(XSPI_Type *base, bool enable)
1069 {
1070 bool moduleEnabled = false;
1071
1072 if (XSPI_CheckModuleEnabled(base))
1073 {
1074 moduleEnabled = true;
1075 XSPI_EnableModule(base, false);
1076 }
1077
1078 if (enable)
1079 {
1080 base->MCR |= XSPI_MCR_CKN_FA_EN_MASK;
1081 }
1082 else
1083 {
1084 base->MCR &= ~XSPI_MCR_CKN_FA_EN_MASK;
1085 }
1086
1087 if (moduleEnabled)
1088 {
1089 XSPI_EnableModule(base, true);
1090 }
1091 }
1092
1093 /*!
1094 * @brief Update DLL configuration.
1095 *
1096 * @param[in] base XSPI peripheral base address.
1097 * @param[in] ptrDllConfig Pointer to the DLL configuration.
1098 * @param[in] enableDDR DDR mode is enabled or not.
1099 * @param[in] enableX16Mode X16 mode is enabled or not.
1100 * @param[in] xspiRootClk The frequency of xspi root clock, the unit is Hz.
1101 */
1102 void XSPI_UpdateDllValue( XSPI_Type *base, xspi_dll_config_t *ptrDllConfig,
1103 bool enableDDR, bool enableX16Mode, uint32_t xspiRootClk);
1104
1105 /*!
1106 * @brief Set Data learning configurations.
1107 *
1108 * @param[in] base XSPI peripheral base address.
1109 * @param[in] ptrDataLearningConfig Pointer to data learning configuration.
1110 *
1111 * @retval kStatus_XSPI_AhbReadAccessAsserted Fail to set data learning configuration due to AHB read access asserted.
1112 * @retval kStatus_XSPI_IPAccessAsserted Fail to set data learning configuration due to a IP access already asserted.
1113 * @retval kStatus_XSPI_AhbWriteAccessAsserted Fail to set data learning configuration due to AHB write access asserted.
1114 * @retval kStatus_Success Successfully to set Data learning configurations.
1115 */
1116 status_t XSPI_SetDataLearningConfig(XSPI_Type *base, xspi_data_learning_config_t *ptrDataLearningConfig);
1117
1118 /*!
1119 * @brief Check if data learning failure has detected.
1120 *
1121 * @param[in] base XSPI peripheral base address.
1122 *
1123 * @retval true Data learning has failed.
1124 * @retval false Data learning not fail.
1125 */
XSPI_CheckDataLearningFailure(XSPI_Type * base)1126 static inline bool XSPI_CheckDataLearningFailure(XSPI_Type *base)
1127 {
1128 return (bool)((base->DLSR_F[0] & XSPI_DLSR_F_DLPFF_MASK) == XSPI_DLSR_F_DLPFF_MASK);
1129 }
1130
1131 /*!
1132 * @brief Get data learning positive and negative edge match signature.
1133 *
1134 * @param[in] base XSPI peripheral base address.
1135 * @param[out] posEdgeMatch Pointer to the memory to store positive edge match signature.
1136 * @param[out] negEdgeMatch Pointer to the memory to store negative edge match signature.
1137 */
XSPI_GetDataLearningEdgeMatchSignature(XSPI_Type * base,uint8_t * posEdgeMatch,uint8_t * negEdgeMatch)1138 static inline void XSPI_GetDataLearningEdgeMatchSignature(XSPI_Type *base, uint8_t *posEdgeMatch, uint8_t *negEdgeMatch)
1139 {
1140 uint32_t tmp32 = base->DLSR_F[0];
1141
1142 *negEdgeMatch = (uint8_t)((tmp32 & XSPI_DLSR_F_NEG_EDGE_MASK) >> XSPI_DLSR_F_NEG_EDGE_SHIFT);
1143 *posEdgeMatch = (uint8_t)((tmp32 & XSPI_DLSR_F_POS_EDGE_MASK) >> XSPI_DLSR_F_POS_EDGE_SHIFT);
1144 }
1145 /* @} */
1146
1147 /*!
1148 * @name External Device Control Functional Interfaces
1149 */
1150
1151 /*!
1152 * @brief Set device configuration.
1153 *
1154 * @param[in] base XSPI peripheral base address.
1155 * @param[in] devConfig Pointer to device configuration.
1156 *
1157 * @retval kStatus_XSPI_AhbReadAccessAsserted Fail to set device configuration due to AHB read access asserted.
1158 * @retval kStatus_XSPI_IPAccessAsserted Fail to set device configuration due to a IP access already asserted.
1159 * @retval kStatus_XSPI_AhbWriteAccessAsserted Fail to set device configuration due to AHB write access asserted.
1160 * @retval kStatus_Success Successfully to set device configurations.
1161 */
1162 status_t XSPI_SetDeviceConfig(XSPI_Type *base, xspi_device_config_t *devConfig);
1163
1164 /* @} */
1165
1166 /*!
1167 * @name Interrupts
1168 * @{
1169 */
1170
1171 /*!
1172 * @brief Enables the XSPI interrupts.
1173 *
1174 * @param base XSPI peripheral base address.
1175 * @param mask XSPI interrupt source.
1176 */
1177
XSPI_EnableInterrupts(XSPI_Type * base,uint32_t mask)1178 static inline void XSPI_EnableInterrupts(XSPI_Type *base, uint32_t mask)
1179 {
1180 base->RSER |= mask;
1181 }
1182
1183 /*!
1184 * @brief Disable the XSPI interrupts.
1185 *
1186 * @param base XSPI peripheral base address.
1187 * @param mask XSPI interrupt source.
1188 */
XSPI_DisableInterrupts(XSPI_Type * base,uint32_t mask)1189 static inline void XSPI_DisableInterrupts(XSPI_Type *base, uint32_t mask)
1190 {
1191 base->RSER &= ~mask;
1192 }
1193
1194 /* @} */
1195
1196 /*! @name DMA control */
1197 /*@{*/
1198
1199 /*!
1200 * @brief Enables or disables XSPI IP Tx FIFO DMA requests.
1201 *
1202 * @param[in] base XSPI peripheral base address.
1203 * @param[in] enable Enable flag for transmit DMA request. Pass true for enable, false for disable.
1204 */
XSPI_EnableTxDMA(XSPI_Type * base,bool enable)1205 static inline void XSPI_EnableTxDMA(XSPI_Type *base, bool enable)
1206 {
1207 if (enable)
1208 {
1209 base->RSER |= XSPI_RSER_TBFDE_MASK;
1210 }
1211 else
1212 {
1213 base->RSER &= ~XSPI_RSER_TBFDE_MASK;
1214 }
1215 }
1216
1217 /*!
1218 * @brief Enables or disables XSPI IP Rx FIFO DMA requests.
1219 *
1220 * @param[in] base XSPI peripheral base address.
1221 * @param[in] enable Enable flag for receive DMA request. Pass true for enable, false for disable.
1222 */
XSPI_EnableRxDMA(XSPI_Type * base,bool enable)1223 static inline void XSPI_EnableRxDMA(XSPI_Type *base, bool enable)
1224 {
1225 if (enable)
1226 {
1227 base->RSER |= XSPI_RSER_RBDDE_MASK;
1228 }
1229 else
1230 {
1231 base->RSER &= ~XSPI_RSER_RBDDE_MASK;
1232 }
1233 }
1234
1235 /*!
1236 * @brief Gets XSPI IP tx fifo address for DMA transfer.
1237 *
1238 * @param[in] base XSPI peripheral base address.
1239 *
1240 * @return The tx fifo address.
1241 */
XSPI_GetTxFifoAddress(XSPI_Type * base)1242 static inline uint32_t XSPI_GetTxFifoAddress(XSPI_Type *base)
1243 {
1244 return (uint32_t)&base->TBDR;
1245 }
1246
1247 /*!
1248 * @brief Gets XSPI IP rx fifo address for DMA transfer.
1249 *
1250 * @param[in] base XSPI peripheral base address.
1251 *
1252 * @return The rx fifo address.
1253 */
XSPI_GetRxFifoAddress(XSPI_Type * base)1254 static inline uint32_t XSPI_GetRxFifoAddress(XSPI_Type *base)
1255 {
1256 return (uint32_t)&base->RBDR[0];
1257 }
1258
1259 /*@}*/
1260
1261 /*!
1262 * @name Status
1263 * @{
1264 */
1265 /*!
1266 * @brief Get the XSPI interrupt status flags.
1267 *
1268 * @param[in] base XSPI peripheral base address.
1269 *
1270 * @return interrupt status flag, use status flag to AND #xspi_flags_t could get the related status.
1271 */
XSPI_GetInterruptStatusFlags(XSPI_Type * base)1272 static inline uint32_t XSPI_GetInterruptStatusFlags(XSPI_Type *base)
1273 {
1274 return base->ERRSTAT;
1275 }
1276
1277 /*! @brief Return whether the bus is idle.
1278 *
1279 * @param[in] base XSPI peripheral base address.
1280 *
1281 * @retval true Bus is idle.
1282 * @retval false Bus is busy.
1283 */
XSPI_GetBusIdleStatus(XSPI_Type * base)1284 static inline bool XSPI_GetBusIdleStatus(XSPI_Type *base)
1285 {
1286 return (bool)(XSPI_SR_BUSY_MASK != (base->SR & XSPI_SR_BUSY_MASK));
1287 }
1288
1289 /*!
1290 * @brief Check if AHB read access has been requested or is ongoing.
1291 *
1292 * @param[in] base XSPI peripheral base address.
1293 *
1294 * @retval true AHB read access is requested or is ongoing.
1295 * @retval false AHB read access is not requested and is not ongoing.
1296 */
XSPI_CheckAhbReadAccessAsserted(XSPI_Type * base)1297 static inline bool XSPI_CheckAhbReadAccessAsserted(XSPI_Type *base)
1298 {
1299 return (bool)((base->SR & XSPI_SR_AHB_ACC_MASK) != 0UL);
1300 }
1301
1302 /*!
1303 * @brief Check if AHB write access has been requested or is ongoing.
1304 *
1305 * @param[in] base XSPI peripheral base address.
1306 *
1307 * @retval true AHB read access is requested or is ongoing.
1308 * @retval false AHB read access is not requested and is not ongoing.
1309 */
XSPI_CheckAhbWriteAccessAsserted(XSPI_Type * base)1310 static inline bool XSPI_CheckAhbWriteAccessAsserted(XSPI_Type *base)
1311 {
1312 return (bool)((base->SR & XSPI_SR_AWRACC_MASK) != 0UL);
1313 }
1314
1315 /*@}*/
1316
1317 /*!
1318 * @name IPS Access Control Low-Level Interfaces
1319 * @{
1320 */
1321
1322 /*! @brief Clear the XSPI IP TX/RX buffer logic.
1323 *
1324 * @param[in] base XSPI peripheral base address.
1325 * @param[in] txFifo Pass true to reset TX FIFO.
1326 * @param[in] rxFifo Pass true to reset RX FIFO.
1327 */
XSPI_ResetTxRxBuffer(XSPI_Type * base,bool txFifo,bool rxFifo)1328 static inline void XSPI_ResetTxRxBuffer(XSPI_Type *base, bool txFifo, bool rxFifo)
1329 {
1330 if (txFifo)
1331 {
1332 base->MCR |= XSPI_MCR_CLR_TXF_MASK;
1333 }
1334 if (rxFifo)
1335 {
1336 base->MCR |= XSPI_MCR_CLR_RXF_MASK;
1337 }
1338 }
1339
1340 /*!
1341 * @brief Clear TX buffer.
1342 *
1343 * @param[in] base XSPI peripheral base address.
1344 */
XSPI_ClearTxBuffer(XSPI_Type * base)1345 static inline void XSPI_ClearTxBuffer(XSPI_Type *base)
1346 {
1347 base->MCR |= XSPI_MCR_CLR_TXF_MASK;
1348
1349 for (uint8_t i = 0U; i < 10U; i++)
1350 {
1351 __NOP();
1352 }
1353 }
1354
1355 /*!
1356 * @brief Update watermark for TX buffer.
1357 *
1358 * @param[in] base XSPI peripheral base address.
1359 * @param[in] waterMark The watermark to set, the unit is byte, should be the multiple of 4 byte.
1360 *
1361 * @retval kStatus_XSPI_IPAccessAsserted Fail to update watermark for Tx buffer, due to IP access is asserted.
1362 * @retval kStatus_XSPI_WaterMarkIllegal Fail to update watermark for Tx buffer, due to input watermark is not the
1363 * multiple of 4 bytes.
1364 * @retval kStatus_Success Successful to update watermark.
1365 */
1366 status_t XSPI_UpdateTxBufferWaterMark(XSPI_Type *base, uint32_t waterMark);
1367
1368 /*!
1369 * @brief Check if IP manager can write to TX buffer.
1370 *
1371 * @param[in] base XSPI peripheral base address.
1372 *
1373 * @retval true Tx buffer lock is open.
1374 * @retval false Tx buffer lock is not open.
1375 */
XSPI_CheckTxBuffLockOpen(XSPI_Type * base)1376 static inline bool XSPI_CheckTxBuffLockOpen(XSPI_Type *base)
1377 {
1378 return (bool)((base->FSMSTAT & XSPI_FSMSTAT_STATE_MASK) == XSPI_FSMSTAT_STATE(1UL));
1379 }
1380
1381 /*!
1382 * @brief Writes data into IPS TX Buffer.
1383 *
1384 * @param[in] base XSPI peripheral base address
1385 * @param[in] data The data bytes to send.
1386 */
XSPI_WriteTxBuffer(XSPI_Type * base,uint32_t data)1387 static inline void XSPI_WriteTxBuffer(XSPI_Type *base, uint32_t data)
1388 {
1389 base->TBDR = data;
1390 }
1391
1392 /*!
1393 * @brief Clear RX buffer.
1394 *
1395 * @param[in] base XSPI peripheral base address.
1396 */
XSPI_ClearRxBuffer(XSPI_Type * base)1397 static inline void XSPI_ClearRxBuffer(XSPI_Type *base)
1398 {
1399 base->MCR |= XSPI_MCR_CLR_RXF_MASK;
1400
1401 for (uint8_t i = 0U; i < 10U; i++)
1402 {
1403 __NOP();
1404 }
1405 }
1406
1407 /*!
1408 * @brief Receive data from IPX RX FIFO.
1409 *
1410 * @param[in] base XSPI peripheral base address
1411 * @param[in] fifoIndex Source fifo index.
1412 *
1413 * @return The data in the FIFO.
1414 */
XSPI_ReadRxBuffer(XSPI_Type * base,uint8_t fifoIndex)1415 static inline uint32_t XSPI_ReadRxBuffer(XSPI_Type *base, uint8_t fifoIndex)
1416 {
1417 return base->RBDR[fifoIndex];
1418 }
1419
1420 /*!
1421 * @brief Trigger a pop event for RX buffer pop event.
1422 *
1423 * @note Each pop event discard watermark + 1 enties from RX buffer.
1424 *
1425 * @param[in] base XSPI peripheral base address.
1426 */
XSPI_TriggerRxBufferPopEvent(XSPI_Type * base)1427 static inline void XSPI_TriggerRxBufferPopEvent(XSPI_Type *base)
1428 {
1429 base->FR = XSPI_FR_RBDF_MASK;
1430 }
1431
1432 /*!
1433 * @brief Update watermark for RX buffer.
1434 *
1435 * @code
1436 * Set watermark as 4 bytes:
1437 * XSPI_UpdateRxBufferWaterMark(XSPI0, 4UL);
1438 * Set watermark as 8 bytes:
1439 * XSPI_UpdateRxBufferWaterMark(XSPI0, 8UL);
1440 * @endcode
1441 *
1442 *
1443 * @param[in] base XSPI peripheral base address.
1444 * @param[in] waterMark Specify the number of bytes in the RX buffer which causes XSPI to assert the watermark exceeded
1445 * flag, should be in multiple of 4 bytes.
1446 *
1447 * @retval kStatus_XSPI_IPAccessAsserted Fail to update watermark for Rx buffer, due to IP access is asserted.
1448 * @retval kStatus_XSPI_WaterMarkIllegal Fail to update watermark for Tx buffer, due to input watermark is not the
1449 * multiple of 4 bytes.
1450 * @retval kStatus_Success Successful to update watermark.
1451 */
1452 status_t XSPI_UpdateRxBufferWaterMark(XSPI_Type *base, uint32_t waterMark);
1453
1454 /*!
1455 * @brief Check if RX buffer watermark is exceed.
1456 *
1457 * @param[in] base XSPI peripheral base address.
1458 *
1459 * @retval true The RX buffer watermark has been excceded.
1460 * @retval false The RX buffer watermark has not been exceeded.
1461 */
XSPI_CheckRxBufferWaterMarkExceed(XSPI_Type * base)1462 static inline bool XSPI_CheckRxBufferWaterMarkExceed(XSPI_Type *base)
1463 {
1464 return (bool)((base->FR & XSPI_FR_RBDF_MASK) == XSPI_FR_RBDF_MASK);
1465 }
1466
1467 /*!
1468 * @brief Get RX buffer aviailable bytes count.
1469 *
1470 * @param[in] base XSPI peripheral base address.
1471 *
1472 * @return The available counts if bytes in RX buffer.
1473 */
XSPI_GetRxBufferAvailableBytesCount(XSPI_Type * base)1474 static inline uint32_t XSPI_GetRxBufferAvailableBytesCount(XSPI_Type *base)
1475 {
1476 return ((base->RBSR & XSPI_RBSR_RDBFL_MASK) >> XSPI_RBSR_RDBFL_SHIFT) * 4UL;
1477 }
1478
1479 /*!
1480 * @brief Get counts of bytes already removed from RX buffer.
1481 *
1482 * @param[in] base XSPI peripheral base address.
1483 *
1484 * @return Counts of removed bytes.
1485 */
XSPI_GetRxBufferRemovedBytesCount(XSPI_Type * base)1486 static inline uint32_t XSPI_GetRxBufferRemovedBytesCount(XSPI_Type *base)
1487 {
1488 return ((base->RBSR & XSPI_RBSR_RDCTR_MASK) >> XSPI_RBSR_RDCTR_SHIFT) * 4UL;
1489 }
1490
1491 /*!
1492 * @brief Set exclusive access lock mode for the specific frad..
1493 *
1494 * @param[in] base XSPI peripheral base address.
1495 * @param[in] ealMode Specify the exclusive access lock mode.
1496 * @param[in] fradId Specify the frad.
1497 */
1498 void XSPI_SetSFPFradEALMode(XSPI_Type *base, xspi_exclusive_access_lock_mode_t ealMode, uint8_t fradId);
1499
1500 /*!
1501 * @brief Update SFP configurations, including MDAD configurations and FRAD configurations.
1502 *
1503 * @param[in] base XSPI peripheral base address.
1504 * @param[in] ptrMdadConfig Pointer to the SFP MDAD configuration.
1505 * @param[in] ptrFradConfig Pointer to the SFP FRAD configuration.
1506 */
1507 void XSPI_UpdateSFPConfig(XSPI_Type *base,
1508 xspi_sfp_mdad_config_t *ptrSfpMdadConfig,
1509 xspi_sfp_frad_config_t *ptrSfpFradConfig);
1510
1511 /*!
1512 * @brief Check if SFP FRAD check is enabled for IP write access.
1513 *
1514 * @param[in] base XSPI peripheral base address.
1515 *
1516 * @retval false SFP FRAD check is disabled.
1517 * @retval true SFP FRAD check is enabled for IP write access.
1518 */
XSPI_CheckSFPFradEnabled(XSPI_Type * base)1519 static inline bool XSPI_CheckSFPFradEnabled(XSPI_Type *base)
1520 {
1521 return (bool)((base->MGC & XSPI_MGC_GVLDFRAD_MASK) != 0UL);
1522 }
1523
1524 /*!
1525 * @brief Get MDAD check error reason for specific target group.
1526 *
1527 * @param[in] base XSPI peripheral base address.
1528 * @param[in] tgId Specify the target group.
1529 *
1530 * @return The details of MDAD error reason, in type of @ref xspi_mdad_error_reason_t.
1531 */
1532 xspi_mdad_error_reason_t XSPI_GetMdadErrorReason(XSPI_Type *base, xspi_target_group_t tgId);
1533
1534 /*!
1535 * @brief Get FARD latest transaction information.
1536 *
1537 * @param[in] base XSPI peripheral base address.
1538 * @param[out] ptrInfo Pointer to the variable in type of @ref xspi_frad_transaction_info_t to store information.
1539 * @param[in] fradId Specify the frad Id.
1540 */
1541 void XSPI_GetFradLastTransactionsInfo(XSPI_Type *base, xspi_frad_transaction_info_t *ptrInfo, uint8_t fradId);
1542
1543 /*!
1544 * @brief Update SFP arbitration lock timeout counter.
1545 *
1546 * @note The SFP arbitration lock time out counter starts when Page program wait flag asserted.
1547 *
1548 * @param[in] base XSPI peripheral base address.
1549 * @param[in] countValue The count value, specify the time in IPS clock cycles.
1550 *
1551 * @retval kStatus_XSPI_RegWriteLocked Write operation to related register is locked.
1552 * @retval kStatus_Success Success to update timeout counter.
1553 */
1554 status_t XSPI_UpdateSFPArbitrationLockTimeoutCounter(XSPI_Type *base, uint32_t countValue);
1555
1556 /*!
1557 * @brief Clear address write status for specific target group.
1558 *
1559 * @param[in] base XSPI peripheral base address.
1560 * @param[in] tgId Specify the target group to clear address write status.
1561 */
1562 void XSPI_ClearTgAddrWriteStatus(XSPI_Type *base, xspi_target_group_t tgId);
1563
1564 /*!
1565 * @brief Get address write status for specific target group.
1566 *
1567 * @param[in] base XSPI peripheral base address.
1568 * @param[in] tgId Specify the target group.
1569 * @param[out] ptrStatus Pointer to the variable in type of @ref xspi_tg_add_write_status_t
1570 to store address write status.
1571 */
1572 void XSPI_GetTgAddrWriteStatus(XSPI_Type *base, xspi_target_group_t tgId, xspi_tg_add_write_status_t *ptrStatus);
1573
1574 /*!
1575 * @brief Unlock Ip access arbitration.
1576 *
1577 * @param[in] base XSPI peripheral base address.
1578 * @param[in] tgId Specify the target group.
1579 */
1580 void XSPI_UnlockIpAccessArbitration(XSPI_Type *base, xspi_target_group_t tgId);
1581
1582 /*!
1583 * @brief Check if IP access is asserted.
1584 *
1585 * @param[in] base XSPI peripheral base address.
1586 *
1587 * @retval false The Access triggered by IP bus is not asserted.
1588 * @retval true The Access triggered by IP bus is asserted.
1589 */
XSPI_CheckIPAccessAsserted(XSPI_Type * base)1590 static inline bool XSPI_CheckIPAccessAsserted(XSPI_Type *base)
1591 {
1592 return (bool)((base->SR & XSPI_SR_IP_ACC_MASK) != 0UL);
1593 }
1594
1595 /*!
1596 * @brief Clear Ip access sequence pointer.
1597 *
1598 * @param[in] base XSPI peripheral base address.
1599 */
XSPI_ClearIPAccessSeqPointer(XSPI_Type * base)1600 static inline void XSPI_ClearIPAccessSeqPointer(XSPI_Type *base)
1601 {
1602 base->SPTRCLR |= XSPI_SPTRCLR_IPPTRC_MASK;
1603 }
1604
1605 /*!
1606 * @brief Update the count of SFP access timeout counter.
1607 *
1608 * @note The counter starts when any IP access pass SFP check(if enabled), and request is granted by XSPI arbiter and
1609 * XSPI is IDLE.
1610 *
1611 * @note The counter does not start in case of IP access was granted by XSPI is not IDLE.
1612 *
1613 * @param base XSPI peripheral base address.
1614 * @param countValue The count value, specify the time in IPS clock cycles.
1615 *
1616 * @retval kStatus_XSPI_RegWriteLocked Write operation to related register is locked.
1617 * @retval kStatus_Success Success to update timeout counter.
1618 */
1619 status_t XSPI_UpdateIPAccessTimeoutCounter(XSPI_Type *base, uint32_t countValue);
1620
1621 /*!
1622 * @brief Check if IP access is granted by XSPI arbitration.
1623 *
1624 * @param base XSPI peripheral base address.
1625 *
1626 * @retval true The IP access is granted arbitration.
1627 * @retval false No IP access is queued.
1628 */
XSPI_CheckIPAccessGranted(XSPI_Type * base)1629 static inline bool XSPI_CheckIPAccessGranted(XSPI_Type *base)
1630 {
1631 return (bool)((base->FSMSTAT & XSPI_FSMSTAT_VLD_MASK) != 0UL);
1632 }
1633
1634 /*!
1635 * @brief Check if IP write access is triggered.
1636 *
1637 * @param[in] base XSPI peripheral base address.
1638 *
1639 * @retval true The IP write access is granted arbitration.
1640 * @retval false No IP write access is queued.
1641 */
XSPI_CheckIpWriteTriggered(XSPI_Type * base)1642 static inline bool XSPI_CheckIpWriteTriggered(XSPI_Type *base)
1643 {
1644 return (bool)((base->FSMSTAT & XSPI_FSMSTAT_STATE_MASK) == XSPI_FSMSTAT_STATE(2U));
1645 }
1646
1647 /*!
1648 * @brief Check if IP read access is triggered.
1649 *
1650 * @param[in] base XSPI peripheral base address.
1651 *
1652 * @retval true The IP read access is granted arbitration.
1653 * @retval false No IP read access is queued.
1654 */
XSPI_CheckIpReadTriggered(XSPI_Type * base)1655 static inline bool XSPI_CheckIpReadTriggered(XSPI_Type *base)
1656 {
1657 return (bool)((base->FSMSTAT & XSPI_FSMSTAT_STATE_MASK) == XSPI_FSMSTAT_STATE(3U));
1658 }
1659
1660 /*!
1661 * @brief Start IP access(including read and write).
1662 *
1663 * @param[in] base XSPI peripheral base address.
1664 * @param[in] addr Address of external device to read/write.
1665 * @param[in] seqIndex Sequence Id of the pre-programed LUT.
1666 * @param[in] byteSize Size of data to read/write, the unit of byte.
1667 * @param[in] tgId Specify the target group used to write/read.
1668 * @param[in] lockArbitration Lock arbitration or not.
1669 *
1670 * @retval kStatus_XSPI_IpAccessAddrSettingInvalid Wrong Address input.
1671 * @retval kStatus_XSPI_IpAccessIPCRInvalid Wrong seqindex or bytesize input.
1672 * @retval kStatus_Success Success to start Ip access.
1673 */
1674 status_t XSPI_StartIpAccess(XSPI_Type *base, uint32_t addr, uint8_t seqIndex,
1675 size_t byteSize, xspi_target_group_t tgId, bool lockArbitration);
1676
1677 /* @} */
1678
1679 /*!
1680 * @name IPS Access Control Functional Interfaces
1681 * @{
1682 */
1683
1684 /*!
1685 * @brief Set IP access configurations, including SFP configurations, sfp arbitration lock timeout value, Ip access
1686 * timeout value.
1687 *
1688 * @param[in] base XSPI peripheral base address.
1689 * @param[in] ptrIpAccessConfig Pointer to the variable which contains Ip access configurations.
1690 *
1691 * @retval kStatus_XSPI_RegWriteLocked Write operation to related register is locked.
1692 * @retval kStatus_Success Success to update timeout counter.
1693 */
1694 status_t XSPI_SetIpAccessConfig(XSPI_Type *base, xspi_ip_access_config_t *ptrIpAccessConfig);
1695
1696 /*!
1697 * @brief Sends a buffer of data bytes using blocking method.
1698 *
1699 * @note This function blocks via polling until all bytes have been sent.
1700 *
1701 * @param[in] base XSPI peripheral base address
1702 * @param[in] buffer Pointer to the buffer to send.
1703 * @param[in] size The number of data bytes to send
1704 *
1705 * @retval kStatus_Success write success without error
1706 * @retval kStatus_XSPI_SequenceExecutionTimeout sequence execution timeout
1707 * @retval kStatus_XSPI_IpCommandSequenceError IP command sequence error detected
1708 * @retval kStatus_XSPI_IpCommandGrantTimeout IP command grant timeout detected
1709 */
1710 status_t XSPI_WriteBlocking(XSPI_Type *base, uint8_t *buffer, size_t size);
1711
1712 /*!
1713 * @brief Receives a buffer of data bytes using a blocking method.
1714 *
1715 * @note This function blocks via polling until all bytes have been sent.
1716 *
1717 * @param[in] base XSPI peripheral base address
1718 * @param[out] buffer Pointer to the buffer to store read data.
1719 * @param[in] size The number of data bytes to receive
1720 *
1721 * @retval kStatus_Success read success without error
1722 * @retval kStatus_XSPI_SequenceExecutionTimeout sequence execution timeout
1723 * @retval kStatus_XSPI_IpCommandSequenceError IP command sequence error detected
1724 * @retval kStatus_XSPI_IpCommandGrantTimeout IP command grant timeout detected
1725 */
1726 status_t XSPI_ReadBlocking(XSPI_Type *base, uint8_t *buffer, size_t size);
1727
1728 /*!
1729 * @brief Execute command to transfer a buffer data bytes using a blocking method.
1730 *
1731 * @param[in] base XSPI peripheral base address
1732 * @param[in] xfer pointer to the transfer structure.
1733 *
1734 * @retval kStatus_Success command transfer success without error
1735 * @retval kStatus_XSPI_SequenceExecutionTimeout sequence execution timeout
1736 * @retval kStatus_XSPI_IpCommandSequenceError IP command sequence error detected
1737 * @retval kStatus_XSPI_IpCommandGrantTimeout IP command grant timeout detected
1738 */
1739 status_t XSPI_TransferBlocking(XSPI_Type *base, xspi_transfer_t *xfer);
1740
1741 /*!
1742 * @brief Initialize the XSPI handle which is used in transactional functions.
1743 *
1744 * @param[in] base XSPI peripheral base address.
1745 * @param[in] handle pointer to xspi_handle_t structure to store the transfer state.
1746 * @param[in] callback pointer to user callback function.
1747 * @param[in] userData user parameter passed to the callback function.
1748 */
1749 void XSPI_TransferCreateHandle(XSPI_Type *base,
1750 xspi_handle_t *handle,
1751 xspi_transfer_callback_t callback,
1752 void *userData);
1753
1754 /*!
1755 * @brief Perform a interrupt non-blocking transfer on the XSPI bus.
1756 *
1757 * @note Calling the API returns immediately after transfer initiates. The user needs
1758 * to call XSPI_GetTransferCount to poll the transfer status to check whether
1759 * the transfer is finished. If the return status is not kStatus_XSPI_Busy, the transfer
1760 * is finished. For XSPI_Read, the dataSize should be multiple of rx watermark level, or
1761 * XSPI could not read data properly.
1762 *
1763 * @param[in] base XSPI peripheral base address.
1764 * @param[in] handle pointer to xspi_handle_t structure which stores the transfer state.
1765 * @param[in] xfer pointer to xspi_transfer_t structure.
1766 *
1767 * @retval kStatus_Success Successfully start the data transmission.
1768 * @retval kStatus_XSPI_Busy Previous transmission still not finished.
1769 */
1770 status_t XSPI_TransferNonBlocking(XSPI_Type *base, xspi_handle_t *handle, xspi_transfer_t *xfer);
1771
1772 /*!
1773 * @brief Get the master transfer status during a interrupt non-blocking transfer.
1774 *
1775 * @param[in] base XSPI peripheral base address.
1776 * @param[in] handle pointer to xspi_handle_t structure which stores the transfer state.
1777 * @param[out] count Number of bytes transferred so far by the non-blocking transaction.
1778 *
1779 * @retval kStatus_InvalidArgument count is Invalid.
1780 * @retval kStatus_Success Successfully return the count.
1781 */
1782 status_t XSPI_TransferGetCount(XSPI_Type *base, xspi_handle_t *handle, size_t *count);
1783
1784 /*!
1785 * @brief Abort an interrupt non-blocking transfer early.
1786 *
1787 * @note This API can be called at any time when an interrupt non-blocking transfer initiates
1788 * to abort the transfer early.
1789 *
1790 * @param[in] base XSPI peripheral base address.
1791 * @param[in] handle pointer to xspi_handle_t structure which stores the transfer state
1792 */
1793 void XSPI_TransferAbort(XSPI_Type *base, xspi_handle_t *handle);
1794
1795 /*! @} */
1796
1797 /*!
1798 * @name AHB Access Control Low-Level Interfaces
1799 * @{
1800 */
1801
1802 /*!
1803 * @brief Blocks to clear AHB buffer and abort ongoing prefetch transaction(if prefetch is enabled.)
1804 *
1805 * @note The function return only after all AHB buffer pointers are cleared.
1806 *
1807 * @param[in] base XSPI peripheral base address.
1808 */
XSPI_ClearAhbBuffer(XSPI_Type * base)1809 static inline void XSPI_ClearAhbBuffer(XSPI_Type *base)
1810 {
1811 base->SPTRCLR |= XSPI_SPTRCLR_ABRT_CLR_MASK;
1812 while ((base->SPTRCLR & XSPI_SPTRCLR_ABRT_CLR_MASK) != 0UL)
1813 {
1814 }
1815 }
1816
1817 /*!
1818 * @brief Enable/disable the clearing of AHB read prefetch buffers when the same flash address is written by an
1819 * AHB or IP command.
1820 *
1821 * @param[in] base XSPI peripheral base address.
1822 * @param[in] enable Used to enable/disable write flush.
1823 *
1824 * @retval kStatus_XSPI_AhbReadAccessAsserted Fail due to an AHB read access already asserted.
1825 * @retval kStatus_XSPI_AhbWriteAccessAsserted Fail due to an AHB write access already asserted.
1826 * @retval kStatus_Success Successfully to enable/disable AHB buffer write flush.
1827 */
1828 status_t XSPI_EnableAhbBufferWriteFlush(XSPI_Type *base, bool enable);
1829
1830 /*!
1831 * @brief Set AHB buffer configurations.
1832 *
1833 * @param[in] base XSPI peripheral base address.
1834 * @param[in] ptrBuffer0Config Pointer to the variable which contain buffer0 configurations.
1835 * @param[in] ptrBuffer1Config Pointer to the variable which contain buffer1 configurations.
1836 * @param[in] ptrBuffer2Config Pointer to the variable which contain buffer2 configurations.
1837 * @param[in] ptrBuffer3Config Pointer to the variable which contain buffer3 configurations.
1838 *
1839 * @retval kStatus_XSPI_AhbReadAccessAsserted Fail due to an AHB read access already asserted.
1840 * @retval kStatus_XSPI_AhbWriteAccessAsserted Fail due to an AHB write access already asserted.
1841 * @retval kStatus_Success Success to set AHB buffer configurations.
1842 */
1843 status_t XSPI_SetAhbBufferConfig(XSPI_Type *base,
1844 xspi_ahbBuffer_config_t *ptrBuffer0Config,
1845 xspi_ahbBuffer_config_t *ptrBuffer1Config,
1846 xspi_ahbBuffer_config_t *ptrBuffer2Config,
1847 xspi_ahbBuffer_config_t *ptrBuffer3Config);
1848
1849 /*!
1850 * @brief Set Buffer size for all 4 AHB buffers.
1851 *
1852 * @param[in] base XSPI peripheral base address.
1853 * @param[in] buf0Size Specify size of AHB buffer0, range of 512, 256, 128, 64, 32, 16, 8, 4, 2, 0.
1854 * @param[in] buf1Size Specify size of AHB buffer1, range of 512, 256, 128, 64, 32, 16, 8, 4, 2, 0.
1855 * @param[in] buf2Size Specify size of AHB buffer2, range of 512, 256, 128, 64, 32, 16, 8, 4, 2, 0.
1856 * @param[in] buf3Size Specify size of AHB buffer3, range of 512, 256, 128, 64, 32, 16, 8, 4, 2, 0.
1857 *
1858 * @retval kStatus_XSPI_AhbReadAccessAsserted Fail due to an AHB read access already asserted.
1859 * @retval kStatus_XSPI_AhbWriteAccessAsserted Fail due to an AHB write access already asserted.
1860 * @retval kStatus_Success Success to set AHB buffer size.
1861 */
1862 status_t XSPI_UpdateAhbBufferSize(XSPI_Type *base, uint16_t buf0Size,
1863 uint16_t buf1Size, uint16_t buf2Size, uint16_t buf3Size);
1864
1865 /*!
1866 * @brief Get status of AHB sub buffer.
1867 *
1868 * @note This function only useful when sub-division feature of the selected AHB buffer is enabled.
1869 *
1870 * @param[in] base XSPI peripheral base address.
1871 * @param[in] ahbBufferId The Id of AHB buffer, range from 0 to 3.
1872 * @param[in] subBufferId The Id of AHB buffer sub division, range from 0 to 3.
1873 *
1874 * @return Current status of selected AHB sub buffer, in type of @ref xspi_ahb_sub_buffer_status_t.
1875 */
1876 xspi_ahb_sub_buffer_status_t XSPI_GetAhbSubBufferStatus(XSPI_Type *base, uint8_t ahbBufferId, uint8_t subBufferId);
1877
1878 /*!
1879 * @brief Start AHB buffer performance monitor.
1880 *
1881 * @param[in] base XSPI peripheral base address.
1882 */
XSPI_StartAhbBufferPerfMonitor(XSPI_Type * base)1883 static inline void XSPI_StartAhbBufferPerfMonitor(XSPI_Type *base)
1884 {
1885 base->AHB_PERF_CTRL |= XSPI_AHB_PERF_CTRL_CNTSTART_MASK;
1886 }
1887
1888 /*!
1889 * @brief Enable AHB buffer performance monitor for selected AHB buffer's sub buffer.
1890 *
1891 * @param[in] base XSPI peripheral base address.
1892 * @param[in] ahbBufferId Specify the selected AHB buffer.
1893 * @param[in] subBufferId Specify the selected sub-buffer.
1894 */
1895 void XSPI_EnableAhbBufferPerfMonitor(XSPI_Type *base, uint8_t ahbBufferId, uint8_t subBufferId);
1896
1897 /*!
1898 * @brief Disable AHB buffer performance monitor for selected AHB buffer.
1899 *
1900 * @param[in] base XSPI peripheral base address.
1901 * @param[in] ahbBufferId Specify the selected AHB buffer.
1902 */
XSPI_DisableAhbBufferPerfMonitor(XSPI_Type * base,uint8_t ahbBufferId)1903 static inline void XSPI_DisableAhbBufferPerfMonitor(XSPI_Type *base, uint8_t ahbBufferId)
1904 {
1905 base->AHB_PERF_CTRL &= (uint32_t)(~(uint32_t)(XSPI_AHB_PERF_CTRL_BUF0_EN_MASK << (uint32_t)(ahbBufferId)));
1906 }
1907
1908 /*!
1909 * @brief Stop AHB buffer performance monitor.
1910 *
1911 * @param[in] base XSPI peripheral base address.
1912 */
XSPI_StopAhbBufferPerfMonitor(XSPI_Type * base)1913 static inline void XSPI_StopAhbBufferPerfMonitor(XSPI_Type *base)
1914 {
1915 base->AHB_PERF_CTRL |= XSPI_AHB_PERF_CTRL_CNTSTP_MASK;
1916 }
1917
1918 /*!
1919 * @brief Get AHB buffer performance monitor result.
1920 *
1921 * @param[in] base XSPI peripheral base address.
1922 * @param[in] ahbBufferId Specify AHB buffer Id.
1923 * @param[out] ptrPerfMonitorResult Pointer to the variable to store selected AHB buffer's performance monitor result.
1924 */
XSPI_GetAhbBufferPerfMonitorResult(XSPI_Type * base,uint8_t ahbBufferId,xspi_ahbBuffer_perf_monitor_result_t * ptrPerfMonitorResult)1925 static inline void XSPI_GetAhbBufferPerfMonitorResult(XSPI_Type *base,
1926 uint8_t ahbBufferId,
1927 xspi_ahbBuffer_perf_monitor_result_t *ptrPerfMonitorResult)
1928 {
1929 uint32_t tmp32 = 0UL;
1930
1931 tmp32 = (uint32_t)(base->AHB_PERF_BUF[ahbBufferId]);
1932 ptrPerfMonitorResult->bufferMissCount = (uint16_t)(tmp32 & 0xFFFFUL);
1933 ptrPerfMonitorResult->bufferHitCount = (uint16_t)((tmp32 & 0xFFFF0000UL) >> 16UL);
1934 }
1935
1936 /*!
1937 * @brief Check if AHB buffer performance monitor timeout counter is overflow.
1938 *
1939 * @param base XSPI peripheral base address.
1940 *
1941 * @retval false AHB buffer performance monitor timeout counter is not overflow.
1942 * @retval true AHB buffer performance monitor timeout counter is overflow.
1943 */
XSPI_CheckAhbBufferPerfMonitorTimeCounterOverflow(XSPI_Type * base)1944 static inline bool XSPI_CheckAhbBufferPerfMonitorTimeCounterOverflow(XSPI_Type *base)
1945 {
1946 return (bool)((base->AHB_PERF_CTRL & XSPI_AHB_PERF_CTRL_TCNTO_MASK) != 0UL);
1947 }
1948
1949 /*!
1950 * @brief Check if AHB buffer performance monitor buffer hit counter is overflow.
1951 *
1952 * @param[in] base XSPI peripheral base address.
1953 * @param[in] ahbBufferId Specify the AHB buffer Id.
1954 *
1955 * @retval false Overflow not detected.
1956 * @retval true Overflow is detected.
1957 */
XSPI_CheckAhbBufferPerfMonitorHitOverflow(XSPI_Type * base,uint8_t ahbBufferId)1958 static inline bool XSPI_CheckAhbBufferPerfMonitorHitOverflow(XSPI_Type *base, uint8_t ahbBufferId)
1959 {
1960 return (bool)((base->AHB_PERF_CTRL & (XSPI_AHB_PERF_CTRL_BUF0_HIT_OVF_MASK << (uint32_t)ahbBufferId)) != 0UL);
1961 }
1962
1963 /*!
1964 * @brief Check if AHB buffer performance monitor buffer miss counter is overflow.
1965 *
1966 * @param[in] base XSPI peripheral base address.
1967 * @param[in] ahbBufferId Specify the AHB buffer Id.
1968 *
1969 * @retval false Overflow not detected.
1970 * @retval true Overflow is detected.
1971 */
XSPI_CheckAhbBufferPerfMonitorMissOverflow(XSPI_Type * base,uint8_t ahbBufferId)1972 static inline bool XSPI_CheckAhbBufferPerfMonitorMissOverflow(XSPI_Type *base, uint8_t ahbBufferId)
1973 {
1974 return (bool)((base->AHB_PERF_CTRL & ((uint32_t)XSPI_AHB_PERF_CTRL_BUF0_MISS_OVF_MASK << (uint32_t)ahbBufferId)) != 0UL);
1975 }
1976
1977 /*!
1978 * @brief Get AHB buffer performance monitor timeout value.
1979 *
1980 * @param[in] base XSPI peripheral base address.
1981 *
1982 * @return The value of time counter, in AHB clock cycles, since the performance monitor was running.
1983 */
XSPI_GetAhbBufferPerfMonitorTimeCounter(XSPI_Type * base)1984 static inline uint32_t XSPI_GetAhbBufferPerfMonitorTimeCounter(XSPI_Type *base)
1985 {
1986 return base->AHB_PERF_TIME_CNT;
1987 }
1988
1989 /*!
1990 * @brief Set AHB transaction(read/write) split size.
1991 *
1992 * @note For AHB write, if enable split feature(ahbSplitSize not set as kXSPI_AhbSplitSizeDisabled), XSPI will split one
1993 * single AHB write burst into smaller bursts on external device side.
1994 *
1995 * @note For AHB read, if enable split feature, HW will realign the prefetch size to split size and in that way split
1996 * a single read burst into smaller bursts.
1997 *
1998 * @param[in] base XSPI peripheral base address.
1999 * @param[in] ahbSplitSize Specify the AHB split size.
2000 *
2001 * @retval kStatus_XSPI_AhbReadAccessAsserted Fail due to an AHB read access already asserted
2002 * @retval kStatus_XSPI_AhbWriteAccessAsserted Fail due to an AHB write access already asserted
2003 * @retval kStatus_XSPI_RegWriteLocked Fail due to write operation to related registers is locked.
2004 * @retval kStatus_Success Success to set AHB access split size.
2005 */
2006 status_t XSPI_SetAhbAccessSplitSize(XSPI_Type *base, xspi_ahb_split_size_t ahbSplitSize);
2007
2008 /*!
2009 * @brief Set AHB transaction(read/write) boundary.
2010 *
2011 * @note For AHB write, XSPI keeps track of the start address and then compares it with the address of subsequent
2012 * transaction receive on the AHB bus, when the input alignment is reached, XSPI negates AHB HREADY to block new
2013 * accesses. This signal will be kept low until all the previous received write data is written to external memory and
2014 * chip select is de-asserted. After that it allows next AHB write data to be received by making HREADY high thus
2015 * ensuring that transaction is split at address boundary on external memory.
2016 *
2017 * @note For AHB read, XSPI checks the start address and end address to see if it is crossing the address boundary
2018 * specified by input alignment. If the transaction crosses the address boundary, then it reduces the transaction size
2019 * such that the data pre-fetch is stopped before the address boundary. Now if the AHB master is reading the data
2020 * sequentially it will get buffer hits up to the input alignment boundary. When it reaches the next address boundary
2021 * it will get a buffer miss and a new data pre-fetch will be launched towards the external memory device.
2022 *
2023 * @param[in] base XSPI peripheral base address.
2024 * @param[in] alignment Specify the AHB alignment, in type of @ref xspi_ahb_alignment_t.
2025 *
2026 * @retval kStatus_XSPI_AhbReadAccessAsserted Fail due to an AHB read access already asserted
2027 * @retval kStatus_XSPI_AhbWriteAccessAsserted Fail due to an AHB write access already asserted
2028 * @retval kStatus_XSPI_RegWriteLocked Fail due to write operation to related registers is locked.
2029 * @retval kStatus_Success Success to set AHB access boundary.
2030 */
2031 status_t XSPI_SetAhbAccessBoundary(XSPI_Type *base, xspi_ahb_alignment_t alignment);
2032
2033 /*!
2034 * @brief Set AHB read sequence Id.
2035 *
2036 * @param[in] base XSPI peripheral base address.
2037 * @param[in] seqId Specify the sequence Id in LUT used for AHB read.
2038 *
2039 * @retval kStatus_XSPI_AhbReadAccessAsserted Fail due to an AHB read access already asserted
2040 * @retval kStatus_XSPI_AhbWriteAccessAsserted Fail due to an AHB write access already asserted
2041 * @retval kStatus_XSPI_RegWriteLocked Fail due to write operation to related registers is locked.
2042 * @retval kStatus_Success Success to set AHB read sequence Id.
2043 */
2044 status_t XSPI_SetAhbReadDataSeqId(XSPI_Type *base, uint8_t seqId);
2045
2046 /*!
2047 * @brief Set AHB write sequence Id.
2048 *
2049 * @param[in] base XSPI peripheral base address.
2050 * @param[in] seqId Specify the sequence Id in LUT used for AHB write.
2051 *
2052 * @retval kStatus_XSPI_AhbReadAccessAsserted Fail due to an AHB read access already asserted
2053 * @retval kStatus_XSPI_AhbWriteAccessAsserted Fail due to an AHB write access already asserted
2054 * @retval kStatus_XSPI_RegWriteLocked Fail due to write operation to related registers is locked.
2055 * @retval kStatus_Success Success to set AHB write sequence Id.
2056 */
2057 status_t XSPI_SetAhbWriteDataSeqId(XSPI_Type *base, uint8_t seqId);
2058
2059 /*!
2060 * @brief Specify how long XSPI can hold HEADY low while waiting for response to an AHB transfer.
2061 *
2062 * @note If the specified time out value expired, an AHB illegal transaction error will be triggerred.
2063 *
2064 * @param[in] base XSPI peripheral base address.
2065 * @param[in] timeoutValue In multiples of 50000 AHB clock cycles, default value is 3,
2066 * it means waiting for 150000 AHB clock cycles.
2067 *
2068 * @retval kStatus_XSPI_AhbReadAccessAsserted Fail due to an AHB read access already asserted
2069 * @retval kStatus_XSPI_AhbWriteAccessAsserted Fail due to an AHB write access already asserted
2070 * @retval kStatus_Success Success to set AHB HREADY timeout value.
2071 */
2072 status_t XSPI_UpdateAhbHreadyTimeOutValue(XSPI_Type *base, uint16_t timeoutValue);
2073
2074 /*!
2075 * @brief Pre-define error payload which will be provided on the read data bus when the HEADY timeout counter expires.
2076 *
2077 * @note If the incoming AHB read request master is not mapped to any of the AHB buffer, the XSPI will keep the AHB
2078 * HREADY signal low and will provided this pre-defined error payload on the AHB read data bus when the HEADY timeout
2079 * counter expires.
2080 *
2081 * @param[in] base XSPI peripheral base address.
2082 * @param[in] highPayload High 32bits payload to set.
2083 * @param[in] lowPayload Low 32bits payload to set.
2084
2085 * @retval kStatus_XSPI_AhbReadAccessAsserted Fail due to an AHB read access already asserted
2086 * @retval kStatus_XSPI_AhbWriteAccessAsserted Fail due to an AHB write access already asserted
2087 * @retval kStatus_Success Success to set AHB HREADY timeout value.
2088 */
2089 status_t XSPI_SetAhbErrorPayload(XSPI_Type *base, uint32_t highPayload, uint32_t lowPayload);
2090
2091 /*!
2092 * @brief Return AHB read error information.
2093 *
2094 * @param[in] base XSPI peripheral base address.
2095 *
2096 * @return Latest AHB read error information, in type of xspi_ahb_read_error_info_t.
2097 */
2098 xspi_ahb_read_error_info_t XSPI_ReturnAhbReadErrorInfo(XSPI_Type *base);
2099
2100 /*!
2101 * @brief Clear AHB access sequence pointer.
2102 *
2103 * @param[in] base XSPI peripheral base address.
2104 */
XSPI_ClearAhbAccessSeqPointer(XSPI_Type * base)2105 static inline void XSPI_ClearAhbAccessSeqPointer(XSPI_Type *base)
2106 {
2107 base->SPTRCLR |= XSPI_SPTRCLR_BFPTRC_MASK;
2108 }
2109
2110 /*!
2111 * @brief Get Ahb request suspend information if priority mechanism is enabled.
2112 *
2113 * @param[in] base XSPI peripheral base address.
2114 * @param[out] ptrSuspendInfo Contain latest suspend info, the value may be 0xFF if the item is invalid in current
2115 * suspend state.
2116 */
2117 void XSPI_GetAhbRequestSuspendInfo(XSPI_Type *base, xspi_ahb_request_suspend_info_t *ptrSuspendInfo);
2118
2119 /*!
2120 * @brief Enable/disable AHB Read Prefetch feature.
2121 *
2122 * @param[in] base XSPI peripheral base address.
2123 * @param[in] enable Used to enable/disable AHB read prefetch:
2124 * - \b false Disable AHB read prefetch;
2125 * - \b true Enable AHB read prefetch.
2126 */
XSPI_EnableAhbReadPrefetch(XSPI_Type * base,bool enable)2127 static inline void XSPI_EnableAhbReadPrefetch(XSPI_Type *base, bool enable)
2128 {
2129 if (enable)
2130 {
2131 base->SPTRCLR &= ~XSPI_SPTRCLR_PREFETCH_DIS_MASK;
2132 }
2133 else
2134 {
2135 base->SPTRCLR |= XSPI_SPTRCLR_PREFETCH_DIS_MASK;
2136 }
2137 }
2138
2139 /*!
2140 * @brief Block access(write and read) after the AHB write operation.
2141 *
2142 * @note If external flash support RWW, read should not be blocked:
2143 * @code
2144 * XSPI_BlockAccessAfterAhbWrite(XSPI0, true, false);
2145 * @endcode
2146 *
2147 * @note If either of access is blocked, the page program wait flag will be asserted after
2148 * an AHB write sequence completed. The assertion of flag will lock the arbitration and all
2149 * access to the external memory are blocked. And the internal "page wait time" counter
2150 * starts(Invoke XSPI_UpdatePageWaitTimeCounter to update counter value). After this counter
2151 * reaches the value, a read is triggered by the XSPI module to read external device's
2152 * status register(The seq id should be pre-defiend by XSPI_SetAhbReadStatusRegSeqId),
2153 * and the value is stored in the XSPI internal regsiter. And there are two
2154 * options(Invoke XSPI_SelectPPWFlagClearPolicy to select) to clear the asserted page program wait flag.
2155 * 1. Automatic cleared by XSPI hardware;
2156 * 2. Cleared by software.
2157 *
2158 * @note As soon as the page program wait flag is asserted, another counter(SFP arbitration
2159 * lock counter) also started, if the flag not cleared in desired counter value the
2160 * arbitration lock timeout error will be generated.
2161 *
2162 * @param[in] base XSPI peripheral base address.
2163 * @param[in] blockSequentWrite Block sequence write or not.
2164 * @param[in] blockRead Block read or not.
2165 *
2166 * @retval kStatus_XSPI_AhbReadAccessAsserted Fail due to an AHB read access already asserted
2167 * @retval kStatus_XSPI_AhbWriteAccessAsserted Fail due to an AHB write access already asserted
2168 * @retval kStatus_Success Success to set related registers..
2169 */
2170 status_t XSPI_BlockAccessAfterAhbWrite(XSPI_Type *base, bool blockSequentWrite, bool blockRead);
2171
2172 /*!
2173 * @brief Set Page program wait flag clear policy.
2174 *
2175 * @note If set as hardware policy, the device's WIP information should be set by invoking XSPI_SetSFMStatusRegInfo()
2176 *
2177 * @param[in] base XSPI peripheral base address.
2178 * @param[in] policy Specify the policy to clear page program wait flag.
2179 *
2180 * @retval kStatus_XSPI_AhbReadAccessAsserted Fail due to an AHB read access already asserted
2181 * @retval kStatus_XSPI_AhbWriteAccessAsserted Fail due to an AHB write access already asserted
2182 * @retval kStatus_XSPI_RegWriteLocked Fail due to write operation to related registers is locked.
2183 * @retval kStatus_Success Success to set PPW flag clear policy.
2184 */
2185 status_t XSPI_SelectPPWFlagClearPolicy(XSPI_Type *base, xspi_ppw_flag_clear_policy_t policy);
2186
2187 /*!
2188 * @brief Update page wait timeout counter.
2189 *
2190 * @param[in] base XSPI peripheral base address.
2191 * @param[in] countValue The value of counter, in AHB clock cycles.
2192 *
2193 * @retval kStatus_XSPI_AhbReadAccessAsserted Fail due to an AHB read access already asserted
2194 * @retval kStatus_XSPI_AhbWriteAccessAsserted Fail due to an AHB write access already asserted
2195 * @retval kStatus_XSPI_PageProgramWaitFlagAsserted Page program wait flag already asserted.
2196 * @retval kStatus_Success Successfully to update page wait timeout counter.
2197 */
2198 status_t XSPI_UpdatePageWaitTimeCounter(XSPI_Type *base, uint32_t countValue);
2199
2200 /*!
2201 * @brief Set AHB read status register sequence Id
2202 *
2203 * @note The read status sequence only triggerred when the page wait time counter expired.
2204 *
2205 * @param[in] base XSPI peripheral base address.
2206 * @param[in] seqId Specify the sequence Id in LUT used for AHB read status register.
2207 *
2208 * @retval kStatus_XSPI_AhbReadAccessAsserted Fail due to an AHB read access already asserted
2209 * @retval kStatus_XSPI_AhbWriteAccessAsserted Fail due to an AHB write access already asserted
2210 * @retval kStatus_XSPI_RegWriteLocked Fail due to write operation to related registers is locked.
2211 * @retval kStatus_Success Success to set AHB read status register sequence Id.
2212 */
2213 status_t XSPI_SetAhbReadStatusRegSeqId(XSPI_Type *base, uint8_t seqId);
2214
2215 /*!
2216 * @brief Get external serial flash's status register value.
2217 *
2218 * @note This function is only useful after the Page program wait flag is asserted due to
2219 * either wait/read access is blocked after the AHB write operation.
2220 *
2221 * @param[in] base XSPI peripheral base address.
2222 *
2223 * @return The status regsiter value of external device.
2224 */
XSPI_GetSFMStatusRegValue(XSPI_Type * base)2225 static inline uint16_t XSPI_GetSFMStatusRegValue(XSPI_Type *base)
2226 {
2227 while ((base->PPW_RDSR & XSPI_PPW_RDSR_VALID_MASK) == 0UL)
2228 {
2229 }
2230
2231 return (uint16_t)(base->PPW_RDSR & XSPI_PPW_RDSR_RDSR_MASK);
2232 }
2233
2234 /*!
2235 * @brief Set Serial flash memory status register information
2236 *
2237 * @param[in] base XSPI peripheral base address.
2238 * @param[in] ptrStatusRegInfo Pointer to the variable which contain status register information.
2239 *
2240 * @retval kStatus_XSPI_AhbReadAccessAsserted Fail due to an AHB read access already asserted
2241 * @retval kStatus_XSPI_AhbWriteAccessAsserted Fail due to an AHB write access already asserted
2242 * @retval kStatus_XSPI_PageProgramWaitFlagAsserted Page program wait flag already asserted.
2243 * @retval kStatus_Success Successfully to set status register information.
2244 */
2245 status_t XSPI_SetSFMStatusRegInfo(XSPI_Type *base, xspi_device_status_reg_info_t *ptrStatusRegInfo);
2246
2247 /*! @} */
2248
2249 /*!
2250 * @name AHB Access Control Functional Interfaces
2251 * @{
2252 */
2253
2254 /*!
2255 * @brief Set AHB access configuration.
2256 *
2257 * @param[in] base XSPI peripheral base address.
2258 * @param[in] ptrAhbAccessConfig Pointer to the variable which contains AHB access configurations.
2259 *
2260 * @retval kStatus_XSPI_AhbReadAccessAsserted Fail due to an AHB read access already asserted
2261 * @retval kStatus_XSPI_AhbWriteAccessAsserted Fail due to an AHB write access already asserted
2262 * @retval kStatus_XSPI_RegWriteLocked Fail due to write operation to related registers is locked.
2263 * @retval kStatus_Success Success to set AHB read status register sequence Id.
2264 */
2265 status_t XSPI_SetAhbAccessConfig(XSPI_Type *base, xspi_ahb_access_config_t *ptrAhbAccessConfig);
2266
2267 /*! @} */
2268
2269
2270
2271 /*! @} */
2272
2273 #if defined(__cplusplus)
2274 }
2275 #endif /*_cplusplus. */
2276 /*@}*/
2277
2278 #endif /* FSL_XSPI_H_ */
2279
