From d59fd3e52967c745b361009af56fbebf3c480b08 Mon Sep 17 00:00:00 2001
From: Armando <douyiwen@espressif.com>
Date: Wed, 4 Jan 2023 19:35:20 +0800
Subject: [PATCH] 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.
---
 components/fatfs/vfs/esp_vfs_fat.h                      | 2 +-
 docs/en/migration-guides/release-5.x/5.1/index.rst      | 1 +
 docs/en/migration-guides/release-5.x/5.1/storage.rst    | 9 +++++++++
 docs/zh_CN/migration-guides/release-5.x/5.1/index.rst   | 1 +
 docs/zh_CN/migration-guides/release-5.x/5.1/storage.rst | 9 +++++++++
 tools/idf_py_actions/hints.yml                          | 4 ++++
 6 files changed, 25 insertions(+), 1 deletion(-)
 create mode 100644 docs/en/migration-guides/release-5.x/5.1/storage.rst
 create mode 100644 docs/zh_CN/migration-guides/release-5.x/5.1/storage.rst

diff --git a/components/fatfs/vfs/esp_vfs_fat.h b/components/fatfs/vfs/esp_vfs_fat.h
index 856b617515..c84a205513 100644
--- 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
index 21ae774552..98840beaef 100644
--- 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
new file mode 100644
index 0000000000..40f24f34ac
--- /dev/null
+++ 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
index 3c2f45c8dc..ea870e49a8 100644
--- 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
new file mode 100644
index 0000000000..23bc0e9802
--- /dev/null
+++ 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
index dabe8da0ff..564553c57e 100644
--- 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."