XCORE SDK
XCORE Software Development Kit
qspi_flash.h
Go to the documentation of this file.
1 // Copyright 2020-2021 XMOS LIMITED.
2 // This Software is subject to the terms of the XMOS Public Licence: Version 1.
3 #pragma once
4 
9 #include <stdbool.h>
10 #include "qspi_io.h"
11 
19 #if !defined(QSPI_FLASH_SANITY_CHECKS)
25 #define QSPI_FLASH_SANITY_CHECKS 0
26 #endif
27 
28 typedef enum {
34 
43 
53 
57 typedef struct {
64 
71 
78 
84 
85  /*
86  * The following members are all set automatically by qspi_flash_init() if
87  * SFDP is supported. These may be set prior to calling qspi_flash_init()
88  * in the event that SFDP is not supported.
89  * Additionally, sfdp_skip may be set to skip SFDP and use manually set
90  * parameters.
91  */
92  bool sfdp_skip;
93  bool sfdp_supported;
94  size_t page_size_bytes;
95  size_t page_count;
96  size_t flash_size_kbytes;
97 
98  /* should be 3 or 4 */
99  int address_bytes;
100 
101  struct {
102  uint32_t size_log2;
103  uint32_t cmd;
104  } erase_info[4];
105 
106  uint32_t busy_poll_cmd;
107  uint8_t busy_poll_bit;
108  uint8_t busy_poll_ready_value;
109 
110  /* 1 or 2. 0 means quad mode is automatically detected and cannot be explicitly entered */
111  uint8_t qe_reg;
112  uint8_t qe_bit;
113  uint32_t sr2_read_cmd; /* if 0, then read 2 bytes with the standard status register read command */
114  uint32_t sr2_write_cmd;/* if 0, then write 2 bytes with the standard status register write command */
115 
117 
125 typedef enum {
132 
137 #define QSPI_FLASH_STATUS_REG_WIP_BM 0x01
138 
143 #define QSPI_FLASH_STATUS_REG_WEL_BM 0x02
144 
145 /*
146  * Returns the erase size in bytes associated with the given erase type.
147  *
148  * \param ctx The QSPI flash context associated with the QSPI flash.
149  * \param erase_type The erase type to return the size of.
150  *
151  * \returns The erase size in bytes of \p erase type. If \p erase_type
152  * is qspi_flash_erase_chip then SIZE_MAX is returned. If \p erase_type
153  * is invalid or not available on the flash chip, then 0 is returned.
154  */
155 inline size_t qspi_flash_erase_type_size(qspi_flash_ctx_t *ctx, qspi_flash_erase_length_t erase_type)
156 {
157  if (erase_type >= qspi_flash_erase_1 && erase_type <= qspi_flash_erase_4) {
158  uint32_t size_log2 = ctx->erase_info[erase_type].size_log2;
159  return size_log2 > 0 ? (1 << size_log2) : 0;
160  } else if (erase_type == qspi_flash_erase_chip) {
161  return SIZE_MAX;
162  } else {
163  return 0;
164  }
165 }
166 
167 /*
168  * Returns log2 of the erase size in bytes associated with the given erase type.
169  *
170  * \param ctx The QSPI flash context associated with the QSPI flash.
171  * \param erase_type The erase type to return the size of.
172  *
173  * \returns The log2 of the erase size in bytes of \p erase type. If \p erase_type
174  * is qspi_flash_erase_chip then UINT32_MAX is returned. If \p erase_type
175  * is invalid or not available on the flash chip, then 0 is returned.
176  */
177 inline uint32_t qspi_flash_erase_type_size_log2(qspi_flash_ctx_t *ctx, qspi_flash_erase_length_t erase_type)
178 {
179  if (erase_type >= qspi_flash_erase_1 && erase_type <= qspi_flash_erase_4) {
180  return ctx->erase_info[erase_type].size_log2;
181  } else if (erase_type == qspi_flash_erase_chip) {
182  return UINT32_MAX;
183  } else {
184  return 0;
185  }
186 }
187 
205 
213 
222 
233 
242 
253  uint32_t address,
254  qspi_flash_erase_length_t erase_length);
255 
267  uint32_t cmd,
268  const uint8_t *val,
269  size_t len);
270 
280  const uint8_t *val,
281  size_t len);
282 
294  uint32_t cmd,
295  uint8_t *val,
296  size_t len);
297 
306  uint8_t *val,
307  size_t len);
308 
317  uint8_t *val,
318  size_t len);
319 
335  uint32_t cmd,
336  const uint8_t mask,
337  const uint8_t val);
338 
349  const uint8_t mask,
350  const uint8_t val);
351 
365  uint8_t *data,
366  uint32_t address,
367  size_t len);
368 
384  uint8_t *data,
385  uint32_t address,
386  size_t len);
387 
403  uint8_t *data,
404  uint32_t address,
405  size_t len);
406 
426  uint8_t *data,
427  uint32_t address,
428  size_t len);
429 
445  uint8_t *data,
446  uint32_t address,
447  size_t len);
448 
466  const uint8_t *data,
467  uint32_t address,
468  size_t len);
469 
484  const uint8_t *data,
485  uint32_t address,
486  size_t len);
487 
499  uint8_t *data,
500  uint32_t address,
501  size_t len);
502 
511 
524  // END: addtogroup hil_qspi_flash
void qspi_flash_write(qspi_flash_ctx_t *ctx, const uint8_t *data, uint32_t address, size_t len)
void qspi_flash_write_nibble_swapped(qspi_flash_ctx_t *ctx, const uint8_t *data, uint32_t address, size_t len)
void qspi_flash_xip_read(qspi_flash_ctx_t *ctx, uint8_t *data, uint32_t address, size_t len)
bool qspi_flash_write_in_progress(qspi_flash_ctx_t *ctx)
void qspi_flash_deinit(qspi_flash_ctx_t *ctx)
qspi_flash_page_program_cmd_t
Definition: qspi_flash.h:28
void qspi_flash_write_enable(qspi_flash_ctx_t *ctx)
void qspi_flash_read_nibble_swapped(qspi_flash_ctx_t *ctx, uint8_t *data, uint32_t address, size_t len)
void qspi_flash_fast_read(qspi_flash_ctx_t *ctx, uint8_t *data, uint32_t address, size_t len)
void qspi_flash_write_disable(qspi_flash_ctx_t *ctx)
void qspi_flash_xip_read_nibble_swapped(qspi_flash_ctx_t *ctx, uint8_t *data, uint32_t address, size_t len)
bool qspi_flash_quad_enable_write(qspi_flash_ctx_t *ctx, bool set)
void qspi_flash_read_status_register(qspi_flash_ctx_t *ctx, uint8_t *val, size_t len)
void qspi_flash_read_register(qspi_flash_ctx_t *ctx, uint32_t cmd, uint8_t *val, size_t len)
void qspi_flash_read(qspi_flash_ctx_t *ctx, uint8_t *data, uint32_t address, size_t len)
void qspi_flash_wait_while_write_in_progress(qspi_flash_ctx_t *ctx)
void qspi_flash_erase(qspi_flash_ctx_t *ctx, uint32_t address, qspi_flash_erase_length_t erase_length)
void qspi_flash_read_id(qspi_flash_ctx_t *ctx, uint8_t *val, size_t len)
void qspi_flash_write_status_register(qspi_flash_ctx_t *ctx, const uint8_t *val, size_t len)
void qspi_flash_write_register(qspi_flash_ctx_t *ctx, uint32_t cmd, const uint8_t *val, size_t len)
void qspi_flash_init(qspi_flash_ctx_t *ctx)
void qspi_flash_poll_status_register(qspi_flash_ctx_t *ctx, const uint8_t mask, const uint8_t val)
qspi_flash_erase_length_t
Definition: qspi_flash.h:125
void qspi_flash_sfdp_read(qspi_flash_ctx_t *ctx, uint8_t *data, uint32_t address, size_t len)
void qspi_flash_poll_register(qspi_flash_ctx_t *ctx, uint32_t cmd, const uint8_t mask, const uint8_t val)
@ qspi_flash_page_program_1_1_1
Definition: qspi_flash.h:33
@ qspi_flash_page_program_1_1_4
Definition: qspi_flash.h:42
@ qspi_flash_page_program_1_4_4
Definition: qspi_flash.h:51
@ qspi_flash_erase_2
Definition: qspi_flash.h:127
@ qspi_flash_erase_chip
Definition: qspi_flash.h:130
@ qspi_flash_erase_4
Definition: qspi_flash.h:129
@ qspi_flash_erase_1
Definition: qspi_flash.h:126
@ qspi_flash_erase_3
Definition: qspi_flash.h:128
qspi_io_source_clock_t
Definition: qspi_io.h:33
API for QSPI I/O.
Definition: qspi_flash.h:57
qspi_io_source_clock_t source_clock
Definition: qspi_flash.h:70
int custom_clock_setup
Definition: qspi_flash.h:77
qspi_flash_page_program_cmd_t quad_page_program_cmd
Definition: qspi_flash.h:83
qspi_io_ctx_t qspi_io_ctx
Definition: qspi_flash.h:63
Definition: qspi_io.h:93