diff --git a/docs/en/api-guides/wifi-driver/wifi-performance-and-power-save.rst b/docs/en/api-guides/wifi-driver/wifi-performance-and-power-save.rst index 21ae29644a..0f9fecfcf2 100644 --- a/docs/en/api-guides/wifi-driver/wifi-performance-and-power-save.rst +++ b/docs/en/api-guides/wifi-driver/wifi-performance-and-power-save.rst @@ -412,7 +412,7 @@ The table below shows the best throughput results gained in Espressif's lab and .. _How-to-improve-Wi-Fi-performance: How to Improve Wi-Fi Performance ----------------------------------- +-------------------------------- The performance of {IDF_TARGET_NAME} Wi-Fi is affected by many parameters, and there are mutual constraints between each parameter. A proper configuration cannot only improve performance, but also increase available memory for applications and improve stability. diff --git a/docs/en/migration-guides/release-5.x/5.2/wifi.rst b/docs/en/migration-guides/release-5.x/5.2/wifi.rst index 2b68771161..8d47403004 100644 --- a/docs/en/migration-guides/release-5.x/5.2/wifi.rst +++ b/docs/en/migration-guides/release-5.x/5.2/wifi.rst @@ -3,14 +3,13 @@ Wi-Fi :link_to_translation:`zh_CN:[中文]` - Wi-Fi Enterprise Security ---------------------------- +------------------------- APIs defined in `esp_wpa2.h` have been deprecated. Please use newer APIs from `esp_eap_client.h`. Wi-Fi Disconnect Reason Codes ------------------------------- +----------------------------- For the event WIFI_EVENT_STA_DISCONNECTED, the original reason code WIFI_REASON_NO_AP_FOUND has been split as follows: diff --git a/docs/zh_CN/api-guides/error-handling.rst b/docs/zh_CN/api-guides/error-handling.rst index d6d96d6418..29f7ce2675 100644 --- a/docs/zh_CN/api-guides/error-handling.rst +++ b/docs/zh_CN/api-guides/error-handling.rst @@ -95,7 +95,7 @@ ESP-IDF 中大多数函数会返回 :cpp:type:`esp_err_t` 类型的错误码，: 用于可恢复错误的宏 ---------------------- -ESP-IDF 提供了一组宏来处理可恢复的错误，定义在 ``esp_check.h`` 头文件中。 **ESP_RETURN_ON_...**、 **ESP_GOTO_ON_...** 和 **ESP_RETURN_VOID_ON_...** 系列宏可简洁、一致地处理错误，提升代码的可读性与可维护性。与 ``ESP_ERROR_CHECK`` 不同，这些宏不会终止程序，而是在检测到错误时打印错误信息并执行返回或跳转。针对中断服务例程 (ISR) 场景，还提供了相应的 ``_ISR`` 版本（如 :c:macro:`ESP_RETURN_ON_ERROR_ISR`），确保中断上下文的安全性。 +ESP-IDF 提供了一组宏来处理可恢复的错误，定义在 ``esp_check.h`` 头文件中。 **ESP_RETURN_ON_...**、 **ESP_GOTO_ON_...**、 **ESP_RETURN_VOID_ON_...** 和 **ESP_RETURN_ON_ERROR_CLEANUP** 系列宏可简洁、一致地处理错误，提升代码的可读性与可维护性。与 ``ESP_ERROR_CHECK`` 不同，这些宏不会终止程序，而是在检测到错误时打印错误信息并执行返回或跳转。针对中断服务例程 (ISR) 场景，还提供了相应的 ``_ISR`` 版本（如 :c:macro:`ESP_RETURN_ON_ERROR_ISR`），确保中断上下文的安全性。 这些宏的定义如下： @@ -120,6 +120,8 @@ ESP-IDF 提供了一组宏来处理可恢复的错误，定义在 ``esp_check.h` - :c:macro:`ESP_RETURN_VOID_ON_ERROR_ISR` - 适用于中断服务例程 (ISR) 上下文。 - :c:macro:`ESP_RETURN_VOID_ON_FALSE_ISR` - 适用于中断服务例程 (ISR) 上下文。 +- **ESP_RETURN_ON_ERROR_CLEANUP**：检测到错误时，在执行清理代码后从函数返回。该宏尤其适用于在返回错误码之前需要释放资源的情况。该宏会对返回 :cpp:type:`esp_err_t` 的表达式进行求值；若结果不为 :c:macro:`ESP_OK`，则会先执行可变参数提供的清理代码（例如释放资源或记录日志），然后从当前函数返回该错误码。 + 这些宏的默认行为可通过 Kconfig 进行配置：如果启用了 :ref:`CONFIG_COMPILER_OPTIMIZATION_CHECKS_SILENT` 选项，错误信息将不会被包含在应用程序二进制文件中，也不会被打印出来。 .. _check_macros_examples: @@ -144,6 +146,19 @@ ESP-IDF 提供了一组宏来处理可恢复的错误，定义在 ``esp_check.h` ESP_RETURN_ON_FALSE(a, err_code, TAG, "fail reason 3"); // 如果给定条件不等于 `true`，则打印错误信息，并使原函数立刻返回，返回值为给定的错误码。 ESP_GOTO_ON_FALSE(a, err_code, err, TAG, "fail reason 4"); // 如果给定条件不等于 `true`，该宏会打印错误信息，将局部变量 `ret` 赋值为给定的 `err_code`，并使原函数跳转至 `err`。 + ESP_RETURN_ON_ERROR_CLEANUP(init_resource(), free_mem(), deinit_resource()); // 如果失败，通过调用 `free_mem()` 和 `deinit_resource()` 清理资源，然后返回错误码。 + + ESP_RETURN_ON_ERROR_CLEANUP( // 如果需要更复杂的清理操作，可以使用 `do {...} while(0)` 代码块（使用 ESP_LOG 时需要）。 + sensor_calibrate(), + do { + if (err_rc_ == ESP_ERR_TIMEOUT) { + ESP_LOGE(TAG, "Sensor calibration timeout"); + } + sensor_deinit(); + ESP_LOGE(TAG, "Sensor cleanup completed"); + } while (0) + ); + err: // clean up return ret; diff --git a/docs/zh_CN/api-guides/wifi-driver/wifi-performance-and-power-save.rst b/docs/zh_CN/api-guides/wifi-driver/wifi-performance-and-power-save.rst index c35e754d8c..b39d07411e 100644 --- a/docs/zh_CN/api-guides/wifi-driver/wifi-performance-and-power-save.rst +++ b/docs/zh_CN/api-guides/wifi-driver/wifi-performance-and-power-save.rst @@ -408,6 +408,7 @@ Wi-Fi 使用的堆内存峰值是 Wi-Fi 驱动程序 **理论上消耗的最大 使用 iperf example 测试吞吐量时，sdkconfig 是 :idf_file:`examples/wifi/iperf/sdkconfig.defaults.esp32s3`。 + .. _How-to-improve-Wi-Fi-performance: 如何提高 Wi-Fi 性能 diff --git a/docs/zh_CN/api-reference/system/esp_timer.rst b/docs/zh_CN/api-reference/system/esp_timer.rst index 5f4d7ab877..3520a3bf96 100644 --- a/docs/zh_CN/api-reference/system/esp_timer.rst +++ b/docs/zh_CN/api-reference/system/esp_timer.rst @@ -34,6 +34,7 @@ FreeRTOS 有其单独的软件定时器，但分辨率比 ESP 定时器低得多 ESP 定时器 API 提供： - 一次性和周期性定时器 +- 相对定时和绝对定时 - 多种分发回调函数的方法 - 处理过期回调函数 - 计数器位宽：{IDF_TARGET_HR_TIMER_Resolution} 位 diff --git a/docs/zh_CN/migration-guides/release-5.x/5.2/wifi.rst b/docs/zh_CN/migration-guides/release-5.x/5.2/wifi.rst index 22b9f3569e..519a0d8472 100644 --- a/docs/zh_CN/migration-guides/release-5.x/5.2/wifi.rst +++ b/docs/zh_CN/migration-guides/release-5.x/5.2/wifi.rst @@ -3,14 +3,13 @@ Wi-Fi :link_to_translation:`en:[English]` - Wi-Fi 企业级安全 ------------------------- +---------------- 在 `esp_wpa2.h` 中定义的 API 已弃用，请使用来自 `esp_eap_client.h` 的新 API。 Wi-Fi 断开连接原因代码 ------------------------- +---------------------- 对于事件 WIFI_EVENT_STA_DISCONNECTED，原有的断开原因代码 WIFI_REASON_NO_AP_FOUND 已细分为以下几种情况： @@ -19,8 +18,9 @@ Wi-Fi 断开连接原因代码 - REASON_NO_AP_FOUND_IN_AUTHMODE_THRESHOLD（在认证模式门限范围内未找到 AP） - REASON_NO_AP_FOUND_W_COMPATIBLE_SECURITY（未找到具有兼容安全性的 AP） +详情请参阅 :ref:`esp_wifi_reason_code`. Wi-Fi 多天线 ------------------------- +------------ Wi-Fi 多天线相关的 API 将要被弃用，请使用来自 `esp_phy.h` 的新 API。