diff --git a/docs/en/COPYRIGHT.rst b/docs/en/COPYRIGHT.rst index 1082cc860a..bf9ad5fad3 100644 --- a/docs/en/COPYRIGHT.rst +++ b/docs/en/COPYRIGHT.rst @@ -19,7 +19,9 @@ Firmware Components These third party libraries can be included into the application (firmware) produced by ESP-IDF. -* :component:`Newlib ` is licensed under the BSD License and is Copyright of various parties, as described in :component_file:`COPYING.NEWLIB `. If :ref:`CONFIG_LIBC_PICOLIBC` is enabled, see also :component_file:`COPYING.picolibc `. +* :component:`Newlib ` is licensed under the BSD License, with copyright held by the respective parties, as described in :component_file:`COPYING.NEWLIB `. If :ref:`CONFIG_LIBC_PICOLIBC` is enabled, see also :component_file:`COPYING.picolibc `. + +:component:`Picolibc ` is licensed under the BSD License, with copyright held by the respective parties, as described in :component_file:`COPYING.picolibc `. * :component:`Xtensa header files ` are Copyright (C) 2013 Tensilica Inc and are licensed under the MIT License as reproduced in the individual header files. diff --git a/docs/en/api-guides/performance/ram-usage.rst b/docs/en/api-guides/performance/ram-usage.rst index 98eddd5df1..9cac631274 100644 --- a/docs/en/api-guides/performance/ram-usage.rst +++ b/docs/en/api-guides/performance/ram-usage.rst @@ -57,10 +57,10 @@ Configuration Options for Stack Overflow Detection .. only:: SOC_ASSIST_DEBUG_SUPPORTED - Hardware Stack Guard - ~~~~~~~~~~~~~~~~~~~~ + Hardware Stack Guard + ~~~~~~~~~~~~~~~~~~~~ - The Hardware Stack Guard is a reliable method for detecting stack overflow. This method uses the hardware's Debug Assistant module to monitor the CPU's stack pointer register. A panic is immediately triggered if the stack pointer register goes beyond the bounds of the current stack (see :ref:`Hardware-Stack-Guard` for more details). The Hardware Stack Guard can be enabled via the :ref:`CONFIG_ESP_SYSTEM_HW_STACK_GUARD` option. + The Hardware Stack Guard is a reliable method for detecting stack overflow. This method uses the hardware's Debug Assistant module to monitor the CPU's stack pointer register. A panic is immediately triggered if the stack pointer register goes beyond the bounds of the current stack (see :ref:`Hardware-Stack-Guard` for more details). The Hardware Stack Guard can be enabled via the :ref:`CONFIG_ESP_SYSTEM_HW_STACK_GUARD` option. End of Stack Watchpoint ~~~~~~~~~~~~~~~~~~~~~~~ @@ -74,11 +74,11 @@ The Stack Canary Bytes feature adds a set of magic bytes at the end of each task .. note:: - When using the End of Stack Watchpoint or Stack Canary Bytes, it is possible that a stack pointer skips over the watchpoint or canary bytes on a stack overflow and corrupts another region of RAM instead. Thus, these methods cannot detect all stack overflows. + When using the End of Stack Watchpoint or Stack Canary Bytes, it is possible that a stack pointer skips over the watchpoint or canary bytes on a stack overflow and corrupts another region of RAM instead. Thus, these methods cannot detect all stack overflows. - .. only:: SOC_ASSIST_DEBUG_SUPPORTED + .. only:: SOC_ASSIST_DEBUG_SUPPORTED - Recommended and default option is :ref:`CONFIG_ESP_SYSTEM_HW_STACK_GUARD` which avoids this disadvantage. + Recommended and default option is :ref:`CONFIG_ESP_SYSTEM_HW_STACK_GUARD` which avoids this disadvantage. Run-time Methods to Determine Stack Size ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/en/api-guides/performance/size.rst b/docs/en/api-guides/performance/size.rst index 9cbaa16243..d48b699d26 100644 --- a/docs/en/api-guides/performance/size.rst +++ b/docs/en/api-guides/performance/size.rst @@ -158,7 +158,7 @@ Picolibc instead of Newlib By default, ESP-IDF uses the Newlib C library, and it also has experimental support for the Picolibc C library. -Picolibc C library provides smaller ``printf``-family functions and can reduce the binary size by up to 30 KB, depending on your application. +Picolibc C library provides smaller ``printf`` family functions and can reduce the binary size by up to 30 KB, depending on your application. To switch to linking against the Picolibc C library, please enable the configuration options :ref:`CONFIG_IDF_EXPERIMENTAL_FEATURES` and :ref:`CONFIG_LIBC_PICOLIBC`. diff --git a/docs/zh_CN/COPYRIGHT.rst b/docs/zh_CN/COPYRIGHT.rst index cbd82840d0..c614804a53 100644 --- a/docs/zh_CN/COPYRIGHT.rst +++ b/docs/zh_CN/COPYRIGHT.rst @@ -19,9 +19,9 @@ 以下这些第三方库包含在 ESP-IDF 生成的应用程序（固件）中。 -* :component:`Newlib ` 经 BSD 许可证许可，版权归各方所有，如 :component_file:`COPYING.NEWLIB ` 中所述。如果启用了 :ref:`CONFIG_LIBC_PICOLIBC`，另请参阅 :component_file:`COPYING.picolibc `。 +* 如 :component_file:`COPYING.NEWLIB ` 中所述， :component:`Newlib ` 经 BSD 许可证许可，版权归各方所有。如启用了 :ref:`CONFIG_LIBC_PICOLIBC`，请参阅 :component_file:`COPYING.picolibc `。 -* :component:`Picolibc ` 经 BSD 许可证许可，版权归各方所有，如 :component_file:`COPYING.picolibc ` 中所述。 +* 如 :component_file:`COPYING.picolibc ` 中所述， :component:`Picolibc ` 经 BSD 许可证许可，版权归各方所有。 * :component:`Xtensa 头文件 ` 版权归 2013 Tensilica 公司所有，并根据各头文件中复制的 MIT 许可证进行许可。 diff --git a/docs/zh_CN/api-guides/c.rst b/docs/zh_CN/api-guides/c.rst index 76ee9f2466..ed7a304db9 100644 --- a/docs/zh_CN/api-guides/c.rst +++ b/docs/zh_CN/api-guides/c.rst @@ -3,14 +3,14 @@ C 支持 :link_to_translation:`en:[English]` -ESP-IDF 主要使用 C 语言编写，并提供 C API。ESP-IDF 可以使用以下 C 标准库实现之一： +ESP-IDF 主要使用 C 语言编写，并提供 C API。ESP-IDF 可以使用以下 C 标准函数库的实现之一： - `Newlib `_ (默认) - `Picolibc `_ (通过 :ref:`CONFIG_LIBC_PICOLIBC` Kconfig 选项启用) Newlib 的版本号记录在 :component_file:`newlib/sbom.yml` 文件中。 -一般来说，除非在下面的 :ref:`unsupported_c_features` 中特别说明，当前使用的编译器（目前是 GCC）支持的所有 C 语言功能在 ESP-IDF 中均可使用。 +一般来说，除非在 :ref:`unsupported_c_features` 特别说明，当前编译器（目前是 GCC）支持的所有 C 语言功能在 ESP-IDF 中均可使用。 .. _c_version: diff --git a/docs/zh_CN/api-guides/lwip.rst b/docs/zh_CN/api-guides/lwip.rst index dc88ee7c13..d47f3ad484 100644 --- a/docs/zh_CN/api-guides/lwip.rst +++ b/docs/zh_CN/api-guides/lwip.rst @@ -173,7 +173,7 @@ BSD 套接字的相关参考资料十分丰富，包括但不限于： 套接字错误原因代码 ++++++++++++++++++++++++ -以下是常见错误代码列表。有关标准 POSIX/C 错误代码的详细列表，请参阅 `newlib errno.h `_ 和特定平台扩展 :component_file:`newlib/platform_include/sys/errno.h`。 +以下是常见错误代码列表。获取标准 POSIX/C 错误代码的详细列表，请参阅 `newlib errno.h `_ 和特定平台扩展 :component_file:`newlib/platform_include/sys/errno.h`。 .. list-table:: :header-rows: 1 diff --git a/docs/zh_CN/api-guides/performance/ram-usage.rst b/docs/zh_CN/api-guides/performance/ram-usage.rst index dff7f3285d..f0c72ce227 100644 --- a/docs/zh_CN/api-guides/performance/ram-usage.rst +++ b/docs/zh_CN/api-guides/performance/ram-usage.rst @@ -7,7 +7,7 @@ 固件应用程序的可用 RAM 在某些情况下可能处于低水平，甚至完全耗尽。为此，应调整这些情况下固件应用程序的内存使用情况。 -固件应用程序通常需要为内部 RAM 保留备用空间，用于应对非常规情况，或在后续版本的更新中，适应 RAM 使用需求的变化。 +固件通常需要为内部 RAM 保留备用空间，用于应对非常规情况，或在后续版本的更新中，适应 RAM 使用需求的变化。 背景 ---------- @@ -57,28 +57,28 @@ ESP-IDF 包含一系列堆 API，可以在运行时测量空闲堆内存，请 .. only:: SOC_ASSIST_DEBUG_SUPPORTED - 硬件栈保护 - ~~~~~~~~~~~~ + 硬件栈保护 + ~~~~~~~~~~~~ - 硬件栈保护是一种检测栈溢出的可靠方法，通过硬件的辅助调试模块来监视 CPU 的栈指针寄存器。如果栈指针寄存器超出了当前栈的边界，则立即触发紧急情况提示（更多详细信息，请参阅 :ref:`Hardware-Stack-Guard`）。可以通过 :ref:`CONFIG_ESP_SYSTEM_HW_STACK_GUARD` 选项启用硬件栈保护。 + 硬件栈保护是一种检测栈溢出的可靠方法，通过硬件的辅助调试模块来监视 CPU 的栈指针寄存器。如果栈指针寄存器超出了当前栈的边界，则立即触发紧急情况提示（更多详细信息，请参阅 :ref:`Hardware-Stack-Guard`）。可以通过 :ref:`CONFIG_ESP_SYSTEM_HW_STACK_GUARD` 选项启用硬件栈保护。 栈末尾监视点 ~~~~~~~~~~~~~~ 栈末尾监视点将 CPU 监视点放置在当前栈的末尾。如果该字被覆盖（例如栈溢出），则会立即触发紧急情况提示。在未使用调试器的监视点时，可以设置 :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` 选项，启用栈末尾监视点功能。 -栈金丝雀字节 -~~~~~~~~~~~~~~ +栈 canary 字节 +~~~~~~~~~~~~~~~~~ -栈金丝雀字节功能在每个任务的栈末尾添加一组魔术字节，并在每次上下文切换时检查这些字节是否已更改。如果这些魔术字节被覆盖，则会触发紧急情况提示。可以通过 :ref:`CONFIG_FREERTOS_CHECK_STACKOVERFLOW` 选项启用栈金丝雀字节功能。 +栈 canary 字节功能在每个任务的栈末尾添加一组魔术字节，并在每次上下文切换时检查这些字节是否已更改。如果这些魔术字节被覆盖，则会触发紧急情况提示。可以通过 :ref:`CONFIG_FREERTOS_CHECK_STACKOVERFLOW` 选项启用栈 canary 字节功能。 .. note:: - 使用栈末尾监视点或栈金丝雀字节时，栈指针可能在栈溢出时跳过监视点或金丝雀字节，损坏 RAM 的其他区域。因此，上述方法并不能检测所有的栈溢出。 + 使用栈末尾监视点或栈 canary 字节时，栈指针可能在栈溢出时跳过监视点或 canary 字节，损坏 RAM 的其他区域。因此，上述方法并不能检测所有的栈溢出。 - .. only:: SOC_ASSIST_DEBUG_SUPPORTED + .. only:: SOC_ASSIST_DEBUG_SUPPORTED - 推荐启用默认选项 :ref:`CONFIG_ESP_SYSTEM_HW_STACK_GUARD`，避免这个缺点。 + 推荐启用默认选项 :ref:`CONFIG_ESP_SYSTEM_HW_STACK_GUARD`，避免这个缺点。 任务运行时确定栈内存大小的方法 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -96,7 +96,7 @@ ESP-IDF 包含一系列堆 API，可以在运行时测量空闲堆内存，请 - 避免占用过多栈内存的函数。字符串格式化函数（如 ``printf()``）会使用大量栈内存，如果任务不调用这类函数，通常可以减小其占用的栈内存。 - - :ref:`picolibc-instead-of-newlib` 可以显著减少 ``printf()`` 调用的堆栈使用量。 + - 使用实验性的选项 :ref:`picolibc-instead-of-newlib` 可以显著减少 ``printf()`` 调用的堆栈使用量。 - 启用 :ref:`newlib-nano-formatting`，可以在任务调用 ``printf()`` 或其他 C 语言字符串格式化函数时，减少这类任务的栈内存使用量。 - 避免在栈上分配大型变量。在 C 语言声明的默认作用域中，任何分配为自动变量的大型结构体或数组都会占用栈内存。要优化这些变量占用的栈内存大小，可以使用静态分配，或仅在需要时从堆中动态分配。 diff --git a/docs/zh_CN/api-guides/performance/size.rst b/docs/zh_CN/api-guides/performance/size.rst index de8cd04b85..a609b638bc 100644 --- a/docs/zh_CN/api-guides/performance/size.rst +++ b/docs/zh_CN/api-guides/performance/size.rst @@ -158,9 +158,9 @@ lwIP IPv4 默认情况下，ESP-IDF 使用 Newlib C 库，同时也对 Picolibc C 库提供实验性支持。 -Picolibc C 库提供了更小的 ``printf`` 系列函数，并且根据您的应用程序，可以将二进制文件大小最多减少 30 KB。 +Picolibc C 库提供了更精简的 ``printf`` 系列函数，并且根据应用程序，可以将二进制文件大小减少最多 30 KB。 -要切换为链接到 Picolibc C 库，请启用以下配置选项：:ref:CONFIG_IDF_EXPERIMENTAL_FEATURES 和 :ref:`CONFIG_LIBC_PICOLIBC`。 +如需切换链接到 Picolibc C 库，请启用配置选项 :ref:`CONFIG_IDF_EXPERIMENTAL_FEATURES` 和 :ref:`CONFIG_LIBC_PICOLIBC`。 .. _newlib-nano-formatting: @@ -171,13 +171,13 @@ ESP-IDF 的 I/O 函数（ ``printf()`` 和 ``scanf()`` 等）默认使用 Newlib .. only:: CONFIG_ESP_ROM_HAS_NEWLIB_NANO_FORMAT - 启用配置选项 :ref:`CONFIG_LIBC_NEWLIB_NANO_FORMAT` 将使 Newlib 切换到 Nano 格式化模式。这种模式的代码量更小，并且大部分内容被编译到了 {IDF_TARGET_NAME} 的 ROM 中，因此不需要将其添加至二进制文件中。 + 启用配置选项 :ref:`CONFIG_LIBC_NEWLIB_NANO_FORMAT` 将 Newlib 切换到 Nano 格式化模式。从而减小了代码体积，同时大部分内容被编译到 {IDF_TARGET_NAME} 的 ROM 中，因此不需要将其添加至二进制文件中。 具体的二进制文件大小差异取决于固件使用的功能，但通常为 25 KB 到 50 KB。 .. only:: CONFIG_ESP_ROM_HAS_NEWLIB_NORMAL_FORMAT - 禁用配置选项 :ref:`CONFIG_LIBC_NEWLIB_NANO_FORMAT` 将切换 Newlib 到“完整”格式化模式。这将减小二进制文件的大小，因为 {IDF_TARGET_NAME} 的 ROM 中已存有完整格式化版本的函数，因此不需要将其添加至二进制文件中。 + 禁用配置选项 :ref:`CONFIG_LIBC_NEWLIB_NANO_FORMAT` 将 Newlib 切换到完整格式化模式。从而减小二进制文件的大小，因为 {IDF_TARGET_NAME} 的 ROM 中已存有完整格式化版本的函数，因此无需将其添加至二进制文件中。 启用 Nano 格式化会减少调用 ``printf()`` 或其他字符串格式化函数的堆栈使用量，参阅 :ref:`optimize-stack-sizes`。 diff --git a/docs/zh_CN/api-reference/system/system_time.rst b/docs/zh_CN/api-reference/system/system_time.rst index 9abf7a8040..f70989db5a 100644 --- a/docs/zh_CN/api-reference/system/system_time.rst +++ b/docs/zh_CN/api-reference/system/system_time.rst @@ -26,7 +26,7 @@ - 高分辨率定时器 - 无 -默认时钟源的时间精度最高，建议使用该配置。此外，用户也可以通过配置选项 :ref:`CONFIG_LIBC_TIME_SYSCALL` 来选择其他时钟源。 +默认时钟源的时间精度最高，建议使用该配置。此外，你可以通过配置选项 :ref:`CONFIG_LIBC_TIME_SYSCALL` 来选择其他时钟源。 .. _rtc-clock-source-choice: