Mirrors/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2026-09-22 13:01:16 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs(kconfig): update kconfig ref links to use menuitem

Browse Source
This commit is contained in:
Marius Vikhammer
2026-08-06 13:06:20 +02:00
parent c6e80a336a
commit 4d332f710e
304 changed files with 2362 additions and 2372 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/en/COPYRIGHT.rst
View File

@@ -19,7 +19,7 @@ Firmware Components
These third party libraries can be included into the application (firmware) produced by ESP-IDF.
* :component:`Newlib <esp_libc>` is licensed under the BSD License, with copyright held by the respective parties, as described in :component_file:`COPYING.NEWLIB <esp_libc/COPYING.NEWLIB>`. If :ref:`CONFIG_LIBC_PICOLIBC<CONFIG_LIBC_PICOLIBC>` is enabled, see also :component_file:`COPYING.picolibc <esp_libc/COPYING.picolibc>`.
* :component:`Newlib <esp_libc>` is licensed under the BSD License, with copyright held by the respective parties, as described in :component_file:`COPYING.NEWLIB <esp_libc/COPYING.NEWLIB>`. If :menuitem:`CONFIG_LIBC_PICOLIBC` is enabled, see also :component_file:`COPYING.picolibc <esp_libc/COPYING.picolibc>`.
:component:`Picolibc <esp_libc>` is licensed under the BSD License, with copyright held by the respective parties, as described in :component_file:`COPYING.picolibc <esp_libc/COPYING.NEWLIB>`.

8
docs/en/api-guides/RF_calibration.rst
View File

@@ -14,7 +14,7 @@ RF Calibration
Partial Calibration
-------------------
During RF initialization, the partial calibration method is used by default for RF calibration. It is done based on the full calibration data which is stored in the NVS. To use this method, please go to ``menuconfig`` and enable :ref:`CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE`.
During RF initialization, the partial calibration method is used by default for RF calibration. It is done based on the full calibration data which is stored in the NVS. To use this method, please go to ``menuconfig`` and enable :menuitem:`CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE`.
Full Calibration
----------------
@@ -31,7 +31,7 @@ Full calibration is triggered in the following conditions:
5. The RF calibration data loaded from the NVS partition is broken.
Full calibration takes 100 ms longer than the partial calibration method. If boot duration is not of critical importance to the application, the full calibration method is recommended. To switch to the full calibration method, go to ``menuconfig`` and disable :ref:`CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE`. If you use the default method of RF calibration, there are two ways to add the function of triggering full calibration as a last-resort remedy.
Full calibration takes 100 ms longer than the partial calibration method. If boot duration is not of critical importance to the application, the full calibration method is recommended. To switch to the full calibration method, go to ``menuconfig`` and disable :menuitem:`CONFIG_ESP_PHY_CALIBRATION_AND_DATA_STORAGE`. If you use the default method of RF calibration, there are two ways to add the function of triggering full calibration as a last-resort remedy.
1. Erase the NVS partition if you do not mind all of the data stored in the NVS partition is erased. That is indeed the easiest way.
@@ -47,9 +47,9 @@ PHY Initialization Data
The PHY initialization data is used for RF calibration. There are two ways to get the PHY initialization data.
One is to use the default initialization data which is located in the header file :idf_file:`components/esp_phy/{IDF_TARGET_PATH_NAME}/include/phy_init_data.h`. It is embedded into the application binary after compiling and then stored into read-only memory (DROM). To use the default initialization data, please go to ``menuconfig`` and disable :ref:`CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION`.
One is to use the default initialization data which is located in the header file :idf_file:`components/esp_phy/{IDF_TARGET_PATH_NAME}/include/phy_init_data.h`. It is embedded into the application binary after compiling and then stored into read-only memory (DROM). To use the default initialization data, please go to ``menuconfig`` and disable :menuitem:`CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION`.
An alternative is to store the initialization data in a PHY data partition. A PHY data partition is included in the default partition table. However, when using a custom partition table, please ensure that a PHY data partition (type: ``data``, subtype: ``phy``) is included in the custom partition table. Whether you are using a custom partition table or the default partition table, if initialization data is stored in a partition, it has to be flashed there, otherwise a runtime error occurs. If you want to use initialization data stored in a partition, go to ``menuconfig`` and enable the option :ref:`CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION`.
An alternative is to store the initialization data in a PHY data partition. A PHY data partition is included in the default partition table. However, when using a custom partition table, please ensure that a PHY data partition (type: ``data``, subtype: ``phy``) is included in the custom partition table. Whether you are using a custom partition table or the default partition table, if initialization data is stored in a partition, it has to be flashed there, otherwise a runtime error occurs. If you want to use initialization data stored in a partition, go to ``menuconfig`` and enable the option :menuitem:`CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION`.
API Reference
-------------

10
docs/en/api-guides/ble/ble-multiconnection-guide.rst
View File

@@ -31,13 +31,13 @@ Controller SDKconfig
.. only:: esp32
- :ref:`BTDM_CTRL_BLE_MAX_CONN <CONFIG_BTDM_CTRL_BLE_MAX_CONN>`
- :menuitem:`BTDM_CTRL_BLE_MAX_CONN <CONFIG_BTDM_CTRL_BLE_MAX_CONN>`
The configuration option **BTDM_CTRL_BLE_MAX_CONN** specifies the maximum number of Bluetooth LE connections that the controller can support concurrently. This value must match the maximum number of connections configured on the Host side, as defined in the table above.
.. only:: esp32c3 or esp32s3
- :ref:`BT_CTRL_BLE_MAX_ACT <CONFIG_BT_CTRL_BLE_MAX_ACT>`
- :menuitem:`BT_CTRL_BLE_MAX_ACT <CONFIG_BT_CTRL_BLE_MAX_ACT>`
The configuration option **BT_CTRL_BLE_MAX_ACT** defines the maximum number of Bluetooth LE activities that the controller can handle simultaneously. Each Bluetooth LE activity consumes one resource, including:
@@ -70,10 +70,10 @@ Note
4. If your application requires more simultaneous connections than the values listed above, please contact our `customer support team <https://www.espressif.com/en/contact-us/sales-questions>`__ for further assistance.
.. |bluedroid_enable_config| replace:: :ref:`BT_MULTI_CONNECTION_ENBALE <CONFIG_BT_MULTI_CONNECTION_ENBALE>`
.. |bluedroid_connection_num| replace:: :ref:`BT_ACL_CONNECTIONS <CONFIG_BT_ACL_CONNECTIONS>`
.. |bluedroid_enable_config| replace:: :menuitem:`BT_MULTI_CONNECTION_ENBALE <CONFIG_BT_MULTI_CONNECTION_ENBALE>`
.. |bluedroid_connection_num| replace:: :menuitem:`BT_ACL_CONNECTIONS <CONFIG_BT_ACL_CONNECTIONS>`
.. |bluedroid_example| replace:: :example:`multi_conn <bluetooth/bluedroid/ble/ble_multi_conn>`
.. |nimble_connection_num| replace:: :ref:`BT_NIMBLE_MAX_CONNECTIONS <CONFIG_BT_NIMBLE_MAX_CONNECTIONS>`
.. |nimble_connection_num| replace:: :menuitem:`BT_NIMBLE_MAX_CONNECTIONS <CONFIG_BT_NIMBLE_MAX_CONNECTIONS>`
.. |nimble_example| replace:: :example:`multi_conn<bluetooth/nimble/ble_multi_conn>`
.. only:: esp32 or esp32c3 or esp32s3

2
docs/en/api-guides/ble/bluedroid-dual-identity-host-dev.rst
View File

@@ -8,7 +8,7 @@ Introduction
When a single peer phone connects to an ESP32 peripheral through two different **local identities** (for example, a Public address and a fixed Static Random address from two extended advertising sets), the default Bluedroid Host treats both links as the same peer. Bonds, LTK, and NVS sections can overwrite each other.
Enable :ref:`BT_BLE_PERIPH_PSEUDO_ADDR_BOND <CONFIG_BT_BLE_PERIPH_PSEUDO_ADDR_BOND>` to derive a Host-internal **pseudo address** ``f(local_identity, peer)`` per link. The application sees two different ``remote_bda`` values for the same phone, while SMP and the controller still use the real peer identity on air.
Enable :menuitem:`BT_BLE_PERIPH_PSEUDO_ADDR_BOND <CONFIG_BT_BLE_PERIPH_PSEUDO_ADDR_BOND>` to derive a Host-internal **pseudo address** ``f(local_identity, peer)`` per link. The application sees two different ``remote_bda`` values for the same phone, while SMP and the controller still use the real peer identity on air.
Example
-------

54
docs/en/api-guides/bootloader.rst
View File

@@ -32,23 +32,23 @@ The bootloader does not support booting apps from older versions of ESP-IDF. Whe
Before ESP-IDF V2.1
^^^^^^^^^^^^^^^^^^^
Bootloaders built from very old versions of ESP-IDF (before ESP-IDF V2.1) perform less hardware configuration than newer versions. When using a bootloader from these early ESP-IDF versions and building a new app, enable the config option :ref:`CONFIG_APP_COMPATIBLE_PRE_V2_1_BOOTLOADERS`.
Bootloaders built from very old versions of ESP-IDF (before ESP-IDF V2.1) perform less hardware configuration than newer versions. When using a bootloader from these early ESP-IDF versions and building a new app, enable the config option :menuitem:`CONFIG_APP_COMPATIBLE_PRE_V2_1_BOOTLOADERS`.
Before ESP-IDF V3.1
^^^^^^^^^^^^^^^^^^^
Bootloaders built from versions of ESP-IDF before V3.1 do not support MD5 checksums in the partition table binary. When using a bootloader from these ESP-IDF versions and building a new app, enable the config option :ref:`CONFIG_APP_COMPATIBLE_PRE_V3_1_BOOTLOADERS`.
Bootloaders built from versions of ESP-IDF before V3.1 do not support MD5 checksums in the partition table binary. When using a bootloader from these ESP-IDF versions and building a new app, enable the config option :menuitem:`CONFIG_APP_COMPATIBLE_PRE_V3_1_BOOTLOADERS`.
Before ESP-IDF V5.1
^^^^^^^^^^^^^^^^^^^
Bootloaders built from versions of ESP-IDF prior to V5.1 do not support :ref:`CONFIG_ESP_SYSTEM_ESP32_SRAM1_REGION_AS_IRAM`. When using a bootloader from these ESP-IDF versions and building a new app, you should not use this option.
Bootloaders built from versions of ESP-IDF prior to V5.1 do not support :menuitem:`CONFIG_ESP_SYSTEM_ESP32_SRAM1_REGION_AS_IRAM`. When using a bootloader from these ESP-IDF versions and building a new app, you should not use this option.
SPI Flash Configuration
^^^^^^^^^^^^^^^^^^^^^^^
Each ESP-IDF application or bootloader .bin file contains a header with :ref:`CONFIG_ESPTOOLPY_FLASHMODE`, :ref:`CONFIG_ESPTOOLPY_FLASHFREQ`, :ref:`CONFIG_ESPTOOLPY_FLASHSIZE` embedded in it. These are used to configure the SPI flash during boot.
Each ESP-IDF application or bootloader .bin file contains a header with :menuitem:`CONFIG_ESPTOOLPY_FLASHMODE`, :menuitem:`CONFIG_ESPTOOLPY_FLASHFREQ`, :menuitem:`CONFIG_ESPTOOLPY_FLASHSIZE` embedded in it. These are used to configure the SPI flash during boot.
The :ref:`first-stage-bootloader` reads the :ref:`second-stage-bootloader` header information from flash and uses this information to load the rest of the :ref:`second-stage-bootloader` from flash. However, at this time the system clock speed is lower than configured and not all flash modes are supported. When the :ref:`second-stage-bootloader` then runs, it will reconfigure the flash using values read from the currently selected app binary's header (and NOT from the :ref:`second-stage-bootloader` header). This allows an OTA update to change the SPI flash settings in use.
@@ -59,7 +59,7 @@ The :ref:`first-stage-bootloader` reads the :ref:`second-stage-bootloader` heade
Log Level
---------
The default bootloader log level is "Info". By setting the :ref:`CONFIG_BOOTLOADER_LOG_LEVEL` option, it is possible to increase or decrease this level. This log level is separate from the log level used in the app (see :doc:`/api-reference/system/log`).
The default bootloader log level is "Info". By setting the :menuitem:`CONFIG_BOOTLOADER_LOG_LEVEL` option, it is possible to increase or decrease this level. This log level is separate from the log level used in the app (see :doc:`/api-reference/system/log`).
Reducing bootloader log verbosity can improve the overall project boot time by a small amount.
@@ -68,27 +68,27 @@ Factory Reset
Sometimes it is desirable to have a way for the device to fall back to a known-good state, in case of some problem with an update.
To roll back to the original "factory" device configuration and clear any user settings, configure the config item :ref:`CONFIG_BOOTLOADER_FACTORY_RESET` in the bootloader.
To roll back to the original "factory" device configuration and clear any user settings, configure the config item :menuitem:`CONFIG_BOOTLOADER_FACTORY_RESET` in the bootloader.
The factory reset mechanism allows the device to be factory reset in two ways:
- Clear one or more data partitions. The :ref:`CONFIG_BOOTLOADER_DATA_FACTORY_RESET` option allows users to specify which data partitions will be erased when the factory reset is executed.
- Clear one or more data partitions. The :menuitem:`CONFIG_BOOTLOADER_DATA_FACTORY_RESET` option allows users to specify which data partitions will be erased when the factory reset is executed.
Users can specify the names of partitions as a comma-delimited list with optional spaces for readability. (Like this: ``nvs, phy_init, nvs_custom``).
Make sure that the names of partitions specified in the option are the same as those found in the partition table. Partitions of type "app" cannot be specified here.
- Boot from "factory" app partition. Enabling the :ref:`CONFIG_BOOTLOADER_OTA_DATA_ERASE` option will cause the device to boot from the default "factory" app partition after a factory reset (or if there is no factory app partition in the partition table then the default ota app partition is selected instead). This reset process involves erasing the OTA data partition which holds the currently selected OTA partition slot. The "factory" app partition slot (if it exists) is never updated via OTA, so resetting to this allows reverting to a "known good" firmware application.
- Boot from "factory" app partition. Enabling the :menuitem:`CONFIG_BOOTLOADER_OTA_DATA_ERASE` option will cause the device to boot from the default "factory" app partition after a factory reset (or if there is no factory app partition in the partition table then the default ota app partition is selected instead). This reset process involves erasing the OTA data partition which holds the currently selected OTA partition slot. The "factory" app partition slot (if it exists) is never updated via OTA, so resetting to this allows reverting to a "known good" firmware application.
Either or both of these configuration options can be enabled independently.
In addition, the following configuration options control the reset condition:
- :ref:`CONFIG_BOOTLOADER_NUM_PIN_FACTORY_RESET`- The input GPIO number used to trigger a factory reset. This GPIO must be pulled low or high (configurable) on reset to trigger this.
- :menuitem:`CONFIG_BOOTLOADER_NUM_PIN_FACTORY_RESET`- The input GPIO number used to trigger a factory reset. This GPIO must be pulled low or high (configurable) on reset to trigger this.
- :ref:`CONFIG_BOOTLOADER_HOLD_TIME_GPIO`- this is hold time of GPIO for reset/test mode (by default 5 seconds). The GPIO must be held continuously for this period of time after reset before a factory reset or test partition boot (as applicable) is performed.
- :menuitem:`CONFIG_BOOTLOADER_HOLD_TIME_GPIO`- this is hold time of GPIO for reset/test mode (by default 5 seconds). The GPIO must be held continuously for this period of time after reset before a factory reset or test partition boot (as applicable) is performed.
- :ref:`CONFIG_BOOTLOADER_FACTORY_RESET_PIN_LEVEL` - configure whether a factory reset should trigger on a high or low level of the GPIO. If the GPIO has an internal pullup then this is enabled before the pin is sampled, consult the {IDF_TARGET_NAME} datasheet for details on pin internal pullups.
- :menuitem:`CONFIG_BOOTLOADER_FACTORY_RESET_PIN_LEVEL` - configure whether a factory reset should trigger on a high or low level of the GPIO. If the GPIO has an internal pullup then this is enabled before the pin is sampled, consult the {IDF_TARGET_NAME} datasheet for details on pin internal pullups.
.. only:: SOC_RTC_FAST_MEM_SUPPORTED
@@ -97,11 +97,11 @@ In addition, the following configuration options control the reset condition:
- If the status is read as true, the function will return the status, indicating that the factory reset has occurred. The function then resets the status to false for subsequent factory reset judgement.
- If the status is read as false, the function will return the status, indicating that the factory reset has not occurred, or the memory where this status is stored is invalid.
Note that this feature reserves some RTC FAST memory (the same size as the :ref:`CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP` feature).
Note that this feature reserves some RTC FAST memory (the same size as the :menuitem:`CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP` feature).
.. only:: not SOC_RTC_FAST_MEM_SUPPORTED
Sometimes an application needs to know if the factory reset has occurred. The {IDF_TARGET_NAME} chip does not have RTC FAST memory, so there is no API to detect it. Instead, there is a workaround: you need an NVS partition that will be erased by the bootloader if factory reset occurs (add this partition to :ref:`CONFIG_BOOTLOADER_DATA_FACTORY_RESET`). In this NVS partition, create a "factory_reset_state" token that will be increased in the application. If the "factory_reset_state" is 0 then the factory reset has occurred.
Sometimes an application needs to know if the factory reset has occurred. The {IDF_TARGET_NAME} chip does not have RTC FAST memory, so there is no API to detect it. Instead, there is a workaround: you need an NVS partition that will be erased by the bootloader if factory reset occurs (add this partition to :menuitem:`CONFIG_BOOTLOADER_DATA_FACTORY_RESET`). In this NVS partition, create a "factory_reset_state" token that will be increased in the application. If the "factory_reset_state" is 0 then the factory reset has occurred.
.. _bootloader_boot_from_test_firmware:
@@ -112,15 +112,15 @@ It is possible to write a special firmware app for testing in production, and bo
Implementing a dedicated test app firmware requires creating a totally separate ESP-IDF project for the test app (each project in ESP-IDF only builds one app). The test app can be developed and tested independently of the main project, and then integrated at production testing time as a pre-compiled .bin file which is flashed to the address of the main project's test app partition.
To support this functionality in the main project's bootloader, set the configuration item :ref:`CONFIG_BOOTLOADER_APP_TEST` and configure the following three items:
To support this functionality in the main project's bootloader, set the configuration item :menuitem:`CONFIG_BOOTLOADER_APP_TEST` and configure the following three items:
- :ref:`CONFIG_BOOTLOADER_NUM_PIN_APP_TEST` - GPIO number to boot test partition. The selected GPIO will be configured as an input with internal pull-up enabled. This GPIO must be pulled low or high (configurable) on reset to trigger this.
- :menuitem:`CONFIG_BOOTLOADER_NUM_PIN_APP_TEST` - GPIO number to boot test partition. The selected GPIO will be configured as an input with internal pull-up enabled. This GPIO must be pulled low or high (configurable) on reset to trigger this.
Once the GPIO input is released and the device has been rebooted, the default boot sequence will be enabled again to boot the factory partition or any OTA app partition slot.
- :ref:`CONFIG_BOOTLOADER_HOLD_TIME_GPIO` - this is the hold time of GPIO for reset/test mode (by default 5 seconds). The GPIO must be held continuously for this period of time after reset before a factory reset or test partition boot (as applicable) is performed.
- :menuitem:`CONFIG_BOOTLOADER_HOLD_TIME_GPIO` - this is the hold time of GPIO for reset/test mode (by default 5 seconds). The GPIO must be held continuously for this period of time after reset before a factory reset or test partition boot (as applicable) is performed.
- :ref:`CONFIG_BOOTLOADER_APP_TEST_PIN_LEVEL` - configure whether a test partition boot should trigger on a high or low level of the GPIO. If the GPIO has an internal pull-up, then this is enabled before the pin is sampled. Consult the {IDF_TARGET_NAME} datasheet for details on pin internal pull-ups.
- :menuitem:`CONFIG_BOOTLOADER_APP_TEST_PIN_LEVEL` - configure whether a test partition boot should trigger on a high or low level of the GPIO. If the GPIO has an internal pull-up, then this is enabled before the pin is sampled. Consult the {IDF_TARGET_NAME} datasheet for details on pin internal pull-ups.
Rollback
--------
@@ -134,10 +134,10 @@ Consult the :ref:`app_rollback` and :ref:`anti-rollback` sections in the :doc:`O
Watchdog
--------
The chips come equipped with two groups of watchdog timers: Main System Watchdog Timer (MWDT_WDT) and RTC Watchdog Timer (RTC_WDT). Both watchdog timer groups are enabled when the chip is powered up. However, in the bootloader, they will both be disabled. If :ref:`CONFIG_BOOTLOADER_WDT_ENABLE` is set (which is the default behavior), RTC_WDT is re-enabled. It tracks the time from the bootloader is enabled until the user's main function is called. In this scenario, RTC_WDT remains operational and will automatically reset the chip if no application successfully starts within 9 seconds. This functionality is particularly useful in preventing lockups caused by an unstable power source during startup.
The chips come equipped with two groups of watchdog timers: Main System Watchdog Timer (MWDT_WDT) and RTC Watchdog Timer (RTC_WDT). Both watchdog timer groups are enabled when the chip is powered up. However, in the bootloader, they will both be disabled. If :menuitem:`CONFIG_BOOTLOADER_WDT_ENABLE` is set (which is the default behavior), RTC_WDT is re-enabled. It tracks the time from the bootloader is enabled until the user's main function is called. In this scenario, RTC_WDT remains operational and will automatically reset the chip if no application successfully starts within 9 seconds. This functionality is particularly useful in preventing lockups caused by an unstable power source during startup.
- The timeout period can be adjusted by setting :ref:`CONFIG_BOOTLOADER_WDT_TIME_MS` and recompiling the bootloader.
- The RTC Watchdog can be disabled in the bootloader by disabling the :ref:`CONFIG_BOOTLOADER_WDT_ENABLE` setting and recompiling the bootloader. This is not recommended.
- The timeout period can be adjusted by setting :menuitem:`CONFIG_BOOTLOADER_WDT_TIME_MS` and recompiling the bootloader.
- The RTC Watchdog can be disabled in the bootloader by disabling the :menuitem:`CONFIG_BOOTLOADER_WDT_ENABLE` setting and recompiling the bootloader. This is not recommended.
- See :ref:`app-hardware-watchdog-timers` to learn how RTC_WDT is used in the application.
.. _bootloader-size:
@@ -152,24 +152,24 @@ Bootloader Size
0x0 at start of flash + IDF_TARGET_MAX_BOOTLOADER_SIZE + 0x1000 signature sector // for esp32s2, esp32s3, esp32c2, esp32c3, esp32c6, esp32c61, esp32h2, esp32h21
0x2000 at start of flash + IDF_TARGET_MAX_BOOTLOADER_SIZE + 0x1000 signature sector // for Key Manager supported targets: esp32c5, esp32h4, esp32p4, esp32s31
When enabling additional bootloader functions, including :doc:`/security/flash-encryption` or Secure Boot, and especially if setting a high :ref:`CONFIG_BOOTLOADER_LOG_LEVEL` level, then it is important to monitor the bootloader .bin file's size.
When enabling additional bootloader functions, including :doc:`/security/flash-encryption` or Secure Boot, and especially if setting a high :menuitem:`CONFIG_BOOTLOADER_LOG_LEVEL` level, then it is important to monitor the bootloader .bin file's size.
When using the default :ref:`CONFIG_PARTITION_TABLE_OFFSET` value 0x8000, the size limit is {IDF_TARGET_CONFIG_PARTITION_TABLE_OFFSET} bytes.
When using the default :menuitem:`CONFIG_PARTITION_TABLE_OFFSET` value 0x8000, the size limit is {IDF_TARGET_CONFIG_PARTITION_TABLE_OFFSET} bytes.
If the bootloader binary is too large, then the bootloader build will fail with an error "Bootloader binary size [..] is too large for partition table offset". If the bootloader binary is flashed anyhow then the {IDF_TARGET_NAME} will fail to boot - errors will be logged about either invalid partition table or invalid bootloader checksum.
Options to work around this are:
- Set :ref:`bootloader compiler optimization <CONFIG_BOOTLOADER_COMPILER_OPTIMIZATION>` back to "Size" if it has been changed from this default value.
- Reduce :ref:`bootloader log level <CONFIG_BOOTLOADER_LOG_LEVEL>`. Setting log level to Warning, Error or None all significantly reduce the final binary size (but may make it harder to debug).
- Set :ref:`CONFIG_PARTITION_TABLE_OFFSET` to a higher value than 0x8000, to place the partition table later in the flash. This increases the space available for the bootloader. If the :doc:`partition table </api-guides/partition-tables>` CSV file contains explicit partition offsets, they will need changing so no partition has an offset lower than ``CONFIG_PARTITION_TABLE_OFFSET + 0x1000``. (This includes the default partition CSV files supplied with ESP-IDF.)
- Set :menuitem:`bootloader compiler optimization <CONFIG_BOOTLOADER_COMPILER_OPTIMIZATION>` back to "Size" if it has been changed from this default value.
- Reduce :menuitem:`bootloader log level <CONFIG_BOOTLOADER_LOG_LEVEL>`. Setting log level to Warning, Error or None all significantly reduce the final binary size (but may make it harder to debug).
- Set :menuitem:`CONFIG_PARTITION_TABLE_OFFSET` to a higher value than 0x8000, to place the partition table later in the flash. This increases the space available for the bootloader. If the :doc:`partition table </api-guides/partition-tables>` CSV file contains explicit partition offsets, they will need changing so no partition has an offset lower than ``CONFIG_PARTITION_TABLE_OFFSET + 0x1000``. (This includes the default partition CSV files supplied with ESP-IDF.)
When Secure Boot V2 is enabled, there is also an absolute binary size limit of {IDF_TARGET_MAX_BOOTLOADER_SIZE} (excluding the 4 KB signature), because the bootloader is first loaded into a fixed size buffer for verification.
Fast Boot from Deep-Sleep
-------------------------
The bootloader has the :ref:`CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP` option which allows the wake-up time from Deep-sleep to be reduced (useful for reducing power consumption). This option is available when the :ref:`CONFIG_SECURE_BOOT` option is disabled or :ref:`CONFIG_SECURE_BOOT_INSECURE` is enabled along with Secure Boot. The reduction in time is achieved by ignoring image verification.
The bootloader has the :menuitem:`CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP` option which allows the wake-up time from Deep-sleep to be reduced (useful for reducing power consumption). This option is available when the :menuitem:`CONFIG_SECURE_BOOT` option is disabled or :menuitem:`CONFIG_SECURE_BOOT_INSECURE` is enabled along with Secure Boot. The reduction in time is achieved by ignoring image verification.
.. only:: SOC_RTC_FAST_MEM_SUPPORTED
@@ -191,7 +191,7 @@ In the bootloader space, you cannot use the drivers and functions from other com
* :example:`storage/nvs/nvs_bootloader`
If the bootloader grows too large then it can collide with the partition table, which is flashed at offset 0x8000 by default. Increase the :ref:`partition table offset <CONFIG_PARTITION_TABLE_OFFSET>` value to place the partition table later in the flash. This increases the space available for the bootloader.
If the bootloader grows too large then it can collide with the partition table, which is flashed at offset 0x8000 by default. Increase the :menuitem:`partition table offset <CONFIG_PARTITION_TABLE_OFFSET>` value to place the partition table later in the flash. This increases the space available for the bootloader.
.. only:: SOC_RECOVERY_BOOTLOADER_SUPPORTED

4
docs/en/api-guides/build-system.rst
View File

@@ -434,7 +434,7 @@ The following are some project/build variables that are available as build prope
- ``IDF_TARGET``: Name of the target for which the project is being built.
- ``PROJECT_VER``: Project version.
* If :ref:`CONFIG_APP_PROJECT_VER_FROM_CONFIG` option is set, the value of :ref:`CONFIG_APP_PROJECT_VER` will be used.
* If :menuitem:`CONFIG_APP_PROJECT_VER_FROM_CONFIG` option is set, the value of :menuitem:`CONFIG_APP_PROJECT_VER` will be used.
* Else, if ``PROJECT_VER`` variable is set in project CMakeLists.txt file, its value will be used.
* Else, if the ``PROJECT_DIR/version.txt`` exists, its contents will be used as ``PROJECT_VER``.
* Else, if ``VERSION`` argument is passed to the ``project()`` call in the CMakeLists.txt file as ``project(... VERSION x.y.z.w )`` then it will be used as ``PROJECT_VER``. The ``VERSION`` argument must be compliant with the `cmake standard <https://cmake.org/cmake/help/v3.22/command/project.html>`_.
@@ -1340,7 +1340,7 @@ The example in :example:`build_system/cmake/idf_as_lib` demonstrates the creatio
.. only:: esp32
.. note:: The IDF build system can only set compiler flags for source files that it builds. When an external CMakeLists.txt file is used and PSRAM is enabled, remember to add ``-mfix-esp32-psram-cache-issue`` to the C compiler arguments. See :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` for details of this flag.
.. note:: The IDF build system can only set compiler flags for source files that it builds. When an external CMakeLists.txt file is used and PSRAM is enabled, remember to add ``-mfix-esp32-psram-cache-issue`` to the C compiler arguments. See :menuitem:`CONFIG_SPIRAM_CACHE_WORKAROUND` for details of this flag.
.. _cmake_buildsystem_api:

2
docs/en/api-guides/c.rst
View File

@@ -6,7 +6,7 @@ C Support
ESP-IDF is primarily written in C and provides C APIs. ESP-IDF can use one of the following C Standard Library implementations:
- `Picolibc <https://keithp.com/picolibc/>`_ (default)
- `Newlib <https://sourceware.org/newlib/>`_ (enabled with :ref:`CONFIG_LIBC_NEWLIB<CONFIG_LIBC_NEWLIB>` Kconfig option)
- `Newlib <https://sourceware.org/newlib/>`_ (enabled with :menuitem:`CONFIG_LIBC_NEWLIB` Kconfig option)
The Picolibc version is specified in :component_file:`esp_libc/sbom_picolibc.yml` and the Newlib version in :component_file:`esp_libc/sbom_newlibc.yml`.

2
docs/en/api-guides/code-quality/static-analyzer.rst
View File

@@ -8,7 +8,7 @@ A static analyzer is a tool that checks source code for errors and vulnerabiliti
GNU Static Analyzer
-------------------
The GNU Static Analyzer is distributed with GCC (refer to `GCC documentation <https://gcc.gnu.org/onlinedocs/gcc/Static-Analyzer-Options.html>`_). It can be enabled with :ref:`CONFIG_COMPILER_STATIC_ANALYZER` to perform code checks during application builds.
The GNU Static Analyzer is distributed with GCC (refer to `GCC documentation <https://gcc.gnu.org/onlinedocs/gcc/Static-Analyzer-Options.html>`_). It can be enabled with :menuitem:`CONFIG_COMPILER_STATIC_ANALYZER` to perform code checks during application builds.
Suppressing Warnings
^^^^^^^^^^^^^^^^^^^^

42
docs/en/api-guides/coexist.rst
View File

@@ -258,34 +258,34 @@ Setting Coexistence Compile-time Options
.. list::
- After writing the coexistence program, you must check :ref:`CONFIG_ESP_COEX_SW_COEXIST_ENABLE` option through menuconfig to open coexistence configuration on software, otherwise the coexistence function mentioned above cannot be used.
:esp32: - To ensure better communication performance of Wi-Fi and Bluetooth in the case of coexistence, run the task of the Wi-Fi protocol stack, the task of the Bluetooth Controller and Host protocol stack on different CPUs. You can use :ref:`CONFIG_BTDM_CTRL_PINNED_TO_CORE_CHOICE` and :ref:`CONFIG_BT_BLUEDROID_PINNED_TO_CORE_CHOICE` (or :ref:`CONFIG_BT_NIMBLE_PINNED_TO_CORE_CHOICE`) to put the tasks of the Bluetooth controller and the host protocol stack on the same CPU, and then use :ref:`CONFIG_ESP_WIFI_TASK_CORE_ID` to place the task of the Wi-Fi protocol stack on another CPU.
:esp32s3: - To ensure better communication performance of Wi-Fi and Bluetooth in the case of coexistence, run the task of the Wi-Fi protocol stack, the task of the Bluetooth Controller and Host protocol stack on different CPUs. You can use :ref:`CONFIG_BT_CTRL_PINNED_TO_CORE_CHOICE` and :ref:`CONFIG_BT_BLUEDROID_PINNED_TO_CORE_CHOICE` (or :ref:`CONFIG_BT_NIMBLE_PINNED_TO_CORE_CHOICE` ）to put the tasks of the Bluetooth controller and the host protocol stack on the same CPU, and then use :ref:`CONFIG_ESP_WIFI_TASK_CORE_ID` to place the task of the Wi-Fi protocol stack on another CPU.
:esp32: - In the case of coexistence, BLE SCAN may be interrupted by Wi-Fi and Wi-Fi releases RF resources before the end of the current BLE scan window. In order to make BLE acquire RF resources again within the current scan window, you can check the FULL SCAN configuration option through :ref:`CONFIG_BTDM_CTRL_FULL_SCAN_SUPPORTED`.
:esp32c3 or esp32s3: - When using LE Coded PHY during a BLE connection, to avoid affecting Wi-Fi performance due to the long duration of Bluetooth packets, you can select `BT_CTRL_COEX_PHY_CODED_TX_RX_TLIM_EN` in the sub-options of :ref:`CONFIG_BT_CTRL_COEX_PHY_CODED_TX_RX_TLIM` to limit the maximum time of TX/RX.
:esp32c2 or esp32c6: - When using LE Coded PHY during a BLE connection, to avoid affecting Wi-Fi performance due to the long duration of Bluetooth packets, you can select `BT_LE_COEX_PHY_CODED_TX_RX_TLIM_EN` in the sub-options of :ref:`CONFIG_BT_LE_COEX_PHY_CODED_TX_RX_TLIM` to limit the maximum time of TX/RX.
- After writing the coexistence program, you must check :menuitem:`CONFIG_ESP_COEX_SW_COEXIST_ENABLE` option through menuconfig to open coexistence configuration on software, otherwise the coexistence function mentioned above cannot be used.
:esp32: - To ensure better communication performance of Wi-Fi and Bluetooth in the case of coexistence, run the task of the Wi-Fi protocol stack, the task of the Bluetooth Controller and Host protocol stack on different CPUs. You can use :menuitem:`CONFIG_BTDM_CTRL_PINNED_TO_CORE_CHOICE` and :menuitem:`CONFIG_BT_BLUEDROID_PINNED_TO_CORE_CHOICE` (or :menuitem:`CONFIG_BT_NIMBLE_PINNED_TO_CORE_CHOICE`) to put the tasks of the Bluetooth controller and the host protocol stack on the same CPU, and then use :menuitem:`CONFIG_ESP_WIFI_TASK_CORE_ID` to place the task of the Wi-Fi protocol stack on another CPU.
:esp32s3: - To ensure better communication performance of Wi-Fi and Bluetooth in the case of coexistence, run the task of the Wi-Fi protocol stack, the task of the Bluetooth Controller and Host protocol stack on different CPUs. You can use :menuitem:`CONFIG_BT_CTRL_PINNED_TO_CORE_CHOICE` and :menuitem:`CONFIG_BT_BLUEDROID_PINNED_TO_CORE_CHOICE` (or :menuitem:`CONFIG_BT_NIMBLE_PINNED_TO_CORE_CHOICE` ）to put the tasks of the Bluetooth controller and the host protocol stack on the same CPU, and then use :menuitem:`CONFIG_ESP_WIFI_TASK_CORE_ID` to place the task of the Wi-Fi protocol stack on another CPU.
:esp32: - In the case of coexistence, BLE SCAN may be interrupted by Wi-Fi and Wi-Fi releases RF resources before the end of the current BLE scan window. In order to make BLE acquire RF resources again within the current scan window, you can check the FULL SCAN configuration option through :menuitem:`CONFIG_BTDM_CTRL_FULL_SCAN_SUPPORTED`.
:esp32c3 or esp32s3: - When using LE Coded PHY during a BLE connection, to avoid affecting Wi-Fi performance due to the long duration of Bluetooth packets, you can select `BT_CTRL_COEX_PHY_CODED_TX_RX_TLIM_EN` in the sub-options of :menuitem:`CONFIG_BT_CTRL_COEX_PHY_CODED_TX_RX_TLIM` to limit the maximum time of TX/RX.
:esp32c2 or esp32c6: - When using LE Coded PHY during a BLE connection, to avoid affecting Wi-Fi performance due to the long duration of Bluetooth packets, you can select `BT_LE_COEX_PHY_CODED_TX_RX_TLIM_EN` in the sub-options of :menuitem:`CONFIG_BT_LE_COEX_PHY_CODED_TX_RX_TLIM` to limit the maximum time of TX/RX.
:SOC_BT_SUPPORTED or SOC_WIFI_SUPPORTED: - You can reduce the memory consumption by configuring the following options on menuconfig.
.. only:: SOC_BT_SUPPORTED
- :ref:`CONFIG_BT_BLE_DYNAMIC_ENV_MEMORY`: enable the configuration of dynamic memory for Bluetooth protocol stack.
- :menuitem:`CONFIG_BT_BLE_DYNAMIC_ENV_MEMORY`: enable the configuration of dynamic memory for Bluetooth protocol stack.
.. only:: SOC_WIFI_SUPPORTED
- :ref:`CONFIG_ESP_WIFI_STATIC_RX_BUFFER_NUM`: reduce the number of Wi-Fi static RX buffers.
- :ref:`CONFIG_ESP_WIFI_DYNAMIC_RX_BUFFER_NUM`: reduce the number of Wi-Fi dynamic RX buffers.
- :ref:`CONFIG_ESP_WIFI_TX_BUFFER`: enable the configuration of dynamic allocation TX buffers.
- :ref:`CONFIG_ESP_WIFI_DYNAMIC_TX_BUFFER_NUM`: reduce the number of Wi-Fi dynamic TX buffers.
- :ref:`CONFIG_ESP_WIFI_TX_BA_WIN`: reduce the number of Wi-Fi Block Ack TX windows.
- :ref:`CONFIG_ESP_WIFI_RX_BA_WIN`: reduce the number of Wi-Fi Block Ack RX windows.
- :ref:`CONFIG_ESP_WIFI_MGMT_SBUF_NUM`: reduce the number of Wi-Fi Management Short Buffer.
- :ref:`CONFIG_ESP_WIFI_RX_IRAM_OPT`: turning off this configuration option will reduce the IRAM memory by approximately 17 KB.
- :ref:`CONFIG_LWIP_TCP_SND_BUF_DEFAULT`: reduce the default TX buffer size for TCP sockets.
- :ref:`CONFIG_LWIP_TCP_WND_DEFAULT`: reduce the default size of the RX window for TCP sockets.
- :ref:`CONFIG_LWIP_TCP_RECVMBOX_SIZE`: reduce the size of the TCP receive mailbox. Receive mailbox buffers data within active connections and handles data flow during connections.
- :ref:`CONFIG_LWIP_TCP_ACCEPTMBOX_SIZE`: reduce the size of the TCP accept mailbox. Accept mailbox queues incoming connection requests and manages the initiation of new connections.
- :ref:`CONFIG_LWIP_UDP_RECVMBOX_SIZE`: reduce the size of the UDP receive mailbox.
- :ref:`CONFIG_LWIP_TCPIP_RECVMBOX_SIZE`: reduce the size of TCPIP task receive mailbox.
- :menuitem:`CONFIG_ESP_WIFI_STATIC_RX_BUFFER_NUM`: reduce the number of Wi-Fi static RX buffers.
- :menuitem:`CONFIG_ESP_WIFI_DYNAMIC_RX_BUFFER_NUM`: reduce the number of Wi-Fi dynamic RX buffers.
- :menuitem:`CONFIG_ESP_WIFI_TX_BUFFER`: enable the configuration of dynamic allocation TX buffers.
- :menuitem:`CONFIG_ESP_WIFI_DYNAMIC_TX_BUFFER_NUM`: reduce the number of Wi-Fi dynamic TX buffers.
- :menuitem:`CONFIG_ESP_WIFI_TX_BA_WIN`: reduce the number of Wi-Fi Block Ack TX windows.
- :menuitem:`CONFIG_ESP_WIFI_RX_BA_WIN`: reduce the number of Wi-Fi Block Ack RX windows.
- :menuitem:`CONFIG_ESP_WIFI_MGMT_SBUF_NUM`: reduce the number of Wi-Fi Management Short Buffer.
- :menuitem:`CONFIG_ESP_WIFI_RX_IRAM_OPT`: turning off this configuration option will reduce the IRAM memory by approximately 17 KB.
- :menuitem:`CONFIG_LWIP_TCP_SND_BUF_DEFAULT`: reduce the default TX buffer size for TCP sockets.
- :menuitem:`CONFIG_LWIP_TCP_WND_DEFAULT`: reduce the default size of the RX window for TCP sockets.
- :menuitem:`CONFIG_LWIP_TCP_RECVMBOX_SIZE`: reduce the size of the TCP receive mailbox. Receive mailbox buffers data within active connections and handles data flow during connections.
- :menuitem:`CONFIG_LWIP_TCP_ACCEPTMBOX_SIZE`: reduce the size of the TCP accept mailbox. Accept mailbox queues incoming connection requests and manages the initiation of new connections.
- :menuitem:`CONFIG_LWIP_UDP_RECVMBOX_SIZE`: reduce the size of the UDP receive mailbox.
- :menuitem:`CONFIG_LWIP_TCPIP_RECVMBOX_SIZE`: reduce the size of TCPIP task receive mailbox.
.. note::

18
docs/en/api-guides/core_dump.rst
View File

@@ -23,7 +23,7 @@ Configurations
Destination
^^^^^^^^^^^
The :ref:`CONFIG_ESP_COREDUMP_TO_FLASH_OR_UART` option enables or disables core dump, and selects the core dump destination if enabled. When a crash occurs, the generated core dump file can either be saved to flash, or output to a connected host over UART.
The :menuitem:`CONFIG_ESP_COREDUMP_TO_FLASH_OR_UART` option enables or disables core dump, and selects the core dump destination if enabled. When a crash occurs, the generated core dump file can either be saved to flash, or output to a connected host over UART.
Format & Size
@@ -31,7 +31,7 @@ Format & Size
Core dump files are generated in ELF format, which contains extended features and allows comprehensive information regarding erroneous tasks and crashed software to be saved. The ELF format is flexible and can be extended in future revisions to save additional information.
The :ref:`CONFIG_ESP_COREDUMP_MAX_TASKS_NUM` option configures the number of task snapshots saved by the core dump. Crashed task registers and the stack are always saved, regardless of this configuration option. Other tasks are included in order of their priority (starting with the highest-priority ready task).
The :menuitem:`CONFIG_ESP_COREDUMP_MAX_TASKS_NUM` option configures the number of task snapshots saved by the core dump. Crashed task registers and the stack are always saved, regardless of this configuration option. Other tasks are included in order of their priority (starting with the highest-priority ready task).
Data Integrity Check
^^^^^^^^^^^^^^^^^^^^
@@ -41,7 +41,7 @@ Core dump files include a SHA256 checksum that verifies the integrity of the fil
Reserved Stack Size
^^^^^^^^^^^^^^^^^^^
Core dump routines run from a separate stack due to core dump itself needing to parse and save all other task stacks. The :ref:`CONFIG_ESP_COREDUMP_STACK_SIZE` option controls the size of the core dump's stack in number of bytes.
Core dump routines run from a separate stack due to core dump itself needing to parse and save all other task stacks. The :menuitem:`CONFIG_ESP_COREDUMP_STACK_SIZE` option controls the size of the core dump's stack in number of bytes.
Setting this option to 0 bytes will cause the core dump routines to run from the ISR stack, thus saving a bit of memory. Setting the option greater than zero will cause a separate stack to be instantiated.
@@ -55,7 +55,7 @@ Setting this option to 0 bytes will cause the core dump routines to run from the
Core Dump Memory Regions
^^^^^^^^^^^^^^^^^^^^^^^^
By default, core dumps typically save CPU registers, tasks data and summary of the panic reason. When the :ref:`CONFIG_ESP_COREDUMP_CAPTURE_DRAM` option is selected, ``.bss`` and ``.data`` sections and ``heap`` data will also be part of the dump.
By default, core dumps typically save CPU registers, tasks data and summary of the panic reason. When the :menuitem:`CONFIG_ESP_COREDUMP_CAPTURE_DRAM` option is selected, ``.bss`` and ``.data`` sections and ``heap`` data will also be part of the dump.
For a better debugging experience, it is recommended to dump these sections. However, this will result in a larger coredump file. The required additional storage space may vary based on the amount of DRAM the application uses.
@@ -113,13 +113,13 @@ or
Core Dump to UART
-----------------
When the core dump file is output to UART, the output file is Base64-encoded. The :ref:`CONFIG_ESP_COREDUMP_DECODE` option allows for selecting whether the output file is automatically decoded by the ESP-IDF monitor or kept encoded for manual decoding.
When the core dump file is output to UART, the output file is Base64-encoded. The :menuitem:`CONFIG_ESP_COREDUMP_DECODE` option allows for selecting whether the output file is automatically decoded by the ESP-IDF monitor or kept encoded for manual decoding.
Automatic Decoding
^^^^^^^^^^^^^^^^^^
If :ref:`CONFIG_ESP_COREDUMP_DECODE` is set to automatically decode the UART core dump, ESP-IDF monitor will automatically decode the data, translate any function addresses to source code lines, and display it in the monitor. The output to ESP-IDF monitor would resemble the following output:
If :menuitem:`CONFIG_ESP_COREDUMP_DECODE` is set to automatically decode the UART core dump, ESP-IDF monitor will automatically decode the data, translate any function addresses to source code lines, and display it in the monitor. The output to ESP-IDF monitor would resemble the following output:
.. code-block:: none
@@ -169,12 +169,12 @@ If :ref:`CONFIG_ESP_COREDUMP_DECODE` is set to automatically decode the UART cor
===================== ESP32 CORE DUMP END =====================
===============================================================
The :ref:`CONFIG_ESP_COREDUMP_UART_DELAY` allows for an optional delay to be added before the core dump file is output to UART.
The :menuitem:`CONFIG_ESP_COREDUMP_UART_DELAY` allows for an optional delay to be added before the core dump file is output to UART.
Manual Decoding
^^^^^^^^^^^^^^^
If you set :ref:`CONFIG_ESP_COREDUMP_DECODE` to no decoding, then the raw Base64-encoded body of core dump is output to UART between the following header and footer of the UART output:
If you set :menuitem:`CONFIG_ESP_COREDUMP_DECODE` to no decoding, then the raw Base64-encoded body of core dump is output to UART between the following header and footer of the UART output:
.. code-block:: none
@@ -241,7 +241,7 @@ Supported Notations and RAM Regions
Example
^^^^^^^
1. In :ref:`project-configuration-menu`, enable :ref:`COREDUMP TO FLASH <CONFIG_ESP_COREDUMP_TO_FLASH_OR_UART>`, then save and exit.
1. In :ref:`project-configuration-menu`, enable :menuitem:`COREDUMP TO FLASH <CONFIG_ESP_COREDUMP_TO_FLASH_OR_UART>`, then save and exit.
2. In your project, create a global variable in the DRAM area, such as:

6
docs/en/api-guides/cplusplus.rst
View File

@@ -57,7 +57,7 @@ See :example:`cxx/pthread` for an example of creating threads in C++. Specifical
Exception Handling
------------------
Support for C++ Exceptions in ESP-IDF is disabled by default, but can be enabled using the :ref:`CONFIG_COMPILER_CXX_EXCEPTIONS` option.
Support for C++ Exceptions in ESP-IDF is disabled by default, but can be enabled using the :menuitem:`CONFIG_COMPILER_CXX_EXCEPTIONS` option.
If an exception is thrown, but there is no ``catch`` block, the program is terminated by the ``abort`` function, and the backtrace is printed. See :doc:`fatal-errors` for more information about backtraces.
@@ -72,7 +72,7 @@ Enabling exception handling normally increases application binary size by a few
Additionally, it may be necessary to reserve some amount of RAM for the exception emergency memory pool. Memory from this pool is used if it is not possible to allocate an exception object from the heap.
The amount of memory in the emergency pool can be set using the :ref:`CONFIG_COMPILER_CXX_EXCEPTIONS_EMG_POOL_SIZE` variable.
The amount of memory in the emergency pool can be set using the :menuitem:`CONFIG_COMPILER_CXX_EXCEPTIONS_EMG_POOL_SIZE` variable.
Some additional stack memory (around 200 bytes) is also used if and only if a C++ Exception is actually thrown, because it requires calling some functions from the top of the stack to initiate exception handling.
@@ -89,7 +89,7 @@ If an exception is thrown, the run time of the code that unwinds the stack is or
Runtime Type Information (RTTI)
-------------------------------
Support for RTTI in ESP-IDF is disabled by default, but can be enabled using :ref:`CONFIG_COMPILER_CXX_RTTI` option.
Support for RTTI in ESP-IDF is disabled by default, but can be enabled using :menuitem:`CONFIG_COMPILER_CXX_RTTI` option.
Enabling this option compiles all C++ files with RTTI support enabled, which allows using ``dynamic_cast`` conversion and ``typeid`` operator. Enabling this option typically increases the binary size by tens of kB.

6
docs/en/api-guides/deep-sleep-stub.rst
View File

@@ -88,11 +88,11 @@ The second method is preferable when writing longer code segments in RTC fast me
esp_rom_printf(fmt_str, wake_count++);
}
The RTC memory area where the data will be placed can be configured via the menuconfig option :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_RTCDATA_IN_FAST_MEM`. This option allows keeping slow memory area for ULP programs. Once it is enabled, the data marked with ``RTC_DATA_ATTR`` and ``RTC_RODATA_ATTR`` are placed in the RTC fast memory segment; otherwise, it goes to RTC slow memory (the default option). This option depends on the :ref:`CONFIG_FREERTOS_UNICORE` option because RTC fast memory can be accessed only by PRO_CPU.
The RTC memory area where the data will be placed can be configured via the menuconfig option :menuitem:`CONFIG_{IDF_TARGET_CFG_PREFIX}_RTCDATA_IN_FAST_MEM`. This option allows keeping slow memory area for ULP programs. Once it is enabled, the data marked with ``RTC_DATA_ATTR`` and ``RTC_RODATA_ATTR`` are placed in the RTC fast memory segment; otherwise, it goes to RTC slow memory (the default option). This option depends on the :menuitem:`CONFIG_FREERTOS_UNICORE` option because RTC fast memory can be accessed only by PRO_CPU.
.. only:: esp32
This option depends on the :ref:`CONFIG_FREERTOS_UNICORE` because RTC fast memory can be accessed only by PRO_CPU.
This option depends on the :menuitem:`CONFIG_FREERTOS_UNICORE` because RTC fast memory can be accessed only by PRO_CPU.
The attributes ``RTC_FAST_ATTR`` and ``RTC_SLOW_ATTR`` can be used to specify data that is forcefully placed into RTC fast memory and RTC slow memory, respectively. Any access to data marked with ``RTC_FAST_ATTR`` is allowed by PRO_CPU only.
@@ -145,7 +145,7 @@ However, any string constants used in this way must be declared as arrays and ma
The second approach is advisable when incorporating strings or more complex code segments.
You can enable the Kconfig option :ref:`CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP` to reduce wake-up time. See more information in :doc:`Fast boot from Deep-sleep <bootloader>`.
You can enable the Kconfig option :menuitem:`CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP` to reduce wake-up time. See more information in :doc:`Fast boot from Deep-sleep <bootloader>`.
All of the above functions are declared in :component_file:`esp_hw_support/include/esp_sleep.h`.

6
docs/en/api-guides/error-handling.rst
View File

@@ -43,7 +43,7 @@ For each error code defined in ESP-IDF components, :cpp:type:`esp_err_t` value c
Additionally, :cpp:func:`esp_err_to_name_r` function will attempt to interpret the error code as a `standard POSIX error code <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/errno.h.html>`_, if no matching ``ESP_ERR_`` value is found. This is done using ``strerror_r`` function. POSIX error codes (such as ``ENOENT``, ``ENOMEM``) are defined in ``errno.h`` and are typically obtained from ``errno`` variable. In ESP-IDF this variable is thread-local: multiple FreeRTOS tasks have their own copies of ``errno``. Functions which set ``errno`` only modify its value for the task they run in.
This feature is enabled by default, but can be disabled to reduce application binary size. See :ref:`CONFIG_ESP_ERR_TO_NAME_LOOKUP`. When this feature is disabled, :cpp:func:`esp_err_to_name` and :cpp:func:`esp_err_to_name_r` are still defined and can be called. In this case, :cpp:func:`esp_err_to_name` will return ``UNKNOWN ERROR``, and :cpp:func:`esp_err_to_name_r` will return ``Unknown error 0xXXXX(YYYYY)``, where ``0xXXXX`` and ``YYYYY`` are the hexadecimal and decimal representations of the error code, respectively.
This feature is enabled by default, but can be disabled to reduce application binary size. See :menuitem:`CONFIG_ESP_ERR_TO_NAME_LOOKUP`. When this feature is disabled, :cpp:func:`esp_err_to_name` and :cpp:func:`esp_err_to_name_r` are still defined and can be called. In this case, :cpp:func:`esp_err_to_name` will return ``UNKNOWN ERROR``, and :cpp:func:`esp_err_to_name_r` will return ``Unknown error 0xXXXX(YYYYY)``, where ``0xXXXX`` and ``YYYYY`` are the hexadecimal and decimal representations of the error code, respectively.
.. _esp-error-check-macro:
@@ -85,7 +85,7 @@ Error message will typically look like this:
If :doc:`ESP-IDF monitor <tools/idf-monitor>` is used, addresses in the backtrace will be converted to file names and line numbers.
- The first line mentions the error code as a hexadecimal value, and the identifier used for this error in source code. The latter depends on :ref:`CONFIG_ESP_ERR_TO_NAME_LOOKUP` option being set. Address in the program where error has occurred is printed as well.
- The first line mentions the error code as a hexadecimal value, and the identifier used for this error in source code. The latter depends on :menuitem:`CONFIG_ESP_ERR_TO_NAME_LOOKUP` option being set. Address in the program where error has occurred is printed as well.
- Subsequent lines show the location in the program where :c:macro:`ESP_ERROR_CHECK` macro was called, and the expression which was passed to the macro as an argument.
@@ -122,7 +122,7 @@ The macros are defined as follows:
- **ESP_RETURN_ON_ERROR_CLEANUP**: Return from the function after executing cleanup code if an error is detected. This macro is useful when resources need to be released before returning an error code. It evaluates an expression that returns :cpp:type:`esp_err_t`, and if the result is not :c:macro:`ESP_OK`, it executes the cleanup code provided in the variable arguments (such as freeing resources or logging) before returning the error code from the current function.
The default behavior of these macros can be adjusted: if the :ref:`CONFIG_COMPILER_OPTIMIZATION_CHECKS_SILENT` option is enabled in Kconfig, error messages will not be included in the application binary and will not be printed.
The default behavior of these macros can be adjusted: if the :menuitem:`CONFIG_COMPILER_OPTIMIZATION_CHECKS_SILENT` option is enabled in Kconfig, error messages will not be included in the application binary and will not be printed.
.. _check_macros_examples:

2
docs/en/api-guides/esp-ble-mesh/ble-mesh-architecture.rst
View File

@@ -346,7 +346,7 @@ We have provided a series of application examples for customer development, and
3. Auxiliary Routine
---------------------
Auxiliary routine refers to optional functions in the ESP-BLE-MESH protocol stack. The design of the auxiliary routine generally implement the truncation of code through :ref:`CONFIG_BLE_MESH`.
Auxiliary routine refers to optional functions in the ESP-BLE-MESH protocol stack. The design of the auxiliary routine generally implement the truncation of code through :menuitem:`CONFIG_BLE_MESH`.
3.1 Features
^^^^^^^^^^^^

4
docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst
View File

@@ -406,7 +406,7 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m
2.4 How to Achieve the Transmission of Messages Without Packet Loss?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Acknowledged message is needed if users want to transmit messages without packet loss. The default time to wait for corresponding response is set in :ref:`CONFIG_BLE_MESH_CLIENT_MSG_TIMEOUT`. If the sender waits for the response until the timer expires, the corresponding timeout event would be triggered.
Acknowledged message is needed if users want to transmit messages without packet loss. The default time to wait for corresponding response is set in :menuitem:`CONFIG_BLE_MESH_CLIENT_MSG_TIMEOUT`. If the sender waits for the response until the timer expires, the corresponding timeout event would be triggered.
.. note::
@@ -609,7 +609,7 @@ You can find meaning of errors or warnings when they appear at the bottom of ESP
5.5 What Is the Meaning of Warning ``No free slots for new incoming segmented messages``?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When the node has no space for receiving new segmented message, this warning will appear. Users can make the space larger through the configuration :ref:`CONFIG_BLE_MESH_RX_SEG_MSG_COUNT`.
When the node has no space for receiving new segmented message, this warning will appear. Users can make the space larger through the configuration :menuitem:`CONFIG_BLE_MESH_RX_SEG_MSG_COUNT`.
5.6 What Is the Meaning of Error ``Model not bound to Appkey 0x0000``?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

44
docs/en/api-guides/external-ram.rst
View File

@@ -36,7 +36,7 @@ Hardware
Some PSRAM chips are 1.8 V devices and some are 3.3 V. Consult the datasheet for your PSRAM chip and {IDF_TARGET_NAME} device to find out the working voltages.
By default, the PSRAM is powered up by the on-chip LDO2. You can use :ref:`CONFIG_ESP_LDO_CHAN_PSRAM_DOMAIN` to switch the LDO channel accordingly. Set this value to -1 to use an external power supply, which means the on-chip LDO will not be used. By default, the PSRAM connected to LDO is set to the correct voltage based on the Espressif module used. You can still use :ref:`CONFIG_ESP_LDO_VOLTAGE_PSRAM_DOMAIN` to select the LDO output voltage if you are not using an Espressif module. When using an external power supply, this option does not exist.
By default, the PSRAM is powered up by the on-chip LDO2. You can use :menuitem:`CONFIG_ESP_LDO_CHAN_PSRAM_DOMAIN` to switch the LDO channel accordingly. Set this value to -1 to use an external power supply, which means the on-chip LDO will not be used. By default, the PSRAM connected to LDO is set to the correct voltage based on the Espressif module used. You can still use :menuitem:`CONFIG_ESP_LDO_VOLTAGE_PSRAM_DOMAIN` to select the LDO output voltage if you are not using an Espressif module. When using an external power supply, this option does not exist.
.. note::
@@ -71,7 +71,7 @@ ESP-IDF fully supports the use of external RAM in applications. Once the externa
Integrate RAM into the {IDF_TARGET_NAME} Memory Map
---------------------------------------------------
Select this option by choosing ``Integrate RAM into memory map`` from :ref:`CONFIG_SPIRAM_USE`.
Select this option by choosing ``Integrate RAM into memory map`` from :menuitem:`CONFIG_SPIRAM_USE`.
This is the most basic option for external RAM integration. Most likely, you will need another, more advanced option.
@@ -87,7 +87,7 @@ It is recommended to access the PSRAM by ESP-IDF heap memory allocator (see next
Add External RAM to the Capability Allocator
--------------------------------------------
Select this option by choosing ``Add RAM to heap_caps allocator (malloc() stays internal by default)`` from :ref:`CONFIG_SPIRAM_USE`.
Select this option by choosing ``Add RAM to heap_caps allocator (malloc() stays internal by default)`` from :menuitem:`CONFIG_SPIRAM_USE`.
When enabled, memory is mapped to data virtual address space and also added to the :doc:`capabilities-based heap memory allocator </api-reference/system/mem_alloc>` using ``MALLOC_CAP_SPIRAM``. Since this memory is also tagged with ``MALLOC_CAP_DEFAULT``, calls such as ``heap_caps_malloc(size, MALLOC_CAP_DEFAULT)`` can still return PSRAM pointers.
@@ -101,20 +101,20 @@ In this mode, standard ``malloc()`` does not allocate from external RAM by defau
Provide External RAM via malloc()
---------------------------------
Select this option by choosing ``Make RAM allocatable using malloc() as well`` from :ref:`CONFIG_SPIRAM_USE`. This is the default option.
Select this option by choosing ``Make RAM allocatable using malloc() as well`` from :menuitem:`CONFIG_SPIRAM_USE`. This is the default option.
In this case, memory is added to the capability allocator as described for the previous option. However, it is also added to the pool of RAM that can be returned by the standard ``malloc()`` function.
This allows any application to use the external RAM without having to rewrite the code to use ``heap_caps_malloc(..., MALLOC_CAP_SPIRAM)``.
An additional configuration item, :ref:`CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL`, can be used to set the size threshold when a single allocation should prefer external memory:
An additional configuration item, :menuitem:`CONFIG_SPIRAM_MALLOC_ALWAYSINTERNAL`, can be used to set the size threshold when a single allocation should prefer external memory:
- When allocating a size less than or equal to the threshold, the allocator will try internal memory first.
- When allocating a size larger than the threshold, the allocator will try external memory first.
If a suitable block of preferred internal/external memory is not available, the allocator will try the other type of memory.
Because some buffers can only be allocated in internal memory, a second configuration item :ref:`CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL` reserves a pool of internal DMA-capable memory at startup (in ``main_task``, after PSRAM is initialized). The pool is malloc from the regular internal heaps and re-registered as separate heap pool.
Because some buffers can only be allocated in internal memory, a second configuration item :menuitem:`CONFIG_SPIRAM_MALLOC_RESERVE_INTERNAL` reserves a pool of internal DMA-capable memory at startup (in ``main_task``, after PSRAM is initialized). The pool is malloc from the regular internal heaps and re-registered as separate heap pool.
The reserved pool uses the heap capability priority mechanism:
@@ -128,7 +128,7 @@ Therefore, under normal conditions ``malloc()`` does not allocate from this pool
Allow .bss Segment to Be Placed in External Memory
--------------------------------------------------
Enable this option by checking :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY`.
Enable this option by checking :menuitem:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY`.
If enabled, the region of the data virtual address space where the PSRAM is mapped to will be used to store zero-initialized data (BSS segment) from the lwIP, net80211, libpp, wpa_supplicant and bluedroid ESP-IDF libraries.
@@ -145,7 +145,7 @@ Remaining external RAM can also be added to the capability heap allocator using
Allow .noinit Segment to Be Placed in External Memory
--------------------------------------------------------------
Enable this option by checking :ref:`CONFIG_SPIRAM_ALLOW_NOINIT_SEG_EXTERNAL_MEMORY`. If enabled, the region of the data virtual address space where the PSRAM is mapped to will be used to store non-initialized data. The values placed in this segment will not be initialized or modified even during startup or restart.
Enable this option by checking :menuitem:`CONFIG_SPIRAM_ALLOW_NOINIT_SEG_EXTERNAL_MEMORY`. If enabled, the region of the data virtual address space where the PSRAM is mapped to will be used to store non-initialized data. The values placed in this segment will not be initialized or modified even during startup or restart.
By applying the macro ``EXT_RAM_NOINIT_ATTR``, data could be moved from the internal NOINIT segment to external RAM. Remaining external RAM can still be added to the capability heap allocator using the method shown above, :ref:`external_ram_config_capability_allocator`.
@@ -156,9 +156,9 @@ By applying the macro ``EXT_RAM_NOINIT_ATTR``, data could be moved from the inte
Move Instructions in Flash to PSRAM
-----------------------------------
The :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` option allows the flash ``.text`` sections (for instructions) to be placed in PSRAM.
The :menuitem:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` option allows the flash ``.text`` sections (for instructions) to be placed in PSRAM.
By enabling the :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` option,
By enabling the :menuitem:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` option,
- Instructions from the ``.text`` sections of flash are moved into PSRAM on system startup.
@@ -167,9 +167,9 @@ By applying the macro ``EXT_RAM_NOINIT_ATTR``, data could be moved from the inte
Move Read-Only Data in Flash to PSRAM
---------------------------------------
The :ref:`CONFIG_SPIRAM_RODATA` option allows the flash ``.rodata`` sections (for read only data) to be placed in PSRAM.
The :menuitem:`CONFIG_SPIRAM_RODATA` option allows the flash ``.rodata`` sections (for read only data) to be placed in PSRAM.
By enabling the :ref:`CONFIG_SPIRAM_RODATA` option,
By enabling the :menuitem:`CONFIG_SPIRAM_RODATA` option,
- Instructions from the ``.rodata`` sections of flash are moved into PSRAM on system startup.
@@ -180,7 +180,7 @@ By applying the macro ``EXT_RAM_NOINIT_ATTR``, data could be moved from the inte
Execute In Place (XiP) from PSRAM
------------------------------------
The :ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM` is a helper option for you to select both the :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` and :ref:`CONFIG_SPIRAM_RODATA`.
The :menuitem:`CONFIG_SPIRAM_XIP_FROM_PSRAM` is a helper option for you to select both the :menuitem:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` and :menuitem:`CONFIG_SPIRAM_RODATA`.
The benefits of XiP from PSRAM is:
@@ -197,7 +197,7 @@ By applying the macro ``EXT_RAM_NOINIT_ATTR``, data could be moved from the inte
Execute In Place (XiP) from PSRAM
------------------------------------
The :ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM` option enables the executable in place (XiP) from PSRAM feature. With this option sections that are normally placed in flash, ``.text`` (for instructions) and ``.rodata`` (for read only data), will be loaded in PSRAM.
The :menuitem:`CONFIG_SPIRAM_XIP_FROM_PSRAM` option enables the executable in place (XiP) from PSRAM feature. With this option sections that are normally placed in flash, ``.text`` (for instructions) and ``.rodata`` (for read only data), will be loaded in PSRAM.
With this option enabled, the cache will not be disabled during an SPI1 flash operation, so code that requires executing during an SPI1 flash operation does not have to be placed in internal RAM.
@@ -224,7 +224,7 @@ External RAM use has the following restrictions:
:esp32s3: - DMA transaction descriptors cannot be placed in PSRAM.
:esp32s3: - The bandwidth that DMA accesses external RAM is very limited, especially when the core is trying to access the external RAM at the same time.
:esp32s3: - You can configure :ref:`CONFIG_SPIRAM_SPEED` as 120 MHz for an octal PSRAM. The bandwidth will be improved. However there are still restrictions for this option. See :ref:`All Supported PSRAM Modes and Speeds <flash-psram-combination>` for more details.
:esp32s3: - You can configure :menuitem:`CONFIG_SPIRAM_SPEED` as 120 MHz for an octal PSRAM. The bandwidth will be improved. However there are still restrictions for this option. See :ref:`All Supported PSRAM Modes and Speeds <flash-psram-combination>` for more details.
- External RAM uses the same cache region as the external flash. This means that frequently accessed variables in external RAM can be read and modified almost as quickly as in internal RAM. However, when accessing large chunks of data (> 32 KB), the cache can be insufficient, and speeds will fall back to the access speed of the external RAM. Moreover, accessing large chunks of data can "push out" cached flash, possibly making the execution of code slower afterwards.
@@ -237,14 +237,14 @@ Task Stack Placement in External RAM
There are three ways to place task stacks in external RAM:
1. **Per-task (explicit)** – Use :cpp:func:`xTaskCreateWithCaps` with ``MALLOC_CAP_SPIRAM``. Requires :ref:`CONFIG_FREERTOS_TASK_CREATE_ALLOW_EXT_MEM`.
1. **Per-task (explicit)** – Use :cpp:func:`xTaskCreateWithCaps` with ``MALLOC_CAP_SPIRAM``. Requires :menuitem:`CONFIG_FREERTOS_TASK_CREATE_ALLOW_EXT_MEM`.
2. **Per-task (static)** – Use :cpp:func:`xTaskCreateStatic` with a caller-supplied buffer in external RAM. Requires :ref:`CONFIG_FREERTOS_TASK_CREATE_ALLOW_EXT_MEM`.
2. **Per-task (static)** – Use :cpp:func:`xTaskCreateStatic` with a caller-supplied buffer in external RAM. Requires :menuitem:`CONFIG_FREERTOS_TASK_CREATE_ALLOW_EXT_MEM`.
3. **Global default (automatic)** – Enable :ref:`CONFIG_FREERTOS_PLACE_TASK_STACKS_IN_EXT_RAM`. When set, every call to :cpp:func:`xTaskCreate` / :cpp:func:`xTaskCreatePinnedToCore` allocates the stack from PSRAM first, falling back to internal RAM if PSRAM is exhausted. TCBs are always kept in internal DRAM.
3. **Global default (automatic)** – Enable :menuitem:`CONFIG_FREERTOS_PLACE_TASK_STACKS_IN_EXT_RAM`. When set, every call to :cpp:func:`xTaskCreate` / :cpp:func:`xTaskCreatePinnedToCore` allocates the stack from PSRAM first, falling back to internal RAM if PSRAM is exhausted. TCBs are always kept in internal DRAM.
When :ref:`CONFIG_FREERTOS_PLACE_TASK_STACKS_IN_EXT_RAM` is enabled, the following additional restrictions apply:
When :menuitem:`CONFIG_FREERTOS_PLACE_TASK_STACKS_IN_EXT_RAM` is enabled, the following additional restrictions apply:
- **Flash operations** – Any code path that temporarily disables the CPU cache (flash erase/write, NVS, OTA) must run on a task whose stack is in internal RAM, or the operations must be routed through the `espressif/esp_flash_dispatcher <https://components.espressif.com/components/espressif/esp_flash_dispatcher>`__ component, which executes flash operations on a dedicated internal-RAM task.
- **Deep sleep** – Calling :cpp:func:`esp_deep_sleep_start` from a task with a PSRAM stack logs an error and proceeds anyway, which will likely crash when the cache is disabled during the sleep transition. Use :cpp:func:`esp_deep_sleep_try_to_start` instead: it returns :c:macro:`ESP_ERR_NOT_ALLOWED` cleanly when called from a PSRAM-stacked task. If deep sleep is required, trigger it from a task whose stack is in internal RAM.
@@ -256,11 +256,11 @@ See the :example:`system/freertos/psram_stack` example for a working demonstrati
Failure to Initialize
=====================
By default, failure to initialize external RAM will cause the ESP-IDF startup to abort. This can be disabled by enabling the config item :ref:`CONFIG_SPIRAM_IGNORE_NOTFOUND`.
By default, failure to initialize external RAM will cause the ESP-IDF startup to abort. This can be disabled by enabling the config item :menuitem:`CONFIG_SPIRAM_IGNORE_NOTFOUND`.
.. only:: esp32 or esp32s2
If :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY` is enabled, the option to ignore failure is not available as the linker will have assigned symbols to external memory addresses at link time.
If :menuitem:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY` is enabled, the option to ignore failure is not available as the linker will have assigned symbols to external memory addresses at link time.
.. only:: not esp32
@@ -279,7 +279,7 @@ By default, failure to initialize external RAM will cause the ESP-IDF startup to
Reserving an Unencrypted PSRAM Region
-------------------------------------
Enabling :ref:`CONFIG_SPIRAM_ENC_EXEMPT` reserves a region at the upper end of PSRAM (highest physical addresses; sized by :ref:`CONFIG_SPIRAM_ENC_EXEMPT_SIZE`, in KB, rounded up to the MMU page size) that is mapped without encryption. This region is registered as a separate heap pool reachable only via the ``MALLOC_CAP_SPIRAM_NO_ENC`` capability. The rest of PSRAM (and flash) remains encrypted.
Enabling :menuitem:`CONFIG_SPIRAM_ENC_EXEMPT` reserves a region at the upper end of PSRAM (highest physical addresses; sized by :menuitem:`CONFIG_SPIRAM_ENC_EXEMPT_SIZE`, in KB, rounded up to the MMU page size) that is mapped without encryption. This region is registered as a separate heap pool reachable only via the ``MALLOC_CAP_SPIRAM_NO_ENC`` capability. The rest of PSRAM (and flash) remains encrypted.
.. warning::

30
docs/en/api-guides/fatal-errors.rst
View File

@@ -16,7 +16,7 @@ In certain situations, the execution of the program can not be continued in a we
.. list::
- :doc:`Interrupt watchdog <../api-reference/system/wdts>` timeout
- :doc:`Task watchdog <../api-reference/system/wdts>` timeout (only fatal if :ref:`CONFIG_ESP_TASK_WDT_PANIC` is set)
- :doc:`Task watchdog <../api-reference/system/wdts>` timeout (only fatal if :menuitem:`CONFIG_ESP_TASK_WDT_PANIC` is set)
- Cache access error
:SOC_MEMPROT_SUPPORTED: - Memory protection fault
- Brownout detection event
@@ -50,7 +50,7 @@ For some of the system level checks (interrupt watchdog, cache access error), th
In all cases, the error cause will be printed in parentheses. See :ref:`Guru-Meditation-Errors` for a list of possible error causes.
Subsequent behavior of the panic handler can be set using :ref:`CONFIG_ESP_SYSTEM_PANIC` configuration choice. The available options are:
Subsequent behavior of the panic handler can be set using :menuitem:`CONFIG_ESP_SYSTEM_PANIC` configuration choice. The available options are:
- Print registers and reboot (``CONFIG_ESP_SYSTEM_PANIC_PRINT_REBOOT``) — default option.
@@ -70,19 +70,19 @@ Subsequent behavior of the panic handler can be set using :ref:`CONFIG_ESP_SYSTE
.. note::
The ``CONFIG_ESP_SYSTEM_PANIC_GDBSTUB`` choice in the configuration option :ref:`CONFIG_ESP_SYSTEM_PANIC` is only available when the component ``esp_gdbstub`` is included in the build.
The ``CONFIG_ESP_SYSTEM_PANIC_GDBSTUB`` choice in the configuration option :menuitem:`CONFIG_ESP_SYSTEM_PANIC` is only available when the component ``esp_gdbstub`` is included in the build.
The behavior of the panic handler is affected by three other configuration options.
- If :ref:`CONFIG_ESP_DEBUG_OCDAWARE` is enabled (which is the default), the panic handler will detect whether a JTAG debugger is connected. If it is, execution will be halted and control will be passed to the debugger. In this case, registers and backtrace are not dumped to the console, and GDBStub / Core Dump functions are not used.
- If :menuitem:`CONFIG_ESP_DEBUG_OCDAWARE` is enabled (which is the default), the panic handler will detect whether a JTAG debugger is connected. If it is, execution will be halted and control will be passed to the debugger. In this case, registers and backtrace are not dumped to the console, and GDBStub / Core Dump functions are not used.
- If the :doc:`Core Dump <core_dump>` feature is enabled, then the system state (task stacks and registers) will be dumped to either Flash or UART, for later analysis.
- If :ref:`CONFIG_ESP_PANIC_HANDLER_IRAM` is disabled (disabled by default), the panic handler code is placed in flash memory, not IRAM. This means that if ESP-IDF crashes while flash cache is disabled, the panic handler will automatically re-enable flash cache before running GDB Stub or Core Dump. This adds some minor risk, if the flash cache status is also corrupted during the crash.
- If :menuitem:`CONFIG_ESP_PANIC_HANDLER_IRAM` is disabled (disabled by default), the panic handler code is placed in flash memory, not IRAM. This means that if ESP-IDF crashes while flash cache is disabled, the panic handler will automatically re-enable flash cache before running GDB Stub or Core Dump. This adds some minor risk, if the flash cache status is also corrupted during the crash.
If this option is enabled, the panic handler code (including required UART functions) is placed in IRAM, and hence will decrease the usable memory space in SRAM. But this may be necessary to debug some complex issues with crashes while flash cache is disabled (for example, when writing to SPI flash) or when flash cache is corrupted when an exception is triggered.
- If :ref:`CONFIG_ESP_SYSTEM_PANIC_REBOOT_DELAY_SECONDS` is enabled (disabled by default) and set to a number higher than 0, the panic handler will delay the reboot for that amount of time in seconds. This can help if the tool used to monitor serial output does not provide a possibility to stop and examine the serial output. In that case, delaying the reboot will allow users to examine and debug the panic handler output (backtrace, etc.) for the duration of the delay. After the delay, the device will reboot. The reset reason is preserved.
- If :menuitem:`CONFIG_ESP_SYSTEM_PANIC_REBOOT_DELAY_SECONDS` is enabled (disabled by default) and set to a number higher than 0, the panic handler will delay the reboot for that amount of time in seconds. This can help if the tool used to monitor serial output does not provide a possibility to stop and examine the serial output. In that case, delaying the reboot will allow users to examine and debug the panic handler output (backtrace, etc.) for the duration of the delay. After the delay, the device will reboot. The reset reason is preserved.
The following diagram illustrates the panic handler behavior:
@@ -299,14 +299,14 @@ RTC Watchdog Timeout
{IDF_TARGET_RTCWDT_RTC_RESET:default="Not updated", esp32="RTCWDT_RTC_RESET", esp32s2="RTCWDT_RTC_RST", esp32s3="RTCWDT_RTC_RST", esp32c3="RTCWDT_RTC_RST", esp32c2="RTCWDT_RTC_RST", esp32c6="LP_WDT_SYS", esp32h2="LP_WDT_SYS", esp32p4="LP_WDT_SYS"}
The RTC watchdog is used in the startup code to keep track of execution time and it also helps to prevent a lock-up caused by an unstable power source. It is enabled by default (see :ref:`CONFIG_BOOTLOADER_WDT_ENABLE`). If the execution time is exceeded, the RTC watchdog will restart the system. In this case, the first stage (ROM) bootloader will print a message with the ``RTC Watchdog Timeout`` reason for the reboot.
The RTC watchdog is used in the startup code to keep track of execution time and it also helps to prevent a lock-up caused by an unstable power source. It is enabled by default (see :menuitem:`CONFIG_BOOTLOADER_WDT_ENABLE`). If the execution time is exceeded, the RTC watchdog will restart the system. In this case, the first stage (ROM) bootloader will print a message with the ``RTC Watchdog Timeout`` reason for the reboot.
.. code-block:: none
rst:0x10 ({IDF_TARGET_RTCWDT_RTC_RESET})
The RTC watchdog covers the execution time from the first stage (ROM) bootloader to application startup. It is initially set in the first stage (ROM) bootloader, then configured in the bootloader with the :ref:`CONFIG_BOOTLOADER_WDT_TIME_MS` option (9000 ms by default). During the application initialization stage, it is reconfigured because the source of the slow clock may have changed, and finally disabled right before the ``app_main()`` call. There is an option :ref:`CONFIG_BOOTLOADER_WDT_DISABLE_IN_USER_CODE` which prevents the RTC watchdog from being disabled before ``app_main``. Instead, the RTC watchdog remains active and must be fed periodically in your application's code.
The RTC watchdog covers the execution time from the first stage (ROM) bootloader to application startup. It is initially set in the first stage (ROM) bootloader, then configured in the bootloader with the :menuitem:`CONFIG_BOOTLOADER_WDT_TIME_MS` option (9000 ms by default). During the application initialization stage, it is reconfigured because the source of the slow clock may have changed, and finally disabled right before the ``app_main()`` call. There is an option :menuitem:`CONFIG_BOOTLOADER_WDT_DISABLE_IN_USER_CODE` which prevents the RTC watchdog from being disabled before ``app_main``. Instead, the RTC watchdog remains active and must be fed periodically in your application's code.
The RTC watchdog is also used by the system :ref:`panic handler <Panic-Handler>` to protect the system from hanging during a panic. The RTC watchdog is reconfigured in the panic handler to have a timeout of 10 seconds. If the panic handler takes longer than 10 seconds to execute, the system will be reset by the RTC watchdog.
@@ -423,7 +423,7 @@ In some situations, ESP-IDF will temporarily disable access to external SPI flas
* writing to instruction RAM after the program is loaded
* executing code from data RAM (areas used for heap and static .data and .bss)
Such operations are not necessary for most programs. Prohibiting such operations typically makes software vulnerabilities harder to exploit. Applications which rely on dynamic loading or self-modifying code may disable this protection using :ref:`CONFIG_ESP_SYSTEM_MEMPROT` Kconfig option.
Such operations are not necessary for most programs. Prohibiting such operations typically makes software vulnerabilities harder to exploit. Applications which rely on dynamic loading or self-modifying code may disable this protection using :menuitem:`CONFIG_ESP_SYSTEM_MEMPROT` Kconfig option.
When the fault occurs, the panic handler reports the address of the fault and the type of memory access that caused it.
@@ -435,7 +435,7 @@ Other Fatal Errors
Brownout
^^^^^^^^
{IDF_TARGET_NAME} has a built-in brownout detector, which is enabled by default. The brownout detector can trigger a system reset if the supply voltage goes below a safe level. The brownout detector can be configured using :ref:`CONFIG_ESP_BROWNOUT_DET` and :ref:`CONFIG_ESP_BROWNOUT_DET_LVL_SEL` options.
{IDF_TARGET_NAME} has a built-in brownout detector, which is enabled by default. The brownout detector can trigger a system reset if the supply voltage goes below a safe level. The brownout detector can be configured using :menuitem:`CONFIG_ESP_BROWNOUT_DET` and :menuitem:`CONFIG_ESP_BROWNOUT_DET_LVL_SEL` options.
When the brownout detector triggers, the following message is printed:
@@ -485,7 +485,7 @@ Consult :doc:`Heap Memory Debugging <../api-reference/system/heap_debug>` docume
Guru Meditation Error: Core 0 panic'ed (Stack protection fault).
Hardware stack guard can be disabled using :ref:`CONFIG_ESP_SYSTEM_HW_STACK_GUARD` options.
Hardware stack guard can be disabled using :menuitem:`CONFIG_ESP_SYSTEM_HW_STACK_GUARD` options.
.. _FreeRTOS-End-Of-Stack-Watchpoint:
@@ -514,18 +514,18 @@ If watchpoint triggers, the message will be similar to:
Guru Meditation Error: Core 0 panic'ed (Breakpoint). Exception was unhandled.
This feature can be enabled by using the :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` option.
This feature can be enabled by using the :menuitem:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` option.
FreeRTOS Stack Checks
"""""""""""""""""""""
See :ref:`CONFIG_FREERTOS_CHECK_STACKOVERFLOW`
See :menuitem:`CONFIG_FREERTOS_CHECK_STACKOVERFLOW`
Stack Smashing
^^^^^^^^^^^^^^
Stack smashing protection (based on GCC ``-fstack-protector*`` flags) can be enabled in ESP-IDF using :ref:`CONFIG_COMPILER_STACK_CHECK_MODE` option. If stack smashing is detected, message similar to the following will be printed:
Stack smashing protection (based on GCC ``-fstack-protector*`` flags) can be enabled in ESP-IDF using :menuitem:`CONFIG_COMPILER_STACK_CHECK_MODE` option. If stack smashing is detected, message similar to the following will be printed:
.. code-block:: none
@@ -560,7 +560,7 @@ The backtrace should point to the function where stack smashing has occurred. Ch
A CPU lockup reset happens when there is a double exception, i.e. when an exception occurs while the CPU is already in an exception handler. The most common cause for this is when the cache is in a state where accessing external memory becomes impossible. In such cases, the panic handler will crash as well due to being unable to fetch instructions or read data.
To gather more information about the cause of the lockup, you can try placing the panic handler code in IRAM, which remains accessible even when the cache is disabled. This can be done with :ref:`CONFIG_ESP_PANIC_HANDLER_IRAM`.
To gather more information about the cause of the lockup, you can try placing the panic handler code in IRAM, which remains accessible even when the cache is disabled. This can be done with :menuitem:`CONFIG_ESP_PANIC_HANDLER_IRAM`.
Undefined Behavior Sanitizer (UBSAN) Checks

22
docs/en/api-guides/flash_psram_config.rst
View File

@@ -45,19 +45,19 @@ Configure the Flash
The flash related configurations are under ``Serial flasher config`` menu.
1. Flash type used on the board. For Octal flash, select :ref:`CONFIG_ESPTOOLPY_OCT_FLASH`. For Quad flash, uncheck this configuration.
2. Flash line mode. Select a line mode in :ref:`CONFIG_ESPTOOLPY_FLASHMODE`. The higher the line mode is, the faster the SPI speed is. See terminology above about the line mode.
3. Flash sample mode. Select a sample mode in :ref:`CONFIG_ESPTOOLPY_FLASH_SAMPLE_MODE`. DDR mode is faster than SDR mode. See terminology above about SDR and DDR mode.
4. Flash speed. Select a Flash frequency in :ref:`CONFIG_ESPTOOLPY_FLASHFREQ`.
5. Flash size. Flash size, in megabytes. Select a flash size in :ref:`CONFIG_ESPTOOLPY_FLASHSIZE`.
1. Flash type used on the board. For Octal flash, select :menuitem:`CONFIG_ESPTOOLPY_OCT_FLASH`. For Quad flash, uncheck this configuration.
2. Flash line mode. Select a line mode in :menuitem:`CONFIG_ESPTOOLPY_FLASHMODE`. The higher the line mode is, the faster the SPI speed is. See terminology above about the line mode.
3. Flash sample mode. Select a sample mode in :menuitem:`CONFIG_ESPTOOLPY_FLASH_SAMPLE_MODE`. DDR mode is faster than SDR mode. See terminology above about SDR and DDR mode.
4. Flash speed. Select a Flash frequency in :menuitem:`CONFIG_ESPTOOLPY_FLASHFREQ`.
5. Flash size. Flash size, in megabytes. Select a flash size in :menuitem:`CONFIG_ESPTOOLPY_FLASHSIZE`.
Configure the PSRAM
^^^^^^^^^^^^^^^^^^^
To enable PSRAM, please enable the :ref:`CONFIG_SPIRAM` under ``Component config / Hardware Settings`` menu. Then all the PSRAM related configurations will be visible under ``SPI RAM config`` menu.
To enable PSRAM, enable :menuitem:`CONFIG_SPIRAM`. The related configuration options will then become visible.
1. PSRAM type used on the board. Select a type in :ref:`CONFIG_SPIRAM_MODE` for Quad or Octal PSRAM.
2. PSRAM speed. Select a PSRAM frequency in :ref:`CONFIG_SPIRAM_SPEED`.
1. PSRAM type used on the board. Select a type in :menuitem:`CONFIG_SPIRAM_MODE` for Quad or Octal PSRAM.
2. PSRAM speed. Select a PSRAM frequency in :menuitem:`CONFIG_SPIRAM_SPEED`.
.. note::
@@ -89,7 +89,7 @@ All Supported Modes and Speeds
120 MHz DDR mode is an experimental feature. You will only see it when:
- :ref:`CONFIG_IDF_EXPERIMENTAL_FEATURES` is enabled
- :menuitem:`CONFIG_IDF_EXPERIMENTAL_FEATURES` is enabled
With above step, you will find 120 MHz option is visible.
@@ -101,7 +101,7 @@ All Supported Modes and Speeds
.. note::
The PSRAM requires a phase point calibration algorithm when operating at 120M. The phase point setting is related to the temperature at startup. When the temperature increases / decreases significantly during the operation of the chip, the PSRAM may experience read/write errors. To solve this problem, you can enable dynamic adjustment of the PSRAM phase point based on the temperature value with :ref:`CONFIG_SPIRAM_TIMING_TUNING_POINT_VIA_TEMPERATURE_SENSOR`. This creates a task that measures the temperature every :ref:`CONFIG_SPIRAM_TIMING_MEASURE_TEMPERATURE_INTERVAL_SECOND` seconds and adjusts the PSRAM phase point accordingly.
The PSRAM requires a phase point calibration algorithm when operating at 120M. The phase point setting is related to the temperature at startup. When the temperature increases / decreases significantly during the operation of the chip, the PSRAM may experience read/write errors. To solve this problem, you can enable dynamic adjustment of the PSRAM phase point based on the temperature value with :menuitem:`CONFIG_SPIRAM_TIMING_TUNING_POINT_VIA_TEMPERATURE_SENSOR`. This creates a task that measures the temperature every :menuitem:`CONFIG_SPIRAM_TIMING_MEASURE_TEMPERATURE_INTERVAL_SECOND` seconds and adjusts the PSRAM phase point accordingly.
F8R8 Hardware
^^^^^^^^^^^^^
@@ -245,7 +245,7 @@ Error Handling
The first stage (ROM) bootloader relies on an eFuse bit ``FLASH_TYPE`` to reset the flash into the default mode (SPI mode). If this bit is not burnt and the flash is working in OPI mode, the first stage (ROM) bootloader may not be able to read from the flash and load the following images.
2. If you enabled :ref:`CONFIG_ESPTOOLPY_OCT_FLASH`, and there's an error log saying:
2. If you enabled :menuitem:`CONFIG_ESPTOOLPY_OCT_FLASH`, and there's an error log saying:
.. code-block:: c

6
docs/en/api-guides/hlinterrupts.rst
View File

@@ -40,8 +40,8 @@ Interrupt Priorities
- xt_debugexception
- Debug exception. Called on e.g., a BREAK instruction. [2]_
.. [1] ESP-IDF debug logic can be configured to run on ``xt_highint4`` or ``xt_highint5`` in :ref:`CONFIG_ESP_SYSTEM_CHECK_INT_LEVEL`. Bluetooth's interrupt can be configured to run on priority level 4 by enabling :ref:`CONFIG_BTDM_CTRL_HLI`. If :ref:`CONFIG_BTDM_CTRL_HLI` is enabled, ESP-IDF debug logic must be running on priority level 5 interrupt.
.. [2] If :ref:`CONFIG_BTDM_CTRL_HLI` is enabled, ``xt_debugexception`` is used to fix the `live lock issue <https://www.espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf>`_ in ESP32 ECO3.
.. [1] ESP-IDF debug logic can be configured to run on ``xt_highint4`` or ``xt_highint5`` in :menuitem:`CONFIG_ESP_SYSTEM_CHECK_INT_LEVEL`. Bluetooth's interrupt can be configured to run on priority level 4 by enabling :menuitem:`CONFIG_BTDM_CTRL_HLI`. If :menuitem:`CONFIG_BTDM_CTRL_HLI` is enabled, ESP-IDF debug logic must be running on priority level 5 interrupt.
.. [2] If :menuitem:`CONFIG_BTDM_CTRL_HLI` is enabled, ``xt_debugexception`` is used to fix the `live lock issue <https://www.espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf>`_ in ESP32 ECO3.
.. only:: not esp32
@@ -95,7 +95,7 @@ Notes
.. only:: esp32
When :ref:`CONFIG_BTDM_CTRL_HLI` is enabled, C code is also called from a high-priority interrupt, this is possible thanks to some additional protection added to it.
When :menuitem:`CONFIG_BTDM_CTRL_HLI` is enabled, C code is also called from a high-priority interrupt, this is possible thanks to some additional protection added to it.
- Make sure your assembly code gets linked in. Indeed, as the free-to-use symbols are declared as weak, the linker may discard the file containing the symbol. This happens if the only symbol defined, or used from the user file is the ``xt_*`` free-to-use symbol. To avoid this, in the assembly file containing the ``xt_*`` symbol, define another symbol, like:

8
docs/en/api-guides/inc/external-ram-esp32-notes.rst
View File

@@ -1,5 +1,5 @@
* Regarding stacks in PSRAM: For tasks that do not call ROM code in any way (directly or indirectly), the :ref:`CONFIG_FREERTOS_TASK_CREATE_ALLOW_EXT_MEM` option will eliminate the check in :cpp:func:`xTaskCreateStatic`, allowing a task's stack to be in external RAM. However, using this is **not advised**.
* When used at 80 MHz clock speed, external RAM must also occupy either the HSPI or VSPI bus. Select which SPI host will be used by :ref:`CONFIG_SPIRAM_OCCUPY_SPI_HOST`.
* Regarding stacks in PSRAM: For tasks that do not call ROM code in any way (directly or indirectly), the :menuitem:`CONFIG_FREERTOS_TASK_CREATE_ALLOW_EXT_MEM` option will eliminate the check in :cpp:func:`xTaskCreateStatic`, allowing a task's stack to be in external RAM. However, using this is **not advised**.
* When used at 80 MHz clock speed, external RAM must also occupy either the HSPI or VSPI bus. Select which SPI host will be used by :menuitem:`CONFIG_SPIRAM_OCCUPY_SPI_HOST`.
Chip Revisions
@@ -15,7 +15,7 @@ ESP-IDF has no workaround for the bugs in this revision of silicon, and it canno
ESP32 Rev v1.0
--------------
The bugs in this revision of silicon cause issues if certain sequences of machine instructions operate on external memory. (`ESP32 Series SoC Errata`_ > CPU-3.2). As a workaround, the ``-mfix-esp32-psram-cache-issue`` flag has been added to the ESP32 GCC compiler such that these sequences are filtered out. As a result, the compiler only outputs code that can safely be executed. The :ref:`CONFIG_SPIRAM_CACHE_WORKAROUND` option can be used to enable this workaround.
The bugs in this revision of silicon cause issues if certain sequences of machine instructions operate on external memory. (`ESP32 Series SoC Errata`_ > CPU-3.2). As a workaround, the ``-mfix-esp32-psram-cache-issue`` flag has been added to the ESP32 GCC compiler such that these sequences are filtered out. As a result, the compiler only outputs code that can safely be executed. The :menuitem:`CONFIG_SPIRAM_CACHE_WORKAROUND` option can be used to enable this workaround.
Aside from linking to a recompiled version of Newlib with the additional flag, ESP-IDF also does the following:
@@ -25,4 +25,4 @@ Aside from linking to a recompiled version of Newlib with the additional flag, E
ESP32 Rev v3.0
--------------
ESP32 rev v3.0 fixes the PSRAM cache issue found in rev v1.0. When :ref:`CONFIG_ESP32_REV_MIN` option is set to ``rev v3.0``, compiler workarounds related to PSRAM will be disabled. For more information about ESP32 v3.0, see `ESP32 Chip Revision v3.0 User Guide`_.
ESP32 rev v3.0 fixes the PSRAM cache issue found in rev v1.0. When :menuitem:`CONFIG_ESP32_REV_MIN` option is set to ``rev v3.0``, compiler workarounds related to PSRAM will be disabled. For more information about ESP32 v3.0, see `ESP32 Chip Revision v3.0 User Guide`_.

2
docs/en/api-guides/jtag-debugging/index.rst
View File

@@ -7,7 +7,7 @@ This document provides a guide to installing OpenOCD for {IDF_TARGET_NAME} and d
.. note::
You can also debug your {IDF_TARGET_NAME} without needing to setup JTAG or OpenOCD by using ``idf.py monitor``. See: :doc:`../../api-guides/tools/idf-monitor` and :ref:`CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME`.
You can also debug your {IDF_TARGET_NAME} without needing to setup JTAG or OpenOCD by using ``idf.py monitor``. See: :doc:`../../api-guides/tools/idf-monitor` and :menuitem:`CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME`.
.. highlight:: none

14
docs/en/api-guides/jtag-debugging/tips-and-quirks.rst
View File

@@ -12,11 +12,11 @@ Breakpoints and Watchpoints Available
.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA
{IDF_TARGET_NAME} debugger supports {IDF_TARGET_SOC_CPU_BREAKPOINTS_NUM} hardware implemented breakpoints and 64 software ones. Hardware breakpoints are implemented by {IDF_TARGET_NAME} chip's logic and can be set anywhere in the code: either in flash or IRAM program's regions. Additionally there are 2 types of software breakpoints implemented by OpenOCD: flash (up to 32) and IRAM (up to 32) breakpoints. Currently GDB can not set software breakpoints in flash. So until this limitation is removed those breakpoints have to be emulated by OpenOCD as hardware ones (see :ref:`below <jtag-debugging-tip-where-breakpoints>` for details). {IDF_TARGET_NAME} also supports {IDF_TARGET_SOC_CPU_WATCHPOINTS_NUM} watchpoints, so {IDF_TARGET_SOC_CPU_WATCHPOINTS_NUM} variables can be watched for change or read by the GDB command ``watch myVariable``. Note that menuconfig option :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` uses the last watchpoint and will not provide expected results, if you also try to use it within OpenOCD/GDB. See menuconfig's help for detailed description.
{IDF_TARGET_NAME} debugger supports {IDF_TARGET_SOC_CPU_BREAKPOINTS_NUM} hardware implemented breakpoints and 64 software ones. Hardware breakpoints are implemented by {IDF_TARGET_NAME} chip's logic and can be set anywhere in the code: either in flash or IRAM program's regions. Additionally there are 2 types of software breakpoints implemented by OpenOCD: flash (up to 32) and IRAM (up to 32) breakpoints. Currently GDB can not set software breakpoints in flash. So until this limitation is removed those breakpoints have to be emulated by OpenOCD as hardware ones (see :ref:`below <jtag-debugging-tip-where-breakpoints>` for details). {IDF_TARGET_NAME} also supports {IDF_TARGET_SOC_CPU_WATCHPOINTS_NUM} watchpoints, so {IDF_TARGET_SOC_CPU_WATCHPOINTS_NUM} variables can be watched for change or read by the GDB command ``watch myVariable``. Note that menuconfig option :menuitem:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` uses the last watchpoint and will not provide expected results, if you also try to use it within OpenOCD/GDB. See menuconfig's help for detailed description.
.. only:: CONFIG_IDF_TARGET_ARCH_RISCV
{IDF_TARGET_NAME} debugger supports {IDF_TARGET_SOC_CPU_BREAKPOINTS_NUM} hardware implemented breakpoints and an unlimited number of software ones. Hardware breakpoints are implemented by {IDF_TARGET_NAME} chip's logic and can be set anywhere in the code: either in flash or IRAM program's regions. Additionally there are 2 types of software breakpoints implemented by OpenOCD: flash (up to 32) and IRAM (unlimited) breakpoints. Currently GDB can not set software breakpoints in flash. So until this limitation is removed those breakpoints have to be emulated by OpenOCD as hardware ones (see :ref:`below <jtag-debugging-tip-where-breakpoints>` for details). {IDF_TARGET_NAME} also supports {IDF_TARGET_SOC_CPU_WATCHPOINTS_NUM} watchpoints, so {IDF_TARGET_SOC_CPU_WATCHPOINTS_NUM} variables can be watched for change or read by the GDB command ``watch myVariable``. Note that menuconfig option :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` uses the last watchpoint and will not provide expected results, if you also try to use it within OpenOCD/GDB. See menuconfig's help for detailed description.
{IDF_TARGET_NAME} debugger supports {IDF_TARGET_SOC_CPU_BREAKPOINTS_NUM} hardware implemented breakpoints and an unlimited number of software ones. Hardware breakpoints are implemented by {IDF_TARGET_NAME} chip's logic and can be set anywhere in the code: either in flash or IRAM program's regions. Additionally there are 2 types of software breakpoints implemented by OpenOCD: flash (up to 32) and IRAM (unlimited) breakpoints. Currently GDB can not set software breakpoints in flash. So until this limitation is removed those breakpoints have to be emulated by OpenOCD as hardware ones (see :ref:`below <jtag-debugging-tip-where-breakpoints>` for details). {IDF_TARGET_NAME} also supports {IDF_TARGET_SOC_CPU_WATCHPOINTS_NUM} watchpoints, so {IDF_TARGET_SOC_CPU_WATCHPOINTS_NUM} variables can be watched for change or read by the GDB command ``watch myVariable``. Note that menuconfig option :menuitem:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` uses the last watchpoint and will not provide expected results, if you also try to use it within OpenOCD/GDB. See menuconfig's help for detailed description.
.. _jtag-debugging-tip-where-breakpoints:
@@ -64,9 +64,9 @@ Support Options for OpenOCD at Compile Time
ESP-IDF has some support options for OpenOCD debugging which can be set at compile time:
* :ref:`CONFIG_ESP_DEBUG_OCDAWARE` is enabled by default. If a panic or unhandled exception is thrown and a JTAG debugger is connected (ie OpenOCD is running), ESP-IDF will break into the debugger.
* :menuitem:`CONFIG_ESP_DEBUG_OCDAWARE` is enabled by default. If a panic or unhandled exception is thrown and a JTAG debugger is connected (ie OpenOCD is running), ESP-IDF will break into the debugger.
* :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` (disabled by default) sets watchpoint index 1 (the second of two) at the end of any task stack. This is the most accurate way to debug task stack overflows. Click the link for more details.
* :menuitem:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` (disabled by default) sets watchpoint index 1 (the second of two) at the end of any task stack. This is the most accurate way to debug task stack overflows. Click the link for more details.
Please see the :ref:`project configuration menu for Windows <get-started-configure>`, :ref:`Linux, or macOS <get-started-configure-linux-macos>` menu for more details on setting compile-time options.
@@ -115,7 +115,7 @@ In order to achieve higher data rates and minimize number of dropped packets it
Improve Debugging Speed
^^^^^^^^^^^^^^^^^^^^^^^
Enabling :ref:`CONFIG_ESP_DEBUG_INCLUDE_OCD_STUB_BINS` allocates 12 KB of RAM and embeds pre-built stub binaries into RAM. This improves the overall debugging speed by eliminating the need to load the stub binaries at runtime. It is particularly beneficial when using flash breakpoints, as it reduces the latency of add/remove breakpoints. However, keep in mind that the increased RAM usage may reduce memory availability for other tasks.
Enabling :menuitem:`CONFIG_ESP_DEBUG_INCLUDE_OCD_STUB_BINS` allocates 12 KB of RAM and embeds pre-built stub binaries into RAM. This improves the overall debugging speed by eliminating the need to load the stub binaries at runtime. It is particularly beneficial when using flash breakpoints, as it reduces the latency of add/remove breakpoints. However, keep in mind that the increased RAM usage may reduce memory availability for other tasks.
.. _jtag-debugging-tip-debugger-startup-commands:
@@ -129,7 +129,7 @@ What Is the Meaning of Debugger's Startup Commands?
On startup, debugger is issuing sequence of commands to reset the chip and halt it at specific line of code. This sequence (shown below) is user defined to pick up at most convenient/appropriate line and start debugging.
* ``set remote hardware-watchpoint-limit {IDF_TARGET_SOC_CPU_WATCHPOINTS_NUM}`` — Restrict GDB to using available hardware watchpoints supported by the chip, {IDF_TARGET_SOC_CPU_WATCHPOINTS_NUM} for {IDF_TARGET_NAME}. For more information see https://sourceware.org/gdb/onlinedocs/gdb/Remote-Configuration.html.
* ``mon reset halt`` — reset the chip and keep the CPUs halted. Target has to be reset to disable memory protection, which is required to enable flash support. If reset is not desirable, add an extra argument ``-c 'set ESP_FLASH_SIZE 0'`` to the start of the OpenOCD command line to disable flash support, see :ref:`jtag-debugging-tip-openocd-config-vars`. Alternatively, disable memory protection using the config option :ref:`CONFIG_ESP_SYSTEM_MEMPROT`.
* ``mon reset halt`` — reset the chip and keep the CPUs halted. Target has to be reset to disable memory protection, which is required to enable flash support. If reset is not desirable, add an extra argument ``-c 'set ESP_FLASH_SIZE 0'`` to the start of the OpenOCD command line to disable flash support, see :ref:`jtag-debugging-tip-openocd-config-vars`. Alternatively, disable memory protection using the config option :menuitem:`CONFIG_ESP_SYSTEM_MEMPROT`.
* ``maintenance flush register-cache`` — monitor (``mon``) command can not inform GDB that the target state has changed. GDB will assume that whatever stack the target had before ``mon reset halt`` will still be valid. In fact, after reset the target state will change, and executing ``maintenance flush register-cache`` is a way to force GDB to get new state from the target.
* ``thb app_main`` — insert a temporary hardware breakpoint at ``app_main``, put here another function name if required
* ``c`` — resume the program. It will then stop at breakpoint inserted at ``app_main``.
@@ -255,7 +255,7 @@ By default, enabling Flash Encryption and/or Secure Boot will disable JTAG debug
Please note that once JTAG is permanently disabled, it cannot be re-enabled for JTAG access. However, we do have the option of disabling JTAG softly. For more details on soft disabling and re-enabling soft-disabled JTAG, please refer to the :ref:`HMAC for Enabling JTAG <hmac_for_enabling_jtag>`.
The project configuration option :ref:`CONFIG_SECURE_BOOT_ALLOW_JTAG` will keep JTAG enabled at this time, removing all physical security but allowing debugging. (Although the name suggests Secure Boot, this option can be applied even when only Flash Encryption is enabled).
The project configuration option :menuitem:`CONFIG_SECURE_BOOT_ALLOW_JTAG` will keep JTAG enabled at this time, removing all physical security but allowing debugging. (Although the name suggests Secure Boot, this option can be applied even when only Flash Encryption is enabled).
However, OpenOCD may attempt to automatically read and write the flash in order to set :ref:`software breakpoints <jtag-debugging-tip-where-breakpoints>`. Setting a software breakpoint will change the digest of a signed app and make the signature invalid. This means if Secure Boot is enabled, a software breakpoint is set, and then a reset occurs, the signature verification will fail on boot.

24
docs/en/api-guides/low-power-mode/low-power-mode-ble.rst
View File

@@ -17,15 +17,15 @@ To select the main XTAL as the Bluetooth LE internal clock source, configure the
.. only:: esp32
:ref:`CONFIG_BTDM_CTRL_LOW_POWER_CLOCK` = Main crystal (`CONFIG_BTDM_CTRL_LPCLK_SEL_MAIN_XTAL`)
:menuitem:`CONFIG_BTDM_CTRL_LOW_POWER_CLOCK` = Main crystal (`CONFIG_BTDM_CTRL_LPCLK_SEL_MAIN_XTAL`)
.. only:: esp32c3 or esp32s3
:ref:`CONFIG_BT_CTRL_LOW_POWER_CLOCK` = Main crystal (`CONFIG_BT_CTRL_LPCLK_SEL_MAIN_XTAL`)
:menuitem:`CONFIG_BT_CTRL_LOW_POWER_CLOCK` = Main crystal (`CONFIG_BT_CTRL_LPCLK_SEL_MAIN_XTAL`)
.. only:: esp32c2 or esp32c6 or esp32h2 or esp32c5 or esp32c61
:ref:`CONFIG_BT_LE_LP_CLK_SRC` = Use main XTAL as RTC clock source (`CONFIG_BT_LE_LP_CLK_SRC_MAIN_XTAL`)
:menuitem:`CONFIG_BT_LE_LP_CLK_SRC` = Use main XTAL as RTC clock source (`CONFIG_BT_LE_LP_CLK_SRC_MAIN_XTAL`)
When this is selected, the main XTAL remains powered on during light-sleep, resulting in higher current consumption. Please refer to :example_file:`Power Save README <bluetooth/nimble/power_save/README.md>` for the typical current consumption in light-sleep using XTAL versus a 32 kHz external crystal.
@@ -38,19 +38,19 @@ To use a 32 kHz external crystal as the Bluetooth LE internal clock source, conf
.. only:: esp32
:ref:`CONFIG_BTDM_CTRL_LOW_POWER_CLOCK` = External 32 kHz crystal/oscillator (`CONFIG_BTDM_CTRL_LPCLK_SEL_EXT_32K_XTAL`)
:menuitem:`CONFIG_BTDM_CTRL_LOW_POWER_CLOCK` = External 32 kHz crystal/oscillator (`CONFIG_BTDM_CTRL_LPCLK_SEL_EXT_32K_XTAL`)
.. only:: esp32c3 or esp32s3
:ref:`CONFIG_BT_CTRL_LOW_POWER_CLOCK` = External 32 kHz crystal/oscillator (`CONFIG_BT_CTRL_LPCLK_SEL_EXT_32K_XTAL`)
:menuitem:`CONFIG_BT_CTRL_LOW_POWER_CLOCK` = External 32 kHz crystal/oscillator (`CONFIG_BT_CTRL_LPCLK_SEL_EXT_32K_XTAL`)
.. only:: esp32c2 or esp32c6 or esp32h2 or esp32c5 or esp32c61
:ref:`CONFIG_BT_LE_LP_CLK_SRC` = Use system RTC slow clock source (`CONFIG_BT_LE_LP_CLK_SRC_DEFAULT`)
:menuitem:`CONFIG_BT_LE_LP_CLK_SRC` = Use system RTC slow clock source (`CONFIG_BT_LE_LP_CLK_SRC_DEFAULT`)
**Configuration Path 2:**
:ref:`CONFIG_RTC_CLK_SRC` = External 32 kHz crystal (`CONFIG_RTC_CLK_SRC_EXT_CRYS`)
:menuitem:`CONFIG_RTC_CLK_SRC` = External 32 kHz crystal (`CONFIG_RTC_CLK_SRC_EXT_CRYS`)
**Note:** Even if 32 kHz is selected in menuconfig, the system will fall back to the main XTAL if the external crystal is not detected during Bluetooth LE initialization. This may lead to unexpected current consumption in light-sleep mode.
@@ -63,7 +63,7 @@ Selecting 136 kHz RC Oscillator
**Configuration Path 1:**
:ref:`CONFIG_BT_CTRL_LOW_POWER_CLOCK` = Internal 136kHz RC oscillator (`CONFIG_BT_CTRL_LPCLK_SEL_RTC_SLOW`)
:menuitem:`CONFIG_BT_CTRL_LOW_POWER_CLOCK` = Internal 136kHz RC oscillator (`CONFIG_BT_CTRL_LPCLK_SEL_RTC_SLOW`)
Generally, the 136 kHz RC oscillator cannot meet the accuracy requirement of Bluetooth LE. It is only suitable for scenarios with low clock accuracy requirements, such as legacy advertising (ADV) or scanning. It does not support connections in central or peripheral roles.
@@ -77,13 +77,13 @@ Selecting 136 kHz RC Oscillator
**Configuration Path 1:**
:ref:`CONFIG_BT_LE_LP_CLK_SRC` = Use system RTC slow clock source (`CONFIG_BT_LE_LP_CLK_SRC_DEFAULT`)
:menuitem:`CONFIG_BT_LE_LP_CLK_SRC` = Use system RTC slow clock source (`CONFIG_BT_LE_LP_CLK_SRC_DEFAULT`)
.. only:: not esp32
**Configuration Path 2:**
:ref:`CONFIG_RTC_CLK_SRC` = Internal 136 kHz RC oscillator (`CONFIG_RTC_CLK_SRC_INT_RC`)
:menuitem:`CONFIG_RTC_CLK_SRC` = Internal 136 kHz RC oscillator (`CONFIG_RTC_CLK_SRC_INT_RC`)
.. only:: esp32c2 or esp32c6 or esp32h2 or esp32c5 or esp32c61
@@ -96,8 +96,8 @@ Selecting 136 kHz RC Oscillator
**Configuration Path:**
- :ref:`CONFIG_BT_LE_LL_PEER_SCA_SET_ENABLE` = y
- :ref:`CONFIG_BT_LE_LL_PEER_SCA` = 3000
- :menuitem:`CONFIG_BT_LE_LL_PEER_SCA_SET_ENABLE` = y
- :menuitem:`CONFIG_BT_LE_LL_PEER_SCA` = 3000
**Note:** Using the 136 kHz RC oscillator may occasionally cause issues such as connection establishment failures or connection timeouts.

180
docs/en/api-guides/low-power-mode/low-power-mode-soc.rst
View File

@@ -16,7 +16,7 @@ DFS
Dynamic Frequency Scaling (DFS) is a fundamental feature of the power management mechanism integrated into ESP-IDF. DFS adjusts the Advanced Peripheral Bus (APB) frequency and CPU frequency based on the application's holding of power locks. When holding a high-performance lock, it utilizes high frequency, while in idle states without holding power locks, it switches to low frequency to reduce power consumption, thereby minimizing the power consumption of running applications as much as possible.
The frequency adjustment mechanism of DFS operates based on the maximum frequency demand dictated by held power locks. Additionally, the values of :ref:`CONFIG_FREERTOS_HZ` also influence the frequency adjustments of DFS. Higher values lead to a higher frequency of task scheduling, then the system can also more quickly re-adjust the clock frequencies according to the system requirements. For further details regarding the frequency adjustment mechanism, please refer to :doc:`Power Management <../../api-reference/system/power_management>`.
The frequency adjustment mechanism of DFS operates based on the maximum frequency demand dictated by held power locks. Additionally, the values of :menuitem:`CONFIG_FREERTOS_HZ` also influence the frequency adjustments of DFS. Higher values lead to a higher frequency of task scheduling, then the system can also more quickly re-adjust the clock frequencies according to the system requirements. For further details regarding the frequency adjustment mechanism, please refer to :doc:`Power Management <../../api-reference/system/power_management>`.
The following graph illustrates the ideal current situation during the operation of the DFS mechanism.
@@ -50,7 +50,7 @@ Light-sleep Mode
Light-sleep mode is a low power mode preset in the {IDF_TARGET_NAME}. Users can switch to Light-sleep mode by calling :cpp:func:`esp_light_sleep_start` interface. Upon entering sleep, the chip will shut down unnecessary power domains and apply clock gating to modules not in use, based on the current operational states of peripherals. The {IDF_TARGET_NAME} supports various wake-up sources. Please refer to :doc:`Sleep Modes <../../api-reference/system/sleep_modes>` for more information. When the chip wakes up from Light-sleep mode, the CPU continues running from the context it was in before entering sleep, and the operational states of peripherals remain unaffected. To effectively reduce chip power consumption under Light-sleep mode, it is highly recommended that users utilize Auto Light-sleep mode described below.
Auto Light-sleep mode is a low power mode provided by ESP-IDF :doc:`Power Management <../../api-reference/system/power_management>` component that leverages FreeRTOS's Tickless IDLE feature. When the application releases all power locks and all FreeRTOS tasks are in a blocked or suspended state, the system automatically calculates the next time point when an event will wake the operating system. If this calculated time point exceeds a set duration (:ref:`CONFIG_FREERTOS_IDLE_TIME_BEFORE_SLEEP`), the ``esp_pm`` component automatically configures the timer wake-up source and enters light sleep to reduce power consumption. To enable this mode, users need to set the ``light_sleep_enable`` field to true in :cpp:type:`esp_pm_config_t` when configuring DFS. For more details, please refer to `DFS Configuration`_.
Auto Light-sleep mode is a low power mode provided by ESP-IDF :doc:`Power Management <../../api-reference/system/power_management>` component that leverages FreeRTOS's Tickless IDLE feature. When the application releases all power locks and all FreeRTOS tasks are in a blocked or suspended state, the system automatically calculates the next time point when an event will wake the operating system. If this calculated time point exceeds a set duration (:menuitem:`CONFIG_FREERTOS_IDLE_TIME_BEFORE_SLEEP`), the ``esp_pm`` component automatically configures the timer wake-up source and enters light sleep to reduce power consumption. To enable this mode, users need to set the ``light_sleep_enable`` field to true in :cpp:type:`esp_pm_config_t` when configuring DFS. For more details, please refer to `DFS Configuration`_.
.. code-block:: text
@@ -165,11 +165,11 @@ Common Configuration Options
.. only:: esp32 or esp32s3
- single/dual core operation mode (:ref:`CONFIG_FREERTOS_UNICORE`)
- single/dual core operation mode (:menuitem:`CONFIG_FREERTOS_UNICORE`)
For multi-core chips, the single core operation mode can be selected.
- RTOS Tick rate (Hz) (:ref:`CONFIG_FREERTOS_HZ`)
- RTOS Tick rate (Hz) (:menuitem:`CONFIG_FREERTOS_HZ`)
This parameter denotes the frequency of the system's periodic task scheduling.
@@ -189,7 +189,7 @@ DFS offers the following configurable options:
Specific configuration steps are as follows:
1. Enable :ref:`CONFIG_PM_ENABLE`
1. Enable :menuitem:`CONFIG_PM_ENABLE`
2. Configure ``max_freq_mhz`` and ``min_freq_mhz`` as follows:
::
@@ -211,10 +211,10 @@ Recommended Configuration
* - Configuration Name
- Configuration Status
* - Enable power management component (:ref:`CONFIG_PM_ENABLE`)
* - Enable power management component (:menuitem:`CONFIG_PM_ENABLE`)
- ON
* - RTOS Tick rate (Hz) (:ref:`CONFIG_FREERTOS_HZ`)
* - RTOS Tick rate (Hz) (:menuitem:`CONFIG_FREERTOS_HZ`)
- 1000
* - ``max_freq_mhz``
@@ -239,10 +239,10 @@ This section introduces the recommended configuration and configuration steps fo
The configuration options below are briefly introduced. For more detailed information, please click the link behind each option.
- Minimum IDLE Tick count before entering sleep state (:ref:`CONFIG_FREERTOS_IDLE_TIME_BEFORE_SLEEP`)
- Put light sleep related codes in IRAM (:ref:`CONFIG_PM_SLP_IRAM_OPT`)
- Put RTOS IDLE related codes in IRAM (:ref:`CONFIG_PM_RTOS_IDLE_OPT`)
- RTC slow clock source (:ref:`CONFIG_RTC_CLK_SRC`)
- Minimum IDLE Tick count before entering sleep state (:menuitem:`CONFIG_FREERTOS_IDLE_TIME_BEFORE_SLEEP`)
- Put light sleep related codes in IRAM (:menuitem:`CONFIG_PM_SLP_IRAM_OPT`)
- Put RTOS IDLE related codes in IRAM (:menuitem:`CONFIG_PM_RTOS_IDLE_OPT`)
- RTC slow clock source (:menuitem:`CONFIG_RTC_CLK_SRC`)
.. list-table::
:header-rows: 1
@@ -260,16 +260,16 @@ This section introduces the recommended configuration and configuration steps fo
- Low
- Small
- Disable all GPIO when chip at sleep (:ref:`CONFIG_PM_SLP_DISABLE_GPIO`)
- Disable all GPIO when chip at sleep (:menuitem:`CONFIG_PM_SLP_DISABLE_GPIO`)
.. only:: SOC_PM_SUPPORT_MAC_BB_PD
- Power down MAC and baseband (:ref:`CONFIG_ESP_PHY_MAC_BB_PD`)
- Power down MAC and baseband (:menuitem:`CONFIG_ESP_PHY_MAC_BB_PD`)
.. only:: SOC_PM_SUPPORT_CPU_PD
- Power down CPU (:ref:`CONFIG_PM_POWER_DOWN_CPU_IN_LIGHT_SLEEP`)
- Power down CPU (:menuitem:`CONFIG_PM_POWER_DOWN_CPU_IN_LIGHT_SLEEP`)
.. only:: esp32p4
@@ -277,14 +277,14 @@ This section introduces the recommended configuration and configuration steps fo
.. only:: SOC_PM_SUPPORT_TAGMEM_PD
- Power down I/D-cache tag memory (:ref:`CONFIG_PM_RESTORE_CACHE_TAGMEM_AFTER_LIGHT_SLEEP`)
- Power down I/D-cache tag memory (:menuitem:`CONFIG_PM_RESTORE_CACHE_TAGMEM_AFTER_LIGHT_SLEEP`)
.. only:: SOC_PM_SUPPORT_VDDSDIO_PD
.. only:: SOC_PM_SUPPORT_VDDSDIO_PD and not SOC_PM_FLASH_KEEP_POWER_IN_LSLP
- Power down flash in light sleep (:ref:`CONFIG_ESP_SLEEP_POWER_DOWN_FLASH`)
- Power down flash in light sleep (:menuitem:`CONFIG_ESP_SLEEP_POWER_DOWN_FLASH`)
.. only:: SOC_SPIRAM_SUPPORTED
@@ -292,7 +292,7 @@ This section introduces the recommended configuration and configuration steps fo
.. only:: SOC_PM_SUPPORT_TOP_PD
- Power down Digital Peripheral modules and all child power domains under the TOP power domain in light sleep (:ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`)
- Power down Digital Peripheral modules and all child power domains under the TOP power domain in light sleep (:menuitem:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`)
.. only:: SOC_PM_SUPPORT_RTC_PERIPH_PD
@@ -309,23 +309,23 @@ This section introduces the recommended configuration and configuration steps fo
* - Configuration Name
- Configuration Description
* - :ref:`CONFIG_PM_SLP_IRAM_OPT`
* - :menuitem:`CONFIG_PM_SLP_IRAM_OPT`
- When this option is enabled, the software flow for entering and exiting light/deep sleep is linked to on-chip RAM, which shortens the sleep transition time but consumes more on-chip RAM resources. When this option is disabled, the light/deep sleep software flow is compiled into flash memory instead, resulting in longer sleep transition time but saving on-chip RAM resources.
* - :ref:`CONFIG_PM_RTOS_IDLE_OPT`
* - :menuitem:`CONFIG_PM_RTOS_IDLE_OPT`
- In auto light sleep mode, when this option is enabled, the FreeRTOS system tick, IDLE task hook functions, and the FreeRTOS tickless idle software context are linked to on-chip RAM. Otherwise, they will be linked to flash memory.
* - :ref:`CONFIG_ESP_PERIPH_CTRL_FUNC_IN_IRAM`
* - :menuitem:`CONFIG_ESP_PERIPH_CTRL_FUNC_IN_IRAM`
- When this option is enabled, the software implementation related to peripheral clock and reset control will be linked to on-chip RAM. Otherwise, it will be linked to flash memory.
* - :ref:`CONFIG_ESP_REGI2C_CTRL_FUNC_IN_IRAM`
* - :menuitem:`CONFIG_ESP_REGI2C_CTRL_FUNC_IN_IRAM`
- When this option is enabled, the software implementation related to Analog I2C read/write access will be linked to on-chip RAM. Otherwise, it will be linked to flash memory.
Configuration Steps:
1. Configure wake-up sources (refer to :doc:`Sleep Modes <../../api-reference/system/sleep_modes>` for details)
2. Enable :ref:`CONFIG_PM_ENABLE`
3. Enable :ref:`CONFIG_FREERTOS_USE_TICKLESS_IDLE`
2. Enable :menuitem:`CONFIG_PM_ENABLE`
3. Enable :menuitem:`CONFIG_FREERTOS_USE_TICKLESS_IDLE`
4. Configure DFS parameters
5. ``light_sleep_enable`` = true, detailed as follows:
@@ -354,40 +354,40 @@ Recommended Configuration
* - Configuration Name
- Configuration Status
* - Enable power management component (:ref:`CONFIG_PM_ENABLE`)
* - Enable power management component (:menuitem:`CONFIG_PM_ENABLE`)
- ON
* - Enable RTOS Tickless IDLE mode (:ref:`CONFIG_FREERTOS_USE_TICKLESS_IDLE`)
* - Enable RTOS Tickless IDLE mode (:menuitem:`CONFIG_FREERTOS_USE_TICKLESS_IDLE`)
- ON
* - RTOS Tick rate (Hz) (:ref:`CONFIG_FREERTOS_HZ`)
* - RTOS Tick rate (Hz) (:menuitem:`CONFIG_FREERTOS_HZ`)
- 1000
* - Minimum IDLE Tick count before entering sleep mode (:ref:`CONFIG_FREERTOS_IDLE_TIME_BEFORE_SLEEP`)
* - Minimum IDLE Tick count before entering sleep mode (:menuitem:`CONFIG_FREERTOS_IDLE_TIME_BEFORE_SLEEP`)
- 3
* - Put light sleep related codes in IRAM (:ref:`CONFIG_PM_SLP_IRAM_OPT`)
* - Put light sleep related codes in IRAM (:menuitem:`CONFIG_PM_SLP_IRAM_OPT`)
- OFF
* - Put RTOS IDLE related codes in IRAM (:ref:`CONFIG_PM_RTOS_IDLE_OPT`)
* - Put RTOS IDLE related codes in IRAM (:menuitem:`CONFIG_PM_RTOS_IDLE_OPT`)
- OFF
* - RTC slow clock source (:ref:`CONFIG_RTC_CLK_SRC`)
* - RTC slow clock source (:menuitem:`CONFIG_RTC_CLK_SRC`)
- Internal 150 kHz OSC
* - Disable all GPIO when chip at sleep (:ref:`CONFIG_PM_SLP_DISABLE_GPIO`)
* - Disable all GPIO when chip at sleep (:menuitem:`CONFIG_PM_SLP_DISABLE_GPIO`)
- ON
* - Power down MAC and baseband (:ref:`CONFIG_ESP_PHY_MAC_BB_PD`)
* - Power down MAC and baseband (:menuitem:`CONFIG_ESP_PHY_MAC_BB_PD`)
- ON
* - Power down CPU (:ref:`CONFIG_PM_POWER_DOWN_CPU_IN_LIGHT_SLEEP`)
* - Power down CPU (:menuitem:`CONFIG_PM_POWER_DOWN_CPU_IN_LIGHT_SLEEP`)
- ON
* - Power down flash in light sleep (:ref:`CONFIG_ESP_SLEEP_POWER_DOWN_FLASH`)
* - Power down flash in light sleep (:menuitem:`CONFIG_ESP_SLEEP_POWER_DOWN_FLASH`)
- OFF
* - Set flash into deep power-down mode in light sleep (:ref:`CONFIG_ESP_SLEEP_SET_FLASH_DPD`)
* - Set flash into deep power-down mode in light sleep (:menuitem:`CONFIG_ESP_SLEEP_SET_FLASH_DPD`)
- OFF
* - ``max_freq_mhz``
@@ -411,37 +411,37 @@ Recommended Configuration
* - Configuration Name
- Configuration Status
* - Enable power management component (:ref:`CONFIG_PM_ENABLE`)
* - Enable power management component (:menuitem:`CONFIG_PM_ENABLE`)
- ON
* - Enable RTOS Tickless IDLE mode (:ref:`CONFIG_FREERTOS_USE_TICKLESS_IDLE`)
* - Enable RTOS Tickless IDLE mode (:menuitem:`CONFIG_FREERTOS_USE_TICKLESS_IDLE`)
- ON
* - RTOS Tick rate (Hz) (:ref:`CONFIG_FREERTOS_HZ`)
* - RTOS Tick rate (Hz) (:menuitem:`CONFIG_FREERTOS_HZ`)
- 1000
* - Minimum IDLE Tick count before entering sleep mode (:ref:`CONFIG_FREERTOS_IDLE_TIME_BEFORE_SLEEP`)
* - Minimum IDLE Tick count before entering sleep mode (:menuitem:`CONFIG_FREERTOS_IDLE_TIME_BEFORE_SLEEP`)
- 3
* - Put light sleep related codes in IRAM (:ref:`CONFIG_PM_SLP_IRAM_OPT`)
* - Put light sleep related codes in IRAM (:menuitem:`CONFIG_PM_SLP_IRAM_OPT`)
- ON
* - Put RTOS IDLE related codes in IRAM (:ref:`CONFIG_PM_RTOS_IDLE_OPT`)
* - Put RTOS IDLE related codes in IRAM (:menuitem:`CONFIG_PM_RTOS_IDLE_OPT`)
- OFF
* - RTC slow clock source (:ref:`CONFIG_RTC_CLK_SRC`)
* - RTC slow clock source (:menuitem:`CONFIG_RTC_CLK_SRC`)
- Internal 150 kHz OSC
* - Disable all GPIO when chip at sleep (:ref:`CONFIG_PM_SLP_DISABLE_GPIO`)
* - Disable all GPIO when chip at sleep (:menuitem:`CONFIG_PM_SLP_DISABLE_GPIO`)
- ON
* - Power down MAC and baseband (:ref:`CONFIG_ESP_PHY_MAC_BB_PD`)
* - Power down MAC and baseband (:menuitem:`CONFIG_ESP_PHY_MAC_BB_PD`)
- ON
* - Power down CPU (:ref:`CONFIG_PM_POWER_DOWN_CPU_IN_LIGHT_SLEEP`)
* - Power down CPU (:menuitem:`CONFIG_PM_POWER_DOWN_CPU_IN_LIGHT_SLEEP`)
- ON
* - Set flash into deep power-down mode in light sleep (:ref:`CONFIG_ESP_SLEEP_SET_FLASH_DPD`)
* - Set flash into deep power-down mode in light sleep (:menuitem:`CONFIG_ESP_SLEEP_SET_FLASH_DPD`)
- ON
* - ``max_freq_mhz``
@@ -457,7 +457,7 @@ Recommended Configuration
Configurations not mentioned in the above table are set to default.
.. note::
On {IDF_TARGET_NAME}, SPI flash need remains powered during light sleep and :ref:`CONFIG_ESP_SLEEP_POWER_DOWN_FLASH` is not available.
On {IDF_TARGET_NAME}, SPI flash need remains powered during light sleep and :menuitem:`CONFIG_ESP_SLEEP_POWER_DOWN_FLASH` is not available.
.. only:: esp32s3
@@ -468,43 +468,43 @@ Recommended Configuration
* - Configuration Name
- Configuration Status
* - Enable power management component (:ref:`CONFIG_PM_ENABLE`)
* - Enable power management component (:menuitem:`CONFIG_PM_ENABLE`)
- ON
* - Enable RTOS Tickless IDLE mode (:ref:`CONFIG_FREERTOS_USE_TICKLESS_IDLE`)
* - Enable RTOS Tickless IDLE mode (:menuitem:`CONFIG_FREERTOS_USE_TICKLESS_IDLE`)
- ON
* - RTOS Tick rate (Hz) (:ref:`CONFIG_FREERTOS_HZ`)
* - RTOS Tick rate (Hz) (:menuitem:`CONFIG_FREERTOS_HZ`)
- 1000
* - Minimum IDLE Tick count before entering sleep mode (:ref:`CONFIG_FREERTOS_IDLE_TIME_BEFORE_SLEEP`)
* - Minimum IDLE Tick count before entering sleep mode (:menuitem:`CONFIG_FREERTOS_IDLE_TIME_BEFORE_SLEEP`)
- 3
* - Put light sleep related codes in IRAM (:ref:`CONFIG_PM_SLP_IRAM_OPT`)
* - Put light sleep related codes in IRAM (:menuitem:`CONFIG_PM_SLP_IRAM_OPT`)
- OFF
* - Put RTOS IDLE related codes in IRAM (:ref:`CONFIG_PM_RTOS_IDLE_OPT`)
* - Put RTOS IDLE related codes in IRAM (:menuitem:`CONFIG_PM_RTOS_IDLE_OPT`)
- OFF
* - RTC slow clock source (:ref:`CONFIG_RTC_CLK_SRC`)
* - RTC slow clock source (:menuitem:`CONFIG_RTC_CLK_SRC`)
- Internal 150 kHz OSC
* - Disable all GPIO when chip at sleep (:ref:`CONFIG_PM_SLP_DISABLE_GPIO`)
* - Disable all GPIO when chip at sleep (:menuitem:`CONFIG_PM_SLP_DISABLE_GPIO`)
- ON
* - Power down MAC and baseband (:ref:`CONFIG_ESP_PHY_MAC_BB_PD`)
* - Power down MAC and baseband (:menuitem:`CONFIG_ESP_PHY_MAC_BB_PD`)
- ON
* - Power down CPU (:ref:`CONFIG_PM_POWER_DOWN_CPU_IN_LIGHT_SLEEP`)
* - Power down CPU (:menuitem:`CONFIG_PM_POWER_DOWN_CPU_IN_LIGHT_SLEEP`)
- ON
* - Power down I/D-cache tag memory (:ref:`CONFIG_PM_RESTORE_CACHE_TAGMEM_AFTER_LIGHT_SLEEP`)
* - Power down I/D-cache tag memory (:menuitem:`CONFIG_PM_RESTORE_CACHE_TAGMEM_AFTER_LIGHT_SLEEP`)
- ON
* - Power down flash in light sleep (:ref:`CONFIG_ESP_SLEEP_POWER_DOWN_FLASH`)
* - Power down flash in light sleep (:menuitem:`CONFIG_ESP_SLEEP_POWER_DOWN_FLASH`)
- OFF
* - Set flash into deep power-down mode in light sleep (:ref:`CONFIG_ESP_SLEEP_SET_FLASH_DPD`)
* - Set flash into deep power-down mode in light sleep (:menuitem:`CONFIG_ESP_SLEEP_SET_FLASH_DPD`)
- OFF
* - ``max_freq_mhz``
@@ -528,40 +528,40 @@ Recommended Configuration
* - Configuration Name
- Configuration Status
* - Enable power management component (:ref:`CONFIG_PM_ENABLE`)
* - Enable power management component (:menuitem:`CONFIG_PM_ENABLE`)
- ON
* - Enable RTOS Tickless IDLE mode (:ref:`CONFIG_FREERTOS_USE_TICKLESS_IDLE`)
* - Enable RTOS Tickless IDLE mode (:menuitem:`CONFIG_FREERTOS_USE_TICKLESS_IDLE`)
- ON
* - RTOS Tick rate (Hz) (:ref:`CONFIG_FREERTOS_HZ`)
* - RTOS Tick rate (Hz) (:menuitem:`CONFIG_FREERTOS_HZ`)
- 1000
* - Minimum IDLE Tick count before entering sleep mode (:ref:`CONFIG_FREERTOS_IDLE_TIME_BEFORE_SLEEP`)
* - Minimum IDLE Tick count before entering sleep mode (:menuitem:`CONFIG_FREERTOS_IDLE_TIME_BEFORE_SLEEP`)
- 3
* - Put light sleep related codes in IRAM (:ref:`CONFIG_PM_SLP_IRAM_OPT`)
* - Put light sleep related codes in IRAM (:menuitem:`CONFIG_PM_SLP_IRAM_OPT`)
- OFF
* - Put RTOS IDLE related codes in IRAM (:ref:`CONFIG_PM_RTOS_IDLE_OPT`)
* - Put RTOS IDLE related codes in IRAM (:menuitem:`CONFIG_PM_RTOS_IDLE_OPT`)
- OFF
* - RTC slow clock source (:ref:`CONFIG_RTC_CLK_SRC`)
* - RTC slow clock source (:menuitem:`CONFIG_RTC_CLK_SRC`)
- Internal 150 kHz OSC
* - Disable all GPIO when chip at sleep (:ref:`CONFIG_PM_SLP_DISABLE_GPIO`)
* - Disable all GPIO when chip at sleep (:menuitem:`CONFIG_PM_SLP_DISABLE_GPIO`)
- ON
* - Power down MAC and baseband (:ref:`CONFIG_ESP_PHY_MAC_BB_PD`)
* - Power down MAC and baseband (:menuitem:`CONFIG_ESP_PHY_MAC_BB_PD`)
- ON
* - Power down CPU (:ref:`CONFIG_PM_POWER_DOWN_CPU_IN_LIGHT_SLEEP`)
* - Power down CPU (:menuitem:`CONFIG_PM_POWER_DOWN_CPU_IN_LIGHT_SLEEP`)
- ON
* - Power down flash in light sleep (:ref:`CONFIG_ESP_SLEEP_POWER_DOWN_FLASH`)
* - Power down flash in light sleep (:menuitem:`CONFIG_ESP_SLEEP_POWER_DOWN_FLASH`)
- OFF
* - Set flash into deep power-down mode in light sleep (:ref:`CONFIG_ESP_SLEEP_SET_FLASH_DPD`)
* - Set flash into deep power-down mode in light sleep (:menuitem:`CONFIG_ESP_SLEEP_SET_FLASH_DPD`)
- OFF
* - ``max_freq_mhz``
@@ -585,28 +585,28 @@ Recommended Configuration
* - Configuration Name
- Configuration Status
* - Enable power management component (:ref:`CONFIG_PM_ENABLE`)
* - Enable power management component (:menuitem:`CONFIG_PM_ENABLE`)
- ON
* - Enable RTOS Tickless IDLE mode (:ref:`CONFIG_FREERTOS_USE_TICKLESS_IDLE`)
* - Enable RTOS Tickless IDLE mode (:menuitem:`CONFIG_FREERTOS_USE_TICKLESS_IDLE`)
- ON
* - RTOS Tick rate (Hz) (:ref:`CONFIG_FREERTOS_HZ`)
* - RTOS Tick rate (Hz) (:menuitem:`CONFIG_FREERTOS_HZ`)
- 1000
* - Minimum IDLE Tick count before entering sleep mode (:ref:`CONFIG_FREERTOS_IDLE_TIME_BEFORE_SLEEP`)
* - Minimum IDLE Tick count before entering sleep mode (:menuitem:`CONFIG_FREERTOS_IDLE_TIME_BEFORE_SLEEP`)
- 3
* - Put light sleep related codes in IRAM (:ref:`CONFIG_PM_SLP_IRAM_OPT`)
* - Put light sleep related codes in IRAM (:menuitem:`CONFIG_PM_SLP_IRAM_OPT`)
- OFF
* - Put RTOS IDLE related codes in IRAM (:ref:`CONFIG_PM_RTOS_IDLE_OPT`)
* - Put RTOS IDLE related codes in IRAM (:menuitem:`CONFIG_PM_RTOS_IDLE_OPT`)
- OFF
* - RTC slow clock source (:ref:`CONFIG_RTC_CLK_SRC`)
* - RTC slow clock source (:menuitem:`CONFIG_RTC_CLK_SRC`)
- Internal 150 kHz OSC
* - Disable all GPIO when chip at sleep (:ref:`CONFIG_PM_SLP_DISABLE_GPIO`)
* - Disable all GPIO when chip at sleep (:menuitem:`CONFIG_PM_SLP_DISABLE_GPIO`)
- ON
* - ``max_freq_mhz``
@@ -630,34 +630,34 @@ Recommended Configuration
* - Configuration Name
- Configuration Status
* - Enable power management component (:ref:`CONFIG_PM_ENABLE`)
* - Enable power management component (:menuitem:`CONFIG_PM_ENABLE`)
- ON
* - Enable RTOS Tickless IDLE mode (:ref:`CONFIG_FREERTOS_USE_TICKLESS_IDLE`)
* - Enable RTOS Tickless IDLE mode (:menuitem:`CONFIG_FREERTOS_USE_TICKLESS_IDLE`)
- ON
* - RTOS Tick rate (Hz) (:ref:`CONFIG_FREERTOS_HZ`)
* - RTOS Tick rate (Hz) (:menuitem:`CONFIG_FREERTOS_HZ`)
- 1000
* - Minimum IDLE Tick count before entering sleep mode (:ref:`CONFIG_FREERTOS_IDLE_TIME_BEFORE_SLEEP`)
* - Minimum IDLE Tick count before entering sleep mode (:menuitem:`CONFIG_FREERTOS_IDLE_TIME_BEFORE_SLEEP`)
- 3
* - Put light sleep related codes in IRAM (:ref:`CONFIG_PM_SLP_IRAM_OPT`)
* - Put light sleep related codes in IRAM (:menuitem:`CONFIG_PM_SLP_IRAM_OPT`)
- OFF
* - Put RTOS IDLE related codes in IRAM (:ref:`CONFIG_PM_RTOS_IDLE_OPT`)
* - Put RTOS IDLE related codes in IRAM (:menuitem:`CONFIG_PM_RTOS_IDLE_OPT`)
- OFF
* - RTC slow clock source (:ref:`CONFIG_RTC_CLK_SRC`)
* - RTC slow clock source (:menuitem:`CONFIG_RTC_CLK_SRC`)
- Internal 150 kHz OSC
* - Disable all GPIO when chip at sleep (:ref:`CONFIG_PM_SLP_DISABLE_GPIO`)
* - Disable all GPIO when chip at sleep (:menuitem:`CONFIG_PM_SLP_DISABLE_GPIO`)
- ON
* - Power down flash in light sleep (:ref:`CONFIG_ESP_SLEEP_POWER_DOWN_FLASH`)
* - Power down flash in light sleep (:menuitem:`CONFIG_ESP_SLEEP_POWER_DOWN_FLASH`)
- OFF
* - Set flash into deep power-down mode in light sleep (:ref:`CONFIG_ESP_SLEEP_SET_FLASH_DPD`)
* - Set flash into deep power-down mode in light sleep (:menuitem:`CONFIG_ESP_SLEEP_SET_FLASH_DPD`)
- OFF
* - ``max_freq_mhz``

16
docs/en/api-guides/low-power-mode/low-power-mode-wifi.rst
View File

@@ -274,24 +274,24 @@ Common Configuration Options
- Power consumption related:
- Max Wi-Fi TX power (dBm) (:ref:`CONFIG_ESP_PHY_MAX_WIFI_TX_POWER`)
- Max Wi-Fi TX power (dBm) (:menuitem:`CONFIG_ESP_PHY_MAX_WIFI_TX_POWER`)
- Speed optimization related:
- Wi-Fi IRAM speed optimization (:ref:`CONFIG_ESP_WIFI_IRAM_OPT`)
- Wi-Fi RX IRAM speed optimization (:ref:`CONFIG_ESP_WIFI_RX_IRAM_OPT`)
- Wi-Fi Sleep IRAM speed optimization (:ref:`CONFIG_ESP_WIFI_SLP_IRAM_OPT`)
- Wi-Fi IRAM speed optimization (:menuitem:`CONFIG_ESP_WIFI_IRAM_OPT`)
- Wi-Fi RX IRAM speed optimization (:menuitem:`CONFIG_ESP_WIFI_RX_IRAM_OPT`)
- Wi-Fi Sleep IRAM speed optimization (:menuitem:`CONFIG_ESP_WIFI_SLP_IRAM_OPT`)
- Wi-Fi Protocol related:
- Minimum active time (:ref:`CONFIG_ESP_WIFI_SLP_DEFAULT_MIN_ACTIVE_TIME`)
- Minimum active time (:menuitem:`CONFIG_ESP_WIFI_SLP_DEFAULT_MIN_ACTIVE_TIME`)
- Maximum keep alive time (:ref:`CONFIG_ESP_WIFI_SLP_DEFAULT_MAX_ACTIVE_TIME`)
- Maximum keep alive time (:menuitem:`CONFIG_ESP_WIFI_SLP_DEFAULT_MAX_ACTIVE_TIME`)
- Send gratuitous ARP periodically (:ref:`CONFIG_LWIP_ESP_GRATUITOUS_ARP`)
- Send gratuitous ARP periodically (:menuitem:`CONFIG_LWIP_ESP_GRATUITOUS_ARP`)
- Wi-Fi sleep optimize when beacon lost (:ref:`CONFIG_ESP_WIFI_SLP_BEACON_LOST_OPT`)
- Wi-Fi sleep optimize when beacon lost (:menuitem:`CONFIG_ESP_WIFI_SLP_BEACON_LOST_OPT`)
.. _Modem-sleep Mode Configuration:

72
docs/en/api-guides/lwip.rst
View File

@@ -20,7 +20,7 @@ Adapted APIs
.. warning::
When using any lwIP API other than the `BSD Sockets API`_, please make sure that the API is thread-safe. To check if a given API call is thread-safe, enable the :ref:`CONFIG_LWIP_CHECK_THREAD_SAFETY` configuration option and run the application. This enables lwIP to assert the correct access of the TCP/IP core functionality. If the API is not accessed or locked properly from the appropriate `lwIP FreeRTOS Task`_, the execution will be aborted. The general recommendation is to use the :doc:`/api-reference/network/esp_netif` component to interact with lwIP.
When using any lwIP API other than the `BSD Sockets API`_, please make sure that the API is thread-safe. To check if a given API call is thread-safe, enable the :menuitem:`CONFIG_LWIP_CHECK_THREAD_SAFETY` configuration option and run the application. This enables lwIP to assert the correct access of the TCP/IP core functionality. If the API is not accessed or locked properly from the appropriate `lwIP FreeRTOS Task`_, the execution will be aborted. The general recommendation is to use the :doc:`/api-reference/network/esp_netif` component to interact with lwIP.
Some common lwIP app APIs are supported indirectly by ESP-IDF:
@@ -37,7 +37,7 @@ Some common lwIP app APIs are supported indirectly by ESP-IDF:
- ICMP Ping is supported using a variation on the lwIP ping API, see :doc:`/api-reference/protocols/icmp_echo`.
- ICMPv6 Ping, supported by lwIP's ICMPv6 Echo API, is used to test IPv6 network connectivity. For more information, see :example:`protocols/sockets/icmpv6_ping`. This example demonstrates how to use the network interface to discover an IPv6 address, create a raw ICMPv6 socket, send an ICMPv6 Echo Request to a destination IPv6 address, and wait for an Echo Reply from the target.
- NetBIOS lookup is available using the standard lwIP API. :example:`protocols/http_server/restful_server` has the option to demonstrate using NetBIOS to look up a host on the LAN.
- mDNS uses a different implementation to the lwIP default mDNS, see :doc:`/api-reference/protocols/mdns`. But lwIP can look up mDNS hosts using standard APIs such as ``gethostbyname()`` and the convention ``hostname.local``, provided the :ref:`CONFIG_LWIP_DNS_SUPPORT_MDNS_QUERIES` setting is enabled.
- mDNS uses a different implementation to the lwIP default mDNS, see :doc:`/api-reference/protocols/mdns`. But lwIP can look up mDNS hosts using standard APIs such as ``gethostbyname()`` and the convention ``hostname.local``, provided the :menuitem:`CONFIG_LWIP_DNS_SUPPORT_MDNS_QUERIES` setting is enabled.
- The PPP implementation in lwIP can be used to create PPPoS (PPP over serial) interface in ESP-IDF. Please refer to the documentation of the :doc:`/api-reference/network/esp_netif` component to create and configure a PPP network interface, by means of the ``ESP_NETIF_DEFAULT_PPP()`` macro defined in :component_file:`esp_netif/include/esp_netif_defaults.h`. Additional runtime settings are provided via :component_file:`esp_netif/include/esp_netif_ppp.h`. PPPoS interfaces are typically used to interact with NBIoT/GSM/LTE modems. More application-level friendly API is supported by the `esp_modem <https://components.espressif.com/component/espressif/esp_modem>`_ library, which uses this PPP lwIP module behind the scenes.
DHCP Address Conflict Detection
@@ -45,7 +45,7 @@ DHCP Address Conflict Detection
Usually, DHCP servers verify that a selected IPv4 address is unique on the network before offering it. However, some, including the DHCP server in ESP-IDF, do not perform verification by default to simplify operation and speed up address assignment.
If you want to avoid any possible IP address conflicts and connectivity issues, the ESP-IDF DHCP client provides several options to validate the offered IPv4 address before binding it (see :ref:`CONFIG_LWIP_DHCP_CHECKS_OFFERED_ADDRESS`):
If you want to avoid any possible IP address conflicts and connectivity issues, the ESP-IDF DHCP client provides several options to validate the offered IPv4 address before binding it (see :menuitem:`CONFIG_LWIP_DHCP_CHECKS_OFFERED_ADDRESS`):
- **Simple ARP check, default option** (``CONFIG_LWIP_DHCP_DOES_ARP_CHECK``): Sends two ARP probes and only declines the offer if a reply for the offered IP comes from a different MAC address than the interface MAC. This is fast (about 1–2 seconds) and avoids false conflicts on networks where the AP echoes the client's MAC in ARP replies. **Use this option if you encounter DHCP DECLINE loops where the ARP reply for the offered IP advertises the interface's own MAC.**
- **Address Conflict Detection (ACD)** (``CONFIG_LWIP_DHCP_DOES_ACD_CHECK``): Uses upstream lwIP ACD per RFC 5227 to probe/announce addresses. Some access points respond to ARP probes with the client's own MAC for the offered IP; upstream behavior treats any matching sender IP during PROBING as a conflict, which can cause repeated DHCP DECLINEs on such networks. **Use this option only if you need full RFC 5227 compliance and are aware of the potential issues with certain access points.**
@@ -242,11 +242,11 @@ Common Options
Used with level argument ``SOL_SOCKET``.
- ``SO_REUSEADDR``: available if :ref:`CONFIG_LWIP_SO_REUSE` is set, whose behavior can be customized by setting :ref:`CONFIG_LWIP_SO_REUSE_RXTOALL`
- ``SO_REUSEADDR``: available if :menuitem:`CONFIG_LWIP_SO_REUSE` is set, whose behavior can be customized by setting :menuitem:`CONFIG_LWIP_SO_REUSE_RXTOALL`
- ``SO_KEEPALIVE``
- ``SO_BROADCAST``
- ``SO_ACCEPTCONN``
- ``SO_RCVBUF``: available if :ref:`CONFIG_LWIP_SO_RCVBUF` is set
- ``SO_RCVBUF``: available if :menuitem:`CONFIG_LWIP_SO_RCVBUF` is set
- ``SO_SNDTIMEO`` / ``SO_RCVTIMEO``
- ``SO_ERROR``: only used with ``select()``, see `Socket Error Handling`_
- ``SO_TYPE``
@@ -259,7 +259,7 @@ Used with level argument ``IPPROTO_IP``.
- ``IP_TOS``
- ``IP_TTL``
- ``IP_PKTINFO``: available if :ref:`CONFIG_LWIP_NETBUF_RECVINFO` is set
- ``IP_PKTINFO``: available if :menuitem:`CONFIG_LWIP_NETBUF_RECVINFO` is set
For multicast UDP sockets:
@@ -341,9 +341,9 @@ lwIP creates a dedicated TCP/IP FreeRTOS task to handle socket API requests from
A number of configuration items are available to modify the task and the queues (mailboxes) used to send data to/from the TCP/IP task:
- :ref:`CONFIG_LWIP_TCPIP_RECVMBOX_SIZE`
- :ref:`CONFIG_LWIP_TCPIP_TASK_STACK_SIZE`
- :ref:`CONFIG_LWIP_TCPIP_TASK_AFFINITY`
- :menuitem:`CONFIG_LWIP_TCPIP_RECVMBOX_SIZE`
- :menuitem:`CONFIG_LWIP_TCPIP_TASK_STACK_SIZE`
- :menuitem:`CONFIG_LWIP_TCPIP_TASK_AFFINITY`
IPv6 Support
------------
@@ -366,7 +366,7 @@ Stateless Autoconfiguration Process
To enable address autoconfiguration using the Router Advertisement protocol, please enable:
- :ref:`CONFIG_LWIP_IPV6_AUTOCONFIG`
- :menuitem:`CONFIG_LWIP_IPV6_AUTOCONFIG`
This configuration option enables IPv6 autoconfiguration for all network interfaces, which differs from the upstream lwIP behavior, where the autoconfiguration needs to be explicitly enabled for each ``netif`` with ``netif->ip6_autoconfig_enabled=1``.
@@ -377,9 +377,9 @@ DHCPv6
DHCPv6 in lwIP is very simple and supports only stateless configuration. It could be enabled using:
- :ref:`CONFIG_LWIP_IPV6_DHCP6`
- :menuitem:`CONFIG_LWIP_IPV6_DHCP6`
Since the DHCPv6 works only in its stateless configuration, the :ref:`lwip-ivp6-autoconfig` has to be enabled as well via :ref:`CONFIG_LWIP_IPV6_AUTOCONFIG`.
Since the DHCPv6 works only in its stateless configuration, the :ref:`lwip-ivp6-autoconfig` has to be enabled as well via :menuitem:`CONFIG_LWIP_IPV6_AUTOCONFIG`.
Moreover, the DHCPv6 needs to be explicitly enabled from the application code using:
@@ -394,7 +394,7 @@ In order to autoconfigure DNS server(s), especially in IPv6-only networks, we ha
- Recursive Domain Name System (DNS): this belongs to the Neighbor Discovery Protocol (NDP) and uses :ref:`lwip-ivp6-autoconfig`.
The number of servers must be set :ref:`CONFIG_LWIP_IPV6_RDNSS_MAX_DNS_SERVERS`, this option is disabled by default, i.e., set to 0.
The number of servers must be set :menuitem:`CONFIG_LWIP_IPV6_RDNSS_MAX_DNS_SERVERS`, this option is disabled by default, i.e., set to 0.
- DHCPv6 stateless configuration, uses :ref:`lwip-ivp6-dhcp6` to configure DNS servers. Note that this configuration assumes IPv6 Router Advertisement Flags (RFC-5175) to be set to
@@ -423,7 +423,7 @@ lwIP IGMP and MLD6 feature both initialize a timer in order to trigger timeout e
The default lwIP implementation is to have these timers enabled all the time, even if no timeout events are active. This increases CPU usage and power consumption when using automatic Light-sleep mode. ``ESP-lwIP`` default behavior is to set each timer ``on demand``, so it is only enabled when an event is pending.
To return to the default lwIP behavior, which is always-on timers, disable :ref:`CONFIG_LWIP_TIMERS_ONDEMAND`.
To return to the default lwIP behavior, which is always-on timers, disable :menuitem:`CONFIG_LWIP_TIMERS_ONDEMAND`.
lwIP Timers API
+++++++++++++++
@@ -468,7 +468,7 @@ ESP-IDF port layer provides a default hook file, which is included in the lwIP b
**DHCP Extra Option Hook**
ESP-IDF allows applications to define a hook for handling extra DHCP options. This can be useful for implementing custom DHCP-based behaviors, such as retrieving specific vendor options. To enable this feature, configure :ref:`CONFIG_LWIP_HOOK_DHCP_EXTRA_OPTION` either to **Default** (``weak`` implementation is provided which could be replaced by custom implementation) or **Custom** (you will have to implement the hook and define its link dependency to lwip)
ESP-IDF allows applications to define a hook for handling extra DHCP options. This can be useful for implementing custom DHCP-based behaviors, such as retrieving specific vendor options. To enable this feature, configure :menuitem:`CONFIG_LWIP_HOOK_DHCP_EXTRA_OPTION` either to **Default** (``weak`` implementation is provided which could be replaced by custom implementation) or **Custom** (you will have to implement the hook and define its link dependency to lwip)
**Example Usage**
@@ -493,13 +493,13 @@ An application can define the following function to handle a specific DHCP optio
ESP-IDF provides additional lwIP hooks that can be overridden. These include:
- TCP ISN Hook (:ref:`CONFIG_LWIP_HOOK_TCP_ISN`): Allows custom randomization of TCP Initial Sequence Numbers (ESP-IDF provided implementation is the default option, set to *Custom* to provide custom implementation or *None* to use lwIP implementation).
- IPv6 Route Hook (:ref:`CONFIG_LWIP_HOOK_IP6_ROUTE`): Enables custom route selection for IPv6 packets (No hook by default, use *Default* or *Custom* to override).
- IPv6 Get Gateway Hook (:ref:`CONFIG_LWIP_HOOK_ND6_GET_GW`): Enables defining a custom gateway selection logic (No hook by default, use *Default* or *Custom* to override).
- IPv6 Source Address Selection Hook (:ref:`CONFIG_LWIP_HOOK_IP6_SELECT_SRC_ADDR`): Allows customization of source address selection (No hook by default, use *Default* or *Custom* to override).
- Netconn External Resolve Hook (:ref:`CONFIG_LWIP_HOOK_NETCONN_EXTERNAL_RESOLVE`): Allows overriding the DNS resolution logic for network connections (No hook by default, use *Default* or *Custom* to override).
- DNS External Resolve Hook (:ref:`CONFIG_LWIP_HOOK_DNS_EXTERNAL_RESOLVE`): Provides a hook for custom DNS resolution logic with callbacks (No hook by default, but could be selected by an external component to prefer the custom option; use *Default* or *Custom* to override).
- IPv6 Packet Input Hook (:ref:`CONFIG_LWIP_HOOK_IP6_INPUT`): Provides filtering or modification of incoming IPv6 packets (ESP-IDF provided ``weak`` implementation is the default option; use *Custom* or provide a strong definition to override the *Default* option; choose *None* to disable IPv6 packet input filtering)
- TCP ISN Hook (:menuitem:`CONFIG_LWIP_HOOK_TCP_ISN`): Allows custom randomization of TCP Initial Sequence Numbers (ESP-IDF provided implementation is the default option, set to *Custom* to provide custom implementation or *None* to use lwIP implementation).
- IPv6 Route Hook (:menuitem:`CONFIG_LWIP_HOOK_IP6_ROUTE`): Enables custom route selection for IPv6 packets (No hook by default, use *Default* or *Custom* to override).
- IPv6 Get Gateway Hook (:menuitem:`CONFIG_LWIP_HOOK_ND6_GET_GW`): Enables defining a custom gateway selection logic (No hook by default, use *Default* or *Custom* to override).
- IPv6 Source Address Selection Hook (:menuitem:`CONFIG_LWIP_HOOK_IP6_SELECT_SRC_ADDR`): Allows customization of source address selection (No hook by default, use *Default* or *Custom* to override).
- Netconn External Resolve Hook (:menuitem:`CONFIG_LWIP_HOOK_NETCONN_EXTERNAL_RESOLVE`): Allows overriding the DNS resolution logic for network connections (No hook by default, use *Default* or *Custom* to override).
- DNS External Resolve Hook (:menuitem:`CONFIG_LWIP_HOOK_DNS_EXTERNAL_RESOLVE`): Provides a hook for custom DNS resolution logic with callbacks (No hook by default, but could be selected by an external component to prefer the custom option; use *Default* or *Custom* to override).
- IPv6 Packet Input Hook (:menuitem:`CONFIG_LWIP_HOOK_IP6_INPUT`): Provides filtering or modification of incoming IPv6 packets (ESP-IDF provided ``weak`` implementation is the default option; use *Custom* or provide a strong definition to override the *Default* option; choose *None* to disable IPv6 packet input filtering)
Each of these hooks can be configured in menuconfig, allowing selection of default, custom, or no implementation.
@@ -533,8 +533,8 @@ Alternatively, you can define your function-like macro in a header file which wi
Network Interface Callbacks
---------------------------
- Status Callback (:ref:`CONFIG_LWIP_NETIF_STATUS_CALLBACK`): Enables `netif_set_status_callback()` to notify when an interface comes up/down and when IPv4/IPv6 addresses change.
- Link Callback (:ref:`CONFIG_LWIP_NETIF_LINK_CALLBACK`): Enables `netif_set_link_callback()` to notify when the physical link goes up/down. The callback is triggered by `netif_set_link_up()` / `netif_set_link_down()` calls in drivers or virtual interfaces. Can be used alongside `LWIP_NETIF_EXT_STATUS_CALLBACK` for richer eventing.
- Status Callback (:menuitem:`CONFIG_LWIP_NETIF_STATUS_CALLBACK`): Enables `netif_set_status_callback()` to notify when an interface comes up/down and when IPv4/IPv6 addresses change.
- Link Callback (:menuitem:`CONFIG_LWIP_NETIF_LINK_CALLBACK`): Enables `netif_set_link_callback()` to notify when the physical link goes up/down. The callback is triggered by `netif_set_link_up()` / `netif_set_link_down()` calls in drivers or virtual interfaces. Can be used alongside `LWIP_NETIF_EXT_STATUS_CALLBACK` for richer eventing.
.. _lwip-limitations:
@@ -549,17 +549,17 @@ The number of IP addresses returned by network database APIs such as ``getaddrin
In the implementation of ``getaddrinfo()``, the canonical name is not available. Therefore, the ``ai_canonname`` field of the first returned ``addrinfo`` structure will always refer to the ``nodename`` argument or a string with the same contents.
The ``getaddrinfo()`` system call in lwIP within ESP-IDF has a limitation when using ``AF_UNSPEC``, as it defaults to returning only an IPv4 address in dual stack mode. This can cause issues in IPv6-only networks. To handle this, a workaround involves making two sequential calls to ``getaddrinfo()``: the first with ``AF_INET`` to query for IPv4 addresses, and the second with ``AF_INET6`` to retrieve IPv6 addresses. To provide a more robust solution, the custom ``esp_getaddrinfo()`` function has been added to the lwIP port layer to handle both IPv4 and IPv6 addresses when ``AF_UNSPEC`` is used. The :ref:`CONFIG_LWIP_USE_ESP_GETADDRINFO` option, available when both IPv4 and IPv6 are enabled, controls whether ``esp_getaddrinfo()`` or ``getaddrinfo()`` is used. It is disabled by default.
The ``getaddrinfo()`` system call in lwIP within ESP-IDF has a limitation when using ``AF_UNSPEC``, as it defaults to returning only an IPv4 address in dual stack mode. This can cause issues in IPv6-only networks. To handle this, a workaround involves making two sequential calls to ``getaddrinfo()``: the first with ``AF_INET`` to query for IPv4 addresses, and the second with ``AF_INET6`` to retrieve IPv6 addresses. To provide a more robust solution, the custom ``esp_getaddrinfo()`` function has been added to the lwIP port layer to handle both IPv4 and IPv6 addresses when ``AF_UNSPEC`` is used. The :menuitem:`CONFIG_LWIP_USE_ESP_GETADDRINFO` option, available when both IPv4 and IPv6 are enabled, controls whether ``esp_getaddrinfo()`` or ``getaddrinfo()`` is used. It is disabled by default.
Calling ``send()`` or ``sendto()`` repeatedly on a UDP socket may eventually fail with ``errno`` equal to ``ENOMEM``. This failure occurs due to the limitations of buffer sizes in the lower-layer network interface drivers. If all driver transmit buffers are full, the UDP transmission will fail. For applications that transmit a high volume of UDP datagrams and aim to avoid any dropped datagrams by the sender, it is advisable to implement error code checking and employ a retransmission mechanism with a short delay.
.. only:: esp32
Increasing the number of TX buffers in the :ref:`Wi-Fi <CONFIG_ESP_WIFI_TX_BUFFER>` or :ref:`Ethernet <CONFIG_ETH_DMA_TX_BUFFER_NUM>` project configuration as applicable may also help.
Increasing the number of TX buffers in the :menuitem:`Wi-Fi <CONFIG_ESP_WIFI_TX_BUFFER>` or :menuitem:`Ethernet <CONFIG_ETH_DMA_TX_BUFFER_NUM>` project configuration as applicable may also help.
.. only:: not esp32 and SOC_WIFI_SUPPORTED
Increasing the number of TX buffers in the :ref:`Wi-Fi <CONFIG_ESP_WIFI_TX_BUFFER>` project configuration may also help.
Increasing the number of TX buffers in the :menuitem:`Wi-Fi <CONFIG_ESP_WIFI_TX_BUFFER>` project configuration may also help.
.. _lwip-performance:
@@ -577,11 +577,11 @@ Espressif tests ESP-IDF TCP/IP throughput using the iperf test application: http
Suggest applying changes a few at a time and checking the performance each time with a particular application workload.
- If a lot of tasks are competing for CPU time on the system, consider that the lwIP task has configurable CPU affinity (:ref:`CONFIG_LWIP_TCPIP_TASK_AFFINITY`) and runs at fixed priority (18, ``ESP_TASK_TCPIP_PRIO``). To optimize CPU utilization, consider assigning competing tasks to different cores or adjusting their priorities to lower values. For additional details on built-in task priorities, please refer to :ref:`built-in-task-priorities`.
- If a lot of tasks are competing for CPU time on the system, consider that the lwIP task has configurable CPU affinity (:menuitem:`CONFIG_LWIP_TCPIP_TASK_AFFINITY`) and runs at fixed priority (18, ``ESP_TASK_TCPIP_PRIO``). To optimize CPU utilization, consider assigning competing tasks to different cores or adjusting their priorities to lower values. For additional details on built-in task priorities, please refer to :ref:`built-in-task-priorities`.
- If using ``select()`` function with socket arguments only, disabling :ref:`CONFIG_VFS_SUPPORT_SELECT` will make ``select()`` calls faster.
- If using ``select()`` function with socket arguments only, disabling :menuitem:`CONFIG_VFS_SUPPORT_SELECT` will make ``select()`` calls faster.
- If there is enough free IRAM, select :ref:`CONFIG_LWIP_IRAM_OPTIMIZATION` and :ref:`CONFIG_LWIP_EXTRA_IRAM_OPTIMIZATION` to improve TX/RX throughput.
- If there is enough free IRAM, select :menuitem:`CONFIG_LWIP_IRAM_OPTIMIZATION` and :menuitem:`CONFIG_LWIP_EXTRA_IRAM_OPTIMIZATION` to improve TX/RX throughput.
.. only:: SOC_WIFI_SUPPORTED
@@ -601,12 +601,12 @@ Minimum RAM Usage
Most lwIP RAM usage is on-demand, as RAM is allocated from the heap as needed. Therefore, changing lwIP settings to reduce RAM usage may not change RAM usage at idle, but can change it at peak.
- Reducing :ref:`CONFIG_LWIP_MAX_SOCKETS` reduces the maximum number of sockets in the system. This also causes TCP sockets in the ``WAIT_CLOSE`` state to be closed and recycled more rapidly when needed to open a new socket, further reducing peak RAM usage.
- Reducing :ref:`CONFIG_LWIP_TCPIP_RECVMBOX_SIZE`, :ref:`CONFIG_LWIP_TCP_RECVMBOX_SIZE` and :ref:`CONFIG_LWIP_UDP_RECVMBOX_SIZE` reduce RAM usage at the expense of throughput, depending on usage.
- Reducing :ref:`CONFIG_LWIP_TCP_ACCEPTMBOX_SIZE` reduce RAM usage by limiting concurrent accepted connections.
- Reducing :ref:`CONFIG_LWIP_TCP_MSL` and :ref:`CONFIG_LWIP_TCP_FIN_WAIT_TIMEOUT` reduces the maximum segment lifetime in the system. This also causes TCP sockets in the ``TIME_WAIT`` and ``FIN_WAIT_2`` states to be closed and recycled more rapidly.
- Disabling :ref:`CONFIG_LWIP_IPV6` can save about 39 KB for firmware size and 2 KB RAM when the system is powered up and 7 KB RAM when the TCP/IP stack is running. If there is no requirement for supporting IPV6, it can be disabled to save flash and RAM footprint.
- Disabling :ref:`CONFIG_LWIP_IPV4` can save about 26 KB of firmware size and 600 B RAM on power up and 6 KB RAM when the TCP/IP stack is running. If the local network supports IPv6-only configuration, IPv4 can be disabled to save flash and RAM footprint.
- Reducing :menuitem:`CONFIG_LWIP_MAX_SOCKETS` reduces the maximum number of sockets in the system. This also causes TCP sockets in the ``WAIT_CLOSE`` state to be closed and recycled more rapidly when needed to open a new socket, further reducing peak RAM usage.
- Reducing :menuitem:`CONFIG_LWIP_TCPIP_RECVMBOX_SIZE`, :menuitem:`CONFIG_LWIP_TCP_RECVMBOX_SIZE` and :menuitem:`CONFIG_LWIP_UDP_RECVMBOX_SIZE` reduce RAM usage at the expense of throughput, depending on usage.
- Reducing :menuitem:`CONFIG_LWIP_TCP_ACCEPTMBOX_SIZE` reduce RAM usage by limiting concurrent accepted connections.
- Reducing :menuitem:`CONFIG_LWIP_TCP_MSL` and :menuitem:`CONFIG_LWIP_TCP_FIN_WAIT_TIMEOUT` reduces the maximum segment lifetime in the system. This also causes TCP sockets in the ``TIME_WAIT`` and ``FIN_WAIT_2`` states to be closed and recycled more rapidly.
- Disabling :menuitem:`CONFIG_LWIP_IPV6` can save about 39 KB for firmware size and 2 KB RAM when the system is powered up and 7 KB RAM when the TCP/IP stack is running. If there is no requirement for supporting IPV6, it can be disabled to save flash and RAM footprint.
- Disabling :menuitem:`CONFIG_LWIP_IPV4` can save about 26 KB of firmware size and 600 B RAM on power up and 6 KB RAM when the TCP/IP stack is running. If the local network supports IPv6-only configuration, IPv4 can be disabled to save flash and RAM footprint.
.. only:: SOC_WIFI_SUPPORTED

8
docs/en/api-guides/memory-types.rst
View File

@@ -18,7 +18,7 @@ Non-constant static data (.data) and zero-initialized data (.bss) is placed by t
.. only:: SOC_SPIRAM_SUPPORTED
By applying the ``EXT_RAM_BSS_ATTR`` macro, zero-initialized data can also be placed into external RAM. To use this macro, the :ref:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY` needs to be enabled. See :ref:`external_ram_config_bss`.
By applying the ``EXT_RAM_BSS_ATTR`` macro, zero-initialized data can also be placed into external RAM. To use this macro, the :menuitem:`CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY` needs to be enabled. See :ref:`external_ram_config_bss`.
.. only:: esp32
@@ -44,7 +44,7 @@ The macro ``__NOINIT_ATTR`` can be used as attribute to place data into ``.noini
.. only:: SOC_SPIRAM_SUPPORTED
By applying the ``EXT_RAM_NOINIT_ATTR`` macro, non-initialized value could also be placed in external RAM. To do this, the :ref:`CONFIG_SPIRAM_ALLOW_NOINIT_SEG_EXTERNAL_MEMORY` needs to be enabled. See :ref:`external_ram_config_noinit`. If the :ref:`CONFIG_SPIRAM_ALLOW_NOINIT_SEG_EXTERNAL_MEMORY` is not enabled, ``EXT_RAM_NOINIT_ATTR`` will behave just as ``__NOINIT_ATTR``, it will make data to be placed into ``.noinit`` segment in internal RAM.
By applying the ``EXT_RAM_NOINIT_ATTR`` macro, non-initialized value could also be placed in external RAM. To do this, the :menuitem:`CONFIG_SPIRAM_ALLOW_NOINIT_SEG_EXTERNAL_MEMORY` needs to be enabled. See :ref:`external_ram_config_noinit`. If the :menuitem:`CONFIG_SPIRAM_ALLOW_NOINIT_SEG_EXTERNAL_MEMORY` is not enabled, ``EXT_RAM_NOINIT_ATTR`` will behave just as ``__NOINIT_ATTR``, it will make data to be placed into ``.noinit`` segment in internal RAM.
Example::
@@ -178,13 +178,13 @@ The ``DRAM_ATTR`` attribute can be used to force constants from DROM into the :r
.. only:: esp32
In single core mode (:ref:`CONFIG_FREERTOS_UNICORE`), remaining RTC FAST memory is added to the heap, unless the option :ref:`CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEAP` is disabled. This memory can be used interchangeably with :ref:`DRAM`, but is slightly slower to access and not DMA-capable.
In single core mode (:menuitem:`CONFIG_FREERTOS_UNICORE`), remaining RTC FAST memory is added to the heap, unless the option :menuitem:`CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEAP` is disabled. This memory can be used interchangeably with :ref:`DRAM`, but is slightly slower to access and not DMA-capable.
This option is not available in dual core mode, because on {IDF_TARGET_NAME}, RTC FAST memory can only be accessed by the PRO CPU.
.. only:: not esp32
Remaining RTC FAST memory is added to the heap unless the option :ref:`CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEAP` is disabled. This memory can be used interchangeably with :ref:`DRAM`, but is slightly slower to access.
Remaining RTC FAST memory is added to the heap unless the option :menuitem:`CONFIG_ESP_SYSTEM_ALLOW_RTC_FAST_MEM_AS_HEAP` is disabled. This memory can be used interchangeably with :ref:`DRAM`, but is slightly slower to access.
.. only:: SOC_MEM_SPM_SUPPORTED

22
docs/en/api-guides/partition-tables.rst
View File

@@ -6,13 +6,13 @@ Partition Tables
Overview
--------
A single {IDF_TARGET_NAME}'s flash can contain multiple apps, as well as many different kinds of data (calibration data, filesystems, parameter storage, etc). For this reason a partition table is flashed to (:ref:`default offset <CONFIG_PARTITION_TABLE_OFFSET>`) 0x8000 in the flash.
A single {IDF_TARGET_NAME}'s flash can contain multiple apps, as well as many different kinds of data (calibration data, filesystems, parameter storage, etc). For this reason a partition table is flashed to (:menuitem:`default offset <CONFIG_PARTITION_TABLE_OFFSET>`) 0x8000 in the flash.
The partition table length is 0xC00 bytes, as we allow a maximum of 95 entries. An MD5 checksum, used for checking the integrity of the partition table at runtime, is appended after the table data. Thus, the partition table occupies an entire flash sector, which size is 0x1000 (4 KB). As a result, any partition following it must be at least located at (:ref:`default offset <CONFIG_PARTITION_TABLE_OFFSET>`) + 0x1000.
The partition table length is 0xC00 bytes, as we allow a maximum of 95 entries. An MD5 checksum, used for checking the integrity of the partition table at runtime, is appended after the table data. Thus, the partition table occupies an entire flash sector, which size is 0x1000 (4 KB). As a result, any partition following it must be at least located at (:menuitem:`default offset <CONFIG_PARTITION_TABLE_OFFSET>`) + 0x1000.
Each entry in the partition table has a name (label), type (app, data, or something else), subtype and the offset in flash where the partition is loaded.
The simplest way to use the partition table is to open the project configuration menu (``idf.py menuconfig``) and choose one of the simple predefined partition tables under :ref:`CONFIG_PARTITION_TABLE_TYPE`:
The simplest way to use the partition table is to open the project configuration menu (``idf.py menuconfig``) and choose one of the simple predefined partition tables under :menuitem:`CONFIG_PARTITION_TABLE_TYPE`:
* "Single factory app, no OTA"
* "Factory app, two OTA definitions"
@@ -71,7 +71,7 @@ The CSV format is the same format as printed in the summaries shown above. Howev
* Whitespace between fields is ignored, and so is any line starting with ``#`` (comments).
* Each non-comment line in the CSV file is a partition definition.
* If you change the value of :ref:`CONFIG_PARTITION_TABLE_OFFSET`, you should update any fixed ``Offset`` in your CSV file to avoid overlaps with the new partition table location. Alternatively, leaving the ``Offset`` field blank allows the ``gen_esp32part.py`` tool to automatically calculate the correct offset based on the current partition table offset and alignment requirements.
* If you change the value of :menuitem:`CONFIG_PARTITION_TABLE_OFFSET`, you should update any fixed ``Offset`` in your CSV file to avoid overlaps with the new partition table location. Alternatively, leaving the ``Offset`` field blank allows the ``gen_esp32part.py`` tool to automatically calculate the correct offset based on the current partition table offset and alignment requirements.
Here is an example of a CSV partition table that includes bootloader and partition table partitions:
@@ -86,7 +86,7 @@ Here is an example of a CSV partition table that includes bootloader and partiti
factory, app, factory, , 1M,
recoveryBloader, bootloader, recovery, N/A, N/A,
The ``gen_esp32part.py`` tool will replace each ``N/A`` with appropriate values based on the selected Kconfig options: {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} for the bootloader offset and :ref:`CONFIG_PARTITION_TABLE_OFFSET` for the partition table offset.
The ``gen_esp32part.py`` tool will replace each ``N/A`` with appropriate values based on the selected Kconfig options: {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH} for the bootloader offset and :menuitem:`CONFIG_PARTITION_TABLE_OFFSET` for the partition table offset.
Name Field
~~~~~~~~~~
@@ -117,7 +117,7 @@ The bootloader ignores any partition types other than ``app`` (0x00) and ``data`
SubType
~~~~~~~
{IDF_TARGET_ESP_PHY_REF:default = ":ref:`CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION`", esp32p4, esp32c5, esp32c61="NOT UPDATED YET"}
{IDF_TARGET_ESP_PHY_REF:default = ":menuitem:`CONFIG_ESP_PHY_INIT_DATA_IN_PARTITION`", esp32p4, esp32c5, esp32c61="NOT UPDATED YET"}
The 8-bit SubType field is specific to a given partition type. ESP-IDF currently only specifies the meaning of the subtype field for ``app`` and ``data`` partition types.
@@ -149,11 +149,11 @@ See enum :cpp:type:`esp_partition_subtype_t` for the full list of subtypes defin
- ``ota`` (0x01). This is a temporary bootloader partition used by the bootloader OTA update functionality to download a new image. The tool ignores the size for this subtype, allowing you to leave it blank or use ``N/A``. You can only specify an offset, or leave it blank to have the tool calculate it based on the offsets of previously used partitions.
- ``recovery`` (0x02). This is the recovery bootloader partition used for safely performing OTA updates to the bootloader. The ``gen_esp32part.py`` tool automatically determines the address and size for this partition, so you can leave these fields blank or use ``N/A`` as a placeholder. The address must match an eFuse field, which is defined through a Kconfig option. If the normal bootloader loading path fails, the first stage (ROM) bootloader will attempt to load the recovery partition at the address specified by the eFuse field.
The size of the bootloader type is calculated by the ``gen_esp32part.py`` tool based on the specified ``--offset`` (the partition table offset) and ``--primary-partition-offset`` arguments. Specifically, the bootloader size is defined as (:ref:`CONFIG_PARTITION_TABLE_OFFSET` - {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH}). This calculated size applies to all subtypes of the bootloader.
The size of the bootloader type is calculated by the ``gen_esp32part.py`` tool based on the specified ``--offset`` (the partition table offset) and ``--primary-partition-offset`` arguments. Specifically, the bootloader size is defined as (:menuitem:`CONFIG_PARTITION_TABLE_OFFSET` - {IDF_TARGET_CONFIG_BOOTLOADER_OFFSET_IN_FLASH}). This calculated size applies to all subtypes of the bootloader.
* When type is ``partition_table``, the SubType field can be specified as:
- ``primary`` (0x00). This is the primary partition table, located at the :ref:`CONFIG_PARTITION_TABLE_OFFSET` address in flash memory. The tool automatically determines the appropriate size and offset for this subtype, so any size or offset specified for this subtype will be ignored. You can either leave these fields blank or use ``N/A`` as a placeholder.
- ``primary`` (0x00). This is the primary partition table, located at the :menuitem:`CONFIG_PARTITION_TABLE_OFFSET` address in flash memory. The tool automatically determines the appropriate size and offset for this subtype, so any size or offset specified for this subtype will be ignored. You can either leave these fields blank or use ``N/A`` as a placeholder.
- ``ota`` (0x01). It is a temporary partition table partition used by the partition table OTA update functionality for downloading a new image. The tool ignores the size for this subtype, allowing you to leave it blank or use ``N/A``. You can specify an offset, or leave it blank, in which case the tool will calculate it based on the offsets of previously allocated partitions.
The size for the ``partition_table`` type is fixed at ``0x1000`` and applies uniformly across all subtypes of ``partition_table``.
@@ -226,7 +226,7 @@ Offset & Size
.. note::
If you want the partitions in the partition table to work relative to any placement (:ref:`CONFIG_PARTITION_TABLE_OFFSET`) of the table itself, leave the offset field (in CSV file) for all partitions blank. Similarly, if changing the partition table offset, then be aware that all blank partition offsets may change to match, and that any fixed offsets may now collide with the partition table (causing an error).
If you want the partitions in the partition table to work relative to any placement (:menuitem:`CONFIG_PARTITION_TABLE_OFFSET`) of the table itself, leave the offset field (in CSV file) for all partitions blank. Similarly, if changing the partition table offset, then be aware that all blank partition offsets may change to match, and that any fixed offsets may now collide with the partition table (causing an error).
Flags
~~~~~
@@ -301,11 +301,11 @@ The binary format of the partition table contains an MD5 checksum computed based
.. only:: esp32
The MD5 checksum generation can be disabled by the ``--disable-md5sum`` option of ``gen_esp32part.py`` or by the :ref:`CONFIG_PARTITION_TABLE_MD5` option. This is useful for example when one :ref:`uses a bootloader from ESP-IDF before v3.1 <CONFIG_APP_COMPATIBLE_PRE_V3_1_BOOTLOADERS>` which cannot process MD5 checksums and the boot fails with the error message ``invalid magic number 0xebeb``.
The MD5 checksum generation can be disabled by the ``--disable-md5sum`` option of ``gen_esp32part.py`` or by the :menuitem:`CONFIG_PARTITION_TABLE_MD5` option. This is useful for example when one :menuitem:`uses a bootloader from ESP-IDF before v3.1 <CONFIG_APP_COMPATIBLE_PRE_V3_1_BOOTLOADERS>` which cannot process MD5 checksums and the boot fails with the error message ``invalid magic number 0xebeb``.
.. only:: not esp32
The MD5 checksum generation can be disabled by the ``--disable-md5sum`` option of ``gen_esp32part.py`` or by the :ref:`CONFIG_PARTITION_TABLE_MD5` option.
The MD5 checksum generation can be disabled by the ``--disable-md5sum`` option of ``gen_esp32part.py`` or by the :menuitem:`CONFIG_PARTITION_TABLE_MD5` option.
Flashing the Partition Table

116
docs/en/api-guides/performance/ram-usage.rst
View File

@@ -40,8 +40,8 @@ To minimize static memory use:
.. list::
- Constant data can be stored in flash memory instead of RAM, thus it is recommended to declare structures, buffers, or other variables as ``const``. This approach may require modifying firmware functions to accept ``const *`` arguments instead of mutable pointer arguments. These changes can also help reduce the stack usage of certain functions.
:SOC_BT_SUPPORTED: - If using Bluedroid, setting the option :ref:`CONFIG_BT_BLE_DYNAMIC_ENV_MEMORY` will cause Bluedroid to allocate memory on initialization and free it on deinitialization. This does not necessarily reduce the peak memory usage, but changes it from static memory usage to runtime memory usage.
- If using OpenThread, enabling the option :ref:`CONFIG_OPENTHREAD_PLATFORM_MSGPOOL_MANAGEMENT` will cause OpenThread to allocate message pool buffers from PSRAM, which will reduce static memory use.
:SOC_BT_SUPPORTED: - If using Bluedroid, setting the option :menuitem:`CONFIG_BT_BLE_DYNAMIC_ENV_MEMORY` will cause Bluedroid to allocate memory on initialization and free it on deinitialization. This does not necessarily reduce the peak memory usage, but changes it from static memory usage to runtime memory usage.
- If using OpenThread, enabling the option :menuitem:`CONFIG_OPENTHREAD_PLATFORM_MSGPOOL_MANAGEMENT` will cause OpenThread to allocate message pool buffers from PSRAM, which will reduce static memory use.
.. _optimize-stack-sizes:
@@ -60,17 +60,17 @@ Configuration Options for Stack Overflow Detection
Hardware Stack Guard
~~~~~~~~~~~~~~~~~~~~
The Hardware Stack Guard is a reliable method for detecting stack overflow. This method uses the hardware's Debug Assistant module to monitor the CPU's stack pointer register. A panic is immediately triggered if the stack pointer register goes beyond the bounds of the current stack (see :ref:`Hardware-Stack-Guard` for more details). The Hardware Stack Guard can be enabled via the :ref:`CONFIG_ESP_SYSTEM_HW_STACK_GUARD` option.
The Hardware Stack Guard is a reliable method for detecting stack overflow. This method uses the hardware's Debug Assistant module to monitor the CPU's stack pointer register. A panic is immediately triggered if the stack pointer register goes beyond the bounds of the current stack (see :ref:`Hardware-Stack-Guard` for more details). The Hardware Stack Guard can be enabled via the :menuitem:`CONFIG_ESP_SYSTEM_HW_STACK_GUARD` option.
End of Stack Watchpoint
~~~~~~~~~~~~~~~~~~~~~~~
The End of Stack Watchpoint feature places a CPU watchpoint at the end of the current stack. If that word is overwritten (such as in a stack overflow), a panic is triggered immediately. End of Stack Watchpoints can be enabled via the :ref:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` option, but can only be used if debugger watchpoints are not already being used.
The End of Stack Watchpoint feature places a CPU watchpoint at the end of the current stack. If that word is overwritten (such as in a stack overflow), a panic is triggered immediately. End of Stack Watchpoints can be enabled via the :menuitem:`CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` option, but can only be used if debugger watchpoints are not already being used.
Stack Canary Bytes
~~~~~~~~~~~~~~~~~~
The Stack Canary Bytes feature adds a set of magic bytes at the end of each task's stack, and checks if those magic bytes have changed on every context switch. If those magic bytes are overwritten, a panic is triggered. Stack Canary Bytes can be enabled via the :ref:`CONFIG_FREERTOS_CHECK_STACKOVERFLOW` option.
The Stack Canary Bytes feature adds a set of magic bytes at the end of each task's stack, and checks if those magic bytes have changed on every context switch. If those magic bytes are overwritten, a panic is triggered. Stack Canary Bytes can be enabled via the :menuitem:`CONFIG_FREERTOS_CHECK_STACKOVERFLOW` option.
.. note::
@@ -78,7 +78,7 @@ The Stack Canary Bytes feature adds a set of magic bytes at the end of each task
.. only:: SOC_ASSIST_DEBUG_SUPPORTED
Recommended and default option is :ref:`CONFIG_ESP_SYSTEM_HW_STACK_GUARD` which avoids this disadvantage.
Recommended and default option is :menuitem:`CONFIG_ESP_SYSTEM_HW_STACK_GUARD` which avoids this disadvantage.
Run-time Methods to Determine Stack Size
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -104,7 +104,7 @@ Reducing Stack Sizes
.. only:: SOC_SPIRAM_SUPPORTED
If the application uses external RAM, enabling :ref:`CONFIG_FREERTOS_PLACE_TASK_STACKS_IN_EXT_RAM` can move task stacks created by :cpp:func:`xTaskCreate` or :cpp:func:`xTaskCreatePinnedToCore` to PSRAM, reducing internal RAM usage. This option has restrictions for tasks that run while the flash cache is disabled; see :ref:`task-stack-in-external-ram` for details.
If the application uses external RAM, enabling :menuitem:`CONFIG_FREERTOS_PLACE_TASK_STACKS_IN_EXT_RAM` can move task stacks created by :cpp:func:`xTaskCreate` or :cpp:func:`xTaskCreatePinnedToCore` to PSRAM, reducing internal RAM usage. This option has restrictions for tasks that run while the flash cache is disabled; see :ref:`task-stack-in-external-ram` for details.
Reducing Task Count
^^^^^^^^^^^^^^^^^^^
@@ -127,15 +127,15 @@ The default stack sizes for these tasks are usually set conservatively high to a
.. list::
- :ref:`app-main-task` has stack size :ref:`CONFIG_ESP_MAIN_TASK_STACK_SIZE`.
- :doc:`/api-reference/system/esp_timer` system task which executes callbacks has stack size :ref:`CONFIG_ESP_TIMER_TASK_STACK_SIZE`.
- FreeRTOS Timer Task to handle FreeRTOS timer callbacks has stack size :ref:`CONFIG_FREERTOS_TIMER_TASK_STACK_DEPTH`.
- :doc:`/api-reference/system/esp_event` system task to execute callbacks for the default system event loop has stack size :ref:`CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE`.
- :doc:`/api-guides/lwip` TCP/IP task has stack size :ref:`CONFIG_LWIP_TCPIP_TASK_STACK_SIZE`.
:SOC_BT_SUPPORTED: - :doc:`/api-reference/bluetooth/index` have task stack sizes :ref:`CONFIG_BT_BTC_TASK_STACK_SIZE`, :ref:`CONFIG_BT_BTU_TASK_STACK_SIZE`.
:SOC_BT_SUPPORTED: - :doc:`/api-reference/bluetooth/nimble/index` has task stack size :ref:`CONFIG_BT_NIMBLE_HOST_TASK_STACK_SIZE`.
- :ref:`app-main-task` has stack size :menuitem:`CONFIG_ESP_MAIN_TASK_STACK_SIZE`.
- :doc:`/api-reference/system/esp_timer` system task which executes callbacks has stack size :menuitem:`CONFIG_ESP_TIMER_TASK_STACK_SIZE`.
- FreeRTOS Timer Task to handle FreeRTOS timer callbacks has stack size :menuitem:`CONFIG_FREERTOS_TIMER_TASK_STACK_DEPTH`.
- :doc:`/api-reference/system/esp_event` system task to execute callbacks for the default system event loop has stack size :menuitem:`CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE`.
- :doc:`/api-guides/lwip` TCP/IP task has stack size :menuitem:`CONFIG_LWIP_TCPIP_TASK_STACK_SIZE`.
:SOC_BT_SUPPORTED: - :doc:`/api-reference/bluetooth/index` have task stack sizes :menuitem:`CONFIG_BT_BTC_TASK_STACK_SIZE`, :menuitem:`CONFIG_BT_BTU_TASK_STACK_SIZE`.
:SOC_BT_SUPPORTED: - :doc:`/api-reference/bluetooth/nimble/index` has task stack size :menuitem:`CONFIG_BT_NIMBLE_HOST_TASK_STACK_SIZE`.
- The Ethernet driver creates a task for the MAC to receive Ethernet frames. If using the default config ``ETH_MAC_DEFAULT_CONFIG`` then the task stack size is 4 KB. This setting can be changed by passing a custom :cpp:class:`eth_mac_config_t` struct when initializing the Ethernet MAC.
- FreeRTOS idle task stack size is configured by :ref:`CONFIG_FREERTOS_IDLE_TASK_STACKSIZE`.
- FreeRTOS idle task stack size is configured by :menuitem:`CONFIG_FREERTOS_IDLE_TASK_STACKSIZE`.
- To see how to optimize RAM usage when using ``mDNS``, please check `Minimizing RAM Usage <https://docs.espressif.com/projects/esp-protocols/mdns/docs/latest/en/index.html#minimizing-ram-usage>`__.
.. note::
@@ -155,12 +155,12 @@ There are some ESP-IDF configuration options that can reduce heap usage at runti
- lwIP documentation has a section to configure :ref:`lwip-ram-usage`.
:SOC_WIFI_SUPPORTED: - :ref:`wifi-buffer-usage` describes options to either reduce the number of static buffers or reduce the maximum number of dynamic buffers in use, so as to minimize memory usage at a possible cost of performance. Note that static Wi-Fi buffers are still allocated from the heap when Wi-Fi is initialized, and will be freed if Wi-Fi is deinitialized.
:esp32: - The Ethernet driver allocates DMA buffers for the internal Ethernet MAC when it is initialized - configuration options are :ref:`CONFIG_ETH_DMA_BUFFER_SIZE`, :ref:`CONFIG_ETH_DMA_RX_BUFFER_NUM`, :ref:`CONFIG_ETH_DMA_TX_BUFFER_NUM`.
:esp32: - The Ethernet driver allocates DMA buffers for the internal Ethernet MAC when it is initialized - configuration options are :menuitem:`CONFIG_ETH_DMA_BUFFER_SIZE`, :menuitem:`CONFIG_ETH_DMA_RX_BUFFER_NUM`, :menuitem:`CONFIG_ETH_DMA_TX_BUFFER_NUM`.
- Several Mbed TLS configuration options can be used to reduce heap memory usage. See the :ref:`reducing_ram_usage_mbedtls` docs for details.
:esp32: - In single-core mode only, it is possible to use IRAM as byte-accessible memory added to the regular heap by enabling :ref:`CONFIG_ESP32_IRAM_AS_8BIT_ACCESSIBLE_MEMORY`. Note that this option carries a performance penalty, and the risk of security issues caused by executable data. If this option is enabled, then it is possible to set other options to prefer certain buffers allocated from this memory: :ref:`CONFIG_MBEDTLS_MEM_ALLOC_MODE`, :ref:`NimBLE <CONFIG_BT_NIMBLE_MEM_ALLOC_MODE>`.
:esp32: - Reduce :ref:`CONFIG_BTDM_CTRL_BLE_MAX_CONN` if using Bluetooth LE.
:esp32: - Reduce :ref:`CONFIG_BTDM_CTRL_BR_EDR_MAX_ACL_CONN` if using Bluetooth Classic.
:CONFIG_IDF_TARGET_ARCH_RISCV and not esp32c2 and not esp32c3: - Enabling :ref:`CONFIG_COMPILER_CXX_ATOMIC_LOCK_POLICY` forces libstdc++ lock-free ``std::shared_ptr`` reference counting instead of a mutex-based implementation, avoiding an embedded mutex in each control block and saving about 88 bytes of heap per ``shared_ptr``. All C++ object files and linked libraries must use the same setting; see the config help for ABI details.
:esp32: - In single-core mode only, it is possible to use IRAM as byte-accessible memory added to the regular heap by enabling :menuitem:`CONFIG_ESP32_IRAM_AS_8BIT_ACCESSIBLE_MEMORY`. Note that this option carries a performance penalty, and the risk of security issues caused by executable data. If this option is enabled, then it is possible to set other options to prefer certain buffers allocated from this memory: :menuitem:`CONFIG_MBEDTLS_MEM_ALLOC_MODE`, :menuitem:`NimBLE <CONFIG_BT_NIMBLE_MEM_ALLOC_MODE>`.
:esp32: - Reduce :menuitem:`CONFIG_BTDM_CTRL_BLE_MAX_CONN` if using Bluetooth LE.
:esp32: - Reduce :menuitem:`CONFIG_BTDM_CTRL_BR_EDR_MAX_ACL_CONN` if using Bluetooth Classic.
:CONFIG_IDF_TARGET_ARCH_RISCV and not esp32c2 and not esp32c3: - Enabling :menuitem:`CONFIG_COMPILER_CXX_ATOMIC_LOCK_POLICY` forces libstdc++ lock-free ``std::shared_ptr`` reference counting instead of a mutex-based implementation, avoiding an embedded mutex in each control block and saving about 88 bytes of heap per ``shared_ptr``. All C++ object files and linked libraries must use the same setting; see the config help for ABI details.
.. note::
@@ -183,30 +183,30 @@ The following options will reduce IRAM usage of some ESP-IDF features:
.. list::
- Disable :ref:`CONFIG_FREERTOS_IN_IRAM` if enabled to place FreeRTOS functions in flash instead of IRAM. By default, FreeRTOS functions are already placed in Flash to save IRAM.
- Disable :ref:`CONFIG_RINGBUF_IN_IRAM` if enabled to place ring buffer functions in Flash instead of IRAM. By default, ring buffer functions are already placed in Flash to save IRAM.
- Enable :ref:`CONFIG_RINGBUF_PLACE_ISR_FUNCTIONS_INTO_FLASH`. This option is not safe to use if the ISR ringbuf functions are used from an IRAM interrupt context, e.g., if :ref:`CONFIG_UART_ISR_IN_IRAM` is enabled. For the ESP-IDF drivers where this is the case, you can get an error at run-time when installing the driver in question.
:SOC_WIFI_SUPPORTED: - Disabling Wi-Fi options :ref:`CONFIG_ESP_WIFI_IRAM_OPT` and/or :ref:`CONFIG_ESP_WIFI_RX_IRAM_OPT` options frees available IRAM at the cost of Wi-Fi performance.
:CONFIG_ESP_ROM_HAS_SPI_FLASH: - Enabling :ref:`CONFIG_SPI_FLASH_ROM_IMPL` frees some IRAM but means that esp_flash bugfixes and new flash chip support are not available, see :doc:`/api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom` for details.
:esp32: - If the application uses PSRAM and is based on ESP32 rev. 3 (ECO3), setting :ref:`CONFIG_ESP32_REV_MIN` to ``3`` disables PSRAM bug workarounds, saving 10 KB or more of IRAM.
- Disabling :ref:`CONFIG_ESP_EVENT_POST_FROM_IRAM_ISR` prevents posting ``esp_event`` events from :ref:`iram-safe-interrupt-handlers` but saves some IRAM.
:SOC_GPSPI_SUPPORTED: - Disabling :ref:`CONFIG_SPI_MASTER_ISR_IN_IRAM` prevents spi_master interrupts from being serviced while writing to flash, and may otherwise reduce spi_master performance, but saves some IRAM.
:SOC_GPSPI_SUPPORTED: - Disabling :ref:`CONFIG_SPI_SLAVE_ISR_IN_IRAM` prevents spi_slave interrupts from being serviced while writing to flash, which saves some IRAM.
- Setting :ref:`CONFIG_HAL_DEFAULT_ASSERTION_LEVEL` to disable assertion for HAL component saves some IRAM, especially for HAL code who calls ``HAL_ASSERT`` a lot and resides in IRAM.
- Disable :menuitem:`CONFIG_FREERTOS_IN_IRAM` if enabled to place FreeRTOS functions in flash instead of IRAM. By default, FreeRTOS functions are already placed in Flash to save IRAM.
- Disable :menuitem:`CONFIG_RINGBUF_IN_IRAM` if enabled to place ring buffer functions in Flash instead of IRAM. By default, ring buffer functions are already placed in Flash to save IRAM.
- Enable :menuitem:`CONFIG_RINGBUF_PLACE_ISR_FUNCTIONS_INTO_FLASH`. This option is not safe to use if the ISR ringbuf functions are used from an IRAM interrupt context, e.g., if :menuitem:`CONFIG_UART_ISR_IN_IRAM` is enabled. For the ESP-IDF drivers where this is the case, you can get an error at run-time when installing the driver in question.
:SOC_WIFI_SUPPORTED: - Disabling Wi-Fi options :menuitem:`CONFIG_ESP_WIFI_IRAM_OPT` and/or :menuitem:`CONFIG_ESP_WIFI_RX_IRAM_OPT` options frees available IRAM at the cost of Wi-Fi performance.
:CONFIG_ESP_ROM_HAS_SPI_FLASH: - Enabling :menuitem:`CONFIG_SPI_FLASH_ROM_IMPL` frees some IRAM but means that esp_flash bugfixes and new flash chip support are not available, see :doc:`/api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom` for details.
:esp32: - If the application uses PSRAM and is based on ESP32 rev. 3 (ECO3), setting :menuitem:`CONFIG_ESP32_REV_MIN` to ``3`` disables PSRAM bug workarounds, saving 10 KB or more of IRAM.
- Disabling :menuitem:`CONFIG_ESP_EVENT_POST_FROM_IRAM_ISR` prevents posting ``esp_event`` events from :ref:`iram-safe-interrupt-handlers` but saves some IRAM.
:SOC_GPSPI_SUPPORTED: - Disabling :menuitem:`CONFIG_SPI_MASTER_ISR_IN_IRAM` prevents spi_master interrupts from being serviced while writing to flash, and may otherwise reduce spi_master performance, but saves some IRAM.
:SOC_GPSPI_SUPPORTED: - Disabling :menuitem:`CONFIG_SPI_SLAVE_ISR_IN_IRAM` prevents spi_slave interrupts from being serviced while writing to flash, which saves some IRAM.
- Setting :menuitem:`CONFIG_HAL_DEFAULT_ASSERTION_LEVEL` to disable assertion for HAL component saves some IRAM, especially for HAL code who calls ``HAL_ASSERT`` a lot and resides in IRAM.
- Refer to the sdkconfig menu ``Auto-detect Flash chips``, and you can disable flash drivers which you do not need to save some IRAM.
:SOC_GPSPI_SUPPORTED: - Enable :ref:`CONFIG_HEAP_PLACE_FUNCTION_INTO_FLASH`. Provided that :ref:`CONFIG_SPI_MASTER_ISR_IN_IRAM` is not enabled and the heap functions are not incorrectly used from ISRs, this option is safe to enable in all configurations.
:esp32c2: - Enable :ref:`CONFIG_BT_RELEASE_IRAM`. Release BT text section and merge BT data, bss & text into a large free heap region when ``esp_bt_mem_release`` is called. This makes Bluetooth unavailable until the next restart, but saving ~22 KB or more of IRAM.
- Disable :ref:`CONFIG_LIBC_LOCKS_PLACE_IN_IRAM` if no ISRs that run while cache is disabled (i.e. IRAM ISRs) use libc lock APIs.
:CONFIG_ESP_ROM_HAS_SUBOPTIMAL_NEWLIB_ON_MISALIGNED_MEMORY: - Disable :ref:`CONFIG_LIBC_OPTIMIZED_MISALIGNED_ACCESS` to save approximately 1000 bytes of IRAM, at the cost of reduced performance.
:SOC_SPIRAM_SUPPORTED: - Enable :ref:`CONFIG_ESP_EVENT_LOOP_IN_EXT_RAM` to force ``esp_event`` to place event loop related allocations in external RAM instead of internal RAM.
:not CONFIG_ESP_ROM_HAS_VPRINTF_FUNC: - When using **Log V2**, disable :ref:`CONFIG_LOG_API_CONSTRAINED_ENV_SAFE` to remove ``esp_rom_vprintf`` from IRAM, saving about 1.2 KB. This means ``ESP_LOGx`` will no longer safely fall back to ROM-based printing in ISRs or with cache disabled. Use ``ESP_DRAM_LOGx`` explicitly for constrained-environment logging. See :doc:`/api-reference/system/log` for details.
:SOC_GPSPI_SUPPORTED: - Enable :menuitem:`CONFIG_HEAP_PLACE_FUNCTION_INTO_FLASH`. Provided that :menuitem:`CONFIG_SPI_MASTER_ISR_IN_IRAM` is not enabled and the heap functions are not incorrectly used from ISRs, this option is safe to enable in all configurations.
:esp32c2: - Enable :menuitem:`CONFIG_BT_RELEASE_IRAM`. Release BT text section and merge BT data, bss & text into a large free heap region when ``esp_bt_mem_release`` is called. This makes Bluetooth unavailable until the next restart, but saving ~22 KB or more of IRAM.
- Disable :menuitem:`CONFIG_LIBC_LOCKS_PLACE_IN_IRAM` if no ISRs that run while cache is disabled (i.e. IRAM ISRs) use libc lock APIs.
:CONFIG_ESP_ROM_HAS_SUBOPTIMAL_NEWLIB_ON_MISALIGNED_MEMORY: - Disable :menuitem:`CONFIG_LIBC_OPTIMIZED_MISALIGNED_ACCESS` to save approximately 1000 bytes of IRAM, at the cost of reduced performance.
:SOC_SPIRAM_SUPPORTED: - Enable :menuitem:`CONFIG_ESP_EVENT_LOOP_IN_EXT_RAM` to force ``esp_event`` to place event loop related allocations in external RAM instead of internal RAM.
:not CONFIG_ESP_ROM_HAS_VPRINTF_FUNC: - When using **Log V2**, disable :menuitem:`CONFIG_LOG_API_CONSTRAINED_ENV_SAFE` to remove ``esp_rom_vprintf`` from IRAM, saving about 1.2 KB. This means ``ESP_LOGx`` will no longer safely fall back to ROM-based printing in ISRs or with cache disabled. Use ``ESP_DRAM_LOGx`` explicitly for constrained-environment logging. See :doc:`/api-reference/system/log` for details.
.. only:: esp32
Using SRAM1 for IRAM
^^^^^^^^^^^^^^^^^^^^
The SRAM1 memory area is normally used for DRAM, but it is possible to use parts of it for IRAM with :ref:`CONFIG_ESP_SYSTEM_ESP32_SRAM1_REGION_AS_IRAM`. This memory would previously be reserved for DRAM data usage (e.g., ``.bss``) by the ESP-IDF second stage bootloader and later added to the heap. After this option was introduced, the bootloader DRAM size was reduced to a value closer to what it normally actually needs.
The SRAM1 memory area is normally used for DRAM, but it is possible to use parts of it for IRAM with :menuitem:`CONFIG_ESP_SYSTEM_ESP32_SRAM1_REGION_AS_IRAM`. This memory would previously be reserved for DRAM data usage (e.g., ``.bss``) by the ESP-IDF second stage bootloader and later added to the heap. After this option was introduced, the bootloader DRAM size was reduced to a value closer to what it normally actually needs.
To use this option, ESP-IDF should be able to recognize that the new SRAM1 area is also a valid load address for an image segment. If the second stage bootloader was compiled before this option existed, then the bootloader will not be able to load the app that has code placed in this new extended IRAM area. This would typically happen if you are doing an OTA update, where only the app would be updated.
@@ -218,7 +218,7 @@ The following options will reduce IRAM usage of some ESP-IDF features:
.. warning::
Apps compiled with :ref:`CONFIG_ESP_SYSTEM_ESP32_SRAM1_REGION_AS_IRAM` may fail to boot, if used together with a second stage bootloader that was compiled before this config option was introduced. If you are using an older bootloader and updating over OTA, please test carefully before pushing any updates.
Apps compiled with :menuitem:`CONFIG_ESP_SYSTEM_ESP32_SRAM1_REGION_AS_IRAM` may fail to boot, if used together with a second stage bootloader that was compiled before this config option was introduced. If you are using an older bootloader and updating over OTA, please test carefully before pushing any updates.
Any memory that ends up unused for static IRAM will be added to the heap.
@@ -237,9 +237,9 @@ The following options will reduce IRAM usage of some ESP-IDF features:
User ISR callbacks and involved variables have to be in internal RAM if they are also used in interrupt contexts.
Placing additional code into IRAM will exacerbate IRAM usage. For this reason, there is :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND`, which can alleviate the aforementioned kinds of IRAM usage. By enabling this feature, the Cache will not be disabled when SPI flash driver APIs and SPI flash driver-based APIs are used. Therefore, code and data in flash can be executed or accessed normally, but with some minor delay. See :ref:`auto-suspend` for more details about this feature.
Placing additional code into IRAM will exacerbate IRAM usage. For this reason, there is :menuitem:`CONFIG_SPI_FLASH_AUTO_SUSPEND`, which can alleviate the aforementioned kinds of IRAM usage. By enabling this feature, the Cache will not be disabled when SPI flash driver APIs and SPI flash driver-based APIs are used. Therefore, code and data in flash can be executed or accessed normally, but with some minor delay. See :ref:`auto-suspend` for more details about this feature.
IRAM usage for flash driver can be declined with :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND` enabled. Please refer to :ref:`internal_memory_saving_for_flash_driver` for more detailed information.
IRAM usage for flash driver can be declined with :menuitem:`CONFIG_SPI_FLASH_AUTO_SUSPEND` enabled. Please refer to :ref:`internal_memory_saving_for_flash_driver` for more detailed information.
Regarding the flash suspend feature usage, and corresponding response time delay, please also see this example :example:`system/flash_suspend`.
@@ -249,22 +249,22 @@ The following options will reduce IRAM usage of some ESP-IDF features:
Putting C Library in Flash
^^^^^^^^^^^^^^^^^^^^^^^^^^
When compiling for ESP32 revisions older than ECO3 (:ref:`CONFIG_ESP32_REV_MIN`), the PSRAM Cache bug workaround (:ref:`CONFIG_SPIRAM_CACHE_WORKAROUND`) option is enabled, and the C library functions normally located in ROM are recompiled with the workaround and placed into IRAM instead. For most applications, it is safe to move many of the C library functions into flash, reclaiming some IRAM. Corresponding options include:
When compiling for ESP32 revisions older than ECO3 (:menuitem:`CONFIG_ESP32_REV_MIN`), the PSRAM Cache bug workaround (:menuitem:`CONFIG_SPIRAM_CACHE_WORKAROUND`) option is enabled, and the C library functions normally located in ROM are recompiled with the workaround and placed into IRAM instead. For most applications, it is safe to move many of the C library functions into flash, reclaiming some IRAM. Corresponding options include:
.. list::
- :ref:`CONFIG_SPIRAM_CACHE_LIBJMP_IN_IRAM`: affects the functions ``longjmp`` and ``setjump``.
- :ref:`CONFIG_SPIRAM_CACHE_LIBMATH_IN_IRAM`: affects the functions ``abs``, ``div``, ``labs``, ``ldiv``, ``quorem``, ``fpclassify`` and ``nan``.
- :ref:`CONFIG_SPIRAM_CACHE_LIBNUMPARSER_IN_IRAM`: affects the functions ``utoa``, ``itoa``, ``atoi``, ``atol``, ``strtol``, and ``strtoul``.
- :ref:`CONFIG_SPIRAM_CACHE_LIBIO_IN_IRAM`: affects the functions ``wcrtomb``, ``fvwrite``, ``wbuf``, ``wsetup``, ``fputwc``, ``wctomb_r``, ``ungetc``, ``makebuf``, ``fflush``, ``refill``, and ``sccl``.
- :ref:`CONFIG_SPIRAM_CACHE_LIBTIME_IN_IRAM`: affects the functions ``asctime``, ``asctime_r``, ``ctime``, ``ctime_r``, ``lcltime``, ``lcltime_r``, ``gmtime``, ``gmtime_r``, ``strftime``, ``mktime``, ``tzset_r``, ``tzset``, ``time``, ``gettzinfo``, ``systimes``, ``month_lengths``, ``timelocal``, ``tzvars``, ``tzlock``, ``tzcalc_limits``, and ``strptime``.
- :ref:`CONFIG_SPIRAM_CACHE_LIBCHAR_IN_IRAM`: affects the functions ``ctype_``, ``toupper``, ``tolower``, ``toascii``, ``strupr``, ``bzero``, ``isalnum``, ``isalpha``, ``isascii``, ``isblank``, ``iscntrl``, ``isdigit``, ``isgraph``, ``islower``, ``isprint``, ``ispunct``, ``isspace``, and ``isupper``.
- :ref:`CONFIG_SPIRAM_CACHE_LIBMEM_IN_IRAM`: affects the functions ``memccpy``, ``memchr``, ``memmove``, and ``memrchr``.
- :ref:`CONFIG_SPIRAM_CACHE_LIBSTR_IN_IRAM`: affects the functions ``strcasecmp``, ``strcasestr``, ``strchr``, ``strcoll``, ``strcpy``, ``strcspn``, ``strdup``, ``strdup_r``, ``strlcat``, ``strlcpy``, ``strlen``, ``strlwr``, ``strncasecmp``, ``strncat``, ``strncmp``, ``strncpy``, ``strndup``, ``strndup_r``, ``strrchr``, ``strsep``, ``strspn``, ``strstr``, ``strtok_r, and ``strupr``.
- :ref:`CONFIG_SPIRAM_CACHE_LIBRAND_IN_IRAM`: affects the functions ``srand``, ``rand``, and ``rand_r``.
- :ref:`CONFIG_SPIRAM_CACHE_LIBENV_IN_IRAM`: affects the functions ``environ``, ``envlock``, and ``getenv_r``.
- :ref:`CONFIG_SPIRAM_CACHE_LIBFILE_IN_IRAM`: affects the functions ``lock``, ``isatty``, ``fclose``, ``open``, ``close``, ``creat``, ``read``, ``rshift``, ``sbrk``, ``stdio``, ``syssbrk``, ``sysclose``, ``sysopen``, ``creat``, ``sysread``, ``syswrite``, ``impure``, ``fwalk``, and ``findfp``.
- :ref:`CONFIG_SPIRAM_CACHE_LIBMISC_IN_IRAM`: affects the functions ``raise`` and ``system``.
- :menuitem:`CONFIG_SPIRAM_CACHE_LIBJMP_IN_IRAM`: affects the functions ``longjmp`` and ``setjump``.
- :menuitem:`CONFIG_SPIRAM_CACHE_LIBMATH_IN_IRAM`: affects the functions ``abs``, ``div``, ``labs``, ``ldiv``, ``quorem``, ``fpclassify`` and ``nan``.
- :menuitem:`CONFIG_SPIRAM_CACHE_LIBNUMPARSER_IN_IRAM`: affects the functions ``utoa``, ``itoa``, ``atoi``, ``atol``, ``strtol``, and ``strtoul``.
- :menuitem:`CONFIG_SPIRAM_CACHE_LIBIO_IN_IRAM`: affects the functions ``wcrtomb``, ``fvwrite``, ``wbuf``, ``wsetup``, ``fputwc``, ``wctomb_r``, ``ungetc``, ``makebuf``, ``fflush``, ``refill``, and ``sccl``.
- :menuitem:`CONFIG_SPIRAM_CACHE_LIBTIME_IN_IRAM`: affects the functions ``asctime``, ``asctime_r``, ``ctime``, ``ctime_r``, ``lcltime``, ``lcltime_r``, ``gmtime``, ``gmtime_r``, ``strftime``, ``mktime``, ``tzset_r``, ``tzset``, ``time``, ``gettzinfo``, ``systimes``, ``month_lengths``, ``timelocal``, ``tzvars``, ``tzlock``, ``tzcalc_limits``, and ``strptime``.
- :menuitem:`CONFIG_SPIRAM_CACHE_LIBCHAR_IN_IRAM`: affects the functions ``ctype_``, ``toupper``, ``tolower``, ``toascii``, ``strupr``, ``bzero``, ``isalnum``, ``isalpha``, ``isascii``, ``isblank``, ``iscntrl``, ``isdigit``, ``isgraph``, ``islower``, ``isprint``, ``ispunct``, ``isspace``, and ``isupper``.
- :menuitem:`CONFIG_SPIRAM_CACHE_LIBMEM_IN_IRAM`: affects the functions ``memccpy``, ``memchr``, ``memmove``, and ``memrchr``.
- :menuitem:`CONFIG_SPIRAM_CACHE_LIBSTR_IN_IRAM`: affects the functions ``strcasecmp``, ``strcasestr``, ``strchr``, ``strcoll``, ``strcpy``, ``strcspn``, ``strdup``, ``strdup_r``, ``strlcat``, ``strlcpy``, ``strlen``, ``strlwr``, ``strncasecmp``, ``strncat``, ``strncmp``, ``strncpy``, ``strndup``, ``strndup_r``, ``strrchr``, ``strsep``, ``strspn``, ``strstr``, ``strtok_r, and ``strupr``.
- :menuitem:`CONFIG_SPIRAM_CACHE_LIBRAND_IN_IRAM`: affects the functions ``srand``, ``rand``, and ``rand_r``.
- :menuitem:`CONFIG_SPIRAM_CACHE_LIBENV_IN_IRAM`: affects the functions ``environ``, ``envlock``, and ``getenv_r``.
- :menuitem:`CONFIG_SPIRAM_CACHE_LIBFILE_IN_IRAM`: affects the functions ``lock``, ``isatty``, ``fclose``, ``open``, ``close``, ``creat``, ``read``, ``rshift``, ``sbrk``, ``stdio``, ``syssbrk``, ``sysclose``, ``sysopen``, ``creat``, ``sysread``, ``syswrite``, ``impure``, ``fwalk``, and ``findfp``.
- :menuitem:`CONFIG_SPIRAM_CACHE_LIBMISC_IN_IRAM`: affects the functions ``raise`` and ``system``.
The exact amount of IRAM saved will depend on how much C library code is actually used by the application. In addition, the following options may be used to move more of the C library code into flash, however note that this may result in reduced performance. Be careful not to use the C library function allocated with :c:macro:`ESP_INTR_FLAG_IRAM` flag from interrupts when cache is disabled, refer to :ref:`iram-safe-interrupt-handlers` for more details. For these reasons, the functions ``itoa``, ``memcmp``, ``memcpy``, ``memset``, ``strcat``, ``strcmp``, and ``strlen`` are always put in IRAM.
@@ -286,8 +286,8 @@ The following options will reduce IRAM usage of some ESP-IDF features:
.. list::
:esp32s2: - :ref:`CONFIG_ESP32S2_INSTRUCTION_CACHE_SIZE`
:esp32s2: - :ref:`CONFIG_ESP32S2_DATA_CACHE_SIZE`
:esp32s3: - :ref:`CONFIG_ESP32S3_INSTRUCTION_CACHE_SIZE`
:esp32s3: - :ref:`CONFIG_ESP32S3_DATA_CACHE_SIZE`
:esp32p4: - :ref:`CONFIG_CACHE_L2_CACHE_SIZE`
:esp32s2: - :menuitem:`CONFIG_ESP32S2_INSTRUCTION_CACHE_SIZE`
:esp32s2: - :menuitem:`CONFIG_ESP32S2_DATA_CACHE_SIZE`
:esp32s3: - :menuitem:`CONFIG_ESP32S3_INSTRUCTION_CACHE_SIZE`
:esp32s3: - :menuitem:`CONFIG_ESP32S3_DATA_CACHE_SIZE`
:esp32p4: - :menuitem:`CONFIG_CACHE_L2_CACHE_SIZE`

120
docs/en/api-guides/performance/size.rst
View File

@@ -78,26 +78,26 @@ The following configuration options reduces the final binary size of almost any
.. list::
- Set :ref:`CONFIG_COMPILER_OPTIMIZATION` to ``Optimize for size (-Os)``. In some cases, ``Optimize for performance (-O2)`` will also reduce the binary size compared to the default. Note that if your code contains C or C++ Undefined Behavior then increasing the compiler optimization level may expose bugs that otherwise do not happen.
- Set :ref:`CONFIG_COMPILER_LTO_LINKTIME` to enable link-time optimization, and enable LTO at compile time for some of the components (either by setting :ref:`CONFIG_COMPILER_LTO_COMPILETIME`, or by adding the ``-flto=auto`` compile option to specific components). When used together with optimization for size, this option can reduce the binary size. ``idf.py size``, ``idf.py size-components``, and ``idf.py size-files`` all report accurate sizes for LTO-enabled builds. Note that enabling LTO has a few downsides:
- Set :menuitem:`CONFIG_COMPILER_OPTIMIZATION` to ``Optimize for size (-Os)``. In some cases, ``Optimize for performance (-O2)`` will also reduce the binary size compared to the default. Note that if your code contains C or C++ Undefined Behavior then increasing the compiler optimization level may expose bugs that otherwise do not happen.
- Set :menuitem:`CONFIG_COMPILER_LTO_LINKTIME` to enable link-time optimization, and enable LTO at compile time for some of the components (either by setting :menuitem:`CONFIG_COMPILER_LTO_COMPILETIME`, or by adding the ``-flto=auto`` compile option to specific components). When used together with optimization for size, this option can reduce the binary size. ``idf.py size``, ``idf.py size-components``, and ``idf.py size-files`` all report accurate sizes for LTO-enabled builds. Note that enabling LTO has a few downsides:
- Enabling LTO increases the build time.
- Enabling LTO can increase the stack usage of your tasks. Inlining across translation units replaces several small stack frames with fewer but larger ones, so the peak stack depth along a call path may grow. The effect is usually small, but it can be significant for applications with deep call chains that span many LTO-optimized components. After enabling LTO, check the stack high water mark of your tasks (for example, with :cpp:func:`uxTaskGetStackHighWaterMark`) and raise the stack sizes of the affected tasks if necessary.
- LTO must not be enabled for components with custom :doc:`linker fragments <../linker-script-generation>`. This is because LTO merges the code from multiple object files into one, so the linker fragment is not able to control the placement of individual functions and variables.
- Enabling LTO may make the code more difficult to debug.
- Reduce the compiled-in log output by lowering the app :ref:`CONFIG_LOG_DEFAULT_LEVEL`. If the :ref:`CONFIG_LOG_MAXIMUM_LEVEL` is changed from the default then this setting controls the binary size instead. Reducing compiled-in logging reduces the number of strings in the binary, and also the code size of the calls to logging functions.
- If your application does not require dynamic log level changes and you do not need to control logs per module using tags, consider disabling :ref:`CONFIG_LOG_DYNAMIC_LEVEL_CONTROL` and changing :ref:`CONFIG_LOG_TAG_LEVEL_IMPL`. It reduces IRAM usage by approximately 260 bytes, DRAM usage by approximately 264 bytes, and flash usage by approximately 1 KB compared to the default option, it also speeds up logging.
- Set the :ref:`CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL` to ``Silent``. This avoids compiling in a dedicated assertion string and source file name for each assert that may fail. It is still possible to find the failed assert in the code by looking at the memory address where the assertion failed.
- Besides the :ref:`CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL`, you can disable or silent the assertion for the HAL component separately by setting :ref:`CONFIG_HAL_DEFAULT_ASSERTION_LEVEL`. In the bootloader, ESP-IDF lowers the HAL assertion level to be silent even if :ref:`CONFIG_HAL_DEFAULT_ASSERTION_LEVEL` is set to full-assertion level. This is to reduce the bootloader size.
- Setting :ref:`CONFIG_COMPILER_OPTIMIZATION_CHECKS_SILENT` removes specific error messages for particular internal ESP-IDF error check macros. This may make it harder to debug some error conditions by reading the log output.
:esp32: - If the binary needs to run on only certain revision(s) of ESP32, increasing :ref:`CONFIG_ESP32_REV_MIN` to match can result in a reduced binary size. This will make a large difference if setting ESP32 minimum revision 3, and PSRAM is enabled.
:esp32c3: - If the binary needs to run on only certain revision(s) of ESP32-C3, increasing :ref:`CONFIG_ESP32C3_REV_MIN` to match can result in a reduced binary size. This is particularly true if setting ESP32-C3 minimum revision 3 and using Wi-Fi, as some functionality was moved to ROM code.
- Do not enable :ref:`CONFIG_COMPILER_CXX_EXCEPTIONS`, :ref:`CONFIG_COMPILER_CXX_RTTI`, or set the :ref:`CONFIG_COMPILER_STACK_CHECK_MODE` to Overall. All of these options are already disabled by default, but they have a large impact on binary size.
- Disabling :ref:`CONFIG_ESP_ERR_TO_NAME_LOOKUP` removes the lookup table to translate user-friendly names for error values (see :doc:`/api-guides/error-handling`) in error logs, etc. This saves some binary size, but error values will be printed as integers only.
- Setting :ref:`CONFIG_ESP_SYSTEM_PANIC` to ``Silent reboot`` saves a small amount of binary size, however this is **only** recommended if no one will use UART output to debug the device.
:CONFIG_IDF_TARGET_ARCH_RISCV: - Setting :ref:`CONFIG_COMPILER_SAVE_RESTORE_LIBCALLS` reduces binary size by replacing inlined prologues/epilogues with library calls.
- If the application binary uses only one of the security versions of the protocomm component, then the support for others can be disabled to save some code size. The support can be disabled through :ref:`CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_0`, :ref:`CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_1` or :ref:`CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_2` respectively.
:CONFIG_SOC_CPU_ZCMP_WORKAROUND: - Enable :ref:`CONFIG_COMPILER_ENABLE_RISCV_ZCMP` to reduce binary size by using compressed function prologues/epilogues. Read the :ref:`CONFIG_COMPILER_ENABLE_RISCV_ZCMP` notes carefully before enabling this option!
- Reduce the compiled-in log output by lowering the app :menuitem:`CONFIG_LOG_DEFAULT_LEVEL`. If the :menuitem:`CONFIG_LOG_MAXIMUM_LEVEL` is changed from the default then this setting controls the binary size instead. Reducing compiled-in logging reduces the number of strings in the binary, and also the code size of the calls to logging functions.
- If your application does not require dynamic log level changes and you do not need to control logs per module using tags, consider disabling :menuitem:`CONFIG_LOG_DYNAMIC_LEVEL_CONTROL` and changing :menuitem:`CONFIG_LOG_TAG_LEVEL_IMPL`. It reduces IRAM usage by approximately 260 bytes, DRAM usage by approximately 264 bytes, and flash usage by approximately 1 KB compared to the default option, it also speeds up logging.
- Set the :menuitem:`CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL` to ``Silent``. This avoids compiling in a dedicated assertion string and source file name for each assert that may fail. It is still possible to find the failed assert in the code by looking at the memory address where the assertion failed.
- Besides the :menuitem:`CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL`, you can disable or silent the assertion for the HAL component separately by setting :menuitem:`CONFIG_HAL_DEFAULT_ASSERTION_LEVEL`. In the bootloader, ESP-IDF lowers the HAL assertion level to be silent even if :menuitem:`CONFIG_HAL_DEFAULT_ASSERTION_LEVEL` is set to full-assertion level. This is to reduce the bootloader size.
- Setting :menuitem:`CONFIG_COMPILER_OPTIMIZATION_CHECKS_SILENT` removes specific error messages for particular internal ESP-IDF error check macros. This may make it harder to debug some error conditions by reading the log output.
:esp32: - If the binary needs to run on only certain revision(s) of ESP32, increasing :menuitem:`CONFIG_ESP32_REV_MIN` to match can result in a reduced binary size. This will make a large difference if setting ESP32 minimum revision 3, and PSRAM is enabled.
:esp32c3: - If the binary needs to run on only certain revision(s) of ESP32-C3, increasing :menuitem:`CONFIG_ESP32C3_REV_MIN` to match can result in a reduced binary size. This is particularly true if setting ESP32-C3 minimum revision 3 and using Wi-Fi, as some functionality was moved to ROM code.
- Do not enable :menuitem:`CONFIG_COMPILER_CXX_EXCEPTIONS`, :menuitem:`CONFIG_COMPILER_CXX_RTTI`, or set the :menuitem:`CONFIG_COMPILER_STACK_CHECK_MODE` to Overall. All of these options are already disabled by default, but they have a large impact on binary size.
- Disabling :menuitem:`CONFIG_ESP_ERR_TO_NAME_LOOKUP` removes the lookup table to translate user-friendly names for error values (see :doc:`/api-guides/error-handling`) in error logs, etc. This saves some binary size, but error values will be printed as integers only.
- Setting :menuitem:`CONFIG_ESP_SYSTEM_PANIC` to ``Silent reboot`` saves a small amount of binary size, however this is **only** recommended if no one will use UART output to debug the device.
:CONFIG_IDF_TARGET_ARCH_RISCV: - Setting :menuitem:`CONFIG_COMPILER_SAVE_RESTORE_LIBCALLS` reduces binary size by replacing inlined prologues/epilogues with library calls.
- If the application binary uses only one of the security versions of the protocomm component, then the support for others can be disabled to save some code size. The support can be disabled through :menuitem:`CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_0`, :menuitem:`CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_1` or :menuitem:`CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_2` respectively.
:CONFIG_SOC_CPU_ZCMP_WORKAROUND: - Enable :menuitem:`CONFIG_COMPILER_ENABLE_RISCV_ZCMP` to reduce binary size by using compressed function prologues/epilogues. Read the :menuitem:`CONFIG_COMPILER_ENABLE_RISCV_ZCMP` notes carefully before enabling this option!
.. note::
@@ -115,17 +115,17 @@ The following binary size optimizations apply to a particular component or a fun
Wi-Fi
@@@@@
- Disabling :ref:`CONFIG_ESP_WIFI_ENABLE_WPA3_SAE` will save some Wi-Fi binary size if WPA3 support is not needed. Note that WPA3 is mandatory for new Wi-Fi device certifications.
- Disabling :ref:`CONFIG_ESP_WIFI_SOFTAP_SUPPORT` will save some Wi-Fi binary size if soft-AP support is not needed.
- Disabling :ref:`CONFIG_ESP_WIFI_ENTERPRISE_SUPPORT` will save some Wi-Fi binary size if enterprise support is not needed.
- Disabling :ref:`CONFIG_ESP_WIFI_ENABLE_SAE_H2E` will save some Wi-Fi binary size if hash-to-element authentication method of WPA3-SAE is not needed. Note that hash-to-element is faster, more secure and immune to side channel attacks than the default authentication method of hunting-and-pecking.
- Disabling :menuitem:`CONFIG_ESP_WIFI_ENABLE_WPA3_SAE` will save some Wi-Fi binary size if WPA3 support is not needed. Note that WPA3 is mandatory for new Wi-Fi device certifications.
- Disabling :menuitem:`CONFIG_ESP_WIFI_SOFTAP_SUPPORT` will save some Wi-Fi binary size if soft-AP support is not needed.
- Disabling :menuitem:`CONFIG_ESP_WIFI_ENTERPRISE_SUPPORT` will save some Wi-Fi binary size if enterprise support is not needed.
- Disabling :menuitem:`CONFIG_ESP_WIFI_ENABLE_SAE_H2E` will save some Wi-Fi binary size if hash-to-element authentication method of WPA3-SAE is not needed. Note that hash-to-element is faster, more secure and immune to side channel attacks than the default authentication method of hunting-and-pecking.
.. only:: esp32
ADC
@@@
- Disabling ADC calibration features :ref:`CONFIG_ADC_CALI_EFUSE_TP_ENABLE`, :ref:`CONFIG_ADC_CALI_EFUSE_VREF_ENABLE`, :ref:`CONFIG_ADC_CALI_LUT_ENABLE` will save a small amount of binary size if ADC driver is used, at expense of accuracy.
- Disabling ADC calibration features :menuitem:`CONFIG_ADC_CALI_EFUSE_TP_ENABLE`, :menuitem:`CONFIG_ADC_CALI_EFUSE_VREF_ENABLE`, :menuitem:`CONFIG_ADC_CALI_LUT_ENABLE` will save a small amount of binary size if ADC driver is used, at expense of accuracy.
.. only:: SOC_BT_SUPPORTED
@@ -136,15 +136,15 @@ The following binary size optimizations apply to a particular component or a fun
.. list::
:esp32: - Set :ref:`CONFIG_BTDM_CTRL_BLE_MAX_CONN` to 1 if only one Bluetooth LE connection is needed.
- Set :ref:`CONFIG_BT_NIMBLE_MAX_CONNECTIONS` to 1 if only one Bluetooth LE connection is needed.
- Disable either :ref:`CONFIG_BT_NIMBLE_ROLE_CENTRAL` or :ref:`CONFIG_BT_NIMBLE_ROLE_OBSERVER` if these roles are not needed.
- Reducing :ref:`CONFIG_BT_NIMBLE_LOG_LEVEL` can reduce binary size. Note that if the overall log level has been reduced as described above in :ref:`reducing-overall-size` then this also reduces the NimBLE log level.
:esp32: - Set :menuitem:`CONFIG_BTDM_CTRL_BLE_MAX_CONN` to 1 if only one Bluetooth LE connection is needed.
- Set :menuitem:`CONFIG_BT_NIMBLE_MAX_CONNECTIONS` to 1 if only one Bluetooth LE connection is needed.
- Disable either :menuitem:`CONFIG_BT_NIMBLE_ROLE_CENTRAL` or :menuitem:`CONFIG_BT_NIMBLE_ROLE_OBSERVER` if these roles are not needed.
- Reducing :menuitem:`CONFIG_BT_NIMBLE_LOG_LEVEL` can reduce binary size. Note that if the overall log level has been reduced as described above in :ref:`reducing-overall-size` then this also reduces the NimBLE log level.
lwIP IPv6
@@@@@@@@@
- Setting :ref:`CONFIG_LWIP_IPV6` to ``false`` will reduce the size of the lwIP TCP/IP stack, at the cost of only supporting IPv4.
- Setting :menuitem:`CONFIG_LWIP_IPV6` to ``false`` will reduce the size of the lwIP TCP/IP stack, at the cost of only supporting IPv4.
.. note::
@@ -153,7 +153,7 @@ lwIP IPv6
lwIP IPv4
@@@@@@@@@
- If IPv4 connectivity is not required, setting :ref:`CONFIG_LWIP_IPV4` to ``false`` will reduce the size of the lwIP, supporting IPv6-only TCP/IP stack.
- If IPv4 connectivity is not required, setting :menuitem:`CONFIG_LWIP_IPV4` to ``false`` will reduce the size of the lwIP, supporting IPv6-only TCP/IP stack.
.. note::
@@ -164,7 +164,7 @@ lwIP IPv4
Picolibc instead of Newlib
@@@@@@@@@@@@@@@@@@@@@@@@@@
By default, ESP-IDF uses the Picolibc C library. Newlib is also supported and can be selected with :ref:`CONFIG_LIBC_NEWLIB<CONFIG_LIBC_NEWLIB>`.
By default, ESP-IDF uses the Picolibc C library. Newlib is also supported and can be selected with :menuitem:`CONFIG_LIBC_NEWLIB`.
Picolibc C library provides smaller ``printf`` family functions and can reduce the binary size by up to 30 KB, depending on your application.
@@ -177,13 +177,13 @@ By default, ESP-IDF uses Newlib "full" formatting for I/O functions (``printf()`
.. only:: CONFIG_ESP_ROM_HAS_NEWLIB_NANO_FORMAT
Enabling the config option :ref:`CONFIG_LIBC_NEWLIB_NANO_FORMAT` will switch Newlib to the "Nano" formatting mode. This is smaller in code size, and a large part of the implementation is compiled into the {IDF_TARGET_NAME} ROM, so it does not need to be included in the binary at all.
Enabling the config option :menuitem:`CONFIG_LIBC_NEWLIB_NANO_FORMAT` will switch Newlib to the "Nano" formatting mode. This is smaller in code size, and a large part of the implementation is compiled into the {IDF_TARGET_NAME} ROM, so it does not need to be included in the binary at all.
The exact difference in binary size depends on which features the firmware uses, but 25 KB ~ 50 KB is typical.
.. only:: CONFIG_ESP_ROM_HAS_NEWLIB_NORMAL_FORMAT
Disabling the config option :ref:`CONFIG_LIBC_NEWLIB_NANO_FORMAT` will switch Newlib to the "full" formatting mode. This will reduce the binary size, as {IDF_TARGET_NAME} has the full formatting version of the functions in ROM, so it does not need to be included in the binary at all.
Disabling the config option :menuitem:`CONFIG_LIBC_NEWLIB_NANO_FORMAT` will switch Newlib to the "full" formatting mode. This will reduce the binary size, as {IDF_TARGET_NAME} has the full formatting version of the functions in ROM, so it does not need to be included in the binary at all.
Enabling "Nano" formatting reduces the stack usage of each function that calls ``printf()`` or another string formatting function, see :ref:`optimize-stack-sizes`.
@@ -194,7 +194,7 @@ Enabling "Nano" formatting reduces the stack usage of each function that calls `
.. note::
:ref:`CONFIG_LIBC_NEWLIB_NANO_FORMAT` is enabled by default on {IDF_TARGET_NAME}.
:menuitem:`CONFIG_LIBC_NEWLIB_NANO_FORMAT` is enabled by default on {IDF_TARGET_NAME}.
.. _Newlib documentation: https://sourceware.org/newlib/docs.html
@@ -202,7 +202,7 @@ Enabling "Nano" formatting reduces the stack usage of each function that calls `
libstdc++
@@@@@@@@@
- Enable :ref:`CONFIG_COMPILER_CXX_GLIBCXX_CONSTEXPR_COLD_CONSTEXPR<CONFIG_COMPILER_CXX_GLIBCXX_CONSTEXPR_COLD_CONSTEXPR>` or :ref:`CONFIG_COMPILER_CXX_GLIBCXX_CONSTEXPR_COLD<CONFIG_COMPILER_CXX_GLIBCXX_CONSTEXPR_COLD>` to observe the impact on your application's binary size.
- Enable :menuitem:`CONFIG_COMPILER_CXX_GLIBCXX_CONSTEXPR_COLD_CONSTEXPR` or :menuitem:`CONFIG_COMPILER_CXX_GLIBCXX_CONSTEXPR_COLD` to observe the impact on your application's binary size.
.. _minimizing_binary_mbedtls:
@@ -215,23 +215,23 @@ These include:
.. list::
- :ref:`CONFIG_MBEDTLS_HAVE_TIME`
- :ref:`CONFIG_MBEDTLS_ECDSA_DETERMINISTIC`
- :ref:`CONFIG_MBEDTLS_SHA512_C`
- :ref:`CONFIG_MBEDTLS_CLIENT_SSL_SESSION_TICKETS`
- :ref:`CONFIG_MBEDTLS_SERVER_SSL_SESSION_TICKETS`
- :ref:`CONFIG_MBEDTLS_SSL_CONTEXT_SERIALIZATION`
- :ref:`CONFIG_MBEDTLS_SSL_ALPN`
- :ref:`CONFIG_MBEDTLS_SSL_RENEGOTIATION`
- :ref:`CONFIG_MBEDTLS_CCM_C`
- :ref:`CONFIG_MBEDTLS_GCM_C`
- :ref:`CONFIG_MBEDTLS_ECP_C` (Alternatively: Leave this option enabled but disable some of the elliptic curves listed in the sub-menu.)
- :ref:`CONFIG_MBEDTLS_ECP_NIST_OPTIM`
- :ref:`CONFIG_MBEDTLS_ECP_FIXED_POINT_OPTIM`
- Change :ref:`CONFIG_MBEDTLS_TLS_MODE` if both server & client functionalities are not needed.
- Consider disabling some cipher suites listed in the ``TLS Key Exchange Methods`` sub-menu (i.e., :ref:`CONFIG_MBEDTLS_KEY_EXCHANGE_RSA`).
- Consider disabling :ref:`CONFIG_MBEDTLS_ERROR_STRINGS` if the application is already pulling in mbedTLS error strings through using :cpp:func:`mbedtls_strerror`.
:esp32h2: - For {IDF_TARGET_NAME} v1.2 and above, consider disabling :ref:`CONFIG_MBEDTLS_HARDWARE_ECDSA_SIGN_MASKING_CM` and :ref:`CONFIG_MBEDTLS_HARDWARE_ECDSA_SIGN_CONSTANT_TIME_CM` as the software countermeasures for the ECDSA sign operation are not required.
- :menuitem:`CONFIG_MBEDTLS_HAVE_TIME`
- :menuitem:`CONFIG_MBEDTLS_ECDSA_DETERMINISTIC`
- :menuitem:`CONFIG_MBEDTLS_SHA512_C`
- :menuitem:`CONFIG_MBEDTLS_CLIENT_SSL_SESSION_TICKETS`
- :menuitem:`CONFIG_MBEDTLS_SERVER_SSL_SESSION_TICKETS`
- :menuitem:`CONFIG_MBEDTLS_SSL_CONTEXT_SERIALIZATION`
- :menuitem:`CONFIG_MBEDTLS_SSL_ALPN`
- :menuitem:`CONFIG_MBEDTLS_SSL_RENEGOTIATION`
- :menuitem:`CONFIG_MBEDTLS_CCM_C`
- :menuitem:`CONFIG_MBEDTLS_GCM_C`
- :menuitem:`CONFIG_MBEDTLS_ECP_C` (Alternatively: Leave this option enabled but disable some of the elliptic curves listed in the sub-menu.)
- :menuitem:`CONFIG_MBEDTLS_ECP_NIST_OPTIM`
- :menuitem:`CONFIG_MBEDTLS_ECP_FIXED_POINT_OPTIM`
- Change :menuitem:`CONFIG_MBEDTLS_TLS_MODE` if both server & client functionalities are not needed.
- Consider disabling some cipher suites listed in the ``TLS Key Exchange Methods`` sub-menu (i.e., :menuitem:`CONFIG_MBEDTLS_KEY_EXCHANGE_RSA`).
- Consider disabling :menuitem:`CONFIG_MBEDTLS_ERROR_STRINGS` if the application is already pulling in mbedTLS error strings through using :cpp:func:`mbedtls_strerror`.
:esp32h2: - For {IDF_TARGET_NAME} v1.2 and above, consider disabling :menuitem:`CONFIG_MBEDTLS_HARDWARE_ECDSA_SIGN_MASKING_CM` and :menuitem:`CONFIG_MBEDTLS_HARDWARE_ECDSA_SIGN_CONSTANT_TIME_CM` as the software countermeasures for the ECDSA sign operation are not required.
:SOC_AES_SUPPORT_DMA: - Consider disabling :ref:CONFIG_MBEDTLS_AES_HW_SMALL_DATA_LEN_OPTIM if the application does not involve or require performance optimization for operations that involve small data lengths, such as NVS encryption/decryption or TLS communication when performed on small data segments.
The help text for each option has some more information for reference.
@@ -247,10 +247,10 @@ The help text for each option has some more information for reference.
.. only:: CONFIG_ESP_ROM_HAS_MBEDTLS_CRYPTO_LIB
Enabling the config option :ref:`CONFIG_MBEDTLS_USE_CRYPTO_ROM_IMPL` will use the crypto algorithms from mbedTLS library inside the chip ROM.
Enabling the config option :menuitem:`CONFIG_MBEDTLS_USE_CRYPTO_ROM_IMPL` will use the crypto algorithms from mbedTLS library inside the chip ROM.
This option is available only when the selected target and minimum chip revision support the ROM mbedTLS crypto library.
Disabling the config option :ref:`CONFIG_MBEDTLS_USE_CRYPTO_ROM_IMPL` will use the crypto algorithms from the ESP-IDF mbedtls component library. This will increase the binary size (flash footprint).
Disabling the config option :menuitem:`CONFIG_MBEDTLS_USE_CRYPTO_ROM_IMPL` will use the crypto algorithms from the ESP-IDF mbedtls component library. This will increase the binary size (flash footprint).
.. note::
@@ -261,10 +261,10 @@ VFS
:doc:`/api-reference/storage/vfs` feature in ESP-IDF allows multiple filesystem drivers and file-like peripheral drivers to be accessed using standard I/O functions (``open``, ``read``, ``write``, etc.) and C library functions (``fopen``, ``fread``, ``fwrite``, etc.). When filesystem or file-like peripheral driver functionality is not used in the application, this feature can be fully or partially disabled. VFS component provides the following configuration options:
* :ref:`CONFIG_VFS_SUPPORT_TERMIOS` — can be disabled if the application does not use ``termios`` family of functions. Currently, these functions are implemented only for UART VFS driver. Most applications can disable this option. Disabling this option reduces the code size by about 1.8 KB.
* :ref:`CONFIG_VFS_SUPPORT_SELECT` — can be disabled if the application does not use the ``select`` function with file descriptors. Currently, only the UART and eventfd VFS drivers implement ``select`` support. Note that when this option is disabled, ``select`` can still be used for socket file descriptors. Disabling this option reduces the code size by about 2.7 KB.
* :ref:`CONFIG_VFS_SUPPORT_DIR` — can be disabled if the application does not use directory-related functions, such as ``readdir`` (see the description of this option for the complete list). Applications that only open, read and write specific files and do not need to enumerate or create directories can disable this option, reducing the code size by 0.5 KB or more, depending on the filesystem drivers in use.
* :ref:`CONFIG_VFS_SUPPORT_IO` — can be disabled if the application does not use filesystems or file-like peripheral drivers. This disables all VFS functionality, including the three options mentioned above. When this option is disabled, :doc:`/api-reference/system/console` can not be used. Note that the application can still use standard I/O functions with socket file descriptors when this option is disabled. Compared to the default configuration, disabling this option reduces code size by about 9.4 KB.
* :menuitem:`CONFIG_VFS_SUPPORT_TERMIOS` — can be disabled if the application does not use ``termios`` family of functions. Currently, these functions are implemented only for UART VFS driver. Most applications can disable this option. Disabling this option reduces the code size by about 1.8 KB.
* :menuitem:`CONFIG_VFS_SUPPORT_SELECT` — can be disabled if the application does not use the ``select`` function with file descriptors. Currently, only the UART and eventfd VFS drivers implement ``select`` support. Note that when this option is disabled, ``select`` can still be used for socket file descriptors. Disabling this option reduces the code size by about 2.7 KB.
* :menuitem:`CONFIG_VFS_SUPPORT_DIR` — can be disabled if the application does not use directory-related functions, such as ``readdir`` (see the description of this option for the complete list). Applications that only open, read and write specific files and do not need to enumerate or create directories can disable this option, reducing the code size by 0.5 KB or more, depending on the filesystem drivers in use.
* :menuitem:`CONFIG_VFS_SUPPORT_IO` — can be disabled if the application does not use filesystems or file-like peripheral drivers. This disables all VFS functionality, including the three options mentioned above. When this option is disabled, :doc:`/api-reference/system/console` can not be used. Note that the application can still use standard I/O functions with socket file descriptors when this option is disabled. Compared to the default configuration, disabling this option reduces code size by about 9.4 KB.
.. only:: CONFIG_ESP_ROM_HAS_HAL_SYSTIMER or CONFIG_ESP_ROM_HAS_HAL_WDT
@@ -273,16 +273,16 @@ VFS
.. list::
:CONFIG_ESP_ROM_HAS_HAL_SYSTIMER: * Enabling :ref:`CONFIG_HAL_SYSTIMER_USE_ROM_IMPL` can reduce the IRAM usage and binary size by linking in the systimer HAL driver of ROM implementation.
:CONFIG_ESP_ROM_HAS_HAL_WDT: * Enabling :ref:`CONFIG_HAL_WDT_USE_ROM_IMPL` can reduce the IRAM usage and binary size by linking in the watchdog HAL driver of ROM implementation.
:CONFIG_ESP_ROM_HAS_HAL_SYSTIMER: * Enabling :menuitem:`CONFIG_HAL_SYSTIMER_USE_ROM_IMPL` can reduce the IRAM usage and binary size by linking in the systimer HAL driver of ROM implementation.
:CONFIG_ESP_ROM_HAS_HAL_WDT: * Enabling :menuitem:`CONFIG_HAL_WDT_USE_ROM_IMPL` can reduce the IRAM usage and binary size by linking in the watchdog HAL driver of ROM implementation.
Heap
@@@@
.. list::
* Enabling :ref:`CONFIG_HEAP_PLACE_FUNCTION_INTO_FLASH` can reduce the IRAM usage and binary size by placing the entirety of the heap functionalities in flash memory.
:CONFIG_ESP_ROM_HAS_HEAP_TLSF: * Enabling :ref:`CONFIG_HEAP_TLSF_USE_ROM_IMPL` can reduce the IRAM usage and binary size by linking in the TLSF library of ROM implementation.
* Enabling :menuitem:`CONFIG_HEAP_PLACE_FUNCTION_INTO_FLASH` can reduce the IRAM usage and binary size by placing the entirety of the heap functionalities in flash memory.
:CONFIG_ESP_ROM_HAS_HEAP_TLSF: * Enabling :menuitem:`CONFIG_HEAP_TLSF_USE_ROM_IMPL` can reduce the IRAM usage and binary size by linking in the TLSF library of ROM implementation.
.. only:: SOC_USB_SERIAL_JTAG_SUPPORTED
@@ -292,8 +292,8 @@ VFS
For targets that support USB-Serial-JTAG, both the USB-Serial-JTAG and UART console output are enabled by default. If you only need one console, you can reduce the binary size and RAM usage by doing the following:
1. Disable the secondary console by setting :ref:`CONFIG_ESP_CONSOLE_SECONDARY` to ``CONFIG_ESP_CONSOLE_SECONDARY_NONE``.
2. Set :ref:`CONFIG_ESP_CONSOLE_UART` to use one of the following:
1. Disable the secondary console by setting :menuitem:`CONFIG_ESP_CONSOLE_SECONDARY` to ``CONFIG_ESP_CONSOLE_SECONDARY_NONE``.
2. Set :menuitem:`CONFIG_ESP_CONSOLE_UART` to use one of the following:
* ``UART`` reduces the binary size by around 2.5 KB.
* ``USB-Serial-JTAG`` reduces the binary size by around 10 KB and DRAM usage by around 1.5 KB.

66
docs/en/api-guides/performance/speed.rst
View File

@@ -68,7 +68,7 @@ The :doc:`/api-guides/tracing/transports` allows measuring code execution with m
Tasks
^^^^^
If the option :ref:`CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS` is enabled, then the FreeRTOS API :cpp:func:`vTaskGetRunTimeStats` can be used to retrieve runtime information about the processor time used by each FreeRTOS task.
If the option :menuitem:`CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS` is enabled, then the FreeRTOS API :cpp:func:`vTaskGetRunTimeStats` can be used to retrieve runtime information about the processor time used by each FreeRTOS task.
:ref:`SEGGER SystemView <app_trace-system-behaviour-analysis-with-segger-systemview>` is an excellent tool for visualizing task execution and looking for performance issues or improvements in the system as a whole.
@@ -79,11 +79,11 @@ The following optimizations improve the execution of nearly all code, including
.. list::
:esp32: - Set :ref:`CONFIG_ESPTOOLPY_FLASHFREQ` to 80 MHz. This is double the 40 MHz default value and doubles the speed at which code is loaded or executed from flash. You should verify that the board or module that connects the {IDF_TARGET_NAME} to the flash chip is rated for 80 MHz operation at the relevant temperature ranges before changing this setting. This information is contained in the hardware datasheet(s).
- Set :ref:`CONFIG_ESPTOOLPY_FLASHMODE` to QIO or QOUT mode (Quad I/O). Both almost double the speed at which code is loaded or executed from flash compared to the default DIO mode. QIO is slightly faster than QOUT if both are supported. Note that both the flash chip model, and the electrical connections between the {IDF_TARGET_NAME} and the flash chip must support quad I/O modes or the SoC will not work correctly.
- Set :ref:`CONFIG_COMPILER_OPTIMIZATION` to ``Optimize for performance (-O2)`` . This may slightly increase binary size compared to the default setting, but almost certainly increases the performance of some code. Note that if your code contains C or C++ Undefined Behavior, then increasing the compiler optimization level may expose bugs that otherwise are not seen.
:SOC_ASSIST_DEBUG_SUPPORTED: - Set :ref:`CONFIG_ESP_SYSTEM_HW_STACK_GUARD` to disabled. This may slightly increase the performance of some code, especially in cases where a lot of interrupts occur on the device.
:esp32: - If the application uses PSRAM and is based on ESP32 rev. 3 (ECO3), setting :ref:`CONFIG_ESP32_REV_MIN` to ``3`` disables PSRAM bug workarounds, reducing the code size and improving overall performance.
:esp32: - Set :menuitem:`CONFIG_ESPTOOLPY_FLASHFREQ` to 80 MHz. This is double the 40 MHz default value and doubles the speed at which code is loaded or executed from flash. You should verify that the board or module that connects the {IDF_TARGET_NAME} to the flash chip is rated for 80 MHz operation at the relevant temperature ranges before changing this setting. This information is contained in the hardware datasheet(s).
- Set :menuitem:`CONFIG_ESPTOOLPY_FLASHMODE` to QIO or QOUT mode (Quad I/O). Both almost double the speed at which code is loaded or executed from flash compared to the default DIO mode. QIO is slightly faster than QOUT if both are supported. Note that both the flash chip model, and the electrical connections between the {IDF_TARGET_NAME} and the flash chip must support quad I/O modes or the SoC will not work correctly.
- Set :menuitem:`CONFIG_COMPILER_OPTIMIZATION` to ``Optimize for performance (-O2)`` . This may slightly increase binary size compared to the default setting, but almost certainly increases the performance of some code. Note that if your code contains C or C++ Undefined Behavior, then increasing the compiler optimization level may expose bugs that otherwise are not seen.
:SOC_ASSIST_DEBUG_SUPPORTED: - Set :menuitem:`CONFIG_ESP_SYSTEM_HW_STACK_GUARD` to disabled. This may slightly increase the performance of some code, especially in cases where a lot of interrupts occur on the device.
:esp32: - If the application uses PSRAM and is based on ESP32 rev. 3 (ECO3), setting :menuitem:`CONFIG_ESP32_REV_MIN` to ``3`` disables PSRAM bug workarounds, reducing the code size and improving overall performance.
:SOC_CPU_HAS_FPU: - Avoid using floating point arithmetic ``float``. Even though {IDF_TARGET_NAME} has a single precision hardware floating point unit, floating point calculations are always slower than integer calculations. If possible then use fixed point representations, a different method of integer representation, or convert part of the calculation to be integer only before switching to floating point.
:not SOC_CPU_HAS_FPU: - Avoid using floating point arithmetic ``float``. On {IDF_TARGET_NAME} these calculations are emulated in software and are very slow. If possible, use fixed point representations, a different method of integer representation, or convert part of the calculation to be integer only before switching to floating point.
- Avoid using double precision floating point arithmetic ``double``. These calculations are emulated in software and are very slow. If possible then use an integer-based representation, or single-precision floating point.
@@ -98,11 +98,11 @@ The following optimizations improve the execution of nearly all code, including
.. list::
:esp32s2: - :ref:`CONFIG_ESP32S2_INSTRUCTION_CACHE_SIZE`.
:esp32s2: - :ref:`CONFIG_ESP32S2_DATA_CACHE_SIZE`.
:esp32s3: - :ref:`CONFIG_ESP32S3_INSTRUCTION_CACHE_SIZE`.
:esp32s3: - :ref:`CONFIG_ESP32S3_DATA_CACHE_SIZE`.
:esp32p4: - :ref:`CONFIG_CACHE_L2_CACHE_SIZE`.
:esp32s2: - :menuitem:`CONFIG_ESP32S2_INSTRUCTION_CACHE_SIZE`.
:esp32s2: - :menuitem:`CONFIG_ESP32S2_DATA_CACHE_SIZE`.
:esp32s3: - :menuitem:`CONFIG_ESP32S3_INSTRUCTION_CACHE_SIZE`.
:esp32s3: - :menuitem:`CONFIG_ESP32S3_DATA_CACHE_SIZE`.
:esp32p4: - :menuitem:`CONFIG_CACHE_L2_CACHE_SIZE`.
.. note::
@@ -114,7 +114,7 @@ The following optimizations improve the execution of nearly all code, including
.. note::
On {IDF_TARGET_NAME}, the L2 cache size is configurable via the Kconfig option :ref:`CONFIG_CACHE_L2_CACHE_SIZE`.
On {IDF_TARGET_NAME}, the L2 cache size is configurable via the Kconfig option :menuitem:`CONFIG_CACHE_L2_CACHE_SIZE`.
Setting the L2 cache size to its smallest value will maximize the available RAM while also potentially augmenting the frequency of "cache misses".
Setting the L2 cache size to its largest value will potentially lower the frequency of "cache misses" at the cost of reducing the available RAM.
@@ -125,10 +125,10 @@ Although standard output is buffered, it is possible for an application to be li
.. list::
- Reduce the volume of log output by lowering the app :ref:`CONFIG_LOG_DEFAULT_LEVEL` (the equivalent bootloader setting is :ref:`CONFIG_BOOTLOADER_LOG_LEVEL`). This also reduces the binary size, and saves some CPU time spent on string formatting.
:not SOC_USB_OTG_SUPPORTED: - Increase the speed of logging output by increasing the :ref:`CONFIG_ESP_CONSOLE_UART_BAUDRATE`.
:SOC_USB_OTG_SUPPORTED: - Increase the speed of logging output by increasing the :ref:`CONFIG_ESP_CONSOLE_UART_BAUDRATE`. However, if you are using internal USB-CDC, the serial throughput is not dependent on the configured baud rate.
- If your application does not require dynamic log level changes and you do not need to control logs per module using tags, consider disabling :ref:`CONFIG_LOG_DYNAMIC_LEVEL_CONTROL` and changing :ref:`CONFIG_LOG_TAG_LEVEL_IMPL`. It helps to reduce memory usage and also contributes to speeding up log operations in your application about 10 times.
- Reduce the volume of log output by lowering the app :menuitem:`CONFIG_LOG_DEFAULT_LEVEL` (the equivalent bootloader setting is :menuitem:`CONFIG_BOOTLOADER_LOG_LEVEL`). This also reduces the binary size, and saves some CPU time spent on string formatting.
:not SOC_USB_OTG_SUPPORTED: - Increase the speed of logging output by increasing the :menuitem:`CONFIG_ESP_CONSOLE_UART_BAUDRATE`.
:SOC_USB_OTG_SUPPORTED: - Increase the speed of logging output by increasing the :menuitem:`CONFIG_ESP_CONSOLE_UART_BAUDRATE`. However, if you are using internal USB-CDC, the serial throughput is not dependent on the configured baud rate.
- If your application does not require dynamic log level changes and you do not need to control logs per module using tags, consider disabling :menuitem:`CONFIG_LOG_DYNAMIC_LEVEL_CONTROL` and changing :menuitem:`CONFIG_LOG_TAG_LEVEL_IMPL`. It helps to reduce memory usage and also contributes to speeding up log operations in your application about 10 times.
Not Recommended
^^^^^^^^^^^^^^^
@@ -137,7 +137,7 @@ The following options also increase execution speed, but are not recommended as
.. list::
- Set :ref:`CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL` to disabled. This also reduces firmware binary size by a small amount. However, it may increase the severity of bugs in the firmware including security-related bugs. If it is necessary to do this to optimize a particular function, consider adding ``#define NDEBUG`` at the top of that single source file instead.
- Set :menuitem:`CONFIG_COMPILER_OPTIMIZATION_ASSERTION_LEVEL` to disabled. This also reduces firmware binary size by a small amount. However, it may increase the severity of bugs in the firmware including security-related bugs. If it is necessary to do this to optimize a particular function, consider adding ``#define NDEBUG`` at the top of that single source file instead.
.. _speed-targeted-optimizations:
@@ -155,7 +155,7 @@ The following changes increase the speed of a chosen part of the firmware applic
- Jump table optimizations can be re-enabled for individual source files that do not need to be placed in IRAM. For hot paths in large ``switch cases``, this improves performance. For instructions on how to add the ``-fjump-tables`` and ``-ftree-switch-conversion`` options when compiling individual source files, see :ref:`component_build_control`.
- Many ESP-IDF components and drivers provide configuration options to place performance-critical functions in IRAM for reduced latency and improved speed. These options typically have names like ``CONFIG_*_IN_IRAM``, ``CONFIG_*_ISR_IN_IRAM``, or ``CONFIG_*_IRAM_OPT``. Some examples are :ref:`CONFIG_FREERTOS_IN_IRAM` for FreeRTOS functions, :ref:`CONFIG_ESP_WIFI_IRAM_OPT` for Wi-Fi operations, :ref:`CONFIG_UART_ISR_IN_IRAM` for UART interrupt handling, and :ref:`CONFIG_SPI_MASTER_ISR_IN_IRAM` for SPI operations. These options trade IRAM usage for speed, so they should be used selectively based on your application's performance requirements and available IRAM space.
- Many ESP-IDF components and drivers provide configuration options to place performance-critical functions in IRAM for reduced latency and improved speed. These options typically have names like ``CONFIG_*_IN_IRAM``, ``CONFIG_*_ISR_IN_IRAM``, or ``CONFIG_*_IRAM_OPT``. Some examples are :menuitem:`CONFIG_FREERTOS_IN_IRAM` for FreeRTOS functions, :menuitem:`CONFIG_ESP_WIFI_IRAM_OPT` for Wi-Fi operations, :menuitem:`CONFIG_UART_ISR_IN_IRAM` for UART interrupt handling, and :menuitem:`CONFIG_SPI_MASTER_ISR_IN_IRAM` for SPI operations. These options trade IRAM usage for speed, so they should be used selectively based on your application's performance requirements and available IRAM space.
Improving Startup Time
----------------------
@@ -164,12 +164,12 @@ In addition to the overall performance improvements shown above, the following o
.. list::
- Minimizing the :ref:`CONFIG_LOG_DEFAULT_LEVEL` and :ref:`CONFIG_BOOTLOADER_LOG_LEVEL` has a large impact on startup time. To enable more logging after the app starts up, set the :ref:`CONFIG_LOG_MAXIMUM_LEVEL` as well, and then call :cpp:func:`esp_log_level_set` to restore higher level logs. The :example:`system/startup_time` main function shows how to do this.
:SOC_RTC_FAST_MEM_SUPPORTED: - If using Deep-sleep mode, setting :ref:`CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP` allows a faster wake from sleep. Note that if using Secure Boot, this represents a security compromise, as Secure Boot validation are not be performed on wake.
- Setting :ref:`CONFIG_BOOTLOADER_SKIP_VALIDATE_ON_POWER_ON` skips verifying the binary on every boot from the power-on reset. How much time this saves depends on the binary size and the flash settings. Note that this setting carries some risk if the flash becomes corrupt unexpectedly. Read the help text of the :ref:`config item <CONFIG_BOOTLOADER_SKIP_VALIDATE_ON_POWER_ON>` for an explanation and recommendations if using this option.
- It is possible to save a small amount of time during boot by disabling RTC slow clock calibration. To do so, set :ref:`CONFIG_RTC_CLK_CAL_CYCLES` to 0. Any part of the firmware that uses RTC slow clock as a timing source will be less accurate as a result.
:SOC_SPIRAM_SUPPORTED: - When external memory is used (:ref:`CONFIG_SPIRAM` enabled), enabling memory test on the external memory (:ref:`CONFIG_SPIRAM_MEMTEST`) can have a large impact on startup time (approximately 1 second per 4 MB of memory tested). Disabling the memory tests will reduce startup time at the expense of testing the external memory.
:SOC_SPIRAM_SUPPORTED: - When external memory is used (:ref:`CONFIG_SPIRAM` enabled), enabling comprehensive poisoning will increase the startup time (approximately 300 milliseconds per 4 MiB of memory set) since all the memory used as heap (including the external memory) will be set to a default value.
- Minimizing the :menuitem:`CONFIG_LOG_DEFAULT_LEVEL` and :menuitem:`CONFIG_BOOTLOADER_LOG_LEVEL` has a large impact on startup time. To enable more logging after the app starts up, set the :menuitem:`CONFIG_LOG_MAXIMUM_LEVEL` as well, and then call :cpp:func:`esp_log_level_set` to restore higher level logs. The :example:`system/startup_time` main function shows how to do this.
:SOC_RTC_FAST_MEM_SUPPORTED: - If using Deep-sleep mode, setting :menuitem:`CONFIG_BOOTLOADER_SKIP_VALIDATE_IN_DEEP_SLEEP` allows a faster wake from sleep. Note that if using Secure Boot, this represents a security compromise, as Secure Boot validation are not be performed on wake.
- Setting :menuitem:`CONFIG_BOOTLOADER_SKIP_VALIDATE_ON_POWER_ON` skips verifying the binary on every boot from the power-on reset. How much time this saves depends on the binary size and the flash settings. Note that this setting carries some risk if the flash becomes corrupt unexpectedly. Read the help text of the :menuitem:`config item <CONFIG_BOOTLOADER_SKIP_VALIDATE_ON_POWER_ON>` for an explanation and recommendations if using this option.
- It is possible to save a small amount of time during boot by disabling RTC slow clock calibration. To do so, set :menuitem:`CONFIG_RTC_CLK_CAL_CYCLES` to 0. Any part of the firmware that uses RTC slow clock as a timing source will be less accurate as a result.
:SOC_SPIRAM_SUPPORTED: - When external memory is used (:menuitem:`CONFIG_SPIRAM` enabled), enabling memory test on the external memory (:menuitem:`CONFIG_SPIRAM_MEMTEST`) can have a large impact on startup time (approximately 1 second per 4 MB of memory tested). Disabling the memory tests will reduce startup time at the expense of testing the external memory.
:SOC_SPIRAM_SUPPORTED: - When external memory is used (:menuitem:`CONFIG_SPIRAM` enabled), enabling comprehensive poisoning will increase the startup time (approximately 300 milliseconds per 4 MiB of memory set) since all the memory used as heap (including the external memory) will be set to a default value.
The example project :example:`system/startup_time` is pre-configured to optimize startup time. The file :example_file:`system/startup_time/sdkconfig.defaults` contain all of these settings. You can append these to the end of your project's own ``sdkconfig`` file to merge the settings, but please read the documentation for each setting first.
@@ -201,7 +201,7 @@ Common priorities are:
- :ref:`app-main-task` that executes app_main function has minimum priority (1).
- :doc:`/api-reference/system/esp_timer` system task to manage timer events and execute callbacks has high priority (22, ``ESP_TASK_TIMER_PRIO``)
- FreeRTOS Timer Task to handle FreeRTOS timer callbacks is created when the scheduler initializes and has minimum task priority (1, :ref:`configurable <CONFIG_FREERTOS_TIMER_TASK_PRIORITY>`).
- FreeRTOS Timer Task to handle FreeRTOS timer callbacks is created when the scheduler initializes and has minimum task priority (1, :menuitem:`configurable <CONFIG_FREERTOS_TIMER_TASK_PRIORITY>`).
- :doc:`/api-reference/system/esp_event` system task to manage the default system event loop and execute callbacks has high priority (20, ``ESP_TASK_EVENT_PRIO``). This configuration is only used if the application calls :cpp:func:`esp_event_loop_create_default`. It is possible to call :cpp:func:`esp_event_loop_create` with a custom task configuration instead.
- :doc:`/api-guides/lwip` TCP/IP task has high priority (18, ``ESP_TASK_TCPIP_PRIO``).
:SOC_WIFI_SUPPORTED: - :doc:`/api-guides/wifi-driver/index` task has high priority (23).
@@ -215,21 +215,21 @@ Common priorities are:
.. list::
- :ref:`app-main-task` that executes app_main function has minimum priority (1). This task is pinned to Core 0 by default (:ref:`configurable<CONFIG_ESP_MAIN_TASK_AFFINITY>`).
- :ref:`app-main-task` that executes app_main function has minimum priority (1). This task is pinned to Core 0 by default (:menuitem:`configurable <CONFIG_ESP_MAIN_TASK_AFFINITY>`).
- :doc:`/api-reference/system/esp_timer` system task to manage high precision timer events and execute callbacks has high priority (22, ``ESP_TASK_TIMER_PRIO``). This task is pinned to Core 0.
- FreeRTOS Timer Task to handle FreeRTOS timer callbacks is created when the scheduler initializes and has minimum task priority (1, :ref:`configurable <CONFIG_FREERTOS_TIMER_TASK_PRIORITY>`). This task is pinned to Core 0.
- FreeRTOS Timer Task to handle FreeRTOS timer callbacks is created when the scheduler initializes and has minimum task priority (1, :menuitem:`configurable <CONFIG_FREERTOS_TIMER_TASK_PRIORITY>`). This task is pinned to Core 0.
- :doc:`/api-reference/system/esp_event` system task to manage the default system event loop and execute callbacks has high priority (20, ``ESP_TASK_EVENT_PRIO``) and it is pinned to Core 0. This configuration is only used if the application calls :cpp:func:`esp_event_loop_create_default`, it is possible to call :cpp:func:`esp_event_loop_create` with a custom task configuration instead.
- :doc:`/api-guides/lwip` TCP/IP task has high priority (18, ``ESP_TASK_TCPIP_PRIO``) and is not pinned to any core (:ref:`configurable<CONFIG_LWIP_TCPIP_TASK_AFFINITY>`).
:SOC_WIFI_SUPPORTED: - :doc:`/api-guides/wifi-driver/index` task has high priority (23) and is pinned to Core 0 by default (:ref:`configurable<CONFIG_ESP_WIFI_TASK_CORE_ID>`).
- :doc:`/api-guides/lwip` TCP/IP task has high priority (18, ``ESP_TASK_TCPIP_PRIO``) and is not pinned to any core (:menuitem:`configurable <CONFIG_LWIP_TCPIP_TASK_AFFINITY>`).
:SOC_WIFI_SUPPORTED: - :doc:`/api-guides/wifi-driver/index` task has high priority (23) and is pinned to Core 0 by default (:menuitem:`configurable <CONFIG_ESP_WIFI_TASK_CORE_ID>`).
:SOC_WIFI_SUPPORTED: - Wi-Fi wpa_supplicant component may create dedicated tasks while the Wi-Fi Protected Setup (WPS), WPA2 EAP-TLS, Device Provisioning Protocol (DPP) or BSS Transition Management (BTM) features are in use. These tasks all have low priority (2) and are not pinned to any core.
:SOC_BT_SUPPORTED: - :doc:`/api-reference/bluetooth/controller_vhci` task has high priority (23, ``ESP_TASK_BT_CONTROLLER_PRIO``) and is pinned to Core 0 by default (:ref:`configurable <{IDF_TARGET_CONTROLLER_CORE_CONFIG}>`). The Bluetooth Controller needs to respond to requests with low latency, so it should always be among the highest priority task assigned to a single CPU.
:SOC_BT_SUPPORTED: - :doc:`/api-reference/bluetooth/nimble/index` task has high priority (21) and is pinned to Core 0 by default (:ref:`configurable <CONFIG_BT_NIMBLE_PINNED_TO_CORE_CHOICE>`).
:SOC_BT_SUPPORTED: - :doc:`/api-reference/bluetooth/controller_vhci` task has high priority (23, ``ESP_TASK_BT_CONTROLLER_PRIO``) and is pinned to Core 0 by default (:menuitem:`configurable <{IDF_TARGET_CONTROLLER_CORE_CONFIG}>`). The Bluetooth Controller needs to respond to requests with low latency, so it should always be among the highest priority task assigned to a single CPU.
:SOC_BT_SUPPORTED: - :doc:`/api-reference/bluetooth/nimble/index` task has high priority (21) and is pinned to Core 0 by default (:menuitem:`configurable <CONFIG_BT_NIMBLE_PINNED_TO_CORE_CHOICE>`).
:esp32: - :doc:`/api-reference/bluetooth/index` creates multiple tasks when used:
- Stack event callback task ("BTC") has high priority (19).
- Stack BTU layer task has high priority (20).
- Host HCI host task has high priority (22).
All Bluedroid Tasks are pinned to the same core, which is Core 0 by default (:ref:`configurable <CONFIG_BT_BLUEDROID_PINNED_TO_CORE_CHOICE>`).
All Bluedroid Tasks are pinned to the same core, which is Core 0 by default (:menuitem:`configurable <CONFIG_BT_BLUEDROID_PINNED_TO_CORE_CHOICE>`).
- The Ethernet driver creates a task for the MAC to receive Ethernet frames. If using the default config ``ETH_MAC_DEFAULT_CONFIG`` then the priority is medium-high (15) and the task is not pinned to any core. These settings can be changed by passing a custom :cpp:class:`eth_mac_config_t` struct when initializing the Ethernet MAC.
- To see what is the task priority for ``mDNS`` service, please check `Performance Optimization <https://docs.espressif.com/projects/esp-protocols/mdns/docs/latest/en/index.html#performance-optimization>`__.
@@ -254,7 +254,7 @@ Choosing Task Priorities of the Application
.. only:: not SOC_HP_CPU_HAS_MULTIPLE_CORES
With a few exceptions, most importantly the lwIP TCP/IP task, in the default configuration most built-in tasks are pinned to Core 0. This makes it quite easy for the application to place high priority tasks on Core 1. Using priority 19 or higher guarantees that an application task can run on Core 1 without being preempted by any built-in task. To further isolate the tasks running on each CPU, configure the :ref:`lwIP task <CONFIG_LWIP_TCPIP_TASK_AFFINITY>` to only run on Core 0 instead of either core, which may reduce total TCP/IP throughput depending on what other tasks are running.
With a few exceptions, most importantly the lwIP TCP/IP task, in the default configuration most built-in tasks are pinned to Core 0. This makes it quite easy for the application to place high priority tasks on Core 1. Using priority 19 or higher guarantees that an application task can run on Core 1 without being preempted by any built-in task. To further isolate the tasks running on each CPU, configure the :menuitem:`lwIP task <CONFIG_LWIP_TCPIP_TASK_AFFINITY>` to only run on Core 0 instead of either core, which may reduce total TCP/IP throughput depending on what other tasks are running.
.. only:: SOC_WIFI_SUPPORTED or SOC_BT_SUPPORTED or SOC_IEEE802154_SUPPORTED

4
docs/en/api-guides/reproducible-builds.rst
View File

@@ -29,7 +29,7 @@ There are also other possible reasons, such as unstable order of inputs and non-
Enabling Reproducible Builds in ESP-IDF
---------------------------------------
Reproducible builds can be enabled in ESP-IDF using :ref:`CONFIG_APP_REPRODUCIBLE_BUILD` option.
Reproducible builds can be enabled in ESP-IDF using :menuitem:`CONFIG_APP_REPRODUCIBLE_BUILD` option.
This option is disabled by default. It can be enabled in ``menuconfig``.
@@ -49,7 +49,7 @@ ESP-IDF achieves reproducible builds using the following measures:
- Paths to components are replaced with ``/COMPONENT_NAME_DIR`` (where ``NAME`` is the name of the component)
- Path to the toolchain is replaced with ``/TOOLCHAIN``
- Build date and time are not included into the :ref:`application metadata structure <app-image-format-application-description>` and :ref:`bootloader metadata structure <image-format-bootloader-description>` if :ref:`CONFIG_APP_REPRODUCIBLE_BUILD` is enabled.
- Build date and time are not included into the :ref:`application metadata structure <app-image-format-application-description>` and :ref:`bootloader metadata structure <image-format-bootloader-description>` if :menuitem:`CONFIG_APP_REPRODUCIBLE_BUILD` is enabled.
- ESP-IDF build system ensures that source file lists, component lists and other sequences are sorted before passing them to CMake. Various other parts of the build system, such as the linker script generator also perform sorting to ensure that same output is produced regardless of the environment.
.. _reproducible-builds-and-debugging:

14
docs/en/api-guides/startup.rst
View File

@@ -74,7 +74,7 @@ In ESP-IDF, the binary image which resides at offset {IDF_TARGET_CONFIG_BOOTLOAD
When the first stage (ROM) bootloader is finished checking and loading the second stage bootloader, it jumps to the second stage bootloader entry point found in the binary image header.
Second stage bootloader reads the partition table found by default at offset {IDF_TARGET_CONFIG_PARTITION_TABLE_OFFSET} (:ref:`configurable value <CONFIG_PARTITION_TABLE_OFFSET>`). See :doc:`partition tables <partition-tables>` documentation for more information. The bootloader finds factory and OTA app partitions. If OTA app partitions are found in the partition table, the bootloader consults the ``otadata`` partition to determine which one should be booted. See :doc:`/api-reference/system/ota` for more information.
Second stage bootloader reads the partition table found by default at offset {IDF_TARGET_CONFIG_PARTITION_TABLE_OFFSET} (:menuitem:`configurable value <CONFIG_PARTITION_TABLE_OFFSET>`). See :doc:`partition tables <partition-tables>` documentation for more information. The bootloader finds factory and OTA app partitions. If OTA app partitions are found in the partition table, the bootloader consults the ``otadata`` partition to determine which one should be booted. See :doc:`/api-reference/system/ota` for more information.
For a full description of the configuration options available for the ESP-IDF bootloader, see :doc:`bootloader`.
@@ -114,7 +114,7 @@ This port-layer initialization function initializes the basic C Runtime Environm
.. list::
- Reconfigure CPU exceptions for the app (allowing app interrupt handlers to run, and causing :doc:`fatal-errors` to be handled using the options configured for the app rather than the simpler error handler provided by ROM).
- If the option :ref:`CONFIG_BOOTLOADER_WDT_ENABLE` is not set then the RTC watchdog timer is disabled.
- If the option :menuitem:`CONFIG_BOOTLOADER_WDT_ENABLE` is not set then the RTC watchdog timer is disabled.
- Initialize internal memory (data & bss).
- Finish configuring the MMU cache.
:SOC_SPIRAM_SUPPORTED: - Enable PSRAM if configured.
@@ -144,9 +144,9 @@ The primary system initialization stage includes:
- Initialize the heap allocator (before this point all allocations must be static or on the stack).
- Initialize esp_libc component syscalls and time functions.
- Configure the brownout detector.
- Setup libc stdin, stdout, and stderr according to the :ref:`serial console configuration <CONFIG_ESP_CONSOLE_UART>`.
:esp32: - Perform any security-related checks, including burning efuses that should be burned for this configuration (including :ref:`disabling ROM download mode on ESP32 V3 <CONFIG_SECURE_UART_ROM_DL_MODE>`, :ref:`CONFIG_ESP32_DISABLE_BASIC_ROM_CONSOLE`).
:not esp32: - Perform any security-related checks, including burning efuses that should be burned for this configuration (including :ref:`permanently limiting ROM download modes <CONFIG_SECURE_UART_ROM_DL_MODE>`).
- Setup libc stdin, stdout, and stderr according to the :menuitem:`serial console configuration <CONFIG_ESP_CONSOLE_UART>`.
:esp32: - Perform any security-related checks, including burning efuses that should be burned for this configuration (including :menuitem:`disabling ROM download mode on ESP32 V3 <CONFIG_SECURE_UART_ROM_DL_MODE>`, :menuitem:`CONFIG_ESP32_DISABLE_BASIC_ROM_CONSOLE`).
:not esp32: - Perform any security-related checks, including burning efuses that should be burned for this configuration (including :menuitem:`permanently limiting ROM download modes <CONFIG_SECURE_UART_ROM_DL_MODE>`).
- Initialize SPI flash API support.
- Call global C++ constructors and any C functions marked with ``__attribute__((constructor))``.
@@ -161,11 +161,11 @@ After all other components are initialized, the main task is created and the Fre
After doing some more initialization tasks (that require the scheduler to have started), the main task runs the application-provided function ``app_main`` in the firmware.
The main task that runs ``app_main`` has a fixed RTOS priority (one higher than the minimum) and a :ref:`configurable stack size <CONFIG_ESP_MAIN_TASK_STACK_SIZE>`.
The main task that runs ``app_main`` has a fixed RTOS priority (one higher than the minimum) and a :menuitem:`configurable stack size <CONFIG_ESP_MAIN_TASK_STACK_SIZE>`.
.. only:: SOC_HP_CPU_HAS_MULTIPLE_CORES
The main task core affinity is also configurable: :ref:`CONFIG_ESP_MAIN_TASK_AFFINITY`.
The main task core affinity is also configurable: :menuitem:`CONFIG_ESP_MAIN_TASK_AFFINITY`.
Unlike normal FreeRTOS tasks (or embedded C ``main`` functions), the ``app_main`` task is allowed to return. If this happens, The task is cleaned up and the system will continue running with other RTOS tasks scheduled normally. Therefore, it is possible to implement ``app_main`` as either a function that creates other application tasks and then returns, or as a main application task itself.

26
docs/en/api-guides/stdio.rst
View File

@@ -33,11 +33,11 @@ Built-in implementations of standard I/O can be selected using several Kconfig o
.. list::
- :ref:`CONFIG_ESP_CONSOLE_UART_DEFAULT<CONFIG_ESP_CONSOLE_UART_DEFAULT>` — Enables UART with default options (pin numbers, baud rate) for standard I/O.
- :ref:`CONFIG_ESP_CONSOLE_UART_CUSTOM<CONFIG_ESP_CONSOLE_UART_CUSTOM>` — Enables UART for standard I/O, with TX/RX pin numbers and baud rate configurable via Kconfig.
:SOC_USB_OTG_CONSOLE_SUPPORTED: - :ref:`CONFIG_ESP_CONSOLE_USB_CDC<CONFIG_ESP_CONSOLE_USB_CDC>` — Enables USB CDC (using USB_OTG peripheral) for standard I/O. See :doc:`usb-otg-console` for details about hardware connections required.
:SOC_USB_SERIAL_JTAG_SUPPORTED: - :ref:`CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG<CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG>` — Enables USB Serial/JTAG for standard I/O. See :doc:`usb-serial-jtag-console` for details about hardware connections required.
- :ref:`CONFIG_ESP_CONSOLE_NONE<CONFIG_ESP_CONSOLE_NONE>` — Disables standard I/O. If this option is selected, ``stdin``, ``stdout``, and ``stderr`` will be mapped to ``/dev/null`` and won't produce any output or generate any input.
- :menuitem:`CONFIG_ESP_CONSOLE_UART_DEFAULT` — Enables UART with default options (pin numbers, baud rate) for standard I/O.
- :menuitem:`CONFIG_ESP_CONSOLE_UART_CUSTOM` — Enables UART for standard I/O, with TX/RX pin numbers and baud rate configurable via Kconfig.
:SOC_USB_OTG_CONSOLE_SUPPORTED: - :menuitem:`CONFIG_ESP_CONSOLE_USB_CDC` — Enables USB CDC (using USB_OTG peripheral) for standard I/O. See :doc:`usb-otg-console` for details about hardware connections required.
:SOC_USB_SERIAL_JTAG_SUPPORTED: - :menuitem:`CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG` — Enables USB Serial/JTAG for standard I/O. See :doc:`usb-serial-jtag-console` for details about hardware connections required.
- :menuitem:`CONFIG_ESP_CONSOLE_NONE` — Disables standard I/O. If this option is selected, ``stdin``, ``stdout``, and ``stderr`` will be mapped to ``/dev/null`` and won't produce any output or generate any input.
Enabling one of these options will cause the corresponding VFS driver to be built into the application and used to open ``stdin``, ``stdout``, and ``stderr`` streams. Data written to ``stdout`` and ``stderr`` will be sent over the selected interface, and input from the selected interface will be available on ``stdin``.
@@ -55,12 +55,12 @@ Enabling one of these options will cause the corresponding VFS driver to be buil
The following secondary console options are available:
- :ref:`CONFIG_ESP_CONSOLE_SECONDARY_USB_SERIAL_JTAG<CONFIG_ESP_CONSOLE_SECONDARY_USB_SERIAL_JTAG>`
- :menuitem:`CONFIG_ESP_CONSOLE_SECONDARY_USB_SERIAL_JTAG`
Standard Streams and FreeRTOS Tasks
-----------------------------------
ESP-IDF provides two different implementations of standard I/O streams based on the selected LibC implementation defined by :ref:`CONFIG_LIBC`. The behavior of ``stdin``, ``stdout``, and ``stderr`` streams differs between these implementations, particularly regarding how they are shared across FreeRTOS tasks.
ESP-IDF provides two different implementations of standard I/O streams based on the selected LibC implementation defined by :menuitem:`CONFIG_LIBC`. The behavior of ``stdin``, ``stdout``, and ``stderr`` streams differs between these implementations, particularly regarding how they are shared across FreeRTOS tasks.
Common to both implementations, each stream (``stdin``, ``stdout``, ``stderr``) has a mutex associated with it to protect the stream from concurrent access by multiple tasks. For example, if two tasks are writing to ``stdout`` at the same time, the mutex ensures that the outputs from each task are not mixed together.
@@ -117,13 +117,13 @@ VFS drivers provide an optional newline conversion feature for input and output.
Applications can configure this behavior globally using the following Kconfig options:
- For output
- :ref:`CONFIG_LIBC_STDOUT_LINE_ENDING_CRLF<CONFIG_LIBC_STDOUT_LINE_ENDING_CRLF>`
- :ref:`CONFIG_LIBC_STDOUT_LINE_ENDING_CR<CONFIG_LIBC_STDOUT_LINE_ENDING_CR>`
- :ref:`CONFIG_LIBC_STDOUT_LINE_ENDING_LF<CONFIG_LIBC_STDOUT_LINE_ENDING_LF>`
- :menuitem:`CONFIG_LIBC_STDOUT_LINE_ENDING_CRLF`
- :menuitem:`CONFIG_LIBC_STDOUT_LINE_ENDING_CR`
- :menuitem:`CONFIG_LIBC_STDOUT_LINE_ENDING_LF`
- For input
- :ref:`CONFIG_LIBC_STDIN_LINE_ENDING_CRLF<CONFIG_LIBC_STDIN_LINE_ENDING_CRLF>`
- :ref:`CONFIG_LIBC_STDIN_LINE_ENDING_CR<CONFIG_LIBC_STDIN_LINE_ENDING_CR>`
- :ref:`CONFIG_LIBC_STDIN_LINE_ENDING_LF<CONFIG_LIBC_STDIN_LINE_ENDING_LF>`
- :menuitem:`CONFIG_LIBC_STDIN_LINE_ENDING_CRLF`
- :menuitem:`CONFIG_LIBC_STDIN_LINE_ENDING_CR`
- :menuitem:`CONFIG_LIBC_STDIN_LINE_ENDING_LF`
It is also possible to configure line ending conversion for the specific VFS driver:

2
docs/en/api-guides/thread-local-storage.rst
View File

@@ -23,7 +23,7 @@ The ESP-IDF FreeRTOS provides the following APIs to manage thread local variable
- :cpp:func:`pvTaskGetThreadLocalStoragePointer`
- :cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback`
In this case, the maximum number of variables that can be allocated is limited by :ref:`CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS`. Variables are kept in the task control block (TCB) and accessed by their index. Note that index 0 is reserved for ESP-IDF internal uses.
In this case, the maximum number of variables that can be allocated is limited by :menuitem:`CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS`. Variables are kept in the task control block (TCB) and accessed by their index. Note that index 0 is reserved for ESP-IDF internal uses.
Using the APIs above, you can allocate thread local variables of an arbitrary size, and assign them to any number of tasks. Different tasks can have different sets of TLS variables.

10
docs/en/api-guides/tools/idf-monitor.rst
View File

@@ -61,7 +61,7 @@ For easy interaction with IDF Monitor, use the keyboard shortcuts given in the t
-
* - Ctrl + C
- Interrupt running application
- Pause IDF Monitor and runs GDB_ project debugger to debug the application at runtime. This requires :ref:`CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME` option to be enabled.
- Pause IDF Monitor and runs GDB_ project debugger to debug the application at runtime. This requires :menuitem:`CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME` option to be enabled.
Any keys pressed, other than ``Ctrl-]`` and ``Ctrl-T``, will be sent through the serial port.
@@ -73,7 +73,7 @@ IDF Monitor automatically colors the output based on the log level. This feature
The automatic coloring is enabled by default. To disable it, use the command line option ``--disable-auto-color``.
The coloring is done based on the log level followed by optional timestamp and tag. For option to enable coloring on the {IDF_TARGET_NAME} side, see :ref:`CONFIG_LOG_COLORS`.
The coloring is done based on the log level followed by optional timestamp and tag. For option to enable coloring on the {IDF_TARGET_NAME} side, see :menuitem:`CONFIG_LOG_COLORS`.
For more details on the log, see :doc:`Logging <../../api-reference/system/log>`.
@@ -275,9 +275,9 @@ Launching GDB with GDBStub
GDBStub is a useful runtime debugging feature that runs on the target and connects to the host over the serial port to receive debugging commands. GDBStub supports commands such as reading memory and variables, examining call stack frames etc. Although GDBStub is less versatile than JTAG debugging, it does not require any special hardware (such as a JTAG to USB bridge) as communication is done entirely over the serial port.
A target can be configured to run GDBStub in the background by setting the :ref:`CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME`. GDBStub will run in the background until a ``Ctrl+C`` message is sent over the serial port and causes the GDBStub to break (i.e., stop the execution of) the program, thus allowing GDBStub to handle debugging commands.
A target can be configured to run GDBStub in the background by setting the :menuitem:`CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME`. GDBStub will run in the background until a ``Ctrl+C`` message is sent over the serial port and causes the GDBStub to break (i.e., stop the execution of) the program, thus allowing GDBStub to handle debugging commands.
Furthermore, the panic handler can be configured to run GDBStub on a crash by setting the :ref:`CONFIG_ESP_SYSTEM_PANIC` to ``GDBStub on panic``. When a crash occurs, GDBStub will output a special string pattern over the serial port to indicate that it is running.
Furthermore, the panic handler can be configured to run GDBStub on a crash by setting the :menuitem:`CONFIG_ESP_SYSTEM_PANIC` to ``GDBStub on panic``. When a crash occurs, GDBStub will output a special string pattern over the serial port to indicate that it is running.
In both cases (i.e., sending the ``Ctrl+C`` message, or receiving the special string pattern), IDF Monitor will automatically launch GDB in order to allow the user to send debugging commands. After GDB exits, the target is reset via the RTS serial line. If this line is not connected, users can reset their target (by pressing the board's Reset button).
@@ -409,7 +409,7 @@ The following issues are currently known:
- Autocoloring cannot detect the log level if the message contains new lines. In this case, the IDF Monitor will only color the first line of the message.
To work around this issue, enable :ref:`CONFIG_LOG_COLORS` in menuconfig. Please note that this might have some impact on binary size and performance.
To work around this issue, enable :menuitem:`CONFIG_LOG_COLORS` in menuconfig. Please note that this might have some impact on binary size and performance.
- On Windows, if the terminal is closed without first closing the IDF Monitor, some drivers may fail to release the serial port. To release the port, you may need to unplug and replug the USB cable, or in some cases even restart the computer. This issue has been observed with the CH9102 USB-to-UART bridge. Other drivers, such as CP210x and CH340, should work fine.

2
docs/en/api-guides/tools/idf-py.rst
View File

@@ -134,7 +134,7 @@ When no ``*_flashed.bin`` files are present, ``idf.py flash`` configures esptool
After each successful flash, the build system saves copies of all flashed files (bootloader, partition table, app, and any other assets) with an ``_flashed`` suffix in the build directory (e.g., ``bootloader_flashed.bin``, ``partition-table_flashed.bin``). These are used automatically on the next ``idf.py flash`` for fast reflashing.
Fast reflashing works with or without the :ref:`CONFIG_APP_BUILD_MINIMIZE_BINARY_CHANGES` option. Enabling that option can further improve reflash effectiveness by laying out the application binary so that changes are localized. This results in less flash sectors needing to be rewritten. This option may increase the size of the application binary and is not recommended for production builds.
Fast reflashing works with or without the :menuitem:`CONFIG_APP_BUILD_MINIMIZE_BINARY_CHANGES` option. Enabling that option can further improve reflash effectiveness by laying out the application binary so that changes are localized. This results in less flash sectors needing to be rewritten. This option may increase the size of the application binary and is not recommended for production builds.
Full Flash
^^^^^^^^^^

4
docs/en/api-guides/tools/idf-size.rst
View File

@@ -143,7 +143,7 @@ The table is sorted in descending order of the total contribution of the static
.. note::
The size of the ``.rodata`` section in the ``Flash Data`` memory type may appear very large for a single archive. This occurs due to linker relaxations. The linker may attempt to combine object file sections with ``MERGE`` and ``STRINGS`` flags from all archives into one to perform tail string optimization. Consequently, one archive may end up with a very large ``.rodata`` section, containing string literals from other archives. This is evident in the ``.rodata`` section of the ``libesp_app_format.a`` archive. The specific compiler behavior here can be turned off by enabling :ref:`CONFIG_COMPILER_NO_MERGE_CONSTANTS` option (only for GCC toolchain), please read help for more details.
The size of the ``.rodata`` section in the ``Flash Data`` memory type may appear very large for a single archive. This occurs due to linker relaxations. The linker may attempt to combine object file sections with ``MERGE`` and ``STRINGS`` flags from all archives into one to perform tail string optimization. Consequently, one archive may end up with a very large ``.rodata`` section, containing string literals from other archives. This is evident in the ``.rodata`` section of the ``libesp_app_format.a`` archive. The specific compiler behavior here can be turned off by enabling :menuitem:`CONFIG_COMPILER_NO_MERGE_CONSTANTS` option (only for GCC toolchain), please read help for more details.
Source File Usage Summary ``idf.py size-files``
@@ -196,7 +196,7 @@ Comparing Two Binaries
When making changes that impact binary size, you can use the IDF Size tool to analyze the precise differences in size. The ``--diff`` option can be used with all previously mentioned sub-commands, allowing you to specify a path to a project build for comparison with the current project.
For example to compare two ``hello_world`` project builds, follow these steps. First, create two copies of the ``hello_world`` project directory. Name the first project directory ``hello_world_Og``. This project will use the default :ref:`CONFIG_COMPILER_OPTIMIZATION` compiler optimization setting ``Debug (-Og)`` and will serve as the ``REFERENCE`` project. Name the second project directory ``hello_world_Os``. This project will use the ``Optimize for size (-Os)`` setting, which can be enabled using ``idf.py menuconfig``. This will be the ``CURRENT`` project. Build both projects. Then, from within the ``hello_world_Os`` project directory, run the following command:
For example to compare two ``hello_world`` project builds, follow these steps. First, create two copies of the ``hello_world`` project directory. Name the first project directory ``hello_world_Og``. This project will use the default :menuitem:`CONFIG_COMPILER_OPTIMIZATION` compiler optimization setting ``Debug (-Og)`` and will serve as the ``REFERENCE`` project. Name the second project directory ``hello_world_Os``. This project will use the ``Optimize for size (-Os)`` setting, which can be enabled using ``idf.py menuconfig``. This will be the ``CURRENT`` project. Build both projects. Then, from within the ``hello_world_Os`` project directory, run the following command:
.. code-block:: bash

4
docs/en/api-guides/tools/qemu.rst
View File

@@ -162,7 +162,7 @@ By default, QEMU uses the ``qemu_flash.bin`` file in the build directory as the
The provided flash image must meet the following requirements for proper emulation:
- The flash file size matches the value specified by :ref:`CONFIG_ESPTOOLPY_FLASHSIZE` in the project configuration.
- The flash file size matches the value specified by :menuitem:`CONFIG_ESPTOOLPY_FLASHSIZE` in the project configuration.
- The flash file includes all required binaries, such as the bootloader, partition table, and application firmware, placed at their respective memory offsets.
@@ -183,4 +183,4 @@ For more available QEMU options, please refer to the `official QEMU documentatio
Emulating Secure Boot
~~~~~~~~~~~~~~~~~~~~~
QEMU supports emulation of secure boot v2 scheme. Please keep :ref:`CONFIG_SECURE_BOOT_FLASH_BOOTLOADER_DEFAULT` enabled to include signed bootloader image into the QEMU image artifact.
QEMU supports emulation of secure boot v2 scheme. Please keep :menuitem:`CONFIG_SECURE_BOOT_FLASH_BOOTLOADER_DEFAULT` enabled to include signed bootloader image into the QEMU image artifact.

2
docs/en/api-guides/tracing/custom-trace-library.rst
View File

@@ -64,7 +64,7 @@ For transports that need a complex driver or network stack, keep the runtime cal
FreeRTOS Trace Hooks
--------------------
To capture FreeRTOS events, the external component implementing a trace encoder should provide an ``esp_trace_freertos_impl.h`` header, defining the desired trace macros (``traceTASK_SWITCHED_IN()``, ``traceISR_ENTER()``, and so on). ``esp_trace`` includes this header when :ref:`CONFIG_ESP_TRACE_LIB_EXTERNAL <CONFIG_ESP_TRACE_LIB_EXTERNAL>` is enabled.
To capture FreeRTOS events, the external component implementing a trace encoder should provide an ``esp_trace_freertos_impl.h`` header, defining the desired trace macros (``traceTASK_SWITCHED_IN()``, ``traceISR_ENTER()``, and so on). ``esp_trace`` includes this header when :menuitem:`CONFIG_ESP_TRACE_LIB_EXTERNAL <CONFIG_ESP_TRACE_LIB_EXTERNAL>` is enabled.
Application Example
-------------------

6
docs/en/api-guides/tracing/function-tracing.rst
View File

@@ -10,10 +10,10 @@ Function tracing records every function entry and exit automatically, without ma
Enabling Function Tracing
-------------------------
Enable it under ``Component config`` > ``ESP Trace Configuration`` > ``Function Tracing``. The following options control function tracing:
Enable :menuitem:`CONFIG_ESP_TRACE_FUNCTION_TRACE`. The following options control function tracing:
- :ref:`CONFIG_ESP_TRACE_FUNCTION_TRACE` - build the function-trace hooks and runtime.
- :ref:`CONFIG_ESP_TRACE_FUNCTION_TRACE_AUTO_START` - when enabled (default), recording follows the encoder's state and begins as soon as the host starts the session. When disabled, no events are emitted until the application calls :cpp:func:`esp_trace_function_trace_start`; an active host session alone is not enough.
- :menuitem:`CONFIG_ESP_TRACE_FUNCTION_TRACE` - build the function-trace hooks and runtime.
- :menuitem:`CONFIG_ESP_TRACE_FUNCTION_TRACE_AUTO_START` - when enabled (default), recording follows the encoder's state and begins as soon as the host starts the session. When disabled, no events are emitted until the application calls :cpp:func:`esp_trace_function_trace_start`; an active host session alone is not enough.
Enabling the option compiles the hooks and runtime into the build. It does not add ``-finstrument-functions`` to any code, so on its own it produces no events. To trace a component or file, add the flag from its own ``CMakeLists.txt`` for the sources you want traced:

6
docs/en/api-guides/tracing/index.rst
View File

@@ -65,11 +65,11 @@ To enable SEGGER SystemView tracing for FreeRTOS system analysis:
1. Add the ``espressif/esp_sysview`` dependency to your project's ``idf_component.yml``.
2. Select the external trace library by enabling :ref:`CONFIG_ESP_TRACE_LIB_EXTERNAL <CONFIG_ESP_TRACE_LIB_EXTERNAL>`.
2. Select the external trace library by enabling :menuitem:`CONFIG_ESP_TRACE_LIB_EXTERNAL <CONFIG_ESP_TRACE_LIB_EXTERNAL>`.
3. Select the apptrace transport by enabling :ref:`CONFIG_ESP_TRACE_TRANSPORT_APPTRACE <CONFIG_ESP_TRACE_TRANSPORT_APPTRACE>`.
3. Select the apptrace transport by enabling :menuitem:`CONFIG_ESP_TRACE_TRANSPORT_APPTRACE <CONFIG_ESP_TRACE_TRANSPORT_APPTRACE>`.
4. Set the data destination to JTAG by enabling :ref:`CONFIG_APPTRACE_DEST_JTAG <CONFIG_APPTRACE_DEST_JTAG>`.
4. Set the data destination to JTAG by enabling :menuitem:`CONFIG_APPTRACE_DEST_JTAG <CONFIG_APPTRACE_DEST_JTAG>`.
5. Build and flash your application:

8
docs/en/api-guides/tracing/sysview.rst
View File

@@ -21,15 +21,15 @@ SystemView support is provided by the managed component ``espressif/esp_sysview`
dependencies:
espressif/esp_sysview: ^1
2. Selecting the external library in menuconfig: ``Component config`` > ``ESP Trace Configuration`` > ``Trace library`` > ``External library from component registry``.
2. Enable :menuitem:`CONFIG_ESP_TRACE_LIB_EXTERNAL`.
After that, you can configure SystemView in ``Component config`` > ``SEGGER SystemView Configuration``. This menu lets you choose the timestamp source (:ref:`CONFIG_ESP_TRACE_TIMESTAMP_SOURCE`), individually enable or disable collection of SystemView events (``CONFIG_SEGGER_SYSVIEW_EVT_XXX``), and select which CPU to trace when using the UART destination.
After that, the SystemView configuration options become available. These options let you choose the timestamp source (:menuitem:`CONFIG_ESP_TRACE_TIMESTAMP_SOURCE`), individually enable or disable collection of SystemView events (``CONFIG_SEGGER_SYSVIEW_EVT_XXX``), and select which CPU to trace when using the UART destination.
.. note::
For the full, up-to-date list of configuration options and host-side setup, see the component README: `esp_sysview <https://components.espressif.com/components/espressif/esp_sysview>`_.
To trace over the UART interface in real-time, first select UART as the destination in ``Component config`` > ``ESP Trace Configuration`` > ``Application Level Tracing``. Then select Pro or App CPU in ``Component config`` > ``ESP Trace Configuration`` > ``SEGGER SystemView``.
To trace over the UART interface in real-time, first select UART with :menuitem:`CONFIG_APPTRACE_DESTINATION`. Then select Pro or App CPU in the SystemView configuration.
OpenOCD SystemView Tracing Command Options
------------------------------------------
@@ -102,7 +102,7 @@ After trace data are collected, use a special tool to visualize the results and
SystemView version 3.60 and later supports tracing from multiple cores. For multi-core tracing, use the ``esp sysview_mcore`` command to generate a single file compatible with SystemView multi-core format. This command will create a single trace file that can be loaded directly into SystemView 3.60+ for multi-core visualization.
**Note:** SystemView versions before 3.60 do not support multi-core tracing. For older versions, when tracing from {IDF_TARGET_NAME} with JTAG interfaces in the dual-core mode, two separate files are generated: one for PRO CPU and another for APP CPU. Users can load each file into separate instances of the tool. For tracing over UART, after selecting the external library in menuconfig, users can select ``Component config`` > ``SEGGER SystemView Configuration`` to choose which CPU (Pro or App) has to be traced.
**Note:** SystemView versions before 3.60 do not support multi-core tracing. For older versions, when tracing from {IDF_TARGET_NAME} with JTAG interfaces in the dual-core mode, two separate files are generated: one for PRO CPU and another for APP CPU. Users can load each file into separate instances of the tool. For tracing over UART, select which CPU (Pro or App) to trace in the SystemView configuration.
For older SystemView versions, analyzing data for every core in separate instances can be awkward. An alternative is to use the Eclipse plugin called *Impulse*, which can load several trace files, making it possible to inspect events from both cores in one view. This plugin also has no limitation of 1,000,000 events as compared to the free version of SystemView.

20
docs/en/api-guides/tracing/transports.rst
View File

@@ -45,7 +45,7 @@ Using of this feature depends on two components:
1. **Host side:** Application tracing is done over JTAG, so it needs OpenOCD to be set up and running on host machine. For instructions on how to set it up, please see :doc:`JTAG Debugging </api-guides/jtag-debugging/index>` for details.
2. **Target side:** Application tracing functionality can be enabled in menuconfig. **Important:** You must first enable application tracing by going to ``Component config`` > ``ESP Trace Configuration`` > ``Trace transport`` and selecting ``ESP-IDF apptrace``. After that, configuration can be done at ``Component config`` > ``ESP Trace Configuration`` > ``Application Level Tracing``. Here you can configure the destination for the trace data. For UART interfaces, users have to define port number, baud rate, TX and RX pins numbers, and additional UART-related parameters. When any trace library is selected (for example SEGGER SystemView), these settings will be used for the library as well.
2. **Target side:** Application tracing functionality can be enabled in menuconfig. **Important:** You must first set :menuitem:`CONFIG_ESP_TRACE_TRANSPORT` to ``ESP-IDF apptrace``. The related application-level tracing options will then become available. Here you can configure the destination for the trace data. For UART interfaces, users have to define port number, baud rate, TX and RX pins numbers, and additional UART-related parameters. When any trace library is selected (for example SEGGER SystemView), these settings will be used for the library as well.
.. note::
@@ -53,15 +53,15 @@ Using of this feature depends on two components:
There are some additional menuconfig options not mentioned above:
1. *Threshold for flushing last trace data to host on panic* (:ref:`CONFIG_APPTRACE_POSTMORTEM_FLUSH_THRESH`). This option is necessary due to the nature of working over JTAG. In this mode, trace data is exposed to the host in 16 KB blocks. In post-mortem mode, when one block is filled, it is exposed to the host and the previous one becomes unavailable. In other words, the trace data is overwritten in 16 KB granularity. On panic, the latest data from the current input block is exposed to the host and the host can read them for post-analysis. System panic may occur when a very small amount of data are not exposed to the host yet. In this case, the previous 16 KB of collected data will be lost and the host will see the latest, but very small piece of the trace. It can be insufficient to diagnose the problem. This menuconfig option allows avoiding such situations. It controls the threshold for flushing data in case of apanic. For example, you can decide that it needs no less than 512 bytes of the recent trace data, so if there is less than 512 bytes of pending data at the moment of panic, they will not be flushed and will not overwrite the previous 16 KB. The option is only meaningful in post-mortem mode and when working over JTAG.
1. *Threshold for flushing last trace data to host on panic* (:menuitem:`CONFIG_APPTRACE_POSTMORTEM_FLUSH_THRESH`). This option is necessary due to the nature of working over JTAG. In this mode, trace data is exposed to the host in 16 KB blocks. In post-mortem mode, when one block is filled, it is exposed to the host and the previous one becomes unavailable. In other words, the trace data is overwritten in 16 KB granularity. On panic, the latest data from the current input block is exposed to the host and the host can read them for post-analysis. System panic may occur when a very small amount of data are not exposed to the host yet. In this case, the previous 16 KB of collected data will be lost and the host will see the latest, but very small piece of the trace. It can be insufficient to diagnose the problem. This menuconfig option allows avoiding such situations. It controls the threshold for flushing data in case of apanic. For example, you can decide that it needs no less than 512 bytes of the recent trace data, so if there is less than 512 bytes of pending data at the moment of panic, they will not be flushed and will not overwrite the previous 16 KB. The option is only meaningful in post-mortem mode and when working over JTAG.
2. *Timeout for flushing last trace data to host on panic* (:ref:`CONFIG_APPTRACE_ONPANIC_HOST_FLUSH_TMO`). The option is only meaningful in streaming mode and it controls the maximum time that the tracing module will wait for the host to read the last data in case of panic.
2. *Timeout for flushing last trace data to host on panic* (:menuitem:`CONFIG_APPTRACE_ONPANIC_HOST_FLUSH_TMO`). The option is only meaningful in streaming mode and it controls the maximum time that the tracing module will wait for the host to read the last data in case of panic.
3. *Internal Sync Lock* (:ref:`CONFIG_APPTRACE_LOCK_ENABLE`). Enable this option to protect trace buffer writes with locks, preventing data corruption when multiple tasks generate trace data concurrently.
3. *Internal Sync Lock* (:menuitem:`CONFIG_APPTRACE_LOCK_ENABLE`). Enable this option to protect trace buffer writes with locks, preventing data corruption when multiple tasks generate trace data concurrently.
4. *UART RX/TX ring buffer size* (:ref:`CONFIG_APPTRACE_UART_TX_BUFF_SIZE`). The size of the buffer depends on the amount of data transferred through the UART.
4. *UART RX/TX ring buffer size* (:menuitem:`CONFIG_APPTRACE_UART_TX_BUFF_SIZE`). The size of the buffer depends on the amount of data transferred through the UART.
5. *UART TX message size* (:ref:`CONFIG_APPTRACE_UART_TX_MSG_SIZE`). The maximum size of the single message to transfer.
5. *UART TX message size* (:menuitem:`CONFIG_APPTRACE_UART_TX_MSG_SIZE`). The maximum size of the single message to transfer.
How to Use This Library
@@ -78,8 +78,8 @@ Quick Start Summary
In menuconfig, disable the trace library and enable the Application Level Tracing transport:
- ``Component config`` > ``ESP Trace Configuration`` > ``Trace library``: select ``None``
- ``Component config`` > ``ESP Trace Configuration`` > ``Trace transport``: select ``ESP-IDF apptrace``
- Set :menuitem:`CONFIG_ESP_TRACE_LIBRARY` to ``None``
- Set :menuitem:`CONFIG_ESP_TRACE_TRANSPORT` to ``ESP-IDF apptrace``
Alternatively, set these options in ``sdkconfig.defaults`` to enforce standalone mode:
@@ -89,7 +89,7 @@ Quick Start Summary
CONFIG_ESP_TRACE_LIB_NONE=y
CONFIG_ESP_TRACE_TRANSPORT_APPTRACE=y
Configure the destination in ``Component config`` > ``ESP Trace Configuration`` > ``Application Level Tracing``.
Configure the destination with :menuitem:`CONFIG_APPTRACE_DESTINATION`.
2. Runtime configuration via ``esp_apptrace_get_user_params()``
@@ -365,7 +365,7 @@ How to Use It
In order to use logging via trace module, you need to perform the following steps:
1. Enable application tracing in menuconfig by going to ``Component config`` > ``ESP Trace Configuration`` > ``Trace transport`` and selecting ``ESP-IDF apptrace``. After that, configuration can be done at ``Component config`` > ``ESP Trace Configuration`` > ``Application Level Tracing``.
1. Enable application tracing by setting :menuitem:`CONFIG_ESP_TRACE_TRANSPORT` to ``ESP-IDF apptrace``. The related application-level tracing options will then become available.
2. On the target side, the special vprintf-like function :cpp:func:`esp_apptrace_vprintf` needs to be installed. It sends log data to the host. An example is ``esp_log_set_vprintf(esp_apptrace_vprintf);``. To send log data to UART again, use ``esp_log_set_vprintf(vprintf);``.
3. Follow instructions in items 4-6 in `Application Specific Tracing`_ (OpenOCD setup and trace collection).
4. To print out collected log records, run the following command in terminal: ``$IDF_PATH/tools/esp_app_trace/logtrace_proc.py /path/to/trace/file /path/to/program/elf/file``.

4
docs/en/api-guides/usb-otg-console.rst
View File

@@ -48,7 +48,7 @@ Some development boards may offer a USB connector for the internal USB periphera
Software Configuration
======================
USB console feature can be enabled using ``CONFIG_ESP_CONSOLE_USB_CDC`` option in menuconfig tool (see :ref:`CONFIG_ESP_CONSOLE_UART`).
USB console feature can be enabled using ``CONFIG_ESP_CONSOLE_USB_CDC`` option in menuconfig tool (see :menuitem:`CONFIG_ESP_CONSOLE_UART`).
Once the option is enabled, build the project as usual.
@@ -107,7 +107,7 @@ There are several limitations to the USB console feature. These may or may not b
4. USB CDC driver reserves some amount of RAM and increases application code size. Keep this in mind if trying to optimize application memory usage.
5. By default, the low-level ``esp_rom_printf`` feature and ``ESP_EARLY_LOG`` are disabled when USB CDC is used. These can be enabled using :ref:`CONFIG_ESP_CONSOLE_USB_CDC_SUPPORT_ETS_PRINTF` option. With this option enabled, ``esp_rom_printf`` can be used, at the expense of increased IRAM usage. Keep in mind that the cost of ``esp_rom_printf`` and ``ESP_EARLY_LOG`` over USB CDC is significantly higher than over UART. This makes these logging mechanisms much less suitable for "printf debugging", especially in the interrupt handlers.
5. By default, the low-level ``esp_rom_printf`` feature and ``ESP_EARLY_LOG`` are disabled when USB CDC is used. These can be enabled using :menuitem:`CONFIG_ESP_CONSOLE_USB_CDC_SUPPORT_ETS_PRINTF` option. With this option enabled, ``esp_rom_printf`` can be used, at the expense of increased IRAM usage. Keep in mind that the cost of ``esp_rom_printf`` and ``ESP_EARLY_LOG`` over USB CDC is significantly higher than over UART. This makes these logging mechanisms much less suitable for "printf debugging", especially in the interrupt handlers.
6. If you are developing an application which uses the USB peripheral with the TinyUSB stack, this USB Console feature can not be used. This is mainly due to the following reasons:

6
docs/en/api-guides/usb-serial-jtag-console.rst
View File

@@ -45,9 +45,9 @@ Some development boards may offer a USB connector for the USB Serial/JTAG Contro
Software Configuration
======================
The USB Serial/JTAG Controller can be used as the serial port by selecting ``CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG`` in the :ref:`CONFIG_ESP_CONSOLE_UART` option. Once selected, building and flashing the project can occur as usual.
The USB Serial/JTAG Controller can be used as the serial port by selecting ``CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG`` in the :menuitem:`CONFIG_ESP_CONSOLE_UART` option. Once selected, building and flashing the project can occur as usual.
Alternatively, you can access the output through the ``usb_serial_jtag`` port but make sure ``CONFIG_ESP_CONSOLE_SECONDARY_USB_SERIAL_JTAG`` is selected in the :ref:`CONFIG_ESP_CONSOLE_SECONDARY`.
Alternatively, you can access the output through the ``usb_serial_jtag`` port but make sure ``CONFIG_ESP_CONSOLE_SECONDARY_USB_SERIAL_JTAG`` is selected in the :menuitem:`CONFIG_ESP_CONSOLE_SECONDARY`.
.. warning::
@@ -121,7 +121,7 @@ Automatic and Manual Sleep Entry
If users enter sleep manually (via :cpp:func:`esp_light_sleep_start` or :cpp:func:`esp_deep_sleep_start`), users should be cognizant of the fact that USB Serial/JTAG controller does not work during sleep. ESP-IDF **does not add any safety check to reject entry to sleep** even if the USB Serial/JTAG controller is connected. In the case where sleep is entered while the USB Serial/JTAG controller is connected, the connection can be re-established by unplugging and re-plugging the USB cable.
If users enter sleep automatically (via :cpp:func:`esp_pm_configure`), enabling the :ref:`CONFIG_USJ_NO_AUTO_LS_ON_CONNECTION` option allows the {IDF_TARGET_NAME} to automatically detect whether the USB Serial/JTAG controller is currently connected to a host, and prevent automatic entry to sleep as long as the connection persists. However, note that this option increases power consumption.
If users enter sleep automatically (via :cpp:func:`esp_pm_configure`), enabling the :menuitem:`CONFIG_USJ_NO_AUTO_LS_ON_CONNECTION` option allows the {IDF_TARGET_NAME} to automatically detect whether the USB Serial/JTAG controller is currently connected to a host, and prevent automatic entry to sleep as long as the connection persists. However, note that this option increases power consumption.
Application Examples

4
docs/en/api-guides/wifi-driver/overview.rst
View File

@@ -335,7 +335,7 @@ IP_EVENT_STA_LOST_IP
This event arises when the IPV4 address becomes invalid.
IP_EVENT_STA_LOST_IP does not arise immediately after the Wi-Fi disconnects. Instead, it starts an IPV4 address lost timer (configurable via :ref:`CONFIG_ESP_NETIF_LOST_IP_TIMER_ENABLE` and :ref:`CONFIG_ESP_NETIF_IP_LOST_TIMER_INTERVAL`). If the IPV4 address is got before the timer expires, IP_EVENT_STA_LOST_IP does not happen. Otherwise, the event arises when the IPV4 address lost timer expires.
IP_EVENT_STA_LOST_IP does not arise immediately after the Wi-Fi disconnects. Instead, it starts an IPV4 address lost timer (configurable via :menuitem:`CONFIG_ESP_NETIF_LOST_IP_TIMER_ENABLE` and :menuitem:`CONFIG_ESP_NETIF_IP_LOST_TIMER_INTERVAL`). If the IPV4 address is got before the timer expires, IP_EVENT_STA_LOST_IP does not happen. Otherwise, the event arises when the IPV4 address lost timer expires.
Generally, the application can ignore this event, because it is just a debug event to inform that the IPV4 address is lost.
@@ -552,7 +552,7 @@ API :cpp:func:`esp_wifi_set_config()` can be used to configure the AP. And the c
* - ssid_hidden
- If ssid_hidden is 1, AP does not broadcast the SSID; otherwise, it does broadcast the SSID.
* - max_connection
- The max number of stations allowed to connect in. {IDF_TARGET_NAME} supports up to {IDF_TARGET_MAX_CONN_STA_NUM} (``ESP_WIFI_MAX_CONN_NUM``) Wi-Fi connections. Please note that soft-AP and ESP-NOW share the same encryption hardware keys, so the max_connection parameter will be affected by the :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM`. The total number of encryption hardware keys is {IDF_TARGET_SUPPORT_ENCRYPT_NUM}, if :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM` <= {IDF_TARGET_SUB_MAX_NUM_FROM_KEYS}, the max_connection can be set up to {IDF_TARGET_MAX_CONN_STA_NUM}, otherwise the max_connection can be set up to ({IDF_TARGET_SUPPORT_ENCRYPT_NUM} - :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM`).
- The max number of stations allowed to connect in. {IDF_TARGET_NAME} supports up to {IDF_TARGET_MAX_CONN_STA_NUM} (``ESP_WIFI_MAX_CONN_NUM``) Wi-Fi connections. Please note that soft-AP and ESP-NOW share the same encryption hardware keys, so the max_connection parameter will be affected by the :menuitem:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM`. The total number of encryption hardware keys is {IDF_TARGET_SUPPORT_ENCRYPT_NUM}, if :menuitem:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM` <= {IDF_TARGET_SUB_MAX_NUM_FROM_KEYS}, the max_connection can be set up to {IDF_TARGET_MAX_CONN_STA_NUM}, otherwise the max_connection can be set up to ({IDF_TARGET_SUPPORT_ENCRYPT_NUM} - :menuitem:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM`).
* - beacon_interval
- Beacon interval; the value is 100 ~ 60000 ms, with default value being 100 ms. If the value is out of range, AP defaults it to 100 ms.

2
docs/en/api-guides/wifi-driver/security-and-roaming.rst
View File

@@ -54,7 +54,7 @@ Fast BSS transition (802.11r FT), is a standard to permit continuous connectivit
{IDF_TARGET_NAME} station supports FT for WPA2-PSK networks. Do note that {IDF_TARGET_NAME} station only support FT over the air protocol only.
A config option :ref:`CONFIG_ESP_WIFI_11R_SUPPORT` and configuration parameter :cpp:type:`ft_enabled` in :cpp:type:`wifi_sta_config_t` is provided to enable 802.11r support for station. Refer ESP-IDF example :idf_file:`examples/wifi/roaming/README.md` for further details.
A config option :menuitem:`CONFIG_ESP_WIFI_11R_SUPPORT` and configuration parameter :cpp:type:`ft_enabled` in :cpp:type:`wifi_sta_config_t` is provided to enable 802.11r support for station. Refer ESP-IDF example :idf_file:`examples/wifi/roaming/README.md` for further details.
.. only:: SOC_WIFI_FTM_SUPPORT

2
docs/en/api-guides/wifi-driver/wifi-mac-protocols.rst
View File

@@ -80,7 +80,7 @@ Wi-Fi AMSDU
.. only:: SOC_SPIRAM_SUPPORTED
{IDF_TARGET_NAME} supports receiving and transmitting AMSDU. AMSDU TX is disabled by default, since enable AMSDU TX need more memory. Select :ref:`CONFIG_ESP_WIFI_AMSDU_TX_ENABLED` to enable AMSDU Tx feature, it depends on :ref:`CONFIG_SPIRAM`.
{IDF_TARGET_NAME} supports receiving and transmitting AMSDU. AMSDU TX is disabled by default, since enable AMSDU TX need more memory. Select :menuitem:`CONFIG_ESP_WIFI_AMSDU_TX_ENABLED` to enable AMSDU Tx feature, it depends on :menuitem:`CONFIG_SPIRAM`.
Wi-Fi Fragment
-------------------------

52
docs/en/api-guides/wifi-driver/wifi-performance-and-power-save.rst
View File

@@ -439,83 +439,83 @@ Increasing the size or number of the buffers mentioned above properly can improv
**RX direction:**
- :ref:`CONFIG_ESP_WIFI_STATIC_RX_BUFFER_NUM`
- :menuitem:`CONFIG_ESP_WIFI_STATIC_RX_BUFFER_NUM`
This parameter indicates the number of DMA buffer at the hardware layer. Increasing this parameter will increase the sender's one-time receiving throughput, thereby improving the Wi-Fi protocol stack ability to handle burst traffic.
- :ref:`CONFIG_ESP_WIFI_DYNAMIC_RX_BUFFER_NUM`
- :menuitem:`CONFIG_ESP_WIFI_DYNAMIC_RX_BUFFER_NUM`
This parameter indicates the number of RX buffer in the Wi-Fi layer. Increasing this parameter will improve the performance of packet reception. This parameter needs to match the RX buffer size of the LwIP layer.
- :ref:`CONFIG_ESP_WIFI_RX_BA_WIN`
This parameter indicates the size of the AMPDU BA Window at the receiving end. This parameter should be configured to the smaller value between twice of :ref:`CONFIG_ESP_WIFI_STATIC_RX_BUFFER_NUM` and :ref:`CONFIG_ESP_WIFI_DYNAMIC_RX_BUFFER_NUM`.
- :menuitem:`CONFIG_ESP_WIFI_RX_BA_WIN`
This parameter indicates the size of the AMPDU BA Window at the receiving end. This parameter should be configured to the smaller value between twice of :menuitem:`CONFIG_ESP_WIFI_STATIC_RX_BUFFER_NUM` and :menuitem:`CONFIG_ESP_WIFI_DYNAMIC_RX_BUFFER_NUM`.
- :ref:`CONFIG_LWIP_TCP_WND_DEFAULT`
- :menuitem:`CONFIG_LWIP_TCP_WND_DEFAULT`
This parameter represents the RX buffer size of the LwIP layer for each TCP stream. Its value should be configured to the value of WIFI_DYNAMIC_RX_BUFFER_NUM (KB) to reach a high and stable performance. Meanwhile, in case of multiple streams, this value needs to be reduced proportionally.
**TX direction:**
- :ref:`CONFIG_ESP_WIFI_TX_BUFFER`
- :menuitem:`CONFIG_ESP_WIFI_TX_BUFFER`
This parameter indicates the type of TX buffer, it is recommended to configure it as a dynamic buffer, which can make full use of memory.
- :ref:`CONFIG_ESP_WIFI_DYNAMIC_TX_BUFFER_NUM`
- :menuitem:`CONFIG_ESP_WIFI_DYNAMIC_TX_BUFFER_NUM`
This parameter indicates the number of TX buffer on the Wi-Fi layer. Increasing this parameter will improve the performance of packet sending. The parameter value needs to match the TX buffer size of the LwIP layer.
- :ref:`CONFIG_LWIP_TCP_SND_BUF_DEFAULT`
- :menuitem:`CONFIG_LWIP_TCP_SND_BUF_DEFAULT`
This parameter represents the TX buffer size of the LwIP layer for each TCP stream. Its value should be configured to the value of WIFI_DYNAMIC_TX_BUFFER_NUM (KB) to reach a high and stable performance. In case of multiple streams, this value needs to be reduced proportionally.
**Throughput optimization by placing code in IRAM:**
.. only:: esp32 or esp32s2
- :ref:`CONFIG_ESP_WIFI_IRAM_OPT`
- :menuitem:`CONFIG_ESP_WIFI_IRAM_OPT`
If this option is enabled, some Wi-Fi functions are moved to IRAM, improving throughput. This increases IRAM usage by 15 kB.
- :ref:`CONFIG_ESP_WIFI_RX_IRAM_OPT`
- :menuitem:`CONFIG_ESP_WIFI_RX_IRAM_OPT`
If this option is enabled, some Wi-Fi RX functions are moved to IRAM, improving throughput. This increases IRAM usage by 16 kB.
- :ref:`CONFIG_LWIP_IRAM_OPTIMIZATION`
- :menuitem:`CONFIG_LWIP_IRAM_OPTIMIZATION`
If this option is enabled, some LwIP functions are moved to IRAM, improving throughput. This increases IRAM usage by 13 kB.
.. only:: esp32c6
- :ref:`CONFIG_ESP_WIFI_IRAM_OPT`
- :menuitem:`CONFIG_ESP_WIFI_IRAM_OPT`
If this option is enabled, some Wi-Fi functions are moved to IRAM, improving throughput. This increases IRAM usage by 13 kB.
- :ref:`CONFIG_ESP_WIFI_RX_IRAM_OPT`
- :menuitem:`CONFIG_ESP_WIFI_RX_IRAM_OPT`
If this option is enabled, some Wi-Fi RX functions are moved to IRAM, improving throughput. This increases IRAM usage by 7 kB.
- :ref:`CONFIG_LWIP_IRAM_OPTIMIZATION`
- :menuitem:`CONFIG_LWIP_IRAM_OPTIMIZATION`
If this option is enabled, some LwIP functions are moved to IRAM, improving throughput. This increases IRAM usage by 14 kB.
.. only:: esp32s2
**CACHE:**
- :ref:`CONFIG_ESP32S2_INSTRUCTION_CACHE_SIZE`
- :menuitem:`CONFIG_ESP32S2_INSTRUCTION_CACHE_SIZE`
Configure the size of the instruction Cache.
- :ref:`CONFIG_ESP32S2_INSTRUCTION_CACHE_LINE_SIZE`
- :menuitem:`CONFIG_ESP32S2_INSTRUCTION_CACHE_LINE_SIZE`
Configure the width of the instruction Cache bus.
.. only:: esp32s3
**CACHE:**
- :ref:`CONFIG_ESP32S3_INSTRUCTION_CACHE_SIZE`
- :menuitem:`CONFIG_ESP32S3_INSTRUCTION_CACHE_SIZE`
Configure the size of the instruction Cache.
- :ref:`CONFIG_ESP32S3_INSTRUCTION_CACHE_LINE_SIZE`
- :menuitem:`CONFIG_ESP32S3_INSTRUCTION_CACHE_LINE_SIZE`
Configure the size of the instruction Cache bus.
- :ref:`CONFIG_ESP32S3_ICACHE_ASSOCIATED_WAYS`
- :menuitem:`CONFIG_ESP32S3_ICACHE_ASSOCIATED_WAYS`
Configure the associated ways of the instruction Cache.
- :ref:`CONFIG_ESP32S3_DATA_CACHE_SIZE`
- :menuitem:`CONFIG_ESP32S3_DATA_CACHE_SIZE`
Configure the size of the Data Cache.
- :ref:`CONFIG_ESP32S3_DATA_CACHE_LINE_SIZE`
- :menuitem:`CONFIG_ESP32S3_DATA_CACHE_LINE_SIZE`
Configure the line size of the Data Cache.
- :ref:`CONFIG_ESP32S3_DCACHE_ASSOCIATED_WAYS`
- :menuitem:`CONFIG_ESP32S3_DCACHE_ASSOCIATED_WAYS`
Configure the associated ways of the Data Cache.
.. note::
@@ -1109,7 +1109,7 @@ The parameters not mentioned in the following table should be set to the default
Using PSRAM
++++++++++++++++++++++++++++
PSRAM is generally used when the application takes up a lot of memory. In this mode, the :ref:`CONFIG_ESP_WIFI_TX_BUFFER` is forced to be static. :ref:`CONFIG_ESP_WIFI_STATIC_TX_BUFFER_NUM` indicates the number of DMA buffers at the hardware layer, and increasing this parameter can improve performance.
PSRAM is generally used when the application takes up a lot of memory. In this mode, the :menuitem:`CONFIG_ESP_WIFI_TX_BUFFER` is forced to be static. :menuitem:`CONFIG_ESP_WIFI_STATIC_TX_BUFFER_NUM` indicates the number of DMA buffers at the hardware layer, and increasing this parameter can improve performance.
The following are the recommended ranks for using PSRAM:
.. only:: esp32
@@ -1572,11 +1572,11 @@ Disconnected State Sleep
Disconnected state is the duration without Wi-Fi connection between :cpp:func:`esp_wifi_start` to :cpp:func:`esp_wifi_stop`.
Currently, {IDF_TARGET_NAME} Wi-Fi supports sleep mode in disconnected state if running at station mode. This feature could be configured by Menuconfig choice :ref:`CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE`.
Currently, {IDF_TARGET_NAME} Wi-Fi supports sleep mode in disconnected state if running at station mode. This feature could be configured by Menuconfig choice :menuitem:`CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE`.
If :ref:`CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE` is enabled, RF, PHY and BB would be turned off in disconnected state when IDLE. The current would be same with current at modem-sleep.
If :menuitem:`CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE` is enabled, RF, PHY and BB would be turned off in disconnected state when IDLE. The current would be same with current at modem-sleep.
The choice :ref:`CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE` would be selected by default, while it would be selected forcefully in Menuconfig at coexistence mode.
The choice :menuitem:`CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE` would be selected by default, while it would be selected forcefully in Menuconfig at coexistence mode.
.. _connectionless-module-power-save:

2
docs/en/api-guides/wifi-driver/wifi-vendor-features.rst
View File

@@ -222,7 +222,7 @@ By default, all Wi-Fi management frames are processed by the Wi-Fi driver, and t
To use Wi-Fi CSI, the following steps need to be done.
- Select Wi-Fi CSI in menuconfig. Go to ``Menuconfig`` > ``Components config`` > ``Wi-Fi`` > ``Wi-Fi CSI (Channel State Information)``.
- Enable :menuitem:`CONFIG_ESP_WIFI_CSI_ENABLED`.
- Set CSI receiving callback function by calling API :cpp:func:`esp_wifi_set_csi_rx_cb()`.
- Configure CSI by calling API :cpp:func:`esp_wifi_set_csi_config()`.
- Enable CSI by calling API :cpp:func:`esp_wifi_set_csi()`.

24
docs/en/api-guides/wifi-security.rst
View File

@@ -69,7 +69,7 @@ WPA2-Enterprise and WPA3-Enterprise
WPA3-Enterprise also introduces an additional secure mode using **192-bit minimum-strength security protocols** (“Suite B”). This mode ensures a consistent baseline of cryptographic strength.
- WPA3-Enterprise 192-bit mode is supported only on modules that have :c:macro:`SOC_WIFI_GCMP_SUPPORT`.
- To enable WPA3-Enterprise 192-bit mode, configure :ref:`CONFIG_ESP_WIFI_SUITE_B_192`.
- To enable WPA3-Enterprise 192-bit mode, configure :menuitem:`CONFIG_ESP_WIFI_SUITE_B_192`.
Supported EAP Methods
+++++++++++++++++++++++++
@@ -97,7 +97,7 @@ The following EAP methods are supported:
- **EAP-FAST**
An authentication method based on Protected Access Credentials (PAC), requiring an identity and password. To use EAP-FAST, :ref:`CONFIG_ESP_WIFI_MBEDTLS_TLS_CLIENT` must be **disabled**.
An authentication method based on Protected Access Credentials (PAC), requiring an identity and password. To use EAP-FAST, :menuitem:`CONFIG_ESP_WIFI_MBEDTLS_TLS_CLIENT` must be **disabled**.
Examples
++++++++++
@@ -128,7 +128,7 @@ Wi-Fi Protected Access-3 (WPA3) is a set of enhancements to Wi-Fi access securit
- **Transition Disable** : WPA3 defines transition modes for client devices so that they can connect to a network even when some of the APs in that network do not support the strongest security mode. Client device implementations typically configure network profiles in a transition mode by default. However, such a client device could be subject to an active downgrade attack in which the attacker causes the client device to use a lower security mode in order to exploit a vulnerability with that mode. WPA3 has introduced the Transition Disable feature to mitigate such attacks, by enabling client devices to change from a transition mode to an "only" mode when connecting to a network, once that network indicates it fully supports the higher security mode. Enable :cpp:type:`transition_disable` in :cpp:type:`wifi_sta_config_t` to enable this feature for {IDF_TARGET_NAME} station.
- **SAE PUBLIC-KEY (PK)** : As the password at small public networks is shared with multiple users, it may be relatively easy for an attacker to find out the password, which is sufficient to launch an evil twin attack. Such attacks are prevented by an extension to WPA3-Personal called SAE-PK. The SAE-PK authentication exchange is very similar to the regular SAE exchange, with the addition of a digital signature sent by the AP to the client device. The client device validates the public key asserted by the AP based on the password fingerprint and verifies the signature using the public key. So even if the attacker knows the password, it does not know the private key to generate a valid signature, and therefore the client device is protected against an evil twin attack. Enable :ref:`CONFIG_ESP_WIFI_ENABLE_SAE_PK` and :cpp:type:`sae_pk_mode` in :cpp:type:`wifi_sta_config_t` to add support of SAE PK for {IDF_TARGET_NAME} station.
- **SAE PUBLIC-KEY (PK)** : As the password at small public networks is shared with multiple users, it may be relatively easy for an attacker to find out the password, which is sufficient to launch an evil twin attack. Such attacks are prevented by an extension to WPA3-Personal called SAE-PK. The SAE-PK authentication exchange is very similar to the regular SAE exchange, with the addition of a digital signature sent by the AP to the client device. The client device validates the public key asserted by the AP based on the password fingerprint and verifies the signature using the public key. So even if the attacker knows the password, it does not know the private key to generate a valid signature, and therefore the client device is protected against an evil twin attack. Enable :menuitem:`CONFIG_ESP_WIFI_ENABLE_SAE_PK` and :cpp:type:`sae_pk_mode` in :cpp:type:`wifi_sta_config_t` to add support of SAE PK for {IDF_TARGET_NAME} station.
- **SAE PWE Methods**: {IDF_TARGET_NAME} station as well as SoftAP supports SAE Password Element derivation method `Hunting And Pecking` and `Hash to Element (H2E)`. H2E is computationally efficient as it uses fewer iterations than Hunt and Peck, and also it mitigates side-channel attacks. These can be configured using the parameter :cpp:type:`sae_pwe_h2e` from :cpp:type:`wifi_sta_config_t` and :cpp:type:`wifi_ap_config_t` for station and SoftAP respectively. Hunt and peck, H2E both can be enabled by using :cpp:enumerator:`WPA3_SAE_PWE_BOTH` configuration.
@@ -137,7 +137,7 @@ Please refer to the `Security <https://www.wi-fi.org/discover-wi-fi/security>`_
Setting up WPA3 Personal with {IDF_TARGET_NAME}
+++++++++++++++++++++++++++++++++++++++++++++++
A configuration option :ref:`CONFIG_ESP_WIFI_ENABLE_WPA3_SAE` is provided to enable/disable WPA3 for the station. By default, it is kept enabled. If disabled, {IDF_TARGET_NAME} will not be able to establish a WPA3 connection. Also under the Wi-Fi component, a configuration option :ref:`CONFIG_ESP_WIFI_SOFTAP_SAE_SUPPORT` is provided to enable/disable WPA3 for SoftAP. Additionally, since PMF is mandated by WPA3 protocol, PMF Optional is set by default for station and SoftAP. PMF Required can be configured using Wi-Fi configuration. For WPA3 SoftAP, PMF Required is mandatory and will be configured and stored in NVS implicitly if not specified by the user.
A configuration option :menuitem:`CONFIG_ESP_WIFI_ENABLE_WPA3_SAE` is provided to enable/disable WPA3 for the station. By default, it is kept enabled. If disabled, {IDF_TARGET_NAME} will not be able to establish a WPA3 connection. Also under the Wi-Fi component, a configuration option :menuitem:`CONFIG_ESP_WIFI_SOFTAP_SAE_SUPPORT` is provided to enable/disable WPA3 for SoftAP. Additionally, since PMF is mandated by WPA3 protocol, PMF Optional is set by default for station and SoftAP. PMF Required can be configured using Wi-Fi configuration. For WPA3 SoftAP, PMF Required is mandatory and will be configured and stored in NVS implicitly if not specified by the user.
Refer to `Protected Management Frames (PMF)`_ on how to set this mode.
@@ -145,7 +145,7 @@ After configuring all required settings for the WPA3-Personal station, applicati
After configuring all required setting for WPA3-Personal SoftAP, application developers have to set ``WIFI_AUTH_WPA3_PSK`` for `authmode` in :cpp:type:`wifi_ap_config_t` to start AP in WPA3 security. SoftAP can be also configured to use ``WIFI_AUTH_WPA2_WPA3_PSK`` mixed mode.
Note that binary size will be increased by about 6.5 kilobytes after enabling :ref:`CONFIG_ESP_WIFI_SOFTAP_SAE_SUPPORT`.
Note that binary size will be increased by about 6.5 kilobytes after enabling :menuitem:`CONFIG_ESP_WIFI_SOFTAP_SAE_SUPPORT`.
Wi-Fi Enhanced Open™
--------------------
@@ -165,38 +165,38 @@ Setting up OWE with {IDF_TARGET_NAME}
For station mode:
A configuration option :ref:`CONFIG_ESP_WIFI_ENABLE_WPA3_OWE_STA` and configuration parameter :cpp:type:`owe_enabled` in :cpp:type:`wifi_sta_config_t` is provided to enable OWE support for the station. To use OWE transition mode, along with the configuration provided above, `authmode` from :cpp:type:`wifi_scan_threshold_t` should be set to ``WIFI_AUTH_OPEN``.
A configuration option :menuitem:`CONFIG_ESP_WIFI_ENABLE_WPA3_OWE_STA` and configuration parameter :cpp:type:`owe_enabled` in :cpp:type:`wifi_sta_config_t` is provided to enable OWE support for the station. To use OWE transition mode, along with the configuration provided above, `authmode` from :cpp:type:`wifi_scan_threshold_t` should be set to ``WIFI_AUTH_OPEN``.
For SoftAP mode:
A configuration option :ref:`CONFIG_ESP_WIFI_ENABLE_WPA3_OWE_SOFTAP` from menuconfig should be enabled and configuration parameter `authmode` from :cpp:type:`wifi_ap_config_t` should be set to ``WIFI_AUTH_OWE``. SoftAP does not support OWE Transition Mode; configure ``WIFI_AUTH_OWE`` only.
A configuration option :menuitem:`CONFIG_ESP_WIFI_ENABLE_WPA3_OWE_SOFTAP` from menuconfig should be enabled and configuration parameter `authmode` from :cpp:type:`wifi_ap_config_t` should be set to ``WIFI_AUTH_OWE``. SoftAP does not support OWE Transition Mode; configure ``WIFI_AUTH_OWE`` only.
WiFi Privacy Enhancements
--------------------------
MAC addresses, used by devices to connect to Wi-Fi networks, can be captured and tracked because they are transmitted without encryption and due to their unique and static nature. {IDF_TARGET_NAME} supports the WiFi Privacy Enhancements feature which includes MAC randomization, sequence number randomization, diversity in GAS dialogue tokens and vendor sequence numbers. This prevents devices from being consistently tracked when scanning or connecting to networks.
To use this feature, enable configuration option :ref:`CONFIG_ESP_WIFI_PRIVACY_ENHANCEMENTS_ENABLED` from menuconfig.
To use this feature, enable configuration option :menuitem:`CONFIG_ESP_WIFI_PRIVACY_ENHANCEMENTS_ENABLED` from menuconfig.
{IDF_TARGET_NAME} also rotates the STA random MAC periodically while not connected, using menuconfig option :ref:`CONFIG_ESP_WIFI_RMAC_AUTO_RESET_INTERVAL` (valid range: 1 to 24 hours, default 12).
{IDF_TARGET_NAME} also rotates the STA random MAC periodically while not connected, using menuconfig option :menuitem:`CONFIG_ESP_WIFI_RMAC_AUTO_RESET_INTERVAL` (valid range: 1 to 24 hours, default 12).
.. note::
The :ref:`CONFIG_ESP_WIFI_RMAC_AUTO_RESET_INTERVAL` will only generate and set new random mac address when station is not connected to any AP. If the station is connected to any AP, the connection will not be interrupted and same random mac will be used. If the periodic auto-reset timer expires while the station is in the connected state, the timer will be armed/triggered at the next disconnect.
The :menuitem:`CONFIG_ESP_WIFI_RMAC_AUTO_RESET_INTERVAL` will only generate and set new random mac address when station is not connected to any AP. If the station is connected to any AP, the connection will not be interrupted and same random mac will be used. If the periodic auto-reset timer expires while the station is in the connected state, the timer will be armed/triggered at the next disconnect.
WiFi privacy enhancements are not supported and will not work when Wi-Fi Mesh or ESP-NOW is enabled.
{IDF_TARGET_NAME} supports privacy enhancements while scanning when
- enable configuration option :ref:`CONFIG_ESP_WIFI_PRIVACY_ENHANCEMENTS_ENABLED` from menuconfig
- enable configuration option :menuitem:`CONFIG_ESP_WIFI_PRIVACY_ENHANCEMENTS_ENABLED` from menuconfig
- scan_type is :cpp:enumerator:`WIFI_SCAN_TYPE_ACTIVE`
- station is not connected to any Access Point
{IDF_TARGET_NAME} supports privacy enhancements while connecting when
- enable configuration option :ref:`CONFIG_ESP_WIFI_PRIVACY_ENHANCEMENTS_ENABLED` from menuconfig
- enable configuration option :menuitem:`CONFIG_ESP_WIFI_PRIVACY_ENHANCEMENTS_ENABLED` from menuconfig
- new wifi configuration is set using :cpp:func:`esp_wifi_set_config`

2
docs/en/api-reference/bluetooth/nimble/index.rst
View File

@@ -27,7 +27,7 @@ The NimBLE host can run inside the application thread or can have its own indepe
Programming Sequence
====================
To begin with, make sure that the NimBLE stack is enabled from menuconfig :ref:`choose NimBLE for the Bluetooth host <CONFIG_BT_HOST>`.
To begin with, make sure that the NimBLE stack is enabled from menuconfig :menuitem:`choose NimBLE for the Bluetooth host <CONFIG_BT_HOST>`.
Typical programming sequence with NimBLE stack consists of the following steps:
* Initialize NVS flash using :cpp:func:`nvs_flash_init` API. This is because ESP controller uses NVS during initialization.

6
docs/en/api-reference/network/esp_eth.rst
View File

@@ -170,7 +170,7 @@ The Ethernet driver is composed of two parts: MAC and PHY.
.. only:: esp32p4
.. warning::
If the RMII clock mode is configured to :cpp:enumerator:`emac_rmii_clock_mode_t::EMAC_CLK_OUT`, the EMAC derives the 50 MHz RMII reference clock from the MPLL via an integer divider. When PSRAM is also enabled, both peripherals share the MPLL, and PSRAM locks it to a frequency determined by its speed configuration. If PSRAM speed is configured to 80 MHz (:ref:`CONFIG_SPIRAM_SPEED`), the MPLL runs at 320 MHz, and no integer divisor of 320 MHz can produce 50 MHz within the required ±50 ppm tolerance (the closest candidate is 320 / 6 ≈ 53.33 MHz). EMAC initialization will fail in this configuration.
If the RMII clock mode is configured to :cpp:enumerator:`emac_rmii_clock_mode_t::EMAC_CLK_OUT`, the EMAC derives the 50 MHz RMII reference clock from the MPLL via an integer divider. When PSRAM is also enabled, both peripherals share the MPLL, and PSRAM locks it to a frequency determined by its speed configuration. If PSRAM speed is configured to 80 MHz (:menuitem:`CONFIG_SPIRAM_SPEED`), the MPLL runs at 320 MHz, and no integer divisor of 320 MHz can produce 50 MHz within the required ±50 ppm tolerance (the closest candidate is 320 / 6 ≈ 53.33 MHz). EMAC initialization will fail in this configuration.
If you must use 80 MHz PSRAM speed, provide the ``REF_CLK`` from an external source (PHY or oscillator) and configure :cpp:enumerator:`emac_rmii_clock_mode_t::EMAC_CLK_EXT_IN` instead.
@@ -265,9 +265,9 @@ Basic common configuration for MAC layer is described in :cpp:class:`eth_mac_con
.. list::
* **Short and frequent frames dominate network traffic**: If your network traffic primarily consists of very short and frequently transmitted/received frames, you may observe issues such as lower-than-expected throughput (despite the rated 100 Mbps) and missed frames during reception. On transmission, the socket send API may return ``errno`` equal to ``ENOMEM``, accompanied by the `insufficient TX buffer size` message (if debug log level is enabled). This is because the default memory configuration is optimized for larger frames; :ref:`CONFIG_ETH_DMA_BUFFER_SIZE` is set to 512 bytes by default to ensure a better *data buffer* to *descriptor* size overhead ratio. The solution is to increase :ref:`CONFIG_ETH_DMA_RX_BUFFER_NUM` or :ref:`CONFIG_ETH_DMA_TX_BUFFER_NUM`. Additionally, consider decreasing :ref:`CONFIG_ETH_DMA_BUFFER_SIZE` to match the typical frame size in your network to maintain a reasonable memory footprint of the Ethernet driver.
* **Short and frequent frames dominate network traffic**: If your network traffic primarily consists of very short and frequently transmitted/received frames, you may observe issues such as lower-than-expected throughput (despite the rated 100 Mbps) and missed frames during reception. On transmission, the socket send API may return ``errno`` equal to ``ENOMEM``, accompanied by the `insufficient TX buffer size` message (if debug log level is enabled). This is because the default memory configuration is optimized for larger frames; :menuitem:`CONFIG_ETH_DMA_BUFFER_SIZE` is set to 512 bytes by default to ensure a better *data buffer* to *descriptor* size overhead ratio. The solution is to increase :menuitem:`CONFIG_ETH_DMA_RX_BUFFER_NUM` or :menuitem:`CONFIG_ETH_DMA_TX_BUFFER_NUM`. Additionally, consider decreasing :menuitem:`CONFIG_ETH_DMA_BUFFER_SIZE` to match the typical frame size in your network to maintain a reasonable memory footprint of the Ethernet driver.
* **High throughput leads to buffer exhaustion**: If the socket send API intermittently returns ``errno`` equal to ``ENOMEM``, accompanied by the `insufficient TX buffer size` message (if debug log level is enabled), and the throughput is close to the rated 100 Mbps, this likely indicates nearing hardware limitations. In such case, the hardware cannot keep up with the transmission requests. The solution is to increase :ref:`CONFIG_ETH_DMA_TX_BUFFER_NUM` to buffer more frames and mitigate temporary peaks in transmission requests. However, this will not help if the requested traffic consistently exceeds the rated throughput. In such situations, the only solution is to limit the bandwidth by software means at the application level.
* **High throughput leads to buffer exhaustion**: If the socket send API intermittently returns ``errno`` equal to ``ENOMEM``, accompanied by the `insufficient TX buffer size` message (if debug log level is enabled), and the throughput is close to the rated 100 Mbps, this likely indicates nearing hardware limitations. In such case, the hardware cannot keep up with the transmission requests. The solution is to increase :menuitem:`CONFIG_ETH_DMA_TX_BUFFER_NUM` to buffer more frames and mitigate temporary peaks in transmission requests. However, this will not help if the requested traffic consistently exceeds the rated throughput. In such situations, the only solution is to limit the bandwidth by software means at the application level.
Configuration for PHY is described in :cpp:class:`eth_phy_config_t`, including:

4
docs/en/api-reference/network/esp_netif.rst
View File

@@ -137,8 +137,8 @@ Registering event handlers is crucial due to the asynchronous nature of networki
.. note::
Lost IP events are triggered by a timer that can be enabled or disabled by :ref:`CONFIG_ESP_NETIF_LOST_IP_TIMER_ENABLE`,
with the delay configured by :ref:`CONFIG_ESP_NETIF_IP_LOST_TIMER_INTERVAL`. The timer is started upon losing the IP address, and the event is raised after the configured interval (120 s by default).
Lost IP events are triggered by a timer that can be enabled or disabled by :menuitem:`CONFIG_ESP_NETIF_LOST_IP_TIMER_ENABLE`,
with the delay configured by :menuitem:`CONFIG_ESP_NETIF_IP_LOST_TIMER_INTERVAL`. The timer is started upon losing the IP address, and the event is raised after the configured interval (120 s by default).
For backward compatibility, setting the interval to 0 also disables the timer.
.. _esp-netif structure:

14
docs/en/api-reference/network/esp_netif_programming.rst
View File

@@ -97,13 +97,13 @@ Initialize the module with the default configuration after connecting to the net
.. note::
If you want to configure multiple SNTP servers, update the lwIP configuration option :ref:`CONFIG_LWIP_SNTP_MAX_SERVERS`.
If you want to configure multiple SNTP servers, update the lwIP configuration option :menuitem:`CONFIG_LWIP_SNTP_MAX_SERVERS`.
Use DHCP-Obtained SNTP Server(s)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
First, you need to enable the lwIP configuration option :ref:`CONFIG_LWIP_DHCP_GET_NTP_SRV`. Then, initialize the SNTP module with the DHCP option, without specifying an NTP server.
First, you need to enable the lwIP configuration option :menuitem:`CONFIG_LWIP_DHCP_GET_NTP_SRV`. Then, initialize the SNTP module with the DHCP option, without specifying an NTP server.
.. code-block:: c
@@ -158,11 +158,11 @@ This filtering is essential because the ESP-NETIF L2 TAP works alongside the IP
Initialization
^^^^^^^^^^^^^^
To be able to use the ESP-NETIF L2 TAP interface, it needs to be enabled in Kconfig by :ref:`CONFIG_ESP_NETIF_L2_TAP` first and then registered by :cpp:func:`esp_vfs_l2tap_intf_register()` prior usage of any VFS function.
To be able to use the ESP-NETIF L2 TAP interface, it needs to be enabled in Kconfig by :menuitem:`CONFIG_ESP_NETIF_L2_TAP` first and then registered by :cpp:func:`esp_vfs_l2tap_intf_register()` prior usage of any VFS function.
``open()``
^^^^^^^^^^
Once the ESP-NETIF L2 TAP is registered, it can be opened at path name "/dev/net/tap". The same path name can be opened multiple times up to :ref:`CONFIG_ESP_NETIF_L2_TAP_MAX_FDS` and multiple file descriptors with a different configuration may access the Data Link Layer frames.
Once the ESP-NETIF L2 TAP is registered, it can be opened at path name "/dev/net/tap". The same path name can be opened multiple times up to :menuitem:`CONFIG_ESP_NETIF_L2_TAP_MAX_FDS` and multiple file descriptors with a different configuration may access the Data Link Layer frames.
The ESP-NETIF L2 TAP can be opened with the ``O_NONBLOCK`` file status flag to make sure the ``read()`` does not block. Note that the ``write()`` may block in the current implementation when accessing a Network interface since it is a shared resource among multiple ESP-NETIF L2 TAP file descriptors and IP stack, and there is currently no queuing mechanism deployed. The file status flag can be retrieved and modified using ``fcntl()``.
@@ -210,7 +210,7 @@ The following commands manipulate the status flags associated with the file desc
``read()``
^^^^^^^^^^
Opened and configured ESP-NETIF L2 TAP file descriptor can be accessed by ``read()`` to get inbound frames. The read operation can be either blocking or non-blocking based on the actual state of the ``O_NONBLOCK`` file status flag. When the file status flag is set to blocking, the read operation waits until a frame is received and the context is switched to other tasks. When the file status flag is set to non-blocking, the read operation returns immediately. In such case, either a frame is returned if it was already queued or the function indicates the queue is empty. The number of queued frames associated with one file descriptor is limited by :ref:`CONFIG_ESP_NETIF_L2_TAP_RX_QUEUE_SIZE` Kconfig option. Once the number of queued frames reached a configured threshold, the newly arrived frames are dropped until the queue has enough room to accept incoming traffic (Tail Drop queue management).
Opened and configured ESP-NETIF L2 TAP file descriptor can be accessed by ``read()`` to get inbound frames. The read operation can be either blocking or non-blocking based on the actual state of the ``O_NONBLOCK`` file status flag. When the file status flag is set to blocking, the read operation waits until a frame is received and the context is switched to other tasks. When the file status flag is set to non-blocking, the read operation returns immediately. In such case, either a frame is returned if it was already queued or the function indicates the queue is empty. The number of queued frames associated with one file descriptor is limited by :menuitem:`CONFIG_ESP_NETIF_L2_TAP_RX_QUEUE_SIZE` Kconfig option. Once the number of queued frames reached a configured threshold, the newly arrived frames are dropped until the queue has enough room to accept incoming traffic (Tail Drop queue management).
| On success, ``read()`` returns the number of bytes read. Zero is returned when the size of the destination buffer is 0. On error, -1 is returned, and ``errno`` is set to indicate the error.
| * EBADF - not a valid file descriptor.
@@ -254,7 +254,7 @@ Opened ESP-NETIF L2 TAP file descriptor can be closed by the ``close()`` to free
``select()``
^^^^^^^^^^^^
Select is used in a standard way, just :ref:`CONFIG_VFS_SUPPORT_SELECT` needs to be enabled to make the ``select()`` function available.
Select is used in a standard way, just :menuitem:`CONFIG_VFS_SUPPORT_SELECT` needs to be enabled to make the ``select()`` function available.
.. _esp_netif_l2tap_ext_buff:
@@ -340,7 +340,7 @@ Enabling the Event
**Compile Time:**
The feature can be completely disabled during compilation time using the flag :ref:`CONFIG_ESP_NETIF_REPORT_DATA_TRAFFIC` in the kconfig.
The feature can be completely disabled during compilation time using the flag :menuitem:`CONFIG_ESP_NETIF_REPORT_DATA_TRAFFIC` in the kconfig.
**Run Time:**

4
docs/en/api-reference/network/esp_now.rst
View File

@@ -106,11 +106,11 @@ For the receiving device, calling :cpp:func:`esp_now_add_peer()` is not required
.. only:: esp32c2
The maximum number of paired devices is 20, and the paired encryption devices are no more than 4, the default is 2. If you want to change the number of paired encryption devices, set :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM` in the Wi-Fi component configuration menu.
The maximum number of paired devices is 20, and the paired encryption devices are no more than 4, the default is 2. If you want to change the number of paired encryption devices, set :menuitem:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM` in the Wi-Fi component configuration menu.
.. only:: esp32 or esp32s2 or esp32s3 or esp32c3 or esp32c6 or esp32c5
The maximum number of paired devices is 20, and the paired encryption devices are no more than 17, the default is 7. If you want to change the number of paired encryption devices, set :ref:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM` in the Wi-Fi component configuration menu.
The maximum number of paired devices is 20, and the paired encryption devices are no more than 17, the default is 7. If you want to change the number of paired encryption devices, set :menuitem:`CONFIG_ESP_WIFI_ESPNOW_MAX_ENCRYPT_NUM` in the Wi-Fi component configuration menu.
Send ESP-NOW Data
-----------------

6
docs/en/api-reference/peripherals/adc/adc_calibration.rst
View File

@@ -185,9 +185,9 @@ Other functions that take the :cpp:type:`adc_cali_handle_t` as the first positio
Kconfig Options
^^^^^^^^^^^^^^^
- :ref:`CONFIG_ADC_CALI_EFUSE_TP_ENABLE` - disable this to decrease the code size, if the calibration eFuse value is not set to :cpp:type:`ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_TP`.
- :ref:`CONFIG_ADC_CALI_EFUSE_VREF_ENABLE` - disable this to decrease the code size, if the calibration eFuse value is not set to :cpp:type:`ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_VREF`.
- :ref:`CONFIG_ADC_CALI_LUT_ENABLE` - disable this to decrease the code size, if you do not calibrate the ADC raw results under :c:macro:`ADC_ATTEN_DB_12`.
- :menuitem:`CONFIG_ADC_CALI_EFUSE_TP_ENABLE` - disable this to decrease the code size, if the calibration eFuse value is not set to :cpp:type:`ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_TP`.
- :menuitem:`CONFIG_ADC_CALI_EFUSE_VREF_ENABLE` - disable this to decrease the code size, if the calibration eFuse value is not set to :cpp:type:`ADC_CALI_LINE_FITTING_EFUSE_VAL_EFUSE_VREF`.
- :menuitem:`CONFIG_ADC_CALI_LUT_ENABLE` - disable this to decrease the code size, if you do not calibrate the ADC raw results under :c:macro:`ADC_ATTEN_DB_12`.
.. _adc-minimize-noise:

12
docs/en/api-reference/peripherals/adc/adc_continuous.rst
View File

@@ -252,7 +252,7 @@ As the above callbacks are called in an ISR context, you should always ensure th
You can also register your own context when calling :cpp:func:`adc_continuous_register_event_callbacks` by the parameter ``user_data``. This user data will be passed to the callback functions directly.
This function may fail due to reasons like :c:macro:`ESP_ERR_INVALID_ARG`. Especially, when :ref:`CONFIG_ADC_CONTINUOUS_ISR_IRAM_SAFE` is enabled, this error may indicate that the callback functions are not in the internal RAM. Check the error log for more details. Besides, when it fails due to :c:macro:`ESP_ERR_INVALID_STATE`, it indicates that the ADC continuous mode driver is started, and you should not add a callback at this moment.
This function may fail due to reasons like :c:macro:`ESP_ERR_INVALID_ARG`. Especially, when :menuitem:`CONFIG_ADC_CONTINUOUS_ISR_IRAM_SAFE` is enabled, this error may indicate that the callback functions are not in the internal RAM. Check the error log for more details. Besides, when it fails due to :c:macro:`ESP_ERR_INVALID_STATE`, it indicates that the ADC continuous mode driver is started, and you should not add a callback at this moment.
Conversion Done Event
@@ -266,7 +266,7 @@ When the driver completes a conversion, it triggers the :cpp:member:`adc_continu
.. note::
When the Kconfig option :ref:`CONFIG_ADC_CONTINUOUS_ISR_IRAM_SAFE` is enabled, the registered callbacks and the functions called by the callbacks should be placed in IRAM. The involved variables should be placed in internal RAM as well.
When the Kconfig option :menuitem:`CONFIG_ADC_CONTINUOUS_ISR_IRAM_SAFE` is enabled, the registered callbacks and the functions called by the callbacks should be placed in IRAM. The involved variables should be placed in internal RAM as well.
Pool Overflow Event
~~~~~~~~~~~~~~~~~~~
@@ -395,15 +395,15 @@ Hardware Limitations
:esp32: - ESP32 DevKitC: GPIO 0 cannot be used due to external auto program circuits.
:esp32: - ESP-WROVER-KIT: GPIO 0, 2, 4, and 15 cannot be used due to external connections for different purposes.
:esp32s2: - ADC continuous mode driver uses SPI3 peripheral as hardware DMA FIFO. Therefore, if SPI3 is in use already, the :cpp:func:`adc_continuous_new_handle` will return :c:macro:`ESP_ERR_NOT_FOUND`.
:esp32c3: - ADC2 DMA functionality is no longer supported to retrieve ADC conversion results due to hardware limitations, as unstable results have been observed. This issue can be found in `ESP32C3 Errata <https://www.espressif.com/sites/default/files/documentation/esp32-c3_errata_en.pdf>`_. For compatibility, you can enable :ref:`CONFIG_ADC_CONTINUOUS_FORCE_USE_ADC2_ON_C3_S3` to force use ADC2.
:esp32s3: - ADC2 DMA functionality is no longer supported to retrieve ADC conversion results due to hardware limitations, as unstable results have been observed. This issue can be found in `ESP32S3 Errata <https://www.espressif.com/sites/default/files/documentation/esp32-s3_errata_en.pdf>`_. For compatibility, you can enable :ref:`CONFIG_ADC_CONTINUOUS_FORCE_USE_ADC2_ON_C3_S3` to force use ADC2.
:esp32c3: - ADC2 DMA functionality is no longer supported to retrieve ADC conversion results due to hardware limitations, as unstable results have been observed. This issue can be found in `ESP32C3 Errata <https://www.espressif.com/sites/default/files/documentation/esp32-c3_errata_en.pdf>`_. For compatibility, you can enable :menuitem:`CONFIG_ADC_CONTINUOUS_FORCE_USE_ADC2_ON_C3_S3` to force use ADC2.
:esp32s3: - ADC2 DMA functionality is no longer supported to retrieve ADC conversion results due to hardware limitations, as unstable results have been observed. This issue can be found in `ESP32S3 Errata <https://www.espressif.com/sites/default/files/documentation/esp32-s3_errata_en.pdf>`_. For compatibility, you can enable :menuitem:`CONFIG_ADC_CONTINUOUS_FORCE_USE_ADC2_ON_C3_S3` to force use ADC2.
.. _adc-continuous-power-management:
Power Management
^^^^^^^^^^^^^^^^
When power management is enabled, i.e., :ref:`CONFIG_PM_ENABLE` is on, the APB clock frequency may be adjusted when the system is in an idle state, thus potentially changing the behavior of ADC continuous conversion.
When power management is enabled, i.e., :menuitem:`CONFIG_PM_ENABLE` is on, the APB clock frequency may be adjusted when the system is in an idle state, thus potentially changing the behavior of ADC continuous conversion.
However, the continuous mode driver can prevent this change by acquiring a power management lock of type :cpp:enumerator:`ESP_PM_APB_FREQ_MAX`. The lock is acquired after the continuous conversion is started by :cpp:func:`adc_continuous_start`. Similarly, the lock will be released after :cpp:func:`adc_continuous_stop`. Therefore, :cpp:func:`adc_continuous_start` and :cpp:func:`adc_continuous_stop` should appear in pairs, otherwise, the power management will be out of action.
@@ -413,7 +413,7 @@ However, the continuous mode driver can prevent this change by acquiring a power
IRAM Safe
^^^^^^^^^
All the ADC continuous mode driver APIs are not IRAM-safe. They are not supposed to be run when the Cache is disabled. By enabling the Kconfig option :ref:`CONFIG_ADC_CONTINUOUS_ISR_IRAM_SAFE`, the driver's internal ISR handler is IRAM-safe, which means even when the Cache is disabled, the driver will still save the conversion results into its internal pool.
All the ADC continuous mode driver APIs are not IRAM-safe. They are not supposed to be run when the Cache is disabled. By enabling the Kconfig option :menuitem:`CONFIG_ADC_CONTINUOUS_ISR_IRAM_SAFE`, the driver's internal ISR handler is IRAM-safe, which means even when the Cache is disabled, the driver will still save the conversion results into its internal pool.
.. _adc-continuous-thread-safety:

6
docs/en/api-reference/peripherals/adc/adc_oneshot.rst
View File

@@ -163,7 +163,7 @@ Hardware Limitations
:SOC_ADC_DMA_SUPPORTED: - A specific ADC unit can only work under one operating mode at any one time, either continuous mode or oneshot mode. :cpp:func:`adc_oneshot_read` has provided the protection.
:SOC_ADC_DIFF_SUPPORTED: - In single-ended mode, if the N-side channel is used as the input interface, its raw-data polarity is inverted. For an input range of -2 to 2, the N-side raw code is 4393 to 0. Please use the ADC calibration APIs.
:esp32 or esp32s2 or esp32s3: - ADC2 is also used by Wi-Fi. :cpp:func:`adc_oneshot_read` has provided protection between the Wi-Fi driver and ADC oneshot mode driver.
:esp32c3: - ADC2 oneshot mode is no longer supported, due to hardware limitations. The results are not stable. This issue can be found in `ESP32-C3 Series SoC Errata <https://www.espressif.com/sites/default/files/documentation/esp32-c3_errata_en.pdf>`_. For compatibility, you can enable :ref:`CONFIG_ADC_ONESHOT_FORCE_USE_ADC2_ON_C3` to force use ADC2.
:esp32c3: - ADC2 oneshot mode is no longer supported, due to hardware limitations. The results are not stable. This issue can be found in `ESP32-C3 Series SoC Errata <https://www.espressif.com/sites/default/files/documentation/esp32-c3_errata_en.pdf>`_. For compatibility, you can enable :menuitem:`CONFIG_ADC_ONESHOT_FORCE_USE_ADC2_ON_C3` to force use ADC2.
:esp32: - ESP32-DevKitC: GPIO0 cannot be used in oneshot mode, because the DevKit has used it for auto-flash.
:esp32: - ESP-WROVER-KIT: GPIO 0, 2, 4, and 15 cannot be used due to external connections for different purposes.
@@ -172,7 +172,7 @@ Hardware Limitations
Power Management
^^^^^^^^^^^^^^^^
When power management is enabled, i.e., :ref:`CONFIG_PM_ENABLE` is on, the system clock frequency may be adjusted when the system is in an idle state. However, the ADC oneshot mode driver works in a polling routine, the :cpp:func:`adc_oneshot_read` will poll the CPU until the function returns. During this period of time, the task in which ADC oneshot mode driver resides will not be blocked. Therefore the clock frequency is stable when reading.
When power management is enabled, i.e., :menuitem:`CONFIG_PM_ENABLE` is on, the system clock frequency may be adjusted when the system is in an idle state. However, the ADC oneshot mode driver works in a polling routine, the :cpp:func:`adc_oneshot_read` will poll the CPU until the function returns. During this period of time, the task in which ADC oneshot mode driver resides will not be blocked. Therefore the clock frequency is stable when reading.
.. _adc-oneshot-iram-safe:
@@ -201,7 +201,7 @@ Above functions are guaranteed to be thread-safe. Therefore, you can call them f
Kconfig Options
^^^^^^^^^^^^^^^
- :ref:`CONFIG_ADC_ONESHOT_CTRL_FUNC_IN_IRAM` controls where to place the ADC fast read function (IRAM or Flash), see :ref:`adc-oneshot-iram-safe` for more details.
- :menuitem:`CONFIG_ADC_ONESHOT_CTRL_FUNC_IN_IRAM` controls where to place the ADC fast read function (IRAM or Flash), see :ref:`adc-oneshot-iram-safe` for more details.
Application Examples

14
docs/en/api-reference/peripherals/ana_cmpr.rst
View File

@@ -240,7 +240,7 @@ The callback runs in interrupt context, so keep it short and non-blocking.
.. note::
If :ref:`CONFIG_ANA_CMPR_ISR_CACHE_SAFE` is enabled, place the callback and any accessed data in internal RAM.
If :menuitem:`CONFIG_ANA_CMPR_ISR_CACHE_SAFE` is enabled, place the callback and any accessed data in internal RAM.
Scenario 2: Compare a Signal Against an External Reference
==========================================================
@@ -535,16 +535,16 @@ While enabled, only a limited set of runtime control functions are intended to b
Power Management
----------------
When :ref:`CONFIG_PM_ENABLE` is enabled, sleep and clock changes can affect the comparator. The driver uses a power management lock internally when needed, so enabling the comparator can prevent light sleep while the unit is active.
When :menuitem:`CONFIG_PM_ENABLE` is enabled, sleep and clock changes can affect the comparator. The driver uses a power management lock internally when needed, so enabling the comparator can prevent light sleep while the unit is active.
If power consumption matters, structure your application so the comparator is only enabled when needed.
IRAM Safe
---------
If you need comparator interrupts to keep working while the cache is disabled, enable :ref:`CONFIG_ANA_CMPR_ISR_CACHE_SAFE`.
If you need comparator interrupts to keep working while the cache is disabled, enable :menuitem:`CONFIG_ANA_CMPR_ISR_CACHE_SAFE`.
If you also need the runtime control functions to remain callable in that situation, enable :ref:`CONFIG_ANA_CMPR_CTRL_FUNC_IN_IRAM`.
If you also need the runtime control functions to remain callable in that situation, enable :menuitem:`CONFIG_ANA_CMPR_CTRL_FUNC_IN_IRAM`.
The following control APIs can be placed in IRAM:
@@ -569,11 +569,11 @@ Kconfig Options
The most relevant Kconfig options are:
- :ref:`CONFIG_ANA_CMPR_ISR_CACHE_SAFE`
- :menuitem:`CONFIG_ANA_CMPR_ISR_CACHE_SAFE`
Keeps the default ISR path available when cache is disabled. Enable this if comparator interrupts must work in cache-off windows.
- :ref:`CONFIG_ANA_CMPR_CTRL_FUNC_IN_IRAM`
- :menuitem:`CONFIG_ANA_CMPR_CTRL_FUNC_IN_IRAM`
Places ISR-callable runtime control APIs in IRAM, so they remain callable when cache is disabled.
- :ref:`CONFIG_ANA_CMPR_ENABLE_DEBUG_LOG`
- :menuitem:`CONFIG_ANA_CMPR_ENABLE_DEBUG_LOG`
Enables driver debug logs for troubleshooting and bring-up. This increases binary size and log verbosity.
Examples

8
docs/en/api-reference/peripherals/camera_driver.rst
View File

@@ -327,8 +327,8 @@ The following Kconfig options affect interrupt handler behavior when the cache i
.. list::
:SOC_MIPI_CSI_SUPPORTED: - :ref:`CONFIG_CAM_CTLR_MIPI_CSI_ISR_CACHE_SAFE`, see :ref:`cam-thread-safety` for details.
:SOC_ISP_DVP_SUPPORTED: - :ref:`CONFIG_CAM_CTLR_ISP_DVP_ISR_CACHE_SAFE`, see :ref:`cam-thread-safety` for details.
:SOC_MIPI_CSI_SUPPORTED: - :menuitem:`CONFIG_CAM_CTLR_MIPI_CSI_ISR_CACHE_SAFE`, see :ref:`cam-thread-safety` for details.
:SOC_ISP_DVP_SUPPORTED: - :menuitem:`CONFIG_CAM_CTLR_ISP_DVP_ISR_CACHE_SAFE`, see :ref:`cam-thread-safety` for details.
.. _cam-iram-safe:
@@ -341,8 +341,8 @@ The following Kconfig options:
.. list::
:SOC_MIPI_CSI_SUPPORTED: - :ref:`CONFIG_CAM_CTLR_MIPI_CSI_ISR_CACHE_SAFE`
:SOC_ISP_DVP_SUPPORTED: - :ref:`CONFIG_CAM_CTLR_ISP_DVP_ISR_CACHE_SAFE`
:SOC_MIPI_CSI_SUPPORTED: - :menuitem:`CONFIG_CAM_CTLR_MIPI_CSI_ISR_CACHE_SAFE`
:SOC_ISP_DVP_SUPPORTED: - :menuitem:`CONFIG_CAM_CTLR_ISP_DVP_ISR_CACHE_SAFE`
- Enable the interrupt being serviced even when the cache is disabled.
- Place all functions used by the ISR into IRAM.

2
docs/en/api-reference/peripherals/cordic.rst
View File

@@ -299,7 +299,7 @@ Kconfig Options
The following Kconfig option configures the CORDIC driver:
- :ref:`CONFIG_CORDIC_ONESHOT_CTRL_FUNC_IN_IRAM` - Place calculation control functions in IRAM.
- :menuitem:`CONFIG_CORDIC_ONESHOT_CTRL_FUNC_IN_IRAM` - Place calculation control functions in IRAM.
API Reference
=============

12
docs/en/api-reference/peripherals/dac.rst
View File

@@ -83,7 +83,7 @@ The following diagram illustrates the life cycle of the DAC continuous driver an
.. only:: esp32
On ESP32, the DAC digital controller can be connected internally to the I2S0 and use its DMA for continuous conversion. Although the DAC only needs 8-bit data for conversion, it has to be the left-shifted 8 bits (i.e., the high 8 bits in a 16-bit slot) to satisfy the I2S communication format. By default, the driver helps to expand the data to 16-bit wide automatically. To expand manually, please disable :ref:`CONFIG_DAC_DMA_AUTO_16BIT_ALIGN` in the menuconfig.
On ESP32, the DAC digital controller can be connected internally to the I2S0 and use its DMA for continuous conversion. Although the DAC only needs 8-bit data for conversion, it has to be the left-shifted 8 bits (i.e., the high 8 bits in a 16-bit slot) to satisfy the I2S communication format. By default, the driver helps to expand the data to 16-bit wide automatically. To expand manually, please disable :menuitem:`CONFIG_DAC_DMA_AUTO_16BIT_ALIGN` in the menuconfig.
The clock of the DAC digital controller comes from I2S0 as well, so there are two clock sources for selection:
@@ -110,7 +110,7 @@ Currently, the clock source of the cosine wave generator only comes from ``RTC_F
Power Management
^^^^^^^^^^^^^^^^
When the power management is enabled (i.e., :ref:`CONFIG_PM_ENABLE` is on), the system will adjust or stop the clock source of DAC before entering Light-sleep mode, thus potential influence to the DAC signals may lead to false data conversion.
When the power management is enabled (i.e., :menuitem:`CONFIG_PM_ENABLE` is on), the system will adjust or stop the clock source of DAC before entering Light-sleep mode, thus potential influence to the DAC signals may lead to false data conversion.
When using DAC driver in continuous mode, it can prevent the system from changing or stopping the clock source in DMA or cosine mode by acquiring a power management lock. When the clock source is generated from APB, the lock type will be set to :cpp:enumerator:`esp_pm_lock_type_t::ESP_PM_APB_FREQ_MAX`. When the clock source is APLL (only in DMA mode), it will be set to :cpp:enumerator:`esp_pm_lock_type_t::ESP_PM_NO_LIGHT_SLEEP`. Whenever the DAC is converting (i.e., DMA or cosine wave generator is working), the driver guarantees that the power management lock is acquired after calling :cpp:func:`dac_continuous_enable`. Likewise, the driver will release the lock when :cpp:func:`dac_continuous_disable` is called.
@@ -121,7 +121,7 @@ IRAM Safe
By default, the DAC DMA interrupt will be deferred when the cache is disabled for reasons like writing/erasing Flash. Thus the DMA EOF interrupt will not get executed in time.
To avoid such case in real-time applications, you can enable the Kconfig option :ref:`CONFIG_DAC_ISR_IRAM_SAFE` which:
To avoid such case in real-time applications, you can enable the Kconfig option :menuitem:`CONFIG_DAC_ISR_IRAM_SAFE` which:
1. Enables the interrupt being serviced even when cache is disabled;
@@ -137,12 +137,12 @@ All the public DAC APIs are guaranteed to be thread safe by the driver, which me
Kconfig Options
^^^^^^^^^^^^^^^
- :ref:`CONFIG_DAC_ISR_IRAM_SAFE` controls whether the default ISR handler can work when cache is disabled. See :ref:`dac-iram-safe` for more information.
- :ref:`CONFIG_DAC_ENABLE_DEBUG_LOG` is used to enable the debug log output. Enable this option increases the firmware binary size.
- :menuitem:`CONFIG_DAC_ISR_IRAM_SAFE` controls whether the default ISR handler can work when cache is disabled. See :ref:`dac-iram-safe` for more information.
- :menuitem:`CONFIG_DAC_ENABLE_DEBUG_LOG` is used to enable the debug log output. Enable this option increases the firmware binary size.
.. only:: esp32
- :ref:`CONFIG_DAC_DMA_AUTO_16BIT_ALIGN` auto expands the 8-bit data to 16-bit data in the driver to satisfy the I2S DMA format.
- :menuitem:`CONFIG_DAC_DMA_AUTO_16BIT_ALIGN` auto expands the 8-bit data to 16-bit data in the driver to satisfy the I2S DMA format.
Application Example
-------------------

2
docs/en/api-reference/peripherals/ds.rst
View File

@@ -51,7 +51,7 @@ The APIs :cpp:func:`esp_ds_sign` and :cpp:func:`esp_ds_start_sign` calculate a p
**PSA Crypto driver**
The RSA_DS peripheral is also exposed via the **PSA Crypto RSA_DS driver**, so you can use standard PSA APIs for signing (PKCS#1 v1.5 or PSS) and RSA decryption (PKCS#1 v1.5 or OAEP). Enable ``CONFIG_MBEDTLS_HARDWARE_RSA_DS_PERIPHERAL`` in ``Component config`` > ``mbedTLS``. For using the RSA_DS peripheral with ESP-TLS (e.g. TLS client authentication), see :ref:`digital-signature-with-esp-tls` in the ESP-TLS documentation.
The RSA_DS peripheral is also exposed via the **PSA Crypto RSA_DS driver**, so you can use standard PSA APIs for signing (PKCS#1 v1.5 or PSS) and RSA decryption (PKCS#1 v1.5 or OAEP). Enable :menuitem:`CONFIG_MBEDTLS_HARDWARE_RSA_DS_PERIPHERAL`. For using the RSA_DS peripheral with ESP-TLS (e.g. TLS client authentication), see :ref:`digital-signature-with-esp-tls` in the ESP-TLS documentation.
.. _configure-the-ds-peripheral:

2
docs/en/api-reference/peripherals/ecdsa.rst
View File

@@ -122,7 +122,7 @@ Following code snippet uses :cpp:func:`esp_efuse_write_key` to set physical key
The ECDSA_DS peripheral of {IDF_TARGET_NAME} supports both ECDSA-P192 and ECDSA-P256 operations, but only ECDSA-P256 operations are enabled by default. You can enable ECDSA-P192 operations through the following configuration options:
- :ref:`CONFIG_ESP_ECDSA_ENABLE_P192_CURVE` enables support for ECDSA-P192 curve operations, allowing the device to perform ECDSA operations with both 192-bit and 256-bit curves. However, if ECDSA-P192 operations have already been permanently disabled during eFuse write protection, enabling this option can not re-enable ECDSA-P192 curve operations.
- :menuitem:`CONFIG_ESP_ECDSA_ENABLE_P192_CURVE` enables support for ECDSA-P192 curve operations, allowing the device to perform ECDSA operations with both 192-bit and 256-bit curves. However, if ECDSA-P192 operations have already been permanently disabled during eFuse write protection, enabling this option can not re-enable ECDSA-P192 curve operations.
- :cpp:func:`esp_efuse_enable_ecdsa_p192_curve_mode()` enables ECDSA-P192 curve operations programmatically by writing the appropriate value to the eFuse, allowing both P-192 and P-256 curve operations. Note that this API will fail if the eFuse is already write-protected.

4
docs/en/api-reference/peripherals/etm.rst
View File

@@ -139,7 +139,7 @@ The digital ID printed in the dump information is defined in the ``soc/soc_etm_s
Power Management
^^^^^^^^^^^^^^^^
When power management is enabled, i.e., :ref:`CONFIG_PM_ENABLE` is on, the system may adjust or disable the clock source, and power off the ETM peripheral before going to sleep. As a result, the existing connection between events and tasks will be lost, and the ETM channels can't work correctly after wake up. So by default, the driver will acquire a power management lock internally to forbid the system from powering off the ETM peripheral.
When power management is enabled, i.e., :menuitem:`CONFIG_PM_ENABLE` is on, the system may adjust or disable the clock source, and power off the ETM peripheral before going to sleep. As a result, the existing connection between events and tasks will be lost, and the ETM channels can't work correctly after wake up. So by default, the driver will acquire a power management lock internally to forbid the system from powering off the ETM peripheral.
.. only:: SOC_ETM_SUPPORT_SLEEP_RETENTION
@@ -161,7 +161,7 @@ The ETM core driver is thread-safe.
Kconfig Options
^^^^^^^^^^^^^^^
- :ref:`CONFIG_ETM_ENABLE_DEBUG_LOG` is used to enable the debug log output. Enabling this option increases the firmware binary size as well.
- :menuitem:`CONFIG_ETM_ENABLE_DEBUG_LOG` is used to enable the debug log output. Enabling this option increases the firmware binary size as well.
API Reference
-------------

16
docs/en/api-reference/peripherals/gptimer.rst
View File

@@ -311,7 +311,7 @@ The GPTimer driver supports dynamically updating the alarm value in the interrup
Power Management
----------------
When power management :ref:`CONFIG_PM_ENABLE` is enabled, the system may adjust or disable the clock source before entering sleep mode, causing the GPTimer to lose accuracy.
When power management :menuitem:`CONFIG_PM_ENABLE` is enabled, the system may adjust or disable the clock source before entering sleep mode, causing the GPTimer to lose accuracy.
To prevent this, the GPTimer driver creates a power management lock internally. When the :cpp:func:`gptimer_enable` function is called, the lock is activated to ensure the system does not enter sleep mode, thus maintaining the timer's accuracy. To reduce power consumption, you can call the :cpp:func:`gptimer_disable` function to release the power management lock, allowing the system to enter sleep mode. However, this will stop the timer, so you need to restart the timer after waking up.
@@ -338,7 +338,7 @@ The following functions can also be used in an interrupt context:
Cache Safety
------------
When the file system performs Flash read/write operations, the system temporarily disables the Cache function to avoid errors when loading instructions and data from Flash. This causes the GPTimer interrupt handler to be unresponsive during this period, preventing the user callback function from executing in time. If you want the interrupt handler to run normally when the Cache is disabled, you can enable the :ref:`CONFIG_GPTIMER_ISR_CACHE_SAFE` option.
When the file system performs Flash read/write operations, the system temporarily disables the Cache function to avoid errors when loading instructions and data from Flash. This causes the GPTimer interrupt handler to be unresponsive during this period, preventing the user callback function from executing in time. If you want the interrupt handler to run normally when the Cache is disabled, you can enable the :menuitem:`CONFIG_GPTIMER_ISR_CACHE_SAFE` option.
.. note::
@@ -347,18 +347,18 @@ When the file system performs Flash read/write operations, the system temporaril
Performance
-----------
To improve the real-time responsiveness of interrupt handling, the GPTimer driver provides the :ref:`CONFIG_GPTIMER_ISR_HANDLER_IN_IRAM` option. Once enabled, the interrupt handler is placed in internal RAM, reducing delays caused by potential cache misses when loading instructions from Flash.
To improve the real-time responsiveness of interrupt handling, the GPTimer driver provides the :menuitem:`CONFIG_GPTIMER_ISR_HANDLER_IN_IRAM` option. Once enabled, the interrupt handler is placed in internal RAM, reducing delays caused by potential cache misses when loading instructions from Flash.
.. note::
However, the user callback function and its context data called by the interrupt handler may still reside in Flash. Cache misses are still possible, so users must manually place the callback function and data in internal RAM, for example by using :c:macro:`IRAM_ATTR` and :c:macro:`DRAM_ATTR`.
As mentioned above, the GPTimer driver allows some functions to be called in an interrupt context. By enabling the :ref:`CONFIG_GPTIMER_CTRL_FUNC_IN_IRAM` option, these functions can also be placed in IRAM, which helps avoid performance loss caused by cache misses and allows them to be used when the Cache is disabled.
As mentioned above, the GPTimer driver allows some functions to be called in an interrupt context. By enabling the :menuitem:`CONFIG_GPTIMER_CTRL_FUNC_IN_IRAM` option, these functions can also be placed in IRAM, which helps avoid performance loss caused by cache misses and allows them to be used when the Cache is disabled.
Other Kconfig Options
---------------------
- The :ref:`CONFIG_GPTIMER_ENABLE_DEBUG_LOG` option forces the GPTimer driver to enable all debug logs, regardless of the global log level settings. Enabling this option helps developers obtain more detailed log information during debugging, making it easier to locate and solve problems.
- The :menuitem:`CONFIG_GPTIMER_ENABLE_DEBUG_LOG` option forces the GPTimer driver to enable all debug logs, regardless of the global log level settings. Enabling this option helps developers obtain more detailed log information during debugging, making it easier to locate and solve problems.
Resource Consumption
--------------------
@@ -368,9 +368,9 @@ Use the :doc:`/api-guides/tools/idf-size` tool to check the code and data consum
- Compiler optimization level set to ``-Os`` to ensure minimal code size.
- Default log level set to ``ESP_LOG_INFO`` to balance debug information and performance.
- Disable the following driver optimization options:
- :ref:`CONFIG_GPTIMER_ISR_HANDLER_IN_IRAM` - Do not place the interrupt handler in IRAM.
- :ref:`CONFIG_GPTIMER_CTRL_FUNC_IN_IRAM` - Do not place control functions in IRAM.
- :ref:`CONFIG_GPTIMER_ISR_CACHE_SAFE` - Do not enable Cache safety options.
- :menuitem:`CONFIG_GPTIMER_ISR_HANDLER_IN_IRAM` - Do not place the interrupt handler in IRAM.
- :menuitem:`CONFIG_GPTIMER_CTRL_FUNC_IN_IRAM` - Do not place control functions in IRAM.
- :menuitem:`CONFIG_GPTIMER_ISR_CACHE_SAFE` - Do not enable Cache safety options.
**Note that the following data are not exact values and are for reference only; they may differ on different chip models.**

8
docs/en/api-reference/peripherals/i2c.rst
View File

@@ -625,7 +625,7 @@ Power Management
.. only:: SOC_I2C_SUPPORT_APB
When the power management is enabled (i.e. :ref:`CONFIG_PM_ENABLE` is on), the system will adjust or stop the source clock of I2C FIFO before going into Light-sleep mode, thus potentially changing the I2C signals and leading to transmitting or receiving invalid data.
When the power management is enabled (i.e. :menuitem:`CONFIG_PM_ENABLE` is on), the system will adjust or stop the source clock of I2C FIFO before going into Light-sleep mode, thus potentially changing the I2C signals and leading to transmitting or receiving invalid data.
However, the driver can prevent the system from changing APB frequency by acquiring a power management lock of type :cpp:enumerator:`ESP_PM_APB_FREQ_MAX`. Whenever user creates an I2C bus that has selected :cpp:enumerator:`I2C_CLK_SRC_APB` as the clock source, the driver will guarantee that the power management lock is acquired when I2C operations begin and the lock will be released automatically when I2C operations finish.
@@ -644,7 +644,7 @@ IRAM Safe
By default, the I2C interrupt will be deferred when the cache is disabled for reasons like writing or erasing flash. Thus the event callback functions will not get executed in time, which is not expected in a real-time application.
There's a Kconfig option :ref:`CONFIG_I2C_ISR_IRAM_SAFE` that will:
There's a Kconfig option :menuitem:`CONFIG_I2C_ISR_IRAM_SAFE` that will:
1. Enable the interrupt being serviced even when cache is disabled.
2. Place all functions that used by the ISR into IRAM.
@@ -678,8 +678,8 @@ Other functions are not guaranteed to be thread-safe. Thus, you should avoid cal
Kconfig Options
^^^^^^^^^^^^^^^
- :ref:`CONFIG_I2C_ISR_IRAM_SAFE` controls whether the default ISR handler can work when cache is disabled, see also :ref:`i2c-iram-safe` for more information.
- :ref:`CONFIG_I2C_ENABLE_DEBUG_LOG` is used to enable the debug log at the cost of increased firmware binary size.
- :menuitem:`CONFIG_I2C_ISR_IRAM_SAFE` controls whether the default ISR handler can work when cache is disabled, see also :ref:`i2c-iram-safe` for more information.
- :menuitem:`CONFIG_I2C_ENABLE_DEBUG_LOG` is used to enable the debug log at the cost of increased firmware binary size.
Application Examples
--------------------

8
docs/en/api-reference/peripherals/i2s.rst
View File

@@ -258,7 +258,7 @@ The public APIs are all channel-level APIs. The channel handle :cpp:type:`i2s_ch
Power Management
^^^^^^^^^^^^^^^^
When the power management is enabled (i.e., :ref:`CONFIG_PM_ENABLE` is on), the system will adjust or stop the source clock of I2S before entering Light-sleep, thus potentially changing the I2S signals and leading to transmitting or receiving invalid data.
When the power management is enabled (i.e., :menuitem:`CONFIG_PM_ENABLE` is on), the system will adjust or stop the source clock of I2S before entering Light-sleep, thus potentially changing the I2S signals and leading to transmitting or receiving invalid data.
The I2S driver can prevent the system from changing or stopping the source clock by acquiring a power management lock. When the source clock is generated from APB, the lock type will be set to :cpp:enumerator:`esp_pm_lock_type_t::ESP_PM_APB_FREQ_MAX` and when the source clock is APLL (if supported), it will be set to :cpp:enumerator:`esp_pm_lock_type_t::ESP_PM_NO_LIGHT_SLEEP`. The driver guarantees that the power management lock is acquired when the channel is enabled by :cpp:func:`i2s_channel_enable`. Likewise, the driver releases the lock when the channel is disabled by :cpp:func:`i2s_channel_disable`, which keeps the I2S source clock stable while the channel is running.
@@ -416,7 +416,7 @@ IRAM Safe
By default, the I2S interrupt will be deferred when the cache is disabled for reasons like writing/erasing flash. Thus the EOF interrupt will not get executed in time.
To avoid such case in real-time applications, you can enable the Kconfig option :ref:`CONFIG_I2S_ISR_IRAM_SAFE` that:
To avoid such case in real-time applications, you can enable the Kconfig option :menuitem:`CONFIG_I2S_ISR_IRAM_SAFE` that:
1. Keeps the interrupt being serviced even when the cache is disabled.
@@ -432,8 +432,8 @@ All the public I2S APIs are guaranteed to be thread safe by the driver, which me
Kconfig Options
^^^^^^^^^^^^^^^
- :ref:`CONFIG_I2S_ISR_IRAM_SAFE` controls whether the default ISR handler can work when the cache is disabled. See :ref:`i2s-iram-safe` for more information.
- :ref:`CONFIG_I2S_ENABLE_DEBUG_LOG` is used to enable the debug log output. Enable this option increases the firmware binary size.
- :menuitem:`CONFIG_I2S_ISR_IRAM_SAFE` controls whether the default ISR handler can work when the cache is disabled. See :ref:`i2s-iram-safe` for more information.
- :menuitem:`CONFIG_I2S_ENABLE_DEBUG_LOG` is used to enable the debug log output. Enable this option increases the firmware binary size.
Application Example
-------------------

12
docs/en/api-reference/peripherals/i3c_master.rst
View File

@@ -538,7 +538,7 @@ Enabling this option ensures interrupt operation when the cache is disabled, but
About Low Power Consumption
----------------------------
When power management :ref:`CONFIG_PM_ENABLE` is enabled, the system may adjust or disable clock sources before entering sleep mode, which can cause I3C transfer errors.
When power management :menuitem:`CONFIG_PM_ENABLE` is enabled, the system may adjust or disable clock sources before entering sleep mode, which can cause I3C transfer errors.
To prevent this from happening, the I3C driver internally creates a power management lock. After calling a transfer function, this lock will be activated to ensure the system does not enter sleep mode, thus maintaining the correct operation of the timer. After the transfer is complete, the driver automatically releases the lock, allowing the system to enter sleep mode.
@@ -547,9 +547,9 @@ Kconfig Options
The following Kconfig options can be used to configure the I3C driver:
- :ref:`CONFIG_I3C_MASTER_ISR_CACHE_SAFE`: Ensure I3C interrupts work properly when cache is disabled (e.g., during SPI Flash write)
- :ref:`CONFIG_I3C_MASTER_ISR_HANDLER_IN_IRAM`: Place I3C master ISR handler in IRAM to improve performance and reduce cache misses
- :ref:`CONFIG_I3C_MASTER_ENABLE_DEBUG_LOG`: Enable I3C debug logging
- :menuitem:`CONFIG_I3C_MASTER_ISR_CACHE_SAFE`: Ensure I3C interrupts work properly when cache is disabled (e.g., during SPI Flash write)
- :menuitem:`CONFIG_I3C_MASTER_ISR_HANDLER_IN_IRAM`: Place I3C master ISR handler in IRAM to improve performance and reduce cache misses
- :menuitem:`CONFIG_I3C_MASTER_ENABLE_DEBUG_LOG`: Enable I3C debug logging
About Resource Consumption
---------------------------
@@ -559,8 +559,8 @@ You can use the :doc:`/api-guides/tools/idf-size` tool to view the code and data
- Compiler optimization level is set to ``-Os`` to ensure minimal code size.
- Default log level is set to ``ESP_LOG_INFO`` to balance debug information and performance.
- The following driver optimization options are disabled:
- :ref:`CONFIG_I3C_MASTER_ISR_HANDLER_IN_IRAM` - ISR handler is not placed in IRAM.
- :ref:`CONFIG_I3C_MASTER_ISR_CACHE_SAFE` - Cache safety option is not enabled.
- :menuitem:`CONFIG_I3C_MASTER_ISR_HANDLER_IN_IRAM` - ISR handler is not placed in IRAM.
- :menuitem:`CONFIG_I3C_MASTER_ISR_CACHE_SAFE` - Cache safety option is not enabled.
**Note: The following data is not precise and is for reference only. Data may vary on different chip models.**

6
docs/en/api-reference/peripherals/isp.rst
View File

@@ -1117,7 +1117,7 @@ These functions can be called from different RTOS tasks without protection by ex
Kconfig Options
^^^^^^^^^^^^^^^
- :ref:`CONFIG_ISP_ISR_IRAM_SAFE` controls whether the default ISR handler should be masked when the cache is disabled.
- :menuitem:`CONFIG_ISP_ISR_IRAM_SAFE` controls whether the default ISR handler should be masked when the cache is disabled.
.. _isp-iram-safe:
@@ -1126,7 +1126,7 @@ IRAM Safe
By default, the ISP interrupt will be deferred when the cache is disabled because of writing or erasing the flash.
Kconfig option :ref:`CONFIG_ISP_ISR_IRAM_SAFE` will:
Kconfig option :menuitem:`CONFIG_ISP_ISR_IRAM_SAFE` will:
- Enable the interrupt being serviced even when the cache is disabled
- Place all functions that used by the ISR into IRAM
@@ -1134,7 +1134,7 @@ Kconfig option :ref:`CONFIG_ISP_ISR_IRAM_SAFE` will:
This allows the interrupt to run while the cache is disabled, but comes at the cost of increased IRAM consumption. With this option enabled, the ISR callbacks will be running when cache is disabled. Therefore you should make sure the callbacks and its involved context are IRAM-safe as well.
Kconfig option :ref:`CONFIG_ISP_CTRL_FUNC_IN_IRAM` will:
Kconfig option :menuitem:`CONFIG_ISP_CTRL_FUNC_IN_IRAM` will:
- Place some of the ISP control functions into IRAM, including:

4
docs/en/api-reference/peripherals/jpeg.rst
View File

@@ -565,7 +565,7 @@ The factory function :cpp:func:`jpeg_new_decoder_engine`, :cpp:func:`jpeg_decode
Power Management
^^^^^^^^^^^^^^^^
When power management is enabled (i.e., :ref:`CONFIG_PM_ENABLE` is set), the system needs to adjust or stop the source clock of JPEG to enter Light-sleep, thus potentially changing the JPEG decoder or encoder process. This might lead to unexpected behavior in hardware calculation. To prevent such issues, entering Light-sleep is disabled for the time when JPEG encoder or decoder is working.
When power management is enabled (i.e., :menuitem:`CONFIG_PM_ENABLE` is set), the system needs to adjust or stop the source clock of JPEG to enter Light-sleep, thus potentially changing the JPEG decoder or encoder process. This might lead to unexpected behavior in hardware calculation. To prevent such issues, entering Light-sleep is disabled for the time when JPEG encoder or decoder is working.
Whenever the user is decoding or encoding via JPEG (i.e., calling :cpp:func:`jpeg_encoder_process` or :cpp:func:`jpeg_decoder_process`), the driver guarantees that the power management lock is acquired by setting it to :cpp:enumerator:`esp_pm_lock_type_t::ESP_PM_CPU_FREQ_MAX`. Once the encoding or decoding is finished, the driver releases the lock and the system can enter Light-sleep.
@@ -592,7 +592,7 @@ Please note the following when using it:
Kconfig Options
^^^^^^^^^^^^^^^
- :ref:`CONFIG_JPEG_ENABLE_DEBUG_LOG` is used to enable the debug log at the cost of increased firmware binary size.
- :menuitem:`CONFIG_JPEG_ENABLE_DEBUG_LOG` is used to enable the debug log at the cost of increased firmware binary size.
Maintainers' Notes
------------------

4
docs/en/api-reference/peripherals/lcd/rgb_lcd.rst
View File

@@ -256,7 +256,7 @@ This mode allocates two "bounce buffers" from internal memory and a main frame b
.. note::
For optimal performance in this mode, it is highly recommended to enable the "PSRAM XIP (Execute In Place)" feature by turning on the Kconfig option: :ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM`. This allows the CPU to fetch instructions and read-only data directly from PSRAM instead of the main flash. Additionally, the external memory cache remains active even when writing to the main flash via SPI 1, making it feasible to display an OTA progress bar during your application updates.
For optimal performance in this mode, it is highly recommended to enable the "PSRAM XIP (Execute In Place)" feature by turning on the Kconfig option: :menuitem:`CONFIG_SPIRAM_XIP_FROM_PSRAM`. This allows the CPU to fetch instructions and read-only data directly from PSRAM instead of the main flash. Additionally, the external memory cache remains active even when writing to the main flash via SPI 1, making it feasible to display an OTA progress bar during your application updates.
.. note::
@@ -310,7 +310,7 @@ This mode is similar to :ref:`bounce_buffer_with_single_psram_frame_buffer`, but
.. note::
In a well-designed embedded application, situations where the DMA cannot deliver data as fast as the LCD consumes it should be avoided. However, such scenarios can theoretically occur. In the {IDF_TARGET_NAME} hardware, this results in the LCD outputting dummy bytes while the DMA waits for data. If the DMA were to run in a continuous stream, it could cause a desynchronization between the LCD address from which the DMA reads data and the address from which the LCD peripheral outputs data, leading to a **permanently** shifted image.
To prevent this, you can either enable the :ref:`CONFIG_LCD_RGB_RESTART_IN_VSYNC` option, allowing the driver to automatically restart the DMA during the VBlank interrupt, or call :cpp:func:`esp_lcd_rgb_panel_restart` to manually restart the DMA. Note that :cpp:func:`esp_lcd_rgb_panel_restart` does not restart the DMA immediately; instead, the DMA will be restarted at the next VSYNC event.
To prevent this, you can either enable the :menuitem:`CONFIG_LCD_RGB_RESTART_IN_VSYNC` option, allowing the driver to automatically restart the DMA during the VBlank interrupt, or call :cpp:func:`esp_lcd_rgb_panel_restart` to manually restart the DMA. Note that :cpp:func:`esp_lcd_rgb_panel_restart` does not restart the DMA immediately; instead, the DMA will be restarted at the next VSYNC event.
API Reference
-------------

12
docs/en/api-reference/peripherals/mcpwm.rst
View File

@@ -983,7 +983,7 @@ If you don't want to process the captured value in the capture event callback fu
Power Management
^^^^^^^^^^^^^^^^
When power management is enabled (i.e., :ref:`CONFIG_PM_ENABLE` is on), the system will adjust the PLL and APB frequency before going into Light-sleep, thus potentially changing the period of an MCPWM timers' counting step and leading to inaccurate time-keeping.
When power management is enabled (i.e., :menuitem:`CONFIG_PM_ENABLE` is on), the system will adjust the PLL and APB frequency before going into Light-sleep, thus potentially changing the period of an MCPWM timers' counting step and leading to inaccurate time-keeping.
However, the driver can prevent the system from going into Light-sleep by acquiring a power management lock of type :cpp:enumerator:`ESP_PM_NO_LIGHT_SLEEP`. Whenever the driver creates an MCPWM timer instance that has selected PLL as its clock source, the driver guarantees that the power management lock is acquired when enabling the timer by :cpp:func:`mcpwm_timer_enable`. On the contrary, the driver releases the lock when :cpp:func:`mcpwm_timer_disable` is called for that timer.
@@ -1014,7 +1014,7 @@ IRAM Safe
By default, the MCPWM interrupt will be deferred when the Cache is disabled for reasons like writing/erasing Flash. Thus the event callback functions will not get executed in time, which is not expected in a real-time application.
There is a Kconfig option :ref:`CONFIG_MCPWM_ISR_CACHE_SAFE` that:
There is a Kconfig option :menuitem:`CONFIG_MCPWM_ISR_CACHE_SAFE` that:
* enables the interrupt to be serviced even when the cache is disabled
* places all functions used by the ISR into IRAM [2]_
@@ -1022,7 +1022,7 @@ There is a Kconfig option :ref:`CONFIG_MCPWM_ISR_CACHE_SAFE` that:
This allows the interrupt to run while the cache is disabled but comes at the cost of increased IRAM consumption.
There is another Kconfig option :ref:`CONFIG_MCPWM_CTRL_FUNC_IN_IRAM` that can put commonly used IO control functions into IRAM as well. So, these functions can also be executable when the cache is disabled. The IO control function is as follows:
There is another Kconfig option :menuitem:`CONFIG_MCPWM_CTRL_FUNC_IN_IRAM` that can put commonly used IO control functions into IRAM as well. So, these functions can also be executable when the cache is disabled. The IO control function is as follows:
- :cpp:func:`mcpwm_comparator_set_compare_value`
- :cpp:func:`mcpwm_timer_set_period`
@@ -1048,9 +1048,9 @@ Other functions that are not related to :ref:`mcpwm-resource-allocation-and-init
Kconfig Options
^^^^^^^^^^^^^^^
- :ref:`CONFIG_MCPWM_ISR_CACHE_SAFE` controls whether the default ISR handler can work when the cache is disabled, see :ref:`mcpwm-iram-safe` for more information.
- :ref:`CONFIG_MCPWM_CTRL_FUNC_IN_IRAM` controls where to place the MCPWM control functions (IRAM or flash), see :ref:`mcpwm-iram-safe` for more information.
- :ref:`CONFIG_MCPWM_ENABLE_DEBUG_LOG` is used to enable the debug log output. Enabling this option will increase the firmware binary size.
- :menuitem:`CONFIG_MCPWM_ISR_CACHE_SAFE` controls whether the default ISR handler can work when the cache is disabled, see :ref:`mcpwm-iram-safe` for more information.
- :menuitem:`CONFIG_MCPWM_CTRL_FUNC_IN_IRAM` controls where to place the MCPWM control functions (IRAM or flash), see :ref:`mcpwm-iram-safe` for more information.
- :menuitem:`CONFIG_MCPWM_ENABLE_DEBUG_LOG` is used to enable the debug log output. Enabling this option will increase the firmware binary size.
Application Examples
--------------------

18
docs/en/api-reference/peripherals/parlio/parlio_rx.rst
View File

@@ -336,7 +336,7 @@ For applications requiring very low latency, the RX unit driver provides :cpp:fu
Power Management
^^^^^^^^^^^^^^^^
When power management :ref:`CONFIG_PM_ENABLE` is enabled, the system may adjust or disable the clock source before entering sleep, causing the RX unit's internal time base to not work as expected.
When power management :menuitem:`CONFIG_PM_ENABLE` is enabled, the system may adjust or disable the clock source before entering sleep, causing the RX unit's internal time base to not work as expected.
To prevent this, the RX unit driver internally creates a power management lock. The type of lock is set according to different clock sources. The driver will acquire the lock in :cpp:func:`parlio_rx_unit_enable` and release the lock in :cpp:func:`parlio_rx_unit_disable`. This means that regardless of the power management policy, the system will not enter sleep mode, and the clock source will not be disabled or adjusted between these two functions, ensuring that any RX transaction can work normally.
@@ -352,7 +352,7 @@ The driver uses critical sections to ensure atomic operations on registers. Key
Cache Safety
^^^^^^^^^^^^
When the file system performs Flash read/write operations, the system temporarily disables the Cache function to avoid errors when loading instructions and data from Flash. This will cause the RX unit's interrupt handler to be unresponsive during this period, preventing user callback functions from being executed in time. If you want the interrupt handler to run normally while the Cache is disabled, you can enable the :ref:`CONFIG_PARLIO_RX_ISR_CACHE_SAFE` option.
When the file system performs Flash read/write operations, the system temporarily disables the Cache function to avoid errors when loading instructions and data from Flash. This will cause the RX unit's interrupt handler to be unresponsive during this period, preventing user callback functions from being executed in time. If you want the interrupt handler to run normally while the Cache is disabled, you can enable the :menuitem:`CONFIG_PARLIO_RX_ISR_CACHE_SAFE` option.
.. note::
@@ -362,16 +362,16 @@ When the file system performs Flash read/write operations, the system temporaril
.. note::
When the following options are enabled, the Cache will not be disabled automatically during Flash read/write operations. You don't have to enable the :ref:`CONFIG_PARLIO_RX_ISR_CACHE_SAFE`.
When the following options are enabled, the Cache will not be disabled automatically during Flash read/write operations. You don't have to enable the :menuitem:`CONFIG_PARLIO_RX_ISR_CACHE_SAFE`.
.. list::
:SOC_SPI_MEM_SUPPORT_AUTO_SUSPEND: - :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND`
:SOC_SPIRAM_XIP_SUPPORTED: - :ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM`
:SOC_SPI_MEM_SUPPORT_AUTO_SUSPEND: - :menuitem:`CONFIG_SPI_FLASH_AUTO_SUSPEND`
:SOC_SPIRAM_XIP_SUPPORTED: - :menuitem:`CONFIG_SPIRAM_XIP_FROM_PSRAM`
Performance
^^^^^^^^^^^
To improve the real-time response capability of interrupt handling, the RX unit driver provides the :ref:`CONFIG_PARLIO_RX_ISR_HANDLER_IN_IRAM` option. Enabling this option will place the interrupt handler in internal RAM, reducing the latency caused by cache misses when loading instructions from Flash.
To improve the real-time response capability of interrupt handling, the RX unit driver provides the :menuitem:`CONFIG_PARLIO_RX_ISR_HANDLER_IN_IRAM` option. Enabling this option will place the interrupt handler in internal RAM, reducing the latency caused by cache misses when loading instructions from Flash.
.. note::
@@ -382,7 +382,7 @@ And please also take care that, when the :cpp:member:`parlio_receive_config_t::f
Other Kconfig Options
^^^^^^^^^^^^^^^^^^^^^
- :ref:`CONFIG_PARLIO_ENABLE_DEBUG_LOG` option allows forcing the enablement of all debug logs of the RX unit driver, regardless of the global log level setting. Enabling this option can help developers obtain more detailed log information during debugging, making it easier to locate and solve problems. This option is shared with the TX unit driver.
- :menuitem:`CONFIG_PARLIO_ENABLE_DEBUG_LOG` option allows forcing the enablement of all debug logs of the RX unit driver, regardless of the global log level setting. Enabling this option can help developers obtain more detailed log information during debugging, making it easier to locate and solve problems. This option is shared with the TX unit driver.
Resource Consumption
^^^^^^^^^^^^^^^^^^^^
@@ -392,8 +392,8 @@ Use the :doc:`/api-guides/tools/idf-size` tool to view the code and data consump
- The compiler optimization level is set to ``-Os`` to ensure the minimum code size.
- The default log level is set to ``ESP_LOG_INFO`` to balance debugging information and performance.
- The following driver optimization options are disabled:
- :ref:`CONFIG_PARLIO_RX_ISR_HANDLER_IN_IRAM` - The interrupt handler is not placed in IRAM.
- :ref:`CONFIG_PARLIO_RX_ISR_CACHE_SAFE` - The Cache safety option is not enabled.
- :menuitem:`CONFIG_PARLIO_RX_ISR_HANDLER_IN_IRAM` - The interrupt handler is not placed in IRAM.
- :menuitem:`CONFIG_PARLIO_RX_ISR_CACHE_SAFE` - The Cache safety option is not enabled.
**Note that the following data is not precise and is for reference only. The data may vary on different chip models and different versions of IDF.**

18
docs/en/api-reference/peripherals/parlio/parlio_tx.rst
View File

@@ -332,7 +332,7 @@ The waveform of the external clock input is shown below:
Power Management
^^^^^^^^^^^^^^^^
When power management :ref:`CONFIG_PM_ENABLE` is enabled, the system may adjust or disable the clock source before entering sleep, causing the TX unit's internal time base to not work as expected.
When power management :menuitem:`CONFIG_PM_ENABLE` is enabled, the system may adjust or disable the clock source before entering sleep, causing the TX unit's internal time base to not work as expected.
To prevent this, the TX unit driver internally creates a power management lock. The type of lock is set according to different clock sources. The driver will acquire the lock in :cpp:func:`parlio_tx_unit_enable` and release the lock in :cpp:func:`parlio_tx_unit_disable`. This means that regardless of the power management policy, the system will not enter sleep mode, and the clock source will not be disabled or adjusted between these two functions, ensuring that any TX transaction can work normally.
@@ -348,7 +348,7 @@ The driver uses critical sections to ensure atomic operations on registers. Key
Cache Safety
^^^^^^^^^^^^
When the file system performs Flash read/write operations, the system temporarily disables the Cache function to avoid errors when loading instructions and data from Flash. This will cause the TX unit's interrupt handler to be unresponsive during this period, preventing user callback functions from being executed in time. If you want the interrupt handler to run normally while the Cache is disabled, you can enable the :ref:`CONFIG_PARLIO_TX_ISR_CACHE_SAFE` option.
When the file system performs Flash read/write operations, the system temporarily disables the Cache function to avoid errors when loading instructions and data from Flash. This will cause the TX unit's interrupt handler to be unresponsive during this period, preventing user callback functions from being executed in time. If you want the interrupt handler to run normally while the Cache is disabled, you can enable the :menuitem:`CONFIG_PARLIO_TX_ISR_CACHE_SAFE` option.
.. note::
@@ -358,16 +358,16 @@ When the file system performs Flash read/write operations, the system temporaril
.. note::
When the following options are enabled, the Cache will not be disabled automatically during Flash read/write operations. You don't have to enable the :ref:`CONFIG_PARLIO_TX_ISR_CACHE_SAFE`.
When the following options are enabled, the Cache will not be disabled automatically during Flash read/write operations. You don't have to enable the :menuitem:`CONFIG_PARLIO_TX_ISR_CACHE_SAFE`.
.. list::
:SOC_SPI_MEM_SUPPORT_AUTO_SUSPEND: - :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND`
:SOC_SPIRAM_XIP_SUPPORTED: - :ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM`
:SOC_SPI_MEM_SUPPORT_AUTO_SUSPEND: - :menuitem:`CONFIG_SPI_FLASH_AUTO_SUSPEND`
:SOC_SPIRAM_XIP_SUPPORTED: - :menuitem:`CONFIG_SPIRAM_XIP_FROM_PSRAM`
Performance
^^^^^^^^^^^
To improve the real-time response capability of interrupt handling, the TX unit driver provides the :ref:`CONFIG_PARLIO_TX_ISR_HANDLER_IN_IRAM` option. Enabling this option will place the interrupt handler in internal RAM, reducing the latency caused by cache misses when loading instructions from Flash.
To improve the real-time response capability of interrupt handling, the TX unit driver provides the :menuitem:`CONFIG_PARLIO_TX_ISR_HANDLER_IN_IRAM` option. Enabling this option will place the interrupt handler in internal RAM, reducing the latency caused by cache misses when loading instructions from Flash.
.. note::
@@ -376,7 +376,7 @@ To improve the real-time response capability of interrupt handling, the TX unit
Other Kconfig Options
^^^^^^^^^^^^^^^^^^^^^
- :ref:`CONFIG_PARLIO_ENABLE_DEBUG_LOG` option allows forcing the enablement of all debug logs of the TX unit driver, regardless of the global log level setting. Enabling this option can help developers obtain more detailed log information during debugging, making it easier to locate and solve problems. This option is shared with the RX unit driver.
- :menuitem:`CONFIG_PARLIO_ENABLE_DEBUG_LOG` option allows forcing the enablement of all debug logs of the TX unit driver, regardless of the global log level setting. Enabling this option can help developers obtain more detailed log information during debugging, making it easier to locate and solve problems. This option is shared with the RX unit driver.
Resource Consumption
^^^^^^^^^^^^^^^^^^^^
@@ -386,8 +386,8 @@ Use the :doc:`/api-guides/tools/idf-size` tool to view the code and data consump
- The compiler optimization level is set to ``-Os`` to ensure the minimum code size.
- The default log level is set to ``ESP_LOG_INFO`` to balance debugging information and performance.
- The following driver optimization options are disabled:
- :ref:`CONFIG_PARLIO_TX_ISR_HANDLER_IN_IRAM` - The interrupt handler is not placed in IRAM.
- :ref:`CONFIG_PARLIO_TX_ISR_CACHE_SAFE` - The Cache safety option is not enabled.
- :menuitem:`CONFIG_PARLIO_TX_ISR_HANDLER_IN_IRAM` - The interrupt handler is not placed in IRAM.
- :menuitem:`CONFIG_PARLIO_TX_ISR_CACHE_SAFE` - The Cache safety option is not enabled.
**Note that the following data is not precise and is for reference only. The data may vary on different chip models and different versions of IDF.**

12
docs/en/api-reference/peripherals/pcnt.rst
View File

@@ -346,7 +346,7 @@ The internal hardware counter will be cleared to zero automatically when it reac
Power Management
^^^^^^^^^^^^^^^^
When power management is enabled (i.e., :ref:`CONFIG_PM_ENABLE` is on), the system adjusts the APB frequency before entering light sleep, which can cause the PCNT glitch filter to misinterpret valid signals as noise.
When power management is enabled (i.e., :menuitem:`CONFIG_PM_ENABLE` is on), the system adjusts the APB frequency before entering light sleep, which can cause the PCNT glitch filter to misinterpret valid signals as noise.
To prevent this, the driver can acquire a power management lock of type :cpp:enumerator:`ESP_PM_APB_FREQ_MAX`, ensuring the APB frequency remains constant. This lock is acquired when the PCNT unit is enabled via :cpp:func:`pcnt_unit_enable` and released when the unit is disabled via :cpp:func:`pcnt_unit_disable`.
@@ -357,7 +357,7 @@ IRAM Safe
By default, the PCNT interrupt will be deferred when the Cache is disabled for reasons like writing/erasing Flash. Thus the alarm interrupt will not get executed in time, which is not expected in a real-time application.
There is a Kconfig option :ref:`CONFIG_PCNT_ISR_IRAM_SAFE` that:
There is a Kconfig option :menuitem:`CONFIG_PCNT_ISR_IRAM_SAFE` that:
1. Enables the interrupt being serviced even when cache is disabled
2. Places all functions that used by the ISR into IRAM [2]_
@@ -365,7 +365,7 @@ There is a Kconfig option :ref:`CONFIG_PCNT_ISR_IRAM_SAFE` that:
This allows the interrupt to run while the cache is disabled but comes at the cost of increased IRAM consumption.
There is another Kconfig option :ref:`CONFIG_PCNT_CTRL_FUNC_IN_IRAM` that can put commonly used IO control functions into IRAM as well. So that these functions can also be executable when the cache is disabled. These IO control functions are as follows:
There is another Kconfig option :menuitem:`CONFIG_PCNT_CTRL_FUNC_IN_IRAM` that can put commonly used IO control functions into IRAM as well. So that these functions can also be executable when the cache is disabled. These IO control functions are as follows:
- :cpp:func:`pcnt_unit_start`
- :cpp:func:`pcnt_unit_stop`
@@ -393,9 +393,9 @@ Other functions that take the :cpp:type:`pcnt_unit_handle_t` and :cpp:type:`pcnt
Kconfig Options
^^^^^^^^^^^^^^^
- :ref:`CONFIG_PCNT_CTRL_FUNC_IN_IRAM` controls where to place the PCNT control functions (IRAM or Flash), see :ref:`pcnt-iram-safe` for more information.
- :ref:`CONFIG_PCNT_ISR_IRAM_SAFE` controls whether the default ISR handler can work when cache is disabled, see :ref:`pcnt-iram-safe` for more information.
- :ref:`CONFIG_PCNT_ENABLE_DEBUG_LOG` is used to enabled the debug log output. Enabling this option increases the firmware binary size.
- :menuitem:`CONFIG_PCNT_CTRL_FUNC_IN_IRAM` controls where to place the PCNT control functions (IRAM or Flash), see :ref:`pcnt-iram-safe` for more information.
- :menuitem:`CONFIG_PCNT_ISR_IRAM_SAFE` controls whether the default ISR handler can work when cache is disabled, see :ref:`pcnt-iram-safe` for more information.
- :menuitem:`CONFIG_PCNT_ENABLE_DEBUG_LOG` is used to enabled the debug log output. Enabling this option increases the firmware binary size.
Application Examples
--------------------

14
docs/en/api-reference/peripherals/rmt.rst
View File

@@ -571,7 +571,7 @@ A full sample code can be found in :example:`peripherals/rmt/ir_nec_transceiver`
Power Management
^^^^^^^^^^^^^^^^
When power management is enabled, i.e., :ref:`CONFIG_PM_ENABLE` is on, the system may adjust or disable the clock source before going to sleep. As a result, the time base inside the RMT can't work as expected.
When power management is enabled, i.e., :menuitem:`CONFIG_PM_ENABLE` is on, the system may adjust or disable the clock source before going to sleep. As a result, the time base inside the RMT can't work as expected.
The driver can prevent the above issue by creating a power management lock. The lock type is set based on different clock sources. The driver will acquire the lock in :cpp:func:`rmt_enable`, and release it in :cpp:func:`rmt_disable`. That means, any RMT transactions in between these two functions are guaranteed to work correctly and stable.
@@ -586,7 +586,7 @@ Cache Safe
By default, the RMT interrupt is deferred when the Cache is disabled for reasons like writing or erasing the main Flash. Thus the transaction-done interrupt does not get handled in time, which is not acceptable in a real-time application. What is worse, when the RMT transaction relies on **ping-pong** interrupt to successively encode or copy RMT symbols, a delayed interrupt can lead to an unpredictable result.
There is a Kconfig option :ref:`CONFIG_RMT_TX_ISR_CACHE_SAFE` and :ref:`CONFIG_RMT_RX_ISR_CACHE_SAFE` that has the following features:
There is a Kconfig option :menuitem:`CONFIG_RMT_TX_ISR_CACHE_SAFE` and :menuitem:`CONFIG_RMT_RX_ISR_CACHE_SAFE` that has the following features:
1. Enable the interrupt being serviced even when the cache is disabled
2. Place all functions used by the ISR into IRAM [2]_
@@ -594,9 +594,9 @@ There is a Kconfig option :ref:`CONFIG_RMT_TX_ISR_CACHE_SAFE` and :ref:`CONFIG_R
This Kconfig option allows the interrupt handler to run while the cache is disabled but comes at the cost of increased IRAM consumption.
Please note, when :ref:`CONFIG_RMT_TX_ISR_CACHE_SAFE` is enabled, you must also place the encoder functions (mainly the :cpp:member:`rmt_encoder_t::encode` and :cpp:member:`rmt_encoder_t::reset`) into IRAM. You can use :c:macro:`RMT_ENCODER_FUNC_ATTR` to decorate your encoder functions.
Please note, when :menuitem:`CONFIG_RMT_TX_ISR_CACHE_SAFE` is enabled, you must also place the encoder functions (mainly the :cpp:member:`rmt_encoder_t::encode` and :cpp:member:`rmt_encoder_t::reset`) into IRAM. You can use :c:macro:`RMT_ENCODER_FUNC_ATTR` to decorate your encoder functions.
Another Kconfig option :ref:`CONFIG_RMT_RECV_FUNC_IN_IRAM` can place :cpp:func:`rmt_receive` into the IRAM as well. So that the receive function can be used even when the flash cache is disabled.
Another Kconfig option :menuitem:`CONFIG_RMT_RECV_FUNC_IN_IRAM` can place :cpp:func:`rmt_receive` into the IRAM as well. So that the receive function can be used even when the flash cache is disabled.
.. _rmt-thread-safety:
@@ -615,9 +615,9 @@ The following functions are allowed to use under ISR context as well.
Kconfig Options
^^^^^^^^^^^^^^^
- :ref:`CONFIG_RMT_TX_ISR_CACHE_SAFE` and :ref:`CONFIG_RMT_RX_ISR_CACHE_SAFE` control whether the default ISR handler can work when cache is disabled, see also :ref:`rmt-cache-safe` for more information.
- :ref:`CONFIG_RMT_ENABLE_DEBUG_LOG` is used to enable the debug log at the cost of increased firmware binary size.
- :ref:`CONFIG_RMT_RECV_FUNC_IN_IRAM` controls where to place the RMT receive function (IRAM or Flash), see :ref:`rmt-cache-safe` for more information.
- :menuitem:`CONFIG_RMT_TX_ISR_CACHE_SAFE` and :menuitem:`CONFIG_RMT_RX_ISR_CACHE_SAFE` control whether the default ISR handler can work when cache is disabled, see also :ref:`rmt-cache-safe` for more information.
- :menuitem:`CONFIG_RMT_ENABLE_DEBUG_LOG` is used to enable the debug log at the cost of increased firmware binary size.
- :menuitem:`CONFIG_RMT_RECV_FUNC_IN_IRAM` controls where to place the RMT receive function (IRAM or Flash), see :ref:`rmt-cache-safe` for more information.
Application Examples
--------------------

8
docs/en/api-reference/peripherals/sdm.rst
View File

@@ -84,7 +84,7 @@ For the output PDM signals, the pulse density decides the output analog voltage
Power Management
^^^^^^^^^^^^^^^^
When power management is enabled (i.e., :ref:`CONFIG_PM_ENABLE` is on), the system will adjust the APB frequency before going into Light-sleep, thus potentially changing the sample rate of the sigma-delta modulator.
When power management is enabled (i.e., :menuitem:`CONFIG_PM_ENABLE` is on), the system will adjust the APB frequency before going into Light-sleep, thus potentially changing the sample rate of the sigma-delta modulator.
However, the driver can prevent the system from changing APB frequency by acquiring a power management lock of type :cpp:enumerator:`ESP_PM_APB_FREQ_MAX`. Whenever the driver creates an SDM channel instance that has selected :cpp:enumerator:`SDM_CLK_SRC_APB` as its clock source, the driver guarantees that the power management lock is acquired when enabling the channel by :cpp:func:`sdm_channel_enable`. Likewise, the driver releases the lock when :cpp:func:`sdm_channel_disable` is called for that channel.
@@ -93,7 +93,7 @@ However, the driver can prevent the system from changing APB frequency by acquir
IRAM Safe
^^^^^^^^^
There is a Kconfig option :ref:`CONFIG_SDM_CTRL_FUNC_IN_IRAM` that can put commonly-used IO control functions into IRAM as well. So that these functions can also be executable when the cache is disabled. These IO control functions are listed as follows:
There is a Kconfig option :menuitem:`CONFIG_SDM_CTRL_FUNC_IN_IRAM` that can put commonly-used IO control functions into IRAM as well. So that these functions can also be executable when the cache is disabled. These IO control functions are listed as follows:
- :cpp:func:`sdm_channel_set_pulse_density`
@@ -115,8 +115,8 @@ The following functions can also be used in an interrupt context:
Kconfig Options
^^^^^^^^^^^^^^^
- :ref:`CONFIG_SDM_CTRL_FUNC_IN_IRAM` controls where to place the SDM channel control functions (IRAM or Flash), see :ref:`sdm-iram-safe` for more information.
- :ref:`CONFIG_SDM_ENABLE_DEBUG_LOG` is used to enable the debug log output. Enabling this option increases the firmware binary size.
- :menuitem:`CONFIG_SDM_CTRL_FUNC_IN_IRAM` controls where to place the SDM channel control functions (IRAM or Flash), see :ref:`sdm-iram-safe` for more information.
- :menuitem:`CONFIG_SDM_ENABLE_DEBUG_LOG` is used to enable the debug log output. Enabling this option increases the firmware binary size.
.. _convert_to_analog_signal:

12
docs/en/api-reference/peripherals/spi_flash/auto_suspend.inc
View File

@@ -19,7 +19,7 @@ Flash Auto Suspend Feature
4. When the flash is successfully resumed, another suspend can be sent immediately at this state.
When :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND` is enabled, the caches will be kept enabled. They would be disabled if :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND` is disabled. The hardware handles the arbitration between SPI0 and SPI1. If the SPI1 operation is short, such as a reading operation, the CPU and the cache will wait until the SPI1 operation is completed. However, during processes like erasing, page programming, or status register writing (e.g., ``SE``, ``PP``, and ``WRSR``), an auto suspend will happen, interrupting the ongoing flash operation. This allows the CPU to access data from the cache and flash within limited time.
When :menuitem:`CONFIG_SPI_FLASH_AUTO_SUSPEND` is enabled, the caches will be kept enabled. They would be disabled if :menuitem:`CONFIG_SPI_FLASH_AUTO_SUSPEND` is disabled. The hardware handles the arbitration between SPI0 and SPI1. If the SPI1 operation is short, such as a reading operation, the CPU and the cache will wait until the SPI1 operation is completed. However, during processes like erasing, page programming, or status register writing (e.g., ``SE``, ``PP``, and ``WRSR``), an auto suspend will happen, interrupting the ongoing flash operation. This allows the CPU to access data from the cache and flash within limited time.
This approach allows certain code/variables to be stored in flash/PSRAM instead of IRAM/DRAM, while still being executable during flash erasing. This reduces the usage of IRAM/DRAM.
@@ -47,7 +47,7 @@ Regarding the flash suspend feature usage and corresponding response time delay,
2. ISR interval: ISR cannot be triggered very often. The most important time is the **ISR interval minus ISR time** (from point b to point c in the diagram). During this time, SPI1 will send resume command to restart the operation. However, it needs a time ``tsus`` for preparation, and the typical value of ``tsus`` is about **40 us**. If SPI1 cannot resume the operation but another suspend command comes, it will cause CPU starve and ``TWDT`` may be triggered.
The ``tsus`` time mentioned in point 2 can be found by looking through the flash datasheets, usually in the AC CHARACTERISTICS section. Users needs to make sure that the ``tsus`` value obtained from the datasheets is not greater than the :ref:`CONFIG_SPI_FLASH_SUSPEND_TSUS_VAL_US` value in Kconfig.
The ``tsus`` time mentioned in point 2 can be found by looking through the flash datasheets, usually in the AC CHARACTERISTICS section. Users needs to make sure that the ``tsus`` value obtained from the datasheets is not greater than the :menuitem:`CONFIG_SPI_FLASH_SUSPEND_TSUS_VAL_US` value in Kconfig.
Furthermore, the flash suspend might be delayed. If both the CPU and the cache access the flash via SPI0 frequently and SPI1 sends the suspend command frequently as well, the efficiency of MSPI data transfer will be influenced. So, we have a **lock** inside to prevent this. When SPI1 sends the suspend command, SPI0 will take over memory SPI bus and take the lock. After SPI0 finishes sending data, it will retain control of the memory SPI bus until the lock delay period time finishes. During this lock delay period, if there is any other SPI0 transaction, then the SPI0 transaction will be proceeded and a new lock delay period will start. Otherwise, SPI0 will release the memory bus and start SPI0/1 arbitration.
@@ -60,7 +60,7 @@ In the default configuration, flash suspend is issued automatically by hardware,
Normally, after issuing the suspend command, the hardware waits for a fixed period of time defined by ``tsus`` before handing the memory bus back to SPI0/CPU. Because this delay must be configured according to the worst case given in the datasheet, it is conservative in most situations.
By enabling :ref:`CONFIG_SPI_FLASH_AUTO_CHECK_SUSPEND_STATUS`, the hardware will instead poll the ``WIP`` bit in the flash status register to determine whether the suspend command has actually taken effect, rather than waiting for the fixed time given by :ref:`CONFIG_SPI_FLASH_SUSPEND_TSUS_VAL_US`. Since the actual suspend setup time is usually much shorter than the maximum value listed in the datasheet, this approach can significantly reduce the overhead during suspend and improve overall performance.
By enabling :menuitem:`CONFIG_SPI_FLASH_AUTO_CHECK_SUSPEND_STATUS`, the hardware will instead poll the ``WIP`` bit in the flash status register to determine whether the suspend command has actually taken effect, rather than waiting for the fixed time given by :menuitem:`CONFIG_SPI_FLASH_SUSPEND_TSUS_VAL_US`. Since the actual suspend setup time is usually much shorter than the maximum value listed in the datasheet, this approach can significantly reduce the overhead during suspend and improve overall performance.
.. important::
@@ -70,10 +70,10 @@ By enabling :ref:`CONFIG_SPI_FLASH_AUTO_CHECK_SUSPEND_STATUS`, the hardware will
Normally, after the flash is suspended, the hardware will automatically arrange an appropriate moment to send the resume command, allowing the flash to continue its original erase/write operation. This implementation is transparent to software, but it has a side effect: while a high-priority task or interrupt is still running, the hardware may again initiate a suspend/resume sequence, which interrupts those tasks and affects the continuity and timing of their execution.
By enabling :ref:`CONFIG_SPI_FLASH_SOFTWARE_RESUME`, the hardware auto-resume feature is disabled, and the flash resume operation is instead issued by software at an appropriate point. With this option enabled, once the flash is suspended it will stay suspended until software explicitly resumes it. In the SPI1 wait-idle flow, software actively checks the flash's suspend state, and if it finds the flash in a suspended state, it calls the driver's resume interface to let the flash continue the original operation. This means that the resume command is only issued after the high-priority task or interrupt has truly finished and software has returned to the SPI1 operation context, avoiding repeated bus preemption caused by suspend-resume on high-priority paths.
By enabling :menuitem:`CONFIG_SPI_FLASH_SOFTWARE_RESUME`, the hardware auto-resume feature is disabled, and the flash resume operation is instead issued by software at an appropriate point. With this option enabled, once the flash is suspended it will stay suspended until software explicitly resumes it. In the SPI1 wait-idle flow, software actively checks the flash's suspend state, and if it finds the flash in a suspended state, it calls the driver's resume interface to let the flash continue the original operation. This means that the resume command is only issued after the high-priority task or interrupt has truly finished and software has returned to the SPI1 operation context, avoiding repeated bus preemption caused by suspend-resume on high-priority paths.
Because this mechanism relies on the software layer to perform resume at well-defined execution points, and the current implementation does not provide corresponding protection for multi-core scenarios, this option has the following limitations:
- It is only supported on single-core scenarios. :ref:`CONFIG_FREERTOS_UNICORE` must be enabled.
- It is an experimental feature and is only visible after :ref:`CONFIG_IDF_EXPERIMENTAL_FEATURES` is enabled.
- It is only supported on single-core scenarios. :menuitem:`CONFIG_FREERTOS_UNICORE` must be enabled.
- It is an experimental feature and is only visible after :menuitem:`CONFIG_IDF_EXPERIMENTAL_FEATURES` is enabled.
- This feature improves the continuity of interrupt response and the overall application performance. However, it also increases the time needed to complete a single flash operation.

22
docs/en/api-reference/peripherals/spi_flash/index.rst
View File

@@ -118,7 +118,7 @@ SPI Flash Size
The SPI flash size is configured by writing a field in the ESP-IDF second stage bootloader image header, flashed at offset 0x1000.
By default, the SPI flash size is detected by ``esptool`` when this bootloader is written to flash, and the header is updated with the correct size. Alternatively, it is possible to generate a fixed flash size by setting :ref:`CONFIG_ESPTOOLPY_FLASHSIZE` in the project configuration.
By default, the SPI flash size is detected by ``esptool`` when this bootloader is written to flash, and the header is updated with the correct size. Alternatively, it is possible to generate a fixed flash size by setting :menuitem:`CONFIG_ESPTOOLPY_FLASHSIZE` in the project configuration.
If it is necessary to override the configured flash size at runtime, it is possible to set the ``chip_size`` member of the ``g_rom_flashchip`` structure. This size is used by ``esp_flash_*`` functions (in both software & ROM) to check the bounds.
@@ -254,16 +254,16 @@ The delay is used by some long operations which requires the master to wait or p
The top API wraps these the chip driver and OS functions into an entire component, and also provides some argument checking.
OS functions can also help to avoid a watchdog timeout when erasing large flash areas. During this time, the CPU is occupied with the flash erasing task. This stops other tasks from being executed. Among these tasks is the idle task to feed the watchdog timer (WDT). If the configuration option :ref:`CONFIG_ESP_TASK_WDT_PANIC` is selected and the flash operation time is longer than the watchdog timeout period, the system will reboot.
OS functions can also help to avoid a watchdog timeout when erasing large flash areas. During this time, the CPU is occupied with the flash erasing task. This stops other tasks from being executed. Among these tasks is the idle task to feed the watchdog timer (WDT). If the configuration option :menuitem:`CONFIG_ESP_TASK_WDT_PANIC` is selected and the flash operation time is longer than the watchdog timeout period, the system will reboot.
It is pretty hard to totally eliminate this risk, because the erasing time varies with different flash chips, making it hard to be compatible in flash drivers. Therefore, users need to pay attention to it. Please use the following guidelines:
1. It is recommended to enable the :ref:`CONFIG_SPI_FLASH_YIELD_DURING_ERASE` option to allow the scheduler to re-schedule during erasing flash memory. Besides, following parameters can also be used.
1. It is recommended to enable the :menuitem:`CONFIG_SPI_FLASH_YIELD_DURING_ERASE` option to allow the scheduler to re-schedule during erasing flash memory. Besides, following parameters can also be used.
- Increase :ref:`CONFIG_SPI_FLASH_ERASE_YIELD_TICKS` or decrease :ref:`CONFIG_SPI_FLASH_ERASE_YIELD_DURATION_MS` in menuconfig.
- You can also increase :ref:`CONFIG_ESP_TASK_WDT_TIMEOUT_S` in menuconfig for a larger watchdog timeout period. However, with larger watchdog timeout period, previously detected timeouts may no longer be detected.
- Increase :menuitem:`CONFIG_SPI_FLASH_ERASE_YIELD_TICKS` or decrease :menuitem:`CONFIG_SPI_FLASH_ERASE_YIELD_DURATION_MS` in menuconfig.
- You can also increase :menuitem:`CONFIG_ESP_TASK_WDT_TIMEOUT_S` in menuconfig for a larger watchdog timeout period. However, with larger watchdog timeout period, previously detected timeouts may no longer be detected.
2. Please be aware of the consequences of enabling the :ref:`CONFIG_ESP_TASK_WDT_PANIC` option when doing long-running SPI flash operations which triggers the panic handler when it times out. However, this option can also help dealing with unexpected exceptions in your application. Please decide whether this is needed to be enabled according to actual condition.
2. Please be aware of the consequences of enabling the :menuitem:`CONFIG_ESP_TASK_WDT_PANIC` option when doing long-running SPI flash operations which triggers the panic handler when it times out. However, this option can also help dealing with unexpected exceptions in your application. Please decide whether this is needed to be enabled according to actual condition.
3. During your development, please carefully review the actual flash operation according to the specific requirements and time limits on erasing flash memory of your projects. Always allow reasonable redundancy based on your specific product requirements when configuring the flash erasing timeout threshold, thus improving the reliability of your product.
@@ -285,7 +285,7 @@ Once the flash operation is complete, the function on CPU A sets another flag, `
Additionally, all API functions are protected with a mutex (``s_flash_op_mutex``).
In a single core environment (:ref:`CONFIG_FREERTOS_UNICORE` enabled), you need to disable both caches, so that no inter-CPU communication can take place.
In a single core environment (:menuitem:`CONFIG_FREERTOS_UNICORE` enabled), you need to disable both caches, so that no inter-CPU communication can take place.
.. only:: SOC_SPI_MEM_SUPPORT_AUTO_SUSPEND
@@ -294,13 +294,13 @@ In a single core environment (:ref:`CONFIG_FREERTOS_UNICORE` enabled), you need
Internal Memory Saving For Flash Driver
---------------------------------------
The ESP-IDF provides options to optimize the usage of IRAM by selectively placing certain functions into flash memory via turning off :ref:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM`. It allows SPI flash operation functions to be executed from flash memory instead of IRAM. Thus it saves IRAM memory for other significant time-critical functions or tasks.
The ESP-IDF provides options to optimize the usage of IRAM by selectively placing certain functions into flash memory via turning off :menuitem:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM`. It allows SPI flash operation functions to be executed from flash memory instead of IRAM. Thus it saves IRAM memory for other significant time-critical functions or tasks.
However, this has some implications for flash itself. Functions placed into flash memory may have slightly increased execution times compared to those placed in IRAM. Applications with strict timing requirements or those heavily reliant on SPI flash operations may need to evaluate the trade-offs before enabling this option.
.. note::
:ref:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM` should not be turned off when :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND` is not enabled, otherwise it will cause critical crash. As for flash suspend feature, please refer to :ref:`auto-suspend` for more information.
:menuitem:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM` should not be turned off when :menuitem:`CONFIG_SPI_FLASH_AUTO_SUSPEND` is not enabled, otherwise it will cause critical crash. As for flash suspend feature, please refer to :ref:`auto-suspend` for more information.
Resource Consumption
^^^^^^^^^^^^^^^^^^^^
@@ -309,7 +309,7 @@ In a single core environment (:ref:`CONFIG_FREERTOS_UNICORE` enabled), you need
**Note that the following data are not exact values and are for reference only; they may differ on different chip models.**
Resource consumption when :ref:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM` is enabled:
Resource consumption when :menuitem:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM` is enabled:
.. list-table:: Resource Consumption
:widths: 20 10 10 10 10 10 10 10 10 10
@@ -346,7 +346,7 @@ In a single core environment (:ref:`CONFIG_FREERTOS_UNICORE` enabled), you need
- 247
- 247
Resource consumption when :ref:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM` is disabled:
Resource consumption when :menuitem:`CONFIG_SPI_FLASH_PLACE_FUNCTIONS_IN_IRAM` is disabled:
.. list-table:: Resource Consumption
:widths: 20 10 10 10 10 10 10 10 10 10

2
docs/en/api-reference/peripherals/spi_flash/spi_flash_concurrency.rst
View File

@@ -19,7 +19,7 @@ There are three kinds of activities that can happen on SPI0/1 bus:
.. list::
- Calling non_encrypted SPI flash read API (:cpp:func:`esp_flash_read`, etc.)
:esp32: - Or other drivers on SPI1 bus for user defined SPI operations (enable experimental feature :ref:`CONFIG_SPI_FLASH_SHARE_SPI1_BUS`)
:esp32: - Or other drivers on SPI1 bus for user defined SPI operations (enable experimental feature :menuitem:`CONFIG_SPI_FLASH_SHARE_SPI1_BUS`)
- Cache read (via SPI0). Following API and operations can trigger cache read:

22
docs/en/api-reference/peripherals/spi_flash/spi_flash_idf_vs_rom.rst
View File

@@ -6,7 +6,7 @@ SPI Flash API ESP-IDF Version vs Chip-ROM Version
.. toctree::
:maxdepth: 1
There is a set of SPI flash drivers in Chip-ROM which you can use by enabling :ref:`CONFIG_SPI_FLASH_ROM_IMPL`. Most of the ESP-IDF SPI flash driver code are in internal RAM, therefore enabling this option frees some internal RAM usage. Note that if you enable this option, this means some SPI flash driver features and bugfixes that are done in ESP-IDF might not be included in the Chip-ROM version.
There is a set of SPI flash drivers in Chip-ROM which you can use by enabling :menuitem:`CONFIG_SPI_FLASH_ROM_IMPL`. Most of the ESP-IDF SPI flash driver code are in internal RAM, therefore enabling this option frees some internal RAM usage. Note that if you enable this option, this means some SPI flash driver features and bugfixes that are done in ESP-IDF might not be included in the Chip-ROM version.
Feature Supported by ESP-IDF but Not in Chip-ROM
@@ -17,16 +17,16 @@ Feature Supported by ESP-IDF but Not in Chip-ROM
- Octal flash chip support. See :ref:`oct-flash-doc` for details.
- 32-bit-address support on flash chips. Note that this feature is an optional feature, please do read :ref:`32-bit-flash-doc` for details.
- TH flash chip support.
- Kconfig option :ref:`CONFIG_SPI_FLASH_CHECK_ERASE_TIMEOUT_DISABLED`.
- :ref:`CONFIG_SPI_FLASH_VERIFY_WRITE`, enabling this option helps you detect bad writing.
- :ref:`CONFIG_SPI_FLASH_LOG_FAILED_WRITE`, enabling this option prints the bad writing.
- :ref:`CONFIG_SPI_FLASH_WARN_SETTING_ZERO_TO_ONE`, enabling this option checks if you are writing zero to one.
- :ref:`CONFIG_SPI_FLASH_DANGEROUS_WRITE`, enabling this option checks for flash programming to certain protected regions like bootloader, partition table or application itself.
- :ref:`CONFIG_SPI_FLASH_ENABLE_COUNTERS`, enabling this option to collect performance data for ESP-IDF SPI flash driver APIs.
- :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND`, enabling this option to automatically suspend or resume a long flash operation when short flash operation happens. Note that this feature is an optional feature, please do read :ref:`auto-suspend-intro` for more limitations.
- :ref:`CONFIG_ESP_SLEEP_SET_FLASH_DPD`, enabling this option allows the flash to enter deep power-down (DPD) mode during sleep for lower power consumption. Note that this feature is an optional feature, please do read :ref:`deep-power-down-mode` for more limitations.
:ESP_ROM_HAS_SPI_FLASH_MMAP and SOC_SPIRAM_XIP_SUPPORTED and not esp32s3: - :ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM`, enabling this option allows you to use external PSRAM as instruction cache and read-only data cache. Some functions in the ROM don't support this usage, and an ESP-IDF version of these functions is provided.
:esp32s3: - :ref:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` and :ref:`CONFIG_SPIRAM_RODATA`, enabling these options allows you to use external PSRAM as instruction cache and read-only data cache. Some functions in the ROM don't support this usage, and an ESP-IDF version of these functions is provided.
- Kconfig option :menuitem:`CONFIG_SPI_FLASH_CHECK_ERASE_TIMEOUT_DISABLED`.
- :menuitem:`CONFIG_SPI_FLASH_VERIFY_WRITE`, enabling this option helps you detect bad writing.
- :menuitem:`CONFIG_SPI_FLASH_LOG_FAILED_WRITE`, enabling this option prints the bad writing.
- :menuitem:`CONFIG_SPI_FLASH_WARN_SETTING_ZERO_TO_ONE`, enabling this option checks if you are writing zero to one.
- :menuitem:`CONFIG_SPI_FLASH_DANGEROUS_WRITE`, enabling this option checks for flash programming to certain protected regions like bootloader, partition table or application itself.
- :menuitem:`CONFIG_SPI_FLASH_ENABLE_COUNTERS`, enabling this option to collect performance data for ESP-IDF SPI flash driver APIs.
- :menuitem:`CONFIG_SPI_FLASH_AUTO_SUSPEND`, enabling this option to automatically suspend or resume a long flash operation when short flash operation happens. Note that this feature is an optional feature, please do read :ref:`auto-suspend-intro` for more limitations.
- :menuitem:`CONFIG_ESP_SLEEP_SET_FLASH_DPD`, enabling this option allows the flash to enter deep power-down (DPD) mode during sleep for lower power consumption. Note that this feature is an optional feature, please do read :ref:`deep-power-down-mode` for more limitations.
:ESP_ROM_HAS_SPI_FLASH_MMAP and SOC_SPIRAM_XIP_SUPPORTED and not esp32s3: - :menuitem:`CONFIG_SPIRAM_XIP_FROM_PSRAM`, enabling this option allows you to use external PSRAM as instruction cache and read-only data cache. Some functions in the ROM don't support this usage, and an ESP-IDF version of these functions is provided.
:esp32s3: - :menuitem:`CONFIG_SPIRAM_FETCH_INSTRUCTIONS` and :menuitem:`CONFIG_SPIRAM_RODATA`, enabling these options allows you to use external PSRAM as instruction cache and read-only data cache. Some functions in the ROM don't support this usage, and an ESP-IDF version of these functions is provided.
Bugfixes Introduced in ESP-IDF but Not in Chip-ROM
--------------------------------------------------

14
docs/en/api-reference/peripherals/spi_flash/spi_flash_optional_feature.rst
View File

@@ -94,7 +94,7 @@ The support for ESP32-S2, ESP32-C3, ESP32-C6, ESP32-H2, and ESP32-P4 may be adde
To enable High Performance mode:
1. De-select :ref:`CONFIG_ESPTOOLPY_OCT_FLASH` and :ref:`CONFIG_ESPTOOLPY_FLASH_MODE_AUTO_DETECT`. HPM is not used for Octal flash, enabling related options may bypass HPM functions.
1. De-select :menuitem:`CONFIG_ESPTOOLPY_OCT_FLASH` and :menuitem:`CONFIG_ESPTOOLPY_FLASH_MODE_AUTO_DETECT`. HPM is not used for Octal flash, enabling related options may bypass HPM functions.
2. Enable ``CONFIG_SPI_FLASH_HPM_ENA`` option.
@@ -108,13 +108,13 @@ The support for ESP32-S2, ESP32-C3, ESP32-C6, ESP32-H2, and ESP32-P4 may be adde
Check whether the bootloader supports `DC Aware` in the following way:
- If you are starting a new project, it's suggested to enable `DC Aware` by selecting :ref:`CONFIG_BOOTLOADER_FLASH_DC_AWARE` option in the bootloader menu. Please note that, you won't be able to modify this option via OTA, because the support is in the bootloader.
- If you are starting a new project, it's suggested to enable `DC Aware` by selecting :menuitem:`CONFIG_BOOTLOADER_FLASH_DC_AWARE` option in the bootloader menu. Please note that, you won't be able to modify this option via OTA, because the support is in the bootloader.
- If you are working on an existing project and want to update `HPM-DC` config option in the app via OTA, check the sdkconfig file used to build your bootloader (upgrading ESP-IDF version may make this file different from the one used by bootloader to build):
- For latest version (v4.4.7+, v5.0.7+, v5.1.4+, v5.2 and above), if :ref:`CONFIG_BOOTLOADER_FLASH_DC_AWARE` is selected, the bootloader supports `DC Aware`.
- For latest version (v4.4.7+, v5.0.7+, v5.1.4+, v5.2 and above), if :menuitem:`CONFIG_BOOTLOADER_FLASH_DC_AWARE` is selected, the bootloader supports `DC Aware`.
- For other versions (v4.4.4-v4.4.6, v5.0-v5.0.6, and v5.1-v5.1.3), if ``CONFIG_ESPTOOLPY_FLASHFREQ_120M`` is selected, the bootloader supports `DC Aware`. In this case, enable :ref:`CONFIG_BOOTLOADER_FLASH_DC_AWARE` to confirm this (though it will not affect bootloader in devices in the field).
- For other versions (v4.4.4-v4.4.6, v5.0-v5.0.6, and v5.1-v5.1.3), if ``CONFIG_ESPTOOLPY_FLASHFREQ_120M`` is selected, the bootloader supports `DC Aware`. In this case, enable :menuitem:`CONFIG_BOOTLOADER_FLASH_DC_AWARE` to confirm this (though it will not affect bootloader in devices in the field).
- For versions below v4.4.4, the bootloader doesn't support `DC Aware`.
@@ -185,12 +185,12 @@ Restrictions
For Quad flash chips, by default, the part of flash above 16 MB can be used for data storage, for example using a file system.
*Experimental Feature*: To enable full support for Quad flash addresses above 16MB (for both code execution and data access), enable this experimental feature by setting below options to ``y``:
- :ref:`CONFIG_IDF_EXPERIMENTAL_FEATURES`
- :ref:`CONFIG_BOOTLOADER_CACHE_32BIT_ADDR_QUAD_FLASH`
- :menuitem:`CONFIG_IDF_EXPERIMENTAL_FEATURES`
- :menuitem:`CONFIG_BOOTLOADER_CACHE_32BIT_ADDR_QUAD_FLASH`
Please note that, this option is experimental, which means that it can not be used on all Quad flash chips stably. For more information, please contact `Espressif's business team <https://www.espressif.com/en/contact-us/sales-questions>`_.
For Octal flash chips, this feature is enabled by default if :ref:`CONFIG_ESPTOOLPY_OCT_FLASH` is enabled.
For Octal flash chips, this feature is enabled by default if :menuitem:`CONFIG_ESPTOOLPY_OCT_FLASH` is enabled.
.. _oct-flash-doc:

4
docs/en/api-reference/peripherals/spi_flash/spi_flash_override_driver.rst
View File

@@ -159,7 +159,7 @@ The flash driver in the application is used to read, write, erase, and save data
.. important::
Flash work for suspend (i.e., enabling :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND`) should be tested carefully and systematically due to different flash hardware design. If you want to use the suspend feature for mass production, please contact `Espressif's business team <https://www.espressif.com/en/contact-us/sales-questions>`_.
Flash work for suspend (i.e., enabling :menuitem:`CONFIG_SPI_FLASH_AUTO_SUSPEND`) should be tested carefully and systematically due to different flash hardware design. If you want to use the suspend feature for mass production, please contact `Espressif's business team <https://www.espressif.com/en/contact-us/sales-questions>`_.
.. code-block:: c
@@ -232,7 +232,7 @@ The flash driver in the application is used to read, write, erase, and save data
- Step 5: The ``linker.lf`` is used to put every chip driver that you are going to use whilst cache is disabled into internal RAM. See :doc:`/api-guides/linker-script-generation` for more details. Make sure this file covers all the source files that you add.
- Step 6: Add a new component in your project, e.g., ``custom_chip_driver``. List your chip object under ``default_registered_chips`` in ``custom_chip_driver/chip_drivers.c``. Then enable the :ref:`CONFIG_SPI_FLASH_OVERRIDE_CHIP_DRIVER_LIST` configuration option. This prevents compilation and linking of the default chip driver list (``default_registered_chips``) provided by ESP-IDF. Instead, the linker searches for the structure of the same name (``default_registered_chips``) that must be provided by you. You can refer to :example_file:`storage/custom_flash_driver/components/custom_chip_driver/chip_drivers.c`.
- Step 6: Add a new component in your project, e.g., ``custom_chip_driver``. List your chip object under ``default_registered_chips`` in ``custom_chip_driver/chip_drivers.c``. Then enable the :menuitem:`CONFIG_SPI_FLASH_OVERRIDE_CHIP_DRIVER_LIST` configuration option. This prevents compilation and linking of the default chip driver list (``default_registered_chips``) provided by ESP-IDF. Instead, the linker searches for the structure of the same name (``default_registered_chips``) that must be provided by you. You can refer to :example_file:`storage/custom_flash_driver/components/custom_chip_driver/chip_drivers.c`.
- Step 7: Build your project, and you will see the new flash driver in use.

2
docs/en/api-reference/peripherals/spi_flash/xip_from_psram.inc
View File

@@ -3,7 +3,7 @@
Executing Code from PSRAM
-------------------------
Select :ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM` config to enable this mode. In this mode, code is executed from PSRAM, and the cache will not be disabled during write APIs in most cases.
Select :menuitem:`CONFIG_SPIRAM_XIP_FROM_PSRAM` config to enable this mode. In this mode, code is executed from PSRAM, and the cache will not be disabled during write APIs in most cases.
In this mode, the flash ``.text`` sections (used for instructions) and the flash ``.rodata`` sections (used for read-only data) will be loaded into PSRAM at startup. The corresponding virtual addresses will be mapped to PSRAM. You do not need to ensure that code and data executed while the flash is being erased or programmed reside in IRAM.

8
docs/en/api-reference/peripherals/spi_master.rst
View File

@@ -580,7 +580,7 @@ The typical transaction duration for one byte of data is given below.
- Polling Transaction via DMA: {IDF_TARGET_MAX_TRANS_TIME_POLL_DMA} µs.
- Polling Transaction via CPU: {IDF_TARGET_MAX_TRANS_TIME_POLL_CPU} µs.
Note that these data are tested with :ref:`CONFIG_SPI_MASTER_ISR_IN_IRAM` enabled. SPI transaction related code are placed in the internal memory. If this option is turned off (for example, for internal memory optimization), the transaction duration may be affected.
Note that these data are tested with :menuitem:`CONFIG_SPI_MASTER_ISR_IN_IRAM` enabled. SPI transaction related code are placed in the internal memory. If this option is turned off (for example, for internal memory optimization), the transaction duration may be affected.
SPI Clock Frequency
^^^^^^^^^^^^^^^^^^^
@@ -636,11 +636,11 @@ The transfer speed calculation of other phases (Command, Address, Dummy) is simi
Cache Missing
^^^^^^^^^^^^^
The default config puts only the ISR into the IRAM. Other SPI-related functions, including the driver itself and the callback, might suffer from cache misses and need to wait until the code is read from flash. Select :ref:`CONFIG_SPI_MASTER_IN_IRAM` to put the whole SPI driver into IRAM and put the entire callback(s) and its callee functions into IRAM to prevent cache missing.
The default config puts only the ISR into the IRAM. Other SPI-related functions, including the driver itself and the callback, might suffer from cache misses and need to wait until the code is read from flash. Select :menuitem:`CONFIG_SPI_MASTER_IN_IRAM` to put the whole SPI driver into IRAM and put the entire callback(s) and its callee functions into IRAM to prevent cache missing.
.. note::
SPI driver implementation is based on FreeRTOS APIs, to use :ref:`CONFIG_SPI_MASTER_IN_IRAM`, you should enable :ref:`CONFIG_FREERTOS_IN_IRAM`.
SPI driver implementation is based on FreeRTOS APIs, to use :menuitem:`CONFIG_SPI_MASTER_IN_IRAM`, you should enable :menuitem:`CONFIG_FREERTOS_IN_IRAM`.
For an interrupt transaction, the overall cost is **20+8n/Fspi[MHz]** [µs] for n bytes transferred in one transaction. Hence, the transferring speed is: **n/(20+8n/Fspi)**. An example of transferring speed at 8 MHz clock speed is given in the following table.
@@ -681,7 +681,7 @@ For an interrupt transaction, the overall cost is **20+8n/Fspi[MHz]** [µs] for
When a transaction length is short, the cost of the transaction interval is high. If possible, try to squash several short transactions into one transaction to achieve a higher transfer speed.
Please note that the ISR is disabled during flash operation by default. To keep sending transactions during flash operations, enable :ref:`CONFIG_SPI_MASTER_ISR_IN_IRAM` and set :c:macro:`ESP_INTR_FLAG_IRAM` in the member :cpp:member:`spi_bus_config_t::intr_flags`. In this case, all the transactions queued before starting flash operations are handled by the ISR in parallel. Also note that the callback of each Device and their ``callee`` functions should be in IRAM, or your callback will crash due to cache missing. For more details, see :ref:`iram-safe-interrupt-handlers`.
Please note that the ISR is disabled during flash operation by default. To keep sending transactions during flash operations, enable :menuitem:`CONFIG_SPI_MASTER_ISR_IN_IRAM` and set :c:macro:`ESP_INTR_FLAG_IRAM` in the member :cpp:member:`spi_bus_config_t::intr_flags`. In this case, all the transactions queued before starting flash operations are handled by the ISR in parallel. Also note that the callback of each Device and their ``callee`` functions should be in IRAM, or your callback will crash due to cache missing. For more details, see :ref:`iram-safe-interrupt-handlers`.
.. only:: esp32h2

2
docs/en/api-reference/peripherals/temp_sensor.rst
View File

@@ -142,7 +142,7 @@ As the temperature sensor does not use the APB clock, it will keep working no ma
By default, the temperature sensor interrupt will be deferred when the cache is disabled for reasons like writing/erasing flash. Thus the event callback functions will not get executed in time, which is not expected in a real-time application.
There is a Kconfig option :ref:`CONFIG_TEMP_SENSOR_ISR_IRAM_SAFE` that will:
There is a Kconfig option :menuitem:`CONFIG_TEMP_SENSOR_ISR_IRAM_SAFE` that will:
1. Enable the interrupt that is being serviced even when the cache is disabled.
2. Place all functions that are used by the ISR into IRAM.

18
docs/en/api-reference/peripherals/twai.rst
View File

@@ -371,7 +371,7 @@ When recovery completes, the :cpp:member:`twai_event_callbacks_t::on_state_chang
Power Management
----------------
When power management is enabled via :ref:`CONFIG_PM_ENABLE`, the system may adjust or disable clock sources before entering sleep mode, which could cause TWAI to malfunction. To prevent this, the driver manages a power management lock internally. This lock is acquired when calling :cpp:func:`twai_node_enable`, ensuring the system does not enter sleep mode and TWAI remains functional. To allow the system to enter a low-power state, call :cpp:func:`twai_node_disable` to release the lock. During sleep, the TWAI controller will also stop functioning.
When power management is enabled via :menuitem:`CONFIG_PM_ENABLE`, the system may adjust or disable clock sources before entering sleep mode, which could cause TWAI to malfunction. To prevent this, the driver manages a power management lock internally. This lock is acquired when calling :cpp:func:`twai_node_enable`, ensuring the system does not enter sleep mode and TWAI remains functional. To allow the system to enter a low-power state, call :cpp:func:`twai_node_disable` to release the lock. During sleep, the TWAI controller will also stop functioning.
.. only:: SOC_TWAI_SUPPORT_SLEEP_RETENTION
@@ -380,12 +380,12 @@ When power management is enabled via :ref:`CONFIG_PM_ENABLE`, the system may adj
{IDF_TARGET_NAME} supports powering down the TWAI controller during **Light Sleep** to further reduce power consumption and automatically restore after waking up. This means the application does not need to reconfigure TWAI after **Light Sleep** wake up.
Enable the option :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`, and set :cpp:member:`twai_onchip_node_config_t::flags::sleep_allow_pd` to ``true`` when initializing the TWAI node to enable this feature. Otherwise, the TWAI controller will remain powered during **Light Sleep**. This feature helps reduce power consumption during light sleep but requires additional storage to save register configurations.
Enable the option :menuitem:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`, and set :cpp:member:`twai_onchip_node_config_t::flags::sleep_allow_pd` to ``true`` when initializing the TWAI node to enable this feature. Otherwise, the TWAI controller will remain powered during **Light Sleep**. This feature helps reduce power consumption during light sleep but requires additional storage to save register configurations.
Cache Safety
------------
During Flash write operations, the system temporarily disables cache to prevent instruction and data fetch errors from Flash. This can cause interrupt handlers stored in Flash to become unresponsive. If you want interrupt routines to remain operational during cache-disabled periods, enable the :ref:`CONFIG_TWAI_ISR_CACHE_SAFE` option.
During Flash write operations, the system temporarily disables cache to prevent instruction and data fetch errors from Flash. This can cause interrupt handlers stored in Flash to become unresponsive. If you want interrupt routines to remain operational during cache-disabled periods, enable the :menuitem:`CONFIG_TWAI_ISR_CACHE_SAFE` option.
.. note::
@@ -399,9 +399,9 @@ The driver guarantees thread safety for all public TWAI APIs. You can safely cal
Performance
-----------
To improve the real-time performance of interrupt handling, the driver provides the :ref:`CONFIG_TWAI_ISR_IN_IRAM` option. When enabled, the TWAI ISR (Interrupt Service Routine) and receive operations are placed in internal RAM, reducing latency caused by instruction fetching from Flash.
To improve the real-time performance of interrupt handling, the driver provides the :menuitem:`CONFIG_TWAI_ISR_IN_IRAM` option. When enabled, the TWAI ISR (Interrupt Service Routine) and receive operations are placed in internal RAM, reducing latency caused by instruction fetching from Flash.
For applications that require high-performance transmit operations, the driver provides the :ref:`CONFIG_TWAI_IO_FUNC_IN_IRAM` option to place transmit functions in IRAM. This is particularly beneficial for time-critical applications that frequently call :cpp:func:`twai_node_transmit` from user tasks.
For applications that require high-performance transmit operations, the driver provides the :menuitem:`CONFIG_TWAI_IO_FUNC_IN_IRAM` option to place transmit functions in IRAM. This is particularly beneficial for time-critical applications that frequently call :cpp:func:`twai_node_transmit` from user tasks.
.. note::
@@ -416,8 +416,8 @@ You can inspect the Flash and memory usage of the TWAI driver using the :doc:`/a
- Default log level is set to ``ESP_LOG_INFO`` to balance debugging information and performance.
- The following driver optimization options are disabled:
- :ref:`CONFIG_TWAI_ISR_IN_IRAM` – ISR is not placed in IRAM.
- :ref:`CONFIG_TWAI_ISR_CACHE_SAFE` – Cache safety option is disabled.
- :menuitem:`CONFIG_TWAI_ISR_IN_IRAM` – ISR is not placed in IRAM.
- :menuitem:`CONFIG_TWAI_ISR_CACHE_SAFE` – Cache safety option is disabled.
**The following resource usage data is for reference only. Actual values may vary across different target chips.**
@@ -431,7 +431,7 @@ You can inspect the Flash and memory usage of the TWAI driver using the :doc:`/a
| soc | 64 | 0 | 0 | 0 | 0 | 64 | 64 | 0 |
+-----------------+------------+-------+------+-------+-------+-------+---------+-------+
Resource Usage with :ref:`CONFIG_TWAI_ISR_IN_IRAM` Enabled:
Resource Usage with :menuitem:`CONFIG_TWAI_ISR_IN_IRAM` Enabled:
+-----------------+------------+-------+------+-------+-------+-------+---------+-------+
| Component Layer | Total Size | DIRAM | .bss | .data | .text | Flash | .rodata | .text |
@@ -448,7 +448,7 @@ Additionally, each TWAI handle dynamically allocates approximately ``168`` + 4 *
Other Kconfig Options
---------------------
- :ref:`CONFIG_TWAI_ENABLE_DEBUG_LOG`: This option forces all debug logs of the TWAI driver to be enabled regardless of the global log level settings. Enabling this can help developers obtain more detailed log information during debugging, making it easier to locate and resolve issues.
- :menuitem:`CONFIG_TWAI_ENABLE_DEBUG_LOG`: This option forces all debug logs of the TWAI driver to be enabled regardless of the global log level settings. Enabling this can help developers obtain more detailed log information during debugging, making it easier to locate and resolve issues.
Application Examples
====================

12
docs/en/api-reference/peripherals/uhci.rst
View File

@@ -241,7 +241,7 @@ As the basic usage has been covered, it's time to explore more advanced features
Power Management
^^^^^^^^^^^^^^^^
When power management is enabled, i.e., :ref:`CONFIG_PM_ENABLE` is on, the system may adjust or disable the clock source before going to sleep. As a result, the FIFO inside the UHCI can't work as expected.
When power management is enabled, i.e., :menuitem:`CONFIG_PM_ENABLE` is on, the system may adjust or disable the clock source before going to sleep. As a result, the FIFO inside the UHCI can't work as expected.
The driver can prevent the above issue by creating a power management lock. The lock type is set based on different clock sources. The driver will acquire the lock in :cpp:func:`uhci_receive` or :cpp:func:`uhci_transmit`, and release it in the transaction-done interrupt. That means, any UHCI transactions between these two functions are guaranteed to work correctly and stably.
@@ -250,7 +250,7 @@ Cache Safe
By default, the interrupt on which UHCI relies is deferred when the Cache is disabled for reasons such as writing or erasing the main flash. Thus, the transaction-done interrupt fails to be handled in time, which is unacceptable in a real-time application. What is worse, when the UHCI transaction relies on **ping-pong** interrupt to successively encode or copy the UHCI buffer, a delayed interrupt can lead to an unpredictable result.
There is a Kconfig option :ref:`CONFIG_UHCI_ISR_CACHE_SAFE` that has the following features:
There is a Kconfig option :menuitem:`CONFIG_UHCI_ISR_CACHE_SAFE` that has the following features:
1. Enable the interrupt being serviced even when the cache is disabled
2. Place all functions used by the ISR into IRAM [1]_
@@ -265,7 +265,7 @@ Use the :doc:`/api-guides/tools/idf-size` tool to check the code and data consum
**Note that the following data are not exact values and are for reference only; they may differ on different chip models.**
Resource consumption when :ref:`CONFIG_UHCI_ISR_CACHE_SAFE` is enabled:
Resource consumption when :menuitem:`CONFIG_UHCI_ISR_CACHE_SAFE` is enabled:
.. list-table:: Resource Consumption
:widths: 10 10 10 10 10 10 10 10 10
@@ -290,7 +290,7 @@ Resource consumption when :ref:`CONFIG_UHCI_ISR_CACHE_SAFE` is enabled:
- 175
- 175
Resource consumption when :ref:`CONFIG_UHCI_ISR_CACHE_SAFE` is disabled:
Resource consumption when :menuitem:`CONFIG_UHCI_ISR_CACHE_SAFE` is disabled:
.. list-table:: Resource Consumption
:widths: 10 10 10 10 10 10 10 10 10 10
@@ -320,7 +320,7 @@ Resource consumption when :ref:`CONFIG_UHCI_ISR_CACHE_SAFE` is disabled:
Performance
^^^^^^^^^^^
To improve the real-time response capability of interrupt handling, the UHCI driver provides the :ref:`CONFIG_UHCI_ISR_HANDLER_IN_IRAM` option. Enabling this option will place the interrupt handler in internal RAM, reducing the latency caused by cache misses when loading instructions from Flash.
To improve the real-time response capability of interrupt handling, the UHCI driver provides the :menuitem:`CONFIG_UHCI_ISR_HANDLER_IN_IRAM` option. Enabling this option will place the interrupt handler in internal RAM, reducing the latency caused by cache misses when loading instructions from Flash.
.. note::
@@ -334,7 +334,7 @@ The factory function :cpp:func:`uhci_new_controller`, :cpp:func:`uhci_register_e
Other Kconfig Options
^^^^^^^^^^^^^^^^^^^^^
- :ref:`CONFIG_UHCI_ENABLE_DEBUG_LOG` is allowed for the forced enabling of all debug logs for the UHCI driver, regardless of the global log level setting. Enabling this option can help developers obtain more detailed log information during the debugging process, making it easier to locate and resolve issues, but it will increase the size of the firmware binary.
- :menuitem:`CONFIG_UHCI_ENABLE_DEBUG_LOG` is allowed for the forced enabling of all debug logs for the UHCI driver, regardless of the global log level setting. Enabling this option can help developers obtain more detailed log information during the debugging process, making it easier to locate and resolve issues, but it will increase the size of the firmware binary.
Application Examples
--------------------

14
docs/en/api-reference/protocols/esp_crt_bundle.rst
View File

@@ -26,9 +26,9 @@ Configuration
Most configuration is done through menuconfig. CMake generates the bundle according to the configuration and embed it.
* :ref:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE`: automatically build and attach the bundle.
* :ref:`CONFIG_MBEDTLS_DEFAULT_CERTIFICATE_BUNDLE`: decide which certificates to include from the complete root certificate list.
* :ref:`CONFIG_MBEDTLS_CUSTOM_CERTIFICATE_BUNDLE_PATH`: specify the path of any additional certificates to embed in the bundle.
* :menuitem:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE`: automatically build and attach the bundle.
* :menuitem:`CONFIG_MBEDTLS_DEFAULT_CERTIFICATE_BUNDLE`: decide which certificates to include from the complete root certificate list.
* :menuitem:`CONFIG_MBEDTLS_CUSTOM_CERTIFICATE_BUNDLE_PATH`: specify the path of any additional certificates to embed in the bundle.
To enable the bundle when using ESP-TLS simply pass the function pointer to the bundle attach function:
@@ -75,7 +75,7 @@ The bundle is embedded into the app and can be updated along with the app by an
Periodic Sync
-------------
The bundle is kept updated by periodic sync with the Mozilla's NSS root certificate store. The deprecated certs from the upstream bundle are added to deprecated list (for compatibility reasons) in ESP-IDF minor or patch release. If required, the deprecated certs can be added to the default bundle by enabling :ref:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_DEPRECATED_LIST`. The deprecated certs shall be removed (reset) on the next major ESP-IDF release.
The bundle is kept updated by periodic sync with the Mozilla's NSS root certificate store. The deprecated certs from the upstream bundle are added to deprecated list (for compatibility reasons) in ESP-IDF minor or patch release. If required, the deprecated certs can be added to the default bundle by enabling :menuitem:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_DEPRECATED_LIST`. The deprecated certs shall be removed (reset) on the next major ESP-IDF release.
Cross-Signed Certificate Support
---------------------------------
@@ -83,7 +83,7 @@ Cross-Signed Certificate Support
Overview
^^^^^^^^
When the configuration option :ref:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_CROSS_SIGNED_VERIFY` is enabled, the ESP x509 Certificate Bundle API adds support for verifying certificate chains that include cross-signed root certificates.
When the configuration option :menuitem:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_CROSS_SIGNED_VERIFY` is enabled, the ESP x509 Certificate Bundle API adds support for verifying certificate chains that include cross-signed root certificates.
This feature allows the verification process to dynamically select candidate Certificate Authorities (CAs) from the bundle, even when the certificate chain contains cross-signed roots, improving interoperability with a wider range of server certificates.
@@ -102,11 +102,11 @@ Key Points:
Usage
^^^^^
No additional application changes are required beyond enabling :ref:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_CROSS_SIGNED_VERIFY` in your project configuration. The bundle will automatically provide candidate CAs during the TLS handshake.
No additional application changes are required beyond enabling :menuitem:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_CROSS_SIGNED_VERIFY` in your project configuration. The bundle will automatically provide candidate CAs during the TLS handshake.
.. note::
If :ref:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_CROSS_SIGNED_VERIFY` is enabled, it internally uses ``MBEDTLS_X509_TRUSTED_CERT_CALLBACK``. In this case, users should **not** provide their own trusted certificate callback, as the certificate bundle will manage this automatically.
If :menuitem:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_CROSS_SIGNED_VERIFY` is enabled, it internally uses ``MBEDTLS_X509_TRUSTED_CERT_CALLBACK``. In this case, users should **not** provide their own trusted certificate callback, as the certificate bundle will manage this automatically.
Application Examples
--------------------

8
docs/en/api-reference/protocols/esp_http_client.rst
View File

@@ -71,7 +71,7 @@ A secure element (ATECC608) can be used for the underlying TLS connection in the
HTTPS Request
-------------
ESP HTTP client supports SSL connections using **mbedTLS**, with the ``url`` configuration starting with ``https`` scheme or ``transport_type`` set to ``HTTP_TRANSPORT_OVER_SSL``. HTTPS support can be configured via :ref:`CONFIG_ESP_HTTP_CLIENT_ENABLE_HTTPS` (enabled by default).
ESP HTTP client supports SSL connections using **mbedTLS**, with the ``url`` configuration starting with ``https`` scheme or ``transport_type`` set to ``HTTP_TRANSPORT_OVER_SSL``. HTTPS support can be configured via :menuitem:`CONFIG_ESP_HTTP_CLIENT_ENABLE_HTTPS` (enabled by default).
.. note::
@@ -147,9 +147,9 @@ Configuration
To enable response header saving, the following Kconfig options must be configured:
* :ref:`CONFIG_ESP_HTTP_CLIENT_SAVE_RESPONSE_HEADERS`: Enable saving of response headers (disabled by default to conserve memory).
* :ref:`CONFIG_ESP_HTTP_CLIENT_MAX_SAVED_RESPONSE_HEADERS`: Maximum number of response headers to save (default: 10).
* :ref:`CONFIG_ESP_HTTP_CLIENT_MAX_RESPONSE_HEADER_SIZE`: Maximum size in bytes for both header key and value (default: 128 bytes each).
* :menuitem:`CONFIG_ESP_HTTP_CLIENT_SAVE_RESPONSE_HEADERS`: Enable saving of response headers (disabled by default to conserve memory).
* :menuitem:`CONFIG_ESP_HTTP_CLIENT_MAX_SAVED_RESPONSE_HEADERS`: Maximum number of response headers to save (default: 10).
* :menuitem:`CONFIG_ESP_HTTP_CLIENT_MAX_RESPONSE_HEADER_SIZE`: Maximum size in bytes for both header key and value (default: 128 bytes each).
Usage
^^^^^

6
docs/en/api-reference/protocols/esp_http_server.rst
View File

@@ -93,7 +93,7 @@ Check the example under :example:`protocols/http_server/persistent_sockets`. Thi
WebSocket Server
----------------
The HTTP server component provides WebSocket support. The WebSocket feature can be enabled in menuconfig using the :ref:`CONFIG_HTTPD_WS_SUPPORT` option.
The HTTP server component provides WebSocket support. The WebSocket feature can be enabled in menuconfig using the :menuitem:`CONFIG_HTTPD_WS_SUPPORT` option.
:example:`protocols/http_server/ws_echo_server` demonstrates how to create a WebSocket echo server using the HTTP server, which starts on a local network and requires a WebSocket client for interaction, echoing back received WebSocket frames.
@@ -105,7 +105,7 @@ The HTTP server component provides a pre-handshake callback for WebSocket endpoi
The pre-handshake callback can be used for authentication, authorization, or other checks. If the callback returns :c:macro:`ESP_OK`, the WebSocket handshake will proceed. If the callback returns any other value, the handshake will be aborted and the connection will be closed.
To use the WebSocket pre-handshake callback, you must enable :ref:`CONFIG_HTTPD_WS_PRE_HANDSHAKE_CB_SUPPORT` in your project configuration.
To use the WebSocket pre-handshake callback, you must enable :menuitem:`CONFIG_HTTPD_WS_PRE_HANDSHAKE_CB_SUPPORT` in your project configuration.
WebSocket Post-Handshake Callback
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -114,7 +114,7 @@ Similar to the pre-handshake callback, the HTTP server component also provides a
At this point the connection has been upgraded to WebSocket, and the server has responded with the WebSocket handshake response. This post handshake callback can be used for logging, sending initial messages, or other setup tasks.
To use the WebSocket post-handshake callback, you must enable :ref:`CONFIG_HTTPD_WS_POST_HANDSHAKE_CB_SUPPORT` in your project configuration.
To use the WebSocket post-handshake callback, you must enable :menuitem:`CONFIG_HTTPD_WS_POST_HANDSHAKE_CB_SUPPORT` in your project configuration.
.. code-block:: c

2
docs/en/api-reference/protocols/esp_https_server.rst
View File

@@ -77,7 +77,7 @@ HTTPS Server Cert Selection Hook
The ESP HTTPS Server component provides an option to set the server certification selection hook. This feature allows you to configure and use a certificate selection callback during server handshake. The callback helps to select a certificate to present to the client based on the TLS extensions supplied in the client hello message, such as ALPN and SNI.
To enable this feature, please enable :ref:`CONFIG_ESP_HTTPS_SERVER_CERT_SELECT_HOOK` in the ESP HTTPS Server menuconfig. Please note that the ESP-TLS option is only available when Mbedtls is used as the TLS stack for ESP-TLS (default behaviour).
To enable this feature, please enable :menuitem:`CONFIG_ESP_HTTPS_SERVER_CERT_SELECT_HOOK` in the ESP HTTPS Server menuconfig. Please note that the ESP-TLS option is only available when Mbedtls is used as the TLS stack for ESP-TLS (default behaviour).
When enabled, you can set the certificate selection callback using the :cpp:member:`httpd_ssl_config::cert_select_cb` member of the :cpp:type:`httpd_ssl_config_t` structure.

10
docs/en/api-reference/protocols/esp_tls.rst
View File

@@ -50,8 +50,8 @@ ESP-TLS provides multiple options for TLS server verification on the client side
* ``cacert_bytes`` - the size of the CA certificate in bytes.
* **use_global_ca_store**: The ``global_ca_store`` can be initialized and set at once. Then it can be used to verify the server for all the ESP-TLS connections which have set ``use_global_ca_store = true`` in their respective :cpp:type:`esp_tls_cfg_t` structure. See the API Reference section below for information regarding different APIs used for initializing and setting up the ``global_ca_store``.
* **crt_bundle_attach**: The ESP x509 Certificate Bundle API provides an easy way to include a bundle of custom x509 root certificates for TLS server verification. More details can be found at :doc:`ESP x509 Certificate Bundle </api-reference/protocols/esp_crt_bundle>`.
* **psk_hint_key**: To use pre-shared keys for server verification, :ref:`CONFIG_ESP_TLS_PSK_VERIFICATION` should be enabled in the ESP-TLS menuconfig. Then the pointer to the PSK hint and key should be provided to the :cpp:type:`esp_tls_cfg_t` structure. The ESP-TLS will use the PSK for server verification only when no other option regarding server verification is selected.
* **skip server verification**: This is an insecure option provided in the ESP-TLS for testing purposes. The option can be set by enabling :ref:`CONFIG_ESP_TLS_INSECURE` and :ref:`CONFIG_ESP_TLS_SKIP_SERVER_CERT_VERIFY` in the ESP-TLS menuconfig. When this option is enabled the ESP-TLS will skip server verification by default when no other options for server verification are selected in the :cpp:type:`esp_tls_cfg_t` structure.
* **psk_hint_key**: To use pre-shared keys for server verification, :menuitem:`CONFIG_ESP_TLS_PSK_VERIFICATION` should be enabled in the ESP-TLS menuconfig. Then the pointer to the PSK hint and key should be provided to the :cpp:type:`esp_tls_cfg_t` structure. The ESP-TLS will use the PSK for server verification only when no other option regarding server verification is selected.
* **skip server verification**: This is an insecure option provided in the ESP-TLS for testing purposes. The option can be set by enabling :menuitem:`CONFIG_ESP_TLS_INSECURE` and :menuitem:`CONFIG_ESP_TLS_SKIP_SERVER_CERT_VERIFY` in the ESP-TLS menuconfig. When this option is enabled the ESP-TLS will skip server verification by default when no other options for server verification are selected in the :cpp:type:`esp_tls_cfg_t` structure.
.. warning::
@@ -83,7 +83,7 @@ Example:
ESP-TLS Server Cert Selection Hook
----------------------------------
The ESP-TLS component provides an option to set the server certification selection hook when using the MbedTLS stack. This provides an ability to configure and use a certificate selection callback during server handshake. The callback helps to select a certificate to present to the client based on the TLS extensions supplied in the client hello message, such as ALPN and SNI. To enable this feature, please enable :ref:`CONFIG_ESP_TLS_SERVER_CERT_SELECT_HOOK` in the ESP-TLS menuconfig.
The ESP-TLS component provides an option to set the server certification selection hook when using the MbedTLS stack. This provides an ability to configure and use a certificate selection callback during server handshake. The callback helps to select a certificate to present to the client based on the TLS extensions supplied in the client hello message, such as ALPN and SNI. To enable this feature, please enable :menuitem:`CONFIG_ESP_TLS_SERVER_CERT_SELECT_HOOK` in the ESP-TLS menuconfig.
The certificate selection callback can be configured in the :cpp:type:`esp_tls_cfg_t` structure as follows:
@@ -219,7 +219,7 @@ To enable the secure element support, and use it in your project for TLS connect
1) Add `esp-cryptoauthlib <https://github.com/espressif/esp-cryptoauthlib>`_ as a dependency in your project. For details, please refer to `how to use esp-cryptoauthlib with ESP-IDF <https://github.com/espressif/esp-cryptoauthlib#how-to-use-esp-cryptoauthlib-with-esp-idf>`_.
2) Enable the menuconfig option :ref:`CONFIG_MBEDTLS_SECURE_ELEMENT_DRIVER_ENABLED`:
2) Enable the menuconfig option :menuitem:`CONFIG_MBEDTLS_SECURE_ELEMENT_DRIVER_ENABLED`:
.. code-block:: none
@@ -343,7 +343,7 @@ The mechanism for session resumption differs slightly between TLS versions:
To enable and use client session tickets:
1. Enable the Kconfig option :ref:`CONFIG_ESP_TLS_CLIENT_SESSION_TICKETS`.
1. Enable the Kconfig option :menuitem:`CONFIG_ESP_TLS_CLIENT_SESSION_TICKETS`.
2. After a successful TLS connection (and handshake completion), retrieve the session ticket using :cpp:func:`esp_tls_get_client_session`.
* **For TLS 1.3**: Since session tickets can arrive from the server at any point after the handshake, an application might need to call :cpp:func:`esp_tls_get_client_session` periodically or after specific application-level exchanges if it wants to ensure it has the most recent ticket. Each new ticket received and processed by the TLS stack supersedes the previous one for future resumption attempts.

80
docs/en/api-reference/protocols/mbedtls.rst
View File

@@ -183,9 +183,9 @@ Enabling the Custom Backend
Enable the feature via ``menuconfig`` under ``Component Config`` > ``mbedTLS``:
- :ref:`CONFIG_MBEDTLS_PSA_ITS_CUSTOM_STORAGE_BACKEND`: Enable the custom storage backend
- :ref:`CONFIG_MBEDTLS_PSA_ITS_CUSTOM_BACKEND_UID_MIN`: Start of the custom key ID range (default ``0x30000000``)
- :ref:`CONFIG_MBEDTLS_PSA_ITS_CUSTOM_BACKEND_UID_MAX`: End of the custom key ID range (default ``0x3FFFFFFF``)
- :menuitem:`CONFIG_MBEDTLS_PSA_ITS_CUSTOM_STORAGE_BACKEND`: Enable the custom storage backend
- :menuitem:`CONFIG_MBEDTLS_PSA_ITS_CUSTOM_BACKEND_UID_MIN`: Start of the custom key ID range (default ``0x30000000``)
- :menuitem:`CONFIG_MBEDTLS_PSA_ITS_CUSTOM_BACKEND_UID_MAX`: End of the custom key ID range (default ``0x3FFFFFFF``)
PSA key IDs within the configured range are routed to the registered backend. All other key IDs (and internal PSA data such as the random seed) continue using the default NVS backend.
@@ -290,57 +290,57 @@ The example :example:`protocols/smtp_client` sends email (including attachments)
Important Config Options
------------------------
The Mbed TLS configuration system supports preset configurations. Following is a brief list of important config options accessible at ``Component Config`` > ``mbedTLS``. The full list of config options can be found :ref:`here <CONFIG_MBEDTLS_MEM_ALLOC_MODE>`.
The Mbed TLS configuration system supports preset configurations. Following is a brief list of important config options accessible at ``Component Config`` > ``mbedTLS``. The full list of config options can be found :menuitem:`here <CONFIG_MBEDTLS_MEM_ALLOC_MODE>`.
**Core Configuration:**
.. list::
:SOC_SHA_SUPPORTED: - :ref:`CONFIG_MBEDTLS_HARDWARE_SHA`: Support for hardware SHA acceleration
:SOC_AES_SUPPORTED: - :ref:`CONFIG_MBEDTLS_HARDWARE_AES`: Support for hardware AES acceleration
:SOC_MPI_SUPPORTED: - :ref:`CONFIG_MBEDTLS_HARDWARE_MPI`: Support for hardware MPI (bignum) acceleration
:SOC_ECC_SUPPORTED: - :ref:`CONFIG_MBEDTLS_HARDWARE_ECC`: Support for hardware ECC acceleration
- :ref:`CONFIG_MBEDTLS_MEM_ALLOC_MODE`: Memory allocation strategy (Internal/External/Custom)
- :ref:`CONFIG_MBEDTLS_ASYMMETRIC_CONTENT_LEN`: Asymmetric in/out fragment length for memory optimization
- :ref:`CONFIG_MBEDTLS_DYNAMIC_BUFFER`: Enable dynamic TX/RX buffer allocation
- :ref:`CONFIG_MBEDTLS_DEBUG`: Enable mbedTLS debugging (useful for debugging)
:SOC_SHA_SUPPORTED: - :menuitem:`CONFIG_MBEDTLS_HARDWARE_SHA`: Support for hardware SHA acceleration
:SOC_AES_SUPPORTED: - :menuitem:`CONFIG_MBEDTLS_HARDWARE_AES`: Support for hardware AES acceleration
:SOC_MPI_SUPPORTED: - :menuitem:`CONFIG_MBEDTLS_HARDWARE_MPI`: Support for hardware MPI (bignum) acceleration
:SOC_ECC_SUPPORTED: - :menuitem:`CONFIG_MBEDTLS_HARDWARE_ECC`: Support for hardware ECC acceleration
- :menuitem:`CONFIG_MBEDTLS_MEM_ALLOC_MODE`: Memory allocation strategy (Internal/External/Custom)
- :menuitem:`CONFIG_MBEDTLS_ASYMMETRIC_CONTENT_LEN`: Asymmetric in/out fragment length for memory optimization
- :menuitem:`CONFIG_MBEDTLS_DYNAMIC_BUFFER`: Enable dynamic TX/RX buffer allocation
- :menuitem:`CONFIG_MBEDTLS_DEBUG`: Enable mbedTLS debugging (useful for debugging)
**TLS Protocol Configuration:**
.. list::
- :ref:`CONFIG_MBEDTLS_TLS_ENABLED`: Enable TLS protocol support
- :ref:`CONFIG_MBEDTLS_SSL_PROTO_TLS1_2`: Support for TLS 1.2 (recommended)
- :ref:`CONFIG_MBEDTLS_SSL_PROTO_TLS1_3`: Support for TLS 1.3 (latest standard)
- :ref:`CONFIG_MBEDTLS_SSL_PROTO_DTLS`: Support for DTLS (UDP-based TLS)
- :ref:`CONFIG_MBEDTLS_CLIENT_SSL_SESSION_TICKETS`: Support for TLS Session Resumption (client session tickets)
- :ref:`CONFIG_MBEDTLS_SERVER_SSL_SESSION_TICKETS`: Support for TLS Session Resumption Server session tickets
- :ref:`CONFIG_MBEDTLS_SSL_ALPN`: Support for Application Layer Protocol Negotiation
- :ref:`CONFIG_MBEDTLS_SSL_SERVER_NAME_INDICATION`: Support for Server Name Indication (SNI)
- :menuitem:`CONFIG_MBEDTLS_TLS_ENABLED`: Enable TLS protocol support
- :menuitem:`CONFIG_MBEDTLS_SSL_PROTO_TLS1_2`: Support for TLS 1.2 (recommended)
- :menuitem:`CONFIG_MBEDTLS_SSL_PROTO_TLS1_3`: Support for TLS 1.3 (latest standard)
- :menuitem:`CONFIG_MBEDTLS_SSL_PROTO_DTLS`: Support for DTLS (UDP-based TLS)
- :menuitem:`CONFIG_MBEDTLS_CLIENT_SSL_SESSION_TICKETS`: Support for TLS Session Resumption (client session tickets)
- :menuitem:`CONFIG_MBEDTLS_SERVER_SSL_SESSION_TICKETS`: Support for TLS Session Resumption Server session tickets
- :menuitem:`CONFIG_MBEDTLS_SSL_ALPN`: Support for Application Layer Protocol Negotiation
- :menuitem:`CONFIG_MBEDTLS_SSL_SERVER_NAME_INDICATION`: Support for Server Name Indication (SNI)
**Certificate Support:**
.. list::
- :ref:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE`: Support for trusted root certificate bundle (more about this: :doc:`/api-reference/protocols/esp_crt_bundle`)
- :ref:`CONFIG_MBEDTLS_X509_USE_C`: Enable X.509 certificate support
- :ref:`CONFIG_MBEDTLS_PEM_PARSE_C`: Read & Parse PEM formatted certificates
- :ref:`CONFIG_MBEDTLS_PEM_WRITE_C`: Write PEM formatted certificates
- :ref:`CONFIG_MBEDTLS_X509_CRT_PARSE_C`: Parse X.509 certificates
- :ref:`CONFIG_MBEDTLS_X509_CRL_PARSE_C`: Parse X.509 certificate revocation lists
- :menuitem:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE`: Support for trusted root certificate bundle (more about this: :doc:`/api-reference/protocols/esp_crt_bundle`)
- :menuitem:`CONFIG_MBEDTLS_X509_USE_C`: Enable X.509 certificate support
- :menuitem:`CONFIG_MBEDTLS_PEM_PARSE_C`: Read & Parse PEM formatted certificates
- :menuitem:`CONFIG_MBEDTLS_PEM_WRITE_C`: Write PEM formatted certificates
- :menuitem:`CONFIG_MBEDTLS_X509_CRT_PARSE_C`: Parse X.509 certificates
- :menuitem:`CONFIG_MBEDTLS_X509_CRL_PARSE_C`: Parse X.509 certificate revocation lists
**Cryptographic Algorithms:**
.. list::
- :ref:`CONFIG_MBEDTLS_AES_C`: AES block cipher support
- :ref:`CONFIG_MBEDTLS_RSA_C`: RSA public key cryptosystem
- :ref:`CONFIG_MBEDTLS_ECP_C`: Elliptic Curve Cryptography support
- :ref:`CONFIG_MBEDTLS_ECDSA_C`: Elliptic Curve Digital Signature Algorithm
- :ref:`CONFIG_MBEDTLS_ECDH_C`: Elliptic Curve Diffie-Hellman key exchange
- :ref:`CONFIG_MBEDTLS_SHA256_C`: SHA-256 hash function
- :ref:`CONFIG_MBEDTLS_SHA512_C`: SHA-512 hash function
- :ref:`CONFIG_MBEDTLS_GCM_C`: Galois/Counter Mode for authenticated encryption
- :menuitem:`CONFIG_MBEDTLS_AES_C`: AES block cipher support
- :menuitem:`CONFIG_MBEDTLS_RSA_C`: RSA public key cryptosystem
- :menuitem:`CONFIG_MBEDTLS_ECP_C`: Elliptic Curve Cryptography support
- :menuitem:`CONFIG_MBEDTLS_ECDSA_C`: Elliptic Curve Digital Signature Algorithm
- :menuitem:`CONFIG_MBEDTLS_ECDH_C`: Elliptic Curve Diffie-Hellman key exchange
- :menuitem:`CONFIG_MBEDTLS_SHA256_C`: SHA-256 hash function
- :menuitem:`CONFIG_MBEDTLS_SHA512_C`: SHA-512 hash function
- :menuitem:`CONFIG_MBEDTLS_GCM_C`: Galois/Counter Mode for authenticated encryption
.. note::
@@ -391,15 +391,15 @@ The following table shows typical memory usage with different configs when the :
- NA
- 42196 B
* - Enable SSL Dynamic Buffer Length
- :ref:`CONFIG_MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH`
- :menuitem:`CONFIG_MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH`
- 42120 B
* - Disable Keep Peer Certificate
- :ref:`CONFIG_MBEDTLS_SSL_KEEP_PEER_CERTIFICATE`
- :menuitem:`CONFIG_MBEDTLS_SSL_KEEP_PEER_CERTIFICATE`
- 38533 B
* - Enable Dynamic TX/RX Buffer
- :ref:`CONFIG_MBEDTLS_DYNAMIC_BUFFER`
:ref:`CONFIG_MBEDTLS_DYNAMIC_FREE_CONFIG_DATA`
:ref:`CONFIG_MBEDTLS_DYNAMIC_FREE_CA_CERT`
- :menuitem:`CONFIG_MBEDTLS_DYNAMIC_BUFFER`
:menuitem:`CONFIG_MBEDTLS_DYNAMIC_FREE_CONFIG_DATA`
:menuitem:`CONFIG_MBEDTLS_DYNAMIC_FREE_CA_CERT`
- 22013 B
.. note::
@@ -408,7 +408,7 @@ The following table shows typical memory usage with different configs when the :
.. note::
:ref:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_CROSS_SIGNED_VERIFY` is enabled by default. If cross-signed certificate chains are not required, disabling it reduces peak heap usage during the TLS handshake by approximately 1 KB, at the cost of a larger certificate bundle in flash. See :doc:`/api-reference/protocols/esp_crt_bundle` for details.
:menuitem:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_CROSS_SIGNED_VERIFY` is enabled by default. If cross-signed certificate chains are not required, disabling it reduces peak heap usage during the TLS handshake by approximately 1 KB, at the cost of a larger certificate bundle in flash. See :doc:`/api-reference/protocols/esp_crt_bundle` for details.
Reducing Binary Size

6
docs/en/api-reference/provisioning/protocomm.rst
View File

@@ -41,9 +41,9 @@ Enabling Protocomm Security Version
The protocomm component provides a project configuration menu to enable/disable support of respective security versions. The respective configuration options are as follows:
* Support ``protocomm_security0``, with no security: :ref:`CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_0`, this option is enabled by default.
* Support ``protocomm_security1`` with Curve25519 key exchange + AES-CTR encryption/decryption: :ref:`CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_1`, this option is enabled by default.
* Support ``protocomm_security2`` with SRP6a-based key exchange + AES-GCM encryption/decryption: :ref:`CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_2`.
* Support ``protocomm_security0``, with no security: :menuitem:`CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_0`, this option is enabled by default.
* Support ``protocomm_security1`` with Curve25519 key exchange + AES-CTR encryption/decryption: :menuitem:`CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_1`, this option is enabled by default.
* Support ``protocomm_security2`` with SRP6a-based key exchange + AES-GCM encryption/decryption: :menuitem:`CONFIG_ESP_PROTOCOMM_SUPPORT_SECURITY_VERSION_2`.
.. note::

50
docs/en/api-reference/storage/fatfs.rst
View File

@@ -81,23 +81,23 @@ Configuration Options
The following configuration options are available for the FatFs component:
* ``CONFIG_FATFS_LONG_FILENAMES`` - Selects how the FatFs library handles long filename (LFN) support. The available options are :ref:`CONFIG_FATFS_LFN_NONE <CONFIG_FATFS_LFN_NONE>` to disable LFN support and limit names to the `8.3 format <https://en.wikipedia.org/wiki/8.3_filename>`_ (SFN only), :ref:`CONFIG_FATFS_LFN_HEAP <CONFIG_FATFS_LFN_HEAP>` to enable LFN support with the LFN working buffer stored on the heap (default), and :ref:`CONFIG_FATFS_LFN_STACK <CONFIG_FATFS_LFN_STACK>` to enable LFN support with the LFN working buffer stored on the stack. For details, see `FatFs filenames <http://elm-chan.org/fsw/ff/doc/filename.html>`_.
* :ref:`CONFIG_FATFS_VOLUME_COUNT` - Sets the number of logical FatFs volumes. Increasing this value can increase baseline memory usage.
* :ref:`CONFIG_FATFS_ALLOC_PREFER_EXTRAM` - If enabled, the FatFs library prefers external RAM when allocating internal buffers. If external RAM allocation fails, it falls back to internal RAM. This can have a noticeable performance cost on hot I/O paths. Disable this option to prioritize performance; enable it to reduce internal RAM usage.
* :ref:`CONFIG_FATFS_ALLOC_PREFER_ALIGNED_WORK_BUFFERS` - If enabled, the FatFs library tries to allocate heap work buffers in DMA-capable, cache-aligned memory first so SDMMC transfers avoid extra copies. This option is useful on targets that use PSRAM with SDMMC DMA (for example ESP32-P4). If this option and :ref:`CONFIG_FATFS_ALLOC_PREFER_EXTRAM` are both enabled, the FatFs library tries DMA-capable RAM first, then external RAM, then internal RAM.
* :ref:`CONFIG_FATFS_USE_DYN_BUFFERS` - If enabled, the FatFs library allocates instance buffers separately and sizes them according to each mounted volume's logical sector size. This option is useful when multiple FatFs instances use different logical sector sizes, as it can reduce memory usage. If disabled, all instances use buffers sized for the largest configured logical sector size.
* :ref:`CONFIG_FATFS_PER_FILE_CACHE` - If enabled, each open file uses a separate cache buffer. This improves I/O performance but increases RAM usage when multiple files are open. If disabled, a single shared cache is used, which reduces RAM usage but can increase storage read/write operations.
* :ref:`CONFIG_FATFS_USE_FASTSEEK` - If enabled, POSIX :cpp:func:`lseek` runs faster. Fast seek does not work for files opened in write mode. To use fast seek, open the file in read-only mode, or close and reopen it in read-only mode.
* :ref:`CONFIG_FATFS_FAST_SEEK_BUFFER_SIZE` - Sets the CLMT (Cluster Link Map Table) buffer size used by fast seek when :ref:`CONFIG_FATFS_USE_FASTSEEK` is enabled. Larger buffers can improve seek behavior on larger files, but use more RAM.
* :ref:`CONFIG_FATFS_VFS_FSTAT_BLKSIZE` - Sets the default stdio file buffer block size used through VFS. This option is mainly relevant for stdio-based I/O (for example ``fread``/``fgets``) and is not the primary tuning knob for direct POSIX ``read``/``write`` paths. Larger values can improve buffered read throughput, but increase heap usage.
* :ref:`CONFIG_FATFS_IMMEDIATE_FSYNC` - If enabled, the FatFs library calls :cpp:func:`f_sync` automatically after each call to :cpp:func:`write`, :cpp:func:`pwrite`, :cpp:func:`link`, :cpp:func:`truncate`, and :cpp:func:`ftruncate`. This option improves file consistency and size-reporting accuracy, but decreases performance because it triggers frequent disk operations.
* :ref:`CONFIG_FATFS_LINK_LOCK` - If enabled, this option guarantees API thread safety for the :cpp:func:`link` function. Disabling this option can help applications that perform frequent small file operations (for example, file logging). When disabled, the copy performed by :cpp:func:`link` is non-atomic. In that case, using :cpp:func:`link` on a large file on the same volume from another task is not guaranteed to be thread-safe.
* Other relevant options include :ref:`CONFIG_FATFS_FS_LOCK`, :ref:`CONFIG_FATFS_TIMEOUT_MS`, and ``CONFIG_FATFS_CHOOSE_CODEPAGE`` (especially ``CONFIG_FATFS_CODEPAGE_DYNAMIC`` for code-size impact). Additional options include ``CONFIG_FATFS_SECTOR_SIZE``, ``CONFIG_FATFS_MAX_LFN``, ``CONFIG_FATFS_API_ENCODING``, and ``CONFIG_FATFS_USE_STRFUNC_CHOICE``.
* ``CONFIG_FATFS_LONG_FILENAMES`` - Selects how the FatFs library handles long filename (LFN) support. The available options are :menuitem:`CONFIG_FATFS_LFN_NONE <CONFIG_FATFS_LFN_NONE>` to disable LFN support and limit names to the `8.3 format <https://en.wikipedia.org/wiki/8.3_filename>`_ (SFN only), :menuitem:`CONFIG_FATFS_LFN_HEAP <CONFIG_FATFS_LFN_HEAP>` to enable LFN support with the LFN working buffer stored on the heap (default), and :menuitem:`CONFIG_FATFS_LFN_STACK <CONFIG_FATFS_LFN_STACK>` to enable LFN support with the LFN working buffer stored on the stack. For details, see `FatFs filenames <http://elm-chan.org/fsw/ff/doc/filename.html>`_.
* :menuitem:`CONFIG_FATFS_VOLUME_COUNT` - Sets the number of logical FatFs volumes. Increasing this value can increase baseline memory usage.
* :menuitem:`CONFIG_FATFS_ALLOC_PREFER_EXTRAM` - If enabled, the FatFs library prefers external RAM when allocating internal buffers. If external RAM allocation fails, it falls back to internal RAM. This can have a noticeable performance cost on hot I/O paths. Disable this option to prioritize performance; enable it to reduce internal RAM usage.
* :menuitem:`CONFIG_FATFS_ALLOC_PREFER_ALIGNED_WORK_BUFFERS` - If enabled, the FatFs library tries to allocate heap work buffers in DMA-capable, cache-aligned memory first so SDMMC transfers avoid extra copies. This option is useful on targets that use PSRAM with SDMMC DMA (for example ESP32-P4). If this option and :menuitem:`CONFIG_FATFS_ALLOC_PREFER_EXTRAM` are both enabled, the FatFs library tries DMA-capable RAM first, then external RAM, then internal RAM.
* :menuitem:`CONFIG_FATFS_USE_DYN_BUFFERS` - If enabled, the FatFs library allocates instance buffers separately and sizes them according to each mounted volume's logical sector size. This option is useful when multiple FatFs instances use different logical sector sizes, as it can reduce memory usage. If disabled, all instances use buffers sized for the largest configured logical sector size.
* :menuitem:`CONFIG_FATFS_PER_FILE_CACHE` - If enabled, each open file uses a separate cache buffer. This improves I/O performance but increases RAM usage when multiple files are open. If disabled, a single shared cache is used, which reduces RAM usage but can increase storage read/write operations.
* :menuitem:`CONFIG_FATFS_USE_FASTSEEK` - If enabled, POSIX :cpp:func:`lseek` runs faster. Fast seek does not work for files opened in write mode. To use fast seek, open the file in read-only mode, or close and reopen it in read-only mode.
* :menuitem:`CONFIG_FATFS_FAST_SEEK_BUFFER_SIZE` - Sets the CLMT (Cluster Link Map Table) buffer size used by fast seek when :menuitem:`CONFIG_FATFS_USE_FASTSEEK` is enabled. Larger buffers can improve seek behavior on larger files, but use more RAM.
* :menuitem:`CONFIG_FATFS_VFS_FSTAT_BLKSIZE` - Sets the default stdio file buffer block size used through VFS. This option is mainly relevant for stdio-based I/O (for example ``fread``/``fgets``) and is not the primary tuning knob for direct POSIX ``read``/``write`` paths. Larger values can improve buffered read throughput, but increase heap usage.
* :menuitem:`CONFIG_FATFS_IMMEDIATE_FSYNC` - If enabled, the FatFs library calls :cpp:func:`f_sync` automatically after each call to :cpp:func:`write`, :cpp:func:`pwrite`, :cpp:func:`link`, :cpp:func:`truncate`, and :cpp:func:`ftruncate`. This option improves file consistency and size-reporting accuracy, but decreases performance because it triggers frequent disk operations.
* :menuitem:`CONFIG_FATFS_LINK_LOCK` - If enabled, this option guarantees API thread safety for the :cpp:func:`link` function. Disabling this option can help applications that perform frequent small file operations (for example, file logging). When disabled, the copy performed by :cpp:func:`link` is non-atomic. In that case, using :cpp:func:`link` on a large file on the same volume from another task is not guaranteed to be thread-safe.
* Other relevant options include :menuitem:`CONFIG_FATFS_FS_LOCK`, :menuitem:`CONFIG_FATFS_TIMEOUT_MS`, and ``CONFIG_FATFS_CHOOSE_CODEPAGE`` (especially ``CONFIG_FATFS_CODEPAGE_DYNAMIC`` for code-size impact). Additional options include ``CONFIG_FATFS_SECTOR_SIZE``, ``CONFIG_FATFS_MAX_LFN``, ``CONFIG_FATFS_API_ENCODING``, and ``CONFIG_FATFS_USE_STRFUNC_CHOICE``.
These options control how the FatFs library calculates and reports free space:
* :ref:`CONFIG_FATFS_DONT_TRUST_FREE_CLUSTER_CNT` - If set to 1, the FatFs library ignores the free cluster count. The default value is 0.
* :ref:`CONFIG_FATFS_DONT_TRUST_LAST_ALLOC` - If set to 1, the FatFs library ignores the last allocation number. The default value is 0.
* :menuitem:`CONFIG_FATFS_DONT_TRUST_FREE_CLUSTER_CNT` - If set to 1, the FatFs library ignores the free cluster count. The default value is 0.
* :menuitem:`CONFIG_FATFS_DONT_TRUST_LAST_ALLOC` - If set to 1, the FatFs library ignores the last allocation number. The default value is 0.
.. note::
@@ -324,9 +324,9 @@ FatFs behavior can be tuned for different priorities by choosing the right confi
The main variables that affect behavior are:
* Buffer placement and sizing (:ref:`CONFIG_FATFS_ALLOC_PREFER_ALIGNED_WORK_BUFFERS`, :ref:`CONFIG_FATFS_ALLOC_PREFER_EXTRAM`, :ref:`CONFIG_FATFS_USE_DYN_BUFFERS`, :ref:`CONFIG_FATFS_PER_FILE_CACHE`, and application I/O buffer sizes).
* Buffer placement and sizing (:menuitem:`CONFIG_FATFS_ALLOC_PREFER_ALIGNED_WORK_BUFFERS`, :menuitem:`CONFIG_FATFS_ALLOC_PREFER_EXTRAM`, :menuitem:`CONFIG_FATFS_USE_DYN_BUFFERS`, :menuitem:`CONFIG_FATFS_PER_FILE_CACHE`, and application I/O buffer sizes).
* Wear leveling logical sector size and mode (``CONFIG_WL_SECTOR_SIZE_*`` and ``CONFIG_WL_SECTOR_MODE_*``).
* Sync strategy (:ref:`CONFIG_FATFS_IMMEDIATE_FSYNC`).
* Sync strategy (:menuitem:`CONFIG_FATFS_IMMEDIATE_FSYNC`).
* Workload pattern (transaction sizes, sequential vs random access, read vs write ratio).
Optimize I/O Performance
@@ -334,15 +334,15 @@ Optimize I/O Performance
For throughput-oriented workloads:
* Keep :ref:`CONFIG_FATFS_IMMEDIATE_FSYNC` disabled unless your consistency requirements need it.
* If peak speed is the top priority, disable :ref:`CONFIG_FATFS_ALLOC_PREFER_EXTRAM` so buffers stay in internal RAM.
* Keep :menuitem:`CONFIG_FATFS_IMMEDIATE_FSYNC` disabled unless your consistency requirements need it.
* If peak speed is the top priority, disable :menuitem:`CONFIG_FATFS_ALLOC_PREFER_EXTRAM` so buffers stay in internal RAM.
* Prefer larger read/write transaction sizes over many small operations.
* Align transaction sizes to the active sector size when possible (for example 512 B or 4096 B), and pad writes if needed to reduce partial-sector overhead.
* For SPI flash with wear leveling, prefer ``CONFIG_WL_SECTOR_SIZE_4096`` when RAM budget allows, as it is generally more efficient.
* If using 512-byte WL sectors, use ``CONFIG_WL_SECTOR_MODE_PERF`` when your application can accept the higher power-loss risk during flash-sector erase.
* Prefer POSIX ``read``/``write`` over ``fread``/``fwrite`` on hot paths when possible. For broader speed guidance, see :doc:`Maximizing Execution Speed <../../api-guides/performance/speed>`.
* On SDMMC DMA targets (for example ESP32-P4 with PSRAM), enable :ref:`CONFIG_FATFS_ALLOC_PREFER_ALIGNED_WORK_BUFFERS` to reduce extra buffer copies.
* Enable :ref:`CONFIG_FATFS_USE_FASTSEEK` for read-heavy workloads with long backward seeks.
* On SDMMC DMA targets (for example ESP32-P4 with PSRAM), enable :menuitem:`CONFIG_FATFS_ALLOC_PREFER_ALIGNED_WORK_BUFFERS` to reduce extra buffer copies.
* Enable :menuitem:`CONFIG_FATFS_USE_FASTSEEK` for read-heavy workloads with long backward seeks.
.. note::
@@ -351,14 +351,14 @@ For throughput-oriented workloads:
Optimize Memory Usage
^^^^^^^^^^^^^^^^^^^^^^^^^^^
* Disable :ref:`CONFIG_FATFS_PER_FILE_CACHE` to use a single shared cache when reducing RAM usage is the priority.
* Disable :menuitem:`CONFIG_FATFS_PER_FILE_CACHE` to use a single shared cache when reducing RAM usage is the priority.
* Tune ``esp_vfs_fat_mount_config_t.max_files`` (see :ref:`Mount and Use FatFs <fatfs-mount-and-use>`) as low as practical; each simultaneously open file increases RAM usage.
* If :ref:`CONFIG_FATFS_PER_FILE_CACHE` is enabled, prefer ``CONFIG_WL_SECTOR_SIZE_512`` to reduce per-file cache size.
* If :ref:`CONFIG_FATFS_PER_FILE_CACHE` is disabled, ``CONFIG_WL_SECTOR_SIZE_4096`` may be a better tradeoff.
* Enable :ref:`CONFIG_FATFS_ALLOC_PREFER_EXTRAM` on targets with external RAM support to reduce internal RAM pressure, but expect lower I/O performance.
* If :menuitem:`CONFIG_FATFS_PER_FILE_CACHE` is enabled, prefer ``CONFIG_WL_SECTOR_SIZE_512`` to reduce per-file cache size.
* If :menuitem:`CONFIG_FATFS_PER_FILE_CACHE` is disabled, ``CONFIG_WL_SECTOR_SIZE_4096`` may be a better tradeoff.
* Enable :menuitem:`CONFIG_FATFS_ALLOC_PREFER_EXTRAM` on targets with external RAM support to reduce internal RAM pressure, but expect lower I/O performance.
* Consider ``CONFIG_FATFS_LONG_FILENAMES = CONFIG_FATFS_LFN_NONE`` when SFN (8.3) filenames are acceptable.
* If long filenames are required, reduce ``CONFIG_FATFS_MAX_LFN`` to the smallest value that meets your needs.
* Enable :ref:`CONFIG_FATFS_USE_DYN_BUFFERS` so each mounted volume uses buffers sized to its actual sector size.
* Enable :menuitem:`CONFIG_FATFS_USE_DYN_BUFFERS` so each mounted volume uses buffers sized to its actual sector size.
Optimize Storage Efficiency
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

2
docs/en/api-reference/storage/nvs_bootloader.rst
View File

@@ -31,7 +31,7 @@ Applications are expected to follow the steps below in order to enable decryptio
.. note::
While using the HMAC-based scheme, the above workflow can be used without enabling any of the config options for NVS encryption - :ref:`CONFIG_NVS_ENCRYPTION`, :ref:`CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME` -> ``CONFIG_NVS_SEC_KEY_PROTECT_USING_HMAC`` and :ref:`CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID` to encrypt the default as well as custom NVS partitions with :cpp:func:`nvs_flash_secure_init` API.
While using the HMAC-based scheme, the above workflow can be used without enabling any of the config options for NVS encryption - :menuitem:`CONFIG_NVS_ENCRYPTION`, :menuitem:`CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME` -> ``CONFIG_NVS_SEC_KEY_PROTECT_USING_HMAC`` and :menuitem:`CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID` to encrypt the default as well as custom NVS partitions with :cpp:func:`nvs_flash_secure_init` API.
Application Example

Some files were not shown because too many files have changed in this diff Show More