mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
docs: Update translation for ESP-IDF docs for syncronization
This commit is contained in:
renpeiying
parent
c8f17b1b7c
commit
9b447664db
@ -144,6 +144,7 @@ To manage the Python version more generally via the command line, check out the
|
||||
|
||||
.. _example-project-structure:
|
||||
|
||||
|
||||
Example Project
|
||||
===============
|
||||
|
||||
@ -174,7 +175,7 @@ This example "myProject" contains the following elements:
|
||||
|
||||
- A top-level project CMakeLists.txt file. This is the primary file which CMake uses to learn how to build the project; and may set project-wide CMake variables. It includes the file :idf_file:`/tools/cmake/project.cmake` which implements the rest of the build system. Finally, it sets the project name and defines the project.
|
||||
|
||||
- "sdkconfig" project configuration file. This file is created/updated when ``idf.py menuconfig`` runs, and holds the configuration for all of the components in the project (including ESP-IDF itself). The "sdkconfig" file may or may not be added to the source control system of the project.
|
||||
- "sdkconfig" project configuration file. This file is created/updated when ``idf.py menuconfig`` runs, and holds the configuration for all of the components in the project (including ESP-IDF itself). The ``sdkconfig`` file may or may not be added to the source control system of the project.
|
||||
|
||||
- Optional "bootloader_components" directory contains components that need to be compiled and linked inside the bootloader project. A project does not have to contain custom bootloader components of this kind, but it can be useful in case the bootloader needs to be modified to embed new features.
|
||||
|
||||
@ -296,7 +297,9 @@ Multiple Components with the Same Name
|
||||
|
||||
When ESP-IDF is collecting all the components to compile, it will do this in the order specified by ``COMPONENT_DIRS``; by default, this means ESP-IDF's internal components first (``IDF_PATH/components``), then any components in directories specified in ``EXTRA_COMPONENT_DIRS``, and finally the project's components (``PROJECT_DIR/components``). If two or more of these directories contain component sub-directories with the same name, the component in the last place searched is used. This allows, for example, overriding ESP-IDF components with a modified version by copying that component from the ESP-IDF components directory to the project components directory and then modifying it there. If used in this way, the ESP-IDF directory itself can remain untouched.
|
||||
|
||||
.. note:: If a component is overridden in an existing project by moving it to a new location, the project will not automatically see the new component path. Run ``idf.py reconfigure`` (or delete the project build folder) and then build again.
|
||||
.. note::
|
||||
|
||||
If a component is overridden in an existing project by moving it to a new location, the project will not automatically see the new component path. Run ``idf.py reconfigure`` (or delete the project build folder) and then build again.
|
||||
|
||||
|
||||
.. _cmake_minimal_component_cmakelists:
|
||||
@ -443,11 +446,13 @@ When Writing a Component
|
||||
|
||||
If a component only supports some target chips (values of ``IDF_TARGET``) then it can specify ``REQUIRED_IDF_TARGETS`` in the ``idf_component_register`` call to express these requirements. In this case, the build system will generate an error if the component is included in the build, but does not support the selected target.
|
||||
|
||||
.. note:: In CMake terms, ``REQUIRES`` & ``PRIV_REQUIRES`` are approximate wrappers around the CMake functions ``target_link_libraries(... PUBLIC ...)`` and ``target_link_libraries(... PRIVATE ...)``.
|
||||
.. note::
|
||||
|
||||
In CMake terms, ``REQUIRES`` & ``PRIV_REQUIRES`` are approximate wrappers around the CMake functions ``target_link_libraries(... PUBLIC ...)`` and ``target_link_libraries(... PRIVATE ...)``.
|
||||
|
||||
|
||||
.. _example component requirements:
|
||||
|
||||
|
||||
Example of Component Requirements
|
||||
---------------------------------
|
||||
|
||||
@ -753,7 +758,7 @@ It is also possible to conditionally replace the bootloader depending on a certa
|
||||
|
||||
project(main)
|
||||
|
||||
It is important to note that this can also be used for any other bootloader components than `main`. In all cases, the prefix `bootloader_component` must not be specified.
|
||||
It is important to note that this can also be used for any other bootloader components than ``main``. In all cases, the prefix ``bootloader_component`` must not be specified.
|
||||
|
||||
See :example:`custom_bootloader/bootloader_override` for an example of overriding the default bootloader.
|
||||
|
||||
@ -796,6 +801,7 @@ Browse the :idf_file:`/tools/cmake/project.cmake` file and supporting functions
|
||||
|
||||
.. _component_cmakelists_example:
|
||||
|
||||
|
||||
Example Component CMakeLists
|
||||
============================
|
||||
|
||||
|
||||
@ -90,6 +90,7 @@ The following optimizations improve the execution of nearly all code, including
|
||||
|
||||
Reduce Logging Overhead
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Although standard output is buffered, it is possible for an application to be limited by the rate at which it can print data to log output once buffers are full. This is particularly relevant for startup time if a lot of output is logged, but such problem can happen at other times as well. There are multiple ways to solve this problem:
|
||||
|
||||
.. list::
|
||||
|
||||
@ -1,6 +1,7 @@
|
||||
*********
|
||||
Resources
|
||||
*********
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
.. toctree::
|
||||
|
||||
@ -144,6 +144,7 @@ ESP-IDF 适用于 Python 3.8 以上版本。
|
||||
|
||||
.. _example-project-structure:
|
||||
|
||||
|
||||
示例项目
|
||||
========
|
||||
|
||||
@ -154,6 +155,9 @@ ESP-IDF 适用于 Python 3.8 以上版本。
|
||||
- myProject/
|
||||
- CMakeLists.txt
|
||||
- sdkconfig
|
||||
- bootloader_components/ - boot_component/ - CMakeLists.txt
|
||||
- Kconfig
|
||||
- src1.c
|
||||
- components/ - component1/ - CMakeLists.txt
|
||||
- Kconfig
|
||||
- src1.c
|
||||
@ -173,6 +177,8 @@ ESP-IDF 适用于 Python 3.8 以上版本。
|
||||
|
||||
- "sdkconfig" 项目配置文件，执行 ``idf.py menuconfig`` 时会创建或更新此文件，文件中保存了项目中所有组件（包括 ESP-IDF 本身）的配置信息。 ``sdkconfig`` 文件可能会也可能不会被添加到项目的源码管理系统中。
|
||||
|
||||
- 可选的 "bootloader_components" 目录中包含了需要在引导加载项目中进行编译和链接的组件。并不是每个项目都需要这种自定义组件，但此类组件在引导加载程序需要修改以嵌入新功能时可能很有用。
|
||||
|
||||
- 可选的 "components" 目录中包含了项目的部分自定义组件，并不是每个项目都需要这种自定义组件，但它有助于构建可复用的代码或者导入第三方（不属于 ESP-IDF）的组件。或者，你也可以在顶层 CMakeLists.txt 中设置 ``EXTRA_COMPONENT_DIRS`` 变量以查找其他指定位置处的组件。
|
||||
|
||||
- "main" 目录是一个特殊的组件，它包含项目本身的源代码。"main" 是默认名称，CMake 变量 ``COMPONENT_DIRS`` 默认包含此组件，但你可以修改此变量。有关详细信息，请参阅 :ref:`重命名 main 组件 <rename-main>`。如果项目中源文件较多，建议将其归于组件中，而不是全部放在 "main" 中。
|
||||
@ -227,6 +233,8 @@ ESP-IDF 适用于 Python 3.8 以上版本。
|
||||
|
||||
- ``COMPONENTS``：要构建进项目中的组件名称列表，默认为 ``COMPONENT_DIRS`` 目录下检索到的所有组件。使用此变量可以“精简”项目以缩短构建时间。请注意，如果一个组件通过 ``COMPONENT_REQUIRES`` 指定了它依赖的另一个组件，则会自动将其添加到 ``COMPONENTS`` 中，所以 ``COMPONENTS`` 列表可能会非常短。
|
||||
|
||||
- ``BOOTLOADER_IGNORE_EXTRA_COMPONENT``：引导加载程序编译时应忽略的组件列表，位于 ``bootloader_components/`` 目录中。使用这一变量可以将一个组件有条件地包含在项目中。
|
||||
|
||||
以上变量中的路径可以是绝对路径，或者是相对于项目目录的相对路径。
|
||||
|
||||
请使用 `cmake 中的 set 命令 <cmake set_>`_ 来设置这些变量，如 ``set(VARIABLE "VALUE")``。请注意，``set()`` 命令需放在 ``include(...)`` 之前，``cmake_minimum(...)`` 之后。
|
||||
@ -438,7 +446,9 @@ ESP-IDF 构建系统会在命令行中添加以下 C 预处理器定义：
|
||||
|
||||
如果组件仅支持某些硬件目标（``IDF_TARGET`` 的值），则可以在 ``idf_component_register`` 中指定 ``REQUIRED_IDF_TARGETS`` 来声明这个需求。在这种情况下，如果构建系统导入了不支持当前硬件目标的组件时就会报错。
|
||||
|
||||
.. 注解:: 在 CMake 中，``REQUIRES`` 和 ``PRIV_REQUIRES`` 是 CMake 函数 ``target_link_libraries(... PUBLIC ...)`` 和 ``target_link_libraries(... PRIVATE ...)`` 的近似包装。
|
||||
.. 注解::
|
||||
|
||||
在 CMake 中，``REQUIRES`` 和 ``PRIV_REQUIRES`` 是 CMake 函数 ``target_link_libraries(... PUBLIC ...)`` 和 ``target_link_libraries(... PRIVATE ...)`` 的近似包装。
|
||||
|
||||
|
||||
.. _example component requirements:
|
||||
@ -719,6 +729,40 @@ KConfig.projbuild
|
||||
请参考 :example:`build_system/wrappers` 示例，了解其详细原理。更多细节请参阅 :idf_file:`examples/build_system/wrappers/README.md`。
|
||||
|
||||
|
||||
覆盖默认引导加载程序
|
||||
--------------------------
|
||||
|
||||
由于 ESP-IDF 中存在可选目录 ``bootloader_components``，因此可以覆盖默认的 ESP-IDF 引导加载程序。覆盖前，应定义一个 ``bootloader_components/main`` 组件，使项目目录如下所示：
|
||||
|
||||
- myProject/
|
||||
- CMakeLists.txt
|
||||
- sdkconfig
|
||||
- bootloader_components/ - main/ - CMakeLists.txt
|
||||
- Kconfig
|
||||
- my_bootloader.c
|
||||
- main/ - CMakeLists.txt
|
||||
- app_main.c
|
||||
|
||||
- build/
|
||||
|
||||
|
||||
此处的 ``my_bootloader.c`` 文件会成为新引导加载程序的源代码，这意味着它需要执行所有必要的操作来设置并从 flash 中加载 ``main`` 应用程序。
|
||||
|
||||
还可以根据特定的条件来替换引导加载程序，例如替换指定目标芯片的引导加载程序。这可以通过 ``BOOTLOADER_IGNORE_EXTRA_COMPONENT`` CMake 变量实现，该列表会让 ESP-IDF 引导加载项目忽略 ``bootloader_components`` 中的指定组件，不对其进行编译。例如，如果希望使用 ESP32 目标芯片的默认引导加载程序，``myProject/CMakeLists.txt`` 应如下所示::
|
||||
|
||||
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
|
||||
|
||||
if(${IDF_TARGET} STREQUAL "esp32")
|
||||
set(BOOTLOADER_IGNORE_EXTRA_COMPONENT "main")
|
||||
endif()
|
||||
|
||||
project(main)
|
||||
|
||||
值得注意的是，这还可以用于除 ``main`` 之外的其他引导加载程序组件。在任何情况下，都不能指定前缀 ``bootloader_component``。
|
||||
|
||||
请参考 :example:`custom_bootloader/bootloader_override` 查看覆盖默认引导加载程序的示例。
|
||||
|
||||
|
||||
.. _config_only_component:
|
||||
|
||||
仅配置组件
|
||||
@ -757,6 +801,7 @@ CMake 调试
|
||||
|
||||
.. _component_cmakelists_example:
|
||||
|
||||
|
||||
组件 CMakeLists 示例
|
||||
====================
|
||||
|
||||
|
||||
@ -82,6 +82,7 @@
|
||||
:esp32: - 设置 :ref:`CONFIG_ESPTOOLPY_FLASHFREQ` 为 80 MHz。该值为默认值 40 MHz 的两倍，这意味着从 flash 加载或执行代码的速度也将翻倍。在更改此设置之前，应事先确认连接 {IDF_TARGET_NAME} 和 flash 的板或模块在温度限制范围内支持 80 MHz 的操作。相关信息参见硬件数据手册。
|
||||
- 设置 :ref:`CONFIG_ESPTOOLPY_FLASHMODE` 为 QIO 或 QOUT 模式（四线 I/O 模式）。相较于默认的 DIO 模式，在这两种模式下，从 flash 加载或执行代码的速度几乎翻倍。如果两种模式都支持，QIO 会稍微快于 QOUT。请注意，flash 芯片以及 {IDF_TARGET_NAME} 与 flash 芯片之间的电气连接都必须支持四线 I/O 模式，否则 SoC 将无法正常工作。
|
||||
- 设置 :ref:`CONFIG_COMPILER_OPTIMIZATION` 为 ``Optimize for performance (-O2)`` 。相较于默认设置，这可能会略微增加二进制文件大小，但几乎必然会提高某些代码的性能。请注意，如果代码包含 C 或 C++ 的未定义行为，提高编译器优化级别可能会暴露出原本未发现的错误。
|
||||
:SOC_ASSIST_DEBUG_SUPPORTED: - 将 :ref:`CONFIG_ESP_SYSTEM_HW_STACK_GUARD` 设置为禁用。这可能会小幅提升某些代码的性能，且在设备中断多次的情况下尤为明显。
|
||||
:esp32: - 如果应用程序是基于 ESP32 rev. 3 (ECO3) 的项目并且使用 PSRAM，设置 :ref:`CONFIG_ESP32_REV_MIN` 为 ``3`` 将禁用 PSRAM 的错误修复工作，可以减小代码大小并提高整体性能。
|
||||
:SOC_CPU_HAS_FPU: - 避免使用浮点运算 ``float``。尽管 {IDF_TARGET_NAME} 具备单精度浮点运算器，但是浮点运算总是慢于整数运算。因此可以考虑使用不同的整数表示方法进行运算，如定点表示法，或者将部分计算用整数运算后再切换为浮点运算。
|
||||
:not SOC_CPU_HAS_FPU: - 避免使用浮点运算 ``float``。{IDF_TARGET_NAME} 通过软件模拟进行浮点运算，因此速度非常慢。可以考虑使用不同的整数表示方法进行运算，如定点表示法，或者将部分计算用整数运算后再切换为浮点运算。
|
||||
@ -89,6 +90,7 @@
|
||||
|
||||
减少日志开销
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
尽管标准输出会先存储在缓冲区中，但缓冲区缺少可用空间时，应用程序将数据输出到日志的速度可能会受限。这点在程序启动并输出大量日志时尤为明显，但也可能随时发生。为解决这一问题，可以采取以下几种方法：
|
||||
|
||||
.. list::
|
||||
|
||||
@ -117,4 +117,4 @@ Light-sleep
|
||||
|
||||
如果通过 :cpp:func:`esp_light_sleep_start` 或 :cpp:func:`esp_deep_sleep_start` 手动进入睡眠模式，需注意，USB 串行/JTAG 控制器在睡眠期间不工作。ESP-IDF **没有添加任何拒绝进入睡眠的安全检查**，即使 USB 串行/JTAG 控制器已连接，也会进入睡眠模式。如果在连接了 USB 串行/JTAG 控制器的情况下进入睡眠，可以通过拔出并重新插入 USB 电缆来重新建立连接。
|
||||
|
||||
如果通过 :cpp:func:`esp_pm_configure` 自动进入睡眠模式，请启用 :ref:`CONFIG_USJ_NO_AUTO_LS_ON_CONNECTION` 选项，该选项支持 {IDF_TARGET_NAME} 自动检测 USB 串行/JTAG 控制器与主机的连接情况，并在连接持续时，阻止程序自动进入睡眠模式。注意，此选项会增加功耗。
|
||||
如果通过 :cpp:func:`esp_pm_configure` 自动进入睡眠模式，请启用 :ref:`CONFIG_USJ_NO_AUTO_LS_ON_CONNECTION` 选项，该选项支持 {IDF_TARGET_NAME} 自动检测 USB 串行/JTAG 控制器与主机的连接情况，并在连接持续时，阻止程序自动进入睡眠模式。注意，此选项会增加功耗。
|
||||
|
||||
@ -62,7 +62,6 @@ GPIO 汇总
|
||||
|
||||
每个引脚可以独立启用迟滞功能。默认情况下，它由 eFuse 控制，且处于关闭状态，但也可以由软件控制启用或禁用。您可以通过配置 :cpp:member:`gpio_config_t::hys_ctrl_mode` 来选择迟滞控制模式。迟滞控制模式会和其余 GPIO 配置一起在 :cpp:func:`gpio_config` 中生效。
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
当迟滞功能由 eFuse 控制时，仍然可以独立的控制每个引脚的该功能，您需要 `烧断 eFuse <https://docs.espressif.com/projects/esptool/en/latest/esp32/espefuse/index.html>`_ ，以在特定 GPIO上 启用迟滞功能。
|
||||
|
||||
@ -52,7 +52,9 @@ HTTPS 请求
|
||||
|
||||
ESP HTTP 客户端支持使用 **mbedTLS** 的 SSL 连接，需将 ``url`` 配置为以 ``https`` 开头，或将 ``transport_type`` 设置为 ``HTTP_TRANSPORT_OVER_SSL``。可以通过 :ref:`CONFIG_ESP_HTTP_CLIENT_ENABLE_HTTPS` 来配置 HTTPS 支持（默认启用）。
|
||||
|
||||
.. note:: 在发起 HTTPS 请求时，如需服务器验证，首先需要向 ``esp_http_client_config_t`` 配置中的 ``cert_pem`` 成员提供额外的根证书（PEM 格式）。用户还可以通过 ``esp_http_client_config_t`` 配置中的 ``crt_bundle_attach`` 成员，使用 ``ESP x509 Certificate Bundle`` 进行服务器验证。
|
||||
.. note::
|
||||
|
||||
在发起 HTTPS 请求时，如需服务器验证，首先需要向 ``esp_http_client_config_t`` 配置中的 ``cert_pem`` 成员提供额外的根证书（PEM 格式）。用户还可以通过 ``esp_http_client_config_t`` 配置中的 ``crt_bundle_attach`` 成员，使用 ``ESP x509 Certificate Bundle`` 进行服务器验证。
|
||||
|
||||
如需了解上文备注中的实现细节，请参考应用示例中的函数 ``https_with_url`` 和 ``https_with_hostname_path``。
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@
|
||||
| 96 | 获取 ``ESP_PM_CPU_FREQ_MAX`` | | CPU: 96 MHz |
|
||||
| | | | APB: 32 Mhz |
|
||||
+ +---------------------------------------+-------------------------------------+
|
||||
| | | 获取 ``ESP_PM_APB_FREQ_MAX``, | | CPU: 32 MHz |
|
||||
| | | 获取 ``ESP_PM_APB_FREQ_MAX``， | | CPU: 32 MHz |
|
||||
| | | 未获得 ``ESP_PM_CPU_FREQ_MAX`` | | APB: 32 Mhz |
|
||||
+ +---------------------------------------+-------------------------------------+
|
||||
| | 无 | 使用 :cpp:func:`esp_pm_configure` |
|
||||
@ -14,7 +14,7 @@
|
||||
| 64 | 获取 ``ESP_PM_CPU_FREQ_MAX`` | | CPU: 64 MHz |
|
||||
| | | | APB: 32 Mhz |
|
||||
+ +---------------------------------------+-------------------------------------+
|
||||
| | | 获取 ``ESP_PM_APB_FREQ_MAX``, | | CPU: 32 MHz |
|
||||
| | | 获取 ``ESP_PM_APB_FREQ_MAX``， | | CPU: 32 MHz |
|
||||
| | | 未获得 ``ESP_PM_CPU_FREQ_MAX`` | | APB: 32 Mhz |
|
||||
+ +---------------------------------------+-------------------------------------+
|
||||
| | 无 | 使用 :cpp:func:`esp_pm_configure` |
|
||||
@ -23,9 +23,9 @@
|
||||
| 48 | 获取 ``ESP_PM_CPU_FREQ_MAX`` | | CPU: 48 MHz |
|
||||
| | | | APB: 32 Mhz |
|
||||
+ +---------------------------------------+-------------------------------------+
|
||||
| | | 获取 ``ESP_PM_APB_FREQ_MAX``, | | CPU: 32 MHz |
|
||||
| | | 获取 ``ESP_PM_APB_FREQ_MAX``， | | CPU: 32 MHz |
|
||||
| | | 未获得 ``ESP_PM_CPU_FREQ_MAX`` | | APB: 32 Mhz |
|
||||
+ +---------------------------------------+-------------------------------------+
|
||||
| | 无 | 使用 :cpp:func:`esp_pm_configure` |
|
||||
| | | 为二者设置最小值 |
|
||||
+---------------+---------------------------------------+-------------------------------------+
|
||||
+---------------+---------------------------------------+-------------------------------------+
|
||||
@ -63,4 +63,3 @@ Pull Request 准备好待合并时，首先会合并到我们的内部 git 系
|
||||
contributor-agreement
|
||||
copyright-guide
|
||||
esp-idf-tests-with-pytest
|
||||
|
||||
|
||||
@ -8,6 +8,7 @@ FatFs
|
||||
|
||||
``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
|
||||
---------
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user