1 /* 2 * SPDX-FileCopyrightText: 2021 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 8 #pragma once 9 10 #include "sdkconfig.h" 11 #include <stdint.h> 12 #include <stdbool.h> 13 #include "esp_rom_spiflash_defs.h" 14 15 #ifdef __cplusplus 16 extern "C" { 17 #endif 18 19 typedef enum { 20 ESP_ROM_SPIFLASH_QIO_MODE = 0, 21 ESP_ROM_SPIFLASH_QOUT_MODE, 22 ESP_ROM_SPIFLASH_DIO_MODE, 23 ESP_ROM_SPIFLASH_DOUT_MODE, 24 ESP_ROM_SPIFLASH_FASTRD_MODE, 25 ESP_ROM_SPIFLASH_SLOWRD_MODE, 26 ESP_ROM_SPIFLASH_OPI_STR_MODE, 27 ESP_ROM_SPIFLASH_OPI_DTR_MODE, 28 ESP_ROM_SPIFLASH_OOUT_MODE, 29 ESP_ROM_SPIFLASH_OIO_STR_MODE, 30 ESP_ROM_SPIFLASH_OIO_DTR_MODE, 31 ESP_ROM_SPIFLASH_QPI_MODE, 32 } esp_rom_spiflash_read_mode_t; 33 34 typedef struct { 35 uint32_t device_id; 36 uint32_t chip_size; // chip size in bytes 37 uint32_t block_size; 38 uint32_t sector_size; 39 uint32_t page_size; 40 uint32_t status_mask; 41 } esp_rom_spiflash_chip_t; 42 43 typedef enum { 44 ESP_ROM_SPIFLASH_RESULT_OK, 45 ESP_ROM_SPIFLASH_RESULT_ERR, 46 ESP_ROM_SPIFLASH_RESULT_TIMEOUT 47 } esp_rom_spiflash_result_t; 48 49 /** 50 * @brief SPI Flash init, clock divisor is 4, use 1 line Slow read mode. 51 * Please do not call this function in SDK. 52 * 53 * @param uint32_t ishspi: 0 for spi, 1 for hspi, flash pad decided by strapping 54 * else, bit[5:0] spiclk, bit[11:6] spiq, bit[17:12] spid, bit[23:18] spics0, bit[29:24] spihd 55 * 56 * @param uint8_t legacy: always keeping false. 57 * 58 * @return None 59 */ 60 void esp_rom_spiflash_attach(uint32_t ishspi, bool legacy); 61 62 /** 63 * @brief SPI Read Flash status register. We use CMD 0x05 (RDSR). 64 * Please do not call this function in SDK. 65 * 66 * @param esp_rom_spiflash_chip_t *spi : The information for Flash, which is exported from ld file. 67 * 68 * @param uint32_t *status : The pointer to which to return the Flash status value. 69 * 70 * @return ESP_ROM_SPIFLASH_RESULT_OK : read OK. 71 * ESP_ROM_SPIFLASH_RESULT_ERR : read error. 72 * ESP_ROM_SPIFLASH_RESULT_TIMEOUT : read timeout. 73 */ 74 esp_rom_spiflash_result_t esp_rom_spiflash_read_status(esp_rom_spiflash_chip_t *spi, uint32_t *status); 75 76 /** 77 * @brief SPI Read Flash status register bits 8-15. We use CMD 0x35 (RDSR2). 78 * Please do not call this function in SDK. 79 * 80 * @param esp_rom_spiflash_chip_t *spi : The information for Flash, which is exported from ld file. 81 * 82 * @param uint32_t *status : The pointer to which to return the Flash status value. 83 * 84 * @return ESP_ROM_SPIFLASH_RESULT_OK : read OK. 85 * ESP_ROM_SPIFLASH_RESULT_ERR : read error. 86 * ESP_ROM_SPIFLASH_RESULT_TIMEOUT : read timeout. 87 */ 88 esp_rom_spiflash_result_t esp_rom_spiflash_read_statushigh(esp_rom_spiflash_chip_t *spi, uint32_t *status); 89 90 /** 91 * @brief Write status to Flash status register. 92 * Please do not call this function in SDK. 93 * 94 * @param esp_rom_spiflash_chip_t *spi : The information for Flash, which is exported from ld file. 95 * 96 * @param uint32_t status_value : Value to . 97 * 98 * @return ESP_ROM_SPIFLASH_RESULT_OK : write OK. 99 * ESP_ROM_SPIFLASH_RESULT_ERR : write error. 100 * ESP_ROM_SPIFLASH_RESULT_TIMEOUT : write timeout. 101 */ 102 esp_rom_spiflash_result_t esp_rom_spiflash_write_status(esp_rom_spiflash_chip_t *spi, uint32_t status_value); 103 104 /** 105 * @brief Use a command to Read Flash status register. 106 * Please do not call this function in SDK. 107 * 108 * @param esp_rom_spiflash_chip_t *spi : The information for Flash, which is exported from ld file. 109 * 110 * @param uint32_t*status : The pointer to which to return the Flash status value. 111 * 112 * @return ESP_ROM_SPIFLASH_RESULT_OK : read OK. 113 * ESP_ROM_SPIFLASH_RESULT_ERR : read error. 114 * ESP_ROM_SPIFLASH_RESULT_TIMEOUT : read timeout. 115 */ 116 esp_rom_spiflash_result_t esp_rom_spiflash_read_user_cmd(uint32_t *status, uint8_t cmd); 117 118 /** 119 * @brief Config SPI Flash read mode when init. 120 * Please do not call this function in SDK. 121 * 122 * @param esp_rom_spiflash_read_mode_t mode : QIO/QOUT/DIO/DOUT/FastRD/SlowRD. 123 * 124 * This function does not try to set the QIO Enable bit in the status register, caller is responsible for this. 125 * 126 * @return ESP_ROM_SPIFLASH_RESULT_OK : config OK. 127 * ESP_ROM_SPIFLASH_RESULT_ERR : config error. 128 * ESP_ROM_SPIFLASH_RESULT_TIMEOUT : config timeout. 129 */ 130 esp_rom_spiflash_result_t esp_rom_spiflash_config_readmode(esp_rom_spiflash_read_mode_t mode); 131 132 /** 133 * @brief Config SPI Flash clock divisor. 134 * Please do not call this function in SDK. 135 * 136 * @param uint8_t freqdiv: clock divisor. 137 * 138 * @param uint8_t spi: 0 for SPI0, 1 for SPI1. 139 * 140 * @return ESP_ROM_SPIFLASH_RESULT_OK : config OK. 141 * ESP_ROM_SPIFLASH_RESULT_ERR : config error. 142 * ESP_ROM_SPIFLASH_RESULT_TIMEOUT : config timeout. 143 */ 144 esp_rom_spiflash_result_t esp_rom_spiflash_config_clk(uint8_t freqdiv, uint8_t spi); 145 146 /** 147 * @brief Update SPI Flash parameter. 148 * Please do not call this function in SDK. 149 * 150 * @param uint32_t deviceId : Device ID read from SPI, the low 32 bit. 151 * 152 * @param uint32_t chip_size : The Flash size. 153 * 154 * @param uint32_t block_size : The Flash block size. 155 * 156 * @param uint32_t sector_size : The Flash sector size. 157 * 158 * @param uint32_t page_size : The Flash page size. 159 * 160 * @param uint32_t status_mask : The Mask used when read status from Flash(use single CMD). 161 * 162 * @return ESP_ROM_SPIFLASH_RESULT_OK : Update OK. 163 * ESP_ROM_SPIFLASH_RESULT_ERR : Update error. 164 * ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Update timeout. 165 */ 166 esp_rom_spiflash_result_t esp_rom_spiflash_config_param(uint32_t deviceId, uint32_t chip_size, uint32_t block_size, 167 uint32_t sector_size, uint32_t page_size, uint32_t status_mask); 168 169 /** 170 * @brief Erase whole flash chip. 171 * Please do not call this function in SDK. 172 * 173 * @param None 174 * 175 * @return ESP_ROM_SPIFLASH_RESULT_OK : Erase OK. 176 * ESP_ROM_SPIFLASH_RESULT_ERR : Erase error. 177 * ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Erase timeout. 178 */ 179 esp_rom_spiflash_result_t esp_rom_spiflash_erase_chip(void); 180 181 /** 182 * @brief Erase a 64KB block of flash 183 * Uses SPI flash command D8H. 184 * Please do not call this function in SDK. 185 * 186 * @param uint32_t block_num : Which block to erase. 187 * 188 * @return ESP_ROM_SPIFLASH_RESULT_OK : Erase OK. 189 * ESP_ROM_SPIFLASH_RESULT_ERR : Erase error. 190 * ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Erase timeout. 191 */ 192 esp_rom_spiflash_result_t esp_rom_spiflash_erase_block(uint32_t block_num); 193 194 /** 195 * @brief Erase a sector of flash. 196 * Uses SPI flash command 20H. 197 * Please do not call this function in SDK. 198 * 199 * @param uint32_t sector_num : Which sector to erase. 200 * 201 * @return ESP_ROM_SPIFLASH_RESULT_OK : Erase OK. 202 * ESP_ROM_SPIFLASH_RESULT_ERR : Erase error. 203 * ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Erase timeout. 204 */ 205 esp_rom_spiflash_result_t esp_rom_spiflash_erase_sector(uint32_t sector_num); 206 207 /** 208 * @brief Erase some sectors. 209 * Please do not call this function in SDK. 210 * 211 * @param uint32_t start_addr : Start addr to erase, should be sector aligned. 212 * 213 * @param uint32_t area_len : Length to erase, should be sector aligned. 214 * 215 * @return ESP_ROM_SPIFLASH_RESULT_OK : Erase OK. 216 * ESP_ROM_SPIFLASH_RESULT_ERR : Erase error. 217 * ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Erase timeout. 218 */ 219 esp_rom_spiflash_result_t esp_rom_spiflash_erase_area(uint32_t start_addr, uint32_t area_len); 220 221 /** 222 * @brief Write Data to Flash, you should Erase it yourself if need. 223 * Please do not call this function in SDK. 224 * 225 * @param uint32_t dest_addr : Address to write, should be 4 bytes aligned. 226 * 227 * @param const uint32_t *src : The pointer to data which is to write. 228 * 229 * @param uint32_t len : Length to write, should be 4 bytes aligned. 230 * 231 * @return ESP_ROM_SPIFLASH_RESULT_OK : Write OK. 232 * ESP_ROM_SPIFLASH_RESULT_ERR : Write error. 233 * ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Write timeout. 234 */ 235 esp_rom_spiflash_result_t esp_rom_spiflash_write(uint32_t dest_addr, const uint32_t *src, int32_t len); 236 237 /** 238 * @brief Read Data from Flash, you should Erase it yourself if need. 239 * Please do not call this function in SDK. 240 * 241 * @param uint32_t src_addr : Address to read, should be 4 bytes aligned. 242 * 243 * @param uint32_t *dest : The buf to read the data. 244 * 245 * @param uint32_t len : Length to read, should be 4 bytes aligned. 246 * 247 * @return ESP_ROM_SPIFLASH_RESULT_OK : Read OK. 248 * ESP_ROM_SPIFLASH_RESULT_ERR : Read error. 249 * ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Read timeout. 250 */ 251 esp_rom_spiflash_result_t esp_rom_spiflash_read(uint32_t src_addr, uint32_t *dest, int32_t len); 252 253 /** 254 * @brief SPI1 go into encrypto mode. 255 * Please do not call this function in SDK. 256 * 257 * @param None 258 * 259 * @return None 260 */ 261 void esp_rom_spiflash_write_encrypted_enable(void); 262 263 /** 264 * @brief Prepare 32 Bytes data to encrpto writing, you should Erase it yourself if need. 265 * Please do not call this function in SDK. 266 * 267 * @param uint32_t flash_addr : Address to write, should be 32 bytes aligned. 268 * 269 * @param uint32_t *data : The pointer to data which is to write. 270 * 271 * @return ESP_ROM_SPIFLASH_RESULT_OK : Prepare OK. 272 * ESP_ROM_SPIFLASH_RESULT_ERR : Prepare error. 273 * ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Prepare timeout. 274 */ 275 esp_rom_spiflash_result_t esp_rom_spiflash_prepare_encrypted_data(uint32_t flash_addr, uint32_t *data); 276 277 /** 278 * @brief SPI1 go out of encrypto mode. 279 * Please do not call this function in SDK. 280 * 281 * @param None 282 * 283 * @return None 284 */ 285 void esp_rom_spiflash_write_encrypted_disable(void); 286 287 /** 288 * @brief Write data to flash with transparent encryption. 289 * @note Sectors to be written should already be erased. 290 * 291 * @note Please do not call this function in SDK. 292 * 293 * @param uint32_t flash_addr : Address to write, should be 32 byte aligned. 294 * 295 * @param uint32_t *data : The pointer to data to write. Note, this pointer must 296 * be 32 bit aligned and the content of the data will be 297 * modified by the encryption function. 298 * 299 * @param uint32_t len : Length to write, should be 32 bytes aligned. 300 * 301 * @return ESP_ROM_SPIFLASH_RESULT_OK : Data written successfully. 302 * ESP_ROM_SPIFLASH_RESULT_ERR : Encryption write error. 303 * ESP_ROM_SPIFLASH_RESULT_TIMEOUT : Encrypto write timeout. 304 */ 305 esp_rom_spiflash_result_t esp_rom_spiflash_write_encrypted(uint32_t flash_addr, uint32_t *data, uint32_t len); 306 307 308 /** @brief Wait until SPI flash write operation is complete 309 * 310 * @note Please do not call this function in SDK. 311 * 312 * Reads the Write In Progress bit of the SPI flash status register, 313 * repeats until this bit is zero (indicating write complete). 314 * 315 * @return ESP_ROM_SPIFLASH_RESULT_OK : Write is complete 316 * ESP_ROM_SPIFLASH_RESULT_ERR : Error while reading status. 317 */ 318 esp_rom_spiflash_result_t esp_rom_spiflash_wait_idle(esp_rom_spiflash_chip_t *spi); 319 320 321 /** @brief Enable Quad I/O pin functions 322 * 323 * @note Please do not call this function in SDK. 324 * 325 * Sets the HD & WP pin functions for Quad I/O modes, based on the 326 * efuse SPI pin configuration. 327 * 328 * @param wp_gpio_num - Number of the WP pin to reconfigure for quad I/O. 329 * 330 * @param spiconfig - Pin configuration, as returned from ets_efuse_get_spiconfig(). 331 * - If this parameter is 0, default SPI pins are used and wp_gpio_num parameter is ignored. 332 * - If this parameter is 1, default HSPI pins are used and wp_gpio_num parameter is ignored. 333 * - For other values, this parameter encodes the HD pin number and also the CLK pin number. CLK pin selection is used 334 * to determine if HSPI or SPI peripheral will be used (use HSPI if CLK pin is the HSPI clock pin, otherwise use SPI). 335 * Both HD & WP pins are configured via GPIO matrix to map to the selected peripheral. 336 */ 337 void esp_rom_spiflash_select_qio_pins(uint8_t wp_gpio_num, uint32_t spiconfig); 338 339 /** 340 * @brief Clear WEL bit unconditionally. 341 * 342 * @return always ESP_ROM_SPIFLASH_RESULT_OK 343 */ 344 esp_rom_spiflash_result_t esp_rom_spiflash_write_disable(void); 345 346 /** 347 * @brief Set WREN bit. 348 * 349 * @param esp_rom_spiflash_chip_t *spi : The information for Flash, which is exported from ld file. 350 * 351 * @return always ESP_ROM_SPIFLASH_RESULT_OK 352 */ 353 esp_rom_spiflash_result_t esp_rom_spiflash_write_enable(esp_rom_spiflash_chip_t *spi); 354 355 /* Flash data defined in ROM*/ 356 #if CONFIG_IDF_TARGET_ESP32 || CONFIG_IDF_TARGET_ESP32S2 357 extern esp_rom_spiflash_chip_t g_rom_flashchip; 358 extern uint8_t g_rom_spiflash_dummy_len_plus[]; 359 #else 360 typedef struct { 361 esp_rom_spiflash_chip_t chip; 362 uint8_t dummy_len_plus[3]; 363 uint8_t sig_matrix; 364 } esp_rom_spiflash_legacy_data_t; 365 366 extern esp_rom_spiflash_legacy_data_t *rom_spiflash_legacy_data; 367 #define g_rom_flashchip (rom_spiflash_legacy_data->chip) 368 #define g_rom_spiflash_dummy_len_plus (rom_spiflash_legacy_data->dummy_len_plus) 369 #endif 370 371 #ifdef __cplusplus 372 } 373 #endif 374
