1 // Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 #ifndef __BOOTLOADER_FLASH_H
15 #define __BOOTLOADER_FLASH_H
16
17 #include <stddef.h>
18 #include <stdbool.h>
19 #include <stdint.h>
20 #include <esp_err.h>
21 #include <esp_spi_flash.h> /* including in bootloader for error values */
22 #include "sdkconfig.h"
23 #include "bootloader_flash.h"
24
25 #define FLASH_SECTOR_SIZE 0x1000
26 #define FLASH_BLOCK_SIZE 0x10000
27 #define MMAP_ALIGNED_MASK 0x0000FFFF
28
29 /* SPI commands (actual on-wire commands not SPI controller bitmasks)
30 Suitable for use with the bootloader_execute_flash_command static function.
31 */
32 #define CMD_RDID 0x9F
33 #define CMD_WRSR 0x01
34 #define CMD_WRSR2 0x31 /* Not all SPI flash uses this command */
35 #define CMD_WREN 0x06
36 #define CMD_WRDI 0x04
37 #define CMD_RDSR 0x05
38 #define CMD_RDSR2 0x35 /* Not all SPI flash uses this command */
39 #define CMD_OTPEN 0x3A /* Enable OTP mode, not all SPI flash uses this command */
40 #define CMD_WRAP 0x77 /* Set burst with wrap command */
41 #define CMD_RESUME 0x7A /* Resume command to clear flash suspend bit */
42
43
44 /* Provide a Flash API for bootloader_support code,
45 that can be used from bootloader or app code.
46
47 This header is available to source code in the bootloader &
48 bootloader_support components only.
49 */
50
51 /**
52 * @brief Get number of free pages
53 *
54 * @return Number of free pages
55 */
56 uint32_t bootloader_mmap_get_free_pages(void);
57
58 /**
59 * @brief Map a region of flash to data memory
60 *
61 * @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.
62 *
63 * @important In app code, these functions are not thread safe.
64 *
65 * Call bootloader_munmap once for each successful call to bootloader_mmap.
66 *
67 * In esp-idf app, this function maps directly to spi_flash_mmap.
68 *
69 * @param offset - Starting flash offset to map to memory.
70 * @param length - Length of data to map.
71 *
72 * @return Pointer to mapped data memory (at src_addr), or NULL
73 * if an allocation error occured.
74 */
75 const void *bootloader_mmap(uint32_t src_addr, uint32_t size);
76
77
78 /**
79 * @brief Unmap a previously mapped region of flash
80 *
81 * Call bootloader_munmap once for each successful call to bootloader_mmap.
82 */
83 void bootloader_munmap(const void *mapping);
84
85 /**
86 * @brief Read data from Flash.
87 *
88 *
89 * @note All of src, dest and size have to be 4-byte aligned.
90 *
91 * @param src source address of the data in Flash.
92 * @param dest pointer to the destination buffer
93 * @param size length of data
94 * @param allow_decrypt If true and flash encryption is enabled, data on flash
95 * will be decrypted transparently as part of the read.
96 *
97 * @return ESP_OK on success, ESP_ERR_FLASH_OP_FAIL on SPI failure,
98 * ESP_ERR_FLASH_OP_TIMEOUT on SPI timeout.
99 */
100 esp_err_t bootloader_flash_read(size_t src_addr, void *dest, size_t size, bool allow_decrypt);
101
102
103 /**
104 * @brief Write data to Flash.
105 *
106 * @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.
107 *
108 * Note: In bootloader, when write_encrypted == true, the src buffer is encrypted in place.
109 *
110 * @param dest_addr Destination address to write in Flash.
111 * @param src Pointer to the data to write to flash
112 * @param size Length of data in bytes.
113 * @param write_encrypted If true, data will be written encrypted on flash.
114 *
115 * @return ESP_OK on success, ESP_ERR_FLASH_OP_FAIL on SPI failure,
116 * ESP_ERR_FLASH_OP_TIMEOUT on SPI timeout.
117 */
118 esp_err_t bootloader_flash_write(size_t dest_addr, void *src, size_t size, bool write_encrypted);
119
120 /**
121 * @brief Erase the Flash sector.
122 *
123 * @param sector Sector number, the count starts at sector 0, 4KB per sector.
124 *
125 * @return esp_err_t
126 */
127 esp_err_t bootloader_flash_erase_sector(size_t sector);
128
129 /**
130 * @brief Erase the Flash range.
131 *
132 * @param start_addr start address of flash offset
133 * @param size sector aligned size to be erased
134 *
135 * @return esp_err_t
136 */
137 esp_err_t bootloader_flash_erase_range(uint32_t start_addr, uint32_t size);
138
139 /* Cache MMU block size */
140 #define MMU_BLOCK_SIZE 0x00010000
141
142 /* Cache MMU address mask (MMU tables ignore bits which are zero) */
143 #define MMU_FLASH_MASK (~(MMU_BLOCK_SIZE - 1))
144
145 /**
146 * @brief Calculate the number of cache pages to map
147 * @param size size of data to map
148 * @param vaddr virtual address where data will be mapped
149 * @return number of cache MMU pages required to do the mapping
150 */
bootloader_cache_pages_to_map(uint32_t size,uint32_t vaddr)151 static inline uint32_t bootloader_cache_pages_to_map(uint32_t size, uint32_t vaddr)
152 {
153 return (size + (vaddr - (vaddr & MMU_FLASH_MASK)) + MMU_BLOCK_SIZE - 1) / MMU_BLOCK_SIZE;
154 }
155
156 /**
157 * @brief Execute a user command on the flash
158 *
159 * @param command The command value to execute.
160 * @param mosi_data MOSI data to send
161 * @param mosi_len Length of MOSI data, in bits
162 * @param miso_len Length of MISO data to receive, in bits
163 * @return Received MISO data
164 */
165 uint32_t bootloader_execute_flash_command(uint8_t command, uint32_t mosi_data, uint8_t mosi_len, uint8_t miso_len);
166
167 /**
168 * @brief Enable the flash write protect (WEL bit).
169 */
170 void bootloader_enable_wp(void);
171
172 #endif
173