Esp_Goto_On_False Macro; Check Macros Examples; Error Handling Patterns - Espressif ESP32-S2 Programming 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
esp_err_t test_func(void)
{
esp_err_t ret =
ESP_ERROR_CHECK(x);
printed if `x` is not `ESP_OK`, and then `abort()`.
→
ESP_ERROR_CHECK_WITHOUT_ABORT(x);
printed if `x` is not `ESP_OK`, without `abort()`.
→
ESP_RETURN_ON_ERROR(x, TAG,
printed if `x` is not `ESP_OK`, and then function returns with code `x`.
→
ESP_GOTO_ON_ERROR(x, err, TAG,
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,
printed if `a` is not `true`, and then function returns with code `err_code`.
→
ESP_GOTO_ON_FALSE(a, err_code, err, TAG,
printed if `a` is not `true`, `ret` is set to `err_code`, and then jumps
→
`err`.
→
err:
// clean up
return ret;
}
Note: If the option CONFIG_COMPILER_OPTIMIZATION_CHECKS_SILENT
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 ==
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
= "Test";
ESP_OK;
"fail reason
"fail reason
ESP_ERR_TIMEOUT);
Submit Document Feedback
1");
2");
"fail reason 3");
"fail reason 4");
in Kconfig is enabled, the err message
1305
// err message␣
// err message␣
// err message␣
// err message␣
// err message␣
// err message␣
to␣
Release v4.4