mirror of
https://github.com/espressif/esp-idf.git
synced 2026-10-02 03:00:34 +03:00
docs(kconfig): update kconfig ref links to use menuitem
This commit is contained in:
Marius Vikhammer
@@ -117,7 +117,7 @@ Task Watchdog Timers
|
||||
- Configuration is now passed as a configuration structure.
|
||||
- The function will now handle subscribing of the idle tasks if configured to do so.
|
||||
|
||||
- The former ``CONFIG_ESP_TASK_WDT`` configuration option has been renamed to :ref:`CONFIG_ESP_TASK_WDT_INIT` and a new :ref:`CONFIG_ESP_TASK_WDT_EN` option has been introduced.
|
||||
- The former ``CONFIG_ESP_TASK_WDT`` configuration option has been renamed to :menuitem:`CONFIG_ESP_TASK_WDT_INIT` and a new :menuitem:`CONFIG_ESP_TASK_WDT_EN` option has been introduced.
|
||||
|
||||
FreeRTOS
|
||||
--------
|
||||
@@ -128,7 +128,7 @@ Legacy API and Data Types
|
||||
Previously, the ``configENABLE_BACKWARD_COMPATIBILITY`` option was set by default, thus allowing pre FreeRTOS v8.0.0 function names and data types to be used. The ``configENABLE_BACKWARD_COMPATIBILITY`` is now disabled by default, thus legacy FreeRTOS names/types are no longer supported by default. Users should do one of the following:
|
||||
|
||||
- Update their code to remove usage of legacy FreeRTOS names/types.
|
||||
- Enable the :ref:`CONFIG_FREERTOS_ENABLE_BACKWARD_COMPATIBILITY` to explicitly allow the usage of legacy names/types.
|
||||
- Enable the :menuitem:`CONFIG_FREERTOS_ENABLE_BACKWARD_COMPATIBILITY` to explicitly allow the usage of legacy names/types.
|
||||
|
||||
Tasks Snapshot
|
||||
^^^^^^^^^^^^^^
|
||||
@@ -169,6 +169,6 @@ Bootloader Support
|
||||
Chip Revision
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
The bootloader checks the chip revision at the beginning of the application loading. The application can only be loaded if the version is ``>=`` :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN` and ``<`` ``CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MAX_FULL``.
|
||||
The bootloader checks the chip revision at the beginning of the application loading. The application can only be loaded if the version is ``>=`` :menuitem:`CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN` and ``<`` ``CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MAX_FULL``.
|
||||
|
||||
During the OTA upgrade, the version requirements and chip revision in the application header are checked for compatibility. The application can only be updated if the version is ``>=`` :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN` and ``<`` ``CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MAX_FULL``.
|
||||
During the OTA upgrade, the version requirements and chip revision in the application header are checked for compatibility. The application can only be updated if the version is ``>=`` :menuitem:`CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MIN` and ``<`` ``CONFIG_{IDF_TARGET_CFG_PREFIX}_REV_MAX_FULL``.
|
||||
|
||||
@@ -8,7 +8,7 @@ ESP-IDF Monitor
|
||||
|
||||
ESP-IDF Monitor makes the following changes regarding baud-rate:
|
||||
|
||||
- ESP-IDF monitor now uses the custom console baud-rate (:ref:`CONFIG_ESP_CONSOLE_UART_BAUDRATE`) by default instead of 115200.
|
||||
- ESP-IDF monitor now uses the custom console baud-rate (:menuitem:`CONFIG_ESP_CONSOLE_UART_BAUDRATE`) by default instead of 115200.
|
||||
- Setting a custom baud from menuconfig is no longer supported.
|
||||
- A custom baud-rate can be specified from command line with the ``idf.py monitor -b <baud>`` command or through setting environment variables.
|
||||
- Please note that the baud-rate argument has been renamed from ``-B`` to ``-b`` in order to be consistent with the global baud-rate ``idf.py -b <baud>``. Run ``idf.py monitor --help`` for more information.
|
||||
@@ -46,7 +46,7 @@ Deprecated Commands
|
||||
Esptool
|
||||
-------
|
||||
|
||||
The ``CONFIG_ESPTOOLPY_FLASHSIZE_DETECT`` option has been renamed to :ref:`CONFIG_ESPTOOLPY_HEADER_FLASHSIZE_UPDATE` and has been disabled by default. New and existing projects migrated to ESP-IDF v5.0 have to set :ref:`CONFIG_ESPTOOLPY_FLASHSIZE`. If this is not possible due to an unknown flash size at build time, then :ref:`CONFIG_ESPTOOLPY_HEADER_FLASHSIZE_UPDATE` can be enabled. However, once enabled, to keep the digest valid, an SHA256 digest is no longer appended to the image when updating the binary header with the flash size during flashing.
|
||||
The ``CONFIG_ESPTOOLPY_FLASHSIZE_DETECT`` option has been renamed to :menuitem:`CONFIG_ESPTOOLPY_HEADER_FLASHSIZE_UPDATE` and has been disabled by default. New and existing projects migrated to ESP-IDF v5.0 have to set :menuitem:`CONFIG_ESPTOOLPY_FLASHSIZE`. If this is not possible due to an unknown flash size at build time, then :menuitem:`CONFIG_ESPTOOLPY_HEADER_FLASHSIZE_UPDATE` can be enabled. However, once enabled, to keep the digest valid, an SHA256 digest is no longer appended to the image when updating the binary header with the flash size during flashing.
|
||||
|
||||
Windows Environment
|
||||
--------------------
|
||||
|
||||
@@ -11,7 +11,7 @@ FreeRTOS
|
||||
Dynamic Memory Allocation
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
In the past, FreeRTOS commonly utilized the function ``malloc()`` to allocate dynamic memory. As a result, if an application allowed ``malloc()`` to allocate memory from external RAM (by configuring the :ref:`CONFIG_SPIRAM_USE` option as ``CONFIG_SPIRAM_USE_MALLOC``), FreeRTOS had the potential to allocate dynamic memory from external RAM, and the specific location was determined by the heap allocator.
|
||||
In the past, FreeRTOS commonly utilized the function ``malloc()`` to allocate dynamic memory. As a result, if an application allowed ``malloc()`` to allocate memory from external RAM (by configuring the :menuitem:`CONFIG_SPIRAM_USE` option as ``CONFIG_SPIRAM_USE_MALLOC``), FreeRTOS had the potential to allocate dynamic memory from external RAM, and the specific location was determined by the heap allocator.
|
||||
|
||||
.. note::
|
||||
|
||||
@@ -23,7 +23,7 @@ FreeRTOS
|
||||
|
||||
.. warning::
|
||||
|
||||
If you previously relied on :ref:`CONFIG_SPIRAM_USE` to place FreeRTOS objects into external memory, this change will lead to increased usage of internal memory due the FreeRTOS objects now being allocated there.
|
||||
If you previously relied on :menuitem:`CONFIG_SPIRAM_USE` to place FreeRTOS objects into external memory, this change will lead to increased usage of internal memory due the FreeRTOS objects now being allocated there.
|
||||
|
||||
To place a FreeRTOS task/object into external memory, it is now necessary to do so explicitly. The following methods can be employed:
|
||||
|
||||
|
||||
@@ -7,5 +7,5 @@ NVS Encryption
|
||||
--------------
|
||||
|
||||
- For SoCs with the HMAC peripheral (``SOC_HMAC_SUPPORTED``), turning on :doc:`../../../security/flash-encryption` will no longer automatically turn on :doc:`../../../api-reference/storage/nvs_encryption`.
|
||||
- You will need to explicitly turn on NVS encryption and select the required scheme (flash encryption-based or HMAC peripheral-based). You can select the HMAC peripheral-based scheme (:ref:`CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME`), even if flash encryption is not enabled.
|
||||
- You will need to explicitly turn on NVS encryption and select the required scheme (flash encryption-based or HMAC peripheral-based). You can select the HMAC peripheral-based scheme (:menuitem:`CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME`), even if flash encryption is not enabled.
|
||||
- SoCs without the HMAC peripheral will still automatically turn on NVS encryption when flash encryption is enabled.
|
||||
|
||||
@@ -11,7 +11,7 @@ IDF FreeRTOS Upgrade
|
||||
|
||||
The IDF FreeRTOS kernel (which is a dual-core SMP implementation of FreeRTOS) has been upgraded to be based on Vanilla FreeRTOS v10.5.1. With this upgrade, the design and implementation of IDF FreeRTOS has also been changed significantly. As a result, users should take note of the following changes to kernel behavior and API:
|
||||
|
||||
- When enabling single-core mode via the :ref:`CONFIG_FREERTOS_UNICORE` option, the kernel's behavior will now be identical to Vanilla FreeRTOS (see :ref:`freertos-idf-single-core` for more details).
|
||||
- When enabling single-core mode via the :menuitem:`CONFIG_FREERTOS_UNICORE` option, the kernel's behavior will now be identical to Vanilla FreeRTOS (see :ref:`freertos-idf-single-core` for more details).
|
||||
- For SMP related APIs that were added by IDF FreeRTOS, checks on ``xCoreID`` arguments are now stricter. Providing out of range values for ``xCoreID`` arguments will now trigger an assert.
|
||||
- The following SMP related APIs are now deprecated and replaced due to naming consistency reasons:
|
||||
|
||||
@@ -39,4 +39,4 @@ The Task Snapshot API has been made private due to a lack of a practical way for
|
||||
Panic Handler Behavior
|
||||
----------------------
|
||||
|
||||
The choice ``CONFIG_ESP_SYSTEM_PANIC_GDBSTUB`` in the configuration option :ref:`CONFIG_ESP_SYSTEM_PANIC` has been made dependent on whether the ``esp_gdbstub`` component is included in the build. When trimming the list of components in the build using ``set(COMPONENTS main)``, ``esp_gdbstub`` component has to be added to this list of components to make the ``CONFIG_ESP_SYSTEM_PANIC_GDBSTUB`` option available.
|
||||
The choice ``CONFIG_ESP_SYSTEM_PANIC_GDBSTUB`` in the configuration option :menuitem:`CONFIG_ESP_SYSTEM_PANIC` has been made dependent on whether the ``esp_gdbstub`` component is included in the build. When trimming the list of components in the build using ``set(COMPONENTS main)``, ``esp_gdbstub`` component has to be added to this list of components to make the ``CONFIG_ESP_SYSTEM_PANIC_GDBSTUB`` option available.
|
||||
|
||||
@@ -9,6 +9,6 @@ HTTPS Server
|
||||
Certificate Selection Hook
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In order to enable the Certificate Selection hook feature in ESP HTTPS Server, now you need to enable :ref:`CONFIG_ESP_HTTPS_SERVER_CERT_SELECT_HOOK` instead of :ref:`CONFIG_ESP_TLS_SERVER_CERT_SELECT_HOOK`.
|
||||
In order to enable the Certificate Selection hook feature in ESP HTTPS Server, now you need to enable :menuitem:`CONFIG_ESP_HTTPS_SERVER_CERT_SELECT_HOOK` instead of :menuitem:`CONFIG_ESP_TLS_SERVER_CERT_SELECT_HOOK`.
|
||||
|
||||
The new :ref:`CONFIG_ESP_HTTPS_SERVER_CERT_SELECT_HOOK` option automatically selects :ref:`CONFIG_ESP_TLS_SERVER_CERT_SELECT_HOOK`.
|
||||
The new :menuitem:`CONFIG_ESP_HTTPS_SERVER_CERT_SELECT_HOOK` option automatically selects :menuitem:`CONFIG_ESP_TLS_SERVER_CERT_SELECT_HOOK`.
|
||||
|
||||
@@ -13,7 +13,7 @@ Peripherals
|
||||
- The new driver is in ``esp_driver_touch_sens`` component and the include path is ``driver/touch_sens.h``.
|
||||
- The legacy driver is still available in the previous include path ``driver/touch_sensor.h``.
|
||||
|
||||
Although it is recommended to use the new driver APIs, the legacy driver is still available in the previous include path ``driver/touch_sensor.h``. However, by default, including ``driver/touch_sensor.h`` triggers the build warning below. The warning can be suppressed by the Kconfig option :ref:`CONFIG_TOUCH_SUPPRESS_DEPRECATE_WARN`.
|
||||
Although it is recommended to use the new driver APIs, the legacy driver is still available in the previous include path ``driver/touch_sensor.h``. However, by default, including ``driver/touch_sensor.h`` triggers the build warning below. The warning can be suppressed by the Kconfig option :menuitem:`CONFIG_TOUCH_SUPPRESS_DEPRECATE_WARN`.
|
||||
|
||||
The major changes are listed as follows:
|
||||
|
||||
@@ -57,5 +57,5 @@ Peripherals
|
||||
|
||||
Although we recommend using the new TWAI driver APIs, the legacy driver is still available. To use the legacy driver, include the header file ``driver/twai.h``. When using the legacy driver, please note the following:
|
||||
|
||||
- The new and legacy drivers are not compatible and must not be used together. Mixing them will trigger warnings during startup, and may even cause crashes and system reboots. To suppress this compatibility check, you may enable the configuration option :ref:`CONFIG_TWAI_SKIP_LEGACY_CONFLICT_CHECK`.
|
||||
- The new and legacy drivers are not compatible and must not be used together. Mixing them will trigger warnings during startup, and may even cause crashes and system reboots. To suppress this compatibility check, you may enable the configuration option :menuitem:`CONFIG_TWAI_SKIP_LEGACY_CONFLICT_CHECK`.
|
||||
- The legacy driver will no longer receive new features, such as TWAI FD (Flexible Data-rate) support.
|
||||
|
||||
@@ -6,7 +6,7 @@ Protocols
|
||||
ESP HTTP SERVER
|
||||
---------------
|
||||
|
||||
:ref:`CONFIG_HTTPD_MAX_REQ_HDR_LEN`
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
:menuitem:`CONFIG_HTTPD_MAX_REQ_HDR_LEN`
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The :ref:`CONFIG_HTTPD_MAX_REQ_HDR_LEN` option now defines the maximum limit for the memory that can be allocated internally for the HTTP request header. The actual memory allocated for the header depends on the size of the header received in the HTTP request, rather than being fixed to this value as before. This provides more flexible memory usage based on the actual header size.
|
||||
The :menuitem:`CONFIG_HTTPD_MAX_REQ_HDR_LEN` option now defines the maximum limit for the memory that can be allocated internally for the HTTP request header. The actual memory allocated for the header depends on the size of the header received in the HTTP request, rather than being fixed to this value as before. This provides more flexible memory usage based on the actual header size.
|
||||
|
||||
@@ -11,7 +11,7 @@ Time
|
||||
Log
|
||||
---
|
||||
|
||||
**Log V2** is introduced in this ESP-IDF version as an enhanced and optional logging implementation. It is fully compatible with **Log V1**, allowing projects to continue using **Log V1** without changes. Developers can enable **Log V2** via the Kconfig option :ref:`CONFIG_LOG_VERSION`. In future ESP-IDF versions, **Log V2** may become the default.
|
||||
**Log V2** is introduced in this ESP-IDF version as an enhanced and optional logging implementation. It is fully compatible with **Log V1**, allowing projects to continue using **Log V1** without changes. Developers can enable **Log V2** via the Kconfig option :menuitem:`CONFIG_LOG_VERSION`. In future ESP-IDF versions, **Log V2** may become the default.
|
||||
|
||||
**Key Points**
|
||||
|
||||
|
||||
@@ -19,7 +19,7 @@ If you encounter an orphan section error during linking, you can resolve it usin
|
||||
|
||||
1. Remove the code or data that causes the orphan section, if it's unused or unnecessary.
|
||||
2. Explicitly place the orphan section using a :ref:`linker fragment file <ldgen-linker-fragment-files>`.
|
||||
3. Suppress errors by setting :ref:`CONFIG_COMPILER_ORPHAN_SECTIONS` to ``warning`` or ``place``.
|
||||
3. Suppress errors by setting :menuitem:`CONFIG_COMPILER_ORPHAN_SECTIONS` to ``warning`` or ``place``.
|
||||
|
||||
.. warning::
|
||||
|
||||
@@ -83,4 +83,4 @@ ESP-IDF v6 uses esp-idf-kconfig v3, which introduces several changes in the conf
|
||||
Compiler Options
|
||||
----------------
|
||||
|
||||
The default compiler warnings will be considered as errors. The configuration option :ref:`CONFIG_COMPILER_DISABLE_DEFAULT_ERRORS` has been changed to N.
|
||||
The default compiler warnings will be considered as errors. The configuration option :menuitem:`CONFIG_COMPILER_DISABLE_DEFAULT_ERRORS` has been changed to N.
|
||||
|
||||
@@ -204,7 +204,7 @@ UART
|
||||
|
||||
- ESP-IDF will not provide updates, bug fixes, or security patches for the legacy driver timely.
|
||||
- Users are strongly recommended to migrate to the new I2C drivers: ``driver/i2c_master.h`` and ``driver/i2c_slave.h``.
|
||||
- To temporarily suppress the compile-time warning, enable ``Component config`` > ``Legacy Driver Configurations`` > ``Legacy I2C Driver Configurations`` > ``Suppress legacy driver deprecated warning`` in menuconfig.
|
||||
- To temporarily suppress the compile-time warning, enable :menuitem:`CONFIG_I2C_SUPPRESS_DEPRECATE_WARN`.
|
||||
|
||||
The new I2C drivers provide improved slave and master functionality. For details, please refer to the :ref:`I2C Migration Guide <migration_guide_i2c_driver_5_2>` and the :doc:`I2C Driver Programming Guide <../../../api-reference/peripherals/i2c>`.
|
||||
|
||||
@@ -351,17 +351,17 @@ Migration example:
|
||||
SPI
|
||||
---
|
||||
|
||||
- The :ref:`CONFIG_SPI_MASTER_IN_IRAM` option is now invisible by default in menuconfig and depends on :ref:`CONFIG_FREERTOS_IN_IRAM`. This change was made to prevent potential crashes when SPI functions in IRAM call FreeRTOS functions that are placed in flash.
|
||||
- The :menuitem:`CONFIG_SPI_MASTER_IN_IRAM` option is now invisible by default in menuconfig and depends on :menuitem:`CONFIG_FREERTOS_IN_IRAM`. This change was made to prevent potential crashes when SPI functions in IRAM call FreeRTOS functions that are placed in flash.
|
||||
- To enable SPI master IRAM optimization:
|
||||
|
||||
1. Navigate to ``Component config`` → ``FreeRTOS`` → ``Port`` in menuconfig.
|
||||
2. Enable ``Place FreeRTOS functions in IRAM`` (:ref:`CONFIG_FREERTOS_IN_IRAM`).
|
||||
2. Enable ``Place FreeRTOS functions in IRAM`` (:menuitem:`CONFIG_FREERTOS_IN_IRAM`).
|
||||
3. Navigate to ``Component config`` → ``ESP-Driver:SPI Configurations`` in menuconfig.
|
||||
4. Enable ``Place transmitting functions of SPI master into IRAM`` (:ref:`CONFIG_SPI_MASTER_IN_IRAM`).
|
||||
4. Enable ``Place transmitting functions of SPI master into IRAM`` (:menuitem:`CONFIG_SPI_MASTER_IN_IRAM`).
|
||||
|
||||
.. note::
|
||||
|
||||
Note that enabling :ref:`CONFIG_FREERTOS_IN_IRAM` will increase IRAM usage. Consider this trade-off when optimizing for SPI performance.
|
||||
Note that enabling :menuitem:`CONFIG_FREERTOS_IN_IRAM` will increase IRAM usage. Consider this trade-off when optimizing for SPI performance.
|
||||
|
||||
- Deprecated HSPI and VSPI related IOMUX pin macros on ESP32 and ESP32S2 have been removed.
|
||||
|
||||
@@ -373,7 +373,7 @@ Deprecated header file ``esp_spiram.h`` has been removed. Please use ``esp_psram
|
||||
SPI Flash Driver
|
||||
----------------
|
||||
|
||||
- Deprecated ``enum`` type ``esp_flash_speed_t`` has been removed. The main flash speed is controlled by :ref:`CONFIG_ESPTOOLPY_FLASHFREQ` option.
|
||||
- Deprecated ``enum`` type ``esp_flash_speed_t`` has been removed. The main flash speed is controlled by :menuitem:`CONFIG_ESPTOOLPY_FLASHFREQ` option.
|
||||
- Deprecated header file ``esp_spi_flash.h`` has been removed. Please use ``spi_flash_mmap.h`` instead.
|
||||
- Deprecated API ``spi_flash_dump_counters`` has been removed. Please use :cpp:func:`esp_flash_dump_counters` instead.
|
||||
- Deprecated API ``spi_flash_get_counters`` has been removed. Please use :cpp:func:`esp_flash_get_counters` instead.
|
||||
@@ -437,4 +437,4 @@ You can add this dependency to your project by running ``idf.py add-dependency "
|
||||
|
||||
TWAI has provided a new driver interface in version 5.5, which supports more flexible configurations and richer features. The legacy driver is not recommended to be used anymore. Please refer to the 5.5 migration guide :doc:`TWAI migration guide <../../release-5.x/5.5/peripherals>` and the new driver programming guide :doc:`TWAI driver programming guide <../../../api-reference/peripherals/twai>` for migration.
|
||||
|
||||
If you still need to use the legacy driver, you can enable the configuration option :ref:`CONFIG_TWAI_SUPPRESS_DEPRECATE_WARN` to close the deprecation warnings.
|
||||
If you still need to use the legacy driver, you can enable the configuration option :menuitem:`CONFIG_TWAI_SUPPRESS_DEPRECATE_WARN` to close the deprecation warnings.
|
||||
|
||||
@@ -150,7 +150,7 @@ Migration Options
|
||||
|
||||
**Option 1 (Recommended)** — Move connection-time logic into a dedicated post-handshake callback:
|
||||
|
||||
1. Enable :ref:`CONFIG_HTTPD_WS_POST_HANDSHAKE_CB_SUPPORT` in menuconfig.
|
||||
1. Enable :menuitem:`CONFIG_HTTPD_WS_POST_HANDSHAKE_CB_SUPPORT` in menuconfig.
|
||||
2. Register a ``ws_post_handshake_cb`` on the ``httpd_uri_t`` struct. The frame handler remains clean with no ``HTTP_GET`` check.
|
||||
|
||||
.. code-block:: c
|
||||
@@ -176,7 +176,7 @@ Migration Options
|
||||
|
||||
**Option 2 (Minimal change)** — Set ``.ws_post_handshake_cb`` to the same function as ``.handler``:
|
||||
|
||||
1. Enable :ref:`CONFIG_HTTPD_WS_POST_HANDSHAKE_CB_SUPPORT` in menuconfig.
|
||||
1. Enable :menuitem:`CONFIG_HTTPD_WS_POST_HANDSHAKE_CB_SUPPORT` in menuconfig.
|
||||
2. Set ``.ws_post_handshake_cb = ws_handler`` in the URI registration. The existing ``if (req->method == HTTP_GET)`` check inside the handler continues to work without any further code changes.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
@@ -43,12 +43,12 @@ Protocomm Security Configuration
|
||||
|
||||
The default values for protocomm security configuration options have been changed to improve security by default:
|
||||
|
||||
- :ref:`CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_0` now defaults to ``n`` (previously ``y``)
|
||||
- :ref:`CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_1` now defaults to ``n`` (previously ``y``)
|
||||
- :menuitem:`CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_0` now defaults to ``n`` (previously ``y``)
|
||||
- :menuitem:`CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_1` now defaults to ``n`` (previously ``y``)
|
||||
|
||||
Projects that rely on protocomm security versions 0 or 1 will need to explicitly enable these options in their configuration. If your application uses protocomm security version 0 (no security) or version 1 (Curve25519 + AES-CTR), you must explicitly enable the corresponding configuration option in your project's ``sdkconfig`` or through ``menuconfig``:
|
||||
|
||||
- For security version 0: Enable :ref:`CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_0`
|
||||
- For security version 1: Enable :ref:`CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_1`
|
||||
- For security version 0: Enable :menuitem:`CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_0`
|
||||
- For security version 1: Enable :menuitem:`CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_1`
|
||||
|
||||
This change was made to reduce code size by default and encourage the use of more secure protocomm implementations.
|
||||
|
||||
@@ -18,7 +18,7 @@ VFS
|
||||
- Deleted deprecated USB-Serial-JTAG-VFS functions (``esp_vfs_dev_usb_serial_jtag_*``) located in the ``vfs`` component. Please use API from USB-Serial-JTAG driver instead: ``usb_serial_jtag_vfs_*``.
|
||||
- ``esp_vfs_register_fd_range`` is now considered private and its signature was changed to match the new VFS API style. Projects that still rely on this internal helper must include ``esp_private/socket.h`` and should be aware that the API may change without notice.
|
||||
- Legacy VFS APIs (such as ``esp_vfs_register``) that operate on ``esp_vfs_t`` instead of ``esp_vfs_fs_ops_t`` are deprecated and will be removed in the next major release. Switch to the new ``esp_vfs_fs_ops_t``-based APIs.
|
||||
- TERMIOS support is now disabled by default. Re-enable :ref:`CONFIG_VFS_SUPPORT_TERMIOS` in menuconfig if your application calls POSIX ``termios`` APIs, such as ``tcsetattr``/``tcgetattr`` for UART configuration.
|
||||
- TERMIOS support is now disabled by default. Re-enable :menuitem:`CONFIG_VFS_SUPPORT_TERMIOS` in menuconfig if your application calls POSIX ``termios`` APIs, such as ``tcsetattr``/``tcgetattr`` for UART configuration.
|
||||
- Context-less VFS function pointers are deprecated. Switch to the context-aware ``*_p`` callbacks, register the VFS with ``ESP_VFS_FLAG_CONTEXT_PTR``, and pass ``NULL`` as the context pointer if the driver does not need per-instance state. This change simplifies the API surface and reduces runtime overhead in the VFS call path.
|
||||
|
||||
|
||||
@@ -30,5 +30,5 @@ The ``esp_vfs_console`` component has been renamed to ``esp_stdio``. This compon
|
||||
FATFS
|
||||
-----
|
||||
|
||||
- Dynamic buffers (:ref:`CONFIG_FATFS_USE_DYN_BUFFERS`) now default to enabled to trim static memory usage when multiple volumes are mounted; turn this off in menuconfig if you prefer static allocation.
|
||||
- Long filename support now defaults to heap-based buffers (``CONFIG_FATFS_LFN_HEAP=y``) so filenames longer than 8.3 work out of the box; you can disable it in menuconfig (:ref:`CONFIG_FATFS_LONG_FILENAMES`) if you need to conserve heap.
|
||||
- Dynamic buffers (:menuitem:`CONFIG_FATFS_USE_DYN_BUFFERS`) now default to enabled to trim static memory usage when multiple volumes are mounted; turn this off in menuconfig if you prefer static allocation.
|
||||
- Long filename support now defaults to heap-based buffers (``CONFIG_FATFS_LFN_HEAP=y``) so filenames longer than 8.3 work out of the box; you can disable it in menuconfig (:menuitem:`CONFIG_FATFS_LONG_FILENAMES`) if you need to conserve heap.
|
||||
|
||||
@@ -18,11 +18,11 @@ In most cases, no application behavior changes are expected, except for reduced
|
||||
|
||||
**Breaking change:** It is not possible to redefine stdin, stdout, and stderr for specific tasks as was possible with Newlib. These streams are global and shared between all tasks. This is POSIX-standardized behavior.
|
||||
|
||||
:ref:`CONFIG_LIBC_PICOLIBC_NEWLIB_COMPATIBILITY`, which is enabled by default, provides limited compatibility with Newlib by providing thread-local copies of ``global stdin``, ``stdout``, ``stderr``, and the ``getreent()`` implementation. If a library built with Newlib headers operates with "internal" fields of "struct reent", there may be task stack corruption. Note that manipulating ``struct reent`` fields is expected only by the Newlib library itself.
|
||||
:menuitem:`CONFIG_LIBC_PICOLIBC_NEWLIB_COMPATIBILITY`, which is enabled by default, provides limited compatibility with Newlib by providing thread-local copies of ``global stdin``, ``stdout``, ``stderr``, and the ``getreent()`` implementation. If a library built with Newlib headers operates with "internal" fields of "struct reent", there may be task stack corruption. Note that manipulating ``struct reent`` fields is expected only by the Newlib library itself.
|
||||
|
||||
If you are not linking against external libraries built against Newlib headers, you may disable :ref:`CONFIG_LIBC_PICOLIBC_NEWLIB_COMPATIBILITY` to save a small amount of memory.
|
||||
If you are not linking against external libraries built against Newlib headers, you may disable :menuitem:`CONFIG_LIBC_PICOLIBC_NEWLIB_COMPATIBILITY` to save a small amount of memory.
|
||||
|
||||
Newlib is still maintained in ESP-IDF toolchains. To switch to using it, select Newlib in menuconfig via the option LIBC_NEWLIB in :ref:`CONFIG_LIBC`.
|
||||
Newlib is still maintained in ESP-IDF toolchains. To switch to using it, select Newlib in menuconfig via the option LIBC_NEWLIB in :menuitem:`CONFIG_LIBC`.
|
||||
|
||||
Comparison of Newlib vs Picolibc
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
@@ -68,7 +68,7 @@ The test code was compiled with both Newlib and Picolibc, and the results were c
|
||||
|
||||
.. note::
|
||||
|
||||
Even when :ref:`CONFIG_LIBC_NEWLIB_NANO_FORMAT` is enabled, which disables float formatting, applications with Picolibc are still smaller by 6% (224,592 vs 239,888 bytes).
|
||||
Even when :menuitem:`CONFIG_LIBC_NEWLIB_NANO_FORMAT` is enabled, which disables float formatting, applications with Picolibc are still smaller by 6% (224,592 vs 239,888 bytes).
|
||||
|
||||
Xtensa
|
||||
------
|
||||
@@ -171,7 +171,7 @@ New code:
|
||||
Bootloader
|
||||
----------
|
||||
|
||||
Removed option for compiling bootloader with no optimization level (-O0, `CONFIG_BOOTLOADER_COMPILER_OPTIMIZATION_NONE`). On most targets it was no longer possible to compile the bootloader with -O0, as IRAM sections would overflow. For debugging purposes, it is recommended to use the -Og (:ref:`CONFIG_BOOTLOADER_COMPILER_OPTIMIZATION_DEBUG<CONFIG_BOOTLOADER_COMPILER_OPTIMIZATION_DEBUG>`) optimization level instead. This provides a good balance between optimization and debuggability.
|
||||
Removed option for compiling bootloader with no optimization level (-O0, `CONFIG_BOOTLOADER_COMPILER_OPTIMIZATION_NONE`). On most targets it was no longer possible to compile the bootloader with -O0, as IRAM sections would overflow. For debugging purposes, it is recommended to use the -Og (:menuitem:`CONFIG_BOOTLOADER_COMPILER_OPTIMIZATION_DEBUG`) optimization level instead. This provides a good balance between optimization and debuggability.
|
||||
|
||||
Time
|
||||
----
|
||||
@@ -205,7 +205,7 @@ The application tracing configuration menu has been moved. Previously located at
|
||||
|
||||
Previously, application tracing was automatically enabled when a destination was configured. Now you must explicitly enable application tracing by selecting the trace transport before configuring any destination.
|
||||
|
||||
To enable application tracing, go to ``Component config`` > ``ESP Trace Configuration`` > ``Trace transport`` and select ``ESP-IDF apptrace`` in menuconfig. After that, configuration can be done at ``Component config`` > ``ESP Trace Configuration`` > ``Application Level Tracing``.
|
||||
To enable application tracing, set :menuitem:`CONFIG_ESP_TRACE_TRANSPORT` to ``ESP-IDF apptrace``. The related application-level tracing options will then become available.
|
||||
|
||||
If apptrace will be used without a library (for example when SEGGER SystemView is disabled) in standalone mode, the following configurations need to be set in your sdkconfig file:
|
||||
|
||||
@@ -238,7 +238,7 @@ API Changes
|
||||
|
||||
The destination parameter has been removed from all apptrace APIs.
|
||||
|
||||
Default destination is now configured in menuconfig under ``Component config`` > ``ESP Trace Configuration`` > ``Application Level Tracing`` and can be altered at runtime by providing callback with custom tracing configuration.
|
||||
The default destination is now configured with :menuitem:`CONFIG_APPTRACE_DESTINATION` and can be altered at runtime by providing a callback with custom tracing configuration.
|
||||
|
||||
The UART destination configuration has been simplified:
|
||||
|
||||
@@ -279,9 +279,9 @@ Add the dependency in your component manifest:
|
||||
dependencies:
|
||||
espressif/esp_sysview: ^1
|
||||
|
||||
Then, in menuconfig, select: ``Component config`` > ``ESP Trace Configuration`` > ``Trace library`` > ``External library from component registry``.
|
||||
Then enable :menuitem:`CONFIG_ESP_TRACE_LIB_EXTERNAL`.
|
||||
|
||||
After that, the SystemView configuration can be shown by selecting ``Component config`` > ``SEGGER SystemView Configuration``.
|
||||
After that, the SystemView configuration options become available.
|
||||
|
||||
The SystemView no longer has its own separate destination configuration. It shares the configuration with the application tracing transport (JTAG or UART).
|
||||
|
||||
@@ -319,7 +319,7 @@ For safe use while the scheduler is running, use ``vTaskSuspendAll()`` before ca
|
||||
Memory Placement
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
- To reduce IRAM usage, the default placement for most FreeRTOS functions has been changed from IRAM to flash. Consequently, the ``CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH`` option has been removed. This change saves a significant amount of IRAM but may have a slight performance impact. For performance-critical applications, you can restore the previous behavior by enabling the new :ref:`CONFIG_FREERTOS_IN_IRAM` option.
|
||||
- To reduce IRAM usage, the default placement for most FreeRTOS functions has been changed from IRAM to flash. Consequently, the ``CONFIG_FREERTOS_PLACE_FUNCTIONS_INTO_FLASH`` option has been removed. This change saves a significant amount of IRAM but may have a slight performance impact. For performance-critical applications, you can restore the previous behavior by enabling the new :menuitem:`CONFIG_FREERTOS_IN_IRAM` option.
|
||||
- Before enabling ``CONFIG_FREERTOS_IN_IRAM``, it is recommended to run performance tests to measure the actual impact on your specific use case. The performance difference between flash and IRAM configurations depends on factors such as flash cache efficiency, API usage patterns, and system load.
|
||||
- A baseline performance test is provided in ``components/freertos/test_apps/freertos/performance/test_freertos_api_performance.c``. This test measures the execution time of commonly used FreeRTOS APIs and can help you evaluate the effect of memory placement for your target hardware and application requirements.
|
||||
- Task snapshot functions are automatically placed in IRAM when ``CONFIG_ESP_PANIC_HANDLER_IRAM`` is enabled, ensuring they remain accessible during panic handling.
|
||||
@@ -339,7 +339,7 @@ Ring Buffer
|
||||
Memory Placement
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
To reduce IRAM usage, the default placement for `esp_ringbuf` functions has been changed from IRAM to Flash. Consequently, the ``CONFIG_RINGBUF_PLACE_FUNCTIONS_INTO_FLASH`` option has been removed. This change saves a significant amount of IRAM but may have a slight performance impact. For performance-critical applications, the previous behavior can be restored by enabling the new :ref:`CONFIG_RINGBUF_IN_IRAM` option.
|
||||
To reduce IRAM usage, the default placement for `esp_ringbuf` functions has been changed from IRAM to Flash. Consequently, the ``CONFIG_RINGBUF_PLACE_FUNCTIONS_INTO_FLASH`` option has been removed. This change saves a significant amount of IRAM but may have a slight performance impact. For performance-critical applications, the previous behavior can be restored by enabling the new :menuitem:`CONFIG_RINGBUF_IN_IRAM` option.
|
||||
|
||||
Log
|
||||
---
|
||||
@@ -376,7 +376,7 @@ OTA Updates
|
||||
|
||||
The partial download functionality in ESP HTTPS OTA has been moved under a configuration option in order to reduce the memory footprint if partial download is not used.
|
||||
|
||||
To use partial download features in your OTA applications, you need to enable the component-level configuration :ref:`CONFIG_ESP_HTTPS_OTA_ENABLE_PARTIAL_DOWNLOAD` in menuconfig (``Component config`` > ``ESP HTTPS OTA`` > ``Enable partial HTTP download for OTA``).
|
||||
To use partial download features in your OTA applications, enable :menuitem:`CONFIG_ESP_HTTPS_OTA_ENABLE_PARTIAL_DOWNLOAD`.
|
||||
|
||||
Removed Deprecated APIs
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
@@ -423,12 +423,12 @@ System Console (STDIO)
|
||||
LibC
|
||||
------
|
||||
|
||||
:ref:`CONFIG_COMPILER_ASSERT_NDEBUG_EVALUATE` default value is changed to `n`. This means asserts will no longer evaluate the expression inside the assert when ``NDEBUG`` is set. This reverts the default behavior to be in line with the C standard.
|
||||
:menuitem:`CONFIG_COMPILER_ASSERT_NDEBUG_EVALUATE` default value is changed to `n`. This means asserts will no longer evaluate the expression inside the assert when ``NDEBUG`` is set. This reverts the default behavior to be in line with the C standard.
|
||||
|
||||
ULP
|
||||
---
|
||||
|
||||
The LP-Core will now wake up the main CPU when it encounters an exception during deep sleep. This feature is enabled by default but can be disabled via the :ref:`CONFIG_ULP_TRAP_WAKEUP` Kconfig option is this behavior is not desired.
|
||||
The LP-Core will now wake up the main CPU when it encounters an exception during deep sleep. This feature is enabled by default but can be disabled via the :menuitem:`CONFIG_ULP_TRAP_WAKEUP` Kconfig option is this behavior is not desired.
|
||||
|
||||
Heap
|
||||
----
|
||||
|
||||
@@ -13,7 +13,7 @@ Warnings
|
||||
|
||||
The upgrade to GCC 15.1.0 has resulted in the addition of new warnings, or enhancements to existing warnings. The full details of all GCC warnings can be found in `GCC Warning Options <https://gcc.gnu.org/onlinedocs/gcc-15.1.0/gcc/Warning-Options.html>`_. Users are advised to double-check their code, then fix the warnings if possible. Unfortunately, depending on the warning and the complexity of the user's code, some warnings will be false positives that require non-trivial fixes. In such cases, users can choose to suppress the warning in multiple ways. This section outlines some common warnings that users are likely to encounter and ways to fix them.
|
||||
|
||||
To suprress all new warnings, enable :ref:`CONFIG_COMPILER_DISABLE_GCC15_WARNINGS` config option.
|
||||
To suprress all new warnings, enable :menuitem:`CONFIG_COMPILER_DISABLE_GCC15_WARNINGS` config option.
|
||||
|
||||
``-Wno-unterminated-string-initialization``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
@@ -129,7 +129,7 @@ To resolve this issue, the correct header must be included. Refactor the code li
|
||||
Picolibc
|
||||
--------
|
||||
|
||||
When building with :ref:`CONFIG_LIBC_PICOLIBC<CONFIG_LIBC_PICOLIBC>` enabled, the following adaptation is required.
|
||||
When building with :menuitem:`CONFIG_LIBC_PICOLIBC` enabled, the following adaptation is required.
|
||||
|
||||
``sys/signal.h header removed``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
@@ -148,7 +148,7 @@ The header ``<sys/signal.h>`` is no longer available in Picolibc. To ensure comp
|
||||
|
||||
Espressif RISC-V chips can perform misaligned memory accesses with only a small performance penalty compared to aligned accesses.
|
||||
|
||||
Previously, LibC functions that operate on memory (such as copy or comparison functions) were implemented using byte-by-byte operations when a non-word-aligned pointer was passed. Now, these functions use word (4-byte) load/store operations whenever possible, resulting in a significant performance increase. These optimized implementations are enabled by default via :ref:`CONFIG_LIBC_OPTIMIZED_MISALIGNED_ACCESS`, which reduces the application's memory budget (IRAM) by approximately 800–1000 bytes.
|
||||
Previously, LibC functions that operate on memory (such as copy or comparison functions) were implemented using byte-by-byte operations when a non-word-aligned pointer was passed. Now, these functions use word (4-byte) load/store operations whenever possible, resulting in a significant performance increase. These optimized implementations are enabled by default via :menuitem:`CONFIG_LIBC_OPTIMIZED_MISALIGNED_ACCESS`, which reduces the application's memory budget (IRAM) by approximately 800–1000 bytes.
|
||||
|
||||
The table below shows benchmark results on the ESP32-C3 chip using 4096-byte buffers:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user