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 56 57 /* Provide a Flash API for bootloader_support code, 58 that can be used from bootloader or app code. 59 60 This header is available to source code in the bootloader & 61 bootloader_support components only. 62 */ 63 64 /** 65 * @brief Get number of free pages 66 * 67 * @return Number of free pages 68 */ 69 uint32_t bootloader_mmap_get_free_pages(void); 70 71 /** 72 * @brief Map a region of flash to data memory 73 * 74 * @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. 75 * 76 * @important In app code, these functions are not thread safe. 77 * 78 * Call bootloader_munmap once for each successful call to bootloader_mmap. 79 * 80 * In esp-idf app, this function maps directly to spi_flash_mmap. 81 * 82 * @param offset - Starting flash offset to map to memory. 83 * @param length - Length of data to map. 84 * 85 * @return Pointer to mapped data memory (at src_addr), or NULL 86 * if an allocation error occured. 87 */ 88 const void *bootloader_mmap(uint32_t src_addr, uint32_t size); 89 90 91 /** 92 * @brief Unmap a previously mapped region of flash 93 * 94 * Call bootloader_munmap once for each successful call to bootloader_mmap. 95 */ 96 void bootloader_munmap(const void *mapping); 97 98 /** 99 * @brief Read data from Flash. 100 * 101 * 102 * @note All of src, dest and size have to be 4-byte aligned. 103 * 104 * @param src source address of the data in Flash. 105 * @param dest pointer to the destination buffer 106 * @param size length of data 107 * @param allow_decrypt If true and flash encryption is enabled, data on flash 108 * will be decrypted transparently as part of the read. 109 * 110 * @return ESP_OK on success, ESP_ERR_FLASH_OP_FAIL on SPI failure, 111 * ESP_ERR_FLASH_OP_TIMEOUT on SPI timeout. 112 */ 113 esp_err_t bootloader_flash_read(size_t src_addr, void *dest, size_t size, bool allow_decrypt); 114 115 116 /** 117 * @brief Write data to Flash. 118 * 119 * @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. 120 * 121 * Note: In bootloader, when write_encrypted == true, the src buffer is encrypted in place. 122 * 123 * @param dest_addr Destination address to write in Flash. 124 * @param src Pointer to the data to write to flash 125 * @param size Length of data in bytes. 126 * @param write_encrypted If true, data will be written encrypted on flash. 127 * 128 * @return ESP_OK on success, ESP_ERR_FLASH_OP_FAIL on SPI failure, 129 * ESP_ERR_FLASH_OP_TIMEOUT on SPI timeout. 130 */ 131 esp_err_t bootloader_flash_write(size_t dest_addr, void *src, size_t size, bool write_encrypted); 132 133 /** 134 * @brief Erase the Flash sector. 135 * 136 * @param sector Sector number, the count starts at sector 0, 4KB per sector. 137 * 138 * @return esp_err_t 139 */ 140 esp_err_t bootloader_flash_erase_sector(size_t sector); 141 142 /** 143 * @brief Erase the Flash range. 144 * 145 * @param start_addr start address of flash offset 146 * @param size sector aligned size to be erased 147 * 148 * @return esp_err_t 149 */ 150 esp_err_t bootloader_flash_erase_range(uint32_t start_addr, uint32_t size); 151 152 /** 153 * @brief Execute a user command on the flash 154 * 155 * @param command The command value to execute. 156 * @param mosi_data MOSI data to send 157 * @param mosi_len Length of MOSI data, in bits 158 * @param miso_len Length of MISO data to receive, in bits 159 * @return Received MISO data 160 */ 161 uint32_t bootloader_execute_flash_command(uint8_t command, uint32_t mosi_data, uint8_t mosi_len, uint8_t miso_len); 162 163 /** 164 * @brief Read the SFDP of the flash 165 * 166 * @param sfdp_addr Address of the parameter to read 167 * @param miso_byte_num Bytes to read 168 * @return The read SFDP, little endian, 4 bytes at most 169 */ 170 uint32_t bootloader_flash_read_sfdp(uint32_t sfdp_addr, unsigned int miso_byte_num); 171 172 /** 173 * @brief Enable the flash write protect (WEL bit). 174 */ 175 void bootloader_enable_wp(void); 176 177 /** 178 * @brief Once this function is called, 179 * any on-going internal operations will be terminated and the device will return to its default power-on 180 * state and lose all the current volatile settings, such as Volatile Status Register bits, Write Enable Latch 181 * (WEL) status, Program/Erase Suspend status, etc. 182 */ 183 void bootloader_spi_flash_reset(void); 184 185 #ifdef __cplusplus 186 } 187 #endif 188 189 #endif 190
