错误代码和辅助函数
本节列出了 ESP-IDF 中常见错误代码的定义,以及部分与错误处理相关的辅助函数。
有关 ESP-IDF 中错误代码的基本信息,请参阅 错误处理。
有关 ESP-IDF 定义的错误代码的完整列表,请参阅 错误代码参考。
API 参考
Header File
This header file can be included with:
#include "esp_check.h"
Macros
-
ESP_RETURN_ON_ERROR(x, log_tag, format, ...)
Macro which can be used to check the error code. If the code is not ESP_OK, it prints the message and returns. In the future, we want to switch to C++20. We also want to become compatible with clang. Hence, we provide two versions of the following macros. The first one is using the GNU extension ##__VA_ARGS__. The second one is using the C++20 feature VA_OPT(,). This allows users to compile their code with standard C++20 enabled instead of the GNU extension. Below C++20, we haven't found any good alternative to using ##__VA_ARGS__. Macro which can be used to check the error code. If the code is not ESP_OK, it prints the message and returns.
-
ESP_RETURN_ON_ERROR_ISR(x, log_tag, format, ...)
A version of ESP_RETURN_ON_ERROR() macro that can be called from ISR.
-
ESP_GOTO_ON_ERROR(x, goto_tag, log_tag, format, ...)
Macro which can be used to check the error code. If the code is not 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_ERROR_ISR(x, goto_tag, log_tag, format, ...)
A version of ESP_GOTO_ON_ERROR() macro that can be called from ISR.
-
ESP_RETURN_ON_FALSE(a, err_code, log_tag, format, ...)
Macro which can be used to check the condition. If the condition is not 'true', it prints the message and returns with the supplied 'err_code'.
-
ESP_RETURN_ON_FALSE_ISR(a, err_code, log_tag, format, ...)
A version of ESP_RETURN_ON_FALSE() macro that can be called from ISR.
-
ESP_GOTO_ON_FALSE(a, err_code, goto_tag, log_tag, format, ...)
Macro which can be used to check the condition. If the condition is not 'true', it prints the message, sets the local variable 'ret' to the supplied 'err_code', and then exits by jumping to 'goto_tag'.
-
ESP_GOTO_ON_FALSE_ISR(a, err_code, goto_tag, log_tag, format, ...)
A version of ESP_GOTO_ON_FALSE() macro that can be called from ISR.
Header File
This header file can be included with:
#include "esp_err.h"
Functions
-
const char *esp_err_to_name(esp_err_t code)
Returns string for esp_err_t error codes.
This function finds the error code in a pre-generated lookup-table and returns its string representation.
The function is generated by the Python script tools/gen_esp_err_to_name.py which should be run each time an esp_err_t error is modified, created or removed from the IDF project.
- 参数
code -- esp_err_t error code
- 返回
string error message
-
const char *esp_err_to_name_r(esp_err_t code, char *buf, size_t buflen)
Returns string for esp_err_t and system error codes.
This function finds the error code in a pre-generated lookup-table of esp_err_t errors and returns its string representation. If the error code is not found then it is attempted to be found among system errors.
The function is generated by the Python script tools/gen_esp_err_to_name.py which should be run each time an esp_err_t error is modified, created or removed from the IDF project.
- 参数
code -- esp_err_t error code
buf -- [out] buffer where the error message should be written
buflen -- Size of buffer buf. At most buflen bytes are written into the buf buffer (including the terminating null byte).
- 返回
buf containing the string error message
Macros
-
ESP_OK
esp_err_t value indicating success (no error)
-
ESP_FAIL
Generic esp_err_t code indicating failure
-
ESP_ERR_NO_MEM
Out of memory
-
ESP_ERR_INVALID_ARG
Invalid argument
-
ESP_ERR_INVALID_STATE
Invalid state
-
ESP_ERR_INVALID_SIZE
Invalid size
-
ESP_ERR_NOT_FOUND
Requested resource not found
-
ESP_ERR_NOT_SUPPORTED
Operation or feature not supported
-
ESP_ERR_TIMEOUT
Operation timed out
-
ESP_ERR_INVALID_RESPONSE
Received response was invalid
-
ESP_ERR_INVALID_CRC
CRC or checksum was invalid
-
ESP_ERR_INVALID_VERSION
Version was invalid
-
ESP_ERR_INVALID_MAC
MAC address was invalid
-
ESP_ERR_NOT_FINISHED
Operation has not fully completed
-
ESP_ERR_NOT_ALLOWED
Operation is not allowed
-
ESP_ERR_WIFI_BASE
Starting number of WiFi error codes
-
ESP_ERR_MESH_BASE
Starting number of MESH error codes
-
ESP_ERR_FLASH_BASE
Starting number of flash error codes
-
ESP_ERR_HW_CRYPTO_BASE
Starting number of HW cryptography module error codes
-
ESP_ERR_MEMPROT_BASE
Starting number of Memory Protection API error codes
-
ESP_ERROR_CHECK(x)
Macro which can be used to check the error code, and terminate the program in case the code is not ESP_OK. Prints the error code, error location, and the failed statement to serial output.
Disabled if assertions are disabled.
-
ESP_ERROR_CHECK_WITHOUT_ABORT(x)
Macro which can be used to check the error code. Prints the error code, error location, and the failed statement to serial output. In comparison with ESP_ERROR_CHECK(), this prints the same error message but isn't terminating the program.
Type Definitions
-
typedef int esp_err_t