README.rst
1Wear Levelling API
2==================
3
4:link_to_translation:`zh_CN:[中文]`
5
6Overview
7--------
8Most 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.
9
10The 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>`.
11
12The 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.
13
14To save internal memory, the component has two additional modes which both use sectors of 512 bytes:
15
16- **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.
17- **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.
18
19The default settings are as follows:
20- Sector size is 512 bytes
21- Performance mode
22
23You can change the settings through the configuration menu.
24
25
26The 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.
27
28
29Wear Levelling access API functions
30-----------------------------------
31
32This is the set of API functions for working with data in flash:
33
34- ``wl_mount`` - initializes the wear levelling module and mounts the specified partition
35- ``wl_unmount`` - unmounts the partition and deinitializes the wear levelling module
36- ``wl_erase_range`` - erases a range of addresses in flash
37- ``wl_write`` - writes data to a partition
38- ``wl_read`` - reads data from a partition
39- ``wl_size`` - returns the size of available memory in bytes
40- ``wl_sector_size`` - returns the size of one sector
41
42As a rule, try to avoid using raw wear levelling functions and use filesystem-specific functions instead.
43
44
45Memory Size
46-----------
47
48The memory size is calculated in the wear levelling module based on partition parameters. The module uses some sectors of flash for internal data.
49
50
README_CN.rst
1磨损均衡 API
2==================
3
4:link_to_translation:`en:[English]`
5
6概述
7--------
8
9ESP32 所使用的 flash，特别是 SPI flash 多数具备扇区结构，且每个扇区仅允许有限次数的擦除/修改操作。为了避免过度使用某一扇区，乐鑫提供了磨损均衡组件，无需用户介入即可帮助用户均衡各个扇区之间的磨损。
10
11磨损均衡组件包含了通过分区组件对外部 SPI flash 进行数据读取、写入、擦除和存储器映射相关的 API 函数。磨损均衡组件还具有软件上更高级别的 API 函数，与 :doc:`FAT 文件系统 </api-reference/storage/fatfs>` 协同工作。
12
13磨损均衡组件与 FAT 文件系统组件共用 FAT 文件系统的扇区，扇区大小为 4096 字节，是标准 flash 扇区的大小。在这种模式下，磨损均衡组件性能达到最佳，但需要在 RAM 中占用更多内存。
14
15为了节省内存，磨损均衡组件还提供了另外两种模式，均使用 512 字节大小的扇区：
16
17- **性能模式**：先将数据保存在 RAM 中，擦除扇区，然后将数据存储回 flash。如果设备在扇区擦写过程中突然断电，则整个扇区（4096 字节）数据将全部丢失。
18- **安全模式**：数据先保存在 flash 中空余扇区，擦除扇区后，数据即存储回去。如果设备断电，上电后可立即恢复数据。
19
20设备默认设置如下：
21
22- 定义扇区大小为 512 字节
23- 默认使用性能模式
24
25您可以使用配置菜单更改设置。
26
27磨损均衡组件不会将数据缓存在 RAM 中。写入和擦除函数直接修改 flash，函数返回后，flash 即完成修改。
28
29磨损均衡访问 API
30-----------------------------------
31
32处理 flash 数据常用的 API 如下所示：
33
34- ``wl_mount`` - 为指定分区挂载并初始化磨损均衡模块
35- ``wl_unmount`` - 卸载分区并释放磨损均衡模块
36- ``wl_erase_range`` - 擦除 flash 中指定的地址范围
37- ``wl_write`` - 将数据写入分区
38- ``wl_read`` - 从分区读取数据
39- ``wl_size`` - 返回可用内存的大小（以字节为单位）
40- ``wl_sector_size`` - 返回一个扇区的大小
41
42请尽量避免直接使用原始磨损均衡函数，建议您使用文件系统特定的函数。
43
44内存大小
45-----------
46
47内存大小是根据分区参数在磨损均衡模块中计算所得，由于模块使用 flash 部分扇区存储内部数据，因此计算所得内存大小有少许偏差。
48
