Skip to content

Commit f6cc4f6

Browse files
author
Zhang Shuxian
committed
docs: Update translation for SPI flash and RAM Usage
1 parent 87024c3 commit f6cc4f6

File tree

3 files changed

+176
-25
lines changed

3 files changed

+176
-25
lines changed

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

+76-23
Original file line numberDiff line numberDiff line change
@@ -145,7 +145,7 @@ Refer to the :doc:`Flash Encryption documentation </security/flash-encryption>`
145145
Memory Mapping API
146146
------------------
147147

148-
{IDF_TARGET_CACHE_SIZE:default="64 KB", esp32c2=16 ~ 64 KB}
148+
{IDF_TARGET_CACHE_SIZE:default="64 KB", esp32c2=16~64 KB}
149149

150150
{IDF_TARGET_NAME} features memory hardware which allows regions of flash memory to be mapped into instruction and data address spaces. This mapping works only for read operations. It is not possible to modify contents of flash memory by writing to a mapped memory region.
151151

@@ -265,7 +265,7 @@ In a single core environment (:ref:`CONFIG_FREERTOS_UNICORE` enabled), you need
265265
Internal Memory Saving For Flash Driver
266266
---------------------------------------
267267

268-
The ESP-IDF provides options to optimize the usage of IRAM by selectively placing certain functions into flash memory via turning off :ref:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM`. It allows SPI flash operation functions to be executed from flash memory instead of IRAM. Thus it will save some IRAM memory for other significant time-critical functions or tasks.
268+
The ESP-IDF provides options to optimize the usage of IRAM by selectively placing certain functions into flash memory via turning off :ref:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM`. It allows SPI flash operation functions to be executed from flash memory instead of IRAM. Thus it saves IRAM memory for other significant time-critical functions or tasks.
269269

270270
However, this has some implications for flash itself. Functions placed into flash memory may have slightly increased execution times compared to those placed in IRAM. Applications with strict timing requirements or those heavily reliant on SPI flash operations may need to evaluate the trade-offs before enabling this option.
271271

@@ -276,30 +276,83 @@ In a single core environment (:ref:`CONFIG_FREERTOS_UNICORE` enabled), you need
276276
Resource Consumption
277277
^^^^^^^^^^^^^^^^^^^^
278278

279-
Use the :doc:`/api-guides/tools/idf-size` tool to check the code and data consumption of the SPI flash driver. The following are the test conditions (using ESP32-C2 as an example):
279+
Use the :doc:`/api-guides/tools/idf-size` tool to check the code and data consumption of the SPI flash driver. The following are the test results under 2 different conditions (using ESP32-C2 as an example):
280280

281281
**Note that the following data are not exact values and are for reference only; they may differ on different chip models.**
282282

283-
Resource consumption when :ref:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM` is enabled.
284-
285-
+------------------+------------+-------+------+-------+-------+------------+-------+------------+---------+
286-
| Component Layer | Total Size | DIRAM | .bss | .data | .text | Flash Code | .text | Flash Data | .rodata |
287-
+==================+============+=======+======+=======+=======+============+=======+============+=========+
288-
| hal | 4624 | 4038 | 0 | 0 | 4038 | 586 | 586 | 0 | 0 |
289-
+------------------+------------+-------+------+-------+-------+------------+-------+------------+---------+
290-
| spi_flash | 14074 | 11597 | 82 | 1589 | 9926 | 2230 | 2230 | 247 | 247 |
291-
+------------------+------------+-------+------+-------+-------+------------+-------+------------+---------+
292-
293-
Resource consumption when :ref:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM` is disabled.
294-
295-
+------------------+------------+-------+------+-------+-------+------------+-------+------------+---------+
296-
| Component Layer | Total Size | DIRAM | .bss | .data | .text | Flash Code | .text | Flash Data | .rodata |
297-
+==================+============+=======+======+=======+=======+============+=======+============+=========+
298-
| hal | 4632 | 0 | 0 | 0 | 0 | 4632 | 4632 | 0 | 0 |
299-
+------------------+------------+-------+------+-------+-------+------------+-------+------------+---------+
300-
| spi_flash | 14569 | 1399 | 22 | 429 | 948 | 11648 | 11648 | 1522 | 1522 |
301-
+------------------+------------+-------+------+-------+-------+------------+-------+------------+---------+
302-
283+
Resource consumption when :ref:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM` is enabled:
284+
285+
.. list-table:: Resource Consumption
286+
:widths: 20 10 10 10 10 10 10 10 10 10
287+
:header-rows: 1
288+
289+
* - Component Layer
290+
- Total Size
291+
- DIRAM
292+
- .bss
293+
- .data
294+
- .text
295+
- Flash Code
296+
- .text
297+
- Flash Data
298+
- .rodata
299+
* - hal
300+
- 4624
301+
- 4038
302+
- 0
303+
- 0
304+
- 4038
305+
- 586
306+
- 586
307+
- 0
308+
- 0
309+
* - spi_flash
310+
- 14074
311+
- 11597
312+
- 82
313+
- 1589
314+
- 9926
315+
- 2230
316+
- 2230
317+
- 247
318+
- 247
319+
320+
Resource consumption when :ref:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM` is disabled:
321+
322+
.. list-table:: Resource Consumption
323+
:widths: 20 10 10 10 10 10 10 10 10 10
324+
:header-rows: 1
325+
326+
* - Component Layer
327+
- Total Size
328+
- DIRAM
329+
- .bss
330+
- .data
331+
- .text
332+
- Flash Code
333+
- .text
334+
- Flash Data
335+
- .rodata
336+
* - hal
337+
- 4632
338+
- 0
339+
- 0
340+
- 0
341+
- 0
342+
- 4632
343+
- 4632
344+
- 0
345+
- 0
346+
* - spi_flash
347+
- 14569
348+
- 1399
349+
- 22
350+
- 429
351+
- 948
352+
- 11648
353+
- 11648
354+
- 1522
355+
- 1522
303356

304357
Related Documents
305358
------------------

‎docs/zh_CN/api-guides/performance/ram-usage.rst

+3-1
Original file line numberDiff line numberDiff line change
@@ -216,7 +216,7 @@ IRAM 优化
216216
任何最终未用于静态 IRAM 的内存都将添加到堆内存中。
217217

218218

219-
.. only:: esp32c3
219+
.. only:: SOC_SPI_MEM_SUPPORT_AUTO_SUSPEND
220220

221221
flash 暂停特性
222222
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -232,6 +232,8 @@ IRAM 优化
232232

233233
将额外代码放置到 IRAM 中，将增加 IRAM 使用量，ESP-IDF 提供了 :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND` 选项，可以缓解 IRAM 的使用。通过启用此功能，使用 SPI flash API 和基于 SPI flash API 的 API 时，不会导致缓存禁用，因此 flash 中的代码和数据仍可正常执行或访问，但会有些延迟。有关此功能的详细信息，请参阅 :ref:`auto-suspend`。
234234

235+
启用 :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND` 后，可以减少 flash 驱动的 IRAM 使用。更多详细信息请参阅 :ref:`internal_memory_saving_for_flash_driver`。
236+
235237
有关 flash 暂停特性的使用及其相应的响应时间延迟，请参阅 :example:`system/flash_suspend`。
236238

237239

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

+97-1
Original file line numberDiff line numberDiff line change
@@ -161,7 +161,7 @@ flash 在 {IDF_TARGET_CACHE_SIZE} 页进行映射。内存映射硬件既可将
161161
- :cpp:func:`spi_flash_munmap`：取消上述区域的映射；
162162
- :cpp:func:`esp_partition_mmap`：将分区的一部分映射至 CPU 指令空间或数据空间；
163163

164-
:cpp:func:`spi_flash_mmap` 和 :cpp:func:`esp_partition_mmap` 的区别如下：
164+
:cpp:func:`spi_flash_mmap` 和 :cpp:func:`esp_partition_mmap` 的区别如下：
165165

166166
- :cpp:func:`spi_flash_mmap`：需要给定一个 {IDF_TARGET_CACHE_SIZE} 对齐的物理地址；
167167
- :cpp:func:`esp_partition_mmap`：给定分区内任意偏移量即可，此函数根据需要将返回的指针调整至指向映射内存。
@@ -258,6 +258,102 @@ flash 操作完成后，CPU A 上的函数将设置另一标志位，即 ``s_fla
258258

259259
在单核环境中（启用 :ref:`CONFIG_FREERTOS_UNICORE`），需要禁用上述两个 cache，以防发生 CPU 间通信。
260260

261+
.. only:: SOC_SPI_MEM_SUPPORT_AUTO_SUSPEND
262+
263+
.. _internal_memory_saving_for_flash_driver:
264+
265+
flash 驱动的内部存储优化
266+
-----------------------------
267+
268+
ESP-IDF 提供了优化 IRAM 使用的选项。通过禁用 :ref:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM` 选项，可以选择性地将某些函数地放入 flash，使 SPI flash 操作函数在 flash 中执行，而不是从 IRAM 中执行。这种方式能够节省 IRAM 内存，用于其他对时间敏感的函数或任务。
269+
270+
然而，这种方式对 flash 性能具有一定的影响。与 IRAM 中的函数相比，放在 flash 中的函数执行时间可能略有增加。因此对于具有严格时序要求或严重依赖 SPI flash 操作的应用程序，采取此方式前需进行权衡。
271+
272+
.. note::
273+
274+
未启用 :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND` 时，不应禁用 :ref:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM`，否则会导致严重崩溃。关于 flash 挂起功能，请参阅 :ref:`auto-suspend`。
275+
276+
资源消耗
277+
^^^^^^^^^^^^
278+
279+
使用 :doc:`/api-guides/tools/idf-size` 工具来检查 SPI flash 驱动的代码和数据消耗。以下是测试条件（以 ESP32-C2 为例）：
280+
281+
**请注意，以下数据并非精确值，仅供参考；不同芯片型号可能会有所差异。**
282+
283+
启用 :ref:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM` 时的资源消耗如下表所示：
284+
285+
.. list-table:: 选项启用时的资源消耗
286+
:widths: 20 10 10 10 10 10 10 10 10 10
287+
:header-rows: 1
288+
289+
* - 组件层
290+
- 总大小
291+
- DIRAM
292+
- .bss
293+
- .data
294+
- .text
295+
- flash 代码
296+
- .text
297+
- flash 数据
298+
- .rodata
299+
* - hal
300+
- 4624
301+
- 4038
302+
- 0
303+
- 0
304+
- 4038
305+
- 586
306+
- 586
307+
- 0
308+
- 0
309+
* - spi_flash
310+
- 14074
311+
- 11597
312+
- 82
313+
- 1589
314+
- 9926
315+
- 2230
316+
- 2230
317+
- 247
318+
- 247
319+
320+
禁用 :ref:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM` 时的资源消耗如下表所示：
321+
322+
.. list-table:: 选项禁用时的资源消耗
323+
:widths: 20 10 10 10 10 10 10 10 10 10
324+
:header-rows: 1
325+
326+
* - 组件层
327+
- 总大小
328+
- DIRAM
329+
- .bss
330+
- .data
331+
- .text
332+
- flash 代码
333+
- .text
334+
- flash 数据
335+
- .rodata
336+
* - hal
337+
- 4632
338+
- 0
339+
- 0
340+
- 0
341+
- 0
342+
- 4632
343+
- 4632
344+
- 0
345+
- 0
346+
* - spi_flash
347+
- 14569
348+
- 1399
349+
- 22
350+
- 429
351+
- 948
352+
- 11648
353+
- 11648
354+
- 1522
355+
- 1522
356+
261357
相关文档
262358
-----------------
263359

0 commit comments

Comments
 (0)