diff --git a/components/esp32/esp_err_to_name.c b/components/esp32/esp_err_to_name.c index a85eb0a9ca..96f77a4d93 100644 --- a/components/esp32/esp_err_to_name.c +++ b/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 diff --git a/components/esp32/include/esp_err.h b/components/esp32/include/esp_err.h index b38a723bc3..d8820e5ae1 100644 --- a/components/esp32/include/esp_err.h +++ b/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_FAIL -1 - -#define ESP_ERR_NO_MEM 0x101 -#define ESP_ERR_INVALID_ARG 0x102 -#define ESP_ERR_INVALID_STATE 0x103 -#define ESP_ERR_INVALID_SIZE 0x104 -#define ESP_ERR_NOT_FOUND 0x105 -#define ESP_ERR_NOT_SUPPORTED 0x106 -#define ESP_ERR_TIMEOUT 0x107 -#define ESP_ERR_INVALID_RESPONSE 0x108 -#define ESP_ERR_INVALID_CRC 0x109 -#define ESP_ERR_INVALID_VERSION 0x10A -#define ESP_ERR_INVALID_MAC 0x10B +#define ESP_ERR_NO_MEM 0x101 /*!< Out of memory */ +#define ESP_ERR_INVALID_ARG 0x102 /*!< Invalid argument */ +#define ESP_ERR_INVALID_STATE 0x103 /*!< Invalid state */ +#define ESP_ERR_INVALID_SIZE 0x104 /*!< Invalid size */ +#define ESP_ERR_NOT_FOUND 0x105 /*!< Requested resource not found */ +#define ESP_ERR_NOT_SUPPORTED 0x106 /*!< Operation or feature not supported */ +#define ESP_ERR_TIMEOUT 0x107 /*!< Operation timed out */ +#define ESP_ERR_INVALID_RESPONSE 0x108 /*!< Received response was invalid */ +#define ESP_ERR_INVALID_CRC 0x109 /*!< CRC or checksum was invalid */ +#define ESP_ERR_INVALID_VERSION 0x10A /*!< Version was invalid */ +#define ESP_ERR_INVALID_MAC 0x10B /*!< MAC address was invalid */ #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, diff --git a/components/nvs_flash/include/nvs.h b/components/nvs_flash/include/nvs.h index c58f62f9c6..b3ba37fb4f 100644 --- a/components/nvs_flash/include/nvs.h +++ b/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. */ diff --git a/docs/Doxyfile b/docs/Doxyfile index 98c698275a..396963ea1e 100644 --- a/docs/Doxyfile +++ b/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 diff --git a/docs/conf_common.py b/docs/conf_common.py index bc6d7e401d..ed22db5452 100644 --- a/docs/conf_common.py +++ b/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'] diff --git a/docs/en/api-reference/error-codes.rst b/docs/en/api-reference/error-codes.rst new file mode 100644 index 0000000000..d8e7c4fac4 --- /dev/null +++ b/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 diff --git a/docs/en/api-reference/index.rst b/docs/en/api-reference/index.rst index 60917a8674..e35c4cc39c 100644 --- a/docs/en/api-reference/index.rst +++ b/docs/en/api-reference/index.rst @@ -14,4 +14,5 @@ API Reference Storage System Configuration Options + Error Codes Reference diff --git a/docs/en/api-reference/system/esp_err.rst b/docs/en/api-reference/system/esp_err.rst new file mode 100644 index 0000000000..a3d4cb69d4 --- /dev/null +++ b/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 + diff --git a/docs/en/api-reference/system/index.rst b/docs/en/api-reference/system/index.rst index bdc5d68e22..d9a32fd4e4 100644 --- a/docs/en/api-reference/system/index.rst +++ b/docs/en/api-reference/system/index.rst @@ -19,6 +19,7 @@ System API Base MAC address Over The Air Updates (OTA) ESP pthread + Error Codes and Helper Functions Example code for this API section is provided in :example:`system` directory of ESP-IDF examples. diff --git a/docs/zh_CN/api-reference/error-codes.rst b/docs/zh_CN/api-reference/error-codes.rst new file mode 100644 index 0000000000..5179dae2cf --- /dev/null +++ b/docs/zh_CN/api-reference/error-codes.rst @@ -0,0 +1 @@ +.. include:: ../../en/api-reference/error-codes.rst \ No newline at end of file diff --git a/docs/zh_CN/api-reference/system/esp_err.rst b/docs/zh_CN/api-reference/system/esp_err.rst new file mode 100644 index 0000000000..1edde443d4 --- /dev/null +++ b/docs/zh_CN/api-reference/system/esp_err.rst @@ -0,0 +1 @@ +.. include:: ../../../en/api-reference/system/esp_err.rst diff --git a/tools/gen_esp_err_to_name.py b/tools/gen_esp_err_to_name.py index 7281ed5511..f72f865c6f 100755 --- a/tools/gen_esp_err_to_name.py +++ b/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('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_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('--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: - generate_output(fin, fout) + if args.rst_output is not None: + 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()