VSF Documented
esp_err.h
Go to the documentation of this file.
1/*****************************************************************************
2 * Copyright(C)2009-2026 by VSF Team *
3 * *
4 * Licensed under the Apache License, Version 2.0 (the "License"); *
5 * you may not use this file except in compliance with the License. *
6 * You may obtain a copy of the License at *
7 * *
8 * http://www.apache.org/licenses/LICENSE-2.0 *
9 * *
10 * Unless required by applicable law or agreed to in writing, software *
11 * distributed under the License is distributed on an "AS IS" BASIS, *
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
13 * See the License for the specific language governing permissions and *
14 * limitations under the License. *
15 * *
16 ****************************************************************************/
17
18/*
19 * Clean-room re-implementation of ESP-IDF public API "esp_err.h".
20 *
21 * This file is authored from the ESP-IDF public API reference only. No
22 * code is copied or derived from the ESP-IDF source tree. Names, error
23 * code values and macro semantics are kept compatible so that unmodified
24 * ESP-IDF example applications can compile and link against this header.
25 *
26 * Baseline: ESP-IDF v5.x public API.
27 */
28
29#ifndef __VSF_ESPIDF_ESP_ERR_H__
30#define __VSF_ESPIDF_ESP_ERR_H__
31
32#include <stdint.h>
33#include <stddef.h>
34
35#ifdef __cplusplus
36extern "C" {
37#endif
38
39/*============================ TYPES =========================================*/
40
41typedef int esp_err_t;
42
43/*============================ MACROS ========================================*/
44
45#define ESP_OK 0
46#define ESP_FAIL -1
47
48/* Generic error codes. Values are fixed by ESP-IDF public API contract. */
49#define ESP_ERR_NO_MEM 0x101
50#define ESP_ERR_INVALID_ARG 0x102
51#define ESP_ERR_INVALID_STATE 0x103
52#define ESP_ERR_INVALID_SIZE 0x104
53#define ESP_ERR_NOT_FOUND 0x105
54#define ESP_ERR_NOT_SUPPORTED 0x106
55#define ESP_ERR_TIMEOUT 0x107
56#define ESP_ERR_INVALID_RESPONSE 0x108
57#define ESP_ERR_INVALID_CRC 0x109
58#define ESP_ERR_INVALID_VERSION 0x10A
59#define ESP_ERR_INVALID_MAC 0x10B
60#define ESP_ERR_NOT_FINISHED 0x10C
61#define ESP_ERR_NOT_ALLOWED 0x10D
62
63/* Per-component error code bases. Component-specific errors add an offset
64 * on top of these bases; the concrete codes are declared in each
65 * component's own header. */
66#define ESP_ERR_WIFI_BASE 0x3000
67#define ESP_ERR_MESH_BASE 0x4000
68#define ESP_ERR_FLASH_BASE 0x6000
69#define ESP_ERR_HW_CRYPTO_BASE 0xc000
70#define ESP_ERR_MEMPROT_BASE 0xd000
71
72/*============================ PROTOTYPES ====================================*/
73
74/* Returns a human-readable name for an esp_err_t value. If the code is not
75 * recognized, returns the string "UNKNOWN ERROR". The returned pointer is
76 * valid for the lifetime of the program. */
77const char * esp_err_to_name(esp_err_t code);
78
79/* Reentrant variant. Writes the error name into caller-provided buffer.
80 * Unknown codes are rendered as "UNKNOWN ERROR 0x<hex>". Always returns
81 * buf on success; buf is always NUL-terminated when buflen > 0. */
82const char * esp_err_to_name_r(esp_err_t code, char *buf, size_t buflen);
83
84/* Reports an ESP_ERROR_CHECK() failure and terminates execution.
85 * Never returns. Implementation logs the failure through VSF trace and
86 * then invokes VSF_ASSERT(0). */
87void _esp_error_check_failed(esp_err_t rc, const char *file, int line,
88 const char *function, const char *expression);
89
90/* Reports an ESP_ERROR_CHECK_WITHOUT_ABORT() failure. Returns normally so
91 * that the caller may inspect the error code. */
92void _esp_error_check_failed_without_abort(esp_err_t rc, const char *file,
93 int line, const char *function,
94 const char *expression);
95
96/*============================ CHECK MACROS ==================================*/
97
98/* Aborts when the wrapped expression does not evaluate to ESP_OK. */
99#define ESP_ERROR_CHECK(x) \
100 do { \
101 esp_err_t __err_rc = (esp_err_t)(x); \
102 if (__err_rc != ESP_OK) { \
103 _esp_error_check_failed(__err_rc, __FILE__, __LINE__, \
104 __func__, #x); \
105 } \
106 } while (0)
107
108#if defined(__GNUC__) || defined(__clang__)
109/* GCC statement-expression form: yields the esp_err_t value, so callers
110 * may write rc = ESP_ERROR_CHECK_WITHOUT_ABORT(f()); */
111#define ESP_ERROR_CHECK_WITHOUT_ABORT(x) \
112 ({ \
113 esp_err_t __err_rc = (esp_err_t)(x); \
114 if (__err_rc != ESP_OK) { \
115 _esp_error_check_failed_without_abort(__err_rc, __FILE__, \
116 __LINE__, __func__, #x); \
117 } \
118 __err_rc; \
119 })
120#else
121/* Non-GCC fallback: statement form only, return value not available. */
122#define ESP_ERROR_CHECK_WITHOUT_ABORT(x) \
123 do { \
124 esp_err_t __err_rc = (esp_err_t)(x); \
125 if (__err_rc != ESP_OK) { \
126 _esp_error_check_failed_without_abort(__err_rc, __FILE__, \
127 __LINE__, __func__, #x); \
128 } \
129 } while (0)
130#endif
131
132#ifdef __cplusplus
133}
134#endif
135
136#endif // __VSF_ESPIDF_ESP_ERR_H__
esp_err_to_name_r
const char * esp_err_to_name_r(esp_err_t code, char *buf, size_t buflen)
Definition esp_err_port.c:97
esp_err_to_name
const char * esp_err_to_name(esp_err_t code)
Definition esp_err_port.c:91
esp_err_t
int esp_err_t
Definition esp_err.h:41
_esp_error_check_failed
void _esp_error_check_failed(esp_err_t rc, const char *file, int line, const char *function, const char *expression)
Definition esp_err_port.c:119
_esp_error_check_failed_without_abort
void _esp_error_check_failed_without_abort(esp_err_t rc, const char *file, int line, const char *function, const char *expression)
Definition esp_err_port.c:133
Generated from commit: vsfteam/vsf@015f4d1