mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
Merge branch 'docs/fatfs_add_api_reference_v5.0' into 'release/v5.0'
docs(fatfs): Move mentioned APIs to a separate API reference section (v5.0) See merge request espressif/esp-idf!25350
This commit is contained in:
Jiang Jiang Jian
commit
d811f7c1f0
@ -1,5 +1,5 @@
|
||||
/*
|
||||
* SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
|
||||
* SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
|
||||
*
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
@ -281,7 +281,7 @@ esp_err_t esp_vfs_fat_spiflash_mount_ro(const char* base_path,
|
||||
* @brief Unmount FAT filesystem and release resources acquired using esp_vfs_fat_spiflash_mount_ro
|
||||
*
|
||||
* @param base_path path where partition should be registered (e.g. "/spiflash")
|
||||
* @param partition_label label of partition to be unmounted
|
||||
* @param partition_label label of partition to be unmounted
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK on success
|
||||
@ -289,26 +289,12 @@ esp_err_t esp_vfs_fat_spiflash_mount_ro(const char* base_path,
|
||||
*/
|
||||
esp_err_t esp_vfs_fat_spiflash_unmount_ro(const char* base_path, const char* partition_label);
|
||||
|
||||
esp_err_t esp_vfs_fat_spiflash_mount(const char* base_path,
|
||||
const char* partition_label,
|
||||
const esp_vfs_fat_mount_config_t* mount_config,
|
||||
wl_handle_t* wl_handle)
|
||||
__attribute__((deprecated("esp_vfs_fat_spiflash_mount is deprecated, please use esp_vfs_fat_spiflash_mount_rw_wl instead")));
|
||||
esp_err_t esp_vfs_fat_spiflash_unmount(const char* base_path, wl_handle_t wl_handle)
|
||||
__attribute__((deprecated("esp_vfs_fat_spiflash_unmount is deprecated, please use esp_vfs_fat_spiflash_unmount_rw_wl instead")));
|
||||
esp_err_t esp_vfs_fat_rawflash_mount(const char* base_path,
|
||||
const char* partition_label,
|
||||
const esp_vfs_fat_mount_config_t* mount_config)
|
||||
__attribute__((deprecated("esp_vfs_fat_rawflash_mount is deprecated, please use esp_vfs_fat_spiflash_mount_ro instead")));
|
||||
esp_err_t esp_vfs_fat_rawflash_unmount(const char* base_path, const char* partition_label)
|
||||
__attribute__((deprecated("esp_vfs_fat_rawflash_unmount is deprecated, please use esp_vfs_fat_spiflash_unmount_ro instead")));
|
||||
|
||||
/**
|
||||
* @brief Get information for FATFS partition
|
||||
* @brief Get information for FATFS partition
|
||||
*
|
||||
* @param base_path Path where partition should be registered (e.g. "/spiflash")
|
||||
* @param base_path Base path of the partition examined (e.g. "/spiflash")
|
||||
* @param[out] out_total_bytes Size of the file system
|
||||
* @param[out] out_free_bytes Current used bytes in the file system
|
||||
* @param[out] out_free_bytes Free bytes available in the file system
|
||||
* @return
|
||||
* - ESP_OK on success
|
||||
* - ESP_ERR_INVALID_STATE if partition not found
|
||||
@ -316,6 +302,37 @@ esp_err_t esp_vfs_fat_rawflash_unmount(const char* base_path, const char* partit
|
||||
*/
|
||||
esp_err_t esp_vfs_fat_info(const char* base_path, uint64_t* out_total_bytes, uint64_t* out_free_bytes);
|
||||
|
||||
/** @cond */
|
||||
/**
|
||||
* @deprecated Please use `esp_vfs_fat_spiflash_mount_rw_wl` instead
|
||||
*/
|
||||
esp_err_t esp_vfs_fat_spiflash_mount(const char* base_path,
|
||||
const char* partition_label,
|
||||
const esp_vfs_fat_mount_config_t* mount_config,
|
||||
wl_handle_t* wl_handle)
|
||||
__attribute__((deprecated("esp_vfs_fat_spiflash_mount is deprecated, please use esp_vfs_fat_spiflash_mount_rw_wl instead")));
|
||||
|
||||
/**
|
||||
* @deprecated Please use `esp_vfs_fat_spiflash_unmount_rw_wl` instead
|
||||
*/
|
||||
esp_err_t esp_vfs_fat_spiflash_unmount(const char* base_path, wl_handle_t wl_handle)
|
||||
__attribute__((deprecated("esp_vfs_fat_spiflash_unmount is deprecated, please use esp_vfs_fat_spiflash_unmount_rw_wl instead")));
|
||||
|
||||
/**
|
||||
* @deprecated Please use `esp_vfs_fat_spiflash_mount_ro` instead
|
||||
*/
|
||||
esp_err_t esp_vfs_fat_rawflash_mount(const char* base_path,
|
||||
const char* partition_label,
|
||||
const esp_vfs_fat_mount_config_t* mount_config)
|
||||
__attribute__((deprecated("esp_vfs_fat_rawflash_mount is deprecated, please use esp_vfs_fat_spiflash_mount_ro instead")));
|
||||
|
||||
/**
|
||||
* @deprecated Please use `esp_vfs_fat_spiflash_unmount_ro` instead
|
||||
*/
|
||||
esp_err_t esp_vfs_fat_rawflash_unmount(const char* base_path, const char* partition_label)
|
||||
__attribute__((deprecated("esp_vfs_fat_rawflash_unmount is deprecated, please use esp_vfs_fat_spiflash_unmount_ro instead")));
|
||||
/** @endcond */
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
@ -42,10 +42,7 @@ Most applications use the following workflow when working with ``esp_vfs_fat_``
|
||||
|
||||
10. Call :cpp:func:`esp_vfs_fat_unregister_path` with the path where the file system is mounted to remove FatFs from VFS, and free the ``FATFS`` structure allocated in Step 1.
|
||||
|
||||
The convenience functions ``esp_vfs_fat_sdmmc_mount``, ``esp_vfs_fat_sdspi_mount``, and ``esp_vfs_fat_sdcard_unmount`` wrap the steps described above and also handle SD card initialization. These functions are described in the next section.
|
||||
|
||||
.. doxygenfunction:: esp_vfs_fat_register
|
||||
.. doxygenfunction:: esp_vfs_fat_unregister_path
|
||||
The convenience functions :cpp:func:`esp_vfs_fat_sdmmc_mount`, :cpp:func:`esp_vfs_fat_sdspi_mount`, and :cpp:func:`esp_vfs_fat_sdcard_unmount` wrap the steps described above and also handle SD card initialization. These functions are described in the next section.
|
||||
|
||||
|
||||
Using FatFs with VFS and SD Cards
|
||||
@ -55,22 +52,12 @@ The header file :component_file:`fatfs/vfs/esp_vfs_fat.h` defines convenience fu
|
||||
|
||||
The convenience function :cpp:func:`esp_vfs_fat_sdmmc_unmount` unmounts the filesystem and releases the resources acquired by :cpp:func:`esp_vfs_fat_sdmmc_mount`.
|
||||
|
||||
.. doxygenfunction:: esp_vfs_fat_sdmmc_mount
|
||||
.. doxygenfunction:: esp_vfs_fat_sdmmc_unmount
|
||||
.. doxygenfunction:: esp_vfs_fat_sdspi_mount
|
||||
.. doxygenstruct:: esp_vfs_fat_mount_config_t
|
||||
:members:
|
||||
.. doxygenfunction:: esp_vfs_fat_sdcard_unmount
|
||||
|
||||
|
||||
Using FatFs with VFS in Read-Only Mode
|
||||
--------------------------------------
|
||||
|
||||
The header file :component_file:`fatfs/vfs/esp_vfs_fat.h` also defines the convenience functions :cpp:func:`esp_vfs_fat_spiflash_mount_ro` and :cpp:func:`esp_vfs_fat_spiflash_unmount_ro`. These functions perform Steps 1-3 and 7-9 respectively for read-only FAT partitions. These are particularly helpful for data partitions written only once during factory provisioning which will not be changed by production application throughout the lifetime of the hardware.
|
||||
|
||||
.. doxygenfunction:: esp_vfs_fat_spiflash_mount_ro
|
||||
.. doxygenfunction:: esp_vfs_fat_spiflash_unmount_ro
|
||||
|
||||
|
||||
FatFS Disk IO Layer
|
||||
-------------------
|
||||
@ -145,3 +132,9 @@ It is a reverse tool of (:component_file:`fatfsgen.py<fatfs/fatfsgen.py>`), i.e.
|
||||
Usage::
|
||||
|
||||
./fatfsparse.py [-h] [--long-name-support] [--wear-leveling] fatfs_image.img
|
||||
|
||||
|
||||
High-level API Reference
|
||||
------------------------
|
||||
|
||||
.. include-build-file:: inc/esp_vfs_fat.inc
|
||||
|
||||
@ -3,15 +3,15 @@
|
||||
See also
|
||||
--------
|
||||
|
||||
- :doc:`FAT Filesystem <./fatfs>`
|
||||
- :doc:`Partition Table documentation <../../api-guides/partition-tables>`
|
||||
- :doc:`./fatfs`
|
||||
- :doc:`../../api-guides/partition-tables`
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
An example which combines the wear levelling driver with the FATFS library is provided in the :example:`storage/wear_levelling` directory. This example initializes the wear levelling driver, mounts FATFS partition, as well as writes and reads data from it using POSIX and C library APIs. See the :example_file:`storage/wear_levelling/README.md` file for more information.
|
||||
An example that combines the wear levelling driver with the FATFS library is provided in the :example:`storage/wear_levelling` directory. This example initializes the wear levelling driver, mounts FatFs partition, as well as writes and reads data from it using POSIX and C library APIs. See :example_file:`storage/wear_levelling/README.md` for more information.
|
||||
|
||||
High level API Reference
|
||||
High-level API Reference
|
||||
------------------------
|
||||
|
||||
Header Files
|
||||
@ -19,16 +19,9 @@ Header Files
|
||||
|
||||
* :component_file:`fatfs/vfs/esp_vfs_fat.h`
|
||||
|
||||
Functions
|
||||
^^^^^^^^^
|
||||
High-level wear levelling functions :cpp:func:`esp_vfs_fat_spiflash_mount_rw_wl`, :cpp:func:`esp_vfs_fat_spiflash_unmount_rw_wl` and struct :cpp:class:`esp_vfs_fat_mount_config_t` are described in :doc:`./fatfs`.
|
||||
|
||||
.. doxygenfunction:: esp_vfs_fat_spiflash_mount_rw_wl
|
||||
.. doxygenstruct:: esp_vfs_fat_mount_config_t
|
||||
:members:
|
||||
.. doxygenfunction:: esp_vfs_fat_spiflash_unmount_rw_wl
|
||||
|
||||
Mid level API Reference
|
||||
Mid-level API Reference
|
||||
-----------------------
|
||||
|
||||
.. include-build-file:: inc/wear_levelling.inc
|
||||
|
||||
|
||||
@ -30,13 +30,3 @@ mqtt_client.inc:line: WARNING: Duplicate C++ declaration, also defined at api-re
|
||||
Declaration is '.. cpp:enum:: esp_mqtt_protocol_ver_t'.
|
||||
esp_flash.inc:line: WARNING: Duplicate C++ declaration, also defined at api-reference/storage/spi_flash:line.
|
||||
Declaration is '.. cpp:type:: struct esp_flash_t esp_flash_t'.
|
||||
wear-levelling.rst:line: WARNING: Duplicate C++ declaration, also defined at api-reference/storage/fatfs:line.
|
||||
Declaration is '.. cpp:struct:: esp_vfs_fat_mount_config_t'.
|
||||
wear-levelling.rst:line: WARNING: Duplicate C++ declaration, also defined at api-reference/storage/fatfs:line.
|
||||
Declaration is '.. cpp:member:: bool format_if_mount_failed'.
|
||||
wear-levelling.rst:line: WARNING: Duplicate C++ declaration, also defined at api-reference/storage/fatfs:line.
|
||||
Declaration is '.. cpp:member:: int max_files'.
|
||||
wear-levelling.rst:line: WARNING: Duplicate C++ declaration, also defined at api-reference/storage/fatfs:line.
|
||||
Declaration is '.. cpp:member:: size_t allocation_unit_size'.
|
||||
wear-levelling.rst:line: WARNING: Duplicate C++ declaration, also defined at api-reference/storage/fatfs:line.
|
||||
Declaration is '.. cpp:member:: bool disk_status_check_enable'.
|
||||
|
||||
@ -42,10 +42,7 @@ FatFs 与 VFS 配合使用
|
||||
|
||||
10. 调用 :cpp:func:`esp_vfs_fat_unregister_path` 并使用文件系统挂载的路径将 FatFs 从 VFS 中移除，并释放步骤 1 中分配的 ``FATFS`` 结构。
|
||||
|
||||
便捷函数 ``esp_vfs_fat_sdmmc_mount``、 ``esp_vfs_fat_sdspi_mount`` 和 ``esp_vfs_fat_sdmmc_unmount`` 对上述步骤进行了封装，并加入了对 SD 卡初始化的处理。我们将在下一章节详细介绍以上函数。
|
||||
|
||||
.. doxygenfunction:: esp_vfs_fat_register
|
||||
.. doxygenfunction:: esp_vfs_fat_unregister_path
|
||||
便捷函数 :cpp:func:`esp_vfs_fat_sdmmc_mount`、:cpp:func:`esp_vfs_fat_sdspi_mount` 和 :cpp:func:`esp_vfs_fat_sdcard_unmount` 对上述步骤进行了封装，并加入了对 SD 卡初始化的处理。我们将在下一章节详细介绍以上函数。
|
||||
|
||||
|
||||
FatFs 与 VFS 和 SD 卡配合使用
|
||||
@ -55,22 +52,12 @@ FatFs 与 VFS 和 SD 卡配合使用
|
||||
|
||||
便捷函数 :cpp:func:`esp_vfs_fat_sdmmc_unmount` 用于卸载文件系统并释放从 :cpp:func:`esp_vfs_fat_sdmmc_mount` 函数获取的资源。
|
||||
|
||||
.. doxygenfunction:: esp_vfs_fat_sdmmc_mount
|
||||
.. doxygenfunction:: esp_vfs_fat_sdmmc_unmount
|
||||
.. doxygenfunction:: esp_vfs_fat_sdspi_mount
|
||||
.. doxygenstruct:: esp_vfs_fat_mount_config_t
|
||||
:members:
|
||||
.. doxygenfunction:: esp_vfs_fat_sdcard_unmount
|
||||
|
||||
|
||||
FatFs 与 VFS 配合使用（只读模式下）
|
||||
--------------------------------------
|
||||
|
||||
头文件 :component_file:`fatfs/vfs/esp_vfs_fat.h` 也定义了两个便捷函数 :cpp:func:`esp_vfs_fat_spiflash_mount_ro` 和 :cpp:func:`esp_vfs_fat_spiflash_unmount_ro`。上述两个函数分别对 FAT 只读分区执行步骤 1-3 和步骤 7-9。有些数据分区仅在工厂配置时写入一次，之后在整个硬件生命周期内都不会再有任何改动。利用上述两个函数处理这种数据分区非常方便。
|
||||
|
||||
.. doxygenfunction:: esp_vfs_fat_spiflash_mount_ro
|
||||
.. doxygenfunction:: esp_vfs_fat_spiflash_unmount_ro
|
||||
|
||||
|
||||
FatFs 磁盘 I/O 层
|
||||
-------------------
|
||||
@ -142,3 +129,9 @@ FatFs 分区分析器
|
||||
您可以使用::
|
||||
|
||||
./fatfsparse.py [-h] [--long-name-support] [--wear-leveling] fatfs_image.img
|
||||
|
||||
|
||||
高级 API 参考
|
||||
------------------------
|
||||
|
||||
.. include-build-file:: inc/esp_vfs_fat.inc
|
||||
|
||||
@ -3,10 +3,10 @@
|
||||
另请参阅
|
||||
-----------
|
||||
|
||||
- :doc:`FAT 文件系统 <./fatfs>`
|
||||
- :doc:`分区表 <../../api-guides/partition-tables>`
|
||||
- :doc:`./fatfs`
|
||||
- :doc:`../../api-guides/partition-tables`
|
||||
|
||||
应用示例
|
||||
应用示例
|
||||
-------------------
|
||||
|
||||
:example:`storage/wear_levelling` 中提供了一款磨损均衡驱动与 FatFs 库结合使用的示例。该示例初始化磨损均衡驱动，挂载 FAT 文件系统分区，并使用 POSIX（可移植操作系统接口）和 C 库 API 从中写入和读取数据。如需了解更多信息，请参考 :example_file:`storage/wear_levelling/README.md`。
|
||||
@ -19,16 +19,9 @@
|
||||
|
||||
* :component_file:`fatfs/vfs/esp_vfs_fat.h`
|
||||
|
||||
函数
|
||||
^^^^^^^^^
|
||||
|
||||
.. doxygenfunction:: esp_vfs_fat_spiflash_mount_rw_wl
|
||||
.. doxygenstruct:: esp_vfs_fat_mount_config_t
|
||||
:members:
|
||||
.. doxygenfunction:: esp_vfs_fat_spiflash_unmount_rw_wl
|
||||
有关高级磨损均衡函数 :cpp:func:`esp_vfs_fat_spiflash_mount_rw_wl`、 :cpp:func:`esp_vfs_fat_spiflash_unmount_rw_wl` 和结构体 :cpp:class:`esp_vfs_fat_mount_config_t` 的详细内容，请参见 :doc:`./fatfs`。
|
||||
|
||||
中层 API 参考
|
||||
-----------------------
|
||||
|
||||
.. include-build-file:: inc/wear_levelling.inc
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user