docs: add error codes reference

components/esp32/esp_err_to_name.c

@@ -55,43 +55,43 @@ typedef struct {
 static const esp_err_msg_t esp_err_msg_table[] = {
     // components/esp32/include/esp_err.h
 #   ifdef      ESP_FAIL
-    ERR_TBL_IT(ESP_FAIL),                                   /*    -1 */
+    ERR_TBL_IT(ESP_FAIL),                                   /*    -1 Generic esp_err_t code indicating failure */
 #   endif
 #   ifdef      ESP_OK
-    ERR_TBL_IT(ESP_OK),                                     /*     0 */
+    ERR_TBL_IT(ESP_OK),                                     /*     0 esp_err_t value indicating success (no error) */
 #   endif
 #   ifdef      ESP_ERR_NO_MEM
-    ERR_TBL_IT(ESP_ERR_NO_MEM),                             /*   257 0x101 */
+    ERR_TBL_IT(ESP_ERR_NO_MEM),                             /*   257 0x101 Out of memory */
 #   endif
 #   ifdef      ESP_ERR_INVALID_ARG
-    ERR_TBL_IT(ESP_ERR_INVALID_ARG),                        /*   258 0x102 */
+    ERR_TBL_IT(ESP_ERR_INVALID_ARG),                        /*   258 0x102 Invalid argument */
 #   endif
 #   ifdef      ESP_ERR_INVALID_STATE
-    ERR_TBL_IT(ESP_ERR_INVALID_STATE),                      /*   259 0x103 */
+    ERR_TBL_IT(ESP_ERR_INVALID_STATE),                      /*   259 0x103 Invalid state */
 #   endif
 #   ifdef      ESP_ERR_INVALID_SIZE
-    ERR_TBL_IT(ESP_ERR_INVALID_SIZE),                       /*   260 0x104 */
+    ERR_TBL_IT(ESP_ERR_INVALID_SIZE),                       /*   260 0x104 Invalid size */
 #   endif
 #   ifdef      ESP_ERR_NOT_FOUND
-    ERR_TBL_IT(ESP_ERR_NOT_FOUND),                          /*   261 0x105 */
+    ERR_TBL_IT(ESP_ERR_NOT_FOUND),                          /*   261 0x105 Requested resource not found */
 #   endif
 #   ifdef      ESP_ERR_NOT_SUPPORTED
-    ERR_TBL_IT(ESP_ERR_NOT_SUPPORTED),                      /*   262 0x106 */
+    ERR_TBL_IT(ESP_ERR_NOT_SUPPORTED),                      /*   262 0x106 Operation or feature not supported */
 #   endif
 #   ifdef      ESP_ERR_TIMEOUT
-    ERR_TBL_IT(ESP_ERR_TIMEOUT),                            /*   263 0x107 */
+    ERR_TBL_IT(ESP_ERR_TIMEOUT),                            /*   263 0x107 Operation timed out */
 #   endif
 #   ifdef      ESP_ERR_INVALID_RESPONSE
-    ERR_TBL_IT(ESP_ERR_INVALID_RESPONSE),                   /*   264 0x108 */
+    ERR_TBL_IT(ESP_ERR_INVALID_RESPONSE),                   /*   264 0x108 Received response was invalid */
 #   endif
 #   ifdef      ESP_ERR_INVALID_CRC
-    ERR_TBL_IT(ESP_ERR_INVALID_CRC),                        /*   265 0x109 */
+    ERR_TBL_IT(ESP_ERR_INVALID_CRC),                        /*   265 0x109 CRC or checksum was invalid */
 #   endif
 #   ifdef      ESP_ERR_INVALID_VERSION
-    ERR_TBL_IT(ESP_ERR_INVALID_VERSION),                    /*   266 0x10a */
+    ERR_TBL_IT(ESP_ERR_INVALID_VERSION),                    /*   266 0x10a Version was invalid */
 #   endif
 #   ifdef      ESP_ERR_INVALID_MAC
-    ERR_TBL_IT(ESP_ERR_INVALID_MAC),                        /*   267 0x10b */
+    ERR_TBL_IT(ESP_ERR_INVALID_MAC),                        /*   267 0x10b MAC address was invalid */
 #   endif
     // components/nvs_flash/include/nvs.h
 #   ifdef      ESP_ERR_NVS_BASE
@@ -132,7 +132,7 @@ static const esp_err_msg_t esp_err_msg_table[] = {
     ERR_TBL_IT(ESP_ERR_NVS_KEY_TOO_LONG),                   /*  4361 0x1109 Key name is too long */
 #   endif
 #   ifdef      ESP_ERR_NVS_PAGE_FULL
-    ERR_TBL_IT(ESP_ERR_NVS_PAGE_FULL),                      /*  4362 0x110a Internal error; never returned by nvs_ API
+    ERR_TBL_IT(ESP_ERR_NVS_PAGE_FULL),                      /*  4362 0x110a Internal error; never returned by nvs API
                                                                             functions */
 #   endif
 #   ifdef      ESP_ERR_NVS_INVALID_STATE

components/esp32/include/esp_err.h

@@ -24,21 +24,20 @@ extern "C" {
 typedef int32_t esp_err_t;
 
 /* Definitions for error constants. */
+#define ESP_OK          0       /*!< esp_err_t value indicating success (no error) */
+#define ESP_FAIL        -1      /*!< Generic esp_err_t code indicating failure */
 
-#define ESP_OK          0
+#define ESP_ERR_NO_MEM          0x101   /*!< Out of memory */
-#define ESP_FAIL        -1
+#define ESP_ERR_INVALID_ARG     0x102   /*!< Invalid argument */
-
+#define ESP_ERR_INVALID_STATE   0x103   /*!< Invalid state */
-#define ESP_ERR_NO_MEM          0x101
+#define ESP_ERR_INVALID_SIZE    0x104   /*!< Invalid size */
-#define ESP_ERR_INVALID_ARG     0x102
+#define ESP_ERR_NOT_FOUND       0x105   /*!< Requested resource not found */
-#define ESP_ERR_INVALID_STATE   0x103
+#define ESP_ERR_NOT_SUPPORTED   0x106   /*!< Operation or feature not supported */
-#define ESP_ERR_INVALID_SIZE    0x104
+#define ESP_ERR_TIMEOUT         0x107   /*!< Operation timed out */
-#define ESP_ERR_NOT_FOUND       0x105
+#define ESP_ERR_INVALID_RESPONSE    0x108   /*!< Received response was invalid */
-#define ESP_ERR_NOT_SUPPORTED   0x106
+#define ESP_ERR_INVALID_CRC     0x109   /*!< CRC or checksum was invalid */
-#define ESP_ERR_TIMEOUT         0x107
+#define ESP_ERR_INVALID_VERSION     0x10A   /*!< Version was invalid */
-#define ESP_ERR_INVALID_RESPONSE    0x108
+#define ESP_ERR_INVALID_MAC     0x10B   /*!< MAC address was invalid */
-#define ESP_ERR_INVALID_CRC     0x109
-#define ESP_ERR_INVALID_VERSION     0x10A
-#define ESP_ERR_INVALID_MAC     0x10B
 
 #define ESP_ERR_WIFI_BASE       0x3000 /*!< Starting number of WiFi error codes */
 #define ESP_ERR_MESH_BASE       0x4000 /*!< Starting number of MESH error codes */
@@ -76,6 +75,7 @@ const char *esp_err_to_name(esp_err_t code);
   */
 const char *esp_err_to_name_r(esp_err_t code, char *buf, size_t buflen);
 
+/** @cond */
 void _esp_error_check_failed(esp_err_t rc, const char *file, int line, const char *function, const char *expression) __attribute__((noreturn));
 
 #ifndef __ASSERT_FUNC
@@ -88,6 +88,7 @@ void _esp_error_check_failed(esp_err_t rc, const char *file, int line, const cha
 #define __ASSERT_FUNC "??"
 #endif
 #endif
+/** @endcond */
 
 /**
  * Macro which can be used to check the error code,

components/nvs_flash/include/nvs.h

@@ -38,7 +38,7 @@ typedef uint32_t nvs_handle;
 #define ESP_ERR_NVS_INVALID_HANDLE      (ESP_ERR_NVS_BASE + 0x07)  /*!< Handle has been closed or is NULL */
 #define ESP_ERR_NVS_REMOVE_FAILED       (ESP_ERR_NVS_BASE + 0x08)  /*!< The value wasn’t updated because flash write operation has failed. The value was written however, and update will be finished after re-initialization of nvs, provided that flash operation doesn’t fail again. */
 #define ESP_ERR_NVS_KEY_TOO_LONG        (ESP_ERR_NVS_BASE + 0x09)  /*!< Key name is too long */
-#define ESP_ERR_NVS_PAGE_FULL           (ESP_ERR_NVS_BASE + 0x0a)  /*!< Internal error; never returned by nvs_ API functions */
+#define ESP_ERR_NVS_PAGE_FULL           (ESP_ERR_NVS_BASE + 0x0a)  /*!< Internal error; never returned by nvs API functions */
 #define ESP_ERR_NVS_INVALID_STATE       (ESP_ERR_NVS_BASE + 0x0b)  /*!< NVS is in an inconsistent state due to a previous error. Call nvs_flash_init and nvs_open again, then retry. */
 #define ESP_ERR_NVS_INVALID_LENGTH      (ESP_ERR_NVS_BASE + 0x0c)  /*!< String or blob length is not sufficient to store data */
 #define ESP_ERR_NVS_NO_FREE_PAGES       (ESP_ERR_NVS_BASE + 0x0d)  /*!< NVS partition doesn't contain any empty pages. This may happen if NVS partition was truncated. Erase the whole partition and call nvs_flash_init again. */

docs/Doxyfile

@@ -174,7 +174,9 @@ INPUT = \
     ../../components/freertos/include/freertos/semphr.h \
     ../../components/freertos/include/freertos/timers.h \
     ../../components/freertos/include/freertos/event_groups.h \
-    ../../components/freertos/include/freertos/ringbuf.h
+    ../../components/freertos/include/freertos/ringbuf.h \
+    ### Helper functions for error codes
+    ../../components/esp32/include/esp_err.h
 
 
 

docs/conf_common.py

@@ -45,6 +45,11 @@ kconfig_inc_path = '{}/inc/kconfig.inc'.format(builddir)
 os.system('python ../gen-kconfig-doc.py > ' + kconfig_inc_path + '.in')
 copy_if_modified(kconfig_inc_path + '.in', kconfig_inc_path)
 
+# Generate 'esp_err_defs.inc' file with ESP_ERR_ error code definitions
+esp_err_inc_path = '{}/inc/esp_err_defs.inc'.format(builddir)
+os.system('python ../../tools/gen_esp_err_to_name.py --rst_output ' + esp_err_inc_path + '.in')
+copy_if_modified(esp_err_inc_path + '.in', esp_err_inc_path)
+
 # http://stackoverflow.com/questions/12772927/specifying-an-online-image-in-sphinx-restructuredtext-format
 # 
 suppress_warnings = ['image.nonlocal_uri']

docs/en/api-reference/error-codes.rst

@@ -0,0 +1,8 @@
+Error Codes Reference
+=====================
+
+This section lists various error code constants defined in ESP-IDF.
+
+For general information about error codes in ESP-IDF, see :doc:`Error Handling <../api-guides/error-handling>`.
+
+.. include:: /_build/inc/esp_err_defs.inc

docs/en/api-reference/index.rst

@@ -14,4 +14,5 @@ API Reference
    Storage <storage/index>
    System <system/index>
    Configuration Options <kconfig>
+   Error Codes Reference <error-codes>
 

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

@@ -0,0 +1,14 @@
+Error Codes and Helper Functions
+================================
+
+This section lists definitions of common ESP-IDF error codes and several helper functions related to error handling.
+
+For general information about error codes in ESP-IDF, see :doc:`Error Handling <../../api-guides/error-handling>`.
+
+For the full list of error codes defined in ESP-IDF, see :doc:`Error Code Reference <../error-codes>`.
+
+API Reference
+-------------
+
+.. include:: /_build/inc/esp_err.inc
+

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

@@ -19,6 +19,7 @@ System API
    Base MAC address <base_mac_address>
    Over The Air Updates (OTA) <ota>
    ESP pthread <esp_pthread>
+   Error Codes and Helper Functions <esp_err>
 
 
 Example code for this API section is provided in :example:`system` directory of ESP-IDF examples.

docs/zh_CN/api-reference/error-codes.rst

@@ -0,0 +1 @@
+.. include:: ../../en/api-reference/error-codes.rst

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

@@ -0,0 +1 @@
+.. include:: ../../../en/api-reference/system/esp_err.rst

tools/gen_esp_err_to_name.py

@@ -204,7 +204,7 @@ def max_string_width():
                 max = x
     return max
 
-def generate_output(fin, fout):
+def generate_c_output(fin, fout):
     """
     Writes the output to fout based on th error dictionary err_dict and
     template file fin.
@@ -264,10 +264,23 @@ def generate_output(fin, fout):
         else:
             fout.write(line)
 
+def generate_rst_output(fout):
+    for k in sorted(err_dict.keys()):
+        v = err_dict[k][0]
+        fout.write(':c:macro:`{}` '.format(v.name))
+        if k > 0:
+            fout.write('**(0x{:x})**'.format(k))
+        else:
+            fout.write('({:d})'.format(k))
+        if len(v.comment) > 0:
+            fout.write(': {}'.format(v.comment))
+        fout.write('\n\n')
+
 def main():
     parser = argparse.ArgumentParser(description='ESP32 esp_err_to_name lookup generator for esp_err_t')
-    parser.add_argument('input', help='Path to the esp_err_to_name.c.in template input.', default=os.environ['IDF_PATH'] + '/components/esp32/esp_err_to_name.c.in', nargs='?')
+    parser.add_argument('--c_input', help='Path to the esp_err_to_name.c.in template input.', default=os.environ['IDF_PATH'] + '/components/esp32/esp_err_to_name.c.in')
-    parser.add_argument('output', help='Path to the esp_err_to_name.c output.', default=os.environ['IDF_PATH'] + '/components/esp32/esp_err_to_name.c', nargs='?')
+    parser.add_argument('--c_output', help='Path to the esp_err_to_name.c output.', default=os.environ['IDF_PATH'] + '/components/esp32/esp_err_to_name.c')
+    parser.add_argument('--rst_output', help='Generate .rst output and save it into this file')
     args = parser.parse_args()
 
     for root, dirnames, filenames in os.walk(os.environ['IDF_PATH']):
@@ -287,8 +300,12 @@ def main():
 
     process_remaining_errors()
 
-    with open(args.input, 'r') as fin, open(args.output, 'w') as fout:
+    if args.rst_output is not None:
-        generate_output(fin, fout)
+        with open(args.rst_output, 'w') as fout:
+            generate_rst_output(fout)
+    else:
+        with open(args.c_input, 'r') as fin, open(args.c_output, 'w') as fout:
+            generate_c_output(fin, fout)
 
 if __name__ == "__main__":
     main()