Merge branch 'docs/udpate_memory-types' into 'master'

Docs/udpate memory types

Closes DOC-5388 and DOC-5157

See merge request espressif/esp-idf!24392

components/spi_flash/include/esp_spi_flash_counters.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
  */
@@ -11,7 +11,7 @@
 #include "esp_err.h"
 #include "sdkconfig.h"
 
-#if CONFIG_SPI_FLASH_ENABLE_COUNTERS
+#if CONFIG_SPI_FLASH_ENABLE_COUNTERS || defined __DOXYGEN__
 
 #ifdef __cplusplus
 extern "C" {
@@ -21,15 +21,18 @@ extern "C" {
  * Structure holding statistics for one type of operation
  */
 typedef struct {
-    uint32_t count;     // number of times operation was executed
+    uint32_t count;     /*!< number of times operation was executed */
-    uint32_t time;      // total time taken, in microseconds
+    uint32_t time;      /*!< total time taken, in microseconds */
-    uint32_t bytes;     // total number of bytes
+    uint32_t bytes;     /*!< total number of bytes */
 } esp_flash_counter_t;
 
+/**
+ * Structure for counters of flash actions
+*/
 typedef struct {
-    esp_flash_counter_t read;
+    esp_flash_counter_t read;   /*!< counters for read action, like `esp_flash_read`*/
-    esp_flash_counter_t write;
+    esp_flash_counter_t write;  /*!< counters for write action, like `esp_flash_write`*/
-    esp_flash_counter_t erase;
+    esp_flash_counter_t erase;  /*!< counters for erase action, like `esp_flash_erase`*/
 } esp_flash_counters_t;
 
 // for deprecate old api
@@ -61,4 +64,4 @@ const spi_flash_counters_t* spi_flash_get_counters(void) __attribute__((deprecat
 }
 #endif
 
-#endif //CONFIG_SPI_FLASH_ENABLE_COUNTERS
+#endif //CONFIG_SPI_FLASH_ENABLE_COUNTERS || defined __DOXYGEN__

docs/doxygen/Doxyfile

@@ -263,6 +263,7 @@ INPUT = \
     $(PROJECT_PATH)/components/spi_flash/include/esp_flash_spi_init.h \
     $(PROJECT_PATH)/components/spi_flash/include/esp_flash.h \
     $(PROJECT_PATH)/components/spi_flash/include/spi_flash_mmap.h \
+    $(PROJECT_PATH)/components/spi_flash/include/esp_spi_flash_counters.h \
     $(PROJECT_PATH)/components/spiffs/include/esp_spiffs.h \
     $(PROJECT_PATH)/components/touch_element/include/touch_element/touch_button.h \
     $(PROJECT_PATH)/components/touch_element/include/touch_element/touch_element.h \

docs/en/api-guides/memory-types.rst

@@ -120,7 +120,7 @@ Jump table optimizations can be re-enabled for individual source files that don'
 
 .. _irom:
 
-IROM (code executed from flash)
+IROM (Code Executed from flash)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 If a function is not explicitly placed into :ref:`iram` or RTC memory, it is placed into flash. As IRAM is limited, most of an application's binary code must be placed into IROM instead.

docs/en/api-reference/peripherals/spi_flash/index.rst

@@ -272,6 +272,7 @@ API Reference - SPI Flash
 .. include-build-file:: inc/spi_flash_mmap.inc
 .. include-build-file:: inc/spi_flash_types.inc
 .. include-build-file:: inc/esp_flash_err.inc
+.. include-build-file:: inc/esp_spi_flash_counters.inc
 
 API Reference - Flash Encrypt
 -----------------------------

docs/en/migration-guides/release-5.x/5.1/storage.rst

@@ -6,8 +6,7 @@ Storage
 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.
+``esp_vfs_fat_sdmmc_unmount()`` is now deprecated, and you can use :cpp:func:`esp_vfs_fat_sdcard_unmount()` instead. This API is deprecated in previous ESP-IDF versions, but without a deprecation warning or migration guide. Since ESP-IDF v5.1, calling this ``esp_vfs_fat_sdmmc_unmount()`` API will generate a deprecation warning.
-
 
 SPI_FLASH
 ---------

docs/en/migration-guides/release-5.x/5.1/system.rst

@@ -11,19 +11,21 @@ FreeRTOS
     Dynamic Memory Allocation
     ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-    Previously, most FreeRTOS dynamic allocation would eventually call to ``malloc()``. Thus, if an application was configured to allow ``malloc()`` to allocate from external RAM (i.e., :ref:`CONFIG_SPIRAM_USE` was set ``CONFIG_SPIRAM_USE_MALLOC``), then there was a possibility that FreeRTOS could allocate dynamic memory from external RAM, with the exact placement being decided by the heap allocator.
+     In the past, FreeRTOS commonly utilized the function ``malloc()`` to allocate dynamic memory. As a result, if an application allowed ``malloc()`` to allocate memory from external RAM (by configuring the :ref:`CONFIG_SPIRAM_USE` option as ``CONFIG_SPIRAM_USE_MALLOC``), FreeRTOS had the potential to allocate dynamic memory from external RAM, and the specific location was determined by the heap allocator.
 
     .. note::
+
         Dynamic memory allocation for tasks (which are likely to consume the most memory) were an exception to the scenario above. FreeRTOS would use a separate memory allocation function to guarantee that dynamic memory allocate for a task was always placed in internal RAM.
 
-    Allowing FreeRTOS objects (such as queues and semaphores) to be placed in external RAM becomes an issue if those objects are accessed while the cache is disabled (such as during SPI Flash write operations) and would lead to a cache access errors (see :doc:`Fatal Errors </api-guides/fatal-errors>` for more details).
+    Allowing FreeRTOS objects (such as queues and semaphores) to be placed in external RAM becomes an issue if those objects are accessed while the cache is disabled (such as during SPI flash write operations) and would lead to a cache access errors (see :doc:`Fatal Errors </api-guides/fatal-errors>` for more details).
 
-    Therefore, FreeRTOS has been updated to always use internal memory (i.e., DRAM) for dynamic memory allocation. Calling FreeRTOS creation functions (e.g., :cpp:func:`xTaskCreate`, :cpp:func:`xQueueCreate`) will guarantee that the memory allocated for those tasks/objects is from internal memory (see :ref:`freertos-heap` for more details).
+    Therefore, FreeRTOS has been updated to always use internal memory (i.e., DRAM) for dynamic memory allocation. Calling FreeRTOS creation functions (e.g., :cpp:func:`xTaskCreate`, :cpp:func:`xQueueCreate` ) will guarantee that the memory allocated for those tasks/objects is from internal memory (see :ref:`freertos-heap` for more details).
 
     .. warning::
-        For users that previously relied on :ref:`CONFIG_SPIRAM_USE` to place FreeRTOS objects into external memory, this change will lead to increased usage of internal memory due the FreeRTOS objects now being allocated there.
 
-    Users that want to place a FreeRTOS task/object into external memory will now need to do so explicitly. Users can use one of the following methods:
+        If you previously relied on :ref:`CONFIG_SPIRAM_USE` to place FreeRTOS objects into external memory, this change will lead to increased usage of internal memory due the FreeRTOS objects now being allocated there.
+
+    To place a FreeRTOS task/object into external memory, it is now necessary to do so explicitly. The following methods can be employed:
 
     - Allocate the task/object using one of the ``...CreateWithCaps()`` API such as :cpp:func:`xTaskCreateWithCaps` and :cpp:func:`xQueueCreateWithCaps` (see :ref:`freertos-idf-additional-api` for more details).
     - Manually allocate external memory for those objects using :cpp:func:`heap_caps_malloc`, then create the objects from the allocated memory using one of the ``...CreateStatic()`` FreeRTOS functions.

docs/zh_CN/api-guides/memory-types.rst

@@ -143,7 +143,7 @@ DROM（数据存储在 flash 中）
 
 唯一没有默认放入 DROM 的常量数据是被编译器嵌入到应用程序代码中的字面常量。这些被放置在周围函数的可执行指令中。
 
-``DRAM_ATTR`` 属性可以用来强制将常量从 DRAM 放入 :ref:`dram` 部分（见上文）。
+``DRAM_ATTR`` 属性可以用来强制将常量从 DROM 放入 :ref:`dram` 部分（见上文）。
 
 .. only:: SOC_RTC_SLOW_MEM_SUPPORTED
 

docs/zh_CN/api-reference/peripherals/spi_flash/index.rst

@@ -272,6 +272,7 @@ SPI Flash API 参考
 .. include-build-file:: inc/spi_flash_mmap.inc
 .. include-build-file:: inc/spi_flash_types.inc
 .. include-build-file:: inc/esp_flash_err.inc
+.. include-build-file:: inc/esp_spi_flash_counters.inc
 
 Flash 加密 API 参考
 -----------------------------

docs/zh_CN/migration-guides/release-5.x/5.1/storage.rst

@@ -6,4 +6,11 @@
 FatFs
 -----
 
-``esp_vfs_fat_sdmmc_unmount()`` 已被弃用。 您可以使用 :cpp:func:`esp_vfs_fat_sdcard_unmount()` 代替。 此接口在更早的 IDF 版本中已被弃用， 但是尚未添加弃用警告。 自 IDF v5.1 起， 调用这个 ``esp_vfs_fat_sdmmc_unmount()`` 接口将会产生 deprecation 警告。
+``esp_vfs_fat_sdmmc_unmount()`` 已被弃用，可以使用 :cpp:func:`esp_vfs_fat_sdcard_unmount()` 代替。此接口在更早的 ESP-IDF 版本中已被弃用，但是尚未添加弃用警告。自 ESP-IDF v5.1 起，调用这个 ``esp_vfs_fat_sdmmc_unmount()`` 接口将会产生弃用警告。
+
+SPI_FLASH
+---------
+
+- :cpp:func:`spi_flash_get_counters` 已被弃用，请使用 :cpp:func:`esp_flash_get_counters` 代替。
+- :cpp:func:`spi_flash_dump_counters` 已被弃用，请使用 :cpp:func:`esp_flash_dump_counters` 代替。
+- :cpp:func:`spi_flash_reset_counters` 已被弃用，请使用 :cpp:func:`esp_flash_reset_counters` 代替。

docs/zh_CN/migration-guides/release-5.x/5.1/system.rst

@@ -3,6 +3,33 @@
 
 :link_to_translation:`en:[英文]`
 
+FreeRTOS
+--------
+
+.. only:: SOC_SPIRAM_SUPPORTED
+
+    动态内存分配
+    ^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    过去，FreeRTOS 通常使用 ``malloc()`` 函数来分配动态内存。因此，如果应用程序允许 ``malloc()`` 从外部 RAM 分配内存（通过将 :ref:`CONFIG_SPIRAM_USE` 选项配置为 ``CONFIG_SPIRAM_USE_MALLOC``），FreeRTOS 就有可能从外部 RAM 分配动态内存，并且具体位置由堆分配器确定。
+
+    .. note::
+
+        任务的动态内存分配（通常占用大部分内存）与上述介绍的情况不同，是种例外情况。FreeRTOS 会使用单独的内存分配函数，确保为任务分配的动态内存始终位于内部 RAM 中。
+
+    允许将 FreeRTOS 对象（如队列和信号量）放置在外部 RAM 中可能会出现问题，例如如果在访问这些对象时 cache 被禁用（如在 SPI flash 写入操作期间），则会导致 cache 访问错误（详细信息请参阅 :doc:`严重错误</api-guides/fatal-errors>`）。
+
+    因此，FreeRTOS 已经更新为始终使用内部内存（即 DRAM）进行动态内存分配。调用 FreeRTOS 创建函数（例如 :cpp:func:`xTaskCreate` 或 :cpp:func:`xQueueCreate` ）将保证为这些任务/对象分配的内存来自内部内存（详细信息请参阅 :ref:`freertos-heap`）。
+
+    .. warning::
+
+        如果你之前使用 :ref:`CONFIG_SPIRAM_USE` 将 FreeRTOS 对象放置在外部内存中，这个更改则会导致内部内存的使用增加，因为现在 FreeRTOS 对象将被分配到内部内存中。
+
+    现在将 FreeRTOS 任务/对象放置在外部内存中，需要显示地设置，可采用以下方法之一：
+
+    - 使用 ``...CreateWithCaps()`` API 函数如 :cpp:func:`xTaskCreateWithCaps` 或  :cpp:func:`xQueueCreateWithCaps` 分配任务/对象到外部内存（详情请参阅 :ref:`freertos-idf-additional-api`）。
+    - 使用 :cpp:func:`heap_caps_malloc` 为 FreeRTOS 对象手动分配外部内存，然后使用 ``...CreateStatic()`` FreeRTOS 函数从分配的内存中创建对象。
+
 电源管理
 ----------