Merge branch 'contrib/github_pr_15930' into 'master'

docs(esp32): Add note about including esp_check.h for error-handling.rst docs page in English (GitHub PR)

Closes IDFGH-15271 and DOC-11245

See merge request espressif/esp-idf!39012

Author: Konstantin Kondrashov

docs/en/api-guides/error-handling.rst

@@ -21,7 +21,7 @@ Identifying and handling run-time errors is important for developing robust appl
   - CPU exceptions: access to protected regions of memory, illegal instruction, etc.
   - System level checks: watchdog timeout, cache access error, stack overflow, stack smashing, heap corruption, etc.
 
-This guide explains ESP-IDF error handling mechanisms related to recoverable errors, and provides some common error handling patterns.
+This guide primarily introduces the error handling mechanisms in ESP-IDF for **recoverable errors** and provides common error handling patterns. Some sections also mention macros used for **unrecoverable errors**, with the aim of illustrating their use in scenarios with different levels of error severity.
 
 For instructions on diagnosing unrecoverable errors, see :doc:`Fatal Errors <fatal-errors>`.
 
@@ -45,13 +45,29 @@ Additionally, :cpp:func:`esp_err_to_name_r` function will attempt to interpret t
 
 This feature is enabled by default, but can be disabled to reduce application binary size. See :ref:`CONFIG_ESP_ERR_TO_NAME_LOOKUP`. When this feature is disabled, :cpp:func:`esp_err_to_name` and :cpp:func:`esp_err_to_name_r` are still defined and can be called. In this case, :cpp:func:`esp_err_to_name` will return ``UNKNOWN ERROR``, and :cpp:func:`esp_err_to_name_r` will return ``Unknown error 0xXXXX(YYYYY)``, where ``0xXXXX`` and ``YYYYY`` are the hexadecimal and decimal representations of the error code, respectively.
 
-
 .. _esp-error-check-macro:
 
-``ESP_ERROR_CHECK`` Macro
--------------------------
+Macro For Unrecoverable Errors
+------------------------------
+
+The :c:macro:`ESP_ERROR_CHECK` macro, defined in ``esp_err.h``, is used to handle unrecoverable errors in ESP-IDF applications. It functions similarly to the standard ``assert`` macro, but specifically checks whether an :cpp:type:`esp_err_t` value is equal to :c:macro:`ESP_OK`. If the value is not :c:macro:`ESP_OK`, :c:macro:`ESP_ERROR_CHECK` prints a detailed error message and calls ``abort()``, terminating the application.
+
+The behavior of :c:macro:`ESP_ERROR_CHECK` can be controlled using assertion-related configuration options:
+
+- If ``CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_ENABLE`` is set (default), the macro prints an error message and terminates the program.
+- If ``CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_SILENT`` is enabled, the program terminates silently without printing an error message.
+- If ``CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_DISABLE`` (``NDEBUG`` is defined), the macro only prints an error message and does not terminate the program.
+
+Use :c:macro:`ESP_ERROR_CHECK` in situations where an error is considered fatal and the application cannot continue safely. For situations where the application can recover from an error, use the macros described in the next section.
+
+``ESP_ERROR_CHECK_WITHOUT_ABORT``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :c:macro:`ESP_ERROR_CHECK_WITHOUT_ABORT` macro, defined in ``esp_err.h``, is closely related to the **Macros For Recoverable Errors**. The macro behaves similarly to :c:macro:`ESP_ERROR_CHECK`, but instead of terminating the program with ``abort()``, it prints an error message in the same format and returns the error code if the value is not :c:macro:`ESP_OK`. This allows the application to continue running, making it suitable for cases where errors should be reported but are not considered fatal.
 
-:c:macro:`ESP_ERROR_CHECK` macro serves similar purpose as ``assert``, except that it checks :cpp:type:`esp_err_t` value rather than a ``bool`` condition. If the argument of :c:macro:`ESP_ERROR_CHECK` is not equal :c:macro:`ESP_OK`, then an error message is printed on the console, and ``abort()`` is called.
+The behavior of :c:macro:`ESP_ERROR_CHECK_WITHOUT_ABORT` is controlled by the same assertion-related configuration options as :c:macro:`ESP_ERROR_CHECK`. If either ``CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_DISABLE`` or ``CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_SILENT`` is enabled, the macro does not print any error message, otherwise, the macro prints an error message.
+
+Use :c:macro:`ESP_ERROR_CHECK_WITHOUT_ABORT` when you want to print errors for diagnostic purposes without stopping the application.
 
 Error message will typically look like this:
 
@@ -76,50 +92,40 @@ Error message will typically look like this:
 - Finally, backtrace is printed. This is part of panic handler output common to all fatal errors. See :doc:`Fatal Errors <fatal-errors>` for more information about the backtrace.
 
 
-.. _esp-error-check-without-abort-macro:
-
-``ESP_ERROR_CHECK_WITHOUT_ABORT`` Macro
----------------------------------------
-
-:c:macro:`ESP_ERROR_CHECK_WITHOUT_ABORT` macro serves similar purpose as ``ESP_ERROR_CHECK``, except that it will not call ``abort()``.
-
-
-.. _esp-return-on-error-macro:
-
-``ESP_RETURN_ON_ERROR`` Macro
+Macros For Recoverable Errors
 -----------------------------
 
-:c:macro:`ESP_RETURN_ON_ERROR` macro checks the error code, if the error code is not equal :c:macro:`ESP_OK`, it prints the message and returns the error code.
+For recoverable errors, ESP-IDF provides a set of macros defined in ``esp_check.h``. The **ESP_RETURN_ON_...**, **ESP_GOTO_ON_...**, and **ESP_RETURN_VOID_ON_...** macros enable concise and consistent error handling, improving code readability and maintainability. Unlike ``ESP_ERROR_CHECK``, these macros do not terminate the program; instead, they print an error message and return or jump as appropriate. For use in interrupt service routines (ISRs), corresponding ``_ISR`` versions (such as :c:macro:`ESP_RETURN_ON_ERROR_ISR`) are available, ensuring safe operation in interrupt contexts.
 
+The macros are defined as follows:
 
-.. _esp-goto-on-error-macro:
+- **ESP_RETURN_ON_...**: Return from the function if an error or failed condition is detected:
 
-``ESP_GOTO_ON_ERROR`` Macro
----------------------------
+    - :c:macro:`ESP_RETURN_ON_ERROR` - Checks an error code; if not :c:macro:`ESP_OK`, prints a message and returns the error code.
+    - :c:macro:`ESP_RETURN_ON_FALSE` - Checks a condition; if false, prints a message and returns the supplied ``err_code``.
+    - :c:macro:`ESP_RETURN_ON_ERROR_ISR` - For ISR context.
+    - :c:macro:`ESP_RETURN_ON_FALSE_ISR` - For ISR context.
 
-:c:macro:`ESP_GOTO_ON_ERROR` macro checks the error code, if the error code is not equal :c:macro:`ESP_OK`, it prints the message, sets the local variable ``ret`` to the code, and then exits by jumping to ``goto_tag``.
+- **ESP_GOTO_ON_...**: Jump to a label if an error or failed condition is detected:
 
+    - :c:macro:`ESP_GOTO_ON_ERROR` - Checks an error code; if not :c:macro:`ESP_OK`, prints a message, sets ``ret`` to the code, and jumps to ``goto_tag``.
+    - :c:macro:`ESP_GOTO_ON_FALSE` - Checks a condition; if false, prints a message, sets ``ret`` to ``err_code``, and jumps to ``goto_tag``.
+    - :c:macro:`ESP_GOTO_ON_ERROR_ISR` - For ISR context.
+    - :c:macro:`ESP_GOTO_ON_FALSE_ISR` - For ISR context.
 
-.. _esp-return-on-false-macro:
+- **ESP_RETURN_VOID_...**: Return from a ``void`` function if an error or failed condition is detected:
 
-``ESP_RETURN_ON_FALSE`` Macro
------------------------------
-
-:c:macro:`ESP_RETURN_ON_FALSE` macro checks the condition, if the condition is not equal ``true``, it prints the message and returns with the supplied ``err_code``.
-
-
-.. _esp-goto-on-false-macro:
-
-``ESP_GOTO_ON_FALSE`` Macro
----------------------------
-
-:c:macro:`ESP_GOTO_ON_FALSE` macro checks the condition, if the condition is not equal ``true``, it prints the message, sets the local variable ``ret`` to the supplied ``err_code``, and then exits by jumping to ``goto_tag``.
+    - :c:macro:`ESP_RETURN_VOID_ON_ERROR` - Checks an error code; if not :c:macro:`ESP_OK`, prints a message and returns.
+    - :c:macro:`ESP_RETURN_VOID_ON_FALSE` - Checks a condition; if false, prints a message and returns.
+    - :c:macro:`ESP_RETURN_VOID_ON_ERROR_ISR` - For ISR context.
+    - :c:macro:`ESP_RETURN_VOID_ON_FALSE_ISR` - For ISR context.
 
+The default behavior of these macros can be adjusted: if the :ref:`CONFIG_COMPILER_OPTIMIZATION_CHECKS_SILENT` option is enabled in Kconfig, error messages will not be included in the application binary and will not be printed.
 
 .. _check_macros_examples:
 
-``CHECK MACROS`` Examples
--------------------------
+Error Handling Examples
+-----------------------
 
 Some examples
 
@@ -143,13 +149,6 @@ Some examples
         return ret;
     }
 
-.. note::
-
-     If the option :ref:`CONFIG_COMPILER_OPTIMIZATION_CHECKS_SILENT` in Kconfig is enabled, the error message will be discarded, while the other action works as is.
-
-     The ``ESP_RETURN_XX`` and ``ESP_GOTO_xx`` macros cannot be called from ISR. While there are ``xx_ISR`` versions for each of them, e.g., ``ESP_RETURN_ON_ERROR_ISR``, these macros could be used in ISR.
-
-
 Error Handling Patterns
 -----------------------
 
@@ -191,7 +190,7 @@ Error Handling Patterns
             return err;
         }
 
-3. Convert into unrecoverable error, for example using ``ESP_ERROR_CHECK``. See `ESP_ERROR_CHECK macro`_ section for details.
+3. Convert into unrecoverable error, for example using ``ESP_ERROR_CHECK``. See `Macro For Unrecoverable Errors`_ section for details.
 
     Terminating the application in case of an error is usually undesirable behavior for middleware components, but is sometimes acceptable at application level.
 
@@ -208,3 +207,8 @@ C++ Exceptions
 --------------
 
 See :ref:`cplusplus_exceptions`.
+
+API Reference
+-------------
+
+See :ref:`esp-check-api-ref`.

docs/en/api-guides/fatal-errors.rst

@@ -25,7 +25,7 @@ In certain situations, the execution of the program can not be continued in a we
         - Heap integrity check
         - Undefined behavior sanitizer (UBSAN) checks
 
-- Failed assertions, via ``assert``, ``configASSERT`` and similar macros.
+- Failed assertions, via ``assert``, ``configASSERT`` and :doc:`similar macros </api-guides/error-handling>`.
 
 This guide explains the procedure used in ESP-IDF for handling these errors, and provides suggestions on troubleshooting the errors.
 

docs/en/api-reference/system/esp_err.rst

@@ -9,6 +9,8 @@ For general information about error codes in ESP-IDF, see :doc:`Error Handling <
 
 For the full list of error codes defined in ESP-IDF, see :doc:`Error Codes Reference <../error-codes>`.
 
+.. _esp-check-api-ref:
+
 API Reference
 -------------
 

docs/zh_CN/api-guides/error-handling.rst

@@ -21,7 +21,7 @@
   - CPU 异常：访问受保护的内存区域、非法指令等
   - 系统级检查：看门狗超时、缓存访问错误、堆栈溢出、堆栈粉碎、堆栈损坏等
 
-本文将介绍 ESP-IDF 中针对可恢复错误的错误处理机制，并提供一些常见错误的处理模式。
+本文主要介绍 ESP-IDF 中用于 **可恢复错误** 的处理机制，并提供一些常见错误的处理模式。部分章节也提及了用于 **不可恢复错误** 的相关宏，旨在说明其在不同错误严重程度下的应用场景。
 
 关于如何处理不可恢复的错误，请参阅 :doc:`/api-guides/fatal-errors`。
 
@@ -45,13 +45,29 @@ ESP-IDF 中大多数函数会返回 :cpp:type:`esp_err_t` 类型的错误码，:
 
 该功能（即在无法匹配 ``ESP_ERR_`` 值时，尝试用标准 POSIX 解释错误码）默认启用。用户也可以禁用该功能，从而减小应用程序的二进制文件大小，详情可见 :ref:`CONFIG_ESP_ERR_TO_NAME_LOOKUP`。注意，该功能对禁用并不影响 :cpp:func:`esp_err_to_name` 和 :cpp:func:`esp_err_to_name_r` 函数的定义，用户仍可调用这两个函数转化错误码。在这种情况下， :cpp:func:`esp_err_to_name` 函数在遇到无法匹配错误码的情况会返回 ``UNKNOWN ERROR``，而 :cpp:func:`esp_err_to_name_r` 函数会返回 ``Unknown error 0xXXXX(YYYYY)``，其中 ``0xXXXX`` 和 ``YYYYY`` 分别代表错误代码的十六进制和十进制表示。
 
-
 .. _esp-error-check-macro:
 
-``ESP_ERROR_CHECK`` 宏
+用于不可恢复错误的宏
 ----------------------
 
-宏 :c:macro:`ESP_ERROR_CHECK` 的功能和 ``assert`` 类似，不同之处在于：这个宏会检查 :cpp:type:`esp_err_t` 的值，而非判断 ``bool`` 条件。如果传给 :c:macro:`ESP_ERROR_CHECK` 的参数不等于 :c:macro:`ESP_OK` ，则会在控制台上打印错误消息，然后调用 ``abort()`` 函数。
+宏 :c:macro:`ESP_ERROR_CHECK` 用于处理 ESP-IDF 应用中不可恢复的错误，具体定义参考 ``esp_err.h`` 头文件。该宏的功能和标准的 ``assert`` 宏类似，不同之处在于它会专门检查 :cpp:type:`esp_err_t` 的值是否等于 :c:macro:`ESP_OK`。如果该值不为 :c:macro:`ESP_OK`，会将打印详细的错误信息，并调用 ``abort()`` 函数，从而终止程序运行。
+
+使用下列断言配置选项，可以控制 :c:macro:`ESP_ERROR_CHECK` 宏的行为：
+
+- 启用 ``CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_ENABLE`` （默认设置），该宏会打印错误信息并终止程序。
+- 启用 ``CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_SILENT``，程序会在不打印任何错误信息的情况下直接终止。
+- 启用 ``CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_DISABLE`` （即定义了 ``NDEBUG``），该宏仅打印错误信息，但不会终止程序。
+
+:c:macro:`ESP_ERROR_CHECK` 适用于严重错误且程序无法安全运行的情况。对于可以从错误中恢复的情况，请使用下一节中介绍的相关宏。
+
+``ESP_ERROR_CHECK_WITHOUT_ABORT``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+宏 :c:macro:`ESP_ERROR_CHECK_WITHOUT_ABORT` 用于 **可恢复错误** 的处理， 具体定义见 ``esp_err.h`` 头文件。该宏的行为与 :c:macro:`ESP_ERROR_CHECK` 类似，但在 :cpp:type:`esp_err_t` 值不为 :c:macro:`ESP_OK` 时，不会调用 ``abort()`` 函数终止程序，而是用同样的格式打印错误信息，并返回该错误码，允许程序继续运行。该宏适用于需要报告错误，但无需中断程序的情况。
+
+:c:macro:`ESP_ERROR_CHECK_WITHOUT_ABORT` 宏的行为也受断言相关配置选项（与 :c:macro:`ESP_ERROR_CHECK` 相同）的控制。启用 ``CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_DISABLE`` 或 ``CONFIG_COMPILER_OPTIMIZATION_ASSERTIONS_SILENT`` 时，该宏不打印任何错误信息；否则打印错误信息。
+
+当需要打印错误信息用于诊断，但希望应用程序继续运行时，请使用宏 :c:macro:`ESP_ERROR_CHECK_WITHOUT_ABORT`。
 
 错误消息通常如下所示：
 
@@ -76,50 +92,40 @@ ESP-IDF 中大多数函数会返回 :cpp:type:`esp_err_t` 类型的错误码，:
 - 最后一行打印回溯结果。对于所有不可恢复错误，这里在应急处理程序中打印的内容都是一样的。更多有关回溯结果的详细信息，请参阅 :doc:`/api-guides/fatal-errors`。
 
 
-.. _esp-error-check-without-abort-macro:
-
-``ESP_ERROR_CHECK_WITHOUT_ABORT`` 宏
-------------------------------------
-
-宏 :c:macro:`ESP_ERROR_CHECK_WITHOUT_ABORT` 的功能和 ``ESP_ERROR_CHECK`` 类似，不同之处在于它不会调用 ``abort()``。
-
-
-.. _esp-return-on-error-macro:
-
-``ESP_RETURN_ON_ERROR`` 宏
---------------------------
-
-宏 :c:macro:`ESP_RETURN_ON_ERROR` 用于错误码检查，如果错误码不等于 :c:macro:`ESP_OK`， 该宏会打印错误信息，并使原函数立刻返回。
-
-
-.. _esp-goto-on-error-macro:
-
-``ESP_GOTO_ON_ERROR`` 宏
-------------------------
-
-宏 :c:macro:`ESP_GOTO_ON_ERROR` 用于错误码检查，如果错误码不等于 :c:macro:`ESP_OK`，该宏会打印错误信息，将局部变量 ``ret`` 赋值为该错误码，并使原函数跳转至给定的 ``goto_tag``。
+用于可恢复错误的宏
+----------------------
 
+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-return-on-false-macro:
+这些宏的定义如下：
 
-``ESP_RETURN_ON_FALSE`` 宏
---------------------------
+- **ESP_RETURN_ON_...**：当检测到错误或条件失败时，从函数返回：
 
-宏 :c:macro:`ESP_RETURN_ON_FALSE` 用于条件检查，如果给定条件不等于 ``true``，该宏会打印错误信息，并使原函数立刻返回，返回值为给定的 ``err_code``。
+    - :c:macro:`ESP_RETURN_ON_ERROR` - 检查错误码，如果不是 :c:macro:`ESP_OK`，打印信息并返回该错误码。
+    - :c:macro:`ESP_RETURN_ON_FALSE` - 检查某个条件，如果为假，打印信息并返回提供的 ``err_code``。
+    - :c:macro:`ESP_RETURN_ON_ERROR_ISR` - 适用于中断服务例程 (ISR) 上下文。
+    - :c:macro:`ESP_RETURN_ON_FALSE_ISR` - 适用于中断服务例程 (ISR) 上下文。
 
+- **ESP_GOTO_ON_...**：当检测到错误或条件失败时，跳转到指定标签：
 
-.. _esp-goto-on-false-macro:
+    - :c:macro:`ESP_GOTO_ON_ERROR` - 检查错误码，如果不是 :c:macro:`ESP_OK`，打印信息，将 ``ret`` 设为错误码，并跳转到 ``goto_tag``。
+    - :c:macro:`ESP_GOTO_ON_FALSE` - 检查某个条件，如果为假，打印信息，将 ``ret`` 设为错误码，并跳转到 ``goto_tag``。
+    - :c:macro:`ESP_GOTO_ON_ERROR_ISR` - 适用于中断服务例程 (ISR) 上下文。
+    - :c:macro:`ESP_GOTO_ON_FALSE_ISR` - 适用于中断服务例程 (ISR) 上下文。
 
-``ESP_GOTO_ON_FALSE`` 宏
-------------------------
+- **ESP_RETURN_VOID_...**：当检测到错误或条件失败时，从 ``void`` 函数返回：
 
-宏 :c:macro:`ESP_GOTO_ON_FALSE` 用于条件检查，如果给定条件不等于 ``true``，该宏会打印错误信息，将局部变量 ``ret`` 赋值为给定的 ``err_code``，并使原函数跳转至给定的 ``goto_tag``。
+    - :c:macro:`ESP_RETURN_VOID_ON_ERROR` - 检查错误码，如果不是 :c:macro:`ESP_OK`，打印信息并返回。
+    - :c:macro:`ESP_RETURN_VOID_ON_FALSE` - 检查某个条件，如果为假，打印信息并返回。
+    - :c:macro:`ESP_RETURN_VOID_ON_ERROR_ISR` - 适用于中断服务例程 (ISR) 上下文。
+    - :c:macro:`ESP_RETURN_VOID_ON_FALSE_ISR` - 适用于中断服务例程 (ISR) 上下文。
 
+这些宏的默认行为可通过 Kconfig 进行配置：如果启用了 :ref:`CONFIG_COMPILER_OPTIMIZATION_CHECKS_SILENT` 选项，错误信息将不会被包含在应用程序二进制文件中，也不会被打印出来。
 
 .. _check_macros_examples:
 
-``CHECK 宏使用示例``
--------------------------
+错误处理示例
+-----------------
 
 示例：
 
@@ -143,13 +149,6 @@ ESP-IDF 中大多数函数会返回 :cpp:type:`esp_err_t` 类型的错误码，:
         return ret;
     }
 
-.. note::
-
-     如果 Kconfig 中的 :ref:`CONFIG_COMPILER_OPTIMIZATION_CHECKS_SILENT` 选项被打开，CHECK 宏将不会打印错误信息，其他功能不变。
-
-     ``ESP_RETURN_xx`` 和 ``ESP_GOTO_xx`` 宏不可以在中断服务程序里被调用。如需要在中断中使用类似功能，请使用 ``xx_ISR`` 宏，如 ``ESP_RETURN_ON_ERROR_ISR`` 等。
-
-
 错误处理模式
 ------------
 
@@ -191,7 +190,7 @@ ESP-IDF 中大多数函数会返回 :cpp:type:`esp_err_t` 类型的错误码，:
             return err;
         }
 
-3. 转为不可恢复错误，比如使用 ``ESP_ERROR_CHECK``。详情请见 `ESP_ERROR_CHECK 宏 <#esp-error-check-macro>`_ 章节。
+3. 转为不可恢复错误，比如使用 ``ESP_ERROR_CHECK``。详情请见 `用于不可恢复错误的宏 <#esp-error-check-macro>`_ 章节。
 
     对于中间件组件而言，通常并不希望在发生错误时中止应用程序。不过，有时在应用程序级别，这种做法是可以接受的。
 
@@ -208,3 +207,8 @@ C++ 异常
 --------
 
 请参考 :ref:`cplusplus_exceptions`。
+
+API 参考
+-------------
+
+请参考 :ref:`esp-check-api-ref`。