1API Conventions
2===============
3
4.. highlight:: c
5
6This document describes conventions and assumptions common to ESP-IDF Application Programming Interfaces (APIs).
7
8ESP-IDF provides several kinds of programming interfaces:
9
10* C functions, structures, enums, type definitions and preprocessor macros declared in public header files of ESP-IDF components. Various pages in the API Reference section of the programming guide contain descriptions of these functions, structures and types.
11* Build system functions, predefined variables and options. These are documented in the :ref:`build system guide<cmake_buildsystem_api>`.
12* `Kconfig <kconfig>`_ options can can be used in code and in the build system (CMakeLists.txt) files.
13* :doc:`Host tools <../api-guides/tools/index>` and their command line parameters are also part of ESP-IDF interface.
14
15ESP-IDF consists of components written specifically for ESP-IDF as well as third-party libraries. In some cases, an ESP-IDF-specific wrapper is added to the third-party library, providing an interface that is either simpler or better integrated with the rest of ESP-IDF facilities. In other cases, the original API of the third-party library is presented to the application developers.
16
17Following sections explain some of the aspects of ESP-IDF APIs and their usage.
18
19Error handling
20--------------
21
22Most ESP-IDF APIs return error codes defined with ``esp_err_t`` type. See :doc:`Error Handling <../api-guides/error-handling>` section for more information about error handling approaches. :doc:`Error Code Reference <error-codes>` contains the list of error codes returned by ESP-IDF components.
23
24.. _api_reference_config_structures:
25
26Configuration structures
27------------------------
28
29.. important:: Correct initialization of configuration structures is an important part in making the application compatible with future versions of ESP-IDF.
30
31Most initialization or configuration functions in ESP-IDF take as an argument a pointer to a configuration structure. For example::
32
33    const esp_timer_create_args_t my_timer_args = {
34        .callback = &my_timer_callback,
35        .arg = callback_arg,
36        .name = "my_timer"
37    };
38    esp_timer_handle_t my_timer;
39    esp_err_t err = esp_timer_create(&my_timer_args, &my_timer);
40
41Initialization functions never store the pointer to the configuration structure, so it is safe to allocate the structure on the stack.
42
43The application must initialize all fields of the structure. The following is incorrect::
44
45    esp_timer_create_args_t my_timer_args;
46    my_timer_args.callback = &my_timer_callback;
47    /* Incorrect! Fields .arg and .name are not initialized */
48    esp_timer_create(&my_timer_args, &my_timer);
49
50Most ESP-IDF examples use C99 `designated initializers`_ for structure initialization, since they provide a concise way of setting a subset of fields, and zero-initializing the remaining fields::
51
52    const esp_timer_create_args_t my_timer_args = {
53        .callback = &my_timer_callback,
54        /* Correct, fields .arg and .name are zero-initialized */
55    };
56
57C++ language doesn't support the designated initializers syntax until C++20, however GCC compiler partially supports it as an extension. When using ESP-IDF APIs in C++ code, you may consider using the following pattern::
58
59    esp_timer_create_args_t my_timer_args = {};
60    /* All the fields are zero-initialized */
61    my_timer_args.callback = &my_timer_callback;
62
63Default initializers
64^^^^^^^^^^^^^^^^^^^^
65
66For some configuration structures, ESP-IDF provides macros for setting default values of fields::
67
68    httpd_config_t config = HTTPD_DEFAULT_CONFIG();
69    /* HTTPD_DEFAULT_CONFIG expands to a designated initializer.
70       Now all fields are set to the default values.
71       Any field can still be modified: */
72    config.server_port = 8081;
73    httpd_handle_t server;
74    esp_err_t err = httpd_start(&server, &config);
75
76It is recommended to use default initializer macros whenever they are provided for a particular configuration structure.
77
78.. _api_reference_private_apis:
79
80Private APIs
81------------
82
83Certain header files in ESP-IDF contain APIs intended to be used only in ESP-IDF source code, and not by the applications. Such header files often contain ``private`` or ``esp_private`` in their name or path. Certain components, such as :doc:`hal <../api-guides/hardware-abstraction>` only contain private APIs.
84
85Private APIs may be removed or changed in an incompatible way between minor or patch releases.
86
87.. _api_reference_example_components:
88
89Components in example projects
90------------------------------
91
92ESP-IDF examples contain a variety of projects demonstrating usage of ESP-IDF APIs. In order to reduce code duplication in the examples, a few common helpers are defined inside components that are used by multiple examples. This includes components located in :example:`common_components` directory, as well as some of the components located in the examples themselves. These components are not considered to be part of the ESP-IDF API.
93
94It is not recommended to reference these components directly in custom projects (via ``EXTRA_COMPONENT_DIRS`` build system variable), as they may change significantly between ESP-IDF versions. When starting a new project based on an ESP-IDF example, copy both the project and the common components it depends on out of ESP-IDF, and treat the common components as part of the project. Note that the common components are written with examples in mind, and might not include all the error handling required for production applications. Take time to read the code and understand if it applicable to your use case.
95
96API Stability
97-------------
98
99ESP-IDF uses `Semantic Versioning <http://semver.org/>`_ as explained in the :ref:`versions page<versioning-scheme>`.
100
101Minor and bugfix releases of ESP-IDF guarantee compatibility with previous releases. The sections below explain different aspects and limitations to compatibility.
102
103Source level compatibility
104^^^^^^^^^^^^^^^^^^^^^^^^^^
105
106ESP-IDF guarantees source level compatibility of C functions, structures, enums, type definitions and preprocessor macros declared in public header files of ESP-IDF components. Source level compatibility implies that the application can be recompiled with the newer version of ESP-IDF without changes.
107
108The following changes are allowed between minor versions and do not break source level compatibility:
109
110* Deprecating functions (using the ``deprecated`` attribute) and header files (using a preprocessor ``#warning``). Deprecations are listed in ESP-IDF relese notes. It is recommended to update the source code to use the newer functions or files that replace the deprecated ones, however this is not mandatory. Deprecated functions and files can be removed in major versions of ESP-IDF.
111* Renaming components, moving source and header files between components — provided that the build system ensures that correct files are still found.
112* Renaming Kconfig options. Kconfig system `renaming mechanism <configuration-options-compatibility>`_ ensures that the original Kconfig option names can still be used by the application in ``sdkconfig`` file, CMake files and source code.
113
114Lack of binary compatibility
115^^^^^^^^^^^^^^^^^^^^^^^^^^^^
116
117ESP-IDF does not guarantee binary compatibility between releases. This means that if a precompiled library is built with one ESP-IDF version, it is not guaranteed to work the same way with the next minor or bugfix release. The following are the possible changes that keep source level compatibility but not binary compatibility:
118
119* Changing numerical values for C enum members.
120* Adding new structure members or changing the order of members. See :ref:`api_reference_config_structures` for tips that help ensure compatibility.
121* Replacing an ``extern`` function with a ``static inline`` one with the same signature, or vice versa.
122* Replacing a function-like macro with a compatible C function.
123
124Other exceptions from compatibility
125^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
126
127While we try to make upgrading to a new ESP-IDF version easy, there are parts of ESP-IDF that may change between minor versions in an incompatible way. We appreciate issue reports about any unintended breaking changes that don't fall into the categories below.
128
129* :ref:`api_reference_private_apis`.
130* :ref:`api_reference_example_components`.
131* Features clearly marked as "beta", "preview", or "experimental".
132* Changes made to mitigate security issues or to replace insecure default behaviors with a secure ones.
133* Features which were never functional. For example, if it was never possible to use a certain function or an enumeration value, it may get renamed (as part of fixing it) or removed. This includes software features which depend on non-functional chip hardware features.
134* Unexpected or undefined behavior (for example, due to missing validation of argument ranges) that is not documented explicitly may be fixed/changed.
135* Location of `Kconfig <kconfig>`_ options in menuconfig.
136* Location and names of example projects.
137
138.. _designated initializers: https://en.cppreference.com/w/c/language/struct_initialization
139