From a33b276671828c2edd5460d3bf2097fe08baf707 Mon Sep 17 00:00:00 2001 From: caixinying-git Date: Thu, 8 Jun 2023 15:33:02 +0800 Subject: [PATCH] docs: provide CN translation for linux-host-requirements.rst and external-ram-esp32-notes.rst --- docs/en/api-guides/external-ram.rst | 4 +-- .../inc/external-ram-esp32-notes.rst | 24 +++++++-------- .../inc/linux-host-requirements.rst | 6 ++-- docs/zh_CN/api-guides/external-ram.rst | 4 +-- .../inc/external-ram-esp32-notes.rst | 29 ++++++++++++++++++- .../inc/linux-host-requirements.rst | 14 ++++++++- 6 files changed, 60 insertions(+), 21 deletions(-) diff --git a/docs/en/api-guides/external-ram.rst b/docs/en/api-guides/external-ram.rst index 4573cb6583..3d59500e84 100644 --- a/docs/en/api-guides/external-ram.rst +++ b/docs/en/api-guides/external-ram.rst @@ -207,5 +207,5 @@ Failure to Initialize .. include:: inc/external-ram-esp32-notes.rst -.. _ESP32 ECO: https://www.espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf -.. _ESP32 ECO V3 User Guide: https://www.espressif.com/sites/default/files/documentation/ESP32_ECO_V3_User_Guide__EN.pdf +.. _ESP32 Series SoC Errata: https://www.espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf +.. _ESP32 Chip Revision v3.0 User Guide: https://www.espressif.com/sites/default/files/documentation/ESP32_ECO_V3_User_Guide__EN.pdf diff --git a/docs/en/api-guides/inc/external-ram-esp32-notes.rst b/docs/en/api-guides/inc/external-ram-esp32-notes.rst index a2bd20fd8e..ac8f8d4764 100644 --- a/docs/en/api-guides/inc/external-ram-esp32-notes.rst +++ b/docs/en/api-guides/inc/external-ram-esp32-notes.rst @@ -1,28 +1,28 @@ -* Regarding stacks in PSRAM: For tasks not calling on code in ROM in any way, directly or indirectly, the menuconfig option :ref:`CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY` will eliminate the check in xTaskCreateStatic, allowing a task's stack to be in external RAM. Using this is not advised, however. +* Regarding stacks in PSRAM: For tasks that do not call ROM code in any way (directly or indirectly), the :ref:`CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY` option will eliminate the check in :cpp:func:`xTaskCreateStatic`, allowing a task's stack to be in external RAM. However, using this is **not advised**. * When used at 80 MHz clock speed, external RAM must also occupy either the HSPI or VSPI bus. Select which SPI host will be used by :ref:`CONFIG_SPIRAM_OCCUPY_SPI_HOST`. -Chip revisions +Chip Revisions ============== -There are some issues with certain revisions of ESP32 that have repercussions for use with external RAM. The issues are documented in the `ESP32 ECO`_ document. In particular, ESP-IDF handles the bugs mentioned in the following ways: +There are some issues with certain revisions of ESP32 that have repercussions for use with external RAM. The issues are documented in the `ESP32 Series SoC Errata`_ document. In particular, ESP-IDF handles the bugs mentioned in the following ways: -ESP32 rev v0 ------------- +ESP32 Rev v0.0 +-------------- ESP-IDF has no workaround for the bugs in this revision of silicon, and it cannot be used to map external PSRAM into ESP32's main memory map. -ESP32 rev v1 ------------- -The bugs in this revision of silicon cause issues if certain sequences of machine instructions operate on external memory. (`ESP32 ECO`_ 3.2). As a workaround, the GCC compiler received the flag ``-mfix-esp32-psram-cache-issue`` to filter these sequences and only output the code that can safely be executed. Enable this flag by checking :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND`. +ESP32 Rev v1.0 +-------------- +The bugs in this revision of silicon cause issues if certain sequences of machine instructions operate on external memory. (`ESP32 Series SoC Errata`_ 3.2). As a workaround, the ``-mfix-esp32-psram-cache-issue`` flag has been added to the ESP32 GCC compiler such that these sequences are filtered out. As a result, the compiler only outputs code that can safely be executed. The :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` option can be used to enable this workaround. Aside from linking to a recompiled version of Newlib with the additional flag, ESP-IDF also does the following: - Avoids using some ROM functions -- Allocates static memory for the WiFi stack +- Allocates static memory for the Wi-Fi stack -ESP32 rev v3 ------------- +ESP32 Rev v3.0 +-------------- -ESP32 revision 3 ("ECO V3") fixes the PSRAM cache issue found in rev. 1. When :ref:`CONFIG_ESP32_REV_MIN` option is set to rev. 3, compiler workarounds related to PSRAM will be disabled. For more information about ESP32 ECO V3, see `ESP32 ECO V3 User Guide`_. +ESP32 rev v3.0 fixes the PSRAM cache issue found in rev v1.0. When :ref:`CONFIG_ESP32_REV_MIN` option is set to ``rev v3.0``, compiler workarounds related to PSRAM will be disabled. For more information about ESP32 v3.0, see `ESP32 Chip Revision v3.0 User Guide`_. diff --git a/docs/en/api-guides/inc/linux-host-requirements.rst b/docs/en/api-guides/inc/linux-host-requirements.rst index c51d1a7a67..080f0f5645 100644 --- a/docs/en/api-guides/inc/linux-host-requirements.rst +++ b/docs/en/api-guides/inc/linux-host-requirements.rst @@ -1,6 +1,6 @@ -- Installed IDF including all IDF requirements +- Installed ESP-IDF including all ESP-IDF requirements - System package requirements (``libbsd``, ``libbsd-dev``) -- A recent enough Linux or MacOS version and gcc compiler +- A recent enough Linux or macOS version and GCC compiler - All components the application depends on must be either supported on the Linux target (Linux/POSIX simulator) or mock-able An application that runs on the Linux target has to set the ``COMPONENTS`` variable to ``main`` in the CMakeLists.txt of the application's root directory: @@ -10,4 +10,4 @@ An application that runs on the Linux target has to set the ``COMPONENTS`` varia set(COMPONENTS main) -This prevents the automatic inclusion of all components from IDF to the build process which is otherwise done for convenience. +This prevents the automatic inclusion of all components from ESP-IDF to the build process which is otherwise done for convenience. diff --git a/docs/zh_CN/api-guides/external-ram.rst b/docs/zh_CN/api-guides/external-ram.rst index 9d6260110b..75db03e7ee 100644 --- a/docs/zh_CN/api-guides/external-ram.rst +++ b/docs/zh_CN/api-guides/external-ram.rst @@ -204,5 +204,5 @@ ESP-IDF 启动过程中，片外 RAM 被映射到以 {IDF_TARGET_PSRAM_ADDR_STAR .. include:: inc/external-ram-esp32-notes.rst -.. _ESP32 ECO: https://www.espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_cn.pdf -.. _ESP32 ECO V3 User Guide: https://www.espressif.com/sites/default/files/documentation/ESP32_ECO_V3_User_Guide__CN.pdf +.. _ESP32 系列芯⽚勘误表: https://www.espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_cn.pdf +.. _ESP32 芯⽚版本 v3.0 使⽤指南: https://www.espressif.com/sites/default/files/documentation/ESP32_ECO_V3_User_Guide__CN.pdf diff --git a/docs/zh_CN/api-guides/inc/external-ram-esp32-notes.rst b/docs/zh_CN/api-guides/inc/external-ram-esp32-notes.rst index d0847aee7e..6d93693c8d 100644 --- a/docs/zh_CN/api-guides/inc/external-ram-esp32-notes.rst +++ b/docs/zh_CN/api-guides/inc/external-ram-esp32-notes.rst @@ -1 +1,28 @@ -.. include:: ../../en/api-guides/inc/external-ram-esp32-notes.rst \ No newline at end of file +* PSRAM 中的栈：对于不以任何直接或间接方式调用 ROM 中代码的任务，选项 :ref:`CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY` 会取消 :cpp:func:`xTaskCreateStatic` 中的检查，允许任务栈存放在外部 RAM 中。但 **不建议** 使用此选项。 +* 在以 80 MHz 时钟速度运行时，外部 RAM 还必须占用 HSPI 或 VSPI 总线。设置 :ref:`CONFIG_SPIRAM_OCCUPY_SPI_HOST` 选项可以选择使用的 SPI 主机。 + + +芯片版本 +============== + +某些 ESP32 版本存在与外部 RAM 使用相关的问题，这些问题记录在 `ESP32 系列芯⽚勘误表`_ 文档中。ESP-IDF 会以下列特定方式处理上述错误： + + +ESP32 rev v0.0 +-------------- +ESP-IDF 并未针对该版芯片的错误提供解决方案，也不能将外部 PSRAM 映射到 ESP32 的主存储器映射中。 + + +ESP32 rev v1.0 +-------------- +某些机器指令序列对外部内存进行操作时，该版芯片的错误会引发问题，详情请参阅 `ESP32 系列芯⽚勘误表`_ 第 3.2 节。为此，ESP32 GCC 编译器增加了标志 ``-mfix-esp32-psram-cache-issue``，用于过滤这些序列，只输出可以安全执行的代码。请启用 :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` 选项以使用此方法。 + +启用此选项后，ESP-IDF 会链接到重新编译且带有额外标志的 Newlib，此外还会执行以下操作： + +- 避免使用某些 ROM 函数 +- 为 Wi-Fi 栈分配静态内存 + +ESP32 rev v3.0 +-------------- + +ESP32 rev v3.0 修复了 rev v1.0 中发现的 PSRAM 缓存问题。当 :ref:`CONFIG_ESP32_REV_MIN` 选项设置为 ``rev v3.0`` 时，会禁用与 PSRAM 相关的编译器解决方案。有关 ESP32 v3.0 的更多详情，请参阅 `ESP32 芯⽚版本 v3.0 使⽤指南`_。 diff --git a/docs/zh_CN/api-guides/inc/linux-host-requirements.rst b/docs/zh_CN/api-guides/inc/linux-host-requirements.rst index 7b2eb305c4..a3299137c4 100644 --- a/docs/zh_CN/api-guides/inc/linux-host-requirements.rst +++ b/docs/zh_CN/api-guides/inc/linux-host-requirements.rst @@ -1 +1,13 @@ -.. include:: ../../en/api-guides/inc/linux-host-requirements.rst +- 已安装 ESP-IDF 及使用 ESP-IDF 的所有依赖项 +- 满足系统软件包需求 (``libbsd``、``libbsd-dev``) +- Linux 或 macOS 和 GCC 编译器已更新至足够新的版本 +- 应用程序所依赖的所有组件必须受 Linux 目标（Linux/POSIX 模拟器）支持，或可进行模拟 + +对于在 Linux 目标上运行的应用程序，需要在应用程序根目录的 CMakeLists.txt 文件中，设置 ``COMPONENTS`` 变量为 ``main``，具体操作如下： + +.. code-block:: cmake + + set(COMPONENTS main) + + +为方便起见，应用程序会在构建过程中，自动包含 ESP-IDF 的所有组件，执行上述代码则可以防止此类情况。