1 /*
2  * Copyright 2024 NXP
3  *
4  * All rights reserved.
5  * SPDX-License-Identifier: BSD-3-Clause
6  */
7 
8 #ifndef _FSL_SFDP_H
9 #define _FSL_SFDP_H
10 
11 #include "fsl_common.h"
12 
13 /*!
14  * The SFDP strandard defines the structure of the SFDP database within the memory device and methods used to read its
15  * data.
16  * The SFDP defined header with Parameter ID FF00h and the related Basic Parameter Table is mandatory.
17  * This header and table provide basic information for a SPI protocol memory.
18  *
19  */
20 
21 /*!
22  *
23  * In the JESD216D revision are optional special function parameter tables for the JEDEC x4(Quad) eXtended Serial
24  * Peripheral Interface(x4 xSPI).
25  * New in the JESD216E revision is a description of the Replay Protected Monotonic Counter(RPMC) functionality
26  * and also descriptions of the Secure Read and Secure write Packet transfer transactions.
27  */
28 
29 /*******************************************************************************
30  * Definitions
31  ******************************************************************************/
32 
33 #define SFDP_READ_INST  (0x5A)
34 #define SFDP_FETCH_INST (0x5B)
35 
36 #define SFDP_REVISION(major, minor) (((uint16_t)(major) << 8UL) | ((uint16_t)(minor)))
37 
38 /*!
39  * @brief The enumeration of SFDP revision.
40  */
41 typedef enum _sfdp_revsion
42 {
43     kSFDP_JESD216F = SFDP_REVISION(0x01U, 0x0AU), /*!< Version F. */
44     kSFDP_JESD216E = SFDP_REVISION(0x01U, 0x09U), /*!< Version E. */
45     kSFDP_JESD216D = SFDP_REVISION(0x01U, 0x08U), /*!< Version D. */
46     kSFDP_JESD216C = SFDP_REVISION(0x01U, 0x07U), /*!< Version C. */
47     kSFDP_JESD216B = SFDP_REVISION(0x01U, 0x06U), /*!< Version B. */
48     kSFDP_JESD216A = SFDP_REVISION(0x01U, 0x05U), /*!< Version A. */
49     kSFDP_JESD216  = SFDP_REVISION(0x01U, 0x00U), /*!< The version pre A. */
50 } sfdp_revsion_t;
51 
52 /*!
53  * @brief The enumeration of return type of sfdp parser functions.
54  */
55 typedef enum _sfdp_ret_type
56 {
57     kSFDP_RET_Invalid,              /*!< Invalid input. */
58     kSFDP_RET_HardwareIssue,        /*!< Fail due to spi hardare interface. */
59     kSFDP_RET_NotImplemented,       /*!< The feature not implemented. */
60     kSFDP_RET_ReadCMDNotSupported,  /*!< Read command not supported. */
61     kSFDP_RET_EraseCMDNotSupported, /*!< Erase command not supported. */
62     kSFDP_RET_RegBitNotSupported,   /*!< Register bit field not supported. */
63     kSFDP_RET_OPICMDNotSupported,   /*!< OPI command not supported. */
64     kSFDP_RET_Success,              /*!< Success. */
65 } sfdp_ret_type_t;
66 
67 /*!
68  * @brief The enumeration of sfdp access protocol
69  *
70  */
71 typedef enum _sfdp_access_protocol
72 {
73     kSFDP_AccessProtocol240 = 0xF0, /*!< The access protocol 240 */
74     kSFDP_AccessProtocol241 = 0xF1, /*!< The access protocol 241 */
75     kSFDP_AccessProtocol242 = 0xF2, /*!< The access protocol 242 */
76     kSFDP_AccessProtocol243 = 0xF3, /*!< The access protocol 243 */
77     kSFDP_AccessProtocol244 = 0xF4, /*!< The access protocol 244 */
78     kSFDP_AccessProtocol245 = 0xF5, /*!< The access protocol 245 */
79     kSFDP_AccessProtocol246 = 0xF6, /*!< The access protocol 246 */
80     kSFDP_AccessProtocol247 = 0xF7, /*!< The access protocol 247 */
81     kSFDP_AccessProtocol250 = 0xFA, /*!< The access protocol 250 */
82     kSFDP_AccessProtocol251 = 0xFB, /*!< The access protocol 251 */
83     kSFDP_AccessProtocol252 = 0xFC, /*!< The access protocol 252 */
84     kSFDP_AccessProtocol253 = 0xFD, /*!< The access protocol 253 */
85     kSFDP_AccessProtocol254 = 0xFE, /*!< The access protocol 254 */
86     kSFDP_AccessProtocol255 = 0xFF, /*!< The access protocol 255 */
87 } sfdp_access_protocol_t;
88 
89 /*!
90  * @brief The structure of sfdp header, including SFDP signature, revision, number of parameter header, and access
91  * protocol.
92  */
93 typedef struct _sfdp_header
94 {
95     uint32_t signature; /*!< "SFDP" in little endian, 0x50444653h */
96     uint8_t minorRev;   /*!< SFDP Minor Revision */
97     uint8_t majorRev;   /*!< SFDP Major Revision */
98     uint8_t nph;        /*!< Number of parameter header, 0-based, 0 indicates 1 parameter header. */
99     uint8_t access;     /*!< SFDP access protocol, up to and including JESD216B this field was 0xFF. */
100 } sfdp_header_t;
101 
102 /*!
103  * @brief The structure of sfdp parameter header, including parameter ID, minor revision, major revision, length, and
104  * parameter table pointer.
105  *
106  */
107 typedef struct _sfdp_param_header
108 {
109     uint8_t idLsb;       /*!< Parameter ID LSB */
110     uint8_t minorRev;    /*!< Parameter minor revision. */
111     uint8_t majorRev;    /*!< Parameter major revision. */
112     uint8_t len;         /*!< Parameter length in double words. */
113     uint32_t ptp : 24U;  /*!< Parameter table pointer(byte address). */
114     uint32_t idMsb : 8U; /*!< Parameter ID MSB. */
115 } sfdp_param_header_t;
116 
117 #define SFDP_DW1_BLOCK_SECTOR_ERASE_SIZES_MASK  (0x3UL)
118 #define SFDP_DW1_BLOCK_SECTOR_ERASE_SIZES_SHIFT (0UL)
119 
120 /*!
121  * @brief The enumeration of octal dtr cmd type.
122  */
123 typedef enum _sfdp_octal_dtr_cmd_type
124 {
125     kSFDP_OctalDTRCmdExtensionSameAsCmd    = 0U, /*!< The command extension is same as the command. */
126     kSFDP_OctalDTRCmdExtensionInvertCmd    = 1U, /*!< The command extension is the inverse of the command. */
127     kSFDP_OctalDTRCmdExtensionReserved     = 2U, /*!< Reserved. */
128     kSFDP_OctalDTRCmdExtensionCmdForm16Bit = 3U, /*!< The command and command extension forms a 16 bit command word. */
129 } sfdp_octal_dtr_cmd_type_t;
130 
131 /*!
132  * @brief The structure of basic flash param table, dw10 to dw16 is added from JESD216A, dw17 to dw20 is added from
133  * JESD216C, dw21 to dw23 is added from JESD216F.
134  */
135 typedef struct _sfdp_basic_flash_param_table
136 {
137     uint32_t dw1;  /*!< Uniform 4KB Sectors, write buffer size, volatile status register, fast read support,
138                        number of address bytes, DTR(DDR) support.  */
139     uint32_t dw2;  /*!< Memory density. */
140     uint32_t dw3;  /*!< Fast Read(1s-4s-4s and 1s-1s-4s): wait states, mode bit clocks and instruction. */
141     uint32_t dw4;  /*!< Fast Read(1s-1s-2s and 1s-2s-2s): wait states, mode bit clocks and instruction. */
142     uint32_t dw5;  /*!< Fast Read(2s-2s-2s and 4s-4s-4s) support. */
143     uint32_t dw6;  /*!< Fast Read(2s-2s-2s): wait states, mode bit clocks and instruction. */
144     uint32_t dw7;  /*!< Fast Read(4s-4s-4s): wait states, mode bit clocks and instruction. */
145     uint32_t dw8;  /*!< Erase type 1 and 2 size and instruction. */
146     uint32_t dw9;  /*!< Erase type 3 and 4 size and instruction. */
147     uint32_t dw10; /*!< Added in kSFDP_JESD216A, erase type typical erase times and multiplier used to derive
148                     max erase times. */
149     uint32_t dw11; /*!< Added in kSFDP_JESD216A, chip erase typical time, byte program and page program
150                     typical times, page size. */
151     uint32_t dw12; /*!< Added in kSFDP_JESD216A, erase,program suspend, resume support, intervals, latency.*/
152     uint32_t dw13; /*!< Added in kSFDP_JESD216A, Progam/Erase suspend/resume instructions. */
153     uint32_t dw14; /*!< Added in kSFDP_JESD216A, deep power down and status register polling device busy. */
154     uint32_t dw15; /*!< Added in kSFDP_JESD216A, hold and WP disable function, Quad Enable requirements, 4s-4s-4s mode
155                     enable/disable sequences, 0-4-4 entry/exit methods and support. */
156     uint32_t dw16; /*!< Added in kSFDP_JESD216A, 32-bit address entry/exit methods and support, soft reset and rescure
157                     sequences, volatile and nonvolatile status register support. */
158     uint32_t dw17; /*!< Added in kSFDP_JESD216C, fast read(1s-8s-8s)(1s-1s-8s): wait states,
159                         mode bit clocks, instruction */
160     uint32_t dw18; /*!< Added in kSFDP_JESD216C, octal commands, byte order, data strobe, JEDEC SPI protocol reset. */
161     uint32_t dw19; /*!< Added in kSFDP_JESD216C, octal enable requirements, 8d-8d-8d mode enable/disable sequences,
162                     0-8-8 entry/exit methods and support. */
163     uint32_t dw20; /*!< Added in kSFDP_JESD216C, maximum operating speeds. */
164     uint32_t dw21; /*!< Added in kSFDP_JESD216F, fast read(1s-1d-1d),(1s-2d-2d),(1s-4d-4d), and (4s-4d-4d) support. */
165     uint32_t dw22; /*!< Added in kSFDP_JESD216F, fast read(1s-1d-1d) and (1s-2d-2d) wait states, mode bit clocks, and
166                     instruction. */
167     uint32_t dw23; /*!< Added in kSFDP_JESD216F, fast read(1s-4d-4d) and (4s-4d-4d) wait states, mode bit clocks and
168                     instruction. */
169 } sfdp_basic_flash_param_table_t;
170 
171 /*!
172  * @brief The structure of sector map parameter table.
173  *
174  * @details The Sector Map Parameter Table identifies the location and size of sectors within the main data array of the
175  * flash memory device and identifies which Erase Types are supported by each sector.
176  *
177  * @note Added in kSFDP_JESD216B
178  */
179 typedef struct _sfdp_sector_map_param_table
180 {
181     uint32_t dw1; /*!< 1st DWORD. */
182     uint32_t dw2; /*!< 2nd DWORD. */
183 } sfdp_sector_map_param_table_t;
184 
185 /*!
186  * @brief The structure of replay protected monotonic counters parameter header and table.
187  *
188  * @details  The widely supported RPMC functionality has been adopted by JEDEC to control multiple nonvolatile monotonic
189  * counters integrated into a serial flash device. RPMC allows cryptographically secure host access to the
190  * (typically four) monotonic counters using packets that include a signature. The signature is generated using an
191  * HMAC-SHA256 process that guarantees the authenticity of the transferred packet. The details of RPMC functionality
192  * are described in a separate JEDEC standard.
193  *
194  * @note Added in kSFDP_JESD216E
195  */
196 typedef struct _sfdp_rpmc_param_table
197 {
198     struct
199     {
200         uint32_t flashHardening : 1U;     /*!< 0: Supported, 1: Not supported. */
201         uint32_t counterSize : 1U;        /*!< 0: monotonic counter size is 32 bits, 1: Reserved. */
202         uint32_t busyPollingMethod : 1U;  /*!< 0: Use OP2 Extended status, 1: Use Read status. */
203         uint32_t reserved1 : 1U;          /*!< Reserved. */
204         uint32_t numCounter : 4U;         /*!< Number of supported counters minus one. */
205         uint32_t rpmcPacketWriteCmd : 8U; /*!< RPMC packet WRITE command opcode. */
206         uint32_t rpmcPacketReadCmd : 8U;  /*!< RPMC packet READ command opcode. */
207         uint32_t updateRate : 4U;         /*!< Rate of update = 5 * (2^(updateRate)) seconds. */
208         uint32_t reserved2 : 4U;          /*!< Reserved. */
209     } dw1;
210     struct
211     {
212         uint32_t readCounterPollingDelayValue : 5U;       /*!< Read counter polling delay value. */
213         uint32_t readCounterPollingDelayUnit : 2U;        /*!< Read counter polling delay unit,
214                                                               0: 1us, 1: 16us, 2: 128us, 3: 1ms. */
215         uint32_t reserved1 : 1U;                          /*!< Reserved. */
216 
217         uint32_t writeCounterPollingShortDelayValue : 5U; /*!< Write counter polling short delay value. */
218         uint32_t writeCounterPollingShortDelayUnit : 2U;  /*!< Write counter polling short delay unit,
219                                                          0: 1us, 1: 16us, 2: 128us, 3: 1ms. */
220         uint32_t reserved2 : 1U;                          /*!< Reserved */
221 
222         uint32_t writeCounterPollingLongDelayValue : 5U;  /*!< Write counter polling short delay value. */
223         uint32_t writeCounterPollingLongDelayUnit : 2U;   /*!< Write counter polling short delay unit
224                                                          0: 1ms, 1: 16ms, 2: 128ms, 3: 1s. */
225         uint32_t reserved3 : 1U;                          /*!< Reserved. */
226 
227         uint32_t reserved4 : 8U;                          /*!< Reserved. */
228     } dw2;
229 } sfdp_rpmc_param_table_t;
230 
231 /*!
232  * @brief The structure of 4-byte address instruction parameter table.
233  *
234  * @details Legacy SPI memory devices were limited to 128-Mbits (16-Mbytes) of address space by commands that provided
235  * only three bytes (24-bits) of address. Recent SPI memories that exceed 128-Mbits density provide various options
236  * for providing 4-bytes (32-bits) of address. One option is the use of commands that always provide 4-bytes of
237  * address. These commands in some cases have the same function as legacy 3-byte address commands but use a different
238  * instruction to indicate that 4-bytes of address follow the instruction. The 4-byte address instruction special
239  * function table indicates which 4-byte address command instructions are supported by the SPI memory. The table also
240  * provides the 4-byte address instructions for the four Erase Types defined in 8 th DWORD of the Basic Flash Parameter
241  * Table. If a 4-byte address instruction is not supported for an Erase Type, the instruction for that type is shown in
242  * the table as FFh.
243  * @note Added in kSFDP_JESD216B.
244  */
245 typedef struct _sfdp_4_byte_addr_instruction_param_table
246 {
247     uint32_t dw1; /*!< 1st dword. */
248     uint32_t dw2; /*!< 2nd dword. */
249 } sfdp_4_byte_addr_instruction_param_table_t;
250 
251 /*!
252  * @brief The structure of eXtended serial peripheral interface(xSPI) profile 1.0 parameter table.
253  * @note Added in kSFDP_JESD216C
254  */
255 typedef struct _sfdp_xSPI_profile1_param_table
256 {
257     uint32_t dw1; /*!< 1st dword. */
258     uint32_t dw2; /*!< 2nd dword. */
259     uint32_t dw3; /*!< 3rd dword. */
260     uint32_t dw4; /*!< 4th dword. */
261     uint32_t dw5; /*!< 5th dword. */
262     uint32_t dw6; /*!< 6th dword. */
263 } sfdp_xSPI_profile1_param_table_t;
264 
265 /*!
266  * @brief The structure of eXtended serial peripheral interface(xSPI) profile 2.0 parameter table.
267  * @note Added in kSFDP_JESD216C
268  */
269 typedef struct _sfdp_xSPI_profile2_param_table
270 {
271     uint32_t dw1; /*!< 1st dword. */
272     uint32_t dw2; /*!< 2nd dword. */
273     uint32_t dw3; /*!< 3rd dword. */
274 } sfdp_xSPI_profile2_param_table_t;
275 
276 /*!
277  * @brief The status, control, and configuration register map for SPI memory devices.
278  * @note Added in kSFDP_JESD216C
279  */
280 typedef struct _sfdp_sccr_param_table
281 {
282     uint32_t dw1;  /*!< Volatile register address offset. */
283     uint32_t dw2;  /*!< Non-volatile register address offset. */
284     uint32_t dw3;  /*!< Generic addressable Read/Write status/control register command for volatile registers. */
285     uint32_t dw4;  /*!< Generic addressable Read/Write status/control register command for volatile registers. */
286     uint32_t dw5;  /*!< WIP(write in process). */
287     uint32_t dw6;  /*!< WEL(write enable latch). */
288     uint32_t dw7;  /*!< Program Error. */
289     uint32_t dw8;  /*!< Erase Error. */
290     uint32_t dw9;  /*!< Variable dummy cycle settings on volatile register. */
291     uint32_t dw10; /*!< Variable dummy cycle settings on non-volatile register. */
292     uint32_t dw11; /*!< Variable dummy cycle settings 1. */
293     uint32_t dw12; /*!< Variable dummy cycle settings 2. */
294     uint32_t dw13; /*!< Variable dummy cycle settings 3. */
295     uint32_t dw14; /*!< QPI mode enable volatile. */
296     uint32_t dw15; /*!< OPI mode enable non volatile. */
297     uint32_t dw16; /*!< Octal mode enable volatile. */
298     uint32_t dw17; /*!< Octal mode enable non-volatile. */
299     uint32_t dw18; /*!< STR or DTR mode select volatile. */
300     uint32_t dw19; /*!< STR or DTR mode select non-volatile. */
301     uint32_t dw20; /*!< STR Octal Mode enable volatile. */
302     uint32_t dw21; /*!< STR Octal Mode enable non-volatile. */
303     uint32_t dw22; /*!< DTR Octal Mode enable volatile. */
304     uint32_t dw23; /*!< DTR Octal Mode enable non-volatile. */
305     uint32_t dw24; /*!< DPD Status */
306     uint32_t dw25; /*!< UDPD status. */
307     uint32_t dw26; /*!< Output driver strength volatile. */
308     uint32_t dw27; /*!< Output driver strength non-volatile. */
309     uint32_t dw28; /*!< Output driver strength control bits patterns. */
310 } sfdp_sccr_param_table_t;
311 
312 /*!
313  * @brief Status, control and configuration register map for xSPI profile 2.0 memory devices.
314  *
315  * @details The purpose of the SCCR Map is to provide a host controller with a minimum amount of information to be able
316  * to boot a system and load necessary code for the system to run. It is to be expected that the code loaded from the
317  * memory device will contain the necessary information required to achieve optimum performance from the device.
318  */
319 typedef struct _sfdp_sccr_profile2_param_table
320 {
321     uint32_t dw1;  /*!< Volatile register address offset. */
322     uint32_t dw2;  /*!< Non-volatile register address offset. */
323     uint32_t dw3;  /*!< Generic addressable Read/Write Status/Control register commands. */
324     uint32_t dw4;  /*!< Program Error. */
325     uint32_t dw5;  /*!< Erase Error. */
326     uint32_t dw6;  /*!< Variable dummy cycle settings - volatile register. */
327     uint32_t dw7;  /*!< Variable dummy cycle settings - non-volatile register. */
328     uint32_t dw8;  /*!< Variable dummy cycle settings 1 - bit patterns. */
329     uint32_t dw9;  /*!< Variable dummy cycle settings 2 - bit patterns. */
330     uint32_t dw10; /*!< Variable dummy cycle settings 3 - bit patterns. */
331     uint32_t dw11; /*!< Output driver strength - volatile. */
332     uint32_t dw12; /*!< Output driver strength - non-volatile. */
333     uint32_t dw13; /*!< Output driver strength control bit patterns. */
334 } sfdp_sccr_profile2_param_table_t;
335 
336 /*!
337  * @brief The structure of status, control and configuration register map offsets for multi-chip spi memory devices.
338  * @details For multi-chip devices, each chip (die) will follow the same Status, Control and Configuration Register Map
339  * as described in 6.10. Direct commands are not an option in this case, register bits may only be accessed by a
340  * command specifying an address and a register value.
341  * @note Added in kSFDP_JESD216C
342  */
343 typedef struct _sfdp_sccr_multi_dies_addr_offset_param_table
344 {
345     uint32_t dw1; /*!< Volatile register address offset for Die1. */
346     uint32_t dw2; /*!< Non-Volatile register address offset for Die1. */
347     uint32_t dw3; /*!< Volatile register address offset for Die2. */
348     uint32_t dw4; /*!< Non-Volatile register address offset for Die2. */
349     uint32_t dw5; /*!< Volatile register address offset for Die3. */
350     uint32_t dw6; /*!< Non-Volatile register address offset for Die3. */
351 } sfdp_sccr_multi_dies_addr_offset_param_table_t;
352 
353 /*!
354  * @brief The structure of command sequence to octal parameter table.
355  * @note Added in kSFDP_JESD216C
356  */
357 typedef struct _sfdp_command_seq_to_octal_param_table
358 {
359     uint32_t dw1; /*!< 1st dword. */
360     uint32_t dw2; /*!< 2nd dword. */
361     uint32_t dw3; /*!< 3rd dword. */
362     uint32_t dw4; /*!< 4th dword. */
363     uint32_t dw5; /*!< 5th dword. */
364     uint32_t dw6; /*!< 6th dword. */
365     uint32_t dw7; /*!< 7th dword. */
366     uint32_t dw8; /*!< 8th dword. */
367 } sfdp_command_seq_to_octal_param_table_t;
368 
369 /*!
370  * @brief The structure of x4 Quad IO with DS parameter table.
371  * @note Added in kSFDP_JESD216D
372  */
373 typedef struct _sfdp_x4_quad_with_DS_param_table
374 {
375     uint32_t dw1; /*!< Command codes used in 4s-4d-4d protocol mode. */
376     uint32_t dw2; /*!< Command codes used in 4s-4d-4d protocol mode. */
377     uint32_t dw3; /*!< Memory commands supported in 4s-4d-4d protocal mode. */
378     uint32_t dw4; /*!< Dummy cycles used for various frequencies. */
379     uint32_t dw5; /*!< Dummy cycles used for various frequencies. */
380 } sfdp_x4_quad_with_DS_param_table_t;
381 
382 /*!
383  * @brief The structure of command sequences to change to Quad DTR(DDR).
384  * @note Added in kSFDP_JESD216D
385  */
386 typedef struct _sfdp_command_seq_to_quad_param_table
387 {
388     uint32_t dw1; /*!< 1st dword. */
389     uint32_t dw2; /*!< 2nd dword. */
390     uint32_t dw3; /*!< 3rd dword. */
391     uint32_t dw4; /*!< 4th dword. */
392     uint32_t dw5; /*!< 5th dword. */
393     uint32_t dw6; /*!< 6th dword. */
394     uint32_t dw7; /*!< 7th dword. */
395     uint32_t dw8; /*!< 8th dword. */
396 } sfdp_command_seq_to_quad_param_table_t;
397 
398 /*!
399  * @brief The structure of secure packet read/write parameter table.
400  * @note Added in kSFDP_JESD216E.
401  */
402 typedef struct _sfdp_secure_packet_read_write_param_table
403 {
404     uint32_t dw1; /*!< 1st dword. */
405     uint32_t dw2; /*!< 2nd dword. */
406     uint32_t dw3; /*!< 3rd dword. */
407     uint32_t dw4; /*!< 4th dword. */
408 } sfdp_secure_packet_read_write_param_table;
409 
410 /*!
411  * @brief The enumeration of address mode of serial flash devices.
412  */
413 typedef enum _sfdp_addr_mode
414 {
415     kSFDP_AddrMode_3ByteOnly = 0x0U, /*!< Serial flash device only support 3-byte mode. */
416     kSFDP_AddrMode_3Or4Byte  = 0x1U, /*!< Default to 3-byte mode, enters 4-byte mode on command. */
417     kSFDP_AddrMode_4ByteOnly = 0x2U, /*!< Defult to 4-byte mode. */
418     kSFDP_AddrMode_Reserved  = 0x3U, /*!< Reserved. */
419 } sfdp_addr_mode_t;
420 
421 /*!
422  * @brief The enumeration of flash data pad number.
423  */
424 typedef enum _sfdp_flash_pad_num
425 {
426     kSFDP_Flash1Pad = 0U, /*!< Data pad number is 1. */
427     kSFDP_Flash2Pad = 1U, /*!< Data pad number is 2. */
428     kSFDP_Flash4Pad = 2U, /*!< Data pad number is 4. */
429     kSFDP_Flash8Pad = 3U, /*!< Data pad number is 8. */
430 } sfdp_flash_pad_num_t;
431 
432 #define SFDP_ENCODE_PROTOCOL_TYPE(instrPad, instrDDR, addrPad, addrDDR, dataPad, dataDDR, key) \
433     (((uint16_t)(key) << 14U) | ((uint16_t)(dataPad) << 0U) | ((uint16_t)(dataDDR) << 2U) |    \
434      ((uint8_t)(addrPad) << 3U) | ((uint16_t)(addrDDR) << 5U) | ((uint8_t)(instrPad) << 6U) |  \
435      ((uint16_t)(instrDDR) << 8U))
436 
437 #define SFDP_DECODE_PROTOCOL_TYPE(protocol)                                    \
438     do                                                                         \
439     {                                                                          \
440         instrPad = (sfdp_flash_pad_num_t)(((uint16_t)protocol & 0xC0U) >> 6U); \
441         instrDDR = (((uint16_t)protocol & 0x100U) >> 8U);                      \
442         addrPad  = (sfdp_flash_pad_num_t)(((uint16_t)protocol & 0x18U) >> 3U); \
443         addrDDR  = (((uint16_t)protocol & 0x20U) >> 5U);                       \
444         dataPad  = (sfdp_flash_pad_num_t)((uint16_t)protocol & 0x3);           \
445         dataDDR  = (((uint16_t)protocol & 0x4U) >> 2U);                        \
446     } while (0)
447 
448 /*!
449  * @brief The enumeration of protocol types.
450  *
451  * @details Command mode nomenclature used to indicate the number of active pins used for the instruction (A),
452  * address (B), and data (C), and the data rate used for each. Data rates(n) can be single (S) and dual (D).
453  * At the present time, the only valid Read SFDP command modes are: (1S-1S-1S), (2S-2S-2S), (4S-4S-4S), (4S-4D-4D),
454  * and (8D-8D-8D). (4S-4D-4D), and (8D-8D-8D) modes also use a Data Strobe (DS) as part of the communication protocol.
455  */
456 typedef enum _sfdp_protocol_type
457 {
458     kSFDP_Protocol_1s1s1s = SFDP_ENCODE_PROTOCOL_TYPE(
459         kSFDP_Flash1Pad, 0U, kSFDP_Flash1Pad, 0U, kSFDP_Flash1Pad, 0U, 0U), /*!< The protocol is 1s-1s-1s. */
460     kSFDP_Protocol_1s1d1d = SFDP_ENCODE_PROTOCOL_TYPE(
461         kSFDP_Flash1Pad, 0U, kSFDP_Flash1Pad, 1U, kSFDP_Flash1Pad, 1U, 0U), /*!< The protocol is 1s-1d-1d. */
462 
463     kSFDP_Protocol_1s1s2s = SFDP_ENCODE_PROTOCOL_TYPE(
464         kSFDP_Flash1Pad, 0U, kSFDP_Flash1Pad, 0U, kSFDP_Flash2Pad, 0U, 1U), /*!< The protocol is 1s-1s-2s. */
465     kSFDP_Protocol_1s2s2s = SFDP_ENCODE_PROTOCOL_TYPE(
466         kSFDP_Flash1Pad, 0U, kSFDP_Flash2Pad, 0U, kSFDP_Flash2Pad, 0U, 1U), /*!< The protocol is 1s-2s-2s. */
467     kSFDP_Protocol_1s2d2d = SFDP_ENCODE_PROTOCOL_TYPE(
468         kSFDP_Flash1Pad, 0U, kSFDP_Flash2Pad, 1U, kSFDP_Flash2Pad, 1U, 1U), /*!< The protocol is 1s-2d-2d. */
469     kSFDP_Protocol_2s2s2s = SFDP_ENCODE_PROTOCOL_TYPE(
470         kSFDP_Flash2Pad, 0U, kSFDP_Flash2Pad, 0U, kSFDP_Flash2Pad, 0U, 1U), /*!< The protocol is 2s-2s-2s. */
471 
472     kSFDP_Protocol_1s1s4s = SFDP_ENCODE_PROTOCOL_TYPE(
473         kSFDP_Flash1Pad, 0U, kSFDP_Flash1Pad, 0U, kSFDP_Flash4Pad, 0U, 2U), /*!< The protocol is 1s-1s-4s. */
474     kSFDP_Protocol_1s4s4s = SFDP_ENCODE_PROTOCOL_TYPE(
475         kSFDP_Flash1Pad, 0U, kSFDP_Flash4Pad, 0U, kSFDP_Flash4Pad, 0U, 2U), /*!< The protocol is 1s-4s-4s. */
476     kSFDP_Protocol_1s4d4d = SFDP_ENCODE_PROTOCOL_TYPE(
477         kSFDP_Flash1Pad, 0U, kSFDP_Flash4Pad, 1U, kSFDP_Flash4Pad, 1U, 2U), /*!< The protocol is 1s-4d-4d. */
478     kSFDP_Protocol_4s4s4s = SFDP_ENCODE_PROTOCOL_TYPE(
479         kSFDP_Flash4Pad, 0U, kSFDP_Flash4Pad, 0U, kSFDP_Flash4Pad, 0U, 2U), /*!< The protocol is 4s-4s-4s. */
480     kSFDP_Protocol_4s4d4d = SFDP_ENCODE_PROTOCOL_TYPE(
481         kSFDP_Flash4Pad, 0U, kSFDP_Flash4Pad, 1U, kSFDP_Flash4Pad, 1U, 2U), /*!< The protocol is 4s-4d-4d. */
482 
483     kSFDP_Protocol_1s1s8s = SFDP_ENCODE_PROTOCOL_TYPE(
484         kSFDP_Flash1Pad, 0U, kSFDP_Flash1Pad, 0U, kSFDP_Flash8Pad, 0U, 3U), /*!< The protocol is 1s-1s-8s. */
485     kSFDP_Protocol_1s8s8s = SFDP_ENCODE_PROTOCOL_TYPE(
486         kSFDP_Flash1Pad, 0U, kSFDP_Flash8Pad, 0U, kSFDP_Flash8Pad, 0U, 3U), /*!< The protocol is 1s-8s-8s. */
487     kSFDP_Protocol_1s8d8d = SFDP_ENCODE_PROTOCOL_TYPE(
488         kSFDP_Flash1Pad, 0U, kSFDP_Flash8Pad, 1U, kSFDP_Flash8Pad, 1U, 3U), /*!< The protocol is 1s-8d-8d. */
489     kSFDP_Protocol_8s8s8s = SFDP_ENCODE_PROTOCOL_TYPE(
490         kSFDP_Flash8Pad, 0U, kSFDP_Flash8Pad, 0U, kSFDP_Flash8Pad, 0U, 3U), /*!< The protocol is 8s-8s-8s. */
491     kSFDP_Protocol_8d8d8d = SFDP_ENCODE_PROTOCOL_TYPE(
492         kSFDP_Flash8Pad, 1U, kSFDP_Flash8Pad, 1U, kSFDP_Flash8Pad, 1U, 3U), /*!< The protocol is 8d-8d-8d. */
493 } sfdp_protocol_type_t;
494 
495 #define SFDP_4_BYTE_ADDR_INST_TABLE                                                                              \
496     {                                                                                                            \
497         0x13U, 0x0CU, 0x0EU, 0x3CU, 0xBCU, 0xBEU, 0xFFU, 0x34U, 0xECU, 0xEEU, 0xFFU, 0xFFU, 0x84U, 0x8EU, 0xFDU, \
498             0xFFU, 0xFFU                                                                                         \
499     }
500 
501 /*!
502  * @brief The structure of write status command information, including instruction.
503  *
504  */
505 typedef struct _sfdp_write_status_cmd_info
506 {
507     uint8_t instruction; /*!< The instruction to write status register. */
508 } sfdp_write_status_cmd_info_t;
509 
510 /*!
511  * @brief The structure of register bit information.
512  *
513  */
514 struct _sfdp_reg_bit_info
515 {
516     uint8_t readInstr;          /*!< Read instrution. */
517     uint8_t writeInstr;         /*!< Write instruction. */
518     uint8_t dummyCycles;        /*!< Default dummy cycles. */
519     bool polarity;              /*!< false: positive, value = 1 means write is in progress,
520                                   true: Inverted, value = 0 means write is in progress. */
521     uint8_t location;           /*!< Shift of bit field. */
522     bool addrFollowCmd;         /*!< If required the address followed command. */
523     bool upperHalfWordSelected; /*!< Upper half word or lower half word. */
524 };
525 
526 typedef struct _sfdp_reg_bit_info sfdp_wip_bit_info_t;
527 typedef struct _sfdp_reg_bit_info sfdp_wel_bit_info_t;
528 typedef struct _sfdp_reg_bit_info sfdp_program_error_bit_info_t;
529 typedef struct _sfdp_reg_bit_info sfdp_erase_error_bit_info_t;
530 
531 /*!
532  * @brief The structure of variable dummy cycle bit field information.
533  *
534  */
535 typedef struct _sfdp_variable_dummy_cycle
536 {
537     uint8_t writeInstr;         /*!< Write instruction. */
538     uint8_t readInstr;          /*!< Read instruction. */
539     uint8_t dummyCycles;        /*!< Number of dummy cycle used for command. */
540     uint8_t location;           /*!< Shift of bit field. */
541     bool upperHalfWordSelected; /*!< Upper half word or lower half word. */
542     bool addrFollowCmd;         /*!<  If required the address followed command. */
543     uint8_t bitFieldWidth;      /*!< Bit field width. */
544 } sfdp_variable_dummy_cycle_t;
545 
546 /*!
547  * @brief The enumeration of 4-byte address mode enter methods.
548  *
549  */
550 typedef enum _sfdp_4_byte_addr_enter_method
551 {
552     kSFDP_4ByteAddrEnterMethod0 = 1U << 0U, /*!< Issue instruction 0xB7h */
553     kSFDP_4ByteAddrEnterMethod1 = 1U << 1U, /*!< Issue write enable 0x06h then issue instruction 0xB7h */
554     kSFDP_4ByteAddrEnterMethod2 = 1U << 2U, /*!< Read with 0xCB, write instruction is C5h with 1 byte of data. */
555     kSFDP_4ByteAddrEnterMethod3 = 1U << 3U, /*!< When MSB is set to "1", 4-byte address mode is active, read with
556                                                 instruction 0x16h, write instruction is 0x17h with 1 byte of data. */
557     kSFDP_4ByteAddrEnterMethod4 = 1U << 4U, /*!< A 16-bit nonvolatile configuration register control 3-byte/4-byte
558                                                 address mode, read instruction is 0xB5h, Bit[0] controls address mode
559                                                 [0=3 Byte, 1=4 Byte], write configuration register instruction is
560                                                 0xB1h, data length is 2 bytes. */
561     kSFDP_4ByteAddrEnterMethod5 = 1U << 5U, /*!< Supports dedicated 4-byte address instruction set. */
562     kSFDP_4ByteAddrEnterMethod6 = 1U << 6U, /*!< Always operates in 4-byte address mode. */
563 } sfdp_4_byte_addr_enter_method_t;
564 
565 /*!
566  * @brief The enumeration of 4 byte address mode exit methods.
567  *
568  */
569 typedef enum _sfdp_4_byte_addr_exit_method
570 {
571     kSFDP_4ByteAddrExitMethod0 = 1U << 0U, /*!< Issue instruction 0xE9h to exit 4-byte address mode. */
572     kSFDP_4ByteAddrExitMethod1 = 1U << 1U, /*!< Issue write enable instruction 0x06, then issue instruction
573                                                 0xE9h to exit 4-byte address mode. */
574     kSFDP_4ByteAddrExitMethod2 = 1U << 2U, /*!< 8-bit volatile extended address register used to defined A[31:24] bits,
575                                                read with instruction 0xC8h, write instruction is C5h, data length is 1
576                                                byte, return to lowest memory segment by setting A[31:24] to 0x0 and use
577                                                3-bte addressing. */
578     kSFDP_4ByteAddrExitMethod3 = 1U << 3U, /*!< 8-bit volatile bank register used to define A[30:24] bit, MSB is used
579                                                to enable/disable 4-byte address mode, when MSB is cleared to 0, 3-byte
580                                                address mode is active and A30:A24 are used to select the active 128Mbit
581                                                memory segment, read with instruction 0x16h, write instruction is 0x17h,
582                                                data length is 1byte. */
583     kSFDP_4ByteAddrExitMethod4 = 1U << 4U, /*!< A 16-bit nonvolatile configuration register control 3-byte/4-byte
584                                                address mode, read instruction is 0xB5h, Bit[0] controls address mode
585                                                [0=3 Byte, 1=4 Byte], write configuration register instruction is
586                                                0xB1h, data length is 2 bytes. */
587     kSFDP_4ByteAddrExitMethod5 = 1U << 5U, /*!< Hardware reset. */
588     kSFDP_4ByteAddrExitMethod6 = 1U << 6U, /*!< Software reset. */
589     kSFDP_4ByteAddrExitMethod7 = 1U << 7U, /*!< Power cycle. */
590 } sfdp_4_byte_addr_exit_method_t;
591 
592 /*!
593  * @brief The enumeration of policy used to get supported protocol, please refer to @ref sfdp_protocol_type_t.
594  */
595 typedef enum _sfdp_cmd_policy
596 {
597     kSFDP_CmdPolicy_HighestThroughput = 0U, /*!< Use this policy to select the supported read command that result in
598                                            highest throughput. */
599     kSFDP_CmdPolicy_DdrIO            = 1U,  /*!< Both input and output are in DTR(DDR) mode. */
600     kSFDP_CmdPolicy_DdrOutput        = 2U,  /*!< Only output is in DTR(DDR) mode. */
601     kSFDP_CmdPolicy_LowestThroughput = 3U,  /*!< Use this policy to select the supported read command that result in
602                                            lowest throughput. */
603 
604     kSFDP_CmdPolicy_SdrIO     = 4U,         /*!< Both input and output are in STR(SDR) mode. */
605     kSFDP_CmdPolicy_SdrOutput = 5U,         /*!< Only output is in STR(SDR) mode. */
606 } sfdp_cmd_policy_t;
607 #define SFDP_CMD_POLICY_COUNT (6U)
608 
609 /*!
610  * @brief The structure of read command information, including instruction, dummy cycle, and mode clocks.
611  */
612 typedef struct _sfdp_read_cmd_info
613 {
614     uint8_t instruction; /*!< The read instruction. */
615     uint8_t dummyCycle;  /*!< The default dummy cycle of read instruction. */
616     uint8_t modeClocks;  /*!< Mode bit clocks. */
617 } sfdp_read_cmd_info_t;
618 
619 /*!
620  * @brief The structure of chip erase command information, including instruction and typical time to erase whole chip.
621  *
622  */
623 typedef struct _sfdp_chip_erase_cmd_info
624 {
625     uint8_t instruction;  /* Instruction to erase whole chip. */
626     uint32_t typicalTime; /* Typical time to erase whole chip, the unit is ms. */
627 } sfdp_chip_erase_cmd_info_t;
628 
629 /*!
630  * @brief The structure of erase command information, including size, instruction and typical time to erase
631  * specific size.
632  */
633 typedef struct _sfdp_erase_cmd_info
634 {
635     uint32_t eraseSize;   /*!< Size of memory to erase, the unit is byte. */
636     uint8_t instruction;  /*!< Instruction to erase specific size of memory. */
637     uint32_t typicalTime; /*!< Typical time to erase specific size of memory, the unit is ms. */
638 } sfdp_erase_cmd_info_t;
639 
640 /*!
641  * @brief The enumeration of erase command type.
642  */
643 typedef enum _sfdp_erase_cmd_type
644 {
645     kSFDP_EraseCmdType1 = 0U, /*!< Erase command type 1. */
646     kSFDP_EraseCmdType2 = 1U, /*!< Erase command type 2. */
647     kSFDP_EraseCmdType3 = 2U, /*!< Erase command type 3. */
648     kSFDP_EraseCmdType4 = 3U, /*!< Erase command type 4. */
649 } sfdp_erase_cmd_type_t;
650 
651 /*!
652  * @brief The structure of page program command information, including instruction and typical time to program the
653  * specific page.
654  *
655  */
656 typedef struct _sfdp_page_program_cmd_info
657 {
658     uint8_t instruction;  /*!< The instruction of page program. */
659     uint32_t typicalTime; /*!< Typical time to program page, the unit is us. */
660 } sfdp_page_program_cmd_info_t;
661 
662 /*!
663  * @brief The structure of read status command information, including instruction, address size a
664  *
665  */
666 typedef struct _sfdp_read_status_cmd_info
667 {
668     uint8_t instruction; /*!< The read status instruction. */
669     uint8_t addrSize;    /*!< Number of address size for generic addressable read/write
670                            status/control register instruction. */
671     uint8_t dummyCycle;  /*!< Number of dummy cycle. */
672 } sfdp_read_status_cmd_info_t;
673 
674 typedef status_t (*SFDP_SpiReadFunc)(uint32_t address, uint32_t *outputBuffer, uint32_t sizeInBytes);
675 
676 /*!
677  * @brief The enumeration of cmd supported in xspi 1.0 and xspi 2.0 profile.
678  *
679  */
680 typedef enum _sfdp_xspi_profile_opi_cmd
681 {
682     kSFDP_OPICmd_ReadSfdp = 0U,        /*!< Read SFDP command. */
683     kSFDP_OPICmd_Erase4K,              /*!< Erase 4K command. */
684     kSFDP_OPICmd_EraseChip,            /*!< Erase chip command. */
685     kSFDP_OPICmd_WriteStatusConfigReg, /*!< Write status configuration register command. */
686     kSFDP_OPICmd_ReadConfigReg,        /*!< Read configuration register command. */
687     kSFDP_OPICmd_ReadStatusReg,        /*!< Read status register command. */
688     kSFDP_OPICmd_WriteStatusReg,       /*!< Write status register command. */
689 } sfdp_xspi_profile_opi_cmd_t;
690 #define SFDP_XSPI_PROFILE_OPI_CMD_COUNT (7U)
691 
692 /*!
693  * @brief The enumeration of 0-4-4 mode entry method.
694  *
695  */
696 typedef enum _sfdp_044_mode_entry_method
697 {
698     kSFDP_044ModeEntryMethod0 =
699         1U << 0U, /*!< Mode Bits[7:0] = A5h, note that QE must be set prior to using this mode. */
700     kSFDP_044ModeEntryMethod1 = 1U << 1U, /*!< Read volatile configuration register with instruction 85h, set bit 3(XIP)
701                                             in the data read, and write the modified data using the instruction 81h. */
702     kSFDP_044ModeEntryMethod2 = 1U << 2U, /*!< Mode Bit[7:0]= AXh */
703 } sfdp_044_mode_entry_method_t;
704 
705 /*!
706  * @brief The enumeration of 0-4-4 mode exit method.
707  *
708  */
709 typedef enum _sfdp_044_mode_exit_method
710 {
711     kSFDP_044ModeExitMethod0 = 1U << 0U, /*!< Mode Bit[7:0] = 00h will terminate 0-4-4 mode
712                                             at the end of the current read operation. */
713     kSFDP_044ModeExitMethod1 = 1U << 1U, /*!< If 3-byte address active, input Fh in IO0-IO3 for 8 clocks,
714                                             if 4-byte address active, input Fh on IO0-IO3 for 10 clocks. */
715     kSFDP_044ModeExitMethod2 = 1U << 3U, /*!< Input Fh on IO0-IO3 for 8 clocks. */
716     kSFDP_044ModeExitMethod3 = 1U << 4U, /*!< Mode Bit[7:0] != AXh. */
717 } sfdp_044_mode_exit_method_t;
718 
719 /*!
720  * @brief The enumeration of 0-8-8 mode entry method.
721  *
722  */
723 typedef enum _sfdp_088_mode_entry_method
724 {
725     kSFDP_088ModeEntryNotSupported = 0U, /*!< Device does not support 0-8-8 mode. */
726     kSFDP_088ModeEntryMethod1      = 1U, /*!< Read the 8-bit volatile configuration register with instruction 85h, set
727                                              XIP bit[0] in the data read, and write the modified data using the instruction
728                                              81h, then mode bits[7:0] = 01h. */
729 } sfdp_088_mode_entry_method_t;
730 
731 /*!
732  * @brief The enumeration of 0-8-8 mode exit method.
733  *
734  */
735 typedef enum _sfdp_088_mode_exit_method
736 {
737     kSFDP_088ModeExitNotSupported = 0U,  /*!< Device does not support 0-8-8 mode. */
738     kSFDP_088ModeExitMethod1 = 1U << 0U, /*!< Mode Bits[7:0] = 00h will terminate this mode at the end of the current
739                                         read operation. */
740     kSFDP_088ModeExitMethod2 = 1U << 1U, /*!< If 3-byte address active, input FFh on DQ0-DQ7 for 4 clocks, if 4-byte
741                                         address active input Fh on DQ0-DQ7 for 5 clocks. */
742 } sfdp_088_mode_exit_method_t;
743 
744 /*!
745  * @brief The enumeration of 4s-4s-4s mode enable method from 1s-1s-1s mode.
746  */
747 typedef enum _sfdp_4s4s4s_mode_enable_method
748 {
749     kSFDP_4s4s4sModeEnableMethod0 = 1U << 0U, /*!< set QE per QER, then issue instruction 38h. */
750     kSFDP_4s4s4sModeEnableMethod1 = 1U << 1U, /*!< Issue instruction 38h. */
751     kSFDP_4s4s4sModeEnableMethod2 = 1U << 2U, /*!< Issue instruction 35h. */
752     kSFDP_4s4s4sModeEnableMethod3 = 1U << 3U, /*!< Read configuration using instruction 65h followed by address 800003h,
753                                                 set bit 6, write configuration using instruction 71h followed by
754                                                 address 800003h. */
755     kSFDP_4s4s4sModeEnableMethod4 = 1U << 4U, /*!< Read volatile enhanced configuration using instruction 65h, no
756                                                 address is required, set bit 7 to 1, write volatile enhanced
757                                                 configuration using instruction 61h, no address is required. */
758 } sfdp_4s4s4s_mode_enable_method_t;
759 
760 /*!
761  * @brief The enumeration of 4s-4s-4s mode disable method
762  *
763  */
764 typedef enum _sfdp_4s4s4s_mode_disable_method
765 {
766     kSFDP_4s4s4sModeDisableMethod0 = 1U << 0U, /*!< Issue FFh instruction. */
767     kSFDP_4s4s4sModeDisableMethod1 = 1U << 1U, /*!< Issue F5h instruction. */
768     kSFDP_4s4s4sModeDisableMethod2 = 1U << 2U, /*!< Read configuration using instruction 65h followed by address
769                                                 800003h, clear bit 6, write configuration using instruction 71h followed
770                                                 by address 800003h. */
771     kSFDP_4s4s4sModeDisableMethod3 = 1U << 3U, /*!< Issue software reset 66/99 sequence. */
772     kSFDP_4s4s4sModeDisableMethod4 = 1U << 4U, /* Read volatile enhanced configuration using instruction 65h, no address
773                                                 is required, clear bit 7, write volatile enhanced configuration using
774                                                 instruction 61h, no address is required. */
775 } sfdp_4s4s4s_mode_disable_method_t;
776 
777 /*!
778  * @brief The enumeration of 8s-8s-8s mode enable method from 1s-1s-1s mode.
779  *
780  */
781 typedef enum _sfdp_8s8s8s_mode_enable_method
782 {
783     kSFDP_8s8s8sModeEnableMethod0 = 1U << 1U, /*!< Issue instruction 06h, then issue instruction E8h. */
784     kSFDP_8s8s8sModeEnableMethod1 = 1U << 2U, /*!< Issue instruction 06h, then issue instruction 72h(address = 0h,
785                                                data=01h or 02h). */
786 } sfdp_8s8s8s_mode_enable_method_t;
787 
788 /*!
789  * @brief The enumeration of 8s-8s-8s mode disable method.
790  *
791  */
792 typedef enum _sfdp_8s8s8s_mode_disable_method
793 {
794     kSFDP_8s8s8sModeDisableMethod0 = 1U << 0U, /*!< Issue instruction 06h, then issue FFh instruction. */
795     kSFDP_8s8s8sModeDisableMethod1 = 1U << 3U, /*!< Issue the soft reset sequence. */
796 } sfdp_8s8s8s_mode_disable_method_t;
797 
798 /*!
799  * @brief The structure of erase/suspend resume command information, including suspend instruction, resume
800  * instruction, erase maximum latency, resume to suspend interval.
801  *
802  */
803 typedef struct _sfdp_erase_suspend_resume_cmd_info
804 {
805     uint8_t suspendInstr;     /*!< Suspend instruction. */
806     uint8_t resumeInstr;      /*!< Resume instruction. */
807     uint32_t eraseMaxLatency; /*!< Maximum time required by the flash device to suspend an in-progress erase, the unit
808                                  is ns.  */
809     uint32_t resumeToSuspendInterval; /*!< The interval between the resumed erase operation to another suspend, the unit
810                                          is us. */
811 } sfdp_erase_suspend_resume_cmd_info_t;
812 
813 /*!
814  * @brief The structure of program suspend command information, including suspend instruction, resume instruction,
815  * erase maximum latency, resume to suspend interval.
816  *
817  */
818 typedef struct _sfdp_program_suspend_cmd_info
819 {
820     uint8_t suspendInstr;     /*!< Suspend instruction. */
821     uint8_t resumeInstr;      /*!< Resume instruction. */
822     uint32_t eraseMaxLatency; /*!< Maximum time required by the flash device to suspend an in-progress erase, the unit
823                                  is ns.  */
824     uint32_t resumeToSuspendInterval; /*!< The interval between the resumed erase operation to another suspend, the unit
825                                          is us. */
826 } sfdp_program_suspend_cmd_info_t;
827 
828 /*!
829  * @brief The structure of deep power down command information, including enter/exit instruction, exit deep power down
830  * delay.
831  *
832  */
833 typedef struct _sfdp_deep_power_down_cmd_info
834 {
835     uint8_t enterDeepPowerDownInstr; /*!< Instruction of enter deep power down mode. */
836     uint8_t exitDeepPowerDownInstr;  /*!< Instruction of exit deep power down mode. */
837     uint32_t exitDeepPowerDownDelay; /*!< Maximum time required by the flash device to exit deep power down and be
838                                         ready to accept any command, the unit is ns. */
839 } sfdp_deep_power_down_cmd_info_t;
840 
841 /*!
842  * @brief The enumeration of quad enable method, the quad enable bit used to enable 1s-1s-4s and 1s-4s-4s quad read
843  * or quad program operations.
844  *
845  */
846 typedef enum _sfdp_quad_enable_method
847 {
848     kSFDP_QuadEnableNotSupported = 0U, /*!< Device doest not have a QE bit, device detects 1s-1s-4s and 1s-4s-4s reads
849                                        based on instruction. */
850     kSFDP_QuadEnableMethod1 = 1U,      /*!< QE is bit 1 of status register 2, it is set via write status with two data
851                                          bytes where bit 1 of the second byte is one, it is cleared via write status with two
852                                          data bytes where bit 1 of the second byte is zero. */
853     kSFDP_QuadEnableMethod2 = 2U, /*!< QE is bit 6 of status register 1, it is set via write status with one data byte
854                                     where bit 6 is one, it is cleared via write status with one data byte where bit 6
855                                     is zero. */
856     kSFDP_QuadEnableMethod3 = 3U, /*!< QE is bit 7 of status register 2, it is set via write status register 2
857                                 instruction 3Eh with one data byte where bit 7 is one, it is cleared via write status
858                                 register 2 instruction 3Eh with one data byte where bit 7 is zero, the status register
859                                 2 is read using instruction 3Fh. */
860     kSFDP_QuadEnableMethod4 = 4U, /*!< QE is bit 1 of status register 2, it is set via write status with two data bytes
861                                 where bit 1 of the second byte is one, it is cleared via write status with two data
862                                 bytes where bit 1 of the second byte is zero. */
863     kSFDP_QuadEnableMethod5 = 5U, /*!< QE is bit 1 of status register 2, using 05h to read status register 1, using 35h
864                                 to read status register 2, it is set via write status instruction 01h with two data
865                                 bytes where bit 1 of the second byte is one, it is cleared via write status with two
866                                 data bytes where bit 1 of the second byte is zero. */
867     kSFDP_QuadEnableMethod6 = 6U, /*!< QE is bit 1 of status register 2, using 05h to read status register 1, using 35h
868                                 to read status register 2, using 15h to read status register 3, it is set via write
869                                 status instruction 31h with two data bytes where bit 1 of the second byte is one, it is
870                                 cleared via write status with two data bytes where bit 1 of the second byte is zero. */
871 } sfdp_quad_enable_method_t;
872 
873 /*!
874  * @brief The enumeration of software reset method.
875  *
876  */
877 typedef enum _sfdp_soft_reset_method
878 {
879     kSFDP_SoftResetNotSupported = 0U,       /*!< No software reset instruction is supported. */
880     kSFDP_SoftResetMethod1      = 1U << 0U, /*!< Drive Fh on all 4 data wires for 8 clocks. */
881     kSFDP_SoftResetMethod2      = 1U << 1U, /*!< Drive Fh on all 4 data wires for 10 clocks if device is operating in
882                                             4-byte address mode. */
883     kSFDP_SoftResetMethod3 = 1U << 2U,      /*!< Drive Fh on all 4 data wires for 16 clocks. */
884     kSFDP_SoftResetMethod4 = 1U << 3U,      /*!< Issue instruction F0h. */
885     kSFDP_SoftResetMethod5 = 1U << 4U, /*!< Issue reset enable instruction 66h, then issue reset instruction 99h. */
886     kSFDP_SoftResetMethod6 = 1U << 5U, /*!< Issue 0-4-4 mode is required prior to other reset sequence above if the
887                                         device may be operating in this mode. */
888 } sfdp_soft_reset_method_t;
889 
890 /*!
891  * @brief The enumeration of octal enable method, the octal enable bit used to enable 1s-1s-8s and 1s-8s-8s octal read
892  * or octal program operations.
893  *
894  */
895 typedef enum _sfdp_octal_enable_method
896 {
897     kSFDP_OctalEnableNotSupported = 0U, /*!< Device does not have an octal enable bit. */
898     kSFDP_OctalEnableMethod1 = 1U, /*!< Octal enable is bit 3 of status register, it is set via write status register2
899                                     instruction 31h with one data byte where bit 3 is one, it is cleared via write
900                                     register instruction 3Eh with one data byte where bit 3 is zero, the status
901                                     register 2 is read using instruction 65h with address byte 02h and one dummy
902                                     cycle. */
903 } sfdp_octal_enable_method_t;
904 
905 /*!
906  * @brief The structure of octal ddr or quad ddr entry sequence format.
907  *
908  */
909 typedef union _sfdp_entry_seq_format
910 {
911     struct
912     {
913         uint8_t byte3;  /*!< 3rd byte of sequence. */
914         uint8_t byte2;  /*!< 2nd byte of sequence. */
915         uint8_t byte1;  /*!< 1st byte of sequence. */
916         uint8_t length; /*!< length of sequence. */
917         uint8_t byte7;  /*!< 7th byte of sequence. */
918         uint8_t byte6;  /*!< 6th byte of sequence. */
919         uint8_t byte5;  /*!< 5th byte of sequence. */
920         uint8_t byte4;  /*!< 4th byte of sequence. */
921     } seqStruct;        /*!< The sequence format in structure format. */
922     uint64_t seqU64;    /*!< The sequence format in uint64 format. */
923 } sfdp_entry_seq_format_t;
924 
925 /*!
926  * @brief The structure of 8d-8d-8d(octal ddr) mode entry sequences.
927  *
928  */
929 typedef struct _sfdp_8d8d8d_entry_seq
930 {
931     sfdp_entry_seq_format_t seq1; /*!< 1st sequence. */
932     sfdp_entry_seq_format_t seq2; /*!< 2nd sequence. */
933     sfdp_entry_seq_format_t seq3; /*!< 3rd sequence. */
934     sfdp_entry_seq_format_t seq4; /*!< 4th sequence. */
935 } sfdp_8d8d8d_entry_seq_t;
936 
937 /*!
938  * @brief The macro used to get command in the sequence.
939  *     - idx: range from 1 to 7
940  *     - seq: The sequence data in type of #sfdp_entry_seq_format_t.
941  */
942 #define SFDP_GET_SEQ_CMD(seq, idx) \
943     (uint8_t)(((seq).seqU64 >> (8ULL * (((idx) / 4ULL) * 4ULL + (3ULL - (idx) % 4ULL)))) & 0xFFULL)
944 
945 /*!
946  * @brief The structure of 4s-4d-4d(quad ddr) entry sequence.
947  *
948  */
949 typedef struct _sfdp_4s4d4d_entry_seq
950 {
951     sfdp_entry_seq_format_t seq1; /*!< 1st sequence. */
952     sfdp_entry_seq_format_t seq2; /*!< 2nd sequence. */
953     sfdp_entry_seq_format_t seq3; /*!< 3rd sequence. */
954     sfdp_entry_seq_format_t seq4; /*!< 4th sequence. */
955 } sfdp_4s4d4d_entry_seq_t;
956 
957 /*!
958  * @brief The handle of sfdp, included all sfdp parameter table.
959  *
960  */
961 typedef struct _sfdp_handle
962 {
963     sfdp_basic_flash_param_table_t bfp;                               /*!< Basic flash parameter table. */
964     sfdp_sector_map_param_table_t sectorMapTable;                     /*!< Sector map parameter table. */
965     sfdp_rpmc_param_table_t rpmcTable;                                /*!< Replay protected monotonic counters
966                                                                       parameter table. */
967     sfdp_4_byte_addr_instruction_param_table_t fourByteAddrInstTable; /*!< 4-byte address instruction
968                                                                         parameter table. */
969     sfdp_xSPI_profile1_param_table_t xSPIProfile1Table;               /*!< eXtended serial peripheral interface profile
970                                                                           1.0 parameter table. */
971     sfdp_xSPI_profile2_param_table_t xSPIProfile2Table;               /*!< eXtended serial peripheral interface profile
972                                                                           2.0 parameter table. */
973     sfdp_sccr_param_table_t SCCRegMapTable;                   /*!< Status, control, and Configuration register map
974                                                               for SPI memory devices. */
975     sfdp_sccr_profile2_param_table_t SCCRegMapMultiChipTable; /*!< Status, control and configuration register map
976                                                           for xSPI profile 2.0 memory devices. */
977     sfdp_sccr_multi_dies_addr_offset_param_table_t SCCRegMapxSPIProfile2Table; /*!< Status, control and configuration
978                                                            register map offset for multi-chip SPI memory devices. */
979     sfdp_command_seq_to_octal_param_table_t cmdSeq2OctalDDR;                   /*!< Command sequences to change to
980                                                                                octal DTR(DDR) mode. */
981     sfdp_command_seq_to_quad_param_table_t cmdSeq2QuadDDR;                     /*!< Command sequences to change to
982                                                                                   Quad DTR(DDR) mode. */
983     sfdp_x4_quad_with_DS_param_table_t x4QualIOWithDS;             /*!< x4 Quad IO with DS parameter table. */
984     sfdp_secure_packet_read_write_param_table securePacketRWTable; /*!< Secure packet READ/WRITE parameter table. */
985 
986     SFDP_SpiReadFunc spiRead;                                      /*!< The function of read sfdp. */
987     sfdp_revsion_t curJEDECVersion;                                /*!< JEDEC version of current serial flash device. */
988     uint8_t nph;                                                   /* Counts of parameter tables. */
989     uint8_t access;            /*!< Current serial flash device's access protocol. */
990     sfdp_addr_mode_t addrMode; /*!< Current serial flash device's address mode. */
991 } sfdp_handle_t;
992 
993 /*******************************************************************************
994  * API
995  ******************************************************************************/
996 
997 /*!
998  * @name Read SFDP Data Sets
999  * @{
1000  */
1001 
1002 /*!
1003  * @brief Read SFDP header, and check if SFDP signature is correct.
1004  *
1005  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1006  * @param[in] spiRead The function to read sfdp header.
1007  *
1008  * @retval kSFDP_RET_HardwareIssue Fail to read SFDP header due to some hardware issue.
1009  * @retval kSFDP_RET_Invalid Fail to read SFDP header due to invalid SFDP signature.
1010  * @retval kSFDP_RET_Success Successfully to read sfdp header.
1011  */
1012 sfdp_ret_type_t SFDP_ReadSFDPHeader(sfdp_handle_t *handle, SFDP_SpiReadFunc spiRead);
1013 
1014 /*!
1015  * @brief Read SFDP parameter header.
1016  *
1017  * @param[out] ptrSfdpParamHeader Pointer to the variable in type of @ref sfdp_param_header_t
1018                                 to store sfdp parameter header.
1019  * @param[in] nph Number of parameter header.
1020  * @param[in] spiRead Function to read sfdp parameter header.
1021  *
1022  * @retval kStatus_Success Successfully to read SFDP parameter header.
1023  * @retval kSFDP_RET_HardwareIssue Fail to read SFDP parameter header due to some hardware issues.
1024  */
1025 sfdp_ret_type_t SFDP_ReadSFDPParameterHeader(sfdp_param_header_t *ptrSfdpParamHeader,
1026                                              uint8_t nph,
1027                                              SFDP_SpiReadFunc spiRead);
1028 
1029 /*!
1030  * @brief Read all current serial flash device supported parameter tables.
1031  *
1032  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1033  *
1034  * @retval kSFDP_RET_HardwareIssue Fail to read SFDP parameter header due to some hardware issues.
1035  * @retval kSFDP_RET_Success Successfully to read all supported parameter tables.
1036  */
1037 sfdp_ret_type_t SFDP_ReadAllSupportedTable(sfdp_handle_t *handle);
1038 
1039 /* @} */
1040 
1041 /*!
1042  * @name Get Flash Basic Attributes
1043  * @{
1044  */
1045 
1046 /*!
1047  * @brief Get Flash Density, the result in unit of KB.
1048 
1049  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1050  *
1051  * @return In unit of KB, 64 means 64KB(512 Kb)
1052  */
1053 uint32_t SFDP_GetFlashDensity(sfdp_handle_t *handle);
1054 
1055 /*!
1056  * @brief Get page size, the result in unit of Byte.
1057  *
1058  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1059  *
1060  * @return The size of page.
1061  */
1062 uint32_t SFDP_GetPageSize(sfdp_handle_t *handle);
1063 
1064 /*!
1065  * @brief Get flash interface mode based on input policy, and number of data pad.
1066  *
1067  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1068  * @param[in] cmdPolicy The policy used to select interface mode, in type of @ref sfdp_cmd_policy_t.
1069  * @param[in] flashPadNum The number of data pad, in type of @ref sfdp_flash_pad_num_t
1070  *
1071  * @return Calculated protocol type, in type of @ref sfdp_protocol_type_t.
1072  */
1073 sfdp_protocol_type_t SFDP_GetFlashProtocolType(sfdp_handle_t *handle,
1074                                                sfdp_cmd_policy_t cmdPolicy,
1075                                                sfdp_flash_pad_num_t flashPadNum);
1076 
1077 /*!
1078  * @brief Check if DTR(DDR) is supported.
1079  *
1080  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1081  *
1082  * @retval true DTR clocking supported.
1083  * @retval false DTR NOT supported.
1084  */
SFDP_CheckDTRSupported(sfdp_handle_t * handle)1085 static inline bool SFDP_CheckDTRSupported(sfdp_handle_t *handle)
1086 {
1087     assert(handle != NULL);
1088     return (bool)((handle->bfp.dw1 & 0x80000UL) != 0UL);
1089 }
1090 
1091 /*!
1092  * @brief Get serial flash device's address mode.
1093  *
1094  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1095  *
1096  * @return Serial flash device's address mode, in type of @ref sfdp_addr_mode_t.
1097  */
SFDP_GetAddressBytes(sfdp_handle_t * handle)1098 static inline sfdp_addr_mode_t SFDP_GetAddressBytes(sfdp_handle_t *handle)
1099 {
1100     assert(handle != NULL);
1101 
1102     return (sfdp_addr_mode_t)((handle->bfp.dw1 & 0x60000UL) >> 17UL);
1103 }
1104 
1105 /*!
1106  * @brief Check if serial flash device support suspend operations.
1107  *
1108  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1109  *
1110  * @retval false Suspend operation not supported.
1111  * @retval true Suspend operation supported.
1112  */
SFDP_CheckSuspendSupported(sfdp_handle_t * handle)1113 static inline bool SFDP_CheckSuspendSupported(sfdp_handle_t *handle)
1114 {
1115     return (bool)((handle->bfp.dw12 & (1UL << 31UL)) == 0UL);
1116 }
1117 
1118 /*!
1119  * @brief Check if serial flash device support deep power down operations.
1120  *
1121  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1122  *
1123  * @retval false Deep power down operation not supported.
1124  * @retval true Deep power down operation supported.
1125  */
SFDP_CheckDeepPowerDownSupported(sfdp_handle_t * handle)1126 static inline bool SFDP_CheckDeepPowerDownSupported(sfdp_handle_t *handle)
1127 {
1128     return (bool)((handle->bfp.dw14 & (1UL << 31UL)) == 0UL);
1129 }
1130 
1131 /*!
1132  * @brief Get 4 byte address mode enter method, only workable when serial flash device support 4-byte
1133  * address mode.
1134  *
1135  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1136  * @return 4-byte address mode enter method of serial flash device, please refer to
1137  * @ref sfdp_4_byte_addr_enter_method_t for details.
1138  */
SFDP_Get4ByteAddrModeEnterMethod(sfdp_handle_t * handle)1139 static inline sfdp_4_byte_addr_enter_method_t SFDP_Get4ByteAddrModeEnterMethod(sfdp_handle_t *handle)
1140 {
1141     return (sfdp_4_byte_addr_enter_method_t)(uint32_t)((handle->bfp.dw16 & 0xFF000000UL) >> 24UL);
1142 }
1143 
1144 /*!
1145  * @brief Get 4 byte address mode exit method, only workable when serial flash device support 4-byte
1146  * address mode.
1147  *
1148  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1149  * @return 4-byte address mode exit method of serial flash device, please refer to
1150  * sfdp_4_byte_addr_exit_method_t for details.
1151  */
SFDP_Get4ByteAddrModeExitMethod(sfdp_handle_t * handle)1152 static inline sfdp_4_byte_addr_exit_method_t SFDP_Get4ByteAddrModeExitMethod(sfdp_handle_t *handle)
1153 {
1154     return (sfdp_4_byte_addr_exit_method_t)(uint32_t)((handle->bfp.dw16 & 0xFFC000UL) >> 14UL);
1155 }
1156 
1157 /*!
1158  * @brief Get software reset method.
1159  *
1160  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1161  * @return Serial flash device software reset method, please refer to @ref sfdp_soft_reset_method_t for details.
1162  */
SFDP_GetSoftResetMethod(sfdp_handle_t * handle)1163 static inline sfdp_soft_reset_method_t SFDP_GetSoftResetMethod(sfdp_handle_t *handle)
1164 {
1165     return (sfdp_soft_reset_method_t)((handle->bfp.dw16 & 0x3F00UL) >> 8UL);
1166 }
1167 
1168 /* @} */
1169 
1170 /*!
1171  * @name Get QPI Attributes
1172  * @{
1173  */
1174 
1175 /*!
1176  * @brief Get supported method to enable 1s-1s-4s and 1s-4s-4s mode.
1177  *
1178  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1179  * @return The serial flash device supported quad enable method, please refer to @ref sfdp_quad_enable_method_t for
1180  * details.
1181  */
SFDP_GetQuadEnableMethod(sfdp_handle_t * handle)1182 static inline sfdp_quad_enable_method_t SFDP_GetQuadEnableMethod(sfdp_handle_t *handle)
1183 {
1184     return (sfdp_quad_enable_method_t)((handle->bfp.dw15 & 0x700000UL) >> 20UL);
1185 }
1186 
1187 /*!
1188  * @brief Check if serial flash device support 0-4-4 mode.
1189  *
1190  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1191  *
1192  * @retval false Current serial flash device do not support 0-4-4 mode.
1193  * @retval true Current serial flash device support 0-4-4 mode.
1194  */
SFDP_Check044ModeSupported(sfdp_handle_t * handle)1195 static inline bool SFDP_Check044ModeSupported(sfdp_handle_t *handle)
1196 {
1197     return ((handle->bfp.dw15 & 0x200UL) != 0UL);
1198 }
1199 
1200 /*!
1201  * @brief Get supported method to entry 0-4-4 mode.
1202  *
1203  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1204  * @return The serial flash device supported method to enter 0-4-4 mode, please refer to
1205  * @ref sfdp_044_mode_entry_method_t for details.
1206  */
SFDP_Get044ModeEntryMethod(sfdp_handle_t * handle)1207 static inline sfdp_044_mode_entry_method_t SFDP_Get044ModeEntryMethod(sfdp_handle_t *handle)
1208 {
1209     return (sfdp_044_mode_entry_method_t)((handle->bfp.dw15 & 0xF0000UL) >> 16UL);
1210 }
1211 
1212 /*!
1213  * @brief Get support method to exit 0-4-4 mode.
1214  *
1215  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1216  * @return The serial flash device supported method to exit 0-4-4 mode, please refer to
1217  * @ref sfdp_044_mode_exit_method_t for details.
1218  */
SFDP_Get044ModeExitMethod(sfdp_handle_t * handle)1219 static inline sfdp_044_mode_exit_method_t SFDP_Get044ModeExitMethod(sfdp_handle_t *handle)
1220 {
1221     return (sfdp_044_mode_exit_method_t)((handle->bfp.dw15 & 0xFC00UL) >> 10U);
1222 }
1223 
1224 /*!
1225  * @brief Get supported method to enable 4s-4s-4s mode from 1s-1s-1s mode.
1226  *
1227  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1228  * @return The serial flash device supported method to enable 4s-4s-4s mode, please refer to
1229  * @ref sfdp_4s4s4s_mode_enable_method_t for details.
1230  */
SFDP_Get4s4s4sModeEnableMethod(sfdp_handle_t * handle)1231 static inline sfdp_4s4s4s_mode_enable_method_t SFDP_Get4s4s4sModeEnableMethod(sfdp_handle_t *handle)
1232 {
1233     return (sfdp_4s4s4s_mode_enable_method_t)((handle->bfp.dw15 & 0x1F0UL) >> 4U);
1234 }
1235 
1236 /*!
1237  * @brief Get supported method to disable 4s-4s-4s mode.
1238  *
1239  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1240  * @return The serial flash device supported method to disable 4s-4s-4s mode, please refer to
1241  * @ref sfdp_4s4s4s_mode_disable_method_t for details.
1242  */
SFDP_Get4s4s4sModeDisableMethod(sfdp_handle_t * handle)1243 static inline sfdp_4s4s4s_mode_disable_method_t SFDP_Get4s4s4sModeDisableMethod(sfdp_handle_t *handle)
1244 {
1245     if (SFDP_Get4s4s4sModeEnableMethod(handle) == kSFDP_4s4s4sModeEnableMethod4)
1246     {
1247         return kSFDP_4s4s4sModeDisableMethod4;
1248     }
1249     else
1250     {
1251         return (sfdp_4s4s4s_mode_disable_method_t)(handle->bfp.dw15 & 0xFUL);
1252     }
1253 }
1254 
1255 /*!
1256  * @brief Get sequence to entry 4s-4d-4d mode.
1257  *
1258  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1259  * @param[out] ptrEntrySe The parameter to store sequences to enter 4s-4d-4d mode,
1260                         in type of @ref sfdp_4s4d4d_entry_seq_t.
1261  *
1262  * @retval kSFDP_RET_Success Successfully to get 4s-4d-4d entry sequence.
1263  * @retval kSFDP_RET_NotImplemented Current serial flash device does not support 4s-4d-4d entry sequence.
1264  */
1265 sfdp_ret_type_t SFDP_Get4s4d4dEntrySeq(sfdp_handle_t *handle, sfdp_4s4d4d_entry_seq_t *ptrEntrySeq);
1266 
1267 /*!
1268  * @brief Check if Data strobe supported in Quad SPI DTR(DDR) mode.
1269  *
1270  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1271  *
1272  * @retval false Data strobe not supported in Quad SPI DTR mode.
1273  * @retval true  Data strobe supported in Quad SPI DTR mode.
1274  */
SFDP_CheckDSSupportedForQpiDtrMode(sfdp_handle_t * handle)1275 static inline bool SFDP_CheckDSSupportedForQpiDtrMode(sfdp_handle_t *handle)
1276 {
1277     return (bool)((handle->bfp.dw18 & (1UL << 27UL)) != 0UL);
1278 }
1279 
1280 /*!
1281  * @brief Check if data strobe supported in Quad SPI STR(SDR) mode.
1282  *
1283  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1284  *
1285  * @retval false Data strobe not supported in Quad SPI STR mode.
1286  * @retval true Data strobe supported in Quad SPI STR mode.
1287  */
SFDP_CheckDSSupportedForQpiStrMode(sfdp_handle_t * handle)1288 static inline bool SFDP_CheckDSSupportedForQpiStrMode(sfdp_handle_t *handle)
1289 {
1290     return (bool)((handle->bfp.dw18 & (1UL << 26UL)) != 0UL);
1291 }
1292 
1293 /* @} */
1294 
1295 /*!
1296  * @name Get OPI Attributes
1297  * @{
1298  */
1299 
1300 /*!
1301  * @brief Get octal DTR(DDR)(also called 8d-8d-8d) command type.
1302  *
1303  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1304  *
1305  * @return The serial flash supported octal dtr cmd type, please refer to @ref sfdp_octal_dtr_cmd_type_t for details.
1306  */
SFDP_GetOctalDTRCmdType(sfdp_handle_t * handle)1307 static inline sfdp_octal_dtr_cmd_type_t SFDP_GetOctalDTRCmdType(sfdp_handle_t *handle)
1308 {
1309     return (sfdp_octal_dtr_cmd_type_t)((handle->bfp.dw18 & 0x60000000UL) >> 29UL);
1310 }
1311 
1312 /*!
1313  * @brief Check if byte order is swapped in 8D-8D-8D mode.
1314  *
1315  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1316  *
1317  * @retval true Byte order is swapped.
1318  * @retval false Byte order is not swapped.
1319  */
SFDP_CheckByteSwapInOctalMode(sfdp_handle_t * handle)1320 static inline bool SFDP_CheckByteSwapInOctalMode(sfdp_handle_t *handle)
1321 {
1322     assert(handle->curJEDECVersion >= kSFDP_JESD216A);
1323 
1324     return (bool)((handle->bfp.dw18 & 0x80000000UL) != 0UL);
1325 }
1326 
1327 /*!
1328  * @brief Get command extension of input command.
1329  *
1330  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1331  * @param[in] cmd The octal command used to calculate command extension.
1332  *
1333  * @return The command extension based on current serial flash device's command policy.
1334  */
1335 uint8_t SFDP_GetOctalDTRCmdExtension(sfdp_handle_t *handle, uint8_t cmd);
1336 
1337 /*!
1338  * @brief Check if current serial flash device support input OPI(octal spi) command.
1339  *
1340  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1341  * @param opiCmd The input octal spi command to check.
1342  *
1343  * @retval kSFDP_RET_OPICMDNotSupported The input opi command not supported.
1344  * @retval kSFDP_RET_Success The input opi command supported.
1345  */
1346 sfdp_ret_type_t SFDP_CheckOPICmdSupported(sfdp_handle_t *handle, sfdp_xspi_profile_opi_cmd_t opiCmd);
1347 
1348 /*!
1349  * @brief Used to enable 1s-1s-8s and 1s-8s-8s octal read or octal program operations.
1350  *
1351  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1352  * @return The serial flash device supported octal enable method, please refer to @ref sfdp_octal_enable_method_t
1353  * for details.
1354  */
SFDP_GetOctalEnableMethod(sfdp_handle_t * handle)1355 static inline sfdp_octal_enable_method_t SFDP_GetOctalEnableMethod(sfdp_handle_t *handle)
1356 {
1357     return (sfdp_octal_enable_method_t)((handle->bfp.dw19 & 0x700000UL) >> 20UL);
1358 }
1359 
1360 /*!
1361  * @brief Check if current serial flash device support 0-8-8 mode.
1362  *
1363  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1364  * @retval false Current serial flash device does not support 0-8-8 mode.
1365  * @retval true Current serial flash device supports 0-8-8 mode.
1366  */
SFDP_Check088ModeSupported(sfdp_handle_t * handle)1367 static inline bool SFDP_Check088ModeSupported(sfdp_handle_t *handle)
1368 {
1369     return (bool)((handle->bfp.dw19 & (1UL << 9UL)) != 0UL);
1370 }
1371 
1372 /*!
1373  * @brief Get 0-8-8 mode entry method.
1374  *
1375  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1376  *
1377  * @return The serial flash device supported 0-8-8 mode entry method,
1378  * please refer to @ref sfdp_088_mode_entry_method_t.
1379  */
SFDP_Get088ModeEntryMethod(sfdp_handle_t * handle)1380 static inline sfdp_088_mode_entry_method_t SFDP_Get088ModeEntryMethod(sfdp_handle_t *handle)
1381 {
1382     return (sfdp_088_mode_entry_method_t)((handle->bfp.dw19 & 0xF0000UL) >> 16UL);
1383 }
1384 
1385 /*!
1386  * @brief Get 0-8-8 mode exit method.
1387  *
1388  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1389  *
1390  * @return The serial flash device supported 0-8-8 mode exit method,
1391  * please refer to @ref sfdp_088_mode_exit_method_t.
1392  */
SFDP_Get088ModeExitMethod(sfdp_handle_t * handle)1393 static inline sfdp_088_mode_exit_method_t SFDP_Get088ModeExitMethod(sfdp_handle_t *handle)
1394 {
1395     return (sfdp_088_mode_exit_method_t)((handle->bfp.dw19 & 0xFC00UL) >> 10UL);
1396 }
1397 
1398 /*!
1399  * @brief Get supported method to enter 8s-8s-8s mode from 1s-1s-1s mode.
1400  *
1401  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1402  * @return The serial flash supported method to enter 8s-8s-8s mode,
1403  * please refer to @ref sfdp_8s8s8s_mode_enable_method_t for details.
1404  */
SFDP_Get8s8s8sModeEnableMethod(sfdp_handle_t * handle)1405 static inline sfdp_8s8s8s_mode_enable_method_t SFDP_Get8s8s8sModeEnableMethod(sfdp_handle_t *handle)
1406 {
1407     return (sfdp_8s8s8s_mode_enable_method_t)((handle->bfp.dw19 & 0x1F0UL) >> 4UL);
1408 }
1409 
1410 /*!
1411  * @brief Get supported method to exit 8s-8s-8s mode.
1412  *
1413  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1414  * @return The serial flash supported method to exit 8s-8s-8s mode, please refer to
1415  * @ref sfdp_8s8s8s_mode_disable_method_t for details.
1416  */
SFDP_Get8s8s8sModeDisableMethod(sfdp_handle_t * handle)1417 static inline sfdp_8s8s8s_mode_disable_method_t SFDP_Get8s8s8sModeDisableMethod(sfdp_handle_t *handle)
1418 {
1419     return (sfdp_8s8s8s_mode_disable_method_t)(handle->bfp.dw19 & 0xFUL);
1420 }
1421 
1422 /*!
1423  * @brief Get 8d-8d-8d(octal DTR) mode entry sequences.
1424  *
1425  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1426  * @param[out] ptrEntrySeq The variable to store sequences to enter 8d-8d-8d mode.
1427  *
1428  * @retval kSFDP_RET_Success Successfully to get sequences to enter 8d-8d-8d mode.
1429  * @retval kSFDP_RET_NotImplemented Current serial flash device do not support sequences to enter 8d-8d-8d mode.
1430  */
1431 sfdp_ret_type_t SFDP_Get8d8d8dEntrySeq(sfdp_handle_t *handle, sfdp_8d8d8d_entry_seq_t *ptrEntrySeq);
1432 /*! @} */
1433 
1434 /*!
1435  * @name Get Device's Commands
1436  * @{
1437  */
1438 
1439 /*!
1440  * @brief Get erase suspend/resume command information.
1441  *
1442  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1443  * @param[out] ptrEraseSuspendResumeCmdInfo The variable to store erase suspend/resume command information, please
1444  *                                          refer to @ref sfdp_erase_suspend_resume_cmd_info_t for details.
1445  */
1446 void SFDP_GetEraseSuspendResumeCmdInfo(sfdp_handle_t *handle,
1447                                        sfdp_erase_suspend_resume_cmd_info_t *ptrEraseSuspendResumeCmdInfo);
1448 
1449 /*!
1450  * @brief Get program suspend/resume command information.
1451  *
1452  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1453  * @param[out] ptrProgramSuspendResumeCmdInfo The variable to store program suspend/resume command information,
1454  * please refer to @ref sfdp_program_suspend_cmd_info_t for details.
1455  */
1456 void SFDP_GetProgramSuspendResumeCmdInfo(sfdp_handle_t *handle,
1457                                          sfdp_program_suspend_cmd_info_t *ptrProgramSuspendResumeCmdInfo);
1458 
1459 /*!
1460  * @brief Get deep power down command information.
1461  *
1462  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1463  * @param[out] ptrDeepPowerDownCmdInfo The variable to store deep power down command information, please refer to
1464  * @ref sfdp_deep_power_down_cmd_info_t for details.
1465  */
1466 void SFDP_GetDeepPowerDownCmdInfo(sfdp_handle_t *handle, sfdp_deep_power_down_cmd_info_t *ptrDeepPowerDownCmdInfo);
1467 
1468 /*!
1469  * @brief Get read command information.
1470  *
1471  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1472  * @param[in] protocolType The protocol type for current serial flash device.
1473  * @param[in] clkFreq The frequency of serial clock.
1474  * @param[out] ptrReadCmdInfo The variable of store read command information,
1475  *                          please refer to @ref sfdp_read_cmd_info_t for details.
1476  */
1477 void SFDP_GetReadCmdInfo(sfdp_handle_t *handle,
1478                          sfdp_protocol_type_t protocolType,
1479                          uint32_t clkFreq,
1480                          sfdp_read_cmd_info_t *ptrReadCmdInfo);
1481 
1482 /*!
1483  * @brief Get chip erase information.
1484  *
1485  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1486  * @param[out] ptrChipEraseCmdInfo The variable to store chip erase command information,
1487  *                                  please refer to @ref sfdp_chip_erase_cmd_info_t for details.
1488  */
1489 void SFDP_GetChipEraseCmdInfo(sfdp_handle_t *handle, sfdp_chip_erase_cmd_info_t *ptrChipEraseCmdInfo);
1490 
1491 /*!
1492  * @brief Get sector erase command information.
1493  *
1494  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1495  * @param[in] type Used to select erase command type, please refer to @ref sfdp_erase_cmd_type_t.
1496  * @param[out] ptrEraseCmdInfo The variable to store erase command information,
1497                                 please refer to @ref sfdp_erase_cmd_info_t for details.
1498  *
1499  * @retval kSFDP_RET_EraseCMDNotSupported Selected type of erase command not supported.
1500  * @retval kSFDP_RET_Success Successfully to get selected erase command information.
1501  */
1502 sfdp_ret_type_t SFDP_GetSectorEraseCmdInfo(sfdp_handle_t *handle,
1503                                            sfdp_erase_cmd_type_t type,
1504                                            sfdp_erase_cmd_info_t *ptrEraseCmdInfo);
1505 
1506 /*!
1507  * @brief Get page program command information.
1508  *
1509  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1510  * @param[in] protocolType The protocol type for current serial flash device.
1511  * @param[out] ptrPageProgramCmdInfo The variable to store page program command information,
1512  *                                  please refer to @ref sfdp_page_program_cmd_info_t.
1513  */
1514 void SFDP_GetPageProgramCmdInfo(sfdp_handle_t *handle,
1515                                 sfdp_protocol_type_t protocolType,
1516                                 sfdp_page_program_cmd_info_t *ptrPageProgramCmdInfo);
1517 
1518 /*!
1519  * @brief Get read status command information.
1520  *
1521  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1522  * @param[in] protocolType The protocol type for current serial flash device.
1523  * @param[out] ptrReadStatusCmdInfo The variable to store read status command information,
1524  *                              please refer to @ref sfdp_read_status_cmd_info_t.
1525  */
1526 void SFDP_GetReadStatusCmdInfo(sfdp_handle_t *handle,
1527                                sfdp_protocol_type_t protocolType,
1528                                sfdp_read_status_cmd_info_t *ptrReadStatusCmdInfo);
1529 
1530 /*!
1531  * @brief Get write status command information.
1532  *
1533  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1534  * @param[out] ptrWriteStatusCmdInfo The variable to stor write status command information,
1535  *                                  please refer to @ref sfdp_write_status_cmd_info_t.
1536  */
1537 void SFDP_GetWriteStatusCmdInfo(sfdp_handle_t *handle, sfdp_write_status_cmd_info_t *ptrWriteStatusCmdInfo);
1538 
1539 /* @} */
1540 
1541 /*!
1542  * @name Get Device register bit field information
1543  * @{
1544  */
1545 
1546 /*!
1547  * @brief Get busy bit field information.
1548  *
1549  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1550  * @param[in] padNum Number of data pad.
1551  * @param[out] ptrBusyBitInfo The variable to store busy bit information.
1552  *
1553  * @retval kSFDP_RET_Success Successfully to get busy bit field information.
1554  */
1555 sfdp_ret_type_t SFDP_GetBusyBitInfo(sfdp_handle_t *handle,
1556                                     sfdp_flash_pad_num_t padNum,
1557                                     sfdp_wip_bit_info_t *ptrBusyBitInfo);
1558 
1559 /*!
1560  * @brief Get WEL(write enable) bit field information.
1561  *
1562  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1563  * @param[in] protocolType Current selected protocol type.
1564  * @param[out] ptrWelBitInfo The variable to store WEL bit information.
1565  *
1566  * @retval kSFDP_RET_Success Successfully to get WEL bit field information.
1567  */
1568 sfdp_ret_type_t SFDP_GetWELBitInfo(sfdp_handle_t *handle,
1569                                    sfdp_protocol_type_t protocolType,
1570                                    sfdp_wel_bit_info_t *ptrWelBitInfo);
1571 
1572 /*!
1573  * @brief Get program error bit field information.
1574  *
1575  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1576  * @param[in] protocolType Specify the protocol type to use.
1577  * @param[out] ptrProgramErrorBitInfo The variable to store program error bit information.
1578  *
1579  * @retval kSFDP_RET_NotImplemented Current serial flash do not implement the parameter table.
1580  * @retval kSFDP_RET_RegBitNotSupported Current serial flash do not support program error bit.
1581  * @retval kSFDP_RET_Success Successfully to get program error bit field information.
1582  */
1583 sfdp_ret_type_t SFDP_GetProgramErrorBitInfo(sfdp_handle_t *handle,
1584                                             sfdp_protocol_type_t protocolType,
1585                                             sfdp_program_error_bit_info_t *ptrProgramErrorBitInfo);
1586 
1587 /*!
1588  * @brief Get erase error bit field information.
1589  *
1590  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1591  * @param[in] protocolType Specify the protocol type to use.
1592  * @param[out] ptrEraseErrorBitInfo The variable to store erase error bit information.
1593  *
1594  * @retval kSFDP_RET_NotImplemented Current serial flash do not implement the parameter table.
1595  * @retval kSFDP_RET_RegBitNotSupported Current serial flash do not support erase error bit.
1596  * @retval kSFDP_RET_Success Successfully to get erase error bit field information.
1597  */
1598 sfdp_ret_type_t SFDP_GetEraseErrorBitInfo(sfdp_handle_t *handle,
1599                                           sfdp_protocol_type_t protocolType,
1600                                           sfdp_erase_error_bit_info_t *ptrEraseErrorBitInfo);
1601 
1602 /*!
1603  * @brief Get variable dummy cycle information.
1604  *
1605  * @param[in] handle The parameter in type of @ref sfdp_handle_t.
1606  * @param[in] protocolType Specify the protocol type to use.
1607  * @param[out] ptrVariableDCInfo The variable to updated dummy cycle value..
1608  *
1609  * @retval kSFDP_RET_NotImplemented Current serial flash do not implement the parameter table.
1610  * @retval kSFDP_RET_RegBitNotSupported Current serial flash do not support variable dummy cycle bit.
1611  * @retval kSFDP_RET_Success Successfully to get variable dummy cycle bit field information.
1612  */
1613 sfdp_ret_type_t SFDP_GetVolatileVariableDummyCycleInfo(sfdp_handle_t *handle,
1614                                                        sfdp_protocol_type_t protocolType,
1615                                                        sfdp_variable_dummy_cycle_t *ptrVariableDCInfo);
1616 /* @} */
1617 
1618 #if defined(__cplusplus)
1619 extern "C" {
1620 #endif
1621 
1622 #if defined(__cplusplus)
1623 }
1624 #endif
1625 
1626 /*!
1627  * @}
1628  */
1629 #endif /* __FSL_SFDP_H */
1630