1 /* 2 * SPDX-FileCopyrightText: 2019-2021 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #pragma once 8 9 #include "esp_flash_partitions.h" 10 #include "esp32s3/rom/spi_flash.h" 11 #include "esp32s3/rom/opi_flash.h" 12 #include "mspi_timing_tuning_configs.h" 13 14 #ifdef __cplusplus 15 extern "C" { 16 #endif 17 18 19 #define SPI_TIMING_CONFIG_NUM_DEFAULT 20 //This should be larger than the max available timing config num 20 #define SPI_TIMING_TEST_DATA_LEN 64 21 #define SPI_TIMING_PSRAM_TEST_DATA_ADDR 0 22 #define SPI_TIMING_FLASH_TEST_DATA_ADDR ESP_BOOTLOADER_OFFSET 23 /** 24 * @note BACKGOURND: 25 * 26 * The SPI FLASH module clock and SPI PSRAM module clock is divided from the SPI core clock, core clock is from system clock: 27 * 28 * PLL ----| |---- FLASH Module Clock 29 * XTAL ----|----> Core Clock ---->| 30 * RTC8M ----| |---- PSRAM Module Clock 31 * 32 * 33 * DDR stands for double data rate, MSPI samples at both posedge and negedge. So the real spped will be doubled. 34 * Speed from high to low: 120M DDR > 80M DDR > 120 SDR > 80M SDR > ... 35 * 36 * Module with speed lower than 120M SDR doesn't need to be tuned 37 * 38 * @note LIMITATION: 39 * How to determine the core clock on 728. There are 2 limitations. 40 * 41 * 1. MSPI FLASH and PSRAM share the core clock register. Therefore: 42 * SPI_TIMING_FLASH_EXPECTED_CORE_CLK_MHZ == SPI_TIMING_PSRAM_EXPECTED_CORE_CLK_MHZ 43 * 44 * 2. DDR mode requires the core clock divider (core_clk / div = module_clk) to be power of 2. 45 */ 46 //--------------------------------------FLASH Sampling Mode --------------------------------------// 47 #define SPI_TIMING_FLASH_DTR_MODE CONFIG_ESPTOOLPY_FLASH_SAMPLE_MODE_DTR 48 #define SPI_TIMING_FLASH_STR_MODE CONFIG_ESPTOOLPY_FLASH_SAMPLE_MODE_STR 49 //--------------------------------------FLASH Module Clock --------------------------------------// 50 #if CONFIG_ESPTOOLPY_FLASHFREQ_20M 51 #define SPI_TIMING_FLASH_MODULE_CLOCK 20 52 #elif CONFIG_ESPTOOLPY_FLASHFREQ_40M 53 #define SPI_TIMING_FLASH_MODULE_CLOCK 40 54 #elif CONFIG_ESPTOOLPY_FLASHFREQ_80M 55 #define SPI_TIMING_FLASH_MODULE_CLOCK 80 56 #else //CONFIG_ESPTOOLPY_FLASHFREQ_120M 57 #define SPI_TIMING_FLASH_MODULE_CLOCK 120 58 #endif 59 //------------------------------------FLASH Needs Tuning or not-------------------------------------// 60 #if SPI_TIMING_FLASH_DTR_MODE 61 #define SPI_TIMING_FLASH_NEEDS_TUNING (SPI_TIMING_FLASH_MODULE_CLOCK > 40) 62 #elif SPI_TIMING_FLASH_STR_MODE 63 #define SPI_TIMING_FLASH_NEEDS_TUNING (SPI_TIMING_FLASH_MODULE_CLOCK > 80) 64 #endif 65 66 //--------------------------------------PSRAM Sampling Mode --------------------------------------// 67 #define SPI_TIMING_PSRAM_DTR_MODE CONFIG_SPIRAM_MODE_OCT 68 #define SPI_TIMING_PSRAM_STR_MODE !CONFIG_SPIRAM_MODE_OCT 69 //--------------------------------------PSRAM Module Clock --------------------------------------// 70 #if CONFIG_ESP32S3_SPIRAM_SUPPORT 71 #if CONFIG_SPIRAM_SPEED_40M 72 #define SPI_TIMING_PSRAM_MODULE_CLOCK 40 73 #elif CONFIG_SPIRAM_SPEED_80M 74 #define SPI_TIMING_PSRAM_MODULE_CLOCK 80 75 #else //CONFIG_SPIRAM_SPEED_120M 76 #define SPI_TIMING_PSRAM_MODULE_CLOCK 120 77 #endif 78 #else //Disable PSRAM 79 #define SPI_TIMING_PSRAM_MODULE_CLOCK 10 //Define this to 10MHz, because we rely on `SPI_TIMING_PSRAM_MODULE_CLOCK` macro for calculation and check below, see `Determine the Core Clock` chapter 80 #endif 81 //------------------------------------PSRAM Needs Tuning or not-------------------------------------// 82 #if SPI_TIMING_PSRAM_DTR_MODE 83 #define SPI_TIMING_PSRAM_NEEDS_TUNING (SPI_TIMING_PSRAM_MODULE_CLOCK > 40) 84 #elif SPI_TIMING_PSRAM_STR_MODE 85 #define SPI_TIMING_PSRAM_NEEDS_TUNING (SPI_TIMING_PSRAM_MODULE_CLOCK > 80) 86 #endif 87 88 89 /** 90 * @note Define A feasible core clock below: SPI_TIMING_FLASH_EXPECTED_CORE_CLK_MHZ and SPI_TIMING_PSRAM_EXPECTED_CORE_CLK_MHZ 91 */ 92 /** 93 * Due to MSPI core clock is used by both MSPI Flash and PSRAM clock, 94 * define the STR/DTR mode here for selecting the core clock: 95 * @note If either Flash or PSRAM, or both of them are set to DTR mode, then we use DIV 2 96 */ 97 #if (SPI_TIMING_FLASH_DTR_MODE || SPI_TIMING_PSRAM_DTR_MODE) 98 #define SPI_TIMING_CORE_CLOCK_DIV 2 99 #else //#if (SPI_TIMING_FLASH_STR_MODE && (SPI_TIMING_PSRAM_STR_MODE || !CONFIG_ESP32S3_SPIRAM_SUPPORT)) 100 #define SPI_TIMING_CORE_CLOCK_DIV 1 101 #endif 102 103 ///////////////////////////////////// FLASH CORE CLOCK ///////////////////////////////////// 104 //FLASH 80M DTR 105 #if SPI_TIMING_FLASH_DTR_MODE && CONFIG_ESPTOOLPY_FLASHFREQ_80M 106 #define SPI_TIMING_FLASH_EXPECTED_CORE_CLK_MHZ 160 107 #endif 108 109 //FLASH 120M DTR 110 #if SPI_TIMING_FLASH_DTR_MODE && CONFIG_ESPTOOLPY_FLASHFREQ_120M 111 #define SPI_TIMING_FLASH_EXPECTED_CORE_CLK_MHZ 240 112 #endif 113 114 //FLASH 120M STR 115 #if SPI_TIMING_FLASH_STR_MODE && CONFIG_ESPTOOLPY_FLASHFREQ_120M 116 #if (SPI_TIMING_CORE_CLOCK_DIV == 2) 117 #define SPI_TIMING_FLASH_EXPECTED_CORE_CLK_MHZ 240 118 #elif (SPI_TIMING_CORE_CLOCK_DIV == 1) 119 #define SPI_TIMING_FLASH_EXPECTED_CORE_CLK_MHZ 120 120 #endif 121 #endif //FLASH 120M STR 122 123 ///////////////////////////////////// PSRAM CORE CLOCK ///////////////////////////////////// 124 //PSRAM 80M DTR 125 #if SPI_TIMING_PSRAM_DTR_MODE && CONFIG_SPIRAM_SPEED_80M 126 #define SPI_TIMING_PSRAM_EXPECTED_CORE_CLK_MHZ 160 127 #endif 128 129 //PSRAM 120M STR 130 #if SPI_TIMING_PSRAM_STR_MODE && CONFIG_SPIRAM_SPEED_120M 131 #if (SPI_TIMING_CORE_CLOCK_DIV == 2) 132 #define SPI_TIMING_PSRAM_EXPECTED_CORE_CLK_MHZ 240 133 #elif (SPI_TIMING_CORE_CLOCK_DIV == 1) 134 #define SPI_TIMING_PSRAM_EXPECTED_CORE_CLK_MHZ 120 135 #endif 136 #endif //PSRAM 120M STR 137 138 139 //------------------------------------------Determine the Core Clock-----------------------------------------------// 140 /** 141 * @note 142 * Limitation 1: 143 * On 728, MSPI FLASH and PSRAM share the core clock register. Therefore, 144 * the expected CORE CLOCK frequencies should be the same. 145 */ 146 #if SPI_TIMING_FLASH_NEEDS_TUNING && SPI_TIMING_PSRAM_NEEDS_TUNING 147 _Static_assert(SPI_TIMING_FLASH_EXPECTED_CORE_CLK_MHZ == SPI_TIMING_PSRAM_EXPECTED_CORE_CLK_MHZ, "FLASH and PSRAM Mode configuration are not supported"); 148 #define SPI_TIMING_CORE_CLOCK_MHZ SPI_TIMING_FLASH_EXPECTED_CORE_CLK_MHZ 149 150 //If only FLASH needs tuning, the core clock COULD be as FLASH expected 151 #elif SPI_TIMING_FLASH_NEEDS_TUNING && !SPI_TIMING_PSRAM_NEEDS_TUNING 152 _Static_assert(SPI_TIMING_FLASH_EXPECTED_CORE_CLK_MHZ % SPI_TIMING_PSRAM_MODULE_CLOCK == 0, "FLASH and PSRAM Mode configuration are not supported"); 153 #define SPI_TIMING_CORE_CLOCK_MHZ SPI_TIMING_FLASH_EXPECTED_CORE_CLK_MHZ 154 155 //If only PSRAM needs tuning, the core clock COULD be as PSRAM expected 156 #elif !SPI_TIMING_FLASH_NEEDS_TUNING && SPI_TIMING_PSRAM_NEEDS_TUNING 157 _Static_assert(SPI_TIMING_PSRAM_EXPECTED_CORE_CLK_MHZ % SPI_TIMING_FLASH_MODULE_CLOCK == 0, "FLASH and PSRAM Mode configuration are not supported"); 158 #define SPI_TIMING_CORE_CLOCK_MHZ SPI_TIMING_PSRAM_EXPECTED_CORE_CLK_MHZ 159 160 #else 161 #define SPI_TIMING_CORE_CLOCK_MHZ 80 162 #endif 163 164 /** 165 * @note 166 * Limitation 2: DDR mode requires the core clock divider (core_clk / div = module_clk) to be power of 2. 167 */ 168 #define CHECK_POWER_OF_2(n) ((((n) & ((~(n)) + 1))) == (n)) 169 170 #if SPI_TIMING_FLASH_DTR_MODE 171 _Static_assert(CHECK_POWER_OF_2(SPI_TIMING_CORE_CLOCK_MHZ / SPI_TIMING_FLASH_MODULE_CLOCK), "FLASH and PSRAM Mode configuration are not supported"); 172 #endif 173 #if SPI_TIMING_PSRAM_DTR_MODE 174 _Static_assert(CHECK_POWER_OF_2(SPI_TIMING_CORE_CLOCK_MHZ / SPI_TIMING_PSRAM_MODULE_CLOCK), "FLASH and PSRAM Mode configuration are not supported"); 175 #endif 176 177 178 //------------------------------------------Helper Macros to get FLASH/PSRAM tuning configs-----------------------------------------------// 179 #define __GET_TUNING_CONFIG(type, core_clock, module_clock, mode) \ 180 (spi_timing_config_t) { .tuning_config_table = MSPI_TIMING_##type##_CONFIG_TABLE_CORE_CLK_##core_clock##M_MODULE_CLK_##module_clock##M_##mode, \ 181 .available_config_num = MSPI_TIMING_##type##_CONFIG_NUM_CORE_CLK_##core_clock##M_MODULE_CLK_##module_clock##M_##mode, \ 182 .default_config_id = MSPI_TIMING_##type##_DEFAULT_CONFIG_ID_CORE_CLK_##core_clock##M_MODULE_CLK_##module_clock##M_##mode } 183 184 #define _GET_TUNING_CONFIG(type, core_clock, module_clock, mode) __GET_TUNING_CONFIG(type, core_clock, module_clock, mode) 185 186 #define SPI_TIMING_FLASH_GET_TUNING_CONFIG(core_clock_mhz, module_clock_mhz, mode) _GET_TUNING_CONFIG(FLASH, core_clock_mhz, module_clock_mhz, mode) 187 #define SPI_TIMING_PSRAM_GET_TUNING_CONFIG(core_clock_mhz, module_clock_mhz, mode) _GET_TUNING_CONFIG(PSRAM, core_clock_mhz, module_clock_mhz, mode) 188 189 190 /** 191 * SPI timing tuning registers. The macro `SPI_TIMING_FLASH_CONFIG_TABLE` below is the corresponding register value table. 192 * Upper layer rely on these 3 registers to tune the timing. 193 */ 194 typedef struct { 195 uint8_t spi_din_mode; /*!< input signal delay mode*/ 196 uint8_t spi_din_num; /*!< input signal delay number */ 197 uint8_t extra_dummy_len; /*!< extra dummy length*/ 198 } spi_timing_tuning_param_t; 199 200 typedef struct { 201 spi_timing_tuning_param_t tuning_config_table[SPI_TIMING_CONFIG_NUM_DEFAULT]; //available timing tuning configs 202 uint32_t available_config_num; 203 uint32_t default_config_id; //If tuning fails, we use this one as default 204 } spi_timing_config_t; 205 206 /** 207 * The SPI FLASH module clock and SPI PSRAM module clock is divided from the SPI core clock, core clock is from system clock: 208 * 209 * PLL ----| |---- FLASH Module Clock 210 * XTAL ----|----> Core Clock ---->| 211 * RTC8M ----| |---- PSRAM Module Clock 212 * 213 */ 214 typedef enum { 215 SPI_TIMING_CONFIG_CORE_CLOCK_80M, 216 SPI_TIMING_CONFIG_CORE_CLOCK_120M, 217 SPI_TIMING_CONFIG_CORE_CLOCK_160M, 218 SPI_TIMING_CONFIG_CORE_CLOCK_240M 219 } spi_timing_config_core_clock_t; 220 221 222 spi_timing_config_core_clock_t spi_timing_config_get_core_clock(void); 223 void spi_timing_config_set_core_clock(uint8_t spi_num, spi_timing_config_core_clock_t core_clock); 224 225 void spi_timing_config_set_flash_clock(uint8_t spi_num, uint32_t freqdiv); 226 void spi_timing_config_flash_set_din_mode_num(uint8_t spi_num, uint8_t din_mode, uint8_t din_num); 227 void spi_timing_config_flash_set_extra_dummy(uint8_t spi_num, uint8_t extra_dummy); 228 void spi_timing_config_flash_read_data(uint8_t spi_num, uint8_t *buf, uint32_t addr, uint32_t len); 229 230 void spi_timing_config_set_psram_clock(uint8_t spi_num, uint32_t freqdiv); 231 void spi_timing_config_psram_set_din_mode_num(uint8_t spi_num, uint8_t din_mode, uint8_t din_num); 232 void spi_timing_config_psram_set_extra_dummy(uint8_t spi_num, uint8_t extra_dummy); 233 void spi_timing_config_psram_write_data(uint8_t spi_num, uint8_t *buf, uint32_t addr, uint32_t len); 234 void spi_timing_config_psram_read_data(uint8_t spi_num,uint8_t *buf, uint32_t addr, uint32_t len); 235 236 /*------------------------------------------------------------------------------------------------- 237 * SPI1 Timing Tuning APIs 238 * These APIs are only used in `spi_flash_timing_tuning.c/sweep_for_success_sample_points()` for 239 * configuring SPI1 timing tuning related registers to find best tuning parameter 240 *-------------------------------------------------------------------------------------------------*/ 241 void spi_timing_config_flash_tune_din_num_mode(uint8_t din_mode, uint8_t din_num); 242 void spi_timing_config_flash_tune_dummy(uint8_t extra_dummy); 243 void spi_timing_config_psram_tune_din_num_mode(uint8_t din_mode, uint8_t din_num); 244 void spi_timing_config_psram_tune_dummy(uint8_t extra_dummy); 245 246 /** 247 * SPI1 register info get APIs. These APIs inform `spi_flash_timing_tuning.c` (driver layer) of the SPI1 flash settings. 248 * In this way, other components (e.g.: esp_flash driver) can get the info from it (`spi_flash_timing_tuning.c`). 249 */ 250 void spi_timing_config_get_cs_timing(uint8_t *setup_time, uint32_t *hold_time); 251 uint32_t spi_timing_config_get_flash_clock_reg(void); 252 253 #ifdef __cplusplus 254 } 255 #endif 256
