1 /*
2 * Copyright (c) 2020 Peter Bigot Consulting, LLC
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 #ifndef ZEPHYR_DRIVERS_FLASH_JESD216_H_
8 #define ZEPHYR_DRIVERS_FLASH_JESD216_H_
9
10 #include <errno.h>
11 #include <zephyr/sys/byteorder.h>
12 #include <zephyr/sys/util.h>
13 #include <zephyr/types.h>
14
15 /* JEDEC Read identification */
16 #define JESD216_CMD_READ_ID SPI_NOR_CMD_RDID
17 #define JESD216_OCMD_READ_ID 0x9F60
18 #define JESD216_READ_ID_LEN 3
19
20 /* Following are structures and constants supporting the JEDEC Serial
21 * Flash Discoverable Parameters standard, JESD216 and its successors,
22 * available at
23 * https://www.jedec.org/standards-documents/docs/jesd216b
24 */
25
26 #define JESD216_CMD_READ_SFDP 0x5A
27 #define JESD216_CMD_BURST_SFDP 0x5B
28 #define JESD216_OCMD_READ_SFDP 0x5AA5
29
30 /* Layout of a JESD216 parameter header. */
31 struct jesd216_param_header {
32 uint8_t id_lsb; /* ID LSB */
33 uint8_t rev_minor; /* Minor revision number */
34 uint8_t rev_major; /* Major revision number */
35 uint8_t len_dw; /* Length of table in 32-bit DWORDs */
36 uint8_t ptp[3]; /* Address of table in SFDP space (LSB@0) */
37 uint8_t id_msb; /* ID MSB */
38 } __packed;
39
40 /* Get the number of bytes required for the parameter table. */
jesd216_param_len(const struct jesd216_param_header * hp)41 static inline uint32_t jesd216_param_len(const struct jesd216_param_header *hp)
42 {
43 return sizeof(uint32_t) * hp->len_dw;
44 }
45
46 /* Get the ID that identifies the content of the parameter table. */
jesd216_param_id(const struct jesd216_param_header * hp)47 static inline uint16_t jesd216_param_id(const struct jesd216_param_header *hp)
48 {
49 return ((uint16_t)hp->id_msb << 8) | hp->id_lsb;
50 }
51
52 /* Get the address within the SFDP where the data for the table is
53 * stored.
54 */
jesd216_param_addr(const struct jesd216_param_header * hp)55 static inline uint32_t jesd216_param_addr(const struct jesd216_param_header *hp)
56 {
57 return ((hp->ptp[2] << 16)
58 | (hp->ptp[1] << 8)
59 | (hp->ptp[0] << 0));
60 }
61
62 /* Layout of the Serial Flash Discoverable Parameters header. */
63 struct jesd216_sfdp_header {
64 uint32_t magic; /* "SFDP" in little endian */
65 uint8_t rev_minor; /* Minor revision number */
66 uint8_t rev_major; /* Major revision number */
67 uint8_t nph; /* Number of parameter headers */
68 uint8_t access; /* Access protocol */
69 struct jesd216_param_header phdr[]; /* Headers */
70 } __packed;
71
72 /* SFDP access protocol for backwards compatibility with JESD216B. */
73 #define JESD216_SFDP_AP_LEGACY 0xFF
74
75 /* The expected value from the jesd216_sfdp::magic field in host byte
76 * order.
77 */
78 #define JESD216_SFDP_MAGIC 0x50444653
79
80 /* All JESD216 data is read from the device in little-endian byte
81 * order. For JEDEC parameter tables defined through JESD216D-01 the
82 * parameters are defined by 32-bit words that may need to be
83 * byte-swapped to extract their information.
84 *
85 * A 16-bit ID from the parameter header is used to identify the
86 * content of each table. The first parameter table in the SFDP
87 * hierarchy must be a Basic Flash Parameter table (ID 0xFF00).
88 */
89
90 /* JESD216D-01 section 6.4: Basic Flash Parameter */
91 #define JESD216_SFDP_PARAM_ID_BFP 0xFF00
92 /* JESD216D-01 section 6.5: Sector Map Parameter */
93 #define JESD216_SFDP_PARAM_ID_SECTOR_MAP 0xFF81
94 /* JESD216D-01 section 6.6: 4-Byte Address Instruction Parameter */
95 #define JESD216_SFDP_PARAM_ID_4B_ADDR_INSTR 0xFF84
96 /* JESD216D-01 section 6.7: xSPI (Profile 1.0) Parameter */
97 #define JESD216_SFDP_PARAM_ID_XSPI_PROFILE_1V0 0xFF05
98 /* JESD216D-01 section 6.8: xSPI (Profile 2.0) Parameter */
99 #define JESD216_SFDP_PARAM_ID_XSPI_PROFILE_2V0 0xFF06
100
101 /* Macro to define the number of bytes required for the SFDP pheader
102 * and @p nph parameter headers.
103 *
104 * @param nph the number of parameter headers to be read. 1 is
105 * sufficient for basic functionality.
106 *
107 * @return required buffer size in bytes.
108 */
109 #define JESD216_SFDP_SIZE(nph) (sizeof(struct jesd216_sfdp_header) \
110 + ((nph) * sizeof(struct jesd216_param_header)))
111
112 /** Extract the magic number from the SFDP structure in host byte order.
113 *
114 * If this compares equal to JESD216_SFDP_MAGIC then the SFDP header
115 * may have been read correctly.
116 */
jesd216_sfdp_magic(const struct jesd216_sfdp_header * hp)117 static inline uint32_t jesd216_sfdp_magic(const struct jesd216_sfdp_header *hp)
118 {
119 return sys_le32_to_cpu(hp->magic);
120 }
121
122 /* Layout of the Basic Flash Parameters table.
123 *
124 * SFDP through JESD216B supported 9 DWORD values. JESD216C extended
125 * this to 17, and JESD216D to 20.
126 *
127 * All values are expected to be stored as little-endian and must be
128 * converted to host byte order to extract the bit fields defined in
129 * the standard. Rather than pre-define layouts to access to all
130 * potential fields this header provides functions for specific fields
131 * known to be important, such as density and erase command support.
132 */
133 struct jesd216_bfp {
134 uint32_t dw1;
135 uint32_t dw2;
136 uint32_t dw3;
137 uint32_t dw4;
138 uint32_t dw5;
139 uint32_t dw6;
140 uint32_t dw7;
141 uint32_t dw8;
142 uint32_t dw9;
143 uint32_t dw10[];
144 } __packed;
145
146 /* Provide a few word-specific flags and bitfield ranges for values
147 * that an application or driver might expect to want to extract.
148 *
149 * See the JESD216 specification for the interpretation of these
150 * bitfields.
151 */
152 #define JESD216_SFDP_BFP_DW1_DTRCLK_FLG BIT(19)
153 #define JESD216_SFDP_BFP_DW1_ADDRBYTES_MASK (BIT(17) | BIT(18))
154 #define JESD216_SFDP_BFP_DW1_ADDRBYTES_SHFT 17
155 #define JESD216_SFDP_BFP_DW1_ADDRBYTES_VAL_3B 0
156 #define JESD216_SFDP_BFP_DW1_ADDRBYTES_VAL_3B4B 1
157 #define JESD216_SFDP_BFP_DW1_ADDRBYTES_VAL_4B 2
158 #define JESD216_SFDP_BFP_DW1_4KERASEINSTR_SHFT 8
159 #define JESD216_SFDP_BFP_DW1_4KERASEINSTR_MASK (0xFF << JESD216_SFDP_BFP_DW1_4KERASEINSTR_SHFT)
160 #define JESD216_SFDP_BFP_DW1_WEISWVSR_FLG BIT(4)
161 #define JESD216_SFDP_BFP_DW1_VSRBP_FLG BIT(3)
162 #define JESD216_SFDP_BFP_DW1_WRTGRAN_FLG BIT(2)
163 #define JESD216_SFDP_BFP_DW1_BSERSZ_SHFT 0
164 #define JESD216_SFDP_BFP_DW1_BSERSZ_MASK (0x03 << JESD216_SFDP_BFP_DW1_BSERSZ_SHFT)
165 #define JESD216_SFDP_BFP_DW1_BSERSZ_VAL_4KSUP 0x01
166 #define JESD216_SFDP_BFP_DW1_BSERSZ_VAL_4KNOTSUP 0x03
167
168 #define JESD216_SFDP_BFP_DW12_SUSPRESSUP_FLG BIT(31)
169
170 /* Data can be extracted from the BFP words using these APIs:
171 *
172 * * DW1 (capabilities) use DW1 bitfield macros above or
173 * jesd216_read_support().
174 * * DW2 (density) use jesd216_bfp_density().
175 * * DW3-DW7 (instr) use jesd216_bfp_read_support().
176 * * DW8-DW9 (erase types) use jesd216_bfp_erase().
177 *
178 * JESD216A (16 DW)
179 *
180 * * DW10 (erase times) use jesd216_bfp_erase_type_times().
181 * * DW11 (other times) use jesd216_bfp_decode_dw11().
182 * * DW12-13 (suspend/resume) no API except
183 * JESD216_SFDP_BFP_DW12_SUSPRESSUP_FLG.
184 * * DW14 (deep power down) use jesd216_bfp_decode_dw14().
185 * * DW15-16 no API except jesd216_bfp_read_support().
186 *
187 * JESD216C (20 DW)
188 * * DW17-20 (quad/oct support) no API except jesd216_bfp_read_support().
189 */
190
191 /* Extract the supported address bytes from BFP DW1. */
jesd216_bfp_addrbytes(const struct jesd216_bfp * hp)192 static inline uint8_t jesd216_bfp_addrbytes(const struct jesd216_bfp *hp)
193 {
194 uint32_t dw1 = sys_le32_to_cpu(hp->dw1);
195 uint8_t addr_support = (dw1 & JESD216_SFDP_BFP_DW1_ADDRBYTES_MASK)
196 >> JESD216_SFDP_BFP_DW1_ADDRBYTES_SHFT;
197
198 return addr_support;
199 }
200
201 /* Extract the density of the chip in bits from BFP DW2. */
jesd216_bfp_density(const struct jesd216_bfp * hp)202 static inline uint64_t jesd216_bfp_density(const struct jesd216_bfp *hp)
203 {
204 uint32_t dw = sys_le32_to_cpu(hp->dw2);
205
206 if (dw & BIT(31)) {
207 return BIT64(dw & BIT_MASK(31));
208 }
209 return 1U + (uint64_t)dw;
210 }
211
212 /* Protocol mode enumeration types.
213 *
214 * Modes are identified by fields representing the number of I/O
215 * signals and the data rate in the transfer. The I/O width may be 1,
216 * 2, 4, or 8 I/O signals. The data rate may be single or double.
217 * SDR is assumed; DDR is indicated by a D following the I/O width.
218 *
219 * A transfer has three phases, and width/rate is specified for each
220 * in turn:
221 * * Transfer of the command
222 * * Transfer of the command modifier (e.g. address)
223 * * Transfer of the data.
224 *
225 * Modes explicitly mentioned in JESD216 or JESD251 are given
226 * enumeration values below, which can be used to extract information
227 * about instruction support.
228 */
229 enum jesd216_mode_type {
230 JESD216_MODE_044, /* implied instruction, execute in place */
231 JESD216_MODE_088,
232 JESD216_MODE_111,
233 JESD216_MODE_112,
234 JESD216_MODE_114,
235 JESD216_MODE_118,
236 JESD216_MODE_122,
237 JESD216_MODE_144,
238 JESD216_MODE_188,
239 JESD216_MODE_222,
240 JESD216_MODE_444,
241 JESD216_MODE_44D4D,
242 JESD216_MODE_888,
243 JESD216_MODE_8D8D8D,
244 JESD216_MODE_LIMIT,
245 };
246
247 /* Command to use for fast read operations in a specified protocol
248 * mode.
249 */
250 struct jesd216_instr {
251 uint8_t instr;
252 uint8_t mode_clocks;
253 uint8_t wait_states;
254 };
255
256 /* Determine whether a particular operational mode is supported for
257 * read, and possibly what command may be used.
258 *
259 * @note For @p mode JESD216_MODE_111 this function will return zero
260 * to indicate that standard read (instruction 03h) is supported, but
261 * without providing information on how. SFDP does not provide an
262 * indication of support for 1-1-1 Fast Read (0Bh).
263 *
264 * @param php pointer to the BFP header.
265 *
266 * @param bfp pointer to the BFP table.
267 *
268 * @param mode the desired protocol mode.
269 *
270 * @param res where to store instruction information. Pass a null
271 * pointer to test for support without retrieving instruction
272 * information.
273 *
274 * @retval positive if instruction is supported and *res has been set.
275 *
276 * @retval 0 if instruction is supported but *res has not been set
277 * (e.g. no instruction needed, or instruction cannot be read from
278 * BFP).
279 *
280 * @retval -ENOTSUP if instruction is not supported.
281 */
282 int jesd216_bfp_read_support(const struct jesd216_param_header *php,
283 const struct jesd216_bfp *bfp,
284 enum jesd216_mode_type mode,
285 struct jesd216_instr *res);
286
287 /* Description of a supported erase operation. */
288 struct jesd216_erase_type {
289 /* The command opcode used for an erase operation. */
290 uint8_t cmd;
291
292 /* The value N when the erase operation erases a 2^N byte
293 * region.
294 */
295 uint8_t exp;
296 };
297
298 /* The number of erase types defined in a JESD216 Basic Flash
299 * Parameter table.
300 */
301 #define JESD216_NUM_ERASE_TYPES 4
302
303 /* Extract a supported erase size and command from BFP DW8 or DW9.
304 *
305 * @param bfp pointer to the parameter table.
306 *
307 * @param idx the erase type index, from 1 through 4. Only index 1 is
308 * guaranteed to be present.
309 *
310 * @param etp where to store the command and size used for the erase.
311 *
312 * @retval 0 if the erase type index provided usable information.
313 * @retval -EINVAL if the erase type index is undefined.
314 */
315 int jesd216_bfp_erase(const struct jesd216_bfp *bfp,
316 uint8_t idx,
317 struct jesd216_erase_type *etp);
318
319 /* Extract typical and maximum erase times from DW10.
320 *
321 * @param php pointer to the BFP header.
322 *
323 * @param bfp pointer to the BFP table.
324 *
325 * @param idx the erase type index, from 1 through 4. For meaningful
326 * results the index should be one for which jesd216_bfp_erase()
327 * returns success.
328 *
329 * @param typ_ms where to store the typical erase time (in
330 * milliseconds) for the specified erase type.
331 *
332 * @retval -ENOTSUP if the erase type index is undefined.
333 * @retval positive is a multiplier that converts typical erase times
334 * to maximum erase times.
335 */
336 int jesd216_bfp_erase_type_times(const struct jesd216_param_header *php,
337 const struct jesd216_bfp *bfp,
338 uint8_t idx,
339 uint32_t *typ_ms);
340
341 /* Get the page size from the Basic Flash Parameters.
342 *
343 * @param php pointer to the BFP header.
344 *
345 * @param bfp pointer to the BFP table.
346 *
347 * @return the page size in bytes from the parameters if supported,
348 * otherwise 256.
349 */
jesd216_bfp_page_size(const struct jesd216_param_header * php,const struct jesd216_bfp * bfp)350 static inline uint32_t jesd216_bfp_page_size(const struct jesd216_param_header *php,
351 const struct jesd216_bfp *bfp)
352 {
353 /* Page size introduced in JESD216A */
354 if (php->len_dw < 11) {
355 return 256;
356 }
357
358 uint32_t dw11 = sys_le32_to_cpu(bfp->dw10[1]);
359 uint8_t exp = (dw11 >> 4) & 0x0F;
360
361 return BIT(exp);
362 }
363
364 /* Decoded data from JESD216 DW11. */
365 struct jesd216_bfp_dw11 {
366 /* Typical time for chip (die) erase, in milliseconds */
367 uint16_t chip_erase_ms;
368
369 /* Typical time for first byte program, in microseconds */
370 uint16_t byte_prog_first_us;
371
372 /* Typical time per byte for byte program after first, in
373 * microseconds
374 */
375 uint16_t byte_prog_addl_us;
376
377 /* Typical time for page program, in microseconds */
378 uint16_t page_prog_us;
379
380 /* Multiplier to get maximum time from typical times. */
381 uint16_t typ_max_factor;
382
383 /* Number of bytes in a page. */
384 uint16_t page_size;
385 };
386
387 /* Get data from BFP DW11.
388 *
389 * @param php pointer to the BFP header.
390 *
391 * @param bfp pointer to the BFP table.
392 *
393 * @param res pointer to where to store the decoded data.
394 *
395 * @retval -ENOTSUP if this information is not available from this BFP table.
396 * @retval 0 on successful storage into @c *res.
397 */
398 int jesd216_bfp_decode_dw11(const struct jesd216_param_header *php,
399 const struct jesd216_bfp *bfp,
400 struct jesd216_bfp_dw11 *res);
401
402 /* Decoded data from JESD216 DW14 */
403 struct jesd216_bfp_dw14 {
404 /* Instruction used to enter deep power-down */
405 uint8_t enter_dpd_instr;
406
407 /* Instruction used to exit deep power-down */
408 uint8_t exit_dpd_instr;
409
410 /* Bits defining ways busy status may be polled. */
411 uint8_t poll_options;
412
413 /* Time after issuing exit instruction until device is ready
414 * to accept a command, in nanoseconds.
415 */
416 uint32_t exit_delay_ns;
417 };
418
419 /* Get data from BFP DW14.
420 *
421 * @param php pointer to the BFP header.
422 *
423 * @param bfp pointer to the BFP table.
424 *
425 * @param res pointer to where to store the decoded data.
426 *
427 * @retval -ENOTSUP if this information is not available from this BFP table.
428 * @retval 0 on successful storage into @c *res.
429 */
430 int jesd216_bfp_decode_dw14(const struct jesd216_param_header *php,
431 const struct jesd216_bfp *bfp,
432 struct jesd216_bfp_dw14 *res);
433
434 /* DW15 Quad Enable Requirements specifies status register QE bits.
435 *
436 * Two common configurations are summarized; see the specification for
437 * full details of how to use these values.
438 */
439 enum jesd216_dw15_qer_type {
440 /* No QE status required for 1-1-4 or 1-4-4 mode */
441 JESD216_DW15_QER_NONE = 0,
442 JESD216_DW15_QER_S2B1v1 = 1,
443 /* Bit 6 of SR byte must be set to enable 1-1-4 or 1-4-4 mode.
444 * SR is one byte.
445 */
446 JESD216_DW15_QER_S1B6 = 2,
447 JESD216_DW15_QER_S2B7 = 3,
448 JESD216_DW15_QER_S2B1v4 = 4,
449 JESD216_DW15_QER_S2B1v5 = 5,
450 JESD216_DW15_QER_S2B1v6 = 6,
451 };
452
453 #define JESD216_DW15_QER_VAL_NONE 0
454 #define JESD216_DW15_QER_VAL_S2B1v1 1
455 #define JESD216_DW15_QER_VAL_S1B6 2
456 #define JESD216_DW15_QER_VAL_S2B7 3
457 #define JESD216_DW15_QER_VAL_S2B1v4 4
458 #define JESD216_DW15_QER_VAL_S2B1v5 5
459 #define JESD216_DW15_QER_VAL_S2B1v6 6
460
461 /* Decoded data from JESD216 DW15 */
462 struct jesd216_bfp_dw15 {
463 /* If true clear NVECR bit 4 to disable HOLD/RESET */
464 bool hold_reset_disable: 1;
465 /* Encoded jesd216_dw15_qer_type */
466 unsigned int qer: 3;
467 /* 0-4-4 mode entry method */
468 unsigned int entry_044: 4;
469 /* 0-4-4 mode exit method */
470 unsigned int exit_044: 6;
471 /* True if 0-4-4 mode is supported */
472 bool support_044: 1;
473 /* 4-4-4 mode enable sequences */
474 unsigned int enable_444: 5;
475 /* 4-4-4 mode disable sequences */
476 unsigned int disable_444: 4;
477 };
478
479 /* Get data from BFP DW15.
480 *
481 * @param php pointer to the BFP header.
482 *
483 * @param bfp pointer to the BFP table.
484 *
485 * @param res pointer to where to store the decoded data.
486 *
487 * @retval -ENOTSUP if this information is not available from this BFP table.
488 * @retval 0 on successful storage into @c *res.
489 */
490 int jesd216_bfp_decode_dw15(const struct jesd216_param_header *php,
491 const struct jesd216_bfp *bfp,
492 struct jesd216_bfp_dw15 *res);
493
494 /* Decoded data from JESD216_DW16 */
495 struct jesd216_bfp_dw16 {
496 /* Bits specifying supported modes of entering 4-byte
497 * addressing.
498 */
499 unsigned int enter_4ba: 8;
500
501 /* Bits specifying supported modes of exiting 4-byte
502 * addressing.
503 */
504 unsigned int exit_4ba: 10;
505
506 /* Bits specifying the soft reset and rescue sequence to
507 * restore the device to its power-on state.
508 */
509 unsigned int srrs_support: 6;
510
511 /* Bits specifying how to modify status register 1, and which
512 * bits are non-volatile.
513 */
514 unsigned int sr1_interface: 7;
515 };
516
517 /* Get data from BFP DW16.
518 *
519 * @param php pointer to the BFP header.
520 *
521 * @param bfp pointer to the BFP table.
522 *
523 * @param res pointer to where to store the decoded data.
524 *
525 * @retval -ENOTSUP if this information is not available from this BFP table.
526 * @retval 0 on successful storage into @c *res.
527 */
528 int jesd216_bfp_decode_dw16(const struct jesd216_param_header *php,
529 const struct jesd216_bfp *bfp,
530 struct jesd216_bfp_dw16 *res);
531
532 #endif /* ZEPHYR_DRIVERS_FLASH_JESD216_H_ */
533
