feedc0de/esp-idf
1
0
Fork 0
forked from espressif/esp-idf
Code Pull Requests Activity

docs: Sync CN and EN files

Browse Source
This commit is contained in:
shenmengjing
2024-10-17 16:57:57 +08:00
parent 653ce935f9
commit 6f86f70f0a
10 changed files with 347 additions and 288 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
docs/en/api-guides/fatal-errors.rst
View File

@@ -32,7 +32,7 @@ This guide explains the procedure used in ESP-IDF for handling these errors, and
Panic Handler Panic Handler
------------- -------------
Every error cause listed in the `Overview`_ will be handled by the *panic handler*. Every error cause listed in the :ref:`Overview` will be handled by the *panic handler*.
The panic handler will start by printing the cause of the error to the console. For CPU exceptions, the message will be similar to The panic handler will start by printing the cause of the error to the console. For CPU exceptions, the message will be similar to
@@ -46,7 +46,7 @@ For some of the system level checks (interrupt watchdog, cache access error), th
Guru Meditation Error: Core 0 panic'ed (|CACHE_ERR_MSG|). Exception was unhandled. Guru Meditation Error: Core 0 panic'ed (|CACHE_ERR_MSG|). Exception was unhandled.
In all cases, the error cause will be printed in parentheses. See `Guru Meditation Errors`_ for a list of possible error causes. In all cases, the error cause will be printed in parentheses. See :ref:`Guru-Meditation-Errors` for a list of possible error causes.
Subsequent behavior of the panic handler can be set using :ref:`CONFIG_ESP_SYSTEM_PANIC` configuration choice. The available options are: Subsequent behavior of the panic handler can be set using :ref:`CONFIG_ESP_SYSTEM_PANIC` configuration choice. The available options are:
@@ -134,7 +134,7 @@ Unless the ``CONFIG_ESP_SYSTEM_PANIC_SILENT_REBOOT`` option is enabled, the pani
.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA .. only:: CONFIG_IDF_TARGET_ARCH_XTENSA
:: .. code-block:: none
Core 0 register dump: Core 0 register dump:
PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030 PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030
@@ -148,7 +148,7 @@ Unless the ``CONFIG_ESP_SYSTEM_PANIC_SILENT_REBOOT`` option is enabled, the pani
.. only:: CONFIG_IDF_TARGET_ARCH_RISCV .. only:: CONFIG_IDF_TARGET_ARCH_RISCV
:: .. code-block:: none
Core 0 register dump: Core 0 register dump:
MEPC : 0x420048b4 RA : 0x420048b4 SP : 0x3fc8f2f0 GP : 0x3fc8a600 MEPC : 0x420048b4 RA : 0x420048b4 SP : 0x3fc8f2f0 GP : 0x3fc8a600
@@ -176,7 +176,7 @@ If :doc:`IDF Monitor <tools/idf-monitor>` is used, Program Counter values will b
.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA .. only:: CONFIG_IDF_TARGET_ARCH_XTENSA
:: .. code-block:: none
Core 0 register dump: Core 0 register dump:
PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030 PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030
@@ -197,7 +197,7 @@ If :doc:`IDF Monitor <tools/idf-monitor>` is used, Program Counter values will b
.. only:: CONFIG_IDF_TARGET_ARCH_RISCV .. only:: CONFIG_IDF_TARGET_ARCH_RISCV
:: .. code-block:: none
Core 0 register dump: Core 0 register dump:
MEPC : 0x420048b4 RA : 0x420048b4 SP : 0x3fc8f2f0 GP : 0x3fc8a600 MEPC : 0x420048b4 RA : 0x420048b4 SP : 0x3fc8f2f0 GP : 0x3fc8a600
@@ -220,7 +220,7 @@ If :doc:`IDF Monitor <tools/idf-monitor>` is used, Program Counter values will b
Moreover, :doc:`IDF Monitor <tools/idf-monitor>` is also capable of generating and printing a backtrace thanks to the stack dump provided by the board in the panic handler. Moreover, :doc:`IDF Monitor <tools/idf-monitor>` is also capable of generating and printing a backtrace thanks to the stack dump provided by the board in the panic handler.
The output looks like this: The output looks like this:
:: .. code-block:: none
Backtrace: Backtrace:
@@ -238,7 +238,7 @@ If :doc:`IDF Monitor <tools/idf-monitor>` is used, Program Counter values will b
This option will let the compiler generate DWARF information for each function of the project. Then, when a CPU exception occurs, the panic handler will parse these data and determine the backtrace of the task that failed. The output looks like this: This option will let the compiler generate DWARF information for each function of the project. Then, when a CPU exception occurs, the panic handler will parse these data and determine the backtrace of the task that failed. The output looks like this:
:: .. code-block:: none
Backtrace: 0x42009e9a:0x3fc92120 0x42009ea6:0x3fc92120 0x42009ec2:0x3fc92130 0x42024620:0x3fc92150 0x40387d7c:0x3fc92160 0xfffffffe:0x3fc92170 Backtrace: 0x42009e9a:0x3fc92120 0x42009ea6:0x3fc92120 0x42009ec2:0x3fc92130 0x42024620:0x3fc92150 0x40387d7c:0x3fc92160 0xfffffffe:0x3fc92170
@@ -256,7 +256,9 @@ GDB Stub
If the ``CONFIG_ESP_SYSTEM_PANIC_GDBSTUB`` option is enabled, the panic handler will not reset the chip when a fatal error happens. Instead, it will start a GDB remote protocol server, commonly referred to as GDB Stub. When this happens, a GDB instance running on the host computer can be instructed to connect to the {IDF_TARGET_NAME} UART port. If the ``CONFIG_ESP_SYSTEM_PANIC_GDBSTUB`` option is enabled, the panic handler will not reset the chip when a fatal error happens. Instead, it will start a GDB remote protocol server, commonly referred to as GDB Stub. When this happens, a GDB instance running on the host computer can be instructed to connect to the {IDF_TARGET_NAME} UART port.
If :doc:`IDF Monitor <tools/idf-monitor>` is used, GDB is started automatically when a GDB Stub prompt is detected on the UART. The output looks like this:: If :doc:`IDF Monitor <tools/idf-monitor>` is used, GDB is started automatically when a GDB Stub prompt is detected on the UART. The output looks like this:
.. code-block:: none
Entering gdb stub now. Entering gdb stub now.
$T0b#e6GNU gdb (crosstool-NG crosstool-ng-1.22.0-80-gff1f415) 7.10 $T0b#e6GNU gdb (crosstool-NG crosstool-ng-1.22.0-80-gff1f415) 7.10
@@ -286,11 +288,12 @@ The GDB prompt can be used to inspect CPU registers, local and static variables,
RTC Watchdog Timeout RTC Watchdog Timeout
-------------------- --------------------
{IDF_TARGET_RTCWDT_RTC_RESET:default="Not updated", esp32="RTCWDT_RTC_RESET", esp32s2="RTCWDT_RTC_RST", esp32s3="RTCWDT_RTC_RST", esp32c3="RTCWDT_RTC_RST", esp32c2="RTCWDT_RTC_RST", esp32c6="LP_WDT_SYS", esp32h2="LP_WDT_SYS", esp32p4="LP_WDT_SYS"} {IDF_TARGET_RTCWDT_RTC_RESET:default="Not updated", esp32="RTCWDT_RTC_RESET", esp32s2="RTCWDT_RTC_RST", esp32s3="RTCWDT_RTC_RST", esp32c3="RTCWDT_RTC_RST", esp32c2="RTCWDT_RTC_RST", esp32c6="LP_WDT_SYS", esp32h2="LP_WDT_SYS", esp32p4="LP_WDT_SYS"}
The RTC watchdog is used in the startup code to keep track of execution time and it also helps to prevent a lock-up caused by an unstable power source. It is enabled by default (see :ref:`CONFIG_BOOTLOADER_WDT_ENABLE`). If the execution time is exceeded, the RTC watchdog will restart the system. In this case, the first stage (ROM) bootloader will print a message with the ``RTC Watchdog Timeout`` reason for the reboot. The RTC watchdog is used in the startup code to keep track of execution time and it also helps to prevent a lock-up caused by an unstable power source. It is enabled by default (see :ref:`CONFIG_BOOTLOADER_WDT_ENABLE`). If the execution time is exceeded, the RTC watchdog will restart the system. In this case, the first stage (ROM) bootloader will print a message with the ``RTC Watchdog Timeout`` reason for the reboot.
:: .. code-block:: none
rst:0x10 ({IDF_TARGET_RTCWDT_RTC_RESET}) rst:0x10 ({IDF_TARGET_RTCWDT_RTC_RESET})
@@ -424,7 +427,9 @@ Other Fatal Errors
{IDF_TARGET_NAME} has a built-in brownout detector, which is enabled by default. The brownout detector can trigger a system reset if the supply voltage goes below a safe level. The brownout detector can be configured using :ref:`CONFIG_ESP_BROWNOUT_DET` and :ref:`CONFIG_ESP_BROWNOUT_DET_LVL_SEL` options. {IDF_TARGET_NAME} has a built-in brownout detector, which is enabled by default. The brownout detector can trigger a system reset if the supply voltage goes below a safe level. The brownout detector can be configured using :ref:`CONFIG_ESP_BROWNOUT_DET` and :ref:`CONFIG_ESP_BROWNOUT_DET_LVL_SEL` options.
When the brownout detector triggers, the following message is printed:: When the brownout detector triggers, the following message is printed:
.. code-block:: none
Brownout detector was triggered Brownout detector was triggered
@@ -436,7 +441,9 @@ Other Fatal Errors
Corrupt Heap Corrupt Heap
^^^^^^^^^^^^ ^^^^^^^^^^^^
ESP-IDF's heap implementation contains a number of run-time checks of the heap structure. Additional checks ("Heap Poisoning") can be enabled in menuconfig. If one of the checks fails, a message similar to the following will be printed:: ESP-IDF's heap implementation contains a number of run-time checks of the heap structure. Additional checks ("Heap Poisoning") can be enabled in menuconfig. If one of the checks fails, a message similar to the following will be printed:
.. code-block:: none
CORRUPT HEAP: Bad tail at 0x3ffe270a. Expected 0xbaad5678 got 0xbaac5678 CORRUPT HEAP: Bad tail at 0x3ffe270a. Expected 0xbaad5678 got 0xbaac5678
assertion "head != NULL" failed: file "/Users/user/esp/esp-idf/components/heap/multi_heap_poisoning.c", line 201, function: multi_heap_free assertion "head != NULL" failed: file "/Users/user/esp/esp-idf/components/heap/multi_heap_poisoning.c", line 201, function: multi_heap_free
@@ -480,19 +487,20 @@ ESP-IDF provides a custom FreeRTOS stack overflow detecting mechanism based on w
Generally, this may cause the watchpoint to be triggered up to 28 bytes earlier than expected. The value 32 is chosen because it is larger than the stack canary size in FreeRTOS (20 bytes). Adopting this approach ensures that the watchpoint triggers before the stack canary is corrupted, not after. Generally, this may cause the watchpoint to be triggered up to 28 bytes earlier than expected. The value 32 is chosen because it is larger than the stack canary size in FreeRTOS (20 bytes). Adopting this approach ensures that the watchpoint triggers before the stack canary is corrupted, not after.
.. note:: .. note::
Not every stack overflow is guaranteed to trigger the watchpoint. It is possible that the task writes to memory beyond the stack canary location, in which case the watchpoint will not be triggered. Not every stack overflow is guaranteed to trigger the watchpoint. It is possible that the task writes to memory beyond the stack canary location, in which case the watchpoint will not be triggered.
If watchpoint triggers, the message will be similar to: If watchpoint triggers, the message will be similar to:
.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA .. only:: CONFIG_IDF_TARGET_ARCH_XTENSA
:: .. code-block:: none
Debug exception reason: Stack canary watchpoint triggered (task_name) Debug exception reason: Stack canary watchpoint triggered (task_name)
.. only:: CONFIG_IDF_TARGET_ARCH_RISCV .. only:: CONFIG_IDF_TARGET_ARCH_RISCV
:: .. code-block:: none
Guru Meditation Error: Core 0 panic'ed (Breakpoint). Exception was unhandled. Guru Meditation Error: Core 0 panic'ed (Breakpoint). Exception was unhandled.
@@ -507,7 +515,9 @@ See :ref:`CONFIG_FREERTOS_CHECK_STACKOVERFLOW`
Stack Smashing Stack Smashing
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
Stack smashing protection (based on GCC ``-fstack-protector*`` flags) can be enabled in ESP-IDF using :ref:`CONFIG_COMPILER_STACK_CHECK_MODE` option. If stack smashing is detected, message similar to the following will be printed:: Stack smashing protection (based on GCC ``-fstack-protector*`` flags) can be enabled in ESP-IDF using :ref:`CONFIG_COMPILER_STACK_CHECK_MODE` option. If stack smashing is detected, message similar to the following will be printed:
.. code-block:: none
Stack smashing protect failure! Stack smashing protect failure!
@@ -537,9 +547,10 @@ The backtrace should point to the function where stack smashing has occurred. Ch
CPU Lockup CPU Lockup
^^^^^^^^^^ ^^^^^^^^^^
A CPU lockup reset happens when there is a double exception, i.e. when an exception occurs while the CPU is already in an exception handler. The most common cause for this is when the cache is in such a state that accessing external memory not possible. If this is the case then the panic handler will crash as well due to being unable to fetch instructions or read data.
If this is the case you can try placing the panic handler code in IRAM, which can be accessed when cache is disabled, to get more information about the cause of the lockup. This can be done with :ref:`CONFIG_ESP_PANIC_HANDLER_IRAM`. A CPU lockup reset happens when there is a double exception, i.e. when an exception occurs while the CPU is already in an exception handler. The most common cause for this is when the cache is in a state where accessing external memory becomes impossible. In such cases, the panic handler will crash as well due to being unable to fetch instructions or read data.
To gather more information about the cause of the lockup, you can try placing the panic handler code in IRAM, which remains accessible even when the cache is disabled. This can be done with :ref:`CONFIG_ESP_PANIC_HANDLER_IRAM`.
Undefined Behavior Sanitizer (UBSAN) Checks Undefined Behavior Sanitizer (UBSAN) Checks
@@ -560,7 +571,9 @@ UBSAN is disabled by default. It can be enabled at file, component, or project l
When enabling UBSAN for code which uses the SOC hardware register header files (``soc/xxx_reg.h``), it is recommended to disable shift-base sanitizer using ``-fno-sanitize=shift-base`` option. This is due to the fact that ESP-IDF register header files currently contain patterns which cause false positives for this specific sanitizer option. When enabling UBSAN for code which uses the SOC hardware register header files (``soc/xxx_reg.h``), it is recommended to disable shift-base sanitizer using ``-fno-sanitize=shift-base`` option. This is due to the fact that ESP-IDF register header files currently contain patterns which cause false positives for this specific sanitizer option.
To enable UBSAN at project level, add the following code at the end of the project's ``CMakeLists.txt`` file:: To enable UBSAN at project level, add the following code at the end of the project's ``CMakeLists.txt`` file:
.. code-block:: none
idf_build_set_property(COMPILE_OPTIONS "-fsanitize=undefined" "-fno-sanitize=shift-base" APPEND) idf_build_set_property(COMPILE_OPTIONS "-fsanitize=undefined" "-fno-sanitize=shift-base" APPEND)
@@ -568,7 +581,9 @@ Alternatively, pass these options through the ``EXTRA_CFLAGS`` and ``EXTRA_CXXFL
Enabling UBSAN results in significant increase of code and data size. Most applications, except for the trivial ones, will not fit into the available RAM of the microcontroller when UBSAN is enabled for the whole application. Therefore it is recommended that UBSAN is instead enabled for specific components under test. Enabling UBSAN results in significant increase of code and data size. Most applications, except for the trivial ones, will not fit into the available RAM of the microcontroller when UBSAN is enabled for the whole application. Therefore it is recommended that UBSAN is instead enabled for specific components under test.
To enable UBSAN for a specific component (``component_name``) from the project's ``CMakeLists.txt`` file, add the following code at the end of the file:: To enable UBSAN for a specific component (``component_name``) from the project's ``CMakeLists.txt`` file, add the following code at the end of the file:
.. code-block:: none
idf_component_get_property(lib component_name COMPONENT_LIB) idf_component_get_property(lib component_name COMPONENT_LIB)
target_compile_options(${lib} PRIVATE "-fsanitize=undefined" "-fno-sanitize=shift-base") target_compile_options(${lib} PRIVATE "-fsanitize=undefined" "-fno-sanitize=shift-base")
@@ -577,20 +592,26 @@ To enable UBSAN for a specific component (``component_name``) from the project's
See the build system documentation for more information about :ref:`build properties <cmake-build-properties>` and :ref:`component properties <cmake-component-properties>`. See the build system documentation for more information about :ref:`build properties <cmake-build-properties>` and :ref:`component properties <cmake-component-properties>`.
To enable UBSAN for a specific component (``component_name``) from ``CMakeLists.txt`` of the same component, add the following at the end of the file:: To enable UBSAN for a specific component (``component_name``) from ``CMakeLists.txt`` of the same component, add the following at the end of the file:
.. code-block:: none
target_compile_options(${COMPONENT_LIB} PRIVATE "-fsanitize=undefined" "-fno-sanitize=shift-base") target_compile_options(${COMPONENT_LIB} PRIVATE "-fsanitize=undefined" "-fno-sanitize=shift-base")
UBSAN Output UBSAN Output
"""""""""""" """"""""""""
When UBSAN detects an error, a message and the backtrace are printed, for example:: When UBSAN detects an error, a message and the backtrace are printed, for example:
.. code-block:: none
Undefined behavior of type out_of_bounds Undefined behavior of type out_of_bounds
Backtrace:0x4008b383:0x3ffcd8b0 0x4008c791:0x3ffcd8d0 0x4008c587:0x3ffcd8f0 0x4008c6be:0x3ffcd950 0x400db74f:0x3ffcd970 0x400db99c:0x3ffcd9a0 Backtrace:0x4008b383:0x3ffcd8b0 0x4008c791:0x3ffcd8d0 0x4008c587:0x3ffcd8f0 0x4008c6be:0x3ffcd950 0x400db74f:0x3ffcd970 0x400db99c:0x3ffcd9a0
When using :doc:`IDF Monitor <tools/idf-monitor>`, the backtrace will be decoded to function names and source code locations, pointing to the location where the issue has happened (here it is ``main.c:128``):: When using :doc:`IDF Monitor <tools/idf-monitor>`, the backtrace will be decoded to function names and source code locations, pointing to the location where the issue has happened (here it is ``main.c:128``):
.. code-block:: none
0x4008b383: panic_abort at /path/to/esp-idf/components/esp_system/panic.c:367 0x4008b383: panic_abort at /path/to/esp-idf/components/esp_system/panic.c:367

8
docs/en/api-reference/network/esp_now.rst
View File

@@ -15,10 +15,12 @@ Frame Format
ESP-NOW uses a vendor-specific action frame to transmit ESP-NOW data. The default ESP-NOW bit rate is 1 Mbps. ESP-NOW uses a vendor-specific action frame to transmit ESP-NOW data. The default ESP-NOW bit rate is 1 Mbps.
Currently, ESP-NOW supports two versions: v1.0 and v2.0. The maximum packet length supported by v2.0 devices is ESP_NOW_MAX_DATA_LEN_V2 bytes, while the maximum packet length supported by v1.0 devices is ESP_NOW_MAX_DATA_LEN bytes. Currently, ESP-NOW supports two versions: v1.0 and v2.0. The maximum packet length supported by v2.0 devices is 1490 (``ESP_NOW_MAX_DATA_LEN_V2``) bytes, while the maximum packet length supported by v1.0 devices is 250 (``ESP_NOW_MAX_DATA_LEN``) bytes.
The v2.0 devices are capable of receiving packets from both v2.0 and v1.0 devices. In contrast, v1.0 devices can only receive packets from other v1.0 devices. The v2.0 devices are capable of receiving packets from both v2.0 and v1.0 devices. In contrast, v1.0 devices can only receive packets from other v1.0 devices.
However, v1.0 devices can receive v2.0 packets if the packet length is less than or equal to ESP_NOW_MAX_IE_DATA_LEN.
For packets exceeding this length, the v1.0 devices will either truncate the data to the first ESP_NOW_MAX_IE_DATA_LEN bytes or discard the packet entirely. However, v1.0 devices can receive v2.0 packets if the packet length is less than or equal to 250 (``ESP_NOW_MAX_IE_DATA_LEN``).For packets exceeding this length, the v1.0 devices will either truncate the data to the first 250 (``ESP_NOW_MAX_IE_DATA_LEN``) bytes or discard the packet entirely.
For detailed behavior, please refer to the documentation corresponding to the specific IDF version. For detailed behavior, please refer to the documentation corresponding to the specific IDF version.
The format of the vendor-specific action frame is as follows: The format of the vendor-specific action frame is as follows:

1
docs/en/api-reference/protocols/modbus.rst
View File

@@ -1,5 +1,6 @@
ESP-Modbus ESP-Modbus
========== ==========
:link_to_translation:`zh_CN:[中文]` :link_to_translation:`zh_CN:[中文]`
The Espressif ESP-Modbus Library (esp-modbus) supports Modbus communication in the networks based on RS485, Wi-Fi, and Ethernet interfaces. The Espressif ESP-Modbus Library (esp-modbus) supports Modbus communication in the networks based on RS485, Wi-Fi, and Ethernet interfaces.

12
docs/en/security/secure-boot-v2.rst
View File

@@ -467,7 +467,7 @@ Ideally, it is strongly recommended that all such keys must been burned before e
.. note:: .. note::
If :doc:`/security/flash-encryption` is enabled by the 2nd stage bootloader at the time of enabling Secure Boot, it ensures that the flash encryption key generated on the first boot shall already be read-protected. If :doc:`/security/flash-encryption` is enabled by the second stage bootloader at the time of enabling Secure Boot, it ensures that the flash encryption key generated on the first boot shall already be read-protected.
.. _secure-boot-v2-generate-key: .. _secure-boot-v2-generate-key:
@@ -600,7 +600,7 @@ Secure Boot Best Practices
* The bootloader should be signed with all the private key(s) that are needed for the life of the device, before it is flashed. * The bootloader should be signed with all the private key(s) that are needed for the life of the device, before it is flashed.
* The build system can sign with at most one private key, user has to run manual commands to append more signatures if necessary. * The build system can sign with at most one private key, user has to run manual commands to append more signatures if necessary.
* You can use the append functionality of ``idf.py secure-sign-data``, this command would also printed at the end of the Secure Boot V2 enabled bootloader compilation. * You can use the append functionality of ``idf.py secure-sign-data``, this command would also printed at the end of the Secure Boot v2 enabled bootloader compilation.
.. code-block:: .. code-block::
@@ -674,12 +674,12 @@ Secure Boot is integrated into the ESP-IDF build system, so ``idf.py build`` wil
However, it is possible to use the ``idf.py`` or the ``openssl`` tool to generate standalone signatures and verify them. Using ``idf.py`` is recommended, but in case you need to generate or verify signatures in non-ESP-IDF environments, you could also use the ``openssl`` commands as the Secure Boot v2 signature generation is compliant with the standard signing algorithms. However, it is possible to use the ``idf.py`` or the ``openssl`` tool to generate standalone signatures and verify them. Using ``idf.py`` is recommended, but in case you need to generate or verify signatures in non-ESP-IDF environments, you could also use the ``openssl`` commands as the Secure Boot v2 signature generation is compliant with the standard signing algorithms.
Generating and Verifying signatures using ``idf.py`` Generating and Verifying Signatures Using ``idf.py``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. To sign a binary image: 1. To sign a binary image:
.. code-block:: .. code-block::
idf.py secure-sign-data --keyfile ./my_signing_key.pem --output ./image_signed.bin image-unsigned.bin idf.py secure-sign-data --keyfile ./my_signing_key.pem --output ./image_signed.bin image-unsigned.bin
@@ -687,11 +687,11 @@ Keyfile is the PEM file containing an {IDF_TARGET_SBV2_KEY} private signing key.
2. To verify a signed binary image: 2. To verify a signed binary image:
.. code-block:: .. code-block::
idf.py secure-verify-signature --keyfile ./my_signing_key.pem image_signed.bin idf.py secure-verify-signature --keyfile ./my_signing_key.pem image_signed.bin
Keyfile is the PEM file containing an {IDF_TARGET_SBV2_KEY} public/\private signing key. Keyfile is the PEM file containing an {IDF_TARGET_SBV2_KEY} public/private signing key.
Generating and Verifying signatures using OpenSSL Generating and Verifying signatures using OpenSSL
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

99
docs/zh_CN/api-guides/fatal-errors.rst
View File

@@ -50,19 +50,19 @@
紧急处理程序接下来的行为将取决于 :ref:`CONFIG_ESP_SYSTEM_PANIC` 的设置，支持的选项包括： 紧急处理程序接下来的行为将取决于 :ref:`CONFIG_ESP_SYSTEM_PANIC` 的设置，支持的选项包括：
- 打印 CPU 寄存器，然后重启（``CONFIG_ESP_SYSTEM_PANIC_PRINT_REBOOT``）- 默认选项 - 打印 CPU 寄存器，然后重启 (``CONFIG_ESP_SYSTEM_PANIC_PRINT_REBOOT``) - 默认选项
打印系统发生异常时 CPU 寄存器的值，打印回溯，最后重启芯片。 打印系统发生异常时 CPU 寄存器的值，打印回溯，最后重启芯片。
- 打印 CPU 寄存器，然后暂停（``CONFIG_ESP_SYSTEM_PANIC_PRINT_HALT``） - 打印 CPU 寄存器，然后暂停 (``CONFIG_ESP_SYSTEM_PANIC_PRINT_HALT``)
与上一个选项类似，但不会重启，而是选择暂停程序的运行。重启程序需要外部执行复位操作。 与上一个选项类似，但不会重启，而是选择暂停程序的运行。重启程序需要外部执行复位操作。
- 静默重启（``CONFIG_ESP_SYSTEM_PANIC_SILENT_REBOOT``） - 静默重启 (``CONFIG_ESP_SYSTEM_PANIC_SILENT_REBOOT``)
不打印 CPU 寄存器的值，也不打印回溯，立即重启芯片。 不打印 CPU 寄存器的值，也不打印回溯，立即重启芯片。
- 调用 GDB Stub（``CONFIG_ESP_SYSTEM_PANIC_GDBSTUB``） - 调用 GDB Stub (``CONFIG_ESP_SYSTEM_PANIC_GDBSTUB``)
启动 GDB 服务器，通过控制台 UART 接口与 GDB 进行通信。该选项只提供只读调试或者事后调试，详细信息请参阅 `GDB Stub`_。 启动 GDB 服务器，通过控制台 UART 接口与 GDB 进行通信。该选项只提供只读调试或者事后调试，详细信息请参阅 `GDB Stub`_。
@@ -134,7 +134,7 @@
.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA .. only:: CONFIG_IDF_TARGET_ARCH_XTENSA
:: .. code-block:: none
Core 0 register dump: Core 0 register dump:
PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030 PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030
@@ -148,7 +148,7 @@
.. only:: CONFIG_IDF_TARGET_ARCH_RISCV .. only:: CONFIG_IDF_TARGET_ARCH_RISCV
:: .. code-block:: none
Core 0 register dump: Core 0 register dump:
MEPC : 0x420048b4 RA : 0x420048b4 SP : 0x3fc8f2f0 GP : 0x3fc8a600 MEPC : 0x420048b4 RA : 0x420048b4 SP : 0x3fc8f2f0 GP : 0x3fc8a600
@@ -176,7 +176,7 @@
.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA .. only:: CONFIG_IDF_TARGET_ARCH_XTENSA
:: .. code-block:: none
Core 0 register dump: Core 0 register dump:
PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030 PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030
@@ -197,7 +197,7 @@
.. only:: CONFIG_IDF_TARGET_ARCH_RISCV .. only:: CONFIG_IDF_TARGET_ARCH_RISCV
:: .. code-block:: none
Core 0 register dump: Core 0 register dump:
MEPC : 0x420048b4 RA : 0x420048b4 SP : 0x3fc8f2f0 GP : 0x3fc8a600 MEPC : 0x420048b4 RA : 0x420048b4 SP : 0x3fc8f2f0 GP : 0x3fc8a600
@@ -220,7 +220,7 @@
此外，由于紧急处理程序中提供了堆栈转储，因此 :doc:`IDF 监视器 <tools/idf-monitor>` 也可以生成并打印回溯。 此外，由于紧急处理程序中提供了堆栈转储，因此 :doc:`IDF 监视器 <tools/idf-monitor>` 也可以生成并打印回溯。
输出结果如下： 输出结果如下：
:: .. code-block:: none
Backtrace: Backtrace:
@@ -238,7 +238,7 @@
该选项会让编译器为项目的每个函数生成 DWARF 信息。然后，当 CPU 异常发生时，紧急处理程序将解析这些数据并生成出错任务的堆栈回溯信息。输出结果如下： 该选项会让编译器为项目的每个函数生成 DWARF 信息。然后，当 CPU 异常发生时，紧急处理程序将解析这些数据并生成出错任务的堆栈回溯信息。输出结果如下：
:: .. code-block:: none
Backtrace: 0x42009e9a:0x3fc92120 0x42009ea6:0x3fc92120 0x42009ec2:0x3fc92130 0x42024620:0x3fc92150 0x40387d7c:0x3fc92160 0xfffffffe:0x3fc92170 Backtrace: 0x42009e9a:0x3fc92120 0x42009ea6:0x3fc92120 0x42009ec2:0x3fc92130 0x42024620:0x3fc92150 0x40387d7c:0x3fc92160 0xfffffffe:0x3fc92170
@@ -256,7 +256,9 @@ GDB Stub
如果启用了 ``CONFIG_ESP_SYSTEM_PANIC_GDBSTUB`` 选项，在发生严重错误时，紧急处理程序不会复位芯片，相反，它将启动 GDB 远程协议服务器，通常称为 GDB Stub。发生这种情况时，可以让主机上运行的 GDB 实例通过 UART 端口连接到 ESP32。 如果启用了 ``CONFIG_ESP_SYSTEM_PANIC_GDBSTUB`` 选项，在发生严重错误时，紧急处理程序不会复位芯片，相反，它将启动 GDB 远程协议服务器，通常称为 GDB Stub。发生这种情况时，可以让主机上运行的 GDB 实例通过 UART 端口连接到 ESP32。
如果使用了 :doc:`IDF 监视器 <tools/idf-monitor>`，该工具会在 UART 端口检测到 GDB Stub 提示符后自动启动 GDB，输出会类似于:: 如果使用了 :doc:`IDF 监视器 <tools/idf-monitor>`，该工具会在 UART 端口检测到 GDB Stub 提示符后自动启动 GDB，输出会类似于：
.. code-block:: none
Entering gdb stub now. Entering gdb stub now.
$T0b#e6GNU gdb (crosstool-NG crosstool-ng-1.22.0-80-gff1f415) 7.10 $T0b#e6GNU gdb (crosstool-NG crosstool-ng-1.22.0-80-gff1f415) 7.10
@@ -286,11 +288,12 @@ GDB Stub
RTC 看门狗超时 RTC 看门狗超时
---------------- ----------------
{IDF_TARGET_RTCWDT_RTC_RESET:default="Not updated", esp32="RTCWDT_RTC_RESET", esp32s2="RTCWDT_RTC_RST", esp32s3="RTCWDT_RTC_RST", esp32c3="RTCWDT_RTC_RST", esp32c2="RTCWDT_RTC_RST", esp32c6="LP_WDT_SYS", esp32h2="LP_WDT_SYS", esp32p4="LP_WDT_SYS"}
{IDF_TARGET_RTCWDT_RTC_RESET:default="未更新", esp32="RTCWDT_RTC_RESET", esp32s2="RTCWDT_RTC_RST", esp32s3="RTCWDT_RTC_RST", esp32c3="RTCWDT_RTC_RST", esp32c2="RTCWDT_RTC_RST", esp32c6="LP_WDT_SYS", esp32h2="LP_WDT_SYS", esp32p4="LP_WDT_SYS"}
RTC 看门狗在启动代码中用于跟踪执行时间，也有助于防止由于电源不稳定引起的锁定。RTC 看门狗默认启用，参见 :ref:`CONFIG_BOOTLOADER_WDT_ENABLE`。如果执行时间超时，RTC 看门狗将自动重启系统。此时，一级 (ROM) 引导加载程序将打印消息 ``RTC Watchdog Timeout`` 说明重启原因。 RTC 看门狗在启动代码中用于跟踪执行时间，也有助于防止由于电源不稳定引起的锁定。RTC 看门狗默认启用，参见 :ref:`CONFIG_BOOTLOADER_WDT_ENABLE`。如果执行时间超时，RTC 看门狗将自动重启系统。此时，一级 (ROM) 引导加载程序将打印消息 ``RTC Watchdog Timeout`` 说明重启原因。
:: .. code-block:: none
rst:0x10 ({IDF_TARGET_RTCWDT_RTC_RESET}) rst:0x10 ({IDF_TARGET_RTCWDT_RTC_RESET})
@@ -402,8 +405,8 @@ Interrupt wdt timeout on CPU0 / CPU1
.. only:: SOC_MEMPROT_SUPPORTED .. only:: SOC_MEMPROT_SUPPORTED
内存保护错误 Memory Protection Fault
^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^
ESP-IDF 中使用 {IDF_TARGET_NAME} 的权限控制功能来防止以下类型的内存访问： ESP-IDF 中使用 {IDF_TARGET_NAME} 的权限控制功能来防止以下类型的内存访问：
@@ -424,7 +427,9 @@ Interrupt wdt timeout on CPU0 / CPU1
{IDF_TARGET_NAME} 内部集成掉电检测电路，并且会默认启用。如果电源电压低于安全值，掉电检测器可以触发系统复位。掉电检测器可以使用 :ref:`CONFIG_ESP_BROWNOUT_DET` 和 :ref:`CONFIG_ESP_BROWNOUT_DET_LVL_SEL` 这两个选项进行设置。 {IDF_TARGET_NAME} 内部集成掉电检测电路，并且会默认启用。如果电源电压低于安全值，掉电检测器可以触发系统复位。掉电检测器可以使用 :ref:`CONFIG_ESP_BROWNOUT_DET` 和 :ref:`CONFIG_ESP_BROWNOUT_DET_LVL_SEL` 这两个选项进行设置。
当掉电检测器被触发时，会打印如下信息:: 当掉电检测器被触发时，会打印如下信息：
.. code-block:: none
Brownout detector was triggered Brownout detector was triggered
@@ -434,9 +439,11 @@ Interrupt wdt timeout on CPU0 / CPU1
堆不完整 堆不完整
^^^^^^^^^^^ ^^^^^^^^
ESP-IDF 堆的实现包含许多运行时的堆结构检查，可以在 menuconfig 中开启额外的检查（“Heap Poisoning”）。如果其中的某项检查失败，则会打印类似如下信息:: ESP-IDF 堆的实现包含许多运行时的堆结构检查，可以在 menuconfig 中开启额外的检查（“Heap Poisoning”）。如果其中的某项检查失败，则会打印类似如下信息：
.. code-block:: none
CORRUPT HEAP: Bad tail at 0x3ffe270a. Expected 0xbaad5678 got 0xbaac5678 CORRUPT HEAP: Bad tail at 0x3ffe270a. Expected 0xbaad5678 got 0xbaac5678
assertion "head != NULL" failed: file "/Users/user/esp/esp-idf/components/heap/multi_heap_poisoning.c", line 201, function: multi_heap_free assertion "head != NULL" failed: file "/Users/user/esp/esp-idf/components/heap/multi_heap_poisoning.c", line 201, function: multi_heap_free
@@ -452,7 +459,7 @@ ESP-IDF 堆的实现包含许多运行时的堆结构检查，可以在 menuconf
.. _Hardware-Stack-Guard: .. _Hardware-Stack-Guard:
硬件堆栈保护 硬件堆栈保护
"""""""""""""""""""" """"""""""""
{IDF_TARGET_NAME} 集成了辅助调试模块，支持监测堆栈指针 (SP) 寄存器，确保其值位于已分配给堆栈的内存范围内。发生中断处理或 FreeRTOS 切换上下文时，辅助调试模块都会设置新的堆栈监测范围。注意，该操作会对性能产生一定影响。 {IDF_TARGET_NAME} 集成了辅助调试模块，支持监测堆栈指针 (SP) 寄存器，确保其值位于已分配给堆栈的内存范围内。发生中断处理或 FreeRTOS 切换上下文时，辅助调试模块都会设置新的堆栈监测范围。注意，该操作会对性能产生一定影响。
@@ -473,26 +480,27 @@ ESP-IDF 堆的实现包含许多运行时的堆结构检查，可以在 menuconf
.. _FreeRTOS-End-Of-Stack-Watchpoint: .. _FreeRTOS-End-Of-Stack-Watchpoint:
FreeRTOS 任务堆栈末尾监视点 FreeRTOS 任务堆栈末尾监视点
"""""""""""""""""""""""""""""""" """""""""""""""""""""""""""
ESP-IDF 支持基于监视点的 FreeRTOS 堆栈溢出检测机制。每次 FreeRTOS 切换任务上下文时，都会设置一个监视点，用于监视堆栈的最后 32 字节。 ESP-IDF 支持基于监视点的 FreeRTOS 堆栈溢出检测机制。每次 FreeRTOS 切换任务上下文时，都会设置一个监视点，用于监视堆栈的最后 32 字节。
通常，该设置会提前触发监视点，触发点可能会比预期提前多达 28 字节。基于 FreeRTOS 中堆栈金丝雀的大小为 20 字节，故将观察范围设置为 32 字节，确保可以在堆栈金丝雀遭到破坏前及时触发监测点。 通常，该设置会提前触发监视点，触发点可能会比预期提前多达 28 字节。基于 FreeRTOS 中堆栈金丝雀的大小为 20 字节，故将观察范围设置为 32 字节，确保可以在堆栈金丝雀遭到破坏前及时触发监测点。
.. note:: .. note::
并非每次堆栈溢出都能触发监视点。如果任务绕过堆栈金丝雀的位置访问堆栈，则无法触发监视点。 并非每次堆栈溢出都能触发监视点。如果任务绕过堆栈金丝雀的位置访问堆栈，则无法触发监视点。
监视点触发后，将打印类似如下信息： 监视点触发后，将打印类似如下信息：
.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA .. only:: CONFIG_IDF_TARGET_ARCH_XTENSA
:: .. code-block:: none
Debug exception reason: Stack canary watchpoint triggered (task_name) Debug exception reason: Stack canary watchpoint triggered (task_name)
.. only:: CONFIG_IDF_TARGET_ARCH_RISCV .. only:: CONFIG_IDF_TARGET_ARCH_RISCV
:: .. code-block:: none
Guru Meditation Error: Core 0 panic'ed (Breakpoint). Exception was unhandled. Guru Meditation Error: Core 0 panic'ed (Breakpoint). Exception was unhandled.
@@ -500,14 +508,16 @@ ESP-IDF 支持基于监视点的 FreeRTOS 堆栈溢出检测机制。每次 Free
FreeRTOS 堆栈检查 FreeRTOS 堆栈检查
""""""""""""""""""""" """""""""""""""""
请参见 :ref:`CONFIG_FREERTOS_CHECK_STACKOVERFLOW`。 请参见 :ref:`CONFIG_FREERTOS_CHECK_STACKOVERFLOW`。
堆栈粉碎 堆栈粉碎
^^^^^^^^^^ ^^^^^^^^
堆栈粉碎保护（基于 GCC ``-fstack-protector*`` 标志）可以通过 ESP-IDF 中的 :ref:`CONFIG_COMPILER_STACK_CHECK_MODE` 选项来开启。如果检测到堆栈粉碎，则会打印类似如下的信息:: 堆栈粉碎保护（基于 GCC ``-fstack-protector*`` 标志）可以通过 ESP-IDF 中的 :ref:`CONFIG_COMPILER_STACK_CHECK_MODE` 选项来开启。如果检测到堆栈粉碎，则会打印类似如下的信息：
.. code-block:: none
Stack smashing protect failure! Stack smashing protect failure!
@@ -532,8 +542,19 @@ FreeRTOS 堆栈检查
.. |CACHE_ERR_MSG| replace:: Cache error .. |CACHE_ERR_MSG| replace:: Cache error
.. |STACK_OVERFLOW| replace:: 堆栈溢出 .. |STACK_OVERFLOW| replace:: 堆栈溢出
.. only:: SOC_CPU_HAS_LOCKUP_RESET
CPU 锁死
^^^^^^^^
若出现双重异常，即当 CPU 已经在异常处理程序中时，又出现了其他异常，则 CPU 会锁死，并触发系统复位。当 cache 出现问题，导致 CPU 无法访问外部存储时，CPU 就会进入锁死状态。此时，紧急处理程序也会因为无法获取指令或读取数据而崩溃。
通过配置选项 :ref:`CONFIG_ESP_PANIC_HANDLER_IRAM`，可以将紧急处理程序的代码放在 IRAM 中，这样即使 cache 被禁用也可以访问 IRAM，从而获取更多关于锁死原因的信息。
未定义行为清理器 (UBSAN) 检查 未定义行为清理器 (UBSAN) 检查
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
未定义行为清理器 (UBSAN) 是一种编译器功能，它会为可能不正确的操作添加运行时检查，例如： 未定义行为清理器 (UBSAN) 是一种编译器功能，它会为可能不正确的操作添加运行时检查，例如：
@@ -544,13 +565,15 @@ FreeRTOS 堆栈检查
请参考 `GCC 文档 <https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html>`_ 中的 ``-fsanitize=undefined`` 选项，查看支持检查的完整列表。 请参考 `GCC 文档 <https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html>`_ 中的 ``-fsanitize=undefined`` 选项，查看支持检查的完整列表。
使能 UBSAN 使能 UBSAN
"""""""""""""" """"""""""
默认情况下未启用 UBSAN。可以通过在构建系统中添加编译器选项 ``-fsanitize=undefined`` 在文件、组件或项目级别上使能 UBSAN。 默认情况下未启用 UBSAN。可以通过在构建系统中添加编译器选项 ``-fsanitize=undefined`` 在文件、组件或项目级别上使能 UBSAN。
在对使用 SoC 硬件寄存器头文件（``soc/xxx_reg.h``）的代码使能 UBSAN 时，建议使用 ``-fno-sanitize=shift-base`` 选项禁用移位基数清理器。这是由于 ESP-IDF 寄存器头文件目前包含的模式会对这个特定的清理器选项造成误报。 在对使用 SoC 硬件寄存器头文件（``soc/xxx_reg.h``）的代码使能 UBSAN 时，建议使用 ``-fno-sanitize=shift-base`` 选项禁用移位基数清理器。这是由于 ESP-IDF 寄存器头文件目前包含的模式会对这个特定的清理器选项造成误报。
要在项目级使能 UBSAN，请在项目 CMakeLists.txt 文件的末尾添加以下内容:: 要在项目级使能 UBSAN，请在项目 CMakeLists.txt 文件的末尾添加以下内容：
.. code-block:: none
idf_build_set_property(COMPILE_OPTIONS "-fsanitize=undefined" "-fno-sanitize=shift-base" APPEND) idf_build_set_property(COMPILE_OPTIONS "-fsanitize=undefined" "-fno-sanitize=shift-base" APPEND)
@@ -558,29 +581,37 @@ FreeRTOS 堆栈检查
使能 UBSAN 会明显增加代码量和数据大小。当为整个应用程序使能 UBSAN 时，微控制器的可用 RAM 无法容纳大多数应用程序（除了一些微小程序）。因此，建议为特定的待测组件使能 UBSAN。 使能 UBSAN 会明显增加代码量和数据大小。当为整个应用程序使能 UBSAN 时，微控制器的可用 RAM 无法容纳大多数应用程序（除了一些微小程序）。因此，建议为特定的待测组件使能 UBSAN。
要为项目 CMakeLists.txt 文件中的特定组件（``component_name``）启用 UBSAN，请在文件末尾添加以下内容:: 要为项目 CMakeLists.txt 文件中的特定组件（``component_name``）启用 UBSAN，请在文件末尾添加以下内容：
.. code-block:: none
idf_component_get_property(lib component_name COMPONENT_LIB) idf_component_get_property(lib component_name COMPONENT_LIB)
target_compile_options(${lib} PRIVATE "-fsanitize=undefined" "-fno-sanitize=shift-base") target_compile_options(${lib} PRIVATE "-fsanitize=undefined" "-fno-sanitize=shift-base")
.. 注意:: .. note::
关于 :ref:`构建属性 <cmake-build-properties>` 和 :ref:`组件属性 <cmake-component-properties>` 的更多信息，请查看构建系统文档。 关于 :ref:`构建属性 <cmake-build-properties>` 和 :ref:`组件属性 <cmake-component-properties>` 的更多信息，请查看构建系统文档。
要为同一组件的 CMakeLists.txt 中的特定组件（``component_name``）使能 UBSAN，在文件末尾添加以下内容:: 要为同一组件的 CMakeLists.txt 中的特定组件（``component_name``）使能 UBSAN，在文件末尾添加以下内容：
.. code-block:: none
target_compile_options(${COMPONENT_LIB} PRIVATE "-fsanitize=undefined" "-fno-sanitize=shift-base") target_compile_options(${COMPONENT_LIB} PRIVATE "-fsanitize=undefined" "-fno-sanitize=shift-base")
UBSAN 输出 UBSAN 输出
"""""""""""""""" """"""""""
当 UBSAN 检测到一个错误时，会打印一个信息和回溯，例如:: 当 UBSAN 检测到一个错误时，会打印一个信息和回溯，例如：
.. code-block:: none
Undefined behavior of type out_of_bounds Undefined behavior of type out_of_bounds
Backtrace:0x4008b383:0x3ffcd8b0 0x4008c791:0x3ffcd8d0 0x4008c587:0x3ffcd8f0 0x4008c6be:0x3ffcd950 0x400db74f:0x3ffcd970 0x400db99c:0x3ffcd9a0 Backtrace:0x4008b383:0x3ffcd8b0 0x4008c791:0x3ffcd8d0 0x4008c587:0x3ffcd8f0 0x4008c6be:0x3ffcd950 0x400db74f:0x3ffcd970 0x400db99c:0x3ffcd9a0
当使用 :doc:`IDF 监视器 <tools/idf-monitor>` 时，回溯会被解码为函数名以及源代码位置，并指向问题发生的位置（这里是 ``main.c:128``）:: 当使用 :doc:`IDF 监视器 <tools/idf-monitor>` 时，回溯会被解码为函数名以及源代码位置，并指向问题发生的位置（这里是 ``main.c:128``）：
.. code-block:: none
0x4008b383: panic_abort at /path/to/esp-idf/components/esp_system/panic.c:367 0x4008b383: panic_abort at /path/to/esp-idf/components/esp_system/panic.c:367

1
docs/zh_CN/api-guides/performance/speed.rst
View File

@@ -314,4 +314,5 @@ ESP-IDF 支持动态 :doc:`/api-reference/system/intr_alloc` 和中断抢占。
- 要提高诸如 ``fread`` 和 ``fgets`` 等缓冲读取函数的执行速度，可以增加文件缓冲区的大小。Newlib 的默认值为 128 字节，但可将其增加到 4096、8192 或 16384 字节。为此，可以使用 ``setvbuf`` 函数对特定文件指针进行局部设置，或者通过修改 :ref:`CONFIG_FATFS_VFS_FSTAT_BLKSIZE` 设置来进行全局修改。 - 要提高诸如 ``fread`` 和 ``fgets`` 等缓冲读取函数的执行速度，可以增加文件缓冲区的大小。Newlib 的默认值为 128 字节，但可将其增加到 4096、8192 或 16384 字节。为此，可以使用 ``setvbuf`` 函数对特定文件指针进行局部设置，或者通过修改 :ref:`CONFIG_FATFS_VFS_FSTAT_BLKSIZE` 设置来进行全局修改。
.. note:: .. note::
增加缓冲区的大小会增加堆内存的使用量。 增加缓冲区的大小会增加堆内存的使用量。

1
docs/zh_CN/api-reference/network/esp_netif.rst
View File

@@ -82,7 +82,6 @@ ESP-NETIF 组件使用了系统事件，典型的网络启动代码如下所示
初始化网络接口可能有些复杂，ESP-NETIF 提供了一些创建常见接口（例如 Wi-Fi 和以太网）的快捷方式。 初始化网络接口可能有些复杂，ESP-NETIF 提供了一些创建常见接口（例如 Wi-Fi 和以太网）的快捷方式。
请参考以下示例来了解如何初始化默认接口： 请参考以下示例来了解如何初始化默认接口：
.. list:: .. list::

11
docs/zh_CN/api-reference/network/esp_now.rst
View File

@@ -13,10 +13,15 @@ CTR 与 CBC-MAC 协议 (CCMP) 可用来保护动作帧的安全。ESP-NOW 广泛
帧格式 帧格式
------------ ------------
ESP-NOW 使用供应商的动作帧传输数据，默认比特率为 1 Mbps。目前 ESP-NOW 支持两个版本： v1.0 和 v2.0。 ESP-NOW 使用供应商的动作帧传输数据，默认比特率为 1 Mbps。
v2.0 的设备支持的最大数据包长度为 ESP_NOW_MAX_DATA_LEN_V2 bytes； v1.0 的设备支持的最大数据包长度为 ESP_NOW_MAX_DATA_LEN bytes。 目前 ESP-NOW 支持两个版本：v1.0 和 v2.0。v2.0 的设备支持的最大数据包长度为 1490 (``ESP_NOW_MAX_DATA_LEN_V2``) 字节；v1.0 的设备支持的最大数据包长度为 250 (``ESP_NOW_MAX_DATA_LEN``) 字节。
v2.0 设备可以接收来自 v2.0 和 v1.0 设备的数据包。v1.0 设备能接收来自 v1.0 的数据包。v1.0 设备可以接收长度不超过 ESP_NOW_MAX_IE_DATA_LEN 的 v2.0 数据包，而对于长度超过 ESP_NOW_MAX_IE_DATA_LEN 的数据包，它要么只接收前 ESP_NOW_MAX_IE_DATA_LEN 字节，要么丢弃数据包。具体行为请参考对应 IDF 版本中的文档。
v2.0 设备可以接收来自 v2.0 和 v1.0 设备的数据包。v1.0 设备只能接收来自 v1.0 设备的数据包。
当然，v1.0 设备也可以接收长度不超过 250 (``ESP_NOW_MAX_IE_DATA_LEN``) 的 v2.0 数据包，只是如果长度超过此值，就只接收前 250 (``ESP_NOW_MAX_IE_DATA_LEN``) 字节，或是直接丢弃数据包。
具体行为请参考对应 IDF 版本中的文档。
供应商的动作帧格式为： 供应商的动作帧格式为：

9
docs/zh_CN/api-reference/protocols/modbus.rst
View File

@@ -1,5 +1,6 @@
ESP-Modbus ESP-Modbus
========== ==========
:link_to_translation:`en:[English]` :link_to_translation:`en:[English]`
乐鑫的 ESP-Modbus 库 (esp-modbus) 支持基于 RS485、Wi-Fi 和以太网接口的 Modbus 通信。 乐鑫的 ESP-Modbus 库 (esp-modbus) 支持基于 RS485、Wi-Fi 和以太网接口的 Modbus 通信。
@@ -8,14 +9,14 @@ ESP-Modbus
* `GitHub 上的 ESP-Modbus 组件 <https://github.com/espressif/esp-modbus>`__ * `GitHub 上的 ESP-Modbus 组件 <https://github.com/espressif/esp-modbus>`__
托管文档 托管文档
-------------------- --------
相应文档请参阅： 相应文档请参阅：
* `ESP-Modbus 文档 <https://docs.espressif.com/projects/esp-modbus>`__ * `ESP-Modbus 文档 <https://docs.espressif.com/projects/esp-modbus>`__
应用示例 应用示例
------------------- --------
以下示例分别介绍了 ESP-Modbus 库的串行端口、TCP 端口的从机和主机实现。 以下示例分别介绍了 ESP-Modbus 库的串行端口、TCP 端口的从机和主机实现。
@@ -30,8 +31,6 @@ ESP-Modbus
详情请参阅具体示例的 ``README.md`` 。 详情请参阅具体示例的 ``README.md`` 。
协议参考 协议参考
------------------- --------
- Modbus 组织与规范协议请参阅 `The Modbus Organization <https://modbus.org/specs.php>`_。 - Modbus 组织与规范协议请参阅 `The Modbus Organization <https://modbus.org/specs.php>`_。

106
docs/zh_CN/security/secure-boot-v2.rst
View File

@@ -1,7 +1,7 @@
:orphan: :orphan:
安全启动 (secure boot) v2 安全启动 (secure boot) v2
============================ =========================
:link_to_translation:`en:[English]` :link_to_translation:`en:[English]`
@@ -9,7 +9,7 @@
{IDF_TARGET_SBV2_KEY:default="RSA-3072", esp32c2="ECDSA-256 或 ECDSA-192", esp32c6="RSA-3072、ECDSA-256 或 ECDSA-192", esp32h2="RSA-3072、ECDSA-256 或 ECDSA-192", esp32p4="RSA-3072、ECDSA-256 或 ECDSA-192", esp32c5="RSA-3072、ECDSA-256、或 ECDSA-192", esp32c61="ECDSA-256 或 ECDSA-192"} {IDF_TARGET_SBV2_KEY:default="RSA-3072", esp32c2="ECDSA-256 或 ECDSA-192", esp32c6="RSA-3072、ECDSA-256 或 ECDSA-192", esp32h2="RSA-3072、ECDSA-256 或 ECDSA-192", esp32p4="RSA-3072、ECDSA-256 或 ECDSA-192", esp32c5="RSA-3072、ECDSA-256、或 ECDSA-192", esp32c61="ECDSA-256 或 ECDSA-192"}
{IDF_TARGET_SECURE_BOOT_OPTION_TEXT:default="", esp32c6="推荐使用 RSA，其验证时间更短。可以在菜单中选择 RSA 和 ECDSA 方案。", esp32h2="推荐使用 RSA，其验证时间更短。可以在菜单中选择 RSA 和 ECDSA 方案。", esp32p4="推荐使用 RSA，其验证时间更短。可以在菜单中选择 RSA 和 ECDSA 方案。", esp32c5="推荐使用 RSA，其验证时间更短。可以在菜单中选择 RSA 和 ECDSA 方案。"} {IDF_TARGET_SECURE_BOOT_OPTION_TEXT:default="", esp32c6="推荐使用 RSA，其验证时间更短。可以在菜单中选择 RSA 和 ECDSA 方案。", esp32h2="推荐使用 RSA，其验证时间更短。可以在菜单中选择 RSA 和 ECDSA 方案。", esp32p4="推荐使用 RSA，其验证时间更短。可以在菜单中选择 RSA 和 ECDSA 方案。"}
{IDF_TARGET_ECO_VERSION:default="", esp32="（v3.0 及以上版本）", esp32c3="（v0.3 及以上版本）"} {IDF_TARGET_ECO_VERSION:default="", esp32="（v3.0 及以上版本）", esp32c3="（v0.3 及以上版本）"}
@@ -31,7 +31,7 @@
芯片版本低于 v3.0 的 ESP32 安全启动请参阅 :doc:`secure-boot-v1`。如果当前芯片版本支持安全启动 v2，推荐使用此模式，相比安全启动 v1 更安全且灵活。 芯片版本低于 v3.0 的 ESP32 安全启动请参阅 :doc:`secure-boot-v1`。如果当前芯片版本支持安全启动 v2，推荐使用此模式，相比安全启动 v1 更安全且灵活。
安全启动 v2 使用基于 {IDF_TARGET_SBV2_SCHEME} 的应用程序和 :ref:`second-stage-bootloader` 验证。若需要使用 {IDF_TARGET_SBV2_SCHEME} 方案对应用程序签名，且无需对引导加载程序签名，同样可以参考本文档。 安全启动 v2 使用基于 {IDF_TARGET_SBV2_SCHEME} 的应用程序和 :ref:`second-stage-bootloader` 验证。若需要使用 {IDF_TARGET_SBV2_SCHEME} 方案对应用程序签名，且无需对引导加载程序 (bootloader) 签名，同样可以参考本文档。
.. only:: esp32 .. only:: esp32
@@ -47,7 +47,7 @@
在本指南中，最常用的命令形式为 ``idf.py secure-<command>``，这是对应 ``espsecure.py <command>`` 的封装。基于 ``idf.py`` 的命令能提供更好的用户体验，但与基于 ``espsecure.py`` 的命令相比，可能会损失一部分高级功能。 在本指南中，最常用的命令形式为 ``idf.py secure-<command>``，这是对应 ``espsecure.py <command>`` 的封装。基于 ``idf.py`` 的命令能提供更好的用户体验，但与基于 ``espsecure.py`` 的命令相比，可能会损失一部分高级功能。
背景 背景
---------- ----
安全启动通过检查每个启动的软件是否已签名来确保设备不会运行任何未经授权（即未签名）的代码。在 {IDF_TARGET_NAME} 上，这些软件包括二级引导加载程序和每个应用程序的二进制文件。注意，一级 (ROM) 引导加载程序是无法更改的 ROM 代码，因此不需要签名。 安全启动通过检查每个启动的软件是否已签名来确保设备不会运行任何未经授权（即未签名）的代码。在 {IDF_TARGET_NAME} 上，这些软件包括二级引导加载程序和每个应用程序的二进制文件。注意，一级 (ROM) 引导加载程序是无法更改的 ROM 代码，因此不需要签名。
@@ -71,7 +71,7 @@
优势 优势
---------- ----
- {IDF_TARGET_SBV2_SCHEME} 的公钥存储在设备上，而相应的 {IDF_TARGET_SBV2_SCHEME} 私钥存储在私密位置，设备无法访问。 - {IDF_TARGET_SBV2_SCHEME} 的公钥存储在设备上，而相应的 {IDF_TARGET_SBV2_SCHEME} 私钥存储在私密位置，设备无法访问。
@@ -94,7 +94,7 @@
使用安全启动 v2 使用安全启动 v2
---------------------- ---------------
以下为使用安全启动 v2 流程的概述。有关如何启用安全启动，请参阅 :ref:`secure-boot-v2-howto`。 以下为使用安全启动 v2 流程的概述。有关如何启用安全启动，请参阅 :ref:`secure-boot-v2-howto`。
@@ -136,7 +136,7 @@
.. _signature-block-format: .. _signature-block-format:
签名块格式 签名块格式
---------------------- ----------
签名块以 4 KB 的整数倍为起始位置，拥有独立 flash 扇区。签名计算覆盖了镜像中的所有字节，包括填充字节，请参阅 :ref:`secure_padding`。 签名块以 4 KB 的整数倍为起始位置，拥有独立 flash 扇区。签名计算覆盖了镜像中的所有字节，包括填充字节，请参阅 :ref:`secure_padding`。
@@ -264,7 +264,7 @@
.. _secure_padding: .. _secure_padding:
安全填充 安全填充
-------------- --------
在安全启动 v2 方案中，应用程序镜像经过处理，会填充到与 flash MMU 页面大小边界对齐，确保只有经过验证的内容会映射到内部地址空间，这称为安全填充。填充后会进行镜像签名计算，随后将签名块 (4 KB) 附加到镜像上。 在安全启动 v2 方案中，应用程序镜像经过处理，会填充到与 flash MMU 页面大小边界对齐，确保只有经过验证的内容会映射到内部地址空间，这称为安全填充。填充后会进行镜像签名计算，随后将签名块 (4 KB) 附加到镜像上。
@@ -301,7 +301,7 @@
.. _verify_signature-block: .. _verify_signature-block:
验证签名块 验证签名块
----------------------------- ----------
如果签名块的第一个字节是 ``0xe7``，并且偏移量 1196 处存储了有效的 CRC32，则签名块有效，否则无效。 如果签名块的第一个字节是 ``0xe7``，并且偏移量 1196 处存储了有效的 CRC32，则签名块有效，否则无效。
@@ -309,7 +309,7 @@
.. _verify_image: .. _verify_image:
验证镜像 验证镜像
----------------------------- --------
如果存储在某个签名块中的公钥是适用于当前设备的有效公钥，且该签名块中存储的签名与从 flash 中读取的镜像数据计算出的签名匹配，则该镜像通过验证。 如果存储在某个签名块中的公钥是适用于当前设备的有效公钥，且该签名块中存储的签名与从 flash 中读取的镜像数据计算出的签名匹配，则该镜像通过验证。
@@ -327,10 +327,10 @@
.. only:: SOC_SECURE_BOOT_V2_ECC and SOC_SECURE_BOOT_V2_RSA .. only:: SOC_SECURE_BOOT_V2_ECC and SOC_SECURE_BOOT_V2_RSA
1. 使用公钥，采用 RSA-PSS（RFC8017 的第 8.1.2 节）算法或 ECDSA（RFC6090 的第 5.3.3 节）算法，验证引导加载程序镜像的签名，并与步骤 (2) 中计算的镜像摘要比较。 3. 使用公钥，采用 RSA-PSS（RFC8017 的第 8.1.2 节）算法或 ECDSA（RFC6090 的第 5.3.3 节）算法，验证引导加载程序镜像的签名，并与步骤 (2) 中计算的镜像摘要比较。
bootloader 大小 引导加载程序的大小
------------------ ------------------
启用安全启动和/或 flash 加密都会增加引导加载程序的大小，因此可能需要更新分区表偏移量，请参阅 :ref:`bootloader-size`。 启用安全启动和/或 flash 加密都会增加引导加载程序的大小，因此可能需要更新分区表偏移量，请参阅 :ref:`bootloader-size`。
@@ -341,7 +341,7 @@ bootloader 大小
.. _efuse-usage: .. _efuse-usage:
使用 eFuse 使用 eFuse
----------- ----------
.. only:: esp32 .. only:: esp32
@@ -373,7 +373,7 @@ bootloader 大小
.. _secure-boot-v2-howto: .. _secure-boot-v2-howto:
启用安全启动 v2 启用安全启动 v2
---------------------------- ---------------
1. 打开 :ref:`project-configuration-menu`，在 ``Security features`` 下设置 ``Enable hardware Secure Boot in bootloader`` 以启用安全启动模式。 1. 打开 :ref:`project-configuration-menu`，在 ``Security features`` 下设置 ``Enable hardware Secure Boot in bootloader`` 以启用安全启动模式。
@@ -415,7 +415,7 @@ bootloader 大小
如果启用了安全启动，``idf.py flash`` 不会烧录引导加载程序。 如果启用了安全启动，``idf.py flash`` 不会烧录引导加载程序。
10. 重置 {IDF_TARGET_NAME}，它将启动你烧录的二级引导加载程序。该二级引导加载程序会在芯片上启用安全启动，然后验证应用程序镜像签名，并启动应用程序。请查看 {IDF_TARGET_NAME} 的串行控制器输出，确保已启用安全启动，且没有因构建配置发生错误。 10. 重置 {IDF_TARGET_NAME} 将启动烧录的二级引导加载程序。该二级引导加载程序会在芯片上启用安全启动，然后验证应用程序镜像签名，并启动应用程序。请查看 {IDF_TARGET_NAME} 的串行控制器输出，确保已启用安全启动，且没有因构建配置发生错误。
.. note:: .. note::
@@ -429,7 +429,7 @@ bootloader 大小
启用安全启动后的限制 启用安全启动后的限制
----------------------------------------- --------------------
- 任何更新过的引导加载程序或应用程序都需要使用与已存储在 eFuse 中的摘要相匹配的密钥来签名。 - 任何更新过的引导加载程序或应用程序都需要使用与已存储在 eFuse 中的摘要相匹配的密钥来签名。
@@ -438,7 +438,7 @@ bootloader 大小
- 一旦启用安全启动，就无法再对 eFuse 密钥进行读保护，这可以避免攻击者对存储公共密钥摘要的 eFuse 块进行读保护，进而导致系统无法验证和处理签名，系统服务无法正常运行。有关读保护密钥的更多信息，请参阅下方详细说明。 - 一旦启用安全启动，就无法再对 eFuse 密钥进行读保护，这可以避免攻击者对存储公共密钥摘要的 eFuse 块进行读保护，进而导致系统无法验证和处理签名，系统服务无法正常运行。有关读保护密钥的更多信息，请参阅下方详细说明。
烧录读保护密钥 烧录读保护密钥
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~
**读保护密钥**： **读保护密钥**：
以下密钥受到读保护后，相应的硬件将直接访问这些密钥（软件无法读取）： 以下密钥受到读保护后，相应的硬件将直接访问这些密钥（软件无法读取）：
@@ -467,12 +467,12 @@ bootloader 大小
.. note:: .. note::
如果在启用安全启动时，第二阶段引导加载程序启用了 :doc:`/security/flash-encryption`，则首次启动时生成的 flash 加密密钥已经受到读保护。 如果在启用安全启动时，二级引导加载程序启用了 :doc:`/security/flash-encryption`，则首次启动时生成的 flash 加密密钥已经受到读保护。
.. _secure-boot-v2-generate-key: .. _secure-boot-v2-generate-key:
生成安全启动签名密钥 生成安全启动签名密钥
---------------------------------- --------------------
根据构建系统提示，使用 ``idf.py secure-generate-signing-key`` 命令生成新签名密钥。 根据构建系统提示，使用 ``idf.py secure-generate-signing-key`` 命令生成新签名密钥。
@@ -516,10 +516,10 @@ bootloader 大小
.. _remote-sign-v2-image: .. _remote-sign-v2-image:
远程镜像签名 远程镜像签名
------------------------ ------------
使用 ``idf.py`` 进行签名 使用 ``idf.py`` 进行签名
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~
对于生产构建，将签名密钥存储在远程签名服务器上，而不是本地构建机器上，是一种比较好的方案，这也是默认的 ESP-IDF 安全启动配置。可以使用命令行工具 ``espsecure.py`` 在远程系统上为应用程序镜像和分区表数据签名，供安全启动使用。 对于生产构建，将签名密钥存储在远程签名服务器上，而不是本地构建机器上，是一种比较好的方案，这也是默认的 ESP-IDF 安全启动配置。可以使用命令行工具 ``espsecure.py`` 在远程系统上为应用程序镜像和分区表数据签名，供安全启动使用。
@@ -539,7 +539,7 @@ bootloader 大小
使用预计算的签名进行签名 使用预计算的签名进行签名
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~
如果存在为镜像生成的有效预计算签名及相应公钥，可以使用这些签名生成一个签名扇区，并将其附加到镜像中。注意，预计算的签名应计算在镜像中的所有字节，包括安全填充字节。 如果存在为镜像生成的有效预计算签名及相应公钥，可以使用这些签名生成一个签名扇区，并将其附加到镜像中。注意，预计算的签名应计算在镜像中的所有字节，包括安全填充字节。
@@ -553,7 +553,7 @@ bootloader 大小
使用外部硬件安全模块 (HSM) 进行签名 使用外部硬件安全模块 (HSM) 进行签名
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
为了提高安全性，可能需要使用外部硬件安全模块 (HSM) 存储私钥，该私钥无法直接访问，但具备一个接口，可以生成二进制文件及其相应公钥的签名。 为了提高安全性，可能需要使用外部硬件安全模块 (HSM) 存储私钥，该私钥无法直接访问，但具备一个接口，可以生成二进制文件及其相应公钥的签名。
@@ -573,7 +573,7 @@ bootloader 大小
使用安全启动的建议 使用安全启动的建议
-------------------------- ------------------
* 在具备高质量熵源的系统上生成签名密钥。 * 在具备高质量熵源的系统上生成签名密钥。
* 时刻对签名密钥保密，泄漏此密钥将危及安全启动系统。 * 时刻对签名密钥保密，泄漏此密钥将危及安全启动系统。
@@ -584,7 +584,7 @@ bootloader 大小
.. only:: SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS .. only:: SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS
密钥管理 密钥管理
-------------- --------
* 应独立计算并分别存储 1 到 3 个 {IDF_TARGET_SBV2_KEY} 公钥对（密钥 #0, #1, #2）。 * 应独立计算并分别存储 1 到 3 个 {IDF_TARGET_SBV2_KEY} 公钥对（密钥 #0, #1, #2）。
* 完成烧录后，应设置 KEY_DIGEST eFuse 为写保护位。 * 完成烧录后，应设置 KEY_DIGEST eFuse 为写保护位。
@@ -596,11 +596,11 @@ bootloader 大小
多个密钥管理 多个密钥管理
------------- ------------
* 在烧录引导加载程序之前，应使用设备整个生命周期所需的所有私钥对引导加载程序签名。 * 在烧录引导加载程序之前，应使用设备整个生命周期所需的所有私钥对引导加载程序签名。
* 构建系统每次只能使用一个私钥签名，如果需要，你必须手动运行命令以附加更多签名。 * 构建系统每次只能使用一个私钥签名，如果需要，必须手动运行命令以附加更多签名。
* 你可以使用 ``idf.py secure-sign-data`` 的附加功能，此命令也将在启用安全启动 v2 的引导加载程序编译的末尾显示。 * 可以使用 ``idf.py secure-sign-data`` 的附加功能，此命令也将在启用安全启动 v2 的引导加载程序编译的末尾显示。
.. code-block:: .. code-block::
@@ -616,7 +616,7 @@ bootloader 大小
.. _secure-boot-v2-key-revocation: .. _secure-boot-v2-key-revocation:
撤销密钥管理 撤销密钥管理
-------------- ------------
* 密钥按线性顺序处理，即密钥 #0、密钥 #1、密钥 #2。 * 密钥按线性顺序处理，即密钥 #0、密钥 #1、密钥 #2。
* 撤销一个密钥后，其余未被撤销的密钥仍可用于应用程序签名。例如，如密钥 #1 被撤销，仍然可以使用密钥 #0 和密钥 #2 给应用程序签名。 * 撤销一个密钥后，其余未被撤销的密钥仍可用于应用程序签名。例如，如密钥 #1 被撤销，仍然可以使用密钥 #0 和密钥 #2 给应用程序签名。
@@ -630,7 +630,7 @@ bootloader 大小
如果在开发流程中需要保留未使用摘要槽，则应从外部启用安全启动 (:ref:`enable-secure-boot-v2-externally`)，而不是在启动设备时启用安全启动，这样引导加载程序就无需启用安全启动，从而避免安全隐患。 如果在开发流程中需要保留未使用摘要槽，则应从外部启用安全启动 (:ref:`enable-secure-boot-v2-externally`)，而不是在启动设备时启用安全启动，这样引导加载程序就无需启用安全启动，从而避免安全隐患。
保守方法 保守方法
~~~~~~~~~~~~ ~~~~~~~~
假设一个受信任的私钥 (N-1) 受到威胁，需要升级到新的密钥对 (N)。 假设一个受信任的私钥 (N-1) 受到威胁，需要升级到新的密钥对 (N)。
@@ -652,7 +652,7 @@ bootloader 大小
.. _secure-boot-v2-aggressive-key-revocation: .. _secure-boot-v2-aggressive-key-revocation:
激进方法 激进方法
~~~~~~~~~~~~~~ ~~~~~~~~
ROM 代码具备一项额外功能，即在签名验证失败时可以撤销公钥摘要。 ROM 代码具备一项额外功能，即在签名验证失败时可以撤销公钥摘要。
@@ -666,15 +666,15 @@ bootloader 大小
.. _secure-boot-v2-technical-details: .. _secure-boot-v2-technical-details:
技术细节 技术细节
----------------- --------
以下章节包含安全启动元件的详细参考描述。 以下章节包含对各安全启动要素的详细参考描述。
安全启动已集成到 ESP-IDF 构建系统中，因此 ``idf.py build`` 将进行应用程序镜像签名。启用 :ref:`CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES` 后，``idf.py bootloader`` 将生成一个已签名的引导加载程序。 安全启动已集成到 ESP-IDF 构建系统中，因此 ``idf.py build`` 将进行应用程序镜像签名。启用 :ref:`CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES` 后，``idf.py bootloader`` 将生成一个已签名的引导加载程序。
另外，也可以使用 ``idf.py`` 或 ``openssl`` 工具生成独立签名并进行验证。建议使用 ``idf.py``，但如果需在非 ESP-IDF 环境中生成或验证签名，也可以使用 ``openssl`` 命令，因为安全引导 v2 生成签名符合标准的签名算法。 当然，也可以使用 ``idf.py`` 或 ``openssl`` 工具生成独立的签名并对其进行验证。推荐使用 ``idf.py``，但如果需要在非 ESP-IDF 环境中生成或验证签名，也可以使用 ``openssl`` 命令，安全启动 v2 的签名生成符合标准签名算法。
用 ``idf.py`` 生成和验证签名 使用 ``idf.py`` 生成并验证签名
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. 二进制镜像签名： 1. 二进制镜像签名：
@@ -685,30 +685,30 @@ bootloader 大小
Keyfile 是包含 {IDF_TARGET_SBV2_KEY} 签名私钥的 PEM 文件。 Keyfile 是包含 {IDF_TARGET_SBV2_KEY} 签名私钥的 PEM 文件。
2. 验证签名的二进制镜像： 2. 验证二进制镜像签名：
.. code-block:: .. code-block::
idf.py secure-verify-signature --keyfile ./my_signing_key.pem image_signed.bin idf.py secure-verify-signature --keyfile ./my_signing_key.pem image_signed.bin
Keyfile 是包含 {IDF_TARGET_SBV2_KEY} 公钥/私钥签名的 PEM 文件。 Keyfile 是包含 {IDF_TARGET_SBV2_KEY} 签名公钥/私钥的 PEM 文件。
用 OpenSSL 生成和验证签名 使用 OpenSSL 生成并验证签名
~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
最好使用 ``idf.py`` 工具生成和验证签名，但如果需要使用 OpenSSL 执行这些操作，可参考以下命令： 一般推荐使用 ``idf.py`` 工具来生成并验证签名，如果想通过 OpenSSL 生成并验证签名，请参照下列命令：
1. 生成需要计算签名的二进制文件镜像的摘要。 1. 生成镜像二进制文件的摘要。
.. code-block:: bash .. code-block:: bash
openssl dgst -sha256 -binary BINARY_FILE > DIGEST_BINARY_FILE openssl dgst -sha256 -binary BINARY_FILE > DIGEST_BINARY_FILE
2. 使用上一步计算出的摘要生成该镜像的签名。 2. 使用上述摘要，生成镜像签名。
.. only:: SOC_SECURE_BOOT_V2_RSA .. only:: SOC_SECURE_BOOT_V2_RSA
用于生成 RSA-PSS 签名： 生成 RSA-PSS 签名：
.. code-block:: bash .. code-block:: bash
@@ -722,7 +722,7 @@ Keyfile 是包含 {IDF_TARGET_SBV2_KEY} 公钥/私钥签名的 PEM 文件。
.. only:: SOC_SECURE_BOOT_V2_ECC .. only:: SOC_SECURE_BOOT_V2_ECC
用于生成 ECDSA 签名： 生成 ECDSA 签名：
.. code-block:: bash .. code-block:: bash
@@ -735,7 +735,7 @@ Keyfile 是包含 {IDF_TARGET_SBV2_KEY} 公钥/私钥签名的 PEM 文件。
.. only:: SOC_SECURE_BOOT_V2_RSA .. only:: SOC_SECURE_BOOT_V2_RSA
For verifying an RSA-PSS signature: 验证 RSA-PSS 签名：
.. code-block:: bash .. code-block:: bash
@@ -749,7 +749,7 @@ Keyfile 是包含 {IDF_TARGET_SBV2_KEY} 公钥/私钥签名的 PEM 文件。
.. only:: SOC_SECURE_BOOT_V2_ECC .. only:: SOC_SECURE_BOOT_V2_ECC
用于验证 ECDSA 签名： 验证 ECDSA 签名：
.. code-block:: bash .. code-block:: bash
@@ -762,7 +762,7 @@ Keyfile 是包含 {IDF_TARGET_SBV2_KEY} 公钥/私钥签名的 PEM 文件。
.. _secure-boot-v2-and-flash-encr: .. _secure-boot-v2-and-flash-encr:
安全启动 & flash 加密 安全启动 & flash 加密
------------------------------ ---------------------
如果使用安全启动时没有启用 :doc:`flash-encryption`，可能会发生 ``time-of-check to time-of-use`` 攻击，即在验证并运行镜像后交换 flash 内容。因此，建议同时使用这两个功能。 如果使用安全启动时没有启用 :doc:`flash-encryption`，可能会发生 ``time-of-check to time-of-use`` 攻击，即在验证并运行镜像后交换 flash 内容。因此，建议同时使用这两个功能。
@@ -798,7 +798,7 @@ Keyfile 是包含 {IDF_TARGET_SBV2_KEY} 公钥/私钥签名的 PEM 文件。
.. _signed-app-verify-v2-howto: .. _signed-app-verify-v2-howto:
启用已签名的应用程序验证 启用已签名的应用程序验证
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~
1. 打开 :ref:`project-configuration-menu` > ``Security features``。 1. 打开 :ref:`project-configuration-menu` > ``Security features``。
@@ -812,7 +812,7 @@ Keyfile 是包含 {IDF_TARGET_SBV2_KEY} 公钥/私钥签名的 PEM 文件。
.. only:: SOC_SECURE_BOOT_V2_ECC and not SOC_SECURE_BOOT_V2_RSA .. only:: SOC_SECURE_BOOT_V2_ECC and not SOC_SECURE_BOOT_V2_RSA
1. 确保 ``App Signing Scheme`` 设置为 ``ECDSA (v2)``。 2. 确保 ``App Signing Scheme`` 设置为 ``ECDSA (v2)``。
.. only:: SOC_SECURE_BOOT_V2_RSA and SOC_SECURE_BOOT_V2_ECC .. only:: SOC_SECURE_BOOT_V2_RSA and SOC_SECURE_BOOT_V2_ECC
@@ -831,11 +831,11 @@ Keyfile 是包含 {IDF_TARGET_SBV2_KEY} 公钥/私钥签名的 PEM 文件。
进阶功能 进阶功能
----------------- --------
JTAG 调试 JTAG 调试
~~~~~~~~~~~~~~ ~~~~~~~~~
启用安全启动模式时，eFuse 会默认禁用 JTAG。初次启动时，引导加载程序即禁用 JTAG 调试功能，并启用安全启动模式。 启用安全启动模式时，eFuse 会默认禁用 JTAG。初次启动时，引导加载程序禁用 JTAG 调试功能，并启用安全启动模式。
有关在启用安全启动或已签名应用程序验证的情况下使用 JTAG 调试的更多信息，请参阅 :ref:`jtag-debugging-security-features`。 有关在启用安全启动或已签名应用程序验证的情况下使用 JTAG 调试的更多信息，请参阅 :ref:`jtag-debugging-security-features`。