diff --git a/docs/en/api-guides/performance/speed.rst b/docs/en/api-guides/performance/speed.rst index fe3f8a5887..8c424ea47d 100644 --- a/docs/en/api-guides/performance/speed.rst +++ b/docs/en/api-guides/performance/speed.rst @@ -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 diff --git a/docs/en/api-reference/bluetooth/controller_vhci.rst b/docs/en/api-reference/bluetooth/controller_vhci.rst index 92768f86bb..b71314842b 100644 --- a/docs/en/api-reference/bluetooth/controller_vhci.rst +++ b/docs/en/api-reference/bluetooth/controller_vhci.rst @@ -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. diff --git a/docs/en/api-reference/peripherals/isp.rst b/docs/en/api-reference/peripherals/isp.rst index 5fdcb98f00..3503ae528a 100644 --- a/docs/en/api-reference/peripherals/isp.rst +++ b/docs/en/api-reference/peripherals/isp.rst @@ -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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/en/api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom.rst b/docs/en/api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom.rst index c87c4415a5..9a7b58e802 100644 --- a/docs/en/api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom.rst +++ b/docs/en/api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom.rst @@ -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 -------------------------------------------------- diff --git a/docs/en/api-reference/system/console.rst b/docs/en/api-reference/system/console.rst index dae47f4cdf..fc191f91d2 100644 --- a/docs/en/api-reference/system/console.rst +++ b/docs/en/api-reference/system/console.rst @@ -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 ^^^^^^^^^ diff --git a/docs/en/api-reference/system/log.rst b/docs/en/api-reference/system/log.rst index 708469a107..aa5b50b2df 100644 --- a/docs/en/api-reference/system/log.rst +++ b/docs/en/api-reference/system/log.rst @@ -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 `: 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 `_. The ``idf.py monitor`` command automatically decodes binary logs. +2. :ref:`Host Side `: Receives and decodes data using the `esp-idf-monitor tool `_. 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) ^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/en/api-reference/system/sleep_modes.rst b/docs/en/api-reference/system/sleep_modes.rst index 3cc29c02d7..70f43d8b41 100644 --- a/docs/en/api-reference/system/sleep_modes.rst +++ b/docs/en/api-reference/system/sleep_modes.rst @@ -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. diff --git a/docs/zh_CN/api-guides/performance/speed.rst b/docs/zh_CN/api-guides/performance/speed.rst index 9f5f41c27a..f879e65b7c 100644 --- a/docs/zh_CN/api-guides/performance/speed.rst +++ b/docs/zh_CN/api-guides/performance/speed.rst @@ -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 diff --git a/docs/zh_CN/api-reference/peripherals/ecdsa.rst b/docs/zh_CN/api-reference/peripherals/ecdsa.rst index 7428a132aa..31eaf4f258 100644 --- a/docs/zh_CN/api-reference/peripherals/ecdsa.rst +++ b/docs/zh_CN/api-reference/peripherals/ecdsa.rst @@ -80,7 +80,6 @@ ECDSA 密钥可以通过 ``idf.py`` 脚本在外部编程。以下是关于编 {IDF_TARGET_NAME} 的 ECDSA 外设还支持使用确定性推导参数 K 来生成确定性签名，详见 `RFC 6979 `_ 第 3.2 节。 - 生成非确定性签名 ---------------- diff --git a/docs/zh_CN/api-reference/peripherals/isp.rst b/docs/zh_CN/api-reference/peripherals/isp.rst index 9f90290d83..992f622b41 100644 --- a/docs/zh_CN/api-reference/peripherals/isp.rst +++ b/docs/zh_CN/api-reference/peripherals/isp.rst @@ -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) 驱动程序 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom.rst b/docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom.rst index 60d2d07ed3..cc2ed38203 100644 --- a/docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom.rst +++ b/docs/zh_CN/api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom.rst @@ -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 中的错误修复 -------------------------------------------------- diff --git a/docs/zh_CN/api-reference/system/console.rst b/docs/zh_CN/api-reference/system/console.rst index bd262390dd..cfd304f5ed 100644 --- a/docs/zh_CN/api-reference/system/console.rst +++ b/docs/zh_CN/api-reference/system/console.rst @@ -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`` 中具有一个弱定义，可通过强定义进行覆盖。 主循环 ^^^^^^ diff --git a/docs/zh_CN/api-reference/system/heap_debug.rst b/docs/zh_CN/api-reference/system/heap_debug.rst index 0dfec950a4..2f2bb44dde 100644 --- a/docs/zh_CN/api-reference/system/heap_debug.rst +++ b/docs/zh_CN/api-reference/system/heap_debug.rst @@ -629,7 +629,8 @@ ESP-IDF 集成了用于请求 :ref:`堆内存信息 `、:ref:` 应用示例 -------------------- -- :example:`system/heap_task_tracking` 演示了如何使用堆任务跟踪功能跟踪分配给每个任务的堆内存。 +- :example:`system/heap_task_tracking/basic` 演示了堆任务跟踪的概览功能，用于导出每个任务在堆内存使用方面的统计信息概要。 +- :example:`system/heap_task_tracking/advanced` 演示了堆任务跟踪中统计信息函数的用法，用于访问每个任务在堆内存使用方面的完整统计数据。 API 参考 - 堆内存跟踪 ---------------------------- diff --git a/docs/zh_CN/api-reference/system/log.rst b/docs/zh_CN/api-reference/system/log.rst index 236dd4902b..55688de978 100644 --- a/docs/zh_CN/api-reference/system/log.rst +++ b/docs/zh_CN/api-reference/system/log.rst @@ -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:`芯片端 `：编码并传输日志数据。 + + - 编码流程 + - 参数类型编码 + - 运行时参数类型编码 + +2. :ref:`主机端 `：使用 `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 工具 `_ 会自动解码二进制日志。必须确保监视器工具使用正确版本的 ELF 文件。**引导加载程序** 和 **应用程序** 各自对应不同的 ELF 文件，调用 ``idf.py monitor`` 时会自动选择相应的文件。 + +当接收到 **ELF 地址** 时，监视器工具会根据 ``消息类型`` 字节 **在相应的 ELF 文件中检索对应字符串**。若 **地址以 0xFF 开头** （范围： ``0xFF - 0xFC``），则表示该字段为 **内嵌字符串**，其长度为 **10 位编码**。 + +一旦获取所有组件，系统便将其格式化并输出到终端。 性能测试 ---------- diff --git a/docs/zh_CN/api-reference/system/sleep_modes.rst b/docs/zh_CN/api-reference/system/sleep_modes.rst index 23e9d1c0a8..2643be6034 100644 --- a/docs/zh_CN/api-reference/system/sleep_modes.rst +++ b/docs/zh_CN/api-reference/system/sleep_modes.rst @@ -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 参考 diff --git a/docs/zh_CN/migration-guides/release-5.x/5.4/wifi.rst b/docs/zh_CN/migration-guides/release-5.x/5.4/wifi.rst index bc8ad418fa..d505147ee6 100644 --- a/docs/zh_CN/migration-guides/release-5.x/5.4/wifi.rst +++ b/docs/zh_CN/migration-guides/release-5.x/5.4/wifi.rst @@ -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`` 的情况. - diff --git a/docs/zh_CN/migration-guides/release-5.x/5.5/wifi.rst b/docs/zh_CN/migration-guides/release-5.x/5.5/wifi.rst index 53389e5f2f..9722599e0a 100644 --- a/docs/zh_CN/migration-guides/release-5.x/5.5/wifi.rst +++ b/docs/zh_CN/migration-guides/release-5.x/5.5/wifi.rst @@ -8,4 +8,3 @@ Wi-Fi ~~~~~~~~ ESP-NOW 的发包回调函数的参数从 ``uint8_t *mac_addr`` 变为 ``esp_now_send_info_t *tx_info``。 -