espressif/esp-idf
1
0
Fork 1
mirror of https://github.com/espressif/esp-idf.git synced 2025-07-30 02:37:19 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: add error codes reference

Browse Source
This commit is contained in:
Ivan Grokhotkov
2018-06-13 16:07:26 +08:00
parent 5e0a3d99e8
commit d9f8311b9d
12 changed files with 86 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
components/esp32/esp_err_to_name.c
View File

@ -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

29
components/esp32/include/esp_err.h
View File

@ -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,

2
components/nvs_flash/include/nvs.h
View File

@ -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. */

4
docs/Doxyfile
View File

@ -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

5
docs/conf_common.py
View File

@ -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']

8
docs/en/api-reference/error-codes.rst Normal file
View File

@ -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

1
docs/en/api-reference/index.rst
View File

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

14
docs/en/api-reference/system/esp_err.rst Normal file
View File

@ -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

1
docs/en/api-reference/system/index.rst
View File

@ -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.

1
docs/zh_CN/api-reference/error-codes.rst Normal file
View File

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

1
docs/zh_CN/api-reference/system/esp_err.rst Normal file
View File

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

27
tools/gen_esp_err_to_name.py
View File

@ -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()