fatfs: deprecate esp_vfs_fat_sdmmc_unmount

This API was deprecated before, but without deprecation warning and migration doc. This commit added deprecation warning and migration doc to it.
espressif · Feb 16, 2023 · d59fd3e · d59fd3e
1 parent 90a6018
commit d59fd3e
Show file tree

Hide file tree

Showing 6 changed files with 25 additions and 1 deletion.
diff --git a/components/fatfs/vfs/esp_vfs_fat.h b/components/fatfs/vfs/esp_vfs_fat.h
@@ -194,7 +194,7 @@ esp_err_t esp_vfs_fat_sdspi_mount(const char* base_path,
  *      - ESP_OK on success
  *      - ESP_ERR_INVALID_STATE if esp_vfs_fat_sdmmc_mount hasn't been called
  */
-esp_err_t esp_vfs_fat_sdmmc_unmount(void);
+esp_err_t esp_vfs_fat_sdmmc_unmount(void) __attribute__((deprecated("Please use esp_vfs_fat_sdcard_unmount instead")));
 
 /**
  * @brief Unmount an SD card from the FAT filesystem and release resources acquired using

diff --git a/docs/en/migration-guides/release-5.x/5.1/index.rst b/docs/en/migration-guides/release-5.x/5.1/index.rst
@@ -7,4 +7,5 @@ Migration from 5.0 to 5.1
     :maxdepth: 1
 
     peripherals
+    storage
     networking
diff --git a/docs/en/migration-guides/release-5.x/5.1/storage.rst b/docs/en/migration-guides/release-5.x/5.1/storage.rst
@@ -0,0 +1,9 @@
+Storage
+=======
+
+:link_to_translation:`zh_CN:[中文]`
+
+FatFs
+-----
+
+``esp_vfs_fat_sdmmc_unmount()`` is now deprecated, you can use :cpp:func:`esp_vfs_fat_sdcard_unmount()` instead. This API is deprecated in previous IDF versions, but without deprecation warning and migration guide. Since IDF v5.1, calling this ``esp_vfs_fat_sdmmc_unmount()`` API will generate deprecation warning.
diff --git a/docs/zh_CN/migration-guides/release-5.x/5.1/index.rst b/docs/zh_CN/migration-guides/release-5.x/5.1/index.rst
@@ -7,4 +7,5 @@
     :maxdepth: 1
 
     peripherals
+    storage
     networking
diff --git a/docs/zh_CN/migration-guides/release-5.x/5.1/storage.rst b/docs/zh_CN/migration-guides/release-5.x/5.1/storage.rst
@@ -0,0 +1,9 @@
+存储
+=======
+
+:link_to_translation:`en:[English]`
+
+FatFs
+-----
+
+``esp_vfs_fat_sdmmc_unmount()`` 已被弃用。 您可以使用 :cpp:func:`esp_vfs_fat_sdcard_unmount()` 代替。 此接口在更早的 IDF 版本中已被弃用， 但是尚未添加弃用警告。 自 IDF v5.1 起， 调用这个 ``esp_vfs_fat_sdmmc_unmount()`` 接口将会产生 deprecation 警告。
diff --git a/tools/idf_py_actions/hints.yml b/tools/idf_py_actions/hints.yml
@@ -279,6 +279,10 @@
     hint: "All the Partition APIs have been moved to the new component 'esp_partition' - please, update your project dependencies. See Storage migration guide 5.x for more details."
     match_to_output: True
 
+-
+    re: "warning: 'esp_vfs_fat_sdmmc_unmount' is deprecated: Please use esp_vfs_fat_sdcard_unmount instead [-Wdeprecated-declarations]"
+    hint: "``esp_vfs_fat_sdmmc_unmount()`` is now deprecated, you can use :cpp:func:`esp_vfs_fat_sdcard_unmount()` instead. See Storage migration guide 5.1 for more details"
+
 -
     re: "esp_usb_jtag: could not find or open device!"
     hint: "Please check the wire connection to debugging device or access rights to a serial port."