Espressif ESP32-S2 User Manual

Chapter 4. API Guides
4.7.9 ESP_GOTO_ON_FALSE 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.
4.7.10 CHECK MACROS Examples
Some examples:
static const char* TAG = "Test";
esp_err_t test_func(void)
{
esp_err_t ret = ESP_OK;
ESP_ERROR_CHECK(x); // err message␣
,→printed if `x` is not `ESP_OK`, and then `abort()`.
ESP_ERROR_CHECK_WITHOUT_ABORT(x); // err message␣
,→printed if `x` is not `ESP_OK`, without `abort()`.
ESP_RETURN_ON_ERROR(x, TAG, "fail reason 1"); // err message␣
,→printed if `x` is not `ESP_OK`, and then function returns with code `x`.
ESP_GOTO_ON_ERROR(x, err, TAG, "fail reason 2"); // err message␣
,→printed if `x` is not `ESP_OK`, `ret` is set to `x`, and then jumps to `err`.
ESP_RETURN_ON_FALSE(a, err_code, TAG, "fail reason 3"); // err message␣
,→printed if `a` is not `true`, and then function returns with code `err_code`.
ESP_GOTO_ON_FALSE(a, err_code, err, TAG, "fail reason 4"); // err message␣
,→printed if `a` is not `true`, `ret` is set to `err_code`, and then jumps to␣
,→`err`.
err:
// clean up
return ret;
}
Note: If the option CONFIG_COMPILER_OPTIMIZATION_CHECKS_SILENT in Kconfig is enabled, the err message
will be discarded, while the other action works as is.
The ESP_RETURN_XX and ESP_GOTO_xx macros can’t 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.
4.7.11 Error handling patterns
1. Attempt to recover. Depending on the situation, this might mean to retry the call after some time, or attempt
to de-initialize the driver and re-initialize it again, or fix the error condition using an out-of-band mechanism
(e.g reset an external peripheral which is not responding).
Example:
esp_err_t err;
do {
err = sdio_slave_send_queue(addr, len, arg, timeout);
// keep retrying while the sending queue is full
} while (err == ESP_ERR_TIMEOUT);
if (err != ESP_OK) {
// handle other errors
}
2. Propagate the error to the caller. In some middleware components this means that a function must exit with
the same error code, making sure any resource allocations are rolled back.
Espressif Systems 1305
Submit Document Feedback
Release v4.4

Espressif ESP32-S2 Specifications

General

Brand	Espressif
Model	ESP32-S2
Category	Single board computers
Language	English