1 /* 2 * SPDX-FileCopyrightText: 2019-2022 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 /** 8 * System level MSPI APIs (private) 9 */ 10 #pragma once 11 12 #include <stdint.h> 13 #include <stdbool.h> 14 #include "sdkconfig.h" 15 #include "esp_rom_spiflash.h" 16 #include "esp_err.h" 17 #include "esp_flash.h" 18 #include "hal/spi_flash_hal.h" 19 #include "spi_flash_override.h" 20 #include "soc/soc_caps.h" 21 #include "soc/clk_tree_defs.h" 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 // Type of MSPI IO 28 typedef enum { 29 ESP_MSPI_IO_CLK = 0, 30 ESP_MSPI_IO_Q, 31 ESP_MSPI_IO_D, 32 ESP_MSPI_IO_CS0, /* cs for spi flash */ 33 ESP_MSPI_IO_HD, 34 ESP_MSPI_IO_WP, 35 #if SOC_SPI_MEM_SUPPORT_OPI_MODE 36 ESP_MSPI_IO_DQS, 37 ESP_MSPI_IO_D4, 38 ESP_MSPI_IO_D5, 39 ESP_MSPI_IO_D6, 40 ESP_MSPI_IO_D7, 41 #endif // SOC_SPI_MEM_SUPPORT_OPI_MODE 42 #if CONFIG_SPIRAM 43 ESP_MSPI_IO_CS1, /* cs for spi ram */ 44 #endif 45 ESP_MSPI_IO_MAX, /* Maximum IO MSPI occupied */ 46 } esp_mspi_io_t; 47 48 /** 49 * @brief To initislize the MSPI pins 50 */ 51 void esp_mspi_pin_init(void); 52 53 /** 54 * @brief Get the number of the GPIO corresponding to the given MSPI io 55 * 56 * @param[in] io MSPI io 57 * 58 * @return MSPI IO number 59 */ 60 uint8_t esp_mspi_get_io(esp_mspi_io_t io); 61 62 /** 63 * @brief Set SPI1 registers to make ROM functions work 64 * @note This function is used for setting SPI1 registers to the state that ROM SPI functions work 65 */ 66 void spi_flash_set_rom_required_regs(void); 67 68 /** 69 * @brief Initialize main flash 70 * @param chip Pointer to main SPI flash(SPI1 CS0) chip to use.. 71 */ 72 esp_err_t esp_flash_init_main(esp_flash_t *chip); 73 74 /** 75 * @brief Should be only used by SPI1 Flash driver to know the necessary timing registers 76 * @param out_timing_config Pointer to timing_tuning parameters. 77 */ 78 void spi_timing_get_flash_timing_param(spi_flash_hal_timing_config_t *out_timing_config); 79 80 /** 81 * @brief Get the knowledge if the MSPI timing is tuned or not 82 */ 83 bool spi_timing_is_tuned(void); 84 85 /** 86 * @brief Set Flash chip specifically required MSPI register settings here 87 */ 88 void spi_flash_set_vendor_required_regs(void); 89 90 /** 91 * @brief Judge whether need to reset flash when brownout. 92 * Set` flash_brownout_needs_reset` inside the function if really need reset. 93 */ 94 void spi_flash_needs_reset_check(void); 95 96 /** 97 * @brief Set flag to reset flash. set when erase chip or program chip 98 * 99 * @param bool status. True if flash is eraing. False if flash is not erasing. 100 * 101 * @return None. 102 */ 103 void spi_flash_set_erasing_flag(bool status); 104 105 /** 106 * @brief Judge whether need to reset flash when brownout. 107 * 108 * @return true if need reset, otherwise false. 109 */ 110 bool spi_flash_brownout_need_reset(void); 111 112 #if CONFIG_SPI_FLASH_HPM_ON 113 /** 114 * @brief Enable SPI flash high performance mode. 115 * 116 * @note 1. When `CONFIG_SPI_FLASH_HPM_ON` is True, caller can always call this function without taking whether the used 117 * frequency falls into the HPM range into consideration. 118 * 2. However, caller shouldn't attempt to call this function on Octal flash. `CONFIG_SPI_FLASH_HPM_ON` may be 119 * True when `CONFIG_ESPTOOLPY_FLASH_MODE_AUTO_DETECT && !CONFIG_ESPTOOLPY_OCT_FLASH` 120 * 121 * @return ESP_OK if success. 122 */ 123 esp_err_t spi_flash_enable_high_performance_mode(void); 124 125 /** 126 * @brief Get the flash dummy through this function 127 * This can be used when one flash has several dummy configurations to enable the high performance mode. 128 * @note Don't forget to subtract one when assign to the register of mspi e.g. if the value you get is 4, (4-1=3) should be assigned to the register. 129 * 130 * @return Pointer to spi_flash_hpm_dummy_conf_t. 131 */ 132 const spi_flash_hpm_dummy_conf_t *spi_flash_hpm_get_dummy(void); 133 134 /** 135 * @brief Used to judge whether flash works under HPM mode with dummy adjustment. 136 * 137 * @return true Yes, and work under HPM with adjusting dummy. Otherwise, false. 138 */ 139 bool spi_flash_hpm_dummy_adjust(void); 140 #endif //CONFIG_SPI_FLASH_HPM_ON 141 142 #if SOC_SPI_MEM_SUPPORT_WRAP 143 /** 144 * @brief set wrap size of flash 145 * 146 * @param wrap_size: wrap mode support disable, 16 32, 64 byte 147 * 148 * @return esp_err_t : ESP_OK for successful. 149 * 150 */ 151 esp_err_t spi_flash_wrap_enable(spi_flash_wrap_size_t wrap_size); 152 153 /** 154 * @brief Probe flash wrap method 155 * 156 * @return esp_err_t: ESP_OK for success 157 */ 158 esp_err_t spi_flash_wrap_probe(void); 159 160 /** 161 * @brief disable cache wrap 162 */ 163 esp_err_t spi_flash_wrap_disable(void); 164 165 /** 166 * @brief Check whether flash and esp chip supports wrap mode. 167 * 168 * @param wrap_size wrap size. 169 * @return true: wrap support, otherwise, false. 170 */ 171 bool spi_flash_support_wrap_size(uint32_t wrap_size); 172 173 #endif //SOC_SPI_MEM_SUPPORT_WRAP 174 175 /** 176 * @brief SPI flash critical section enter function. 177 * 178 */ 179 typedef void (*spi_flash_guard_start_func_t)(void); 180 /** 181 * @brief SPI flash critical section exit function. 182 */ 183 typedef void (*spi_flash_guard_end_func_t)(void); 184 185 /** 186 * Structure holding SPI flash access critical sections management functions. 187 * 188 * Flash API uses two types of flash access management functions: 189 * 1) Functions which prepare/restore flash cache and interrupts before calling 190 * appropriate ROM functions (SPIWrite, SPIRead and SPIEraseBlock): 191 * - 'start' function should disables flash cache and non-IRAM interrupts and 192 * is invoked before the call to one of ROM function above. 193 * - 'end' function should restore state of flash cache and non-IRAM interrupts and 194 * is invoked after the call to one of ROM function above. 195 * These two functions are not recursive. 196 * 197 * Different versions of the guarding functions should be used depending on the context of 198 * execution (with or without functional OS). In normal conditions when flash API is called 199 * from task the functions use OS primitives. When there is no OS at all or when 200 * it is not guaranteed that OS is functional (accessing flash from exception handler) these 201 * functions cannot use OS primitives or even does not need them (multithreaded access is not possible). 202 * 203 * @note Structure and corresponding guard functions should not reside in flash. 204 * For example structure can be placed in DRAM and functions in IRAM sections. 205 */ 206 typedef struct { 207 spi_flash_guard_start_func_t start; /**< critical section start function. */ 208 spi_flash_guard_end_func_t end; /**< critical section end function. */ 209 } spi_flash_guard_funcs_t; 210 211 212 /** 213 * @brief Sets guard functions to access flash. 214 * 215 * @note Pointed structure and corresponding guard functions should not reside in flash. 216 * For example structure can be placed in DRAM and functions in IRAM sections. 217 * 218 * @param funcs pointer to structure holding flash access guard functions. 219 */ 220 void spi_flash_guard_set(const spi_flash_guard_funcs_t* funcs); 221 222 /** 223 * @brief Get the guard functions used for flash access 224 * 225 * @return The guard functions that were set via spi_flash_guard_set(). These functions 226 * can be called if implementing custom low-level SPI flash operations. 227 */ 228 const spi_flash_guard_funcs_t *spi_flash_guard_get(void); 229 230 /** 231 * @brief Default OS-aware flash access guard functions 232 */ 233 extern const spi_flash_guard_funcs_t g_flash_guard_default_ops; 234 235 /** 236 * @brief Non-OS flash access guard functions 237 * 238 * @note This version of flash guard functions is to be used when no OS is present or from panic handler. 239 * It does not use any OS primitives and IPC and implies that only calling CPU is active. 240 */ 241 extern const spi_flash_guard_funcs_t g_flash_guard_no_os_ops; 242 243 /** 244 * @brief This function is used to re-initialize the flash mmap when using ROM flash 245 * implementations. 246 * 247 * @note Only called in startup. User should not call this function. 248 */ 249 void spi_flash_rom_impl_init(void); 250 251 #if SOC_MEMSPI_CLOCK_IS_INDEPENDENT 252 /** 253 * @brief This functions is used to change spi flash clock source between PLL and others, which is used after system wake up from a low power mode or 254 * enter low-power mode like sleep. 255 * @param clk_src mspi(flash) clock source. 256 * 257 * @note Only called in startup. User should not call this function. 258 */ 259 void spi_flash_set_clock_src(soc_periph_mspi_clk_src_t clk_src); 260 #endif 261 262 #ifdef __cplusplus 263 } 264 #endif 265
