esp-idf/components/wear_levelling
Sudeep Mohanty e22b4007d3 esp_hw_support: Removed deprecated CPU util functions
The following files were deleted:
- components/esp_hw_support/include/soc/cpu.h
- components/soc/esp32s3/include/soc/cpu.h

The following functions are deprecated:
- get_sp()

The following functions declared in soc/cpu.h are now moved to esp_cpu.h:
- esp_cpu_configure_region_protection()

The following functions declared in soc/cpu.h are now moved to components/xtensa/include/esp_cpu_utils.h:
- esp_cpu_process_stack_pc()

All files with soc/cpu.h inclusion are updated to include esp_cpu.h instead.

Signed-off-by: Sudeep Mohanty <sudeep.mohanty@espressif.com>
2021-12-28 16:58:37 +05:30
..
doc Added test for version update from V1 to V2. Problems for tests on host are fixed. Random function changed to esp_random() 2018-07-31 08:45:42 +03:00
include Replace all DOS line endings with Unix 2018-07-12 19:10:37 +08:00
private_include support for wear levelling in fatfs partition generator 2021-11-29 16:57:47 +01:00
test_apps esp_hw_support: Removed deprecated CPU util functions 2021-12-28 16:58:37 +05:30
test_wl_host host tests: add missing header files for compiling host tests 2021-07-20 17:44:20 +08:00
.gitignore nvs_flash, wear_levelling: ignore host test files 2017-04-17 11:01:18 +08:00
CMakeLists.txt wear_levelling: Re-enable for ESP32-C3 2020-12-24 14:18:01 +11:00
crc32.cpp separate rom from esp32 component to esp_rom 2019-03-21 18:51:45 +08:00
crc32.h Whitespace: Automated whitespace fixes (large commit) 2020-11-11 07:36:35 +00:00
Kconfig Correct Kconfigs according to the coding style 2019-01-29 13:37:01 +01:00
Partition.cpp Replace all DOS line endings with Unix 2018-07-12 19:10:37 +08:00
README_CN.rst Add Chinese translation for README files in components and tools folders, including: 2019-09-06 20:18:19 +08:00
README.rst docs: update api-reference chapters for C3 2021-03-01 14:58:08 +08:00
SPI_Flash.cpp Replace all DOS line endings with Unix 2018-07-12 19:10:37 +08:00
wear_levelling.cpp Added test for version update from V1 to V2. Problems for tests on host are fixed. Random function changed to esp_random() 2018-07-31 08:45:42 +03:00
WL_Ext_Perf.cpp Replace all DOS line endings with Unix 2018-07-12 19:10:37 +08:00
WL_Ext_Safe.cpp Replace all DOS line endings with Unix 2018-07-12 19:10:37 +08:00
WL_Flash.cpp Whitespace: Automated whitespace fixes (large commit) 2020-11-11 07:36:35 +00:00

Wear Levelling API
==================

:link_to_translation:`zh_CN:[中文]`

Overview
--------
Most of flash memory and especially SPI flash that is used in {IDF_TARGET_NAME} has a sector-based organization and also has a limited number of erase/modification cycles per memory sector. The wear levelling component helps to distribute wear and tear among sectors more evenly without requiring any attention from the user.

The wear levelling component provides API functions related to reading, writing, erasing, and memory mapping of data in external SPI flash through the partition component. The component also has higher-level API functions which work with the FAT filesystem defined in :doc:`FAT filesystem </api-reference/storage/fatfs>`.

The wear levelling component, together with the FAT FS component, uses FAT FS sectors of 4096 bytes, which is a standard size for flash memory. With this size, the component shows the best performance but needs additional memory in RAM.

To save internal memory, the component has two additional modes which both use sectors of 512 bytes:

- **Performance mode.** Erase sector operation data is stored in RAM, the sector is erased, and then data is copied back to flash memory. However, if a device is powered off for any reason, all 4096 bytes of data is lost.
- **Safety mode.** The data is first saved to flash memory, and after the sector is erased, the data is saved back. If a device is powered off, the data can be recovered as soon as the device boots up.

The default settings are as follows:
- Sector size is 512 bytes
- Performance mode

You can change the settings through the configuration menu.


The wear levelling component does not cache data in RAM. The write and erase functions modify flash directly, and flash contents are consistent when the function returns.


Wear Levelling access API functions
-----------------------------------

This is the set of API functions for working with data in flash:

- ``wl_mount`` - initializes the wear levelling module and mounts the specified partition
- ``wl_unmount`` - unmounts the partition and deinitializes the wear levelling module
- ``wl_erase_range`` - erases a range of addresses in flash
- ``wl_write`` - writes data to a partition
- ``wl_read`` - reads data from a partition
- ``wl_size`` - returns the size of available memory in bytes
- ``wl_sector_size`` - returns the size of one sector

As a rule, try to avoid using raw wear levelling functions and use filesystem-specific functions instead.


Memory Size
-----------

The memory size is calculated in the wear levelling module based on partition parameters. The module uses some sectors of flash for internal data.