1 /*
2 * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
7 #pragma once
8 #include "esp_err.h"
9 #include <stdint.h>
10 #include <stdbool.h>
11
12 #include "hal/spi_flash_types.h"
13
14 #ifdef __cplusplus
15 extern "C" {
16 #endif
17
18 struct spi_flash_chip_t;
19 typedef struct spi_flash_chip_t spi_flash_chip_t;
20
21 /** @cond */
22 typedef struct esp_flash_t esp_flash_t;
23 /** @endcond */
24
25 /** @brief Structure for describing a region of flash */
26 typedef struct {
27 uint32_t offset; ///< Start address of this region
28 uint32_t size; ///< Size of the region
29 } esp_flash_region_t;
30
31 /** @brief OS-level integration hooks for accessing flash chips inside a running OS
32 *
33 * It's in the public header because some instances should be allocated statically in the startup
34 * code. May be updated according to hardware version and new flash chip feature requirements,
35 * shouldn't be treated as public API.
36 *
37 * For advanced developers, you may replace some of them with your implementations at your own
38 * risk.
39 */
40 typedef struct {
41 /**
42 * Called before commencing any flash operation. Does not need to be
43 * recursive (ie is called at most once for each call to 'end').
44 */
45 esp_err_t (*start)(void *arg);
46
47 /** Called after completing any flash operation. */
48 esp_err_t (*end)(void *arg);
49
50 /** Called before any erase/write operations to check whether the region is limited by the OS */
51 esp_err_t (*region_protected)(void* arg, size_t start_addr, size_t size);
52
53 /** Delay for at least 'us' microseconds. Called in between 'start' and 'end'. */
54 esp_err_t (*delay_us)(void *arg, uint32_t us);
55
56 /** Called for get temp buffer when buffer from application cannot be directly read into/write from. */
57 void *(*get_temp_buffer)(void* arg, size_t reqest_size, size_t* out_size);
58
59 /** Called for release temp buffer. */
60 void (*release_temp_buffer)(void* arg, void *temp_buf);
61
62 #define SPI_FLASH_YIELD_REQ_YIELD BIT(0)
63 #define SPI_FLASH_YIELD_REQ_SUSPEND BIT(1)
64
65 /** Yield to other tasks. Called during erase operations.
66 * @return ESP_OK means yield needs to be called (got an event to handle), while ESP_ERR_TIMEOUT means skip yield.*/
67 esp_err_t (*check_yield)(void *arg, uint32_t chip_status, uint32_t* out_request);
68
69 #define SPI_FLASH_YIELD_STA_RESUME BIT(2)
70
71 /** Yield to other tasks. Called during erase operations. */
72 esp_err_t (*yield)(void *arg, uint32_t* out_status);
73
74 /** Called for get system time. */
75 int64_t (*get_system_time)(void *arg);
76
77 #define SPI_FLASH_OS_IS_ERASING_STATUS_FLAG BIT(0)
78
79 /** Call to set flash operation status */
80 void (*set_flash_op_status)(uint32_t op_status);
81
82 } esp_flash_os_functions_t;
83
84 /** @brief Structure to describe a SPI flash chip connected to the system.
85
86 Structure must be initialized before use (passed to esp_flash_init()). It's in the public
87 header because some instances should be allocated statically in the startup code. May be
88 updated according to hardware version and new flash chip feature requirements, shouldn't be
89 treated as public API.
90
91 For advanced developers, you may replace some of them with your implementations at your own
92 risk.
93 */
94 struct esp_flash_t {
95 spi_flash_host_inst_t* host; ///< Pointer to hardware-specific "host_driver" structure. Must be initialized before used.
96 const spi_flash_chip_t *chip_drv; ///< Pointer to chip-model-specific "adapter" structure. If NULL, will be detected during initialisation.
97
98 const esp_flash_os_functions_t *os_func; ///< Pointer to os-specific hook structure. Call ``esp_flash_init_os_functions()`` to setup this field, after the host is properly initialized.
99 void *os_func_data; ///< Pointer to argument for os-specific hooks. Left NULL and will be initialized with ``os_func``.
100
101 esp_flash_io_mode_t read_mode; ///< Configured SPI flash read mode. Set before ``esp_flash_init`` is called.
102 uint32_t size; ///< Size of SPI flash in bytes. If 0, size will be detected during initialisation. Note: this stands for the size in the binary image header. If you want to get the flash physical size, please call `esp_flash_get_physical_size`.
103 uint32_t chip_id; ///< Detected chip id.
104 uint32_t busy :1; ///< This flag is used to verify chip's status.
105 uint32_t hpm_dummy_ena :1; ///< This flag is used to verify whether flash works under HPM status.
106 uint32_t reserved_flags :30; ///< reserved.
107 };
108
109
110 /** @brief Initialise SPI flash chip interface.
111 *
112 * This function must be called before any other API functions are called for this chip.
113 *
114 * @note Only the ``host`` and ``read_mode`` fields of the chip structure must
115 * be initialised before this function is called. Other fields may be
116 * auto-detected if left set to zero or NULL.
117 *
118 * @note If the chip->drv pointer is NULL, chip chip_drv will be auto-detected
119 * based on its manufacturer & product IDs. See
120 * ``esp_flash_registered_flash_drivers`` pointer for details of this process.
121 *
122 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.
123 * @return ESP_OK on success, or a flash error code if initialisation fails.
124 */
125 esp_err_t esp_flash_init(esp_flash_t *chip);
126
127 /**
128 * Check if appropriate chip driver is set.
129 *
130 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.
131 *
132 * @return true if set, otherwise false.
133 */
134 bool esp_flash_chip_driver_initialized(const esp_flash_t *chip);
135
136 /** @brief Read flash ID via the common "RDID" SPI flash command.
137 *
138 * @param chip Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init()
139 * @param[out] out_id Pointer to receive ID value.
140 *
141 * ID is a 24-bit value. Lower 16 bits of 'id' are the chip ID, upper 8 bits are the manufacturer ID.
142 *
143 * @return ESP_OK on success, or a flash error code if operation failed.
144 */
145 esp_err_t esp_flash_read_id(esp_flash_t *chip, uint32_t *out_id);
146
147 /** @brief Detect flash size based on flash ID.
148 *
149 * @param chip Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init()
150 * @param[out] out_size Detected size in bytes, standing for the size in the binary image header.
151 *
152 * @note 1. Most flash chips use a common format for flash ID, where the lower 4 bits specify the size as a power of 2. If
153 * the manufacturer doesn't follow this convention, the size may be incorrectly detected.
154 * 2. The out_size returned only stands for The out_size stands for the size in the binary image header.
155 * If you want to get the real size of the chip, please call `esp_flash_get_physical_size` instead.
156 *
157 * @return ESP_OK on success, or a flash error code if operation failed.
158 */
159 esp_err_t esp_flash_get_size(esp_flash_t *chip, uint32_t *out_size);
160
161 /** @brief Detect flash size based on flash ID.
162 *
163 * @param chip Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init()
164 * @param[out] flash_size Detected size in bytes.
165 *
166 * @note Most flash chips use a common format for flash ID, where the lower 4 bits specify the size as a power of 2. If
167 * the manufacturer doesn't follow this convention, the size may be incorrectly detected.
168 *
169 * @return ESP_OK on success, or a flash error code if operation failed.
170 */
171 esp_err_t esp_flash_get_physical_size(esp_flash_t *chip, uint32_t *flash_size);
172
173 /** @brief Read flash unique ID via the common "RDUID" SPI flash command.
174 *
175 * @note This is an optional feature, which is not supported on all flash chips. READ PROGRAMMING GUIDE FIRST!
176 *
177 * @param chip Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init().
178 * @param[out] out_id Pointer to receive unique ID value.
179 *
180 * ID is a 64-bit value.
181 *
182 * @return
183 * - ESP_OK on success, or a flash error code if operation failed.
184 * - ESP_ERR_NOT_SUPPORTED if the chip doesn't support read id.
185 */
186 esp_err_t esp_flash_read_unique_chip_id(esp_flash_t *chip, uint64_t *out_id);
187
188 /** @brief Erase flash chip contents
189 *
190 * @param chip Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init()
191 *
192 *
193 * @return
194 * - ESP_OK on success,
195 * - ESP_ERR_NOT_SUPPORTED if the chip is not able to perform the operation. This is indicated by WREN = 1 after the command is sent.
196 * - Other flash error code if operation failed.
197 */
198 esp_err_t esp_flash_erase_chip(esp_flash_t *chip);
199
200 /** @brief Erase a region of the flash chip
201 *
202 * @param chip Pointer to identify flash chip. If NULL, esp_flash_default_chip is substituted. Must have been successfully initialised via esp_flash_init()
203 * @param start Address to start erasing flash. Must be sector aligned.
204 * @param len Length of region to erase. Must also be sector aligned.
205 *
206 * Sector size is specifyed in chip->drv->sector_size field (typically 4096 bytes.) ESP_ERR_INVALID_ARG will be
207 * returned if the start & length are not a multiple of this size.
208 *
209 * Erase is performed using block (multi-sector) erases where possible (block size is specified in
210 * chip->drv->block_erase_size field, typically 65536 bytes). Remaining sectors are erased using individual sector erase
211 * commands.
212 *
213 * @return
214 * - ESP_OK on success,
215 * - ESP_ERR_NOT_SUPPORTED if the chip is not able to perform the operation. This is indicated by WREN = 1 after the command is sent.
216 * - Other flash error code if operation failed.
217 */
218 esp_err_t esp_flash_erase_region(esp_flash_t *chip, uint32_t start, uint32_t len);
219
220 /** @brief Read if the entire chip is write protected
221 *
222 * @param chip Pointer to identify flash chip. If NULL, esp_flash_default_chip is substituted. Must have been successfully initialised via esp_flash_init()
223 * @param[out] write_protected Pointer to boolean, set to the value of the write protect flag.
224 *
225 * @note A correct result for this flag depends on the SPI flash chip model and chip_drv in use (via the 'chip->drv'
226 * field).
227 *
228 * @return ESP_OK on success, or a flash error code if operation failed.
229 */
230 esp_err_t esp_flash_get_chip_write_protect(esp_flash_t *chip, bool *write_protected);
231
232 /** @brief Set write protection for the SPI flash chip
233 *
234 * @param chip Pointer to identify flash chip. If NULL, esp_flash_default_chip is substituted. Must have been successfully initialised via esp_flash_init()
235 * @param write_protect Boolean value for the write protect flag
236 *
237 * @note Correct behaviour of this function depends on the SPI flash chip model and chip_drv in use (via the 'chip->drv'
238 * field).
239 *
240 * Some SPI flash chips may require a power cycle before write protect status can be cleared. Otherwise,
241 * write protection can be removed via a follow-up call to this function.
242 *
243 * @return ESP_OK on success, or a flash error code if operation failed.
244 */
245 esp_err_t esp_flash_set_chip_write_protect(esp_flash_t *chip, bool write_protect);
246
247
248 /** @brief Read the list of individually protectable regions of this SPI flash chip.
249 *
250 * @param chip Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init()
251 * @param[out] out_regions Pointer to receive a pointer to the array of protectable regions of the chip.
252 * @param[out] out_num_regions Pointer to an integer receiving the count of protectable regions in the array returned in 'regions'.
253 *
254 * @note Correct behaviour of this function depends on the SPI flash chip model and chip_drv in use (via the 'chip->drv'
255 * field).
256 *
257 * @return ESP_OK on success, or a flash error code if operation failed.
258 */
259 esp_err_t esp_flash_get_protectable_regions(const esp_flash_t *chip, const esp_flash_region_t **out_regions, uint32_t *out_num_regions);
260
261
262 /** @brief Detect if a region of the SPI flash chip is protected
263 *
264 * @param chip Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init()
265 * @param region Pointer to a struct describing a protected region. This must match one of the regions returned from esp_flash_get_protectable_regions(...).
266 * @param[out] out_protected Pointer to a flag which is set based on the protected status for this region.
267 *
268 * @note It is possible for this result to be false and write operations to still fail, if protection is enabled for the entire chip.
269 *
270 * @note Correct behaviour of this function depends on the SPI flash chip model and chip_drv in use (via the 'chip->drv'
271 * field).
272 *
273 * @return ESP_OK on success, or a flash error code if operation failed.
274 */
275 esp_err_t esp_flash_get_protected_region(esp_flash_t *chip, const esp_flash_region_t *region, bool *out_protected);
276
277 /** @brief Update the protected status for a region of the SPI flash chip
278 *
279 * @param chip Pointer to identify flash chip. Must have been successfully initialised via esp_flash_init()
280 * @param region Pointer to a struct describing a protected region. This must match one of the regions returned from esp_flash_get_protectable_regions(...).
281 * @param protect Write protection flag to set.
282 *
283 * @note It is possible for the region protection flag to be cleared and write operations to still fail, if protection is enabled for the entire chip.
284 *
285 * @note Correct behaviour of this function depends on the SPI flash chip model and chip_drv in use (via the 'chip->drv'
286 * field).
287 *
288 * @return ESP_OK on success, or a flash error code if operation failed.
289 */
290 esp_err_t esp_flash_set_protected_region(esp_flash_t *chip, const esp_flash_region_t *region, bool protect);
291
292 /** @brief Read data from the SPI flash chip
293 *
294 * @param chip Pointer to identify flash chip. If NULL, esp_flash_default_chip is substituted. Must have been successfully initialised via esp_flash_init()
295 * @param buffer Pointer to a buffer where the data will be read. To get better performance, this should be in the DRAM and word aligned.
296 * @param address Address on flash to read from. Must be less than chip->size field.
297 * @param length Length (in bytes) of data to read.
298 *
299 * There are no alignment constraints on buffer, address or length.
300 *
301 * @note If on-chip flash encryption is used, this function returns raw (ie encrypted) data. Use the flash cache
302 * to transparently decrypt data.
303 *
304 * @return
305 * - ESP_OK: success
306 * - ESP_ERR_NO_MEM: Buffer is in external PSRAM which cannot be concurrently accessed, and a temporary internal buffer could not be allocated.
307 * - or a flash error code if operation failed.
308 */
309 esp_err_t esp_flash_read(esp_flash_t *chip, void *buffer, uint32_t address, uint32_t length);
310
311 /** @brief Write data to the SPI flash chip
312 *
313 * @param chip Pointer to identify flash chip. If NULL, esp_flash_default_chip is substituted. Must have been successfully initialised via esp_flash_init()
314 * @param address Address on flash to write to. Must be previously erased (SPI NOR flash can only write bits 1->0).
315 * @param buffer Pointer to a buffer with the data to write. To get better performance, this should be in the DRAM and word aligned.
316 * @param length Length (in bytes) of data to write.
317 *
318 * There are no alignment constraints on buffer, address or length.
319 *
320 * @return
321 * - ESP_OK on success,
322 * - ESP_FAIL, bad write, this will be detected only when CONFIG_SPI_FLASH_VERIFY_WRITE is enabled
323 * - ESP_ERR_NOT_SUPPORTED if the chip is not able to perform the operation. This is indicated by WREN = 1 after the command is sent.
324 * - Other flash error code if operation failed.
325 */
326 esp_err_t esp_flash_write(esp_flash_t *chip, const void *buffer, uint32_t address, uint32_t length);
327
328 /** @brief Encrypted and write data to the SPI flash chip using on-chip hardware flash encryption
329 *
330 * @param chip Pointer to identify flash chip. Must be NULL (the main flash chip). For other chips, encrypted write is not supported.
331 * @param address Address on flash to write to. 16 byte aligned. Must be previously erased (SPI NOR flash can only write bits 1->0).
332 * @param buffer Pointer to a buffer with the data to write.
333 * @param length Length (in bytes) of data to write. 16 byte aligned.
334 *
335 * @note Both address & length must be 16 byte aligned, as this is the encryption block size
336 *
337 * @return
338 * - ESP_OK: on success
339 * - ESP_FAIL: bad write, this will be detected only when CONFIG_SPI_FLASH_VERIFY_WRITE is enabled
340 * - ESP_ERR_NOT_SUPPORTED: encrypted write not supported for this chip.
341 * - ESP_ERR_INVALID_ARG: Either the address, buffer or length is invalid.
342 */
343 esp_err_t esp_flash_write_encrypted(esp_flash_t *chip, uint32_t address, const void *buffer, uint32_t length);
344
345 /** @brief Read and decrypt data from the SPI flash chip using on-chip hardware flash encryption
346 *
347 * @param chip Pointer to identify flash chip. Must be NULL (the main flash chip). For other chips, encrypted read is not supported.
348 * @param address Address on flash to read from.
349 * @param out_buffer Pointer to a buffer for the data to read to.
350 * @param length Length (in bytes) of data to read.
351 *
352 * @return
353 * - ESP_OK: on success
354 * - ESP_ERR_NOT_SUPPORTED: encrypted read not supported for this chip.
355 */
356 esp_err_t esp_flash_read_encrypted(esp_flash_t *chip, uint32_t address, void *out_buffer, uint32_t length);
357
358 /** @brief Pointer to the "default" SPI flash chip, ie the main chip attached to the MCU.
359
360 This chip is used if the 'chip' argument pass to esp_flash_xxx API functions is ever NULL.
361 */
362 extern esp_flash_t *esp_flash_default_chip;
363
364
365 /*******************************************************************************
366 * Utility Functions
367 ******************************************************************************/
368
369 /**
370 * @brief Returns true if chip is configured for Quad I/O or Quad Fast Read.
371 *
372 * @param chip Pointer to SPI flash chip to use. If NULL, esp_flash_default_chip is substituted.
373 *
374 * @return true if flash works in quad mode, otherwise false
375 */
esp_flash_is_quad_mode(const esp_flash_t * chip)376 static inline bool esp_flash_is_quad_mode(const esp_flash_t *chip)
377 {
378 return (chip->read_mode == SPI_FLASH_QIO) || (chip->read_mode == SPI_FLASH_QOUT);
379 }
380
381 #ifdef __cplusplus
382 }
383 #endif
384
