esp-idf/components/wear_levelling
Michael (XIAO Xufeng) 562af8f65e global: move the soc component out of the common list
This MR removes the common dependency from every IDF components to the SOC component.

Currently, in the ``idf_functions.cmake`` script, we include the header path of SOC component by default for all components.
But for better code organization (or maybe also benifits to the compiling speed), we may remove the dependency to SOC components for most components except the driver and kernel related components.

In CMAKE, we have two kinds of header visibilities (set by include path visibility):

(Assume component A --(depends on)--> B, B is the current component)

1. public (``COMPONENT_ADD_INCLUDEDIRS``): means this path is visible to other depending components (A) (visible to A and B)
2. private (``COMPONENT_PRIV_INCLUDEDIRS``): means this path is only visible to source files inside the component (visible to B only)

and we have two kinds of depending ways:

(Assume component A --(depends on)--> B --(depends on)--> C, B is the current component)

1. public (```COMPONENT_REQUIRES```): means B can access to public include path of C. All other components rely on you (A) will also be available for the public headers. (visible to A, B)
2. private (``COMPONENT_PRIV_REQUIRES``): means B can access to public include path of C, but don't propagate this relation to other components (A). (visible to B)

1. remove the common requirement in ``idf_functions.cmake``, this makes the SOC components invisible to all other components by default.
2. if a component (for example, DRIVER) really needs the dependency to SOC, add a private dependency to SOC for it.
3. some other components that don't really depends on the SOC may still meet some errors saying "can't find header soc/...", this is because it's depended component (DRIVER) incorrectly include the header of SOC in its public headers. Moving all this kind of #include into source files, or private headers
4. Fix the include requirements for some file which miss sufficient #include directives. (Previously they include some headers by the long long long header include link)

This is a breaking change. Previous code may depends on the long include chain.
You may need to include the following headers for some files after this commit:

- soc/soc.h
- soc/soc_memory_layout.h
- driver/gpio.h
- esp_sleep.h

The major broken include chain includes:

1. esp_system.h no longer includes esp_sleep.h. The latter includes driver/gpio.h and driver/touch_pad.h.
2. ets_sys.h no longer includes soc/soc.h
3. freertos/portmacro.h no longer includes soc/soc_memory_layout.h

some peripheral headers no longer includes their hw related headers, e.g. rom/gpio.h no longer includes soc/gpio_pins.h and soc/gpio_reg.h

BREAKING CHANGE
2019-04-16 13:21:15 +08:00
..
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 Version update from V1 to V2 now done in correct way. 2018-10-26 09:21:30 +03:00
test move esp32 chip specific includes to esp32/xxx.h 2019-03-18 17:14:05 +08:00
test_wl_host global: move the soc component out of the common list 2019-04-16 13:21:15 +08:00
.gitignore nvs_flash, wear_levelling: ignore host test files 2017-04-17 11:01:18 +08:00
CMakeLists.txt cmake: make main a component again 2018-09-11 09:44:12 +08:00
component.mk add wear_levelling component and example 2017-04-17 11:01:17 +08:00
crc32.cpp separate rom from esp32 component to esp_rom 2019-03-21 18:51:45 +08:00
crc32.h Replace all DOS line endings with Unix 2018-07-12 19:10:37 +08: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.rst Typos correction. 2017-07-31 13:19:41 +03: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 Version update from V1 to V2 now done in correct way. 2018-10-26 09:21:30 +03:00

Wear Levelling APIs
===================

Overview
--------
Most of the flash devices and specially SPI flash devices that are used in ESP32
have sector based organization and have limited amount of erase/modification cycles
per memory sector. To avoid situation when one sector reach the limit of erases when
other sectors was used not often, we have made a component that avoid this situation.
The wear levelling component share the amount of erases between all sectors in the
memory without user interaction.
The wear_levelling component contains APIs related to reading, writing, erasing,
memory mapping data in the external SPI flash through the partition component. It
also has higher-level APIs which work with FAT filesystem defined in
the :doc:`FAT filesystem </api-reference/storage/fatfs>`.

The wear levelling component, together with FAT FS component, works with FAT FS sector size 4096
bytes which is standard size of the flash devices. In this mode the component has best performance,
but needs additional memoty in the RAM. To save internal memory the component has two additional modes
to work with sector size 512 bytes: Performance and Safety modes. In Performance mode by erase sector
operation data will be stored to the RAM, sector will be erased and then data will be stored
back to the flash. If by this operation power off situation will occur, the complete 4096 bytes
will be lost. To prevent this the Safety mode was implemented. In safety mode the data will be first
stored to the flash and after sector will be erased, will be stored back. If power off situation will
occur, after power on, the data will be recovered.
By default defined the sector size 512 bytes and Performance mode. To change these values please use
the configuration menu.


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


Wear Levelling access APIs
--------------------------

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

- ``wl_mount`` mount wear levelling module for defined partition
- ``wl_unmount`` used to unmount levelling module
- ``wl_erase_range`` used to erase range of addresses in flash
- ``wl_write`` used to write data to the partition
- ``wl_read`` used to read data from the partition
- ``wl_size`` return size of avalible memory in bytes
- ``wl_sector_size`` returns size of one sector

Generally, try to avoid using the raw wear levelling functions in favor of
filesystem-specific functions.

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

The memory size calculated in the wear Levelling module based on parameters of
partition. The module use few sectors of flash for internal data.