mirror of
https://github.com/espressif/esp-idf
synced 2025-03-09 17:19:09 -04:00
docs: Review the CN translation for Picolibc
This commit is contained in:
Zhang Shuxian
BOT
parent
aae5321c4a
commit
d518d110c0
@ -19,7 +19,9 @@ Firmware Components
|
||||
|
||||
These third party libraries can be included into the application (firmware) produced by ESP-IDF.
|
||||
|
||||
* :component:`Newlib <newlib>` is licensed under the BSD License and is Copyright of various parties, as described in :component_file:`COPYING.NEWLIB <newlib/COPYING.NEWLIB>`. If :ref:`CONFIG_LIBC_PICOLIBC<CONFIG_LIBC_PICOLIBC>` is enabled, see also :component_file:`COPYING.picolibc <newlib/COPYING.picolibc>`.
|
||||
* :component:`Newlib <newlib>` is licensed under the BSD License, with copyright held by the respective parties, as described in :component_file:`COPYING.NEWLIB <newlib/COPYING.NEWLIB>`. If :ref:`CONFIG_LIBC_PICOLIBC<CONFIG_LIBC_PICOLIBC>` is enabled, see also :component_file:`COPYING.picolibc <newlib/COPYING.picolibc>`.
|
||||
|
||||
:component:`Picolibc <newlib>` is licensed under the BSD License, with copyright held by the respective parties, as described in :component_file:`COPYING.picolibc <newlib/COPYING.NEWLIB>`.
|
||||
|
||||
* :component:`Xtensa header files <xtensa/include/xtensa>` are Copyright (C) 2013 Tensilica Inc and are licensed under the MIT License as reproduced in the individual header files.
|
||||
|
||||
|
||||
@ -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
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@ -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<CONFIG_LIBC_PICOLIBC>`.
|
||||
|
||||
|
||||
@ -19,9 +19,9 @@
|
||||
|
||||
以下这些第三方库包含在 ESP-IDF 生成的应用程序（固件）中。
|
||||
|
||||
* :component:`Newlib <newlib>` 经 BSD 许可证许可，版权归各方所有，如 :component_file:`COPYING.NEWLIB <newlib/COPYING.NEWLIB>` 中所述。如果启用了 :ref:`CONFIG_LIBC_PICOLIBC<CONFIG_LIBC_PICOLIBC>`，另请参阅 :component_file:`COPYING.picolibc <newlib/COPYING.picolibc>`。
|
||||
* 如 :component_file:`COPYING.NEWLIB <newlib/COPYING.NEWLIB>` 中所述， :component:`Newlib <newlib>` 经 BSD 许可证许可，版权归各方所有。如启用了 :ref:`CONFIG_LIBC_PICOLIBC<CONFIG_LIBC_PICOLIBC>`，请参阅 :component_file:`COPYING.picolibc <newlib/COPYING.picolibc>`。
|
||||
|
||||
* :component:`Picolibc <newlib>` 经 BSD 许可证许可，版权归各方所有，如 :component_file:`COPYING.picolibc <newlib/COPYING.NEWLIB>` 中所述。
|
||||
* 如 :component_file:`COPYING.picolibc <newlib/COPYING.NEWLIB>` 中所述， :component:`Picolibc <newlib>` 经 BSD 许可证许可，版权归各方所有。
|
||||
|
||||
* :component:`Xtensa 头文件 <xtensa/include/xtensa>` 版权归 2013 Tensilica 公司所有，并根据各头文件中复制的 MIT 许可证进行许可。
|
||||
|
||||
|
||||
@ -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 <https://sourceware.org/newlib/>`_ (默认)
|
||||
- `Picolibc <https://keithp.com/picolibc/>`_ (通过 :ref:`CONFIG_LIBC_PICOLIBC<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:
|
||||
|
||||
|
||||
@ -173,7 +173,7 @@ BSD 套接字的相关参考资料十分丰富，包括但不限于：
|
||||
套接字错误原因代码
|
||||
++++++++++++++++++++++++
|
||||
|
||||
以下是常见错误代码列表。有关标准 POSIX/C 错误代码的详细列表，请参阅 `newlib errno.h <https://github.com/espressif/newlib-esp32/blob/master/newlib/libc/include/sys/errno.h>`_ 和特定平台扩展 :component_file:`newlib/platform_include/sys/errno.h`。
|
||||
以下是常见错误代码列表。获取标准 POSIX/C 错误代码的详细列表，请参阅 `newlib errno.h <https://github.com/espressif/newlib-esp32/blob/master/newlib/libc/include/sys/errno.h>`_ 和特定平台扩展 :component_file:`newlib/platform_include/sys/errno.h`。
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
@ -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 语言声明的默认作用域中，任何分配为自动变量的大型结构体或数组都会占用栈内存。要优化这些变量占用的栈内存大小，可以使用静态分配，或仅在需要时从堆中动态分配。
|
||||
|
||||
@ -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<CONFIG_LIBC_PICOLIBC>`。
|
||||
如需切换链接到 Picolibc C 库，请启用配置选项 :ref:`CONFIG_IDF_EXPERIMENTAL_FEATURES` 和 :ref:`CONFIG_LIBC_PICOLIBC<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`。
|
||||
|
||||
|
||||
@ -26,7 +26,7 @@
|
||||
- 高分辨率定时器
|
||||
- 无
|
||||
|
||||
默认时钟源的时间精度最高，建议使用该配置。此外，用户也可以通过配置选项 :ref:`CONFIG_LIBC_TIME_SYSCALL` 来选择其他时钟源。
|
||||
默认时钟源的时间精度最高，建议使用该配置。此外，你可以通过配置选项 :ref:`CONFIG_LIBC_TIME_SYSCALL` 来选择其他时钟源。
|
||||
|
||||
|
||||
.. _rtc-clock-source-choice:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user