diff --git a/components/fatfs/vfs/esp_vfs_fat.h b/components/fatfs/vfs/esp_vfs_fat.h index 20ec8e3df8..e39313c7f4 100644 --- a/components/fatfs/vfs/esp_vfs_fat.h +++ b/components/fatfs/vfs/esp_vfs_fat.h @@ -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 diff --git a/docs/en/api-reference/storage/fatfs.rst b/docs/en/api-reference/storage/fatfs.rst index c661bc8059..4b50acca16 100644 --- a/docs/en/api-reference/storage/fatfs.rst +++ b/docs/en/api-reference/storage/fatfs.rst @@ -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`), 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 diff --git a/docs/en/api-reference/storage/wear-levelling.rst b/docs/en/api-reference/storage/wear-levelling.rst index 3878ed26ef..41ca3fb1f8 100644 --- a/docs/en/api-reference/storage/wear-levelling.rst +++ b/docs/en/api-reference/storage/wear-levelling.rst @@ -19,13 +19,7 @@ Header Files * :component_file:`fatfs/vfs/esp_vfs_fat.h` -Functions -^^^^^^^^^ - -.. doxygenfunction:: esp_vfs_fat_spiflash_mount_rw_wl -.. doxygenstruct:: esp_vfs_fat_mount_config_t - :members: -.. doxygenfunction:: esp_vfs_fat_spiflash_unmount_rw_wl +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:`FAT Filesystem ` documentation page. Mid level API Reference ----------------------- diff --git a/docs/sphinx-known-warnings.txt b/docs/sphinx-known-warnings.txt index e2cc29704e..48fadf1d0c 100644 --- a/docs/sphinx-known-warnings.txt +++ b/docs/sphinx-known-warnings.txt @@ -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'. diff --git a/docs/zh_CN/api-reference/storage/fatfs.rst b/docs/zh_CN/api-reference/storage/fatfs.rst index 3b46f58736..90e2263538 100644 --- a/docs/zh_CN/api-reference/storage/fatfs.rst +++ b/docs/zh_CN/api-reference/storage/fatfs.rst @@ -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