1menu "Main Flash configuration"
2    depends on !APP_BUILD_TYPE_PURE_RAM_APP
3
4    menu "SPI Flash behavior when brownout"
5
6        config SPI_FLASH_BROWNOUT_RESET_XMC
7            bool "Enable sending reset when brownout for XMC flash chips"
8            default y
9            select SPI_FLASH_BROWNOUT_RESET
10            help
11                When this option is selected, the patch will be enabled for XMC.
12                Follow the recommended flow by XMC for better stability.
13
14                DO NOT DISABLE UNLESS YOU KNOW WHAT YOU ARE DOING.
15
16        config SPI_FLASH_BROWNOUT_RESET
17            bool
18            default y
19            select ESP_SYSTEM_BROWNOUT_INTR
20            help
21                When brownout happens during flash erase/write operations,
22                send reset command to stop the flash operations to improve stability.
23
24    endmenu
25
26    menu "Optional and Experimental Features (READ DOCS FIRST)"
27
28        comment "Features here require specific hardware (READ DOCS FIRST!)"
29
30        config SPI_FLASH_UNDER_HIGH_FREQ
31            bool
32            default y if ESPTOOLPY_FLASHFREQ_120M
33            help
34                This is a helper config for HPM. Invisible for users.
35
36        choice SPI_FLASH_HPM
37            prompt "High Performance Mode (READ DOCS FIRST, > 80MHz)"
38            # Currently, only esp32s3 allows high performance mode.
39            depends on IDF_TARGET_ESP32S3 && !ESPTOOLPY_OCT_FLASH
40            default SPI_FLASH_HPM_AUTO
41            help
42                Whether the High Performance Mode of Flash is enabled. As an optional feature, user needs to manually
43                enable this option as a confirmation. To be back-compatible with earlier IDF version, this option is
44                automatically enabled with warning when Flash running > 80Mhz.
45
46            config SPI_FLASH_HPM_ENA
47                # Not using name of SPI_FLASH_HPM_ENABLE because it was used as an invisible option and we don't want
48                # to inherit the value of that one
49                bool "Enable"
50            config SPI_FLASH_HPM_AUTO
51                bool "Auto (Not recommended)"
52            config SPI_FLASH_HPM_DIS
53                bool "Disabled"
54        endchoice
55
56        config SPI_FLASH_HPM_ON
57            bool
58            # For ESP32-S3, it's enabled by default. For later chips it should be disabled by default
59            default y if IDF_TARGET_ESP32S3 && ((SPI_FLASH_HPM_ENA || SPI_FLASH_HPM_AUTO)) || \
60                (!IDF_TARGET_ESP32S3 && SPI_FLASH_HPM_ENA)
61            help
62                This option is invisible, and will be selected automatically
63                when ``ESPTOOLPY_FLASHFREQ_120M`` is selected.
64
65        choice SPI_FLASH_HPM_DC
66            prompt "Support HPM using DC (READ DOCS FIRST)"
67            depends on SPI_FLASH_HPM_ON
68            default SPI_FLASH_HPM_DC_AUTO
69            help
70                This feature needs your bootloader to be compiled DC-aware (BOOTLOADER_FLASH_DC_AWARE=y). Otherwise the
71                chip will not be able to boot after a reset.
72
73            config SPI_FLASH_HPM_DC_AUTO
74                bool "Auto (Enable when bootloader support enabled (BOOTLOADER_FLASH_DC_AWARE))"
75            config SPI_FLASH_HPM_DC_DISABLE
76                bool "Disable (READ DOCS FIRST)"
77        endchoice
78
79        config SPI_FLASH_HPM_DC_ON
80            bool
81            default y if SPI_FLASH_HPM_DC_AUTO && BOOTLOADER_FLASH_DC_AWARE
82            help
83                This is a helper config for HPM. Whether HPM-DC is enabled is also determined by bootloader.
84                Invisible for users.
85
86        config SPI_FLASH_AUTO_SUSPEND
87            bool "Auto suspend long erase/write operations (READ DOCS FIRST)"
88            default n
89            depends on IDF_TARGET_ESP32C3 && !SPI_FLASH_ROM_IMPL
90            help
91                This option is disabled by default because it is supported only
92                for specific flash chips and for specific Espressif chips.
93                To evaluate if you can use this feature refer to
94                `Optional Features for Flash` > `Auto Suspend & Resume` of the `ESP-IDF Programming Guide`.
95
96                CAUTION: If you want to OTA to an app with this feature turned on, please make
97                sure the bootloader has the support for it. (later than IDF v4.3)
98
99                If you are using an official Espressif module, please contact Espressif Business support
100                to check if the module has the flash that support this feature installed.
101                Also refer to `Concurrency Constraints for Flash on SPI1` > `Flash Auto Suspend Feature`
102                before enabling this option.
103
104        config SPI_FLASH_FORCE_ENABLE_XMC_C_SUSPEND
105            bool "Enable XMC-C series flash chip suspend feature anyway"
106            default n
107            help
108                XMC-C series is regarded as not qualified for the Suspend feature, since its specification
109                has a tRS >= 1ms restriction. We strongly do not suggest using it for the Suspend feature.
110                However, if your product in field has enabled this feature, you may still enable this
111                config option to keep the legacy behavior.
112
113                For new users, DO NOT enable this config.
114
115    endmenu
116endmenu
117
118menu "SPI Flash driver"
119    depends on !APP_BUILD_TYPE_PURE_RAM_APP
120
121    config SPI_FLASH_VERIFY_WRITE
122        bool "Verify SPI flash writes"
123        depends on !SPI_FLASH_ROM_IMPL
124        default n
125        help
126            If this option is enabled, any time SPI flash is written then the data will be read
127            back and verified. This can catch hardware problems with SPI flash, or flash which
128            was not erased before verification.
129
130    config SPI_FLASH_LOG_FAILED_WRITE
131        bool "Log errors if verification fails"
132        depends on SPI_FLASH_VERIFY_WRITE
133        default n
134        help
135            If this option is enabled, if SPI flash write verification fails then a log error line
136            will be written with the address, expected & actual values. This can be useful when
137            debugging hardware SPI flash problems.
138
139    config SPI_FLASH_WARN_SETTING_ZERO_TO_ONE
140        bool "Log warning if writing zero bits to ones"
141        depends on SPI_FLASH_VERIFY_WRITE
142        default n
143        help
144            If this option is enabled, any SPI flash write which tries to set zero bits in the flash to
145            ones will log a warning. Such writes will not result in the requested data appearing identically
146            in flash once written, as SPI NOR flash can only set bits to one when an entire sector is erased.
147            After erasing, individual bits can only be written from one to zero.
148
149            Note that some software (such as SPIFFS) which is aware of SPI NOR flash may write one bits as an
150            optimisation, relying on the data in flash becoming a bitwise AND of the new data and any existing data.
151            Such software will log spurious warnings if this option is enabled.
152
153    config SPI_FLASH_ENABLE_COUNTERS
154        bool "Enable operation counters"
155        default n
156        help
157            This option enables the following APIs:
158
159            - esp_flash_reset_counters
160            - esp_flash_dump_counters
161            - esp_flash_get_counters
162
163            These APIs may be used to collect performance data for spi_flash APIs
164            and to help understand behaviour of libraries which use SPI flash.
165
166    config SPI_FLASH_ROM_DRIVER_PATCH
167        bool "Enable SPI flash ROM driver patched functions"
168        default y
169        help
170            Enable this flag to use patched versions of SPI flash ROM driver functions.
171            This option should be enabled, if any one of the following is true: (1) need to write
172            to flash on ESP32-D2WD; (2) main SPI flash is connected to non-default pins; (3) main
173            SPI flash chip is manufactured by ISSI.
174
175    config SPI_FLASH_ROM_IMPL
176        bool "Use esp_flash implementation in ROM"
177        depends on ESP_ROM_HAS_SPI_FLASH
178        default n
179        help
180            Enable this flag to use new SPI flash driver functions from ROM instead of ESP-IDF.
181
182            If keeping this as "n" in your project, you will have less free IRAM.
183            But you can use all of our flash features.
184
185            If making this as "y" in your project, you will increase free IRAM.
186            But you may miss out on some flash features and support for new flash chips.
187
188            Currently the ROM cannot support the following features:
189
190            - SPI_FLASH_AUTO_SUSPEND (C3, S3)
191
192    choice SPI_FLASH_DANGEROUS_WRITE
193        bool  "Writing to dangerous flash regions"
194        default SPI_FLASH_DANGEROUS_WRITE_ALLOWED if APP_BUILD_TYPE_RAM
195        default SPI_FLASH_DANGEROUS_WRITE_ABORTS
196        help
197            SPI flash APIs can optionally abort or return a failure code
198            if erasing or writing addresses that fall at the beginning
199            of flash (covering the bootloader and partition table) or that
200            overlap the app partition that contains the running app.
201
202            It is not recommended to ever write to these regions from an IDF app,
203            and this check prevents logic errors or corrupted firmware memory from
204            damaging these regions.
205
206            Note that this feature *does not* check calls to the esp_rom_xxx SPI flash
207            ROM functions. These functions should not be called directly from IDF
208            applications.
209
210        config SPI_FLASH_DANGEROUS_WRITE_ABORTS
211            bool "Aborts"
212        config SPI_FLASH_DANGEROUS_WRITE_FAILS
213            bool "Fails"
214        config SPI_FLASH_DANGEROUS_WRITE_ALLOWED
215            bool "Allowed"
216    endchoice
217
218    config SPI_FLASH_SHARE_SPI1_BUS
219        bool  "Support other devices attached to SPI1 bus"
220        default n
221        depends on IDF_TARGET_ESP32
222        select SPI_MASTER_ISR_IN_IRAM
223        help
224            Each SPI bus needs a lock for arbitration among devices. This allows multiple
225            devices on a same bus, but may reduce the speed of esp_flash driver access to the
226            main flash chip.
227
228            If you only need to use esp_flash driver to access the main flash chip, disable
229            this option, and the lock will be bypassed on SPI1 bus. Otherwise if extra devices
230            are needed to attach to SPI1 bus, enable this option.
231
232    config SPI_FLASH_BYPASS_BLOCK_ERASE
233        bool "Bypass a block erase and always do sector erase"
234        default n
235        help
236            Some flash chips can have very high "max" erase times, especially for block erase (32KB or 64KB).
237            This option allows to bypass "block erase" and always do sector erase commands.
238            This will be much slower overall in most cases, but improves latency for other code to run.
239
240    config SPI_FLASH_YIELD_DURING_ERASE
241        bool "Enables yield operation during flash erase"
242        default y
243        help
244            This allows to yield the CPUs between erase commands.
245            Prevents starvation of other tasks.
246            Please use this configuration together with ``SPI_FLASH_ERASE_YIELD_DURATION_MS`` and
247            ``SPI_FLASH_ERASE_YIELD_TICKS`` after carefully checking flash datasheet to avoid a
248            watchdog timeout.
249            For more information, please check `SPI Flash API` reference documentation
250            under section `OS Function`.
251
252    config SPI_FLASH_ERASE_YIELD_DURATION_MS
253        int "Duration of erasing to yield CPUs (ms)"
254        depends on SPI_FLASH_YIELD_DURING_ERASE
255        default 20
256        help
257            If a duration of one erase command is large
258            then it will yield CPUs after finishing a current command.
259
260    config SPI_FLASH_ERASE_YIELD_TICKS
261        int "CPU release time (tick) for an erase operation"
262        depends on SPI_FLASH_YIELD_DURING_ERASE
263        default 1
264        help
265            Defines how many ticks will be before returning to continue a erasing.
266
267    config SPI_FLASH_WRITE_CHUNK_SIZE
268        int "Flash write chunk size"
269        default 8192
270        range 256 8192
271        help
272            Flash write is broken down in terms of multiple (smaller) write operations.
273            This configuration options helps to set individual write chunk size, smaller
274            value here ensures that cache (and non-IRAM resident interrupts) remains
275            disabled for shorter duration.
276
277    config SPI_FLASH_SIZE_OVERRIDE
278        bool "Override flash size in bootloader header by ESPTOOLPY_FLASHSIZE"
279        default n
280        help
281            SPI Flash driver uses the flash size configured in bootloader header by default.
282            Enable this option to override flash size with latest ESPTOOLPY_FLASHSIZE value from
283            the app header if the size in the bootloader header is incorrect.
284
285    config SPI_FLASH_CHECK_ERASE_TIMEOUT_DISABLED
286        bool "Flash timeout checkout disabled"
287        default n
288        help
289            This option is helpful if you are using a flash chip whose timeout is quite large or unpredictable.
290
291    config SPI_FLASH_OVERRIDE_CHIP_DRIVER_LIST
292        bool "Override default chip driver list"
293        default n
294        help
295            This option allows the chip driver list to be customized, instead of using the default list provided by
296            ESP-IDF.
297
298            When this option is enabled, the default list is no longer compiled or linked. Instead, the
299            `default_registered_chips` structure must be provided by the user.
300
301            See example: custom_chip_driver under examples/storage for more details.
302
303    menu "Auto-detect flash chips"
304        visible if !SPI_FLASH_OVERRIDE_CHIP_DRIVER_LIST
305
306        orsource "./$IDF_TARGET/Kconfig.soc_caps.in"
307
308        config SPI_FLASH_SUPPORT_ISSI_CHIP
309            bool "ISSI"
310            default y if SPI_FLASH_VENDOR_ISSI_SUPPORTED
311            default n
312            help
313                Enable this to support auto detection of ISSI chips if chip vendor not directly
314                given by ``chip_drv`` member of the chip struct. This adds support for variant
315                chips, however will extend detecting time.
316
317        config SPI_FLASH_SUPPORT_MXIC_CHIP
318            bool "MXIC"
319            default y if SPI_FLASH_VENDOR_MXIC_SUPPORTED
320            default n
321            help
322                Enable this to support auto detection of MXIC chips if chip vendor not directly
323                given by ``chip_drv`` member of the chip struct. This adds support for variant
324                chips, however will extend detecting time.
325
326        config SPI_FLASH_SUPPORT_GD_CHIP
327            bool "GigaDevice"
328            default y if SPI_FLASH_VENDOR_GD_SUPPORTED
329            default n
330            help
331                Enable this to support auto detection of GD (GigaDevice) chips if chip vendor not
332                directly given by ``chip_drv`` member of the chip struct. If you are using Wrover
333                modules, please don't disable this, otherwise your flash may not work in 4-bit
334                mode.
335
336                This adds support for variant chips, however will extend detecting time and image
337                size. Note that the default chip driver supports the GD chips with product ID
338                60H.
339
340        config SPI_FLASH_SUPPORT_WINBOND_CHIP
341            bool "Winbond"
342            default y if SPI_FLASH_VENDOR_WINBOND_SUPPORTED
343            default n
344            help
345                Enable this to support auto detection of Winbond chips if chip vendor not directly
346                given by ``chip_drv`` member of the chip struct. This adds support for variant
347                chips, however will extend detecting time.
348
349        config SPI_FLASH_SUPPORT_BOYA_CHIP
350            bool "BOYA"
351            # ESP32 doesn't usually use this chip, default n to save iram.
352            default y if SPI_FLASH_VENDOR_BOYA_SUPPORTED
353            default n
354            help
355                Enable this to support auto detection of BOYA chips if chip vendor not directly
356                given by ``chip_drv`` member of the chip struct. This adds support for variant
357                chips, however will extend detecting time.
358
359        config SPI_FLASH_SUPPORT_TH_CHIP
360            bool "TH"
361            # ESP32 doesn't usually use this chip, default n to save iram.
362            default y if SPI_FLASH_VENDOR_TH_SUPPORTED
363            default n
364            help
365                Enable this to support auto detection of TH chips if chip vendor not directly
366                given by ``chip_drv`` member of the chip struct. This adds support for variant
367                chips, however will extend detecting time.
368
369        config SPI_FLASH_SUPPORT_MXIC_OPI_CHIP
370            bool "mxic (opi)"
371            depends on IDF_TARGET_ESP32S3
372            default y
373            help
374                Enable this to support auto detection of Octal MXIC chips if chip vendor not directly
375                given by ``chip_drv`` member of the chip struct. This adds support for variant
376                chips, however will extend detecting time.
377
378    endmenu #auto detect flash chips
379
380    config SPI_FLASH_ENABLE_ENCRYPTED_READ_WRITE
381        bool "Enable encrypted partition read/write operations"
382        default y
383        help
384            This option enables flash read/write operations to encrypted partition/s. This option
385            is kept enabled irrespective of state of flash encryption feature. However, in case
386            application is not using flash encryption feature and is in need of some additional
387            memory from IRAM region (~1KB) then this config can be disabled.
388
389endmenu
390