1 /* 2 * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 #ifndef __BOOTLOADER_FLASH_H 7 #define __BOOTLOADER_FLASH_H 8 9 #include <stddef.h> 10 #include <stdbool.h> 11 #include <stdint.h> 12 #include <esp_err.h> 13 #include <spi_flash_mmap.h> /* including in bootloader for error values */ 14 #include "sdkconfig.h" 15 #include "bootloader_flash.h" 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 #define FLASH_SECTOR_SIZE 0x1000 22 #define FLASH_BLOCK_SIZE 0x10000 23 #define MMAP_ALIGNED_MASK (SPI_FLASH_MMU_PAGE_SIZE - 1) 24 #define MMU_FLASH_MASK (~(SPI_FLASH_MMU_PAGE_SIZE - 1)) 25 26 /** 27 * MMU mapping must always be in the unit of a SPI_FLASH_MMU_PAGE_SIZE 28 * This macro is a helper for you to get needed page nums to be mapped. e.g.: 29 * Let's say SPI_FLASH_MMU_PAGE_SIZE is 64KB. 30 * - v_start = 0x4200_0004 31 * - size = 4 * 64KB 32 * 33 * You should map from 0x4200_0000, then map 5 pages. 34 */ 35 #define GET_REQUIRED_MMU_PAGES(size, v_start) ((size + (v_start - (v_start & MMU_FLASH_MASK)) + SPI_FLASH_MMU_PAGE_SIZE - 1) / SPI_FLASH_MMU_PAGE_SIZE) 36 37 /* SPI commands (actual on-wire commands not SPI controller bitmasks) 38 Suitable for use with the bootloader_execute_flash_command static function. 39 */ 40 #define CMD_RDID 0x9F 41 #define CMD_WRSR 0x01 42 #define CMD_WRSR2 0x31 /* Not all SPI flash uses this command */ 43 #define CMD_WRSR3 0x11 /* Not all SPI flash uses this command */ 44 #define CMD_WREN 0x06 45 #define CMD_WRENVSR 0x50 /* Flash write enable for volatile SR bits */ 46 #define CMD_WRDI 0x04 47 #define CMD_RDSR 0x05 48 #define CMD_RDSR2 0x35 /* Not all SPI flash uses this command */ 49 #define CMD_RDSR3 0x15 /* Not all SPI flash uses this command */ 50 #define CMD_OTPEN 0x3A /* Enable OTP mode, not all SPI flash uses this command */ 51 #define CMD_RDSFDP 0x5A /* Read the SFDP of the flash */ 52 #define CMD_RESUME 0x7A /* Resume command to clear flash suspend bit */ 53 #define CMD_RESETEN 0x66 54 #define CMD_RESET 0x99 55 #define CMD_FASTRD_4B 0x0C 56 #define CMD_SLOWRD_4B 0x13 57 58 59 /* Provide a Flash API for bootloader_support code, 60 that can be used from bootloader or app code. 61 62 This header is available to source code in the bootloader & 63 bootloader_support components only. 64 */ 65 66 /** 67 * @brief Get number of free pages 68 * 69 * @return Number of free pages 70 */ 71 uint32_t bootloader_mmap_get_free_pages(void); 72 73 /** 74 * @brief Map a region of flash to data memory 75 * 76 * @important In bootloader code, only one region can be bootloader_mmaped at once. The previous region must be bootloader_munmapped before another region is mapped. 77 * 78 * @important In app code, these functions are not thread safe. 79 * 80 * Call bootloader_munmap once for each successful call to bootloader_mmap. 81 * 82 * In esp-idf app, this function maps directly to spi_flash_mmap. 83 * 84 * @param offset - Starting flash offset to map to memory. 85 * @param length - Length of data to map. 86 * 87 * @return Pointer to mapped data memory (at src_addr), or NULL 88 * if an allocation error occured. 89 */ 90 const void *bootloader_mmap(uint32_t src_addr, uint32_t size); 91 92 /* use ROM functions to mmap */ 93 const void *esp_rom_flash_mmap(uint32_t src_addr, uint32_t size); 94 95 /** 96 * @brief Unmap a previously mapped region of flash 97 * 98 * Call bootloader_munmap once for each successful call to bootloader_mmap. 99 */ 100 void bootloader_munmap(const void *mapping); 101 102 /* use ROM functions to unmmap */ 103 void esp_rom_flash_unmmap(const void *mapping); 104 105 /** 106 * @brief Read data from Flash. 107 * 108 * 109 * @note All of src, dest and size have to be 4-byte aligned. 110 * 111 * @param src source address of the data in Flash. 112 * @param dest pointer to the destination buffer 113 * @param size length of data 114 * @param allow_decrypt If true and flash encryption is enabled, data on flash 115 * will be decrypted transparently as part of the read. 116 * 117 * @return ESP_OK on success, ESP_ERR_FLASH_OP_FAIL on SPI failure, 118 * ESP_ERR_FLASH_OP_TIMEOUT on SPI timeout. 119 */ 120 esp_err_t bootloader_flash_read(size_t src_addr, void *dest, size_t size, bool allow_decrypt); 121 122 /* use ROM functions to flash read */ 123 esp_err_t esp_rom_flash_read(size_t src_addr, void *dest, size_t size, bool allow_decrypt); 124 125 /** 126 * @brief Write data to Flash. 127 * 128 * @note All of dest_addr, src and size have to be 4-byte aligned. If write_encrypted is set, dest_addr and size must be 32-byte aligned. 129 * 130 * Note: In bootloader, when write_encrypted == true, the src buffer is encrypted in place. 131 * 132 * @param dest_addr Destination address to write in Flash. 133 * @param src Pointer to the data to write to flash 134 * @param size Length of data in bytes. 135 * @param write_encrypted If true, data will be written encrypted on flash. 136 * 137 * @return ESP_OK on success, ESP_ERR_FLASH_OP_FAIL on SPI failure, 138 * ESP_ERR_FLASH_OP_TIMEOUT on SPI timeout. 139 */ 140 esp_err_t bootloader_flash_write(size_t dest_addr, void *src, size_t size, bool write_encrypted); 141 142 /* use ROM functions to flash write */ 143 esp_err_t esp_rom_flash_write(size_t dest_addr, void *src, size_t size, bool write_encrypted); 144 145 /** 146 * @brief Erase the Flash sector. 147 * 148 * @param sector Sector number, the count starts at sector 0, 4KB per sector. 149 * 150 * @return esp_err_t 151 */ 152 esp_err_t bootloader_flash_erase_sector(size_t sector); 153 154 /* use ROM functions to flash erase */ 155 esp_err_t esp_rom_flash_erase_sector(size_t sector); 156 157 /** 158 * @brief Erase the Flash range. 159 * 160 * @param start_addr start address of flash offset 161 * @param size sector aligned size to be erased 162 * 163 * @return esp_err_t 164 */ 165 esp_err_t bootloader_flash_erase_range(uint32_t start_addr, uint32_t size); 166 167 /* use ROM functions to flash range read */ 168 esp_err_t esp_rom_flash_erase_range(uint32_t start_addr, uint32_t size); 169 170 /** 171 * @brief Execute a user command on the flash 172 * 173 * @param command The command value to execute. 174 * @param mosi_data MOSI data to send 175 * @param mosi_len Length of MOSI data, in bits 176 * @param miso_len Length of MISO data to receive, in bits 177 * @return Received MISO data 178 */ 179 uint32_t bootloader_execute_flash_command(uint8_t command, uint32_t mosi_data, uint8_t mosi_len, uint8_t miso_len); 180 181 /** 182 * @brief Read the SFDP of the flash 183 * 184 * @param sfdp_addr Address of the parameter to read 185 * @param miso_byte_num Bytes to read 186 * @return The read SFDP, little endian, 4 bytes at most 187 */ 188 uint32_t bootloader_flash_read_sfdp(uint32_t sfdp_addr, unsigned int miso_byte_num); 189 190 /** 191 * @brief Enable the flash write protect (WEL bit). 192 */ 193 void bootloader_enable_wp(void); 194 195 /** 196 * @brief Once this function is called, 197 * any on-going internal operations will be terminated and the device will return to its default power-on 198 * state and lose all the current volatile settings, such as Volatile Status Register bits, Write Enable Latch 199 * (WEL) status, Program/Erase Suspend status, etc. 200 */ 201 void bootloader_spi_flash_reset(void); 202 203 #ifdef __cplusplus 204 } 205 #endif 206 207 #endif 208
