forked from espressif/esp-idf
Merge branch 'docs/sync_cn_and_en_docs' into 'master'
docs: Sync CN and EN docs Closes DOC-10736 See merge request espressif/esp-idf!38734
This commit is contained in:
Shen Meng Jing
@@ -87,7 +87,7 @@ The following optimizations improve the execution of nearly all code, including
|
||||
:SOC_CPU_HAS_FPU: - Avoid using floating point arithmetic ``float``. Even though {IDF_TARGET_NAME} has a single precision hardware floating point unit, floating point calculations are always slower than integer calculations. If possible then use fixed point representations, a different method of integer representation, or convert part of the calculation to be integer only before switching to floating point.
|
||||
:not SOC_CPU_HAS_FPU: - Avoid using floating point arithmetic ``float``. On {IDF_TARGET_NAME} these calculations are emulated in software and are very slow. If possible, use fixed point representations, a different method of integer representation, or convert part of the calculation to be integer only before switching to floating point.
|
||||
- Avoid using double precision floating point arithmetic ``double``. These calculations are emulated in software and are very slow. If possible then use an integer-based representation, or single-precision floating point.
|
||||
:CONFIG_ESP_ROM_HAS_SUBOPTIMAL_NEWLIB_ON_MISALIGNED_MEMORY: - Avoid misaligned 4-byte memory accesses in performance-critical code sections. For potential performance improvements, consider enabling :ref:`CONFIG_LIBC_OPTIMIZED_MISALIGNED_ACCESS`. Note that properly aligned memory operations will always execute at full speed without performance penalties. Requires additional ~190 bytes of IRAM and ~870 bytes of flash memory.
|
||||
:CONFIG_ESP_ROM_HAS_SUBOPTIMAL_NEWLIB_ON_MISALIGNED_MEMORY: - Avoid misaligned 4-byte memory accesses in performance-critical code sections. For potential performance improvements, consider enabling :ref:`CONFIG_LIBC_OPTIMIZED_MISALIGNED_ACCESS`, which requires approximately 190 bytes of IRAM and 870 bytes of flash memory. Note that properly aligned memory operations will always execute at full speed without performance penalties.
|
||||
|
||||
|
||||
.. only:: esp32s2 or esp32s3 or esp32p4
|
||||
|
||||
@@ -29,5 +29,4 @@ API Reference
|
||||
HCI Vendor-specific (VS) Commands
|
||||
--------------------------------------
|
||||
|
||||
Espressif's HCI VS commands are exclusively designed for use with Espressif's Bluetooth Host stack or internal debugging purposes. Application developers **should not** initialize or invoke these VS commands in their applications. Please refer to :doc:`bt_vhci` for detailed information.
|
||||
|
||||
Espressif's HCI VS commands are exclusively designed for use with Espressif's Bluetooth Host stack or internal debugging purposes. Application developers **should not** initialize or invoke these VS commands in their applications. Please refer to :doc:`bt_vhci` for detailed information.
|
||||
|
||||
@@ -106,9 +106,9 @@ You can use the created handle to enable/disable the ISP driver and do other ISP
|
||||
|
||||
.. note::
|
||||
|
||||
ISP peripheral is necessary if MIPI CSI or ISP_DVP is used as camera controller. This means even if ISP functions are not needed, you still need to install the ISP driver by calling :cpp:func:`esp_isp_new_processor`.
|
||||
ISP peripheral is necessary if MIPI CSI or ISP_DVP is used as camera controller. This means that even if ISP functions are not needed, you still need to install the ISP driver by calling :cpp:func:`esp_isp_new_processor`.
|
||||
|
||||
If ISP functions are not needed, ISP driver supports bypassing ISP pipelines and only necessary functions will be enabled. This can be done by setting :cpp:member:`esp_isp_processor_cfg_t::bypass_isp`.
|
||||
If ISP functions are not needed, ISP driver supports bypassing ISP pipelines and enabling only the necessary functions. This can be achieved by setting :cpp:member:`esp_isp_processor_cfg_t::bypass_isp`.
|
||||
|
||||
Install ISP Auto Focus (AF) Driver
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@@ -24,8 +24,8 @@ Feature Supported by ESP-IDF but Not in Chip-ROM
|
||||
- :ref:`CONFIG_SPI_FLASH_DANGEROUS_WRITE`, enabling this option checks for flash programming to certain protected regions like bootloader, partition table or application itself.
|
||||
- :ref:`CONFIG_SPI_FLASH_ENABLE_COUNTERS`, enabling this option to collect performance data for ESP-IDF SPI flash driver APIs.
|
||||
- :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND`, enabling this option to automatically suspend or resume a long flash operation when short flash operation happens. Note that this feature is an optional feature, please do read :ref:`auto-suspend-intro` for more limitations.
|
||||
:ESP_ROM_HAS_SPI_FLASH_MMAP and SOC_SPIRAM_XIP_SUPPORTED and not esp32s3: - :ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM`, enabling this option allows you to use external PSRAM as instruction cache and read-only data cache. Some functions in the ROM don't support this usage, and a ESP-IDF version of these functions is provided.
|
||||
:esp32s3: - :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` and :ref:`CONFIG_SPIRAM_RODATA`, enabling these options allows you to use external PSRAM as instruction cache and read-only data cache. Some functions in the ROM don't support this usage, and a ESP-IDF version of these functions is provided.
|
||||
:ESP_ROM_HAS_SPI_FLASH_MMAP and SOC_SPIRAM_XIP_SUPPORTED and not esp32s3: - :ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM`, enabling this option allows you to use external PSRAM as instruction cache and read-only data cache. Some functions in the ROM don't support this usage, and an ESP-IDF version of these functions is provided.
|
||||
:esp32s3: - :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` and :ref:`CONFIG_SPIRAM_RODATA`, enabling these options allows you to use external PSRAM as instruction cache and read-only data cache. Some functions in the ROM don't support this usage, and an ESP-IDF version of these functions is provided.
|
||||
|
||||
Bugfixes Introduced in ESP-IDF but Not in Chip-ROM
|
||||
--------------------------------------------------
|
||||
|
||||
@@ -17,7 +17,7 @@ ESP-IDF provides ``console`` component, which includes building blocks needed to
|
||||
|
||||
.. note::
|
||||
|
||||
When using a console application on a chip that supports a hardware USB serial interface, we suggest to disable the secondary serial console output. The secondary output will be output-only and consequently does not make sense in an interactive application.
|
||||
When using a console application on a chip that supports a hardware USB serial interface, we suggest disabling the secondary serial console output. The secondary output will be output-only and consequently does not make sense in an interactive application.
|
||||
|
||||
Line Editing
|
||||
------------
|
||||
@@ -57,8 +57,7 @@ Linenoise library does not need explicit initialization. However, some configura
|
||||
|
||||
- :cpp:func:`linenoiseSetReadCharacteristics`
|
||||
|
||||
Set the characteristics of the read file descriptor (e.g., blocking or non blocking mode). The function has a weak definition in linenoise.c that can be overridden
|
||||
by providing a strong definition of the function.
|
||||
Set the characteristics of the read file descriptor (e.g., blocking or non-blocking mode). The function has a weak definition in ``linenoise.c`` that can be overridden by providing a strong definition of the function.
|
||||
|
||||
Main Loop
|
||||
^^^^^^^^^
|
||||
|
||||
@@ -414,11 +414,11 @@ Binary logging is a feature available only in **Log V2**, enabling logs to be tr
|
||||
|
||||
By default, when **Log V2** is enabled, the logging system uses **text mode**. Enabling binary logging reduces flash memory usage by removing log format strings from flash and sending only their addresses instead. Additionally, ``printf`` functions are not used, which reduces both stack usage and flash consumption.
|
||||
|
||||
This feature introduces the :c:macro:`ESP_LOG_ATTR_STR` macro, which relocates format strings to a ``.noload`` section, effectively removing them from the final binary image. Developers can also use this mechanism for assertions or user-defined logging messages to further minimize flash usage.
|
||||
This feature introduces the :c:macro:`ESP_LOG_ATTR_STR` macro, which relocates format strings to a ``.noload`` section, effectively removing them from the final binary image. You can also use this mechanism for assertions or user-defined logging messages to further minimize flash usage.
|
||||
|
||||
Summary of Benefits:
|
||||
|
||||
- Reduces **flash size** by approximately **10% - 35%**, depending on the application. The more extensive the logging in a program, the greater the potential savings.
|
||||
- Reduces **flash size** by approximately **10% – 35%**, depending on the application. The more extensive the logging in a program, the greater the potential savings.
|
||||
- Minimizes **stack usage** by eliminating the need for the ``vprintf``-like function for log formatting.
|
||||
- Reduces **log transmission overhead** by transmitting compact binary data.
|
||||
|
||||
@@ -429,24 +429,26 @@ Binary Logging Workflow
|
||||
|
||||
Binary logging consists of two main components:
|
||||
|
||||
1. **Chip Side**: Encodes and transmits log data:
|
||||
1. :ref:`Chip Side <chip-side>`: Encodes and transmits log data.
|
||||
|
||||
- Encoding process
|
||||
- Argument type encoding
|
||||
- Runtime argument type encoding
|
||||
- Encoding process
|
||||
- Argument type encoding
|
||||
- Runtime argument type encoding
|
||||
|
||||
2. **Host Side**: Receives and decodes data using the `esp-idf-monitor tool <https://github.com/espressif/esp-idf-monitor>`_. The ``idf.py monitor`` command automatically decodes binary logs.
|
||||
2. :ref:`Host Side <host-side>`: Receives and decodes data using the `esp-idf-monitor tool <https://github.com/espressif/esp-idf-monitor>`_. The ``idf.py monitor`` command automatically decodes binary logs.
|
||||
|
||||
- Detects binary log packets.
|
||||
- Extracts packet fields (log level, format, tag, timestamp, arguments).
|
||||
- Determines whether addresses reference:
|
||||
- Detects binary log packets.
|
||||
- Extracts packet fields (log level, format, tag, timestamp, arguments).
|
||||
- Determines whether addresses reference:
|
||||
|
||||
- **ELF file** (requires lookup)
|
||||
- **Embedded string** (contained in the packet)
|
||||
- **ELF file** (requires lookup)
|
||||
- **Embedded string** (contained in the packet)
|
||||
|
||||
- Decodes arguments using the format string and the given array of arguments.
|
||||
- Reconstructs the final log message by coupling the format string with the decoded arguments.
|
||||
- Applies terminal colorization.
|
||||
- Decodes arguments using the format string and the given array of arguments.
|
||||
- Reconstructs the final log message by coupling the format string with the decoded arguments.
|
||||
- Applies terminal colorization.
|
||||
|
||||
.. _chip-side:
|
||||
|
||||
Chip Side
|
||||
^^^^^^^^^
|
||||
@@ -484,7 +486,7 @@ The embedded string format is used if string is not present in ELF file, it foll
|
||||
Argument Type Encoding
|
||||
""""""""""""""""""""""
|
||||
|
||||
Since the format string is removed from the final binary, the chip must still identify argument types to correctly transmit them to the host. This is achieved using the :c:macro:`ESP_LOG_ARGS_TYPE` macro, which leverages the `_Generic` feature to classify user arguments at compile time into three categories: **32-bit**, **64-bit**, and **pointers**. This macro generates an **argument type array** at runtime, which is passed to ``esp_log`` before the user arguments. This ensures that:
|
||||
Since the format string is removed from the final binary, the chip must still identify argument types to correctly transmit them to the host. This is achieved using the :c:macro:`ESP_LOG_ARGS_TYPE` macro, which leverages the `_Generic` feature to classify user arguments at compile time into three categories: **32-bit**, **64-bit**, and **pointers**. This macro generates an **argument type array** at runtime and passes it to ``esp_log`` before the user arguments, ensuring that:
|
||||
|
||||
- The chip transmits data with the correct size and offset.
|
||||
- The host tool reconstructs the log message accurately.
|
||||
@@ -505,7 +507,9 @@ Binary logging supports buffer log functions such as:
|
||||
- :c:macro:`ESP_LOG_BUFFER_CHAR_LEVEL`
|
||||
- :c:macro:`ESP_LOG_BUFFER_HEXDUMP`
|
||||
|
||||
For these cases, binary log handlers check whether the format address matches predefined constants (e.g., ``ESP_BUFFER_HEX_FORMAT``). Instead of sending a format string, the handler **directly transmits raw buffer data**.
|
||||
In such cases, the binary log handler checks whether the format address matches any predefined constants (e.g., ``ESP_BUFFER_HEX_FORMAT``). If it does, the handler skips sending a format string and instead **transmits the raw buffer data directly**.
|
||||
|
||||
.. _host-side:
|
||||
|
||||
Host Side (Monitor Tool)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@@ -318,7 +318,7 @@ RTC peripherals or RTC memories do not need to be powered on during sleep in thi
|
||||
|
||||
In Light-sleep mode, if you set Kconfig option :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`， to continue using :cpp:func:`gpio_wakeup_enable` for GPIO wakeup, you need to first call :cpp:func:`rtc_gpio_init` and :cpp:func:`rtc_gpio_set_direction`, setting the RTCIO to input mode.
|
||||
|
||||
.. only:: not SOC_RTCIO_WAKE_SUPPORTED
|
||||
.. only:: not SOC_RTCIO_WAKE_SUPPORTED and not esp32h2
|
||||
|
||||
GPIO Wakeup
|
||||
^^^^^^^^^^^
|
||||
@@ -329,12 +329,20 @@ RTC peripherals or RTC memories do not need to be powered on during sleep in thi
|
||||
|
||||
.. only:: SOC_PM_SUPPORT_TOP_PD
|
||||
|
||||
.. note::
|
||||
.. note::
|
||||
|
||||
.. only:: SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP
|
||||
|
||||
In Light-sleep mode, if you set Kconfig option :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`， you can use :cpp:func:`esp_deep_sleep_enable_gpio_wakeup` directly for GPIO wakeup, because the digital IO power domain is being powered off, where the situation is the same as entering Deep-sleep.
|
||||
|
||||
.. only:: esp32h2
|
||||
|
||||
GPIO Wakeup
|
||||
^^^^^^^^^^^
|
||||
|
||||
Any IO can be used as the external input to wake up the chip from Light-sleep. Each pin can be individually configured to trigger wakeup on high or low level using the :cpp:func:`gpio_wakeup_enable` function. Then the :cpp:func:`esp_sleep_enable_gpio_wakeup` function should be called to enable this wakeup source.
|
||||
|
||||
|
||||
UART Wakeup (Light-sleep Only)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@@ -475,7 +483,9 @@ Application Examples
|
||||
:SOC_WIFI_SUPPORTED: - :example:`wifi/power_save` demonstrates the usage of Wi-Fi Modem-sleep mode and automatic Light-sleep feature to maintain Wi-Fi connections.
|
||||
:SOC_BT_SUPPORTED: - :example:`bluetooth/nimble/power_save` demonstrates the usage of Bluetooth Modem-sleep mode and automatic Light-sleep feature to maintain Bluetooth connections.
|
||||
:SOC_ULP_SUPPORTED: - :example:`system/deep_sleep` demonstrates the usage of various Deep-sleep wakeup triggers and ULP coprocessor programming.
|
||||
:not SOC_ULP_SUPPORTED: - :example:`system/deep_sleep` demonstrates the usage of Deep-sleep wakeup triggered by various sources, such as the RTC timer, GPIOs, EXT0, EXT1, supported by {IDF_TARGET_NAME}.
|
||||
:not SOC_ULP_SUPPORTED and not esp32c3 and not esp32h2: - :example:`system/deep_sleep` demonstrates the usage of Deep-sleep wakeup triggered by various sources, such as the RTC timer, GPIOs, EXT0, EXT1, supported by {IDF_TARGET_NAME}.
|
||||
:esp32c3: - :example:`system/deep_sleep` demonstrates the usage of Deep-sleep wakeup triggered by various sources, such as the RTC timer, GPIOs, supported by ESP32-C3.
|
||||
:esp32h2: - :example:`system/deep_sleep` demonstrates the usage of Deep-sleep wakeup triggered by various sources, such as the RTC timer, EXT0, EXT1, supported by ESP32-H2.
|
||||
- :example:`system/light_sleep` demonstrates the usage of Light-sleep wakeup triggered by various sources, such as the timer, GPIOs, supported by {IDF_TARGET_NAME}.
|
||||
:SOC_TOUCH_SENSOR_SUPPORTED and SOC_PM_SUPPORT_TOUCH_SENSOR_WAKEUP: - :example:`peripherals/touch_sensor/touch_sens_sleep` demonstrates the usage of Light-sleep and Deep-sleep wakeup triggered by the touch sensor.
|
||||
|
||||
|
||||
@@ -87,6 +87,7 @@
|
||||
:SOC_CPU_HAS_FPU: - 避免使用浮点运算 ``float``。尽管 {IDF_TARGET_NAME} 具备单精度浮点运算器，但是浮点运算总是慢于整数运算。因此可以考虑使用不同的整数表示方法进行运算，如定点表示法，或者将部分计算用整数运算后再切换为浮点运算。
|
||||
:not SOC_CPU_HAS_FPU: - 避免使用浮点运算 ``float``。{IDF_TARGET_NAME} 通过软件模拟进行浮点运算，因此速度非常慢。可以考虑使用不同的整数表示方法进行运算，如定点表示法，或者将部分计算用整数运算后再切换为浮点运算。
|
||||
- 避免使用双精度浮点运算 ``double``。{IDF_TARGET_NAME} 通过软件模拟进行双精度浮点运算，因此速度非常慢。可以考虑使用基于整数的表示方法或单精度浮点数。
|
||||
:CONFIG_ESP_ROM_HAS_SUBOPTIMAL_NEWLIB_ON_MISALIGNED_MEMORY: - 在性能要求较高的代码段中，应避免执行未对齐的 4 字节内存访问。为提升性能，可以考虑启用 :ref:`CONFIG_LIBC_OPTIMIZED_MISALIGNED_ACCESS`。启用此选项将额外占用约 190 字节的 IRAM 和 870 字节的 flash 存储。请注意，正确对齐的内存操作始终能够以全速执行，且不会产生性能损耗。
|
||||
|
||||
|
||||
.. only:: esp32s2 or esp32s3 or esp32p4
|
||||
|
||||
@@ -80,7 +80,6 @@ ECDSA 密钥可以通过 ``idf.py`` 脚本在外部编程。以下是关于编
|
||||
|
||||
{IDF_TARGET_NAME} 的 ECDSA 外设还支持使用确定性推导参数 K 来生成确定性签名，详见 `RFC 6979 <https://tools.ietf.org/html/rfc6979>`_ 第 3.2 节。
|
||||
|
||||
|
||||
生成非确定性签名
|
||||
----------------
|
||||
|
||||
|
||||
@@ -104,6 +104,11 @@ ISP 驱动程序需要由 :cpp:type:`esp_isp_processor_cfg_t` 指定配置。
|
||||
|
||||
使用上述句柄，可以启用/禁用 ISP 驱动程序，也可以安装其他 ISP 模块。
|
||||
|
||||
.. note::
|
||||
|
||||
如果将 MIPI CSI 或 ISP_DVP 用作摄像头控制器，则必须使用 ISP 外设。因此即便无需使用 ISP 功能，也要调用 :cpp:func:`esp_isp_new_processor` 函数安装 ISP 驱动程序。
|
||||
|
||||
如果无需使用 ISP 功能，也可以设置 :cpp:member:`esp_isp_processor_cfg_t::bypass_isp`，使 ISP 驱动程序绕过 ISP 流水线，仅启用必要的功能。
|
||||
|
||||
安装 ISP 自动对焦 (AF) 驱动程序
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@@ -24,6 +24,8 @@ ESP-IDF 支持但不包含在芯片 ROM 中的功能
|
||||
- :ref:`CONFIG_SPI_FLASH_DANGEROUS_WRITE`，启用此选项会检查是否对某些受保护的区域（如引导加载程序、分区表或应用程序本身）进行了 flash 编程。
|
||||
- :ref:`CONFIG_SPI_FLASH_ENABLE_COUNTERS`，启用此选项以收集 ESP-IDF SPI flash 驱动程序 API 的性能数据。
|
||||
- :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND`，启用此选项可在 flash 短时操作时自动挂起或恢复 flash 长时操作。请注意，此功能为可选功能，详情请参阅 :ref:`auto-suspend-intro`。
|
||||
:ESP_ROM_HAS_SPI_FLASH_MMAP and SOC_SPIRAM_XIP_SUPPORTED and not esp32s3: - :ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM`，启用该选项后，可将外部 PSRAM 用作指令 cache 和只读数据 cache。但请注意，ROM 中的某些函数不支持此用法，而 ESP-IDF 提供了这些 ROM 函数的替代版本。
|
||||
:esp32s3: - 启用 :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` 和 :ref:`CONFIG_SPIRAM_RODATA` 后，可将外部 PSRAM 用作指令 cache 和只读数据 cache。但请注意，ROM 中的某些函数不支持此用法，而 ESP-IDF 提供了这些 ROM 函数的替代版本。
|
||||
|
||||
在 ESP-IDF 中引入，但不包含在芯片 ROM 中的错误修复
|
||||
--------------------------------------------------
|
||||
|
||||
@@ -45,12 +45,19 @@ Linenoise 库不需要显式地初始化，但是在调用行编辑函数之前
|
||||
|
||||
- :cpp:func:`linenoiseAllowEmpty`
|
||||
|
||||
设置 linenoise 库收到空行的解析行为，设置为 ``true`` 时返回长度为零的字符串 (``""``) ，设置为 ``false`` 时返回 ``NULL``。默认情况下，将返回长度为零的字符串。
|
||||
设置 linenoise 库收到空行的解析行为，设置为 ``true`` 时返回长度为零的字符串 (``""``) ，设置为 ``false`` 时返回 ``NULL``。默认情况下，将返回长度为零的字符串。
|
||||
|
||||
- :cpp:func:`linenoiseSetMaxLineLen`
|
||||
|
||||
设置 linenoise 库中每行的最大长度，默认长度为 4096 字节，可以通过更新该默认值来优化 RAM 内存的使用。
|
||||
设置 linenoise 库中每行的最大长度，默认长度为 4096 字节，可以通过更新该默认值来优化 RAM 内存的使用。
|
||||
|
||||
- :cpp:func:`linenoiseSetReadFunction`
|
||||
|
||||
设置 linenoise 使用的读取函数。
|
||||
|
||||
- :cpp:func:`linenoiseSetReadCharacteristics`
|
||||
|
||||
设置用于读取的文件描述符的特性（例如，阻塞模式或非阻塞模式）。该函数在 ``linenoise.c`` 中具有一个弱定义，可通过强定义进行覆盖。
|
||||
|
||||
主循环
|
||||
^^^^^^
|
||||
|
||||
@@ -629,7 +629,8 @@ ESP-IDF 集成了用于请求 :ref:`堆内存信息 <heap-information>`、:ref:`
|
||||
应用示例
|
||||
--------------------
|
||||
|
||||
- :example:`system/heap_task_tracking` 演示了如何使用堆任务跟踪功能跟踪分配给每个任务的堆内存。
|
||||
- :example:`system/heap_task_tracking/basic` 演示了堆任务跟踪的概览功能，用于导出每个任务在堆内存使用方面的统计信息概要。
|
||||
- :example:`system/heap_task_tracking/advanced` 演示了堆任务跟踪中统计信息函数的用法，用于访问每个任务在堆内存使用方面的完整统计数据。
|
||||
|
||||
API 参考 - 堆内存跟踪
|
||||
----------------------------
|
||||
|
||||
@@ -222,16 +222,21 @@ ESP-IDF 提供了一套灵活的日志系统，包括两个可配置版本 **Log
|
||||
- 默认为 ``0``，即启用所有格式化项，如颜色、时间戳、标记和末尾换行。
|
||||
- 定义为 ``1`` 时，为指定范围禁用所有的格式化项。
|
||||
|
||||
- **ESP_LOG_COLOR_DISABLED**： 要求 :ref:`CONFIG_LOG_COLORS_SUPPORT` 启用。
|
||||
- **ESP_LOG_COLOR_DISABLED**：要求启用 :ref:`CONFIG_LOG_COLORS_SUPPORT`。
|
||||
|
||||
- 如果全局颜色 (:ref:`CONFIG_LOG_COLORS`) 已禁用，则定义为 ``0``，以启用指定范围的颜色输出。
|
||||
- 如果启用了全局颜色 (:ref:`CONFIG_LOG_COLORS`)，则定义为 ``1``，表示禁用指定范围的颜色输出。
|
||||
|
||||
- **ESP_LOG_TIMESTAMP_DISABLED**： 要求启用 :ref:`CONFIG_LOG_TIMESTAMP_SUPPORT`。
|
||||
- **ESP_LOG_TIMESTAMP_DISABLED**：要求启用 :ref:`CONFIG_LOG_TIMESTAMP_SUPPORT`。
|
||||
|
||||
- 如果已禁用全局时间戳（:ref:`CONFIG_LOG_TIMESTAMP_SOURCE`），则定义为 ``0``，以启用指定范围的时间戳输出。
|
||||
- 如果全局时间戳（:ref:`CONFIG_LOG_TIMESTAMP_SOURCE`）已启用，则定义为 ``1``，表示禁用指定范围的时间戳输出。
|
||||
|
||||
- **ESP_LOG_MODE_BINARY_EN**：要求启用 ``CONFIG_LOG_MODE_BINARY`` 或 ``CONFIG_BOOTLOADER_LOG_MODE_BINARY`` 配置项。
|
||||
|
||||
- 将 ``ESP_LOG_MODE_BINARY_EN`` 设置为 ``0`` 在常规使用中意义不大，因为日志仍会以二进制模式输出。但格式字符串不会从 flash 中移除，且运行时仍会进行参数分析。此设置可用于调试或测试等特定场景。
|
||||
- 启用文本日志模式时，``ESP_LOG_MODE_BINARY_EN`` 会被忽略并自动定义为 ``0``，即便手动将其设置为 ``1`` 也是无效的，
|
||||
|
||||
设置每条日志的输出格式
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@@ -402,6 +407,118 @@ ESP-IDF 提供了一套灵活的日志系统，包括两个可配置版本 **Log
|
||||
|
||||
输出中包含的行数取决于缓冲区的大小。
|
||||
|
||||
二进制日志
|
||||
----------
|
||||
|
||||
二进制日志是一项仅在 **Log V2** 中可用的功能，允许日志以二进制格式而非文本格式进行传输。该功能可通过 Kconfig 选项分别为 **引导加载程序** (``CONFIG_BOOTLOADER_LOG_MODE_BINARY``) 和 **应用程序** (``CONFIG_LOG_MODE_BINARY``) 配置。
|
||||
|
||||
默认情况下，当启用 **Log V2** 时，日志系统使用 **文本模式**。启用二进制日志可减少 flash 内存占用，因为日志格式字符串将从 flash 中移除，仅发送其地址。此外，不使用 ``printf`` 函数也将进一步减少堆栈使用和 flash 消耗。
|
||||
|
||||
该功能引入了 :c:macro:`ESP_LOG_ATTR_STR` 宏，将格式字符串移至 ``.noload`` 段，并从最终的二进制镜像中移除。该机制还能优化断言或自定义的日志消息，从而进一步降低 flash 消耗。
|
||||
|
||||
优势总结：
|
||||
|
||||
- 依据应用程序具体情况，最多可减少约 **10% ～ 35%** 的 **flash 占用**。日志越多，节省空间越显著。
|
||||
- 通过移除类似 ``vprintf`` 的日志格式化函数，降低 **堆栈使用率**。
|
||||
- 以紧凑的二进制数据传输，减少 **日志传输开销**。
|
||||
|
||||
在资源高度受限的环境中，二进制日志优势显著，有助于优化 flash 占用和提升日志效率。
|
||||
|
||||
二进制日志工作流程
|
||||
------------------
|
||||
|
||||
二进制日志由两个主要部分组成：
|
||||
|
||||
1. :ref:`芯片端 <chip-side>`：编码并传输日志数据。
|
||||
|
||||
- 编码流程
|
||||
- 参数类型编码
|
||||
- 运行时参数类型编码
|
||||
|
||||
2. :ref:`主机端 <host-side>`：使用 `esp-idf-monitor 工具 <https://github.com/espressif/esp-idf-monitor>`_ 接收并解码数据。``idf.py monitor`` 命令可自动解析二进制日志。
|
||||
|
||||
- 识别二进制日志数据包。
|
||||
- 提取数据包字段（日志等级、格式、标签、时间戳、参数）。
|
||||
- 判断地址是否引用：
|
||||
|
||||
- **ELF 文件** （需要查找）
|
||||
- **内嵌字符串** （包含在数据包中）
|
||||
|
||||
- 使用格式字符串与参数数组解码日志参数。
|
||||
- 将格式字符串与解码后的参数结合，重构最终日志消息。
|
||||
- 应用终端颜色输出。
|
||||
|
||||
.. _chip-side:
|
||||
|
||||
芯片端
|
||||
^^^^^^
|
||||
|
||||
编码流程
|
||||
""""""""
|
||||
|
||||
二进制日志以结构化数据包形式进行传输。如果字符串存在于 ELF 文件中，则以地址形式发送；如果为运行时生成的字符串，则采用内嵌字符串格式发送。
|
||||
|
||||
数据包结构如下：
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[0] - 消息类型（1：引导加载程序、2：应用程序……）
|
||||
[1] - 控制字节（日志等级、版本、time_64bits 标志）
|
||||
[2] - 长度（10 位，最大 1023 字节）
|
||||
[3-6] - 格式地址（若存在于 ELF 中）或内嵌字符串
|
||||
[7-10] - 标签地址（若存在于 ELF 中）或内嵌字符串
|
||||
[11-14] - 时间戳（若为 32 位）；若时间戳为 64 位，则占用 [11-18]，并在控制字节中设置 time_64bits 标志
|
||||
[...] - 参数（可选）：参数数组，包括 32 位、64 位、指针、内嵌字符串/数据等
|
||||
[15] - CRC8 校验和
|
||||
|
||||
若字符串不在 ELF 文件中，将使用内嵌字符串格式，结构如下：
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[0] - 嵌入标识符 (0xFF - 0xFC)
|
||||
[0,1] - （10 位）字符串负长度 = 1 - len(str)
|
||||
[...] - 字符串内容
|
||||
|
||||
.. note::
|
||||
|
||||
数据包中所有的多字节字段均采用大端 (big-endian) 编码。
|
||||
|
||||
参数类型编码
|
||||
""""""""""""
|
||||
|
||||
由于格式字符串已从最终的二进制文件中移除，芯片仍需识别参数类型以实现正确的传输。为此，引入了 :c:macro:`ESP_LOG_ARGS_TYPE` 宏，借助 `_Generic` 功能在编译期间将用户参数划分为三类：**32 位**、**64 位** 和 **指针**。该宏在运行时生成一个 **参数类型数组**，并在调用 ``esp_log`` 时先于用户参数传入数组，以确保：
|
||||
|
||||
- 芯片端以正确大小和偏移传输数据。
|
||||
- 主机工具能够准确重构日志消息。
|
||||
|
||||
运行时的行为
|
||||
""""""""""""
|
||||
|
||||
``esp_log`` 函数首先检查是否启用了 **二进制日志**，若已启用，将从 ``va_list`` 中提取 **参数类型数组**。但如果未设置二进制日志标志，系统将无法预处理参数类型数组，这时日志处理器会在运行时从格式字符串中 **提取参数类型**。
|
||||
|
||||
运行时提取参数类型效率较低，不如使用 ``ESP_LOG_ATTR_STR(format) ESP_LOG_ARGS(__VA_ARGS__)`` 进行显式指定，在编译时生成参数类型数组，并将格式字符串从 flash 中移除。但在运行时提取参数类型能确保即使 **第三方库不支持二进制日志**，日志依然被正常输出。
|
||||
|
||||
buffer 日志需特殊处理
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
二进制日志支持以下 buffer 日志函数：
|
||||
|
||||
- :c:macro:`ESP_LOG_BUFFER_HEX_LEVEL`
|
||||
- :c:macro:`ESP_LOG_BUFFER_CHAR_LEVEL`
|
||||
- :c:macro:`ESP_LOG_BUFFER_HEXDUMP`
|
||||
|
||||
在处理上述函数时，二进制日志处理器会检查格式地址是否与预定义常量（如 ``ESP_BUFFER_HEX_FORMAT``）匹配。如果匹配，则 **直接发送原始 buffer 数据**，而非格式字符串。
|
||||
|
||||
.. _host-side:
|
||||
|
||||
主机端（监视器工具）
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
在 **主机端**，`esp-idf-monitor 工具 <https://github.com/espressif/esp-idf-monitor>`_ 会自动解码二进制日志。必须确保监视器工具使用正确版本的 ELF 文件。**引导加载程序** 和 **应用程序** 各自对应不同的 ELF 文件，调用 ``idf.py monitor`` 时会自动选择相应的文件。
|
||||
|
||||
当接收到 **ELF 地址** 时，监视器工具会根据 ``消息类型`` 字节 **在相应的 ELF 文件中检索对应字符串**。若 **地址以 0xFF 开头** （范围： ``0xFF - 0xFC``），则表示该字段为 **内嵌字符串**，其长度为 **10 位编码**。
|
||||
|
||||
一旦获取所有组件，系统便将其格式化并输出到终端。
|
||||
|
||||
性能测试
|
||||
----------
|
||||
|
||||
@@ -318,7 +318,7 @@ RTC 控制器中内嵌定时器，可用于在预定义的时间到达后唤醒
|
||||
|
||||
在 Light-sleep 模式下，如果设置 Kconfig 选项 :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`，为了继续使用 :cpp:func:`gpio_wakeup_enable` 用于 GPIO 唤醒， 需要先调用 :cpp:func:`rtc_gpio_init` 和 :cpp:func:`rtc_gpio_set_direction`，用于设置 RTC IO 为输入模式。
|
||||
|
||||
.. only:: not SOC_RTCIO_WAKE_SUPPORTED
|
||||
.. only:: not SOC_RTCIO_WAKE_SUPPORTED and not esp32h2
|
||||
|
||||
GPIO 唤醒
|
||||
^^^^^^^^^^^
|
||||
@@ -329,11 +329,19 @@ RTC 控制器中内嵌定时器，可用于在预定义的时间到达后唤醒
|
||||
|
||||
.. only:: SOC_PM_SUPPORT_TOP_PD
|
||||
|
||||
.. note::
|
||||
.. note::
|
||||
|
||||
.. only:: SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP
|
||||
|
||||
在 Light-sleep 模式下，如果设置 Kconfig 选项 :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`，可以使用直接调用 :cpp:func:`esp_deep_sleep_enable_gpio_wakeup` 用于 GPIO 唤醒，因为此时 digital IO 的电源域已经被关闭，这个情况类似于进入 Deep-sleep。
|
||||
在 Light-sleep 模式下，如果设置 Kconfig 选项 :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`，可以使用直接调用 :cpp:func:`esp_deep_sleep_enable_gpio_wakeup` 用于 GPIO 唤醒，因为此时 digital IO 的电源域会被断电，行为与进入 Deep-sleep 模式时相同。
|
||||
|
||||
.. only:: esp32h2
|
||||
|
||||
GPIO 唤醒
|
||||
^^^^^^^^^^^
|
||||
|
||||
任何一个 IO 都可以用作外部输入管脚，将芯片从 Light-sleep 状态唤醒。调用 :cpp:func:`gpio_wakeup_enable` 函数可以将任意管脚单独配置为在高电平或低电平触发唤醒。此后，应调用 :cpp:func:`esp_sleep_enable_gpio_wakeup` 函数来启用此唤醒源。
|
||||
|
||||
|
||||
UART 唤醒（仅适用于 Light-sleep 模式）
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
@@ -475,8 +483,10 @@ UART 输出处理
|
||||
:SOC_WIFI_SUPPORTED: - :example:`wifi/power_save` 演示如何通过 Wi-Fi Modem-sleep 模式和自动 Light-sleep 模式保持 Wi-Fi 连接。
|
||||
:SOC_BT_SUPPORTED: - :example:`bluetooth/nimble/power_save` 演示如何通过 Bluetooth Modem-sleep 模式和自动 Light-sleep 模式保持 Bluetooth 连接。
|
||||
:SOC_ULP_SUPPORTED: - :example:`system/deep_sleep` 演示如何使用 Deep-sleep 唤醒触发器和 ULP 协处理器编程。
|
||||
:not SOC_ULP_SUPPORTED: - :example:`system/deep_sleep` 演示如何通过 {IDF_TARGET_NAME} 的唤醒源，如 RTC 定时器, GPIO, EXT0, EXT1等，触发 Deep-sleep 唤醒。
|
||||
- :example:`system/light_sleep` 演示如何使用 {IDF_TARGET_NAME} 的唤醒源，如定时器，GPIO等，触发 Light-sleep 唤醒。
|
||||
:not SOC_ULP_SUPPORTED and not esp32c3 and not esp32h2: - :example:`system/deep_sleep` 演示如何通过 {IDF_TARGET_NAME} 的唤醒源，如 RTC 定时器、GPIO、EXT0、EXT1 等，触发 Deep-sleep 唤醒。
|
||||
:esp32c3: - :example:`system/deep_sleep` 演示如何通过 ESP32-C3 的唤醒源，如 RTC 定时器、GPIO 等，触发 Deep-sleep 唤醒。
|
||||
:esp32h2: - :example:`system/deep_sleep` 演示如何通过 ESP32-H2 的唤醒源，如 RTC 定时器、EXT0、EXT1 等，触发 Deep-sleep 唤醒。
|
||||
- :example:`system/light_sleep` 演示如何使用 {IDF_TARGET_NAME} 的唤醒源，如定时器，GPIO 等，触发 Light-sleep 唤醒。
|
||||
:SOC_TOUCH_SENSOR_SUPPORTED and SOC_PM_SUPPORT_TOUCH_SENSOR_WAKEUP: - :example:`peripherals/touch_sensor/touch_sens_sleep` 演示如何使用触摸传感器唤醒 Light-sleep 或 Deep-sleep。
|
||||
|
||||
API 参考
|
||||
|
||||
@@ -46,4 +46,3 @@ WPA3 企业版 Wi‑Fi 认证模式更改
|
||||
为确保与这些模式兼容，请更新您的应用程序关于认证模式的检查逻辑，将新的 ``WIFI_AUTH_WPA3_ENTERPRISE`` 和 ``WIFI_AUTH_WPA2_WPA3_ENTERPRISE`` 模式包含进来.
|
||||
|
||||
这可能涉及更新条件判断语句或认证流程，以涵盖 ``WIFI_AUTH_WPA3_ENTERPRISE`` 和 ``WIFI_AUTH_WPA2_WPA3_ENTERPRISE`` 的情况.
|
||||
|
||||
|
||||
@@ -8,4 +8,3 @@ Wi-Fi
|
||||
~~~~~~~~
|
||||
|
||||
ESP-NOW 的发包回调函数的参数从 ``uint8_t *mac_addr`` 变为 ``esp_now_send_info_t *tx_info``。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user