mirror of
https://github.com/espressif/esp-idf.git
synced 2026-08-18 06:35:35 +03:00
89 lines
3.0 KiB
ReStructuredText
89 lines
3.0 KiB
ReStructuredText
错误代码和辅助函数
|
|
================================
|
|
|
|
:link_to_translation:`en:[English]`
|
|
|
|
本节列出了 ESP-IDF 中常见错误代码的定义，以及部分与错误处理相关的辅助函数。
|
|
|
|
有关 ESP-IDF 中错误代码的基本信息，请参阅 :doc:`错误处理 <../../api-guides/error-handling>`。
|
|
|
|
有关 ESP-IDF 定义的错误代码的完整列表，请参阅 :doc:`错误代码参考 <../error-codes>`。
|
|
|
|
.. _registering-error-codes:
|
|
|
|
注册错误码
|
|
----------
|
|
|
|
ESP-IDF 使用可组合的错误码注册系统，在构建时自动从所有组件中收集错误码定义。这使得 :cpp:func:`esp_err_to_name` 和 :cpp:func:`esp_err_to_name_r` 能够查找整个项目中定义的错误码，而无需手动维护中央注册表。
|
|
|
|
工作原理
|
|
^^^^^^^^
|
|
|
|
错误码在链接时通过名为 ``.esp_err_msg_tbl`` 的链接器段进行注册。在组件的头文件中定义错误码后，需要将这些头文件注册到构建系统中，构建系统将会：
|
|
|
|
1. 在构建过程中提取错误码定义
|
|
2. 生成 C 代码，将错误码放入 ``.esp_err_msg_tbl`` 段
|
|
3. 自动将生成的 C 代码链接到应用程序中
|
|
|
|
链接器会将所有组件中的错误码条目收集到一个数组中，供 :cpp:func:`esp_err_to_name` 在运行时查找。
|
|
|
|
注册组件的错误码
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
要注册组件中的错误码，请在组件的 ``CMakeLists.txt`` 中添加以下内容：
|
|
|
|
.. code-block:: cmake
|
|
|
|
idf_define_esp_err_codes(HEADERS include/my_component.h)
|
|
|
|
将 ``include/my_component.h`` 替换为包含错误码定义的头文件路径。可以指定多个头文件：
|
|
|
|
.. code-block:: cmake
|
|
|
|
idf_define_esp_err_codes(HEADERS
|
|
include/my_api.h
|
|
include/my_driver.h
|
|
)
|
|
|
|
构建系统将自动处理这些头文件，并注册所有符合错误码命名规则的 ``#define`` 指令（通常以 ``ESP_ERR_`` 或类似前缀开头）。
|
|
|
|
示例
|
|
^^^^
|
|
|
|
在组件的头文件 ``include/my_component.h`` 中：
|
|
|
|
.. code-block:: c
|
|
|
|
#pragma once
|
|
|
|
#include "esp_err.h"
|
|
|
|
#define ESP_ERR_MY_COMPONENT_BASE 0x7000
|
|
#define ESP_ERR_MY_COMPONENT_INIT (ESP_ERR_MY_COMPONENT_BASE + 1) /*!< Component initialization failed */
|
|
#define ESP_ERR_MY_COMPONENT_BUSY (ESP_ERR_MY_COMPONENT_BASE + 2) /*!< Component is busy */
|
|
|
|
在组件的 ``CMakeLists.txt`` 中：
|
|
|
|
.. code-block:: cmake
|
|
|
|
idf_component_register(SRCS "my_component.c"
|
|
INCLUDE_DIRS "include"
|
|
PRIV_REQUIRES esp_common)
|
|
|
|
# Register error codes
|
|
idf_define_esp_err_codes(HEADERS include/my_component.h)
|
|
|
|
构建项目后，调用 ``esp_err_to_name(ESP_ERR_MY_COMPONENT_INIT)`` 将返回字符串 ``"ESP_ERR_MY_COMPONENT_INIT"``。
|
|
|
|
.. note::
|
|
|
|
大多数 ESP-IDF 组件的错误码已经完成注册，只有在为自定义组件注册错误码，或向现有组件添加新错误码时，才需要添加 ``idf_define_esp_err_codes()``。
|
|
|
|
.. _esp-check-api-ref:
|
|
|
|
API 参考
|
|
-------------
|
|
|
|
.. include-build-file:: inc/esp_check.inc
|
|
.. include-build-file:: inc/esp_err.inc
|