mirror
/
esp-idf
kopia lustrzana https://github.com/espressif/esp-idf
1
0
Forkuj 0
Kod Zgłoszenia Projekty Wydania Wiki Aktywność

docs: Updated CN translation for esp-ble-mesh, wifi, spi_flash and fata-errors; And keep line number consistency for en/index and versions

pull/8219/head
daiziyan 2021-12-22 11:34:42 +08:00
rodzic 5d47efb72d
commit 20374161a6
11 zmienionych plików z 131 dodań i 97 usunięć
Pokaż statystyki Ściągnij plik aktualizacji Ściągnij plik porównania Expand all files Collapse all files

3
docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst
Wyświetl plik

@ -1,6 +1,8 @@
ESP-BLE-MESH FAQ
================
:link_to_translation:`zh_CN:[中文]`
This document provides a summary of frequently asked questions about developing with ESP-BLE-MESH, and is divided into seven sections:
* :ref:`ble-mesh-faq-provisioner-development`
@ -58,6 +60,7 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The unicast address of Provisioner can be set only once during initialization and can't be changed afterwards. In theory, it can serve as the destination address of the node-reporting-status message, provided that the unicast address of the Provisioner is known by nodes. Nodes can know the unicast address of Provisioner during configuration since Provisioner sends messages to them with its unicast address used as the source address.
Subscription address can also be used. Provisioner subscribes to a group address or virtual address, and nodes send messages to the subscription address.
1.7 Is the unicast address of the node that is firstly provisioned by Provisioner to ESP-BLE-MESH network fixed？

14
docs/en/api-guides/fatal-errors.rst
Wyświetl plik

@ -164,7 +164,7 @@ The register values printed are the register values in the exception frame, i.e.
A Register dump is not printed if the panic handler has been executed as a result of an ``abort()`` call.
.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA
In some cases, such as interrupt watchdog timeout, the panic handler may print additional CPU registers (EPC1-EPC4) and the registers/backtrace of the code running on the other CPU.
The backtrace line contains PC:SP pairs, where PC is the Program Counter and SP is Stack Pointer, for each stack frame of the current task. If a fatal error happens inside an ISR, the backtrace may include PC:SP pairs both from the task which was interrupted, and from the ISR.
@ -214,7 +214,7 @@ If :doc:`IDF Monitor <tools/idf-monitor>` is used, Program Counter values will b
MSTATUS : 0x00001881 MTVEC : 0x40380001 MCAUSE : 0x00000007 MTVAL : 0x00000000
MHARTID : 0x00000000
Moreover, the :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, the :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:
::
@ -234,16 +234,16 @@ If :doc:`IDF Monitor <tools/idf-monitor>` is used, Program Counter values will b
While the backtrace above is very handy, it requires the user to use :doc:`IDF Monitor <tools/idf-monitor>`. Thus, in order to generate and print a backtrace while using another monitor program, it is possible to activate :ref:`CONFIG_ESP_SYSTEM_USE_EH_FRAME` option from the menuconfig.
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:
::
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
These ``PC:SP`` pairs represent the PC (Program Counter) and SP (Stack Pointer) for each stack frame of the current task.
The main benefit of the :ref:`CONFIG_ESP_SYSTEM_USE_EH_FRAME` option is that the backtrace is generated by the board itself (without the need for :doc:`IDF Monitor <tools/idf-monitor>`). However, the option's drawback is that it results in an increase of the compiled binary's size (ranging from 20% to 100% increase in size). Furthermore, this option causes debug information to be included within the compiled binary. Therefore, users are strongly advised not to enable this option in mass/final production builds.
To find the location where a fatal error has happened, look at the lines which follow the "Backtrace" line. Fatal error location is the top line, and subsequent lines show the call stack.
.. _GDB-Stub:
@ -349,7 +349,7 @@ This CPU exception indicates that the instruction which was executed was not a v
This error indicates that the application has written past the end of the stack of the task with name ``task_name``. Note that not every stack overflow is guaranteed to trigger this error. It is possible that the task writes to memory beyond the stack canary location, in which case the watchpoint will not be triggered.
.. only:: CONFIG_IDF_TARGET_ARCH_RISCV
Instruction address misaligned
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1
docs/en/api-guides/wifi.rst
Wyświetl plik

@ -1313,7 +1313,6 @@ For establishing a secure connection, AP and station negotiate and agree on the
- MSCHAP and MSCHAP-V2.
- EAP-FAST: This is a Protected Access Credentials (PAC) based authentication method which also uses identity and password. Currently, USE_MBEDTLS_CRYPTO flag should be disabled to use this feature.
Detailed information on creating certificates and how to run wpa2_enterprise example on {IDF_TARGET_NAME} can be found in :example:`wifi/wifi_enterprise`.
Wireless Network Management

18
docs/en/api-reference/storage/spi_flash.rst
Wyświetl plik

@ -24,7 +24,7 @@ Kconfig option :ref:`CONFIG_SPI_FLASH_USE_LEGACY_IMPL` can be used to switch ``s
Encrypted reads and writes use the old implementation, even if :ref:`CONFIG_SPI_FLASH_USE_LEGACY_IMPL` is not enabled. As such, encrypted flash operations are only supported with the main flash chip (and not with other flash chips, that is on SPI1 with different CS, or on other SPI buses). Reading through cache is only supported on the main flash, which is determined by the HW.
Support for features of flash chips
Support for Features of Flash Chips
-----------------------------------
Flash features of different vendors are operated in different ways and need special support. The fast/slow read and Dual mode (DOUT/DIO) of almost all 24-bits address flash chips are supported, because they don't need any vendor-specific commands.
@ -59,7 +59,7 @@ Users can also customize their own flash chip driver, see :doc:`spi_flash_overri
Custom Flash Driver <spi_flash_override_driver>
Initializing a flash device
Initializing a Flash Device
---------------------------
To use ``esp_flash_*`` APIs, you need to have a chip initialized on a certain SPI bus.
@ -72,7 +72,7 @@ To use ``esp_flash_*`` APIs, you need to have a chip initialized on a certain SP
.. note:: Multiple flash chips can be attached to the same bus now. However, using ``esp_flash_*`` devices and ``spi_device_*`` devices on the same SPI bus is not supported yet.
SPI flash access API
SPI Flash Access API
--------------------
This is the set of API functions for working with data in flash:
@ -108,7 +108,7 @@ Concurrency Constraints for flash on SPI1
.. _flash-partition-apis:
Partition table API
Partition Table API
-------------------
ESP-IDF projects use a partition table to maintain information about various regions of SPI flash memory (bootloader, various application binaries, data, filesystems). More information on partition tables can be found :doc:`here </api-guides/partition-tables>`.
@ -133,7 +133,7 @@ It is possible to encrypt the contents of SPI flash and have it transparently de
Refer to the :doc:`Flash Encryption documentation </security/flash-encryption>` for more details.
Memory mapping API
Memory Mapping API
------------------
{IDF_TARGET_CACHE_SIZE:default="64 KB"}
@ -180,7 +180,7 @@ In other files of the SPI HAL, some of these functions are implemented with exis
You can also implement your own host driver, even with the GPIO. As long as all the functions in the ``spi_flash_host_driver_t`` are implemented, the esp_flash API can access to the flash regardless of the low-level hardware.
Chip driver
Chip Driver
^^^^^^^^^^^
The chip driver, defined in ``spi_flash_chip_driver.h``, wraps basic functions provided by the host driver for the API layer to use.
@ -193,7 +193,7 @@ The chip driver relies on the host driver.
.. _esp_flash_os_func:
OS functions
OS Functions
^^^^^^^^^^^^
Currently the OS function layer provides entries of a lock and delay.
@ -211,7 +211,7 @@ The delay is used by some long operations which requires the master to wait or p
The top API wraps these the chip driver and OS functions into an entire component, and also provides some argument checking.
See also
See Also
--------
- :doc:`Partition Table documentation <../../api-guides/partition-tables>`
@ -221,7 +221,7 @@ See also
.. _spi-flash-implementation-details:
Implementation details
Implementation Details
----------------------
In order to perform some flash operations, it is necessary to make sure that both CPUs are not running any code from flash for the duration of the flash operation:

3
docs/en/index.rst
Wyświetl plik

@ -66,6 +66,3 @@ This is the documentation for Espressif IoT Development Framework (`esp-idf <htt
语言/Languages <languages>
* :ref:`genindex`

22
docs/en/versions.rst
Wyświetl plik

@ -86,19 +86,19 @@ Supported means that the ESP-IDF team will continue to apply bug fixes, security
Support period is divided into "Service" and "Maintenance" period:
.. list-table::
:header-rows: 1
:widths: 25 25 55
.. list-table::
:header-rows: 1
:widths: 25 25 55
* - Period
- Duration
- Recommended for new projects?
- Recommended for new projects?
* - Service
- 12 months
- Yes
- Yes
* - Maintenance
- 18 months
- No
- No
During the Service period, bugfixes releases are more frequent. In some cases, support for new features may be added during the Service period (this is reserved for features which are needed to meet particular regulatory requirements or standards for new products, and which carry a very low risk of introducing regressions.)
@ -225,7 +225,9 @@ To use the latest version on the ESP-IDF master branch, this is the process to f
- Periodically, re-run ``git pull`` to pull the latest version of master. Note that you may need to change your project or report bugs after updating your master branch.
- To switch from master to a release branch or stable version, run ``git checkout`` as shown in the other sections.
.. important:: It is strongly recommended to regularly run ``git pull`` and then ``git submodule update --init --recursive`` so a local copy of master does not get too old. Arbitrary old master branch revisions are effectively unsupportable "snapshots" that may have undocumented bugs. For a semi-stable version, try :ref:`updating-release-branch` instead.
.. important::
It is strongly recommended to regularly run ``git pull`` and then ``git submodule update --init --recursive`` so a local copy of master does not get too old. Arbitrary old master branch revisions are effectively unsupportable "snapshots" that may have undocumented bugs. For a semi-stable version, try :ref:`updating-release-branch` instead.
.. _`updating-release-branch`:
@ -246,7 +248,9 @@ For example, to follow the branch for ESP-IDF v3.1, including any bugfixes for f
Each time you ``git pull`` this branch, ESP-IDF will be updated with fixes for this release.
.. note:: There is no dedicated documentation for release branches. It is recommended to use the documentation for the closest version to the branch which is currently checked out.
.. note::
There is no dedicated documentation for release branches. It is recommended to use the documentation for the closest version to the branch which is currently checked out.
.. _`Releases page`: http://github.com/espressif/esp-idf/releases
.. _`list of branches`: https://github.com/espressif/esp-idf/branches

23
docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-faq.rst
Wyświetl plik

@ -15,6 +15,7 @@ ESP-BLE-MESH 常见问题手册
用户可以参考这些章节，快速找到问题的答案。该文档会根据各种渠道收集的反馈进行更新。
.. _ble-mesh-faq-provisioner-development:
1. Provisioner 开发
@ -22,7 +23,6 @@ ESP-BLE-MESH 常见问题手册
通常而言，Provisioner 用于配网未配网设备并形成 mesh 网络。组网后，设备的角色变成节点。
1.1 未配网设备加入 ESP-BLE-MESH 网络的流程是什么？
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -54,7 +54,7 @@ ESP-BLE-MESH 常见问题手册
1.5 Provisioner 的单播地址是不是固定的？
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:cpp:type:`esp_ble_mesh_prov_t` 中 :code:`prov_unicast_addr` 的值用于设置 Provisioner 的单播地址，只能在初始化期间设置一次，此后不能更改。
:cpp:type:`esp_ble_mesh_prov_t` 中 :code:`prov_unicast_addr` 的值用于设置 Provisioner 的单播地址，只能在初始化期间设置一次，此后不能更改。
1.6 Provisioner 的地址是否可以作为节点上报状态消息的目的地址？
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -320,7 +320,7 @@ ESP-BLE-MESH 常见问题手册
1.22 Provisioner 如何管理 mesh 网络中的节点？
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ESP-BLE-MESH 在示例中实现了一些基本的节点管理功能，比如 :cpp:func:`esp_ble_mesh_store_node_info`。
ESP-BLE-MESH 在示例中实现了一些基本的节点管理功能，比如 :cpp:func:`esp_ble_mesh_store_node_info`。
ESP-BLE-MESH 还提供可用于设置节点本地名称的 API :cpp:func:`esp_ble_mesh_provisioner_set_node_name` 和可用于获取节点本地名称的 API :cpp:func:`esp_ble_mesh_provisioner_get_node_name`。
1.23 Provisioner 想要控制节点的服务器模型时需要什么？
@ -346,31 +346,31 @@ ESP-BLE-MESH 常见问题手册
- Configuration Client Model
- API :cpp:func:`esp_ble_mesh_config_client_get_state` 可用于获取 Configuration Server Model 的 :cpp:type:`esp_ble_mesh_cfg_client_get_state_t` 值。
- API :cpp:func:`esp_ble_mesh_config_client_set_state` 可用于获取 Configuration Server Model 的 :cpp:type:`esp_ble_mesh_cfg_client_set_state_t` 值。
- API :cpp:func:`esp_ble_mesh_config_client_set_state` 可用于设置 Configuration Server Model 的 :cpp:type:`esp_ble_mesh_cfg_client_set_state_t` 值。
- Health Client Model
- API :cpp:func:`esp_ble_mesh_health_client_get_state` 可用于获取 Health Server Model 的 :cpp:type:`esp_ble_mesh_health_client_get_state_t` 值。
- API :cpp:func:`esp_ble_mesh_health_client_set_state` 可用于获取 Health Server Model 的 :cpp:type:`esp_ble_mesh_health_client_set_state_t` 值。
- API :cpp:func:`esp_ble_mesh_health_client_set_state` 可用于设置 Health Server Model 的 :cpp:type:`esp_ble_mesh_health_client_set_state_t` 值。
- Generic Client Models
- API :cpp:func:`esp_ble_mesh_generic_client_get_state` 可用于获取 Generic Server Model 的 :cpp:type:`esp_ble_mesh_generic_client_get_state_t` 值。
- API :cpp:func:`esp_ble_mesh_generic_client_set_state` 可用于获取 Generic Server Model 的 :cpp:type:`esp_ble_mesh_generic_client_set_state_t` 值。
- API :cpp:func:`esp_ble_mesh_generic_client_set_state` 可用于设置 Generic Server Model 的 :cpp:type:`esp_ble_mesh_generic_client_set_state_t` 值。
- Lighting Client Models
- API :cpp:func:`esp_ble_mesh_light_client_get_state` 可用于获取 Lighting Server Model 的 :cpp:type:`esp_ble_mesh_light_client_get_state_t` 值。
- API :cpp:func:`esp_ble_mesh_light_client_set_state` 可用于获取 Lighting Server Model 的 :cpp:type:`esp_ble_mesh_light_client_set_state_t` 值。
- API :cpp:func:`esp_ble_mesh_light_client_set_state` 可用于设置 Lighting Server Model 的 :cpp:type:`esp_ble_mesh_light_client_set_state_t` 值。
- Sensor Client Models
- API :cpp:func:`esp_ble_mesh_sensor_client_get_state` 可用于获取 Sensor Server Model 的 :cpp:type:`esp_ble_mesh_sensor_client_get_state_t` 值。
- API :cpp:func:`esp_ble_mesh_sensor_client_set_state` 可用于获取 Sensor Server Model 的 :cpp:type:`esp_ble_mesh_sensor_client_set_state_t` 值。
- API :cpp:func:`esp_ble_mesh_sensor_client_set_state` 可用于设置 Sensor Server Model 的 :cpp:type:`esp_ble_mesh_sensor_client_set_state_t` 值。
- Time and Scenes Client Models
- API :cpp:func:`esp_ble_mesh_time_scene_client_get_state` 可用于获取 Time and Scenes Server Model 的 :cpp:type:`esp_ble_mesh_time_scene_client_get_state_t` 值。
- API :cpp:func:`esp_ble_mesh_time_scene_client_set_state` 可用于获取 Time and Scenes Server Model 的 :cpp:type:`esp_ble_mesh_time_scene_client_set_state_t` 值。
- API :cpp:func:`esp_ble_mesh_time_scene_client_set_state` 可用于设置 Time and Scenes Server Model 的 :cpp:type:`esp_ble_mesh_time_scene_client_set_state_t` 值。
.. _ble-mesh-faq-node-development:
@ -502,7 +502,7 @@ ESP-BLE-MESH 常见问题手册
2.18 设备通信必须要网关吗？
^^^^^^^^^^^^^^^^^^^^^^^^^^^
- 情况 1：节点仅在 mesh 网络内通信。这种情况下，不需要网关。ESP-BLE-MESH 网络是一个泛洪的网络，网络中的消息没有固定的路径，节点与节点之间可以随意通信.
- 情况 1：节点仅在 mesh 网络内通信。这种情况下，不需要网关。ESP-BLE-MESH 网络是一个泛洪的网络，网络中的消息没有固定的路径，节点与节点之间可以随意通信.
- 情况 2：如果用户想要远程控制网络，比如在到家之前打开某些节点，则需要网关。
@ -540,6 +540,7 @@ ESP-BLE-MESH 常见问题手册
- :code:`Bluetooth --> Blutooth controller --> BLE full scan feature supported.`
- :code:`Wi-Fi --> Software controls Wi-Fi/Bluetooth coexistence --> Wi-Fi`
.. _ble-mesh-faq-fast-provisioning:
4. 快速配网
@ -662,4 +663,4 @@ ESP-BLE-MESH 常见问题手册
7.4 如何在不更改 menuconfig 输出级别的情况下改变 log 级别？
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
无需使用 menuconfig，可以通过 API :cpp:func:`esp_log_level_set` 修改 log 的输出级别。
无需使用 menuconfig，可以通过 API :cpp:func:`esp_log_level_set` 修改 log 的输出级别。

89
docs/zh_CN/api-guides/fatal-errors.rst
Wyświetl plik

@ -12,14 +12,17 @@
- CPU 异常：|CPU_EXCEPTIONS_LIST|
- 系统级检查错误：
- :doc:`中断看门狗 <../api-reference/system/wdts>` 超时
- :doc:`任务看门狗 <../api-reference/system/wdts>` 超时（只有开启 :ref:`CONFIG_ESP_TASK_WDT_PANIC` 后才会触发严重错误）
- 高速缓存访问错误
- 掉电检测事件
- 堆栈溢出
- Stack 粉碎保护检查
- Heap 完整性检查
- 未定义行为清理器（UBSAN）检查
.. list::
- :doc:`中断看门狗 <../api-reference/system/wdts>` 超时
- :doc:`任务看门狗 <../api-reference/system/wdts>` 超时（只有开启 :ref:`CONFIG_ESP_TASK_WDT_PANIC` 后才会触发严重错误）
- 高速缓存访问错误
:CONFIG_ESP_SYSTEM_MEMPROT_FEATURE: - 内存保护故障
- 掉电检测事件
- 堆栈溢出
- 堆栈粉碎保护检查
- 堆完整性检查
- 未定义行为清理器 (UBSAN) 检查
- 使用 ``assert``、``configASSERT`` 等类似的宏断言失败。
@ -60,17 +63,21 @@
- 调用 GDB Stub（``CONFIG_ESP_SYSTEM_PANIC_GDBSTUB``）
启动 GDB 服务器，通过控制台 UART 接口与 GDB 进行通信。详细信息请参阅 :ref:`GDB-Stub`。
启动 GDB 服务器，通过控制台 UART 接口与 GDB 进行通信。该选项只提供只读调试或者事后调试，详细信息请参阅 `GDB Stub`_。
- 调用动态 GDB Stub (``ESP_SYSTEM_GDBSTUB_RUNTIME``)
启动 GDB 服务器，通过控制台 UART 接口与 GDB 进行通信。该选项允许用户在程序运行时对其进行调试、设置断点和改变其执行方式等，详细信息请参阅 `GDB Stub`_。
紧急处理程序的行为还受到另外两个配置项的影响：
- 如果使能了 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_DEBUG_OCDAWARE` （默认），紧急处理程序会检测 {IDF_TARGET_NAME} 是否已经连接 JTAG 调试器。如果检测成功，程序会暂停运行，并将控制权交给调试器。在这种情况下，寄存器和回溯不会被打印到控制台，并且也不会使用 GDB Stub 和 Core Dump 的功能。
- 如果使能了 :doc:`内核转储 <core_dump>` 功能，系统状态（任务堆栈和寄存器）会被转储到 Flash 或者 UART 以供后续分析。
- 如果使能了 :doc:`内核转储 <core_dump>` 功能，系统状态（任务堆栈和寄存器）会被转储到 flash 或者 UART 以供后续分析。
- 如果 :ref:`CONFIG_ESP_PANIC_HANDLER_IRAM` 被禁用（默认情况下禁用），紧急处理程序的代码会放置在 Flash 而不是 IRAM 中。这意味着，如果 ESP-IDF 在 Flash 高速缓存禁用时崩溃，在运行 GDB Stub 和内核转储之前紧急处理程序会自动重新使能 Flash 高速缓存。如果 Flash 高速缓存也崩溃了，这样做会增加一些小风险。
- 如果 :ref:`CONFIG_ESP_PANIC_HANDLER_IRAM` 被禁用（默认情况下禁用），紧急处理程序的代码会放置在 flash 而不是 IRAM 中。这意味着，如果 ESP-IDF 在 flash 高速缓存禁用时崩溃，在运行 GDB Stub 和内核转储之前紧急处理程序会自动重新使能 flash 高速缓存。如果 flash 高速缓存也崩溃了，这样做会增加一些小风险。
如果使能了该选项，紧急处理程序的代码（包括所需的 UART 函数）会放置在 IRAM 中。当禁用 Flash 高速缓存（如写入 SPI flash）时或触发异常导致 Flash 高速缓存崩溃时，可用此选项调试一些复杂的崩溃问题。
如果使能了该选项，紧急处理程序的代码（包括所需的 UART 函数）会放置在 IRAM 中，导致 SRAM 中的可用内存空间变小。当禁用 flash 高速缓存（如写入 SPI flash）时或触发异常导致 flash 高速缓存崩溃时，可用此选项调试一些复杂的崩溃问题。
下图展示了紧急处理程序的行为：
@ -162,7 +169,7 @@
回溯行包含了当前任务中每个堆栈帧的 PC:SP 对（PC 是程序计数器，SP 是堆栈指针）。如果在 ISR 中发生了严重错误，回溯会同时包括被中断任务的 PC:SP 对，以及 ISR 中的 PC:SP 对。
如果使用了 :doc:`IDF 监视器 <tools/idf-monitor>`，该工具会将程序计数器的值转换为对应的代码位置（函数名，文件名，行号），并加以注释
如果使用了 :doc:`IDF 监视器 <tools/idf-monitor>`，该工具会将程序计数器的值转换为对应的代码位置（函数名，文件名，行号），并加以注释：
.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA
@ -227,16 +234,16 @@
虽然以上的回溯信息非常方便，但要求用户使用 :doc:`IDF 监视器 <tools/idf-monitor>`。因此，如果用户希望使用其它的串口监控软件也能显示堆栈回溯信息，则需要在 menuconfig 中启用 :ref:`CONFIG_ESP_SYSTEM_USE_EH_FRAME` 选项。
该选项会让编译器为项目的每个函数生成 DWARF 信息。然后，当 CPU 异常发生时，紧急处理程序将解析这些数据并生成出错任务的堆栈回溯信息。输出结果如下：
::
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
这些 ``PC:SP`` 对代表当前任务每一个栈帧的程序计数器值（Program Counter）和栈顶地址（Stack Pointer）。
:ref:`CONFIG_ESP_SYSTEM_USE_EH_FRAME` 选项的主要优点是，回溯信息可以由程序自己解析生成并打印 (而不依靠 :doc:`IDF 监视器 <tools/idf-monitor>`)。但是该选项会导致编译后的二进制文件更大（增幅可达 20% 甚至 100%）。此外，该选项会将调试信息也保存在二进制文件里。因此，强烈不建议用户在量产/生产版本中启用该选项。
若要查找发生严重错误的代码位置，请查看 "Backtrace" 的后面几行，发生严重错误的代码显示在顶行，后续几行显示的是调用堆栈。
.. _GDB-Stub:
@ -293,18 +300,18 @@ Guru Meditation 错误
- FreeRTOS 中的任务函数已返回。在 FreeRTOS 中，如果想终止任务函数，需要调用 :cpp:func:`vTaskDelete` 函数释放当前任务的资源，而不是直接返回。
- 无法从 SPI Flash 中加载下一条指令，这通常发生在：
- 无法从 SPI flash 中读取下一条指令，这通常发生在：
- 应用程序将 SPI Flash 的引脚重新配置为其它功能（如 GPIO，UART 等等）。有关 SPI Flash 引脚的详细信息，请参阅硬件设计指南和芯片/模组的数据手册。
- 应用程序将 SPI flash 的管脚重新配置为其它功能（如 GPIO、UART 等）。有关 SPI flash 管脚的详细信息，请参阅硬件设计指南和芯片/模组的数据手册。
- 某些外部设备意外连接到 SPI Flash 的引脚上，干扰了 {IDF_TARGET_NAME} 和 SPI Flash 之间的通信。
- 某些外部设备意外连接到 SPI flash 的管脚上，干扰了 {IDF_TARGET_NAME} 和 SPI flash 之间的通信。
.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA
InstrFetchProhibited
^^^^^^^^^^^^^^^^^^^^
此 CPU 异常表示 CPU 无法加载指令，因为指令的地址不在 IRAM 或者 IROM 中的有效区域中。
此 CPU 异常表示 CPU 无法读取指令，因为指令的地址不在 IRAM 或者 IROM 中的有效区域中。
通常这意味着代码中调用了并不指向有效代码块的函数指针。这种情况下，可以查看 ``PC`` （程序计数器）寄存器的值并做进一步判断：若为 0 或者其它非法值（即只要不是 ``0x4xxxxxxx`` 的情况），则证实确实是该原因。
@ -321,16 +328,16 @@ Guru Meditation 错误
LoadStoreAlignment
^^^^^^^^^^^^^^^^^^
应用程序尝试读取/写入的内存位置不符合加载/存储指令对字节对齐大小的要求，例如，32 位加载指令只能访问 4 字节对齐的内存地址，而 16 位加载指令只能访问 2 字节对齐的内存地址。
应用程序尝试读取/写入的内存位置不符合加载/存储指令对字节对齐大小的要求，例如，32 位读取指令只能访问 4 字节对齐的内存地址，而 16 位写入指令只能访问 2 字节对齐的内存地址。
LoadStoreError
^^^^^^^^^^^^^^
这类异常通常发生于以下几种场合:
- 应用程序尝试从仅支持 32 位加载/存储的内存区域执行 8 位或 16 位加载/存储操作，例如，解引用一个指向指令内存区域（比如 IRAM 或者 IROM）的 char* 指针就会触发这个错误。
- 应用程序尝试从仅支持 32 位读取/写入的内存区域执行 8 位或 16 位加载/存储操作，例如，解引用一个指向指令内存区域（比如 IRAM 或者 IROM）的 char* 指针就会触发这个错误。
- 应用程序尝试保存数据到只读的内存区域（比如 IROM 或者 DROM）也会触发这个错误。
- 应用程序尝试写入数据到只读的内存区域（比如 IROM 或者 DROM）也会触发这个错误。
Unhandled debug exception
^^^^^^^^^^^^^^^^^^^^^^^^^
@ -339,10 +346,10 @@ Guru Meditation 错误
Debug exception reason: Stack canary watchpoint triggered (task_name)
此错误表示应用程序写入的位置越过了 ``task_name`` 任务堆栈的末尾，请注意，并非每次堆栈溢出都会触发此错误。任务有可能会绕过堆栈金丝雀（stack canary）的位置访问堆栈，在这种情况下，监视点就不会被触发。
此错误表示应用程序写入的位置越过了 ``task_name`` 任务堆栈的末尾，请注意，并非每次堆栈溢出都会触发此错误。任务有可能会绕过堆栈金丝雀（stack canary）的位置访问内存，在这种情况下，监视点就不会被触发。
.. only:: CONFIG_IDF_TARGET_ARCH_RISCV
Instruction address misaligned
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -371,12 +378,26 @@ Interrupt wdt timeout on CPU0 / CPU1
|CACHE_ERR_MSG|
^^^^^^^^^^^^^^^
在某些情况下，ESP-IDF 会暂时禁止通过高速缓存访问外部 SPI Flash 和 SPI RAM，例如在使用 spi_flash API 读取/写入/擦除/映射 SPI Flash 的时候。在这些情况下，任务会被挂起，并且未使用 ``ESP_INTR_FLAG_IRAM`` 注册的中断处理程序会被禁用。请确保任何使用此标志注册的中断处理程序所访问的代码和数据分别位于 IRAM 和 DRAM 中。更多详细信息请参阅 :ref:`SPI Flash API 文档 <iram-safe-interrupt-handlers>`。
在某些情况下，ESP-IDF 会暂时禁止通过高速缓存访问外部 SPI flash 和 SPI RAM，例如在使用 spi_flash API 读取/写入/擦除/映射 SPI flash 的时候。在这些情况下，任务会被挂起，并且未使用 ``ESP_INTR_FLAG_IRAM`` 注册的中断处理程序会被禁用。请确保任何使用此标志注册的中断处理程序所访问的代码和数据分别位于 IRAM 和 DRAM 中。更多详细信息请参阅 :ref:`SPI flash API 文档 <iram-safe-interrupt-handlers>`。
其它严重错误
.. only:: CONFIG_ESP_SYSTEM_MEMPROT_FEATURE
Memory protection fault
^^^^^^^^^^^^^^^^^^^^^^^
ESP-IDF 中使用 {IDF_TARGET_NAME} 的权限控制功能来防止以下类型的内存访问：
* 程序加载后向指令 RAM 写入代码
* 从数据 RAM （用于堆、静态 .data 和 .bss 区域）执行代码
该类操作对于大多数程序来说并不必要，禁止此类操作往往使软件漏洞更难被利用。依赖动态加载或自修改代码的应用程序可以使用 :ref:`CONFIG_ESP_SYSTEM_MEMPROT_FEATURE` 选项来禁用此项保护。
发生故障时，紧急处理程序会报告故障的地址和引起故障的内存访问的类型。
其他严重错误
------------
欠压
掉电
^^^^
{IDF_TARGET_NAME} 内部集成掉电检测电路，并且会默认启用。如果电源电压低于安全值，掉电检测器可以触发系统复位。掉电检测器可以使用 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_BROWNOUT_DET` 和 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_BROWNOUT_DET_LVL_SEL` 这两个选项进行设置。
@ -389,7 +410,7 @@ Interrupt wdt timeout on CPU0 / CPU1
请注意，如果电源电压快速下降，则只能在控制台上看到部分打印信息。
Heap 不完整
堆不完整
^^^^^^^^^^^
ESP-IDF 堆的实现包含许多运行时的堆结构检查，可以在 menuconfig 中开启额外的检查（“Heap Poisoning”）。如果其中的某项检查失败，则会打印类似如下信息::
@ -400,10 +421,10 @@ ESP-IDF 堆的实现包含许多运行时的堆结构检查，可以在 menuconf
更多详细信息，请查阅 :doc:`堆内存调试 <../api-reference/system/heap_debug>` 文档。
Stack 粉碎
堆栈粉碎
^^^^^^^^^^
Stack 粉碎保护（基于 GCC ``-fstack-protector*`` 标志）可以通过 ESP-IDF 中的 :ref:`CONFIG_COMPILER_STACK_CHECK_MODE` 选项来开启。如果检测到 Stack 粉碎，则会打印类似如下的信息::
堆栈粉碎保护（基于 GCC ``-fstack-protector*`` 标志）可以通过 ESP-IDF 中的 :ref:`CONFIG_COMPILER_STACK_CHECK_MODE` 选项来开启。如果检测到堆栈粉碎，则会打印类似如下的信息::
Stack smashing protect failure!
@ -412,7 +433,7 @@ Stack 粉碎保护（基于 GCC ``-fstack-protector*`` 标志）可以通过 ESP
Backtrace: 0x4008e6c0:0x3ffc1780 0x4008e8b7:0x3ffc17a0 0x400d2138:0x3ffc17c0 0x400e79d5:0x3ffc17e0 0x400e79a7:0x3ffc1840 0x400e79df:0x3ffc18a0 0x400e2235:0x3ffc18c0 0x400e1916:0x3ffc18f0 0x400e19cd:0x3ffc1910 0x400e1a11:0x3ffc1930 0x400e1bb2:0x3ffc1950 0x400d2c44:0x3ffc1a80
0
回溯信息会指明发生 Stack 粉碎的函数，建议检查函数中是否有代码访问局部数组时发生了越界。
回溯信息会指明发生堆栈粉碎的函数，建议检查函数中是否有代码访问局部数组时发生了越界。
.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA
@ -442,7 +463,7 @@ Stack 粉碎保护（基于 GCC ``-fstack-protector*`` 标志）可以通过 ESP
默认情况下未启用 UBSAN。可以通过在构建系统中添加编译器选项 ``-fsanitize=undefined`` 在文件、组件或项目级别上使能 UBSAN。
在对使用硬件寄存器头文件（``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 文件的末尾添加以下内容::

2
docs/zh_CN/api-guides/wifi.rst
Wyświetl plik

@ -1311,7 +1311,7 @@ WPA2-Enterprise 是企业无线网络的安全认证机制。在连接到接入
- PAP: 密码认证协议
- CHAP: 询问握手身份验证协议
- MSCHAP 和 MSCHAP-V2
- EAP-FAST: 这是一种基于受保护的访问凭据 (PAC) 的认证方法，使用身份验证和密码。目前使用此功能时需要禁用 USE_MBEDTLS_CRYPTO 标志。
请查看 :example:`wifi/wifi_enterprise` 获取关于证书创建以及如何在 {IDF_TARGET_NAME} 上运行 wpa2_enterprise 示例的详细信息。

22
docs/zh_CN/api-reference/storage/spi_flash.rst
Wyświetl plik

@ -7,12 +7,12 @@ SPI Flash API
--------
Spi_flash 组件提供外部 flash 数据读取、写入、擦除和内存映射相关的 API 函数，同时也提供了更高层级的，面向分区的 API 函数（定义在 :doc:`分区表 </api-guides/partition-tables>` 中）。
与 ESP-IDF V4.0 之前的 API 不同，这一版 `esp_flash_*` API 功能并不局限于主 SPI Flash 芯片（即运行程序的 SPI Flash 芯片）。使用不同的芯片指针，您可以访问连接到 SPI0/1 或 SPI2 总线的外部 flash 芯片。
与 ESP-IDF V4.0 之前的 API 不同，这一版 `esp_flash_*` API 功能并不局限于主 SPI flash 芯片（即运行程序的 SPI flash 芯片）。使用不同的芯片指针，您可以访问连接到 SPI0/1 或 SPI2 总线的外部 flash 芯片。
.. note::
大多数 `esp_flash_*` API 使用 SPI1，SPI2 等外设而非通过 SPI0 上的 cache。这使得它们不仅能访问主 flash，也能访问外部 flash 。
而由于 cache 的限制，所有经过 cache 的操作都只能对主 flash 进行。这些操作的地址同样受到 cache 能力的限制。Cache 无法访问外部 flash 或者高于它能力的地址段。这些 cache 操作包括：mmap ，加密读写，执行代码或者访问在 flash 中的变量。
.. note::
@ -39,6 +39,14 @@ Flash 特性支持情况
6. XMC
7. BOYA
.. only:: esp32s3
下列芯片支持八线模式 (OPI)：
1. MXIC
关于如何为具有不同 flash 和 PSRAM 容量的开发板设置 menuconfig，请参考 :ref:`SPI flash 和片外 SPI RAM 设置 <flash-psram-configuration>`。
当前驱动支持以下厂家/型号的 flash 的 32 位地址范围的访问：
1. W25Q256
@ -80,7 +88,7 @@ SPI Flash 访问 API
SPI Flash 容量
--------------
SPI flash 容量存储于引导程序映像头部（烧录偏移量为 0x1000）的一个字段。
SPI flash 容量存储于引导程序镜像头部（烧录偏移量为 0x1000）的一个字段。
默认情况下，引导程序写入 flash 时，esptool.py 将引导程序写入 flash 时，会自动检测 SPI flash 容量，同时使用正确容量更新引导程序的头部。您也可以在工程配置中设置 :envvar:`CONFIG_ESPTOOLPY_FLASHSIZE`，生成固定的 flash 容量。
@ -96,7 +104,7 @@ SPI1 Flash 并发约束
.. attention::
指令/数据 cache（用以执行固件）与 SPI1 外设（由像 SPI flash 驱动一样的驱动程序控制）共享 SPI0/1 总线。因此，在 SPI1 总线上调用 SPI Flash API（包括访问主 flash）会对整个系统造成显著的影响。更多细节，参见 :doc:`spi_flash_concurrency`。
指令/数据 cache（用以执行固件）与 SPI1 外设（由像 SPI flash 驱动一样的驱动程序控制）共享 SPI0/1 总线。因此，在 SPI1 总线上调用 SPI flash API（包括访问主 flash）会对整个系统造成显著的影响。更多细节，参见 :doc:`spi_flash_concurrency`。
.. _flash-partition-apis:
@ -123,7 +131,7 @@ SPI Flash 加密
您可以对 SPI flash 内容进行加密，并在硬件层对其进行透明解密。
请参阅 :doc:`Flash 加密文档 </security/flash-encryption>`，查看详细信息。
请参阅 :doc:`flash 加密 </security/flash-encryption>`，查看详细信息。
内存映射 API
------------------
@ -190,7 +198,7 @@ OS 函数
OS 函数层目前提供访问锁和延迟的方法。
锁（见 :ref:`spi_bus_lock`）用于解决同一 SPI 总线上的设备访问和 SPI Flash 芯片访问之间的冲突。例如：
锁（见 :ref:`spi_bus_lock`）用于解决同一 SPI 总线上的设备访问和 SPI flash 芯片访问之间的冲突。例如：
1. 经 SPI1 总线访问 flash 芯片时，应当禁用 cache（平时用于取代码和 PSRAM 数据）。
@ -248,5 +256,3 @@ Flash 加密 API 参考
-----------------------------
.. include-build-file:: inc/esp_flash_encrypt.inc

31
docs/zh_CN/versions.rst
Wyświetl plik

@ -37,7 +37,7 @@ ESP-IDF 在 GitHub 平台上的完整发布历史请见 `发布说明页面`_。
我该选择哪个版本？
----------------------
- 如有量产需求，请使用 `最新稳定版本`_ 。稳定版本已通过人工测试，后续更新仅修复 bug，主要特性不受影响（更多详情，请见 `版本管理`_ ）。请访问 `发布说明页面`_ 界面查看每一个稳定发布版本。
- 如有量产需求，请使用 `最新稳定版本`_ 。稳定版本已通过人工测试，后续更新仅修复 bug，主要特性不受影响（更多详情，请见 :ref:`versioning-scheme` ）。请访问 `发布说明页面`_ 界面查看每一个稳定发布版本。
- 如需尝试/测试 ESP-IDF 的最新特性，请使用 `最新版本（在 master 分支上） <https://docs.espressif.com/projects/esp-idf/zh_CN/latest/>`_。最新版本包含 ESP-IDF 的所有最新特性，已通过自动化测试，但尚未全部完成人工测试（因此存在一定风险）。
@ -54,7 +54,7 @@ ESP-IDF 采用了 `语义版本管理方法 <http://semver.org/>`_，即您可
- 主要版本（例 ``v3.0``）代表有重大更新，包括增加新特性、改变现有特性及移除已弃用的特性。
升级至一个新的主要版本（例 ``v2.1`` 升级至 ``v3.0``）意味着您可能需要更新您的工程代码，并重新测试您的工程，具体可参考 `发布说明页面`_ 的重大变更 (Breaking Change) 部分。
升级至一个新的主要版本（例 ``v2.1`` 升级至 ``v3.0``）意味着您可能需要更新工程代码，并重新测试工程，具体可参考 `发布说明页面`_ 的重大变更 (Breaking Change) 部分。
- 次要版本（例 ``v3.1``）代表有新增特性和 bug 修复，但现有特性不受影响，公开 API 的使用也不受影响。
@ -86,16 +86,16 @@ ESP-IDF 的每个主要版本和次要版本（V4.1、V4.2 等）的支持期限
支持期限分为“服务期”和“维护期”：
.. list-table::
:header-rows: 1
:widths: 25 25 55
.. list-table::
:header-rows: 1
:widths: 25 25 55
* - 周期
- 时长
- 是否推荐新工程使用
- 是否推荐新工程使用
* - 服务期
- 12 个月
- 是
- 是
* - 维护期
- 18 个月
- 否
@ -157,12 +157,12 @@ Git 工作流
- 随着对 beta 版本的不断测试，bug 修复将同时增加至该发布分支和 ``master`` 分支。而且，``master`` 分支可能也已经开始为下个版本开发新特性了。
- 当测试快结束时，该发布分支上将增加一个 rc 标签，代表候选发布 (Release Candidate) ，例 ``v3.1-rc1``。此时，该分支仍属于预发布版本。
- 如果一直未发现或报告重大 bug，则该预发布版本将最终增加“主要版本”（例 ``v4.0``）或“次要版本”标记（例 ``v3.1``），成为正式发布版本，并体现在 `发布说明页面`_ 。
- 后续，该版本中发现的 bug 都将在该发布分支上进行修复。人工测试完成后，该分支将增加一个 Bugfix 版本标签（例 ``v3.1.1``），并体现在 `发布说明页面`_ 。
- 后续，发布版本中发现的 bug 都将在该发布分支上进行修复。
- 发布分支上会定期进行 bug 修复，人工测试完成后，该分支将增加一个 Bugfix 版本标签（例 ``v3.1.1``），并体现在 `发布说明页面`_ 。
.. _updating:
更新 ESP-IDF
----------------
@ -225,7 +225,9 @@ Git 工作流
- 此外，您还应在后续工作中不时使用 ``git pull`` 命令，将远端 master 上的更新同步到本地。注意，在更新 master 分支后，您可能需要更改工程代码，也可能遇到新的 bug。
- 如需从 master 分支切换至一个发布分支或稳定版本，请使用 ``git checkout`` 命令。
.. important:: 强烈建议您定期使用 ``git pull`` 和 ``git submodule update --init --recursive`` 命令，确保本地副本的及时更新。旧的 master 分支相当于一个“快照”，可能存在未记录的问题，且无法获得支持。对于半稳定版本，请参考 :ref:`更新至一个发布分支`。
.. important::
强烈建议您定期使用 ``git pull`` 和 ``git submodule update --init --recursive`` 命令，确保本地副本得到及时更新。旧的 master 分支相当于一个“快照”，可能存在未记录的问题，且无法获得支持。对于半稳定版本，请参考 :ref:`更新至一个发布分支`。
.. _`更新至一个发布分支`:
@ -234,7 +236,7 @@ Git 工作流
从稳定性来说，使用“发布分支”相当于在使用 master 分支和稳定版本之间进行折衷，包含一些 master 分支上的新特性，但也同时保证可通过 beta 测试且基本完成了 bug 修复。
更多详情，请前往 GitHub 查看完整 `标签列表`_。
更多详情，请前往 GitHub 查看完整 `标签列表`_。
举例，您可以关注 ESP-IDF v3.1 分支，随时关注该分支上的 Bugfix 版本发布（ 例 ``v3.1.1`` 等）::
@ -246,11 +248,12 @@ Git 工作流
您每次在该分支上使用 ``git pull`` 时都相当于把最新的 Bugfix 版本发布更新至您的本地副本中。
.. note:: 发布分支并不会有专门的配套文档，建议您使用与本分支最接近版本的文档。
.. note::
发布分支并不会有专门的配套文档，建议您使用与本分支最接近版本的文档。
.. _`发布说明页面`: http://github.com/espressif/esp-idf/releases
.. _`分支列表`: https://github.com/espressif/esp-idf/branches
.. _`标签列表`: https://github.com/espressif/esp-idf/tags
.. _`最新稳定版本`: https://docs.espressif.com/projects/esp-idf/zh_CN/stable/
.. _`支持期限政策`: https://github.com/espressif/esp-idf/blob/master/SUPPORT_POLICY_CN.md
.. _`版本管理`: https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/versions.html