diff --git a/docs/conf_common.py b/docs/conf_common.py index 213c03d87..0425b077b 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -135,9 +135,15 @@ def update_exclude_patterns(tags): 'api-guides/jtag-debugging/configure-wrover.rst', 'api-reference/bluetooth/**', 'api-reference/system/himem.rst', + 'api-reference/system/ipc.rst', + 'hw-reference/get-started-devkitc-v2.rst', 'hw-reference/get-started-devkitc.rst', + 'hw-reference/get-started-ethernet-kit-v1.0.rst', 'hw-reference/get-started-ethernet-kit.rst', + 'hw-reference/get-started-pico-kit-v3.rst', 'hw-reference/get-started-pico-kit.rst', + 'hw-reference/get-started-wrover-kit-v2.rst', + 'hw-reference/get-started-wrover-kit-v3.rst', 'hw-reference/get-started-wrover-kit.rst', 'get-started-legacy/**', 'gnu-make-legacy.rst']: diff --git a/docs/en/about.rst b/docs/en/about.rst index c23ed2b60..2f0540106 100644 --- a/docs/en/about.rst +++ b/docs/en/about.rst @@ -2,9 +2,18 @@ About ===== :link_to_translation:`zh_CN:[中文]` -This is documentation of `ESP-IDF `_, the framework to develop applications for `ESP32 `_ chip by `Espressif `_. +.. only:: esp32 -The ESP32 is 2.4 GHz Wi-Fi and Bluetooth combo, which integrates one or two 32-bit microprocessors, with up to 600 DMIPS processing power. + This is documentation of `ESP-IDF `_, the framework to develop applications for `{IDF_TARGET_NAME} `_ chip by `Espressif `_. + + The {IDF_TARGET_NAME} is 2.4 GHz Wi-Fi and Bluetooth combo, which integrates one or two 32-bit microprocessors, with up to 600 DMIPS processing power. + + +.. only:: esp32s2 + + This is documentation of `ESP-IDF `_, the framework to develop applications for {IDF_TARGET_NAME}. + + The {IDF_TARGET_NAME} is a 2.4 GHz Wi-Fi module, which integrates a 32-bit microprocessors, with up to 600 DMIPS processing power. .. figure:: ../_static/about-doc.png :align: center @@ -13,5 +22,5 @@ The ESP32 is 2.4 GHz Wi-Fi and Bluetooth combo, which integrates one or two 32-b Espressif IoT Integrated Development Framework -The ESP-IDF, Espressif IoT Development Framework, provides toolchain, API, components and workflows to develop applications for ESP32 using Windows, Linux and Mac OS operating systems. +The ESP-IDF, Espressif IoT Development Framework, provides toolchain, API, components and workflows to develop applications for {IDF_TARGET_NAME} using Windows, Linux and Mac OS operating systems. diff --git a/docs/en/api-guides/RF_calibration.rst b/docs/en/api-guides/RF_calibration.rst index 696cc5323..25b5862e3 100644 --- a/docs/en/api-guides/RF_calibration.rst +++ b/docs/en/api-guides/RF_calibration.rst @@ -1,7 +1,7 @@ RF calibration ============== -ESP32 supports three RF calibration methods during RF initialization: +{IDF_TARGET_NAME} supports three RF calibration methods during RF initialization: 1. Partial calibration @@ -11,8 +11,8 @@ ESP32 supports three RF calibration methods during RF initialization: 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. +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_ESP32_PHY_CALIBRATION_AND_DATA_STORAGE`. Full calibration @@ -20,8 +20,8 @@ Full calibration Full calibration is triggered in the follwing conditions: 1. NVS does not exist. - -2. The NVS partition to store calibration data is erased. + +2. The NVS partition to store calibration data is erased. 3. Hardware MAC address is changed. @@ -29,31 +29,32 @@ Full calibration is triggered in the follwing conditions: 5. The RF calibration data loaded from the NVS partition is broken. -It takes about 100ms more than partial calibration. -If boot duration is not critical, it is suggested to use the full calibration method. -To switch to the full calibration method, go to ``menuconfig`` and disable :ref:`CONFIG_ESP32_PHY_CALIBRATION_AND_DATA_STORAGE`. +It takes about 100ms more than partial calibration. +If boot duration is not critical, it is suggested to use the full calibration method. +To switch to the full calibration method, go to ``menuconfig`` and disable :ref:`CONFIG_ESP32_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 don't mind all of the data stored in the NVS partition is erased. That is indeed the easiest way. -2. Call API :cpp:func:`esp_phy_erase_cal_data_in_nvs` before initializing WiFi and BT/BLE based on some conditions (e.g. an option provided in some diagnostic mode). +2. Call API :cpp:func:`esp_phy_erase_cal_data_in_nvs` before initializing WiFi and BT/BLE based on some conditions (e.g. an option provided in some diagnostic mode). In this case, only phy namespace of the NVS partition is erased. No calibration --------------- -No calibration method is only used when ESP32 wakes up from deep sleep. +No calibration method is only used when {IDF_TARGET_NAME} wakes up from deep sleep. PHY initialization data ----------------------- -The PHY initialization data is used for RF calibration. -There are two ways to get the PHY initialization data. +The PHY initialization data is used for RF calibration. +There are two ways to get the PHY initialization data. -One is the default initialization data which is located in the header file :idf_file:`components/esp_wifi/esp32/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_ESP32_PHY_INIT_DATA_IN_PARTITION`. +One is the default initialization data which is located in the header file :idf_file:`components/esp_wifi/{IDF_TARGET_PATH_NAME}/include/phy_init_data.h`. -Another is the initialization data which is stored in a partition. -When using a custom partition table, make sure that PHY data partition is included (type: `data`, subtype: `phy`). -With default partition table, this is done automatically. -If initialization data is stored in a partition, it has to be flashed there, otherwise runtime error will occur. +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_ESP32_PHY_INIT_DATA_IN_PARTITION`. + +Another is the initialization data which is stored in a partition. +When using a custom partition table, make sure that PHY data partition is included (type: `data`, subtype: `phy`). +With default partition table, this is done automatically. +If initialization data is stored in a partition, it has to be flashed there, otherwise runtime error will occur. To switch to the initialization data stored in a partition, go to ``menuconfig`` and enable :ref:`CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION`. diff --git a/docs/en/api-guides/app_trace.rst b/docs/en/api-guides/app_trace.rst index 71ecdf501..dd95b985b 100644 --- a/docs/en/api-guides/app_trace.rst +++ b/docs/en/api-guides/app_trace.rst @@ -5,7 +5,7 @@ Application Level Tracing library Overview -------- -IDF provides useful feature for program behavior analysis: application level tracing. It is implemented in the corresponding library and can be enabled in menuconfig. This feature allows to transfer arbitrary data between host and ESP32 via JTAG interface with small overhead on program execution. +IDF provides useful feature for program behavior analysis: application level tracing. It is implemented in the corresponding library and can be enabled in menuconfig. This feature allows to transfer arbitrary data between host and {IDF_TARGET_NAME} via JTAG interface with small overhead on program execution. Developers can use this library to send application specific state of execution to the host and receive commands or other type of info in the opposite direction at runtime. The main use cases of this library are: @@ -31,7 +31,7 @@ The library supports two modes of operation: **Post-mortem mode**. This is the default mode. The mode does not need interaction with the host side. In this mode tracing module does not check whether host has read all the data from *HW UP BUFFER* buffer and overwrites old data with the new ones. This mode is useful when only the latest trace data are interesting to the user, e.g. for analyzing program's behavior just before the crash. Host can read the data later on upon user request, e.g. via special OpenOCD command in case of working via JTAG interface. -**Streaming mode.** Tracing module enters this mode when host connects to ESP32. In this mode before writing new data to *HW UP BUFFER* tracing module checks that there is enough space in it and if necessary waits for the host to read data and free enough memory. Maximum waiting time is controlled via timeout values passed by users to corresponding API routines. So when application tries to write data to trace buffer using finite value of the maximum waiting time it is possible situation that this data will be dropped. Especially this is true for tracing from time critical code (ISRs, OS scheduler code etc.) when infinite timeouts can lead to system malfunction. In order to avoid loss of such critical data developers can enable additional data buffering via menuconfig option :ref:`CONFIG_APPTRACE_PENDING_DATA_SIZE_MAX`. This macro specifies the size of data which can be buffered in above conditions. The option can also help to overcome situation when data transfer to the host is temporarily slowed down, e.g due to USB bus congestions etc. But it will not help when average bitrate of trace data stream exceeds HW interface capabilities. +**Streaming mode.** Tracing module enters this mode when host connects to {IDF_TARGET_NAME}. In this mode before writing new data to *HW UP BUFFER* tracing module checks that there is enough space in it and if necessary waits for the host to read data and free enough memory. Maximum waiting time is controlled via timeout values passed by users to corresponding API routines. So when application tries to write data to trace buffer using finite value of the maximum waiting time it is possible situation that this data will be dropped. Especially this is true for tracing from time critical code (ISRs, OS scheduler code etc.) when infinite timeouts can lead to system malfunction. In order to avoid loss of such critical data developers can enable additional data buffering via menuconfig option :ref:`CONFIG_APPTRACE_PENDING_DATA_SIZE_MAX`. This macro specifies the size of data which can be buffered in above conditions. The option can also help to overcome situation when data transfer to the host is temporarily slowed down, e.g due to USB bus congestions etc. But it will not help when average bitrate of trace data stream exceeds HW interface capabilities. Configuration Options and Dependencies @@ -55,7 +55,7 @@ There are two additional menuconfig options not mentioned above: How to use this library ----------------------- -This library provides API for transferring arbitrary data between host and ESP32. When enabled in menuconfig target application tracing module is initialized automatically at the system startup, so all what the user needs to do is to call corresponding API to send, receive or flush the data. +This library provides API for transferring arbitrary data between host and {IDF_TARGET_NAME}. When enabled in menuconfig target application tracing module is initialized automatically at the system startup, so all what the user needs to do is to call corresponding API to send, receive or flush the data. .. _app_trace-application-specific-tracing: @@ -192,7 +192,7 @@ Start command syntax: ``outfile`` Path to file to save data from both CPUs. This argument should have the following format: ``file://path/to/file``. ``poll_period`` - Data polling period (in ms) for available trace data. If greater than 0 then command runs in non-blocking mode. By default 1 ms. + Data polling period (in ms) for available trace data. If greater than 0 then command runs in non-blocking mode. By default 1 ms. ``trace_size`` Maximum size of data to collect (in bytes). Tracing is stopped after specified amount of data is received. By default -1 (trace size stop trigger is disabled). ``stop_tmo`` @@ -216,7 +216,7 @@ Command usage examples: esp32 apptrace start file://trace.log 1 2048 5 0 0 - The tracing data will be retrieved and saved in non-blocking mode. This process will stop automatically after 2048 bytes are collected, or if no data are available for more than 5 seconds. + The tracing data will be retrieved and saved in non-blocking mode. This process will stop automatically after 2048 bytes are collected, or if no data are available for more than 5 seconds. .. note:: @@ -326,7 +326,7 @@ How To Use It Support for this feature is enabled by *Component config > Application Level Tracing > FreeRTOS SystemView Tracing* (:ref:`CONFIG_SYSVIEW_ENABLE`) menuconfig option. There are several other options enabled under the same menu: -1. *ESP32 timer to use as SystemView timestamp source* (:ref:`CONFIG_SYSVIEW_TS_SOURCE`) selects the source of timestamps for SystemView events. In single core mode timestamps are generated using ESP32 internal cycle counter running at maximum 240 Mhz (~4 ns granularity). In dual-core mode external timer working at 40 Mhz is used, so timestamp granularity is 25 ns. +1. {IDF_TARGET_NAME} timer to use as SystemView timestamp source: (:ref:`CONFIG_SYSVIEW_TS_SOURCE`) selects the source of timestamps for SystemView events. In single core mode timestamps are generated using {IDF_TARGET_NAME} internal cycle counter running at maximum 240 Mhz (~4 ns granularity). In dual-core mode external timer working at 40 Mhz is used, so timestamp granularity is 25 ns. 2. Individually enabled or disabled collection of SystemView events (``CONFIG_SYSVIEW_EVT_XXX``): - Trace Buffer Overflow Event @@ -340,7 +340,7 @@ Support for this feature is enabled by *Component config > Application Level Tra - Task Create Event - Task Terminate Event - System Idle Event - - Timer Enter Event + - Timer Enter Event - Timer Exit Event IDF has all the code required to produce SystemView compatible traces, so user can just configure necessary project options (see above), build, download the image to target and use OpenOCD to collect data as described in the previous sections. @@ -371,7 +371,7 @@ Start command syntax: ``outfile2`` Path to file to save data from APP CPU. This argument should have the following format: ``file://path/to/file``. ``poll_period`` - Data polling period (in ms) for available trace data. If greater then 0 then command runs in non-blocking mode. By default 1 ms. + Data polling period (in ms) for available trace data. If greater then 0 then command runs in non-blocking mode. By default 1 ms. ``trace_size`` Maximum size of data to collect (in bytes). Tracing is stopped after specified amount of data is received. By default -1 (trace size stop trigger is disabled). ``stop_tmo`` @@ -405,7 +405,7 @@ Command usage examples: Data Visualization """""""""""""""""" -After trace data are collected user can use special tool to visualize the results and inspect behavior of the program. Unfortunately SystemView does not support tracing from multiple cores. So when tracing from ESP32 working in dual-core mode two files are generated: one for PRO CPU and another one for APP CPU. User can load every file into separate instance of the tool. +After trace data are collected user can use special tool to visualize the results and inspect behavior of the program. Unfortunately SystemView does not support tracing from multiple cores. So when tracing from {IDF_TARGET_NAME} working in dual-core mode two files are generated: one for PRO CPU and another one for APP CPU. User can load every file into separate instance of the tool. It is uneasy and awkward to analyze data for every core in separate instance of the tool. Fortunately there is Eclipse plugin called *Impulse* which can load several trace files and makes it possible to inspect events from both cores in one view. Also this plugin has no limitation of 1,000,000 events as compared to free version of SystemView. @@ -501,7 +501,7 @@ The dumping of coverage data is done via OpenOCD (see :doc:`JTAG Debugging <../a When the target dumps code coverage data, the ``.gcda`` files are stored in the project's build directory. For example, if ``gcov_example_main.c`` of the ``main`` component was compiled with the ``--coverage`` option, then dumping the code coverage data would generate a ``gcov_example_main.gcda`` in ``build/esp-idf/main/CMakeFiles/__idf_main.dir/gcov_example_main.c.gcda`` (or ``build/main/gcov_example_main.gcda`` if using the legacy Make build system). Note that the ``.gcno`` files produced during compilation are also placed in the same directory. -The dumping of code coverage data can be done multiple times throughout an application's life time. Each dump will simply update the ``.gcda`` file with the newest code coverage information. Code coverage data is accumulative, thus the newest data will contain the total execution count of each code path over the application's entire lifetime. +The dumping of code coverage data can be done multiple times throughout an application's life time. Each dump will simply update the ``.gcda`` file with the newest code coverage information. Code coverage data is accumulative, thus the newest data will contain the total execution count of each code path over the application's entire lifetime. ESP-IDF supports two methods of dumping code coverage data form the target to the host: @@ -511,15 +511,12 @@ ESP-IDF supports two methods of dumping code coverage data form the target to th Instant Run-Time Dump ~~~~~~~~~~~~~~~~~~~~~ -An Instant Run-Time Dump is triggered by calling the ``esp32 gcov`` OpenOCD command (via a telnet session). Once called, OpenOCD will immediately preempt the ESP32's current state and execute a builtin IDF Gcov debug stub function. The debug stub function will handle the dumping of data to the Host. Upon completion, the ESP32 will resume it's current state. - -.. note:: - Due to the use of the debug stub function, the OpenOCD Debug Stub option must be enabled in project configuration. The option can be found under ``Component config -> ESP32-specific -> OpenOCD debug stubs``. +An Instant Run-Time Dump is triggered by calling the ``esp32 gcov`` OpenOCD command (via a telnet session). Once called, OpenOCD will immediately preempt the {IDF_TARGET_NAME}'s current state and execute a builtin IDF Gcov debug stub function. The debug stub function will handle the dumping of data to the Host. Upon completion, the {IDF_TARGET_NAME} will resume it's current state. Hard-coded Dump ~~~~~~~~~~~~~~~ -A Hard-coded Dump is triggered by the application itself by calling :cpp:func:`esp_gcov_dump` from somewhere within the application. When called, the application will halt and wait for OpenOCD to connect and retrieve the code coverage data. Once :cpp:func:`esp_gcov_dump` is called, the Host must execute the ``esp32 gcov dump`` OpenOCD command (via a telnet session). The ``esp32 gcov dump`` command will cause OpenOCD to connect to the ESP32, retrieve the code coverage data, then disconnect from the ESP32 thus allowing the application to resume. Hard-coded Dumps can also be triggered multiple times throughout an application's lifetime. +A Hard-coded Dump is triggered by the application itself by calling :cpp:func:`esp_gcov_dump` from somewhere within the application. When called, the application will halt and wait for OpenOCD to connect and retrieve the code coverage data. Once :cpp:func:`esp_gcov_dump` is called, the Host must execute the ``esp32 gcov dump`` OpenOCD command (via a telnet session). The ``esp32 gcov dump`` command will cause OpenOCD to connect to the {IDF_TARGET_NAME}, retrieve the code coverage data, then disconnect from the {IDF_TARGET_NAME} thus allowing the application to resume. Hard-coded Dumps can also be triggered multiple times throughout an application's lifetime. Hard-coded dumps are useful if code coverage data is required at certain points of an application's lifetime by placing :cpp:func:`esp_gcov_dump` where necessary (e.g., after application initialization, during each iteration of an application's main loop). diff --git a/docs/en/api-guides/blufi.rst b/docs/en/api-guides/blufi.rst index 97b04dff2..81eb66bbf 100644 --- a/docs/en/api-guides/blufi.rst +++ b/docs/en/api-guides/blufi.rst @@ -4,7 +4,7 @@ BluFi Overview -------- -The BluFi for ESP32 is a Wi-Fi network configuration function via Bluetooth channel. It provides a secure protocol to pass Wi-Fi configuration and credentials to the ESP32. Using this information ESP32 can then e.g. connect to an AP or establish a SoftAP. +The BluFi for {IDF_TARGET_NAME} is a Wi-Fi network configuration function via Bluetooth channel. It provides a secure protocol to pass Wi-Fi configuration and credentials to the {IDF_TARGET_NAME}. Using this information {IDF_TARGET_NAME} can then e.g. connect to an AP or establish a SoftAP. Fragmenting, data encryption, checksum verification in the BluFi layer are the key elements of this process. @@ -16,29 +16,29 @@ The BluFi networking flow includes the configuration of the SoftAP and Station. The following uses Station as an example to illustrate the core parts of the procedure, including broadcast, connection, service discovery, negotiation of the shared key, data transmission, connection status backhaul. -1. Set the ESP32 into GATT Server mode and then it will send broadcasts with specific *advertising data*. You can customize this broadcast as needed, which is not a part of the BluFi Profile. +1. Set the {IDF_TARGET_NAME} into GATT Server mode and then it will send broadcasts with specific *advertising data*. You can customize this broadcast as needed, which is not a part of the BluFi Profile. -2. Use the App installed on the mobile phone to search for this particular broadcast. The mobile phone will connect to ESP32 as the GATT Client once the broadcast is confirmed. The App used during this part is up to you. +2. Use the App installed on the mobile phone to search for this particular broadcast. The mobile phone will connect to {IDF_TARGET_NAME} as the GATT Client once the broadcast is confirmed. The App used during this part is up to you. -3. After the GATT connection is successfully established, the mobile phone will send a data frame for key negotiation to ESP32 (see the section :ref:`frame_formats` for details). +3. After the GATT connection is successfully established, the mobile phone will send a data frame for key negotiation to {IDF_TARGET_NAME} (see the section :ref:`frame_formats` for details). -4. After ESP32 receives the data frame of key negotiation, it will parse the content according to the user-defined negotiation method. +4. After {IDF_TARGET_NAME} receives the data frame of key negotiation, it will parse the content according to the user-defined negotiation method. -5. The mobile phone works with ESP32 for key negotiation using the encryption algorithms such as DH, RSA or ECC. +5. The mobile phone works with {IDF_TARGET_NAME} for key negotiation using the encryption algorithms such as DH, RSA or ECC. -6. After the negotiation process is completed, the mobile phone will send a control frame for security-mode setup to ESP32. +6. After the negotiation process is completed, the mobile phone will send a control frame for security-mode setup to {IDF_TARGET_NAME}. -7. When receiving this control frame, ESP32 will be able to encrypt and decrypt the communication data using the shared key and the security configuration. +7. When receiving this control frame, {IDF_TARGET_NAME} will be able to encrypt and decrypt the communication data using the shared key and the security configuration. -8. The mobile phone sends the data frame defined in the section of :ref:`frame_formats`，with the Wi-Fi configuration information to ESP32, including SSID, password, etc. +8. The mobile phone sends the data frame defined in the section of :ref:`frame_formats`，with the Wi-Fi configuration information to {IDF_TARGET_NAME}, including SSID, password, etc. -9. The mobile phone sends a control frame of Wi-Fi connection request to ESP32. When receiving this control frame, ESP32 will regard the communication of essential information as done and get ready to connect to the Wi-Fi. +9. The mobile phone sends a control frame of Wi-Fi connection request to {IDF_TARGET_NAME}. When receiving this control frame, {IDF_TARGET_NAME} will regard the communication of essential information as done and get ready to connect to the Wi-Fi. -10. After connecting to the Wi-Fi, ESP32 will send a control frame of Wi-Fi connection status report to the mobile phone，to report the connection status. At this point the networking procedure is completed. +10. After connecting to the Wi-Fi, {IDF_TARGET_NAME} will send a control frame of Wi-Fi connection status report to the mobile phone，to report the connection status. At this point the networking procedure is completed. .. note:: - 1. After ESP32 receives the control frame of security-mode configuration, it will execute the operations in accordance with the defined security mode. + 1. After {IDF_TARGET_NAME} receives the control frame of security-mode configuration, it will execute the operations in accordance with the defined security mode. 2. The data lengths before and after symmetric encryption/decryption must stay the same. It also supports in-place encryption and decryption. @@ -55,18 +55,18 @@ The flow chart of BluFi node_height = 60; edge_length = 380; span_height = 10; - default_fontsize = 12; + default_fontsize = 12; - Phone <- ESP32 [label="Advertising"]; - Phone -> ESP32 [label="Create GATT connection"]; - Phone <- ESP32 [label="Negotiate key procedure"]; - Phone -> ESP32 [label="Negotiate key procedure"]; - Phone -> ESP32 [label="CTRL: Set ESP32 to Phone Security mode"]; - Phone -> ESP32 [label="DATA: SSID"]; - Phone -> ESP32 [label="DATA: Password"]; - Phone -> ESP32 [label="DATA: Other information, such as CA certification"]; - Phone -> ESP32 [label="CTRL: Connect to AP"]; - Phone <- ESP32 [label="DATA: Connection State Report"]; + Phone <- {IDF_TARGET_NAME} [label="Advertising"]; + Phone -> {IDF_TARGET_NAME} [label="Create GATT connection"]; + Phone <- {IDF_TARGET_NAME} [label="Negotiate key procedure"]; + Phone -> {IDF_TARGET_NAME} [label="Negotiate key procedure"]; + Phone -> {IDF_TARGET_NAME} [label="CTRL: Set {IDF_TARGET_NAME} to Phone Security mode"]; + Phone -> {IDF_TARGET_NAME} [label="DATA: SSID"]; + Phone -> {IDF_TARGET_NAME} [label="DATA: Password"]; + Phone -> {IDF_TARGET_NAME} [label="DATA: Other information, such as CA certification"]; + Phone -> {IDF_TARGET_NAME} [label="CTRL: Connect to AP"]; + Phone <- {IDF_TARGET_NAME} [label="DATA: Connection State Report"]; } .. _frame_formats: @@ -74,7 +74,7 @@ The flow chart of BluFi The Frame Formats Defined in BluFi ----------------------------------- -The frame formats for the communication between the mobile phone App and ESP32 are defined as follows: +The frame formats for the communication between the mobile phone App and {IDF_TARGET_NAME} are defined as follows: The frame format with no fragment (8 bit)： @@ -144,8 +144,8 @@ The format of Ack Frame（8 bit）： * The control frame is not encrypted for the time being and supports to be verified; * The data frame supports to be encrypted and verified. - - **1.1 Control Frame (0x0 b’00)** + + **1.1 Control Frame (0x0 b’00)** +-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+ | Control Frame (Binary) | Implication | Explanation | Note | @@ -391,8 +391,8 @@ The format of Ack Frame（8 bit）： This field takes 2 bytes that is used to check "sequence + data length + clear text data". -The Security Implementation of ESP32 -------------------------------------- +The Security Implementation of {IDF_TARGET_NAME} +------------------------------------------------ 1. Securing data @@ -410,15 +410,15 @@ The Security Implementation of ESP32 It is added to the Sequence field and used during the checksum verification. - For the coding of ESP32, you can determine and develop the security processing, such as key negotiation. The mobile application sends the negotiation data to ESP32 and then the data will be sent to the application layer for processing. If the application layer does not process it, you can use the DH encryption algorithm provided by BluFi to negotiate the key. - + For the coding of {IDF_TARGET_NAME}, you can determine and develop the security processing, such as key negotiation. The mobile application sends the negotiation data to {IDF_TARGET_NAME} and then the data will be sent to the application layer for processing. If the application layer does not process it, you can use the DH encryption algorithm provided by BluFi to negotiate the key. + The application layer needs to register several security-related functions to BluFi: -.. code-block:: c +.. code-block:: c typedef void (*esp_blufi_negotiate_data_handler_t)(uint8_t *data, int len, uint8_t **output_data, int *output_len, bool *need_free) -This function is for ESP32 to receive normal data during negotiation, and after processing is completed, the data will be transmitted using Output_data and Output_len. +This function is for {IDF_TARGET_NAME} to receive normal data during negotiation, and after processing is completed, the data will be transmitted using Output_data and Output_len. BluFi will send output_data from Negotiate_data_handler after Negotiate_data_handler is called. @@ -426,7 +426,7 @@ Here are two "*", because the length of the data to be emitted is unknown that r .. code-block:: c - typedef int (* esp_blufi_encrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int cyprt_len) + typedef int (* esp_blufi_encrypt_func_t)(uint8_t iv8, uint8_t *crypt_data, int cyprt_len) The data to be encrypted and decrypted must use the same length. The IV8 is a 8 bit sequence value of frames, which can be used as a 8 bit of IV. @@ -450,6 +450,6 @@ UUID BluFi Service UUID: 0xFFFF，16 bit -BluFi (the mobile -> ESP32): 0xFF01, writable +BluFi (the mobile -> {IDF_TARGET_NAME}): 0xFF01, writable -Blufi (ESP32 -> the mobile phone): 0xFF02, readable and callable +Blufi ({IDF_TARGET_NAME} -> the mobile phone): 0xFF02, readable and callable diff --git a/docs/en/api-guides/build-system-legacy.rst b/docs/en/api-guides/build-system-legacy.rst index b1ab9eb14..553236f1c 100644 --- a/docs/en/api-guides/build-system-legacy.rst +++ b/docs/en/api-guides/build-system-legacy.rst @@ -22,7 +22,7 @@ Overview An ESP-IDF project can be seen as an amalgamation of a number of components. For example, for a webserver that shows the current humidity, there could be: -- The ESP32 base libraries (libc, rom bindings etc) +- The {IDF_TARGET_NAME} base libraries (libc, rom bindings etc) - The Wi-Fi drivers - A TCP/IP stack - The FreeRTOS operating system @@ -107,7 +107,7 @@ Minimal Example Makefile :: PROJECT_NAME := myProject - + include $(IDF_PATH)/make/project.mk @@ -150,10 +150,10 @@ Running the ``make list-components`` target dumps many of these variables and ca Multiple components with the same name ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -When esp-idf is collecting all the components to compile, it will do this in the order specified by ``COMPONENT_DIRS``; by default, this means the +When esp-idf is collecting all the components to compile, it will do this in the order specified by ``COMPONENT_DIRS``; by default, this means the idf components first, the project components second and optionally the components in ``EXTRA_COMPONENT_DIRS`` last. If two or more of these directories -contain component subdirectories with the same name, the component in the last place searched is used. This allows, for example, overriding esp-idf components -with a modified version by simply copying the component from the esp-idf component directory to the project component tree and then modifying it there. +contain component subdirectories with the same name, the component in the last place searched is used. This allows, for example, overriding esp-idf components +with a modified version by simply copying the component from the esp-idf component directory to the project component tree and then modifying it there. If used in this way, the esp-idf directory itself can remain untouched. Minimal Component Makefile @@ -191,7 +191,7 @@ The following variables are set at the project level, but exported for use in th - ``HOSTCC``, ``HOSTLD``, ``HOSTAR``: Full names of each tool from the host native toolchain. - ``IDF_VER``: ESP-IDF version, retrieved from either ``$(IDF_PATH)/version.txt`` file (if present) else using git command ``git describe``. Recommended format here is single liner that specifies major IDF release version, e.g. ``v2.0`` for a tagged release or ``v2.0-275-g0efaa4f`` for an arbitrary commit. Application can make use of this by calling :cpp:func:`esp_get_idf_version`. - ``IDF_VERSION_MAJOR``, ``IDF_VERSION_MINOR``, ``IDF_VERSION_PATCH``: Components of ESP-IDF version, to be used in conditional expressions. Note that this information is less precise than that provided by ``IDF_VER`` variable. ``v4.0-dev-*``, ``v4.0-beta1``, ``v4.0-rc1`` and ``v4.0`` will all have the same values of ``ESP_IDF_VERSION_*`` variables, but different ``IDF_VER`` values. -- ``PROJECT_VER``: Project version. +- ``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. * Else, if ``PROJECT_VER`` variable is set in project Makefile file, its value will be used. @@ -285,7 +285,7 @@ The following variables can be set inside ``component.mk`` to control the build settings. Component-specific additions can be made via ``CXXFLAGS +=``. It is also possible (although not recommended) to override this variable completely for a component. -- ``COMPONENT_ADD_LDFRAGMENTS``: Paths to linker fragment files for the linker +- ``COMPONENT_ADD_LDFRAGMENTS``: Paths to linker fragment files for the linker script generation functionality. See :doc:`Linker Script Generation `. To apply compilation flags to a single source file, you can add a variable override as a target, ie:: @@ -326,7 +326,7 @@ Top Level: Project Makefile - ``project.mk`` fills in default project-level make variables and includes make variables from the project configuration. If the generated makefile containing project configuration is out of date, then it is regenerated (via targets in ``project_config.mk``) and then the make process restarts from the top. - ``project.mk`` builds a list of components to build, based on the default component directories or a custom list of components set in `optional project variables`. - Each component can set some `optional project-wide component variables`_. These are included via generated makefiles named ``component_project_vars.mk`` - there is one per component. These generated makefiles are included into ``project.mk``. If any are missing or out of date, they are regenerated (via a recursive make call to the component makefile) and then the make process restarts from the top. -- `Makefile.projbuild` files from components are included into the make process, to add extra targets or configuration. +- `Makefile.projbuild` files from components are included into the make process, to add extra targets or configuration. - By default, the project makefile also generates top-level build & clean targets for each component and sets up `app` and `clean` targets to invoke all of these sub-targets. - In order to compile each component, a recursive make is performed for the component makefile. @@ -484,11 +484,11 @@ has the compile_only_if and compile_only_if_not macros: $(call compile_only_if,$(CONFIG_FOO_ENABLE_BAR),bar.o) -As can be seen in the example, the ``compile_only_if`` macro takes a condition and a +As can be seen in the example, the ``compile_only_if`` macro takes a condition and a list of object files as parameters. If the condition is true (in this case: if the BAR feature is enabled in menuconfig) the object files (in this case: bar.o) will -always be compiled. The opposite goes as well: if the condition is not true, bar.o -will never be compiled. ``compile_only_if_not`` does the opposite: compile if the +always be compiled. The opposite goes as well: if the condition is not true, bar.o +will never be compiled. ``compile_only_if_not`` does the opposite: compile if the condition is false, not compile if the condition is true. This can also be used to select or stub out an implementation, as such: @@ -523,12 +523,12 @@ This can also be used to select or stub out an implementation, as such: $(call compile_only_if,$(or $(CONFIG_ENABLE_LCD_CONSOLE),$(CONFIG_ENABLE_LCD_PLOT)), font.o) Note the use of the Make 'or' function to include the font file. Other substitution functions, -like 'and' and 'if' will also work here. Variables that do not come from menuconfig can also -be used: ESP-IDF uses the default Make policy of judging a variable which is empty or contains +like 'and' and 'if' will also work here. Variables that do not come from menuconfig can also +be used: ESP-IDF uses the default Make policy of judging a variable which is empty or contains only whitespace to be false while a variable with any non-whitespace in it is true. (Note: Older versions of this document advised conditionally adding object file names to -``COMPONENT_OBJS``. While this still is possible, this will only work when all object +``COMPONENT_OBJS``. While this still is possible, this will only work when all object files for a component are named explicitely, and will not clean up deselected object files in a ``make clean`` pass.) @@ -596,8 +596,8 @@ For an example of using this technique, see :example:`protocols/https_request` - Code and Data Placements ------------------------ -ESP-IDF has a feature called linker script generation that enables components to define where its code and data will be placed in memory through -linker fragment files. These files are processed by the build system, and is used to augment the linker script used for linking +ESP-IDF has a feature called linker script generation that enables components to define where its code and data will be placed in memory through +linker fragment files. These files are processed by the build system, and is used to augment the linker script used for linking app binary. See :doc:`Linker Script Generation ` for a quick start guide as well as a detailed discussion of the mechanism. diff --git a/docs/en/api-guides/console.rst b/docs/en/api-guides/console.rst index 3f10279db..c04309924 100644 --- a/docs/en/api-guides/console.rst +++ b/docs/en/api-guides/console.rst @@ -14,9 +14,9 @@ These facilities can be used together or independently. For example, it is possi Line editing ------------ -Line editing feature lets users compose commands by typing them, erasing symbols using 'backspace' key, navigating within the command using left/right keys, navigating to previously typed commands using up/down keys, and performing autocompletion using 'tab' key. +Line editing feature lets users compose commands by typing them, erasing symbols using 'backspace' key, navigating within the command using left/right keys, navigating to previously typed commands using up/down keys, and performing autocompletion using 'tab' key. -.. note:: This feature relies on ANSI escape sequence support in the terminal application. As such, serial monitors which display raw UART data can not be used together with the line editing library. If you see ``[6n`` or similar escape sequence when running get_started/console example instead of a command prompt (``[esp32]>``), it means that the serial monitor does not support escape sequences. Programs which are known to work are GNU screen, minicom, and idf_monitor.py (which can be invoked using ``idf.py monitor`` from project directory). +.. note:: This feature relies on ANSI escape sequence support in the terminal application. As such, serial monitors which display raw UART data can not be used together with the line editing library. If you see ``[6n`` or similar escape sequence when running get_started/console example instead of a command prompt (``[{IDF_TARGET_PATH_NAME}]>``), it means that the serial monitor does not support escape sequences. Programs which are known to work are GNU screen, minicom, and idf_monitor.py (which can be invoked using ``idf.py monitor`` from project directory). Here is an overview of functions provided by `linenoise`_ library. diff --git a/docs/en/api-guides/core_dump.rst b/docs/en/api-guides/core_dump.rst index 68f522415..8a6c0427e 100644 --- a/docs/en/api-guides/core_dump.rst +++ b/docs/en/api-guides/core_dump.rst @@ -1,9 +1,15 @@ -ESP32 Core Dump -=============== +{IDF_TARGET_NAME} Core Dump +=========================== Overview -------- +.. only:: esp32s2 + + .. note:: + + The python utility does not currently support ESP32-S2 + ESP-IDF provides support to generate core dumps on unrecoverable software errors. This useful technique allows post-mortem analysis of software state at the moment of failure. Upon the crash system enters panic state, prints some information and halts or reboots depending configuration. User can choose to generate core dump in order to analyse the reason of failure on PC later on. Core dump contains snapshots of all tasks in the system at the moment of failure. Snapshots include tasks control blocks (TCB) and stacks. diff --git a/docs/en/api-guides/deep-sleep-stub.rst b/docs/en/api-guides/deep-sleep-stub.rst index 5cd98144e..28732497e 100644 --- a/docs/en/api-guides/deep-sleep-stub.rst +++ b/docs/en/api-guides/deep-sleep-stub.rst @@ -1,7 +1,7 @@ Deep Sleep Wake Stubs ===================== -ESP32 supports running a "deep sleep wake stub" when coming out of deep sleep. This function runs immediately as soon as the chip wakes up - before any normal initialisation, bootloader, or ESP-IDF code has run. After the wake stub runs, the SoC can go back to sleep or continue to start ESP-IDF normally. +{IDF_TARGET_NAME} supports running a "deep sleep wake stub" when coming out of deep sleep. This function runs immediately as soon as the chip wakes up - before any normal initialisation, bootloader, or ESP-IDF code has run. After the wake stub runs, the SoC can go back to sleep or continue to start ESP-IDF normally. Deep sleep wake stub code is loaded into "RTC Fast Memory" and any data which it uses must also be loaded into RTC memory. RTC memory regions hold their contents during deep sleep. @@ -33,7 +33,7 @@ It is not necessary to implement ``esp_wake_deep_sleep()`` in your app in order If you want to swap between different deep sleep stubs at runtime, it is also possible to do this by calling the ``esp_set_deep_sleep_wake_stub()`` function. This is not necessary if you only use the default ``esp_wake_deep_sleep()`` function. -All of these functions are declared in the ``esp_deepsleep.h`` header under components/esp32. +All of these functions are declared in the ``esp_sleep.h`` header under components/{IDF_TARGET_PATH_NAME}. Loading Code Into RTC Memory ---------------------------- @@ -69,9 +69,11 @@ The first way is to use the ``RTC_DATA_ATTR`` and ``RTC_RODATA_ATTR`` to specify ets_printf(fmt_str, wake_count++); } -The RTC memory area where this data will be placed can be configured via menuconfig option named ``CONFIG_ESP32_RTCDATA_IN_FAST_MEM``. This option allows to keep slow memory area for ULP programs and 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 (default option). This option depends on the ``CONFIG_FREERTOS_UNICORE`` because RTC fast memory can be accessed only by PRO_CPU. +.. only:: esp32 -The similar attributes ``RTC_FAST_ATTR`` and ``RTC_SLOW_ATTR`` can be used to specify data that will be force placed into RTC_FAST and RTC_SLOW memory respectively. Any access to data marked with ``RTC_FAST_ATTR`` is allowed by PRO_CPU only and it is responsibility of user to make sure about it. + The RTC memory area where this data will be placed can be configured via menuconfig option named ``CONFIG_ESP32_RTCDATA_IN_FAST_MEM``. This option allows to keep slow memory area for ULP programs and 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 (default option). This option depends on the ``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 will be force placed into RTC_FAST and RTC_SLOW memory respectively. Any access to data marked with ``RTC_FAST_ATTR`` is allowed by PRO_CPU only and it is responsibility of user to make sure about it. Unfortunately, any string constants used in this way must be declared as arrays and marked with RTC_RODATA_ATTR, as shown in the example above. diff --git a/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst b/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst index 6fef33dce..55eaddca7 100644 --- a/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst +++ b/docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst @@ -647,8 +647,8 @@ You can find meaning of errors or warnings when they appear at the bottom of ESP The examples use :cpp:func:`ESP_LOG_BUFFER_HEX` to print the message context while the ESP-BLE-MESH protocol stack uses :cpp:func:`bt_hex`. -7.2 Which API can be used to restart ESP32? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +7.2 Which API can be used to restart {IDF_TARGET_NAME}? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The API :cpp:func:`esp_restart`. diff --git a/docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst b/docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst index 231b755a3..3e610a9a6 100644 --- a/docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst +++ b/docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst @@ -14,11 +14,11 @@ Built on top of Zephyr Bluetooth Mesh stack, the ESP-BLE-MESH implementation sup Please see the :doc:`ble-mesh-architecture` for information about the implementation of ESP-BLE-MESH architecture and :doc:`ESP-BLE-MESH API Reference <../../api-reference/bluetooth/esp-ble-mesh>` for information about respective API. -ESP-BLE-MESH is implemented and certified based on the latest Mesh Profile v1.0.1, users can refer `here `_ for the certification details of ESP-BLE-MESH. +ESP-BLE-MESH is implemented and certified based on the latest Mesh Profile v1.0.1, users can refer `here `_ for the certification details of ESP-BLE-MESH. .. note:: - If you are looking for Wi-Fi based implementation of mesh for ESP32, please check another product by Espressif called ESP-MESH. For more information and documentation see :doc:`ESP-MESH <../../api-reference/network/esp_mesh>`. + If you are looking for Wi-Fi based implementation of mesh for {IDF_TARGET_NAME}, please check another product by Espressif called ESP-MESH. For more information and documentation see :doc:`ESP-MESH <../../api-reference/network/esp_mesh>`. .. _getting-started-with-ble-mesh: @@ -26,7 +26,7 @@ ESP-BLE-MESH is implemented and certified based on the latest Mesh Profile v1.0. Getting Started with ESP-BLE-MESH ================================= -This section is intended to help you get started with ESP-BLE-MESH for the hardware based on the ESP32 chip by Espressif. +This section is intended to help you get started with ESP-BLE-MESH for the hardware based on the {IDF_TARGET_NAME} chip by Espressif. We are going to demonstrate process of setting and operation of a small ESP-BLE-MESH network of three nodes. This process will cover device provisioning and node configuration, and then sending on/off commands to Generic OnOff Server Models on specific nodes. @@ -38,14 +38,14 @@ What You Need Hardware: -* Three ESP32 boards, see :ref:`options `. +* Three {IDF_TARGET_NAME} boards, see :ref:`options `. * USB cables to connect the boards. * Computer configured with ESP-IDF. * Mobile phone or tablet running Android or iOS. Software: -* Example application :example:`bluetooth/esp_ble_mesh/ble_mesh_node/onoff_server` code to load to the ESP32 boards. +* Example application :example:`bluetooth/esp_ble_mesh/ble_mesh_node/onoff_server` code to load to the ${IDF_TARGET_NAME} boards. * Mobile App: **nRF Mesh** for Android or iOS. Optionally you can use some other Apps: - `EspBleMesh `_ Android App @@ -219,7 +219,7 @@ ESP-BLE-MESH Examples * ESP-BLE-MESH Fast Provisioning - :example:`Client ` and :example:`Server ` - this example is used for showing how fast provisioning can be used in order to create a mesh network. It takes no more than 60 seconds to provision 100 devices, see :example:`example client code ` and :example:`example server code `. -* :example:`ESP-BLE-MESH and Wi-Fi Coexistence ` - an example that demonstrates the Wi-Fi and Bluetooth (BLE/BR/EDR) coexistence feature of ESP32. Simply put, users can use the Wi-Fi while operating Bluetooth, see :example:`example code `. +* :example:`ESP-BLE-MESH and Wi-Fi Coexistence ` - an example that demonstrates the Wi-Fi and Bluetooth (BLE/BR/EDR) coexistence feature of {IDF_TARGET_NAME}. Simply put, users can use the Wi-Fi while operating Bluetooth, see :example:`example code `. * ESP-BLE-MESH Node Console - an example that implements BLE Mesh node basic features. Within this example a node can be scanned and provisioned by Provisioner and reply to get/set message from Provisioner, see :example:`example node code ` and :example:`example Provisioner code `. diff --git a/docs/en/api-guides/external-ram.rst b/docs/en/api-guides/external-ram.rst index 18eb536b0..2771ded68 100644 --- a/docs/en/api-guides/external-ram.rst +++ b/docs/en/api-guides/external-ram.rst @@ -9,15 +9,15 @@ Support for external RAM Introduction ============ -ESP32 has a few hundred kilobytes of internal RAM, residing on the same die as the rest of the chip components. It can be insufficient for some purposes, so ESP32 has the ability to also use up to 4 MB of external SPI RAM memory. The external memory is incorporated in the memory map and, with certain restrictions, is usable in the same way as internal data RAM. +{IDF_TARGET_NAME} has a few hundred kilobytes of internal RAM, residing on the same die as the rest of the chip components. It can be insufficient for some purposes, so {IDF_TARGET_NAME} has the ability to also use up to 4 MB of external SPI RAM memory. The external memory is incorporated in the memory map and, with certain restrictions, is usable in the same way as internal data RAM. Hardware ======== -ESP32 supports SPI PSRAM connected in parallel with the SPI flash chip. While ESP32 is capable of supporting several types of RAM chips, the ESP32 SDK only supports the ESP-PSRAM32 chip at the moment. +{IDF_TARGET_NAME} supports SPI PSRAM connected in parallel with the SPI flash chip. While {IDF_TARGET_NAME} is capable of supporting several types of RAM chips, ESP-IDF only supports the ESP-PSRAM32 chip at the moment. -The ESP-PSRAM32 chip is a 1.8 V device which can only be used in parallel with a 1.8 V flash component. Make sure to either set the MTDI pin to a high signal level on bootup, or program ESP32 eFuses to always use the VDD_SIO level of 1.8 V. Not doing this can damage the PSRAM and/or flash chip. +The ESP-PSRAM32 chip is a 1.8 V device which can only be used in parallel with a 1.8 V flash component. Make sure to either set the MTDI pin to a high signal level on bootup, or program {IDF_TARGET_NAME} eFuses to always use the VDD_SIO level of 1.8 V. Not doing this can damage the PSRAM and/or flash chip. To connect the ESP-PSRAM32 chip to ESP32D0W*, connect the following signals: @@ -50,10 +50,10 @@ ESP-IDF fully supports the use of external memory in applications. Once the exte .. _external_ram_config_memory_map: -Integrate RAM into the ESP32 memory map ---------------------------------------- +Integrate RAM into the {IDF_TARGET_NAME} memory map +--------------------------------------------------- -Select this option by choosing "Integrate RAM into ESP32 memory map" from :ref:`CONFIG_SPIRAM_USE`. +Select this option by choosing "Integrate RAM into memory map" from :ref:`CONFIG_SPIRAM_USE`. This is the most basic option for external SPI RAM integration. Most likely, you will need another, more advanced option. diff --git a/docs/en/api-guides/fatal-errors.rst b/docs/en/api-guides/fatal-errors.rst index 7cac04253..8dd54b561 100644 --- a/docs/en/api-guides/fatal-errors.rst +++ b/docs/en/api-guides/fatal-errors.rst @@ -38,16 +38,10 @@ For some of the system level checks (interrupt watchdog, cache access error), th In all cases, error cause will be printed in parens. See `Guru Meditation Errors`_ for a list of possible error causes. -.. only:: esp32 - - Subsequent behavior of the panic handler can be set using :ref:`CONFIG_ESP32_PANIC` configuration choice. The available options are: - -.. only:: esp32s2 - - Subsequent behavior of the panic handler can be set using :ref:`CONFIG_ESP32S2_PANIC` configuration choice. The available options are: +Subsequent behavior of the panic handler can be set using :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_PANIC` configuration choice. The available options are: - Print registers and reboot — default option. - + This will print register values at the point of the exception, print the backtrace, and restart the chip. - Print registers and halt @@ -64,18 +58,12 @@ In all cases, error cause will be printed in parens. See `Guru Meditation Errors Behavior of panic handler is affected by two other configuration options. -.. only:: esp32 - - - If :ref:`CONFIG_ESP32_DEBUG_OCDAWARE` is enabled (which is the default), 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. - -.. only:: esp32s2 - - - If :ref:`CONFIG_ESP32S2_DEBUG_OCDAWARE` is enabled (which is the default), 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 :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_DEBUG_OCDAWARE` is enabled (which is the default), 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 :doc:`Core Dump ` feature is enabled, then system state (task stacks and registers) will be dumped either to 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 this option is enabled, the panic handler code is placed in IRAM. This allows the panic handler to run without needing to re-enable cache first. This may be necessary to debug some complex issues with crashes while flash cache is disabled (for example, when writing to SPI flash). The following diagram illustrates panic handler behavior: @@ -84,7 +72,7 @@ The following diagram illustrates panic handler behavior: :scale: 100% :caption: Panic Handler Flowchart (click to enlarge) :align: center - + blockdiag panic-handler { orientation = portrait; edge_layout = flowchart; @@ -126,15 +114,15 @@ The following diagram illustrates panic handler behavior: Register Dump and Backtrace --------------------------- -Unless ``CONFIG_ESP32_PANIC_SILENT_REBOOT`` option is enabled, panic handler prints some of the CPU registers, and the backtrace, to the console:: +Unless ``CONFIG_{IDF_TARGET_CFG_PREFIX}_PANIC_SILENT_REBOOT`` option is enabled, panic handler prints some of the CPU registers, and the backtrace, to the console:: Core 0 register dump: - PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030 - A2 : 0x00000000 A3 : 0x00000001 A4 : 0x00000001 A5 : 0x3ffb50dc - A6 : 0x00000000 A7 : 0x00000001 A8 : 0x00000000 A9 : 0x3ffb5000 - A10 : 0x00000000 A11 : 0x3ffb2bac A12 : 0x40082d1c A13 : 0x06ff1ff8 - A14 : 0x3ffb7078 A15 : 0x00000000 SAR : 0x00000014 EXCCAUSE: 0x0000001d - EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0xffffffff + PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030 + A2 : 0x00000000 A3 : 0x00000001 A4 : 0x00000001 A5 : 0x3ffb50dc + A6 : 0x00000000 A7 : 0x00000001 A8 : 0x00000000 A9 : 0x3ffb5000 + A10 : 0x00000000 A11 : 0x3ffb2bac A12 : 0x40082d1c A13 : 0x06ff1ff8 + A14 : 0x3ffb7078 A15 : 0x00000000 SAR : 0x00000014 EXCCAUSE: 0x0000001d + EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0xffffffff Backtrace: 0x400e14ed:0x3ffb5030 0x400d0802:0x3ffb5050 @@ -149,28 +137,28 @@ Backtrace line contains PC:SP pairs, where PC is the Program Counter and SP is S If :doc:`IDF Monitor ` is used, Program Counter values will be converted to code locations (function name, file name, and line number), and the output will be annotated with additional lines:: Core 0 register dump: - PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030 + PC : 0x400e14ed PS : 0x00060030 A0 : 0x800d0805 A1 : 0x3ffb5030 0x400e14ed: app_main at /Users/user/esp/example/main/main.cpp:36 - A2 : 0x00000000 A3 : 0x00000001 A4 : 0x00000001 A5 : 0x3ffb50dc - A6 : 0x00000000 A7 : 0x00000001 A8 : 0x00000000 A9 : 0x3ffb5000 - A10 : 0x00000000 A11 : 0x3ffb2bac A12 : 0x40082d1c A13 : 0x06ff1ff8 + A2 : 0x00000000 A3 : 0x00000001 A4 : 0x00000001 A5 : 0x3ffb50dc + A6 : 0x00000000 A7 : 0x00000001 A8 : 0x00000000 A9 : 0x3ffb5000 + A10 : 0x00000000 A11 : 0x3ffb2bac A12 : 0x40082d1c A13 : 0x06ff1ff8 0x40082d1c: _calloc_r at /Users/user/esp/esp-idf/components/newlib/syscalls.c:51 - A14 : 0x3ffb7078 A15 : 0x00000000 SAR : 0x00000014 EXCCAUSE: 0x0000001d - EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0xffffffff + A14 : 0x3ffb7078 A15 : 0x00000000 SAR : 0x00000014 EXCCAUSE: 0x0000001d + EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0xffffffff Backtrace: 0x400e14ed:0x3ffb5030 0x400d0802:0x3ffb5050 0x400e14ed: app_main at /Users/user/esp/example/main/main.cpp:36 - 0x400d0802: main_task at /Users/user/esp/esp-idf/components/esp32/cpu_start.c:470 + 0x400d0802: main_task at /Users/user/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/cpu_start.c:470 To find the location where a fatal error has happened, look at the lines which follow the "Backtrace" line. Fatal error location is the top line, and subsequent lines show the call stack. GDB Stub -------- -If ``CONFIG_ESP32_PANIC_GDBSTUB`` option is enabled, panic handler will not reset the chip when fatal error happens. Instead, it will start GDB remote protocol server, commonly referred to as GDB Stub. When this happens, GDB instance running on the host computer can be instructed to connect to the ESP32 UART port. +If ``CONFIG_{IDF_TARGET_CFG_PREFIX}_PANIC_GDBSTUB`` option is enabled, panic handler will not reset the chip when fatal error happens. Instead, it will start GDB remote protocol server, commonly referred to as GDB Stub. When this happens, GDB instance running on the host computer can be instructed to connect to the {IDF_TARGET_NAME} UART port. If :doc:`IDF Monitor ` is used, GDB is started automatically when GDB Stub prompt is detected on the UART. The output would look like this:: @@ -181,7 +169,7 @@ If :doc:`IDF Monitor ` is used, GDB is started automatically This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Type "show copying" and "show warranty" for details. - This GDB was configured as "--host=x86_64-build_apple-darwin16.3.0 --target=xtensa-esp32-elf". + This GDB was configured as "--host=x86_64-build_apple-darwin16.3.0 --target=xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf". Type "show configuration" for configuration details. For bug reporting instructions, please see: . @@ -194,7 +182,7 @@ If :doc:`IDF Monitor ` is used, GDB is started automatically 0x400e1b41 in app_main () at /Users/user/esp/example/main/main.cpp:36 36 *((int*) 0) = 0; - (gdb) + (gdb) GDB prompt can be used to inspect CPU registers, local and static variables, and arbitrary locations in memory. It is not possible to set breakpoints, change PC, or continue execution. To reset the program, exit GDB and perform external reset: Ctrl-T Ctrl-R in IDF Monitor, or using external reset button on the development board. @@ -219,10 +207,10 @@ Most common reasons for this error include: - FreeRTOS task function has returned. In FreeRTOS, if task function needs to terminate, it should call :cpp:func:`vTaskDelete` function and delete itself, instead of returning. - Failure to load next instruction from SPI flash. This usually happens if: - + - Application has reconfigured SPI flash pins as some other function (GPIO, UART, etc.). Consult Hardware Design Guidelines and the Datasheet for the chip or module for details about SPI flash pins. - - - Some external device was accidentally connected to SPI flash pins, and has interfered with communication between ESP32 and SPI flash. + + - Some external device was accidentally connected to SPI flash pins, and has interfered with communication between {IDF_TARGET_NAME} and SPI flash. InstrFetchProhibited @@ -277,13 +265,7 @@ Other Fatal Errors Brownout ^^^^^^^^ -.. only:: esp32 - - ESP32 has a built-in brownout detector, which is enabled by default. Brownout detector can trigger system reset if supply voltage goes below safe level. Brownout detector can be configured using :ref:`CONFIG_ESP32_BROWNOUT_DET` and :ref:`CONFIG_ESP32_BROWNOUT_DET_LVL_SEL` options. - -.. only:: esp32s2 - - ESP32-S2 has a built-in brownout detector, which is enabled by default. Brownout detector can trigger system reset if supply voltage goes below safe level. Brownout detector can be configured using :ref:`CONFIG_ESP32S2_BROWNOUT_DET` and :ref:`CONFIG_ESP32S2_BROWNOUT_DET_LVL_SEL` options. +{IDF_TARGET_NAME} has a built-in brownout detector, which is enabled by default. Brownout detector can trigger system reset if supply voltage goes below safe level. Brownout detector can be configured using :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_BROWNOUT_DET` and :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_BROWNOUT_DET_LVL_SEL` options. When brownout detector triggers, the following message is printed:: diff --git a/docs/en/api-guides/freertos-smp.rst b/docs/en/api-guides/freertos-smp.rst index f4386ebab..5f99a88a0 100644 --- a/docs/en/api-guides/freertos-smp.rst +++ b/docs/en/api-guides/freertos-smp.rst @@ -4,76 +4,80 @@ ESP-IDF FreeRTOS SMP Changes Overview -------- -The vanilla FreeRTOS is designed to run on a single core. However the ESP32 is -dual core containing a Protocol CPU (known as **CPU 0** or **PRO_CPU**) and an -Application CPU (known as **CPU 1** or **APP_CPU**). The two cores are -identical in practice and share the same memory. This allows the two cores to -run tasks interchangeably between them. +.. only:: esp32 -The ESP-IDF FreeRTOS is a modified version of vanilla FreeRTOS which supports -symmetric multiprocessing (SMP). ESP-IDF FreeRTOS is based on the Xtensa port -of FreeRTOS v8.2.0. This guide outlines the major differences between vanilla -FreeRTOS and ESP-IDF FreeRTOS. The API reference for vanilla FreeRTOS can be + The vanilla FreeRTOS is designed to run on a single core. However the ESP32 is + dual core containing a Protocol CPU (known as **CPU 0** or **PRO_CPU**) and an + Application CPU (known as **CPU 1** or **APP_CPU**). The two cores are + identical in practice and share the same memory. This allows the two cores to + run tasks interchangeably between them. + +The ESP-IDF FreeRTOS is a modified version of vanilla FreeRTOS which supports +symmetric multiprocessing (SMP). ESP-IDF FreeRTOS is based on the Xtensa port +of FreeRTOS v8.2.0. This guide outlines the major differences between vanilla +FreeRTOS and ESP-IDF FreeRTOS. The API reference for vanilla FreeRTOS can be found via http://www.freertos.org/a00106.html For information regarding features that are exclusive to ESP-IDF FreeRTOS, see :doc:`ESP-IDF FreeRTOS Additions<../api-reference/system/freertos_additions>`. -:ref:`backported-features`: Although ESP-IDF FreeRTOS is based on the Xtensa +:ref:`backported-features`: Although ESP-IDF FreeRTOS is based on the Xtensa port of FreeRTOS v8.2.0, a number of FreeRTOS v9.0.0 features have been backported to ESP-IDF. -:ref:`tasks-and-task-creation`: Use :cpp:func:`xTaskCreatePinnedToCore` or -:cpp:func:`xTaskCreateStaticPinnedToCore` to create tasks in ESP-IDF FreeRTOS. The -last parameter of the two functions is ``xCoreID``. This parameter specifies -which core the task is pinned to. Acceptable values are ``0`` for **PRO_CPU**, -``1`` for **APP_CPU**, or ``tskNO_AFFINITY`` which allows the task to run on -both. +.. only:: esp32 -:ref:`round-robin-scheduling`: The ESP-IDF FreeRTOS scheduler will skip tasks when -implementing Round-Robin scheduling between multiple tasks in the Ready state -that are of the same priority. To avoid this behavior, ensure that those tasks either -enter a blocked state, or are distributed across a wider range of priorities. + :ref:`tasks-and-task-creation`: Use :cpp:func:`xTaskCreatePinnedToCore` or + :cpp:func:`xTaskCreateStaticPinnedToCore` to create tasks in ESP-IDF FreeRTOS. The + last parameter of the two functions is ``xCoreID``. This parameter specifies + which core the task is pinned to. Acceptable values are ``0`` for **PRO_CPU**, + ``1`` for **APP_CPU**, or ``tskNO_AFFINITY`` which allows the task to run on + both. -:ref:`scheduler-suspension`: Suspending the scheduler in ESP-IDF FreeRTOS will only -affect the scheduler on the the calling core. In other words, calling -:cpp:func:`vTaskSuspendAll` on **PRO_CPU** will not prevent **APP_CPU** from scheduling, and -vice versa. Use critical sections or semaphores instead for simultaneous -access protection. + :ref:`round-robin-scheduling`: The ESP-IDF FreeRTOS scheduler will skip tasks when + implementing Round-Robin scheduling between multiple tasks in the Ready state + that are of the same priority. To avoid this behavior, ensure that those tasks either + enter a blocked state, or are distributed across a wider range of priorities. -:ref:`tick-interrupt-synchronicity`: Tick interrupts of **PRO_CPU** and **APP_CPU** -are not synchronized. Do not expect to use :cpp:func:`vTaskDelay` or -:cpp:func:`vTaskDelayUntil` as an accurate method of synchronizing task execution -between the two cores. Use a counting semaphore instead as their context -switches are not tied to tick interrupts due to preemption. + :ref:`scheduler-suspension`: Suspending the scheduler in ESP-IDF FreeRTOS will only + affect the scheduler on the the calling core. In other words, calling + :cpp:func:`vTaskSuspendAll` on **PRO_CPU** will not prevent **APP_CPU** from scheduling, and + vice versa. Use critical sections or semaphores instead for simultaneous + access protection. -:ref:`critical-sections`: In ESP-IDF FreeRTOS, critical sections are implemented using -mutexes. Entering critical sections involve taking a mutex, then disabling the -scheduler and interrupts of the calling core. However the other core is left -unaffected. If the other core attemps to take same mutex, it will spin until -the calling core has released the mutex by exiting the critical section. + :ref:`tick-interrupt-synchronicity`: Tick interrupts of **PRO_CPU** and **APP_CPU** + are not synchronized. Do not expect to use :cpp:func:`vTaskDelay` or + :cpp:func:`vTaskDelayUntil` as an accurate method of synchronizing task execution + between the two cores. Use a counting semaphore instead as their context + switches are not tied to tick interrupts due to preemption. -:ref:`floating-points`: The ESP32 supports hardware acceleration of single -precision floating point arithmetic (``float``). However the use of hardware -acceleration leads to some behavioral restrictions in ESP-IDF FreeRTOS. -Therefore, tasks that utilize ``float`` will automatically be pinned to a core if -not done so already. Furthermore, ``float`` cannot be used in interrupt service -routines. + :ref:`critical-sections`: In ESP-IDF FreeRTOS, critical sections are implemented using + mutexes. Entering critical sections involve taking a mutex, then disabling the + scheduler and interrupts of the calling core. However the other core is left + unaffected. If the other core attemps to take same mutex, it will spin until + the calling core has released the mutex by exiting the critical section. -:ref:`task-deletion`: Task deletion behavior has been backported from FreeRTOS -v9.0.0 and modified to be SMP compatible. Task memory will be freed immediately -when :cpp:func:`vTaskDelete` is called to delete a task that is not currently running -and not pinned to the other core. Otherwise, freeing of task memory will still + :ref:`floating-points`: The {IDF_TARGET_NAME} supports hardware acceleration of single + precision floating point arithmetic (``float``). However the use of hardware + acceleration leads to some behavioral restrictions in ESP-IDF FreeRTOS. + Therefore, tasks that utilize ``float`` will automatically be pinned to a core if + not done so already. Furthermore, ``float`` cannot be used in interrupt service + routines. + +:ref:`task-deletion`: Task deletion behavior has been backported from FreeRTOS +v9.0.0 and modified to be SMP compatible. Task memory will be freed immediately +when :cpp:func:`vTaskDelete` is called to delete a task that is not currently running +and not pinned to the other core. Otherwise, freeing of task memory will still be delegated to the Idle Task. -:ref:`deletion-callbacks`: ESP-IDF FreeRTOS has backported the Thread Local +:ref:`deletion-callbacks`: ESP-IDF FreeRTOS has backported the Thread Local Storage Pointers (TLSP) feature. However the extra feature of Deletion Callbacks has been added. Deletion callbacks are called automatically during task deletion and are -used to free memory pointed to by TLSP. Call +used to free memory pointed to by TLSP. Call :cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback()` to set TLSP and Deletion Callbacks. -:ref:`esp-idf-freertos-configuration`: Several aspects of ESP-IDF FreeRTOS can be +:ref:`esp-idf-freertos-configuration`: Several aspects of ESP-IDF FreeRTOS can be set in the project configuration (``idf.py menuconfig``) such as running ESP-IDF in Unicore (single core) Mode, or configuring the number of Thread Local Storage Pointers each task will have. @@ -89,9 +93,9 @@ The following features have been backported from FreeRTOS v9.0.0 to ESP-IDF. Static Alocation ^^^^^^^^^^^^^^^^^ -This feature has been backported from FreeRTOS v9.0.0 to ESP-IDF. The +This feature has been backported from FreeRTOS v9.0.0 to ESP-IDF. The :ref:`CONFIG_FREERTOS_SUPPORT_STATIC_ALLOCATION` option must be enabled in `menuconfig` -in order for static allocation functions to be available. Once enabled, the +in order for static allocation functions to be available. Once enabled, the following functions can be called... - :cpp:func:`xTaskCreateStatic` (see :ref:`backporting-notes` below) @@ -119,32 +123,34 @@ Other Features Backporting Notes ^^^^^^^^^^^^^^^^^ -**1)** :cpp:func:`xTaskCreateStatic` has been made SMP compatible in a similar -fashion to :cpp:func:`xTaskCreate` (see :ref:`tasks-and-task-creation`). Therefore +**1)** :cpp:func:`xTaskCreateStatic` has been made SMP compatible in a similar +fashion to :cpp:func:`xTaskCreate` (see :ref:`tasks-and-task-creation`). Therefore :cpp:func:`xTaskCreateStaticPinnedToCore` can also be called. -**2)** Although vanilla FreeRTOS allows the Timer feature's daemon task to -be statically allocated, the daemon task is always dynamically allocated in -ESP-IDF. Therefore ``vApplicationGetTimerTaskMemory`` **does not** need to be +**2)** Although vanilla FreeRTOS allows the Timer feature's daemon task to +be statically allocated, the daemon task is always dynamically allocated in +ESP-IDF. Therefore ``vApplicationGetTimerTaskMemory`` **does not** need to be defined when using statically allocated timers in ESP-IDF FreeRTOS. **3)** The Thread Local Storage Pointer feature has been modified in ESP-IDF FreeRTOS to include Deletion Callbacks (see :ref:`deletion-callbacks`). Therefore -the function :cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback` can also be +the function :cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback` can also be called. + + .. _tasks-and-task-creation: Tasks and Task Creation ----------------------- -Tasks in ESP-IDF FreeRTOS are designed to run on a particular core, therefore -two new task creation functions have been added to ESP-IDF FreeRTOS by -appending ``PinnedToCore`` to the names of the task creation functions in +Tasks in ESP-IDF FreeRTOS are designed to run on a particular core, therefore +two new task creation functions have been added to ESP-IDF FreeRTOS by +appending ``PinnedToCore`` to the names of the task creation functions in vanilla FreeRTOS. The vanilla FreeRTOS functions of :cpp:func:`xTaskCreate` -and :cpp:func:`xTaskCreateStatic` have led to the addition of -:cpp:func:`xTaskCreatePinnedToCore` and :cpp:func:`xTaskCreateStaticPinnedToCore` in +and :cpp:func:`xTaskCreateStatic` have led to the addition of +:cpp:func:`xTaskCreatePinnedToCore` and :cpp:func:`xTaskCreateStaticPinnedToCore` in ESP-IDF FreeRTOS (see :ref:`backported-features`). For more details see :component_file:`freertos/task.c` @@ -349,15 +355,22 @@ context switches and servicing of ISRs during a critical section. Therefore, critical sections are used as a valid protection method against simultaneous access in vanilla FreeRTOS. -On the other hand, the ESP32 has no hardware method for cores to disable each -other’s interrupts. Calling ``portDISABLE_INTERRUPTS()`` will have no effect on -the interrupts of the other core. Therefore, disabling interrupts is **NOT** -a valid protection method against simultaneous access to shared data as it -leaves the other core free to access the data even if the current core has -disabled its own interrupts. +.. only:: esp32 + + On the other hand, the ESP32 has no hardware method for cores to disable each + other’s interrupts. Calling ``portDISABLE_INTERRUPTS()`` will have no effect on + the interrupts of the other core. Therefore, disabling interrupts is **NOT** + a valid protection method against simultaneous access to shared data as it + leaves the other core free to access the data even if the current core has + disabled its own interrupts. + +.. only:: esp32s2 + + ESP-IDF contains some modifications to work with dual core concurrency, + and the dual core API is used even on a single core only chip. For this reason, ESP-IDF FreeRTOS implements critical sections using special mutexes, -referred by portMUX_Type objects on top of specific ESP32 spinlock component +referred by portMUX_Type objects on top of specific spinlock component and calls to enter or exit a critical must provide a spinlock object that is associated with a shared resource requiring access protection. When entering a critical section in ESP-IDF FreeRTOS, the calling core will disable @@ -394,46 +407,42 @@ spinlock is provided upon entering and exiting, the type of call should not matter. -.. _floating-points: +.. only:: esp32 -Floating Point Aritmetic ------------------------- + .. _floating-points: -The ESP32 supports hardware acceleration of single precision floating point -arithmetic (``float``) via Floating Point Units (FPU, also known as coprocessors) -attached to each core. The use of the FPUs imposes some behavioral restrictions -on ESP-IDF FreeRTOS. + Floating Point Arithmetic + ------------------------ -ESP-IDF FreeRTOS implements Lazy Context Switching for FPUs. In other words, -the state of a core's FPU registers are not immediately saved when a context -switch occurs. Therefore, tasks that utilize ``float`` must be pinned to a -particular core upon creation. If not, ESP-IDF FreeRTOS will automatically pin -the task in question to whichever core the task was running on upon the task's -first use of ``float``. Likewise due to Lazy Context Switching, only interrupt -service routines of lowest priority (that is it the Level 1) can use ``float``, -higher priority interrupts do not support FPU usage. - -ESP32 does not support hardware acceleration for double precision floating point -arithmetic (``double``). Instead ``double`` is implemented via software hence the -behavioral restrictions with regards to ``float`` do not apply to ``double``. Note -that due to the lack of hardware acceleration, ``double`` operations may consume -significantly larger amount of CPU time in comparison to ``float``. + ESP-IDF FreeRTOS implements Lazy Context Switching for FPUs. In other words, + the state of a core's FPU registers are not immediately saved when a context + switch occurs. Therefore, tasks that utilize ``float`` must be pinned to a + particular core upon creation. If not, ESP-IDF FreeRTOS will automatically pin + the task in question to whichever core the task was running on upon the task's + first use of ``float``. Likewise due to Lazy Context Switching, only interrupt + service routines of lowest priority (that is it the Level 1) can use ``float``, + higher priority interrupts do not support FPU usage. + ESP32 does not support hardware acceleration for double precision floating point + arithmetic (``double``). Instead ``double`` is implemented via software hence the + behavioral restrictions with regards to ``float`` do not apply to ``double``. Note + that due to the lack of hardware acceleration, ``double`` operations may consume + significantly larger amount of CPU time in comparison to ``float``. .. _task-deletion: Task Deletion ------------- -FreeRTOS task deletion prior to v9.0.0 delegated the freeing of task memory +FreeRTOS task deletion prior to v9.0.0 delegated the freeing of task memory entirely to the Idle Task. Currently, the freeing of task memory will occur -immediately (within :cpp:func:`vTaskDelete`) if the task being deleted is not currently -running or is not pinned to the other core (with respect to the core +immediately (within :cpp:func:`vTaskDelete`) if the task being deleted is not currently +running or is not pinned to the other core (with respect to the core :cpp:func:`vTaskDelete` is called on). TLSP deletion callbacks will also run immediately if the same conditions are met. -However, calling :cpp:func:`vTaskDelete` to delete a task that is either currently -running or pinned to the other core will still result in the freeing of memory +However, calling :cpp:func:`vTaskDelete` to delete a task that is either currently +running or pinned to the other core will still result in the freeing of memory being delegated to the Idle Task. @@ -442,32 +451,32 @@ being delegated to the Idle Task. Thread Local Storage Pointers & Deletion Callbacks -------------------------------------------------- -Thread Local Storage Pointers (TLSP) are pointers stored directly in the TCB. -TLSP allow each task to have its own unique set of pointers to data structures. -However task deletion behavior in vanilla FreeRTOS does not automatically +Thread Local Storage Pointers (TLSP) are pointers stored directly in the TCB. +TLSP allow each task to have its own unique set of pointers to data structures. +However task deletion behavior in vanilla FreeRTOS does not automatically free the memory pointed to by TLSP. Therefore if the memory pointed to by -TLSP is not explicitly freed by the user before task deletion, memory leak will +TLSP is not explicitly freed by the user before task deletion, memory leak will occur. -ESP-IDF FreeRTOS provides the added feature of Deletion Callbacks. Deletion +ESP-IDF FreeRTOS provides the added feature of Deletion Callbacks. Deletion Callbacks are called automatically during task deletion to free memory pointed to by TLSP. Each TLSP can have its own Deletion Callback. Note that due to the -to :ref:`task-deletion` behavior, there can be instances where Deletion +to :ref:`task-deletion` behavior, there can be instances where Deletion Callbacks are called in the context of the Idle Tasks. Therefore Deletion Callbacks **should never attempt to block** and critical sections should be kept as short as possible to minimize priority inversion. Deletion callbacks are of type ``void (*TlsDeleteCallbackFunction_t)( int, void * )`` where the first parameter -is the index number of the associated TLSP, and the second parameter is the +is the index number of the associated TLSP, and the second parameter is the TLSP itself. -Deletion callbacks are set alongside TLSP by calling -:cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback`. Calling the vanilla +Deletion callbacks are set alongside TLSP by calling +:cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback`. Calling the vanilla FreeRTOS function :cpp:func:`vTaskSetThreadLocalStoragePointer` will simply set the TLSP's associated Deletion Callback to `NULL` meaning that no callback will be called for that TLSP during task deletion. If a deletion callback is `NULL`, -users should manually free the memory pointed to by the associated TLSP before +users should manually free the memory pointed to by the associated TLSP before task deletion in order to avoid memory leak. :ref:`CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS` in menuconfig can be used @@ -487,27 +496,27 @@ highlights some of the ESP-IDF FreeRTOS configuration options. For a full list o ESP-IDF FreeRTOS configurations, see :doc:`FreeRTOS <../api-reference/kconfig>` :ref:`CONFIG_FREERTOS_UNICORE` will run ESP-IDF FreeRTOS only -on **PRO_CPU**. Note that this is **not equivalent to running vanilla -FreeRTOS**. Behaviors of multiple components in ESP-IDF will be modified such -as :component_file:`esp32/cpu_start.c`. For more details regarding the -effects of running ESP-IDF FreeRTOS on a single core, search for +on **PRO_CPU**. Note that this is **not equivalent to running vanilla +FreeRTOS**. Behaviors of multiple components in ESP-IDF will be modified such +as :component_file:`{IDF_TARGET_PATH_NAME}/cpu_start.c`. For more details regarding the +effects of running ESP-IDF FreeRTOS on a single core, search for occurences of ``CONFIG_FREERTOS_UNICORE`` in the ESP-IDF components. - -:ref:`CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS` will define the -number of Thread Local Storage Pointers each task will have in ESP-IDF + +:ref:`CONFIG_FREERTOS_THREAD_LOCAL_STORAGE_POINTERS` will define the +number of Thread Local Storage Pointers each task will have in ESP-IDF FreeRTOS. :ref:`CONFIG_FREERTOS_SUPPORT_STATIC_ALLOCATION` will enable the backported functionality of :cpp:func:`xTaskCreateStaticPinnedToCore` in ESP-IDF FreeRTOS - + :ref:`CONFIG_FREERTOS_ASSERT_ON_UNTESTED_FUNCTION` will trigger a halt in particular functions in ESP-IDF FreeRTOS which have not been fully tested in an SMP context. -:ref:`CONFIG_FREERTOS_TASK_FUNCTION_WRAPPER` will enclose all task functions -within a wrapper function. In the case that a task function mistakenly returns -(i.e. does not call :cpp:func:`vTaskDelete`), the call flow will return to the -wrapper function. The wrapper function will then log an error and abort the +:ref:`CONFIG_FREERTOS_TASK_FUNCTION_WRAPPER` will enclose all task functions +within a wrapper function. In the case that a task function mistakenly returns +(i.e. does not call :cpp:func:`vTaskDelete`), the call flow will return to the +wrapper function. The wrapper function will then log an error and abort the application, as illustrated below:: E (25) FreeRTOS: FreeRTOS task should not return. Aborting now! diff --git a/docs/en/api-guides/general-notes.rst b/docs/en/api-guides/general-notes.rst index b3860332f..84fa489a5 100644 --- a/docs/en/api-guides/general-notes.rst +++ b/docs/en/api-guides/general-notes.rst @@ -18,7 +18,7 @@ This process is explained in detail in the following sections. First stage bootloader ^^^^^^^^^^^^^^^^^^^^^^ -After SoC reset, PRO CPU will start running immediately, executing reset vector code, while APP CPU will be held in reset. During startup process, PRO CPU does all the initialization. APP CPU reset is de-asserted in the ``call_start_cpu0`` function of application startup code. Reset vector code is located at address 0x40000400 in the mask ROM of the ESP32 chip and can not be modified. +After SoC reset, PRO CPU will start running immediately, executing reset vector code, while APP CPU will be held in reset. During startup process, PRO CPU does all the initialization. APP CPU reset is de-asserted in the ``call_start_cpu0`` function of application startup code. Reset vector code is located at address 0x40000400 in the mask ROM of the {IDF_TARGET_NAME} chip and can not be modified. Startup code called from the reset vector determines the boot mode by checking ``GPIO_STRAP_REG`` register for bootstrap pin states. Depending on the reset reason, the following takes place: @@ -28,18 +28,18 @@ Startup code called from the reset vector determines the boot mode by checking ` 3. For software CPU reset and watchdog CPU reset: configure SPI flash based on EFUSE values, and attempt to load the code from flash. This step is described in more detail in the next paragraphs. If loading code from flash fails, unpack BASIC interpreter into the RAM and start it. Note that RTC watchdog is still enabled when this happens, so unless any input is received by the interpreter, watchdog will reset the SOC in a few hundred milliseconds, repeating the whole process. If the interpreter receives any input from the UART, it disables the watchdog. -Application binary image is loaded from flash starting at address 0x1000. First 4kB sector of flash is used to store secure boot IV and signature of the application image. Please check secure boot documentation for details about this. +Application binary image is loaded from flash starting at address 0x1000. First 4kB sector of flash is used to store secure boot IV and signature of the application image. Please check secure boot documentation for details about this. .. TODO: describe application binary image format, describe optional flash configuration commands. Second stage bootloader ^^^^^^^^^^^^^^^^^^^^^^^ -In ESP-IDF, the binary image which resides at offset 0x1000 in flash is the second stage bootloader. Second stage bootloader source code is available in components/bootloader directory of ESP-IDF. Note that this arrangement is not the only one possible with the ESP32 chip. It is possible to write a fully featured application which would work when flashed to offset 0x1000, but this is out of scope of this document. Second stage bootloader is used in ESP-IDF to add flexibility to flash layout (using partition tables), and allow for various flows associated with flash encryption, secure boot, and over-the-air updates (OTA) to take place. +In ESP-IDF, the binary image which resides at offset 0x1000 in flash is the second stage bootloader. Second stage bootloader source code is available in components/bootloader directory of ESP-IDF. Note that this arrangement is not the only one possible with the {IDF_TARGET_NAME} chip. It is possible to write a fully featured application which would work when flashed to offset 0x1000, but this is out of scope of this document. Second stage bootloader is used in ESP-IDF to add flexibility to flash layout (using partition tables), and allow for various flows associated with flash encryption, secure boot, and over-the-air updates (OTA) to take place. When the first stage 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 at offset 0x8000. See :doc:`partition tables ` documentation for more information. The bootloader finds factory and OTA partitions, and decides which one to boot based on data found in *OTA info* partition. +Second stage bootloader reads the partition table found at offset 0x8000. See :doc:`partition tables ` documentation for more information. The bootloader finds factory and OTA partitions, and decides which one to boot based on data found in *OTA info* partition. For the selected partition, second stage bootloader copies data and code sections which are mapped into IRAM and DRAM to their load addresses. For sections which have load addresses in DROM and IROM regions, flash MMU is configured to provide the correct mapping. Note that the second stage bootloader configures flash MMU for both PRO and APP CPUs, but it only enables flash MMU for PRO CPU. Reason for this is that second stage bootloader code is loaded into the memory region used by APP CPU cache. The duty of enabling cache for APP CPU is passed on to the application. Once code is loaded and flash MMU is set up, second stage bootloader jumps to the application entry point found in the binary image header. @@ -48,9 +48,9 @@ Currently it is not possible to add application-defined hooks to the bootloader Application startup ^^^^^^^^^^^^^^^^^^^ -ESP-IDF application entry point is ``call_start_cpu0`` function found in ``components/esp32/cpu_start.c``. Two main things this function does are to enable heap allocator and to make APP CPU jump to its entry point, ``call_start_cpu1``. The code on PRO CPU sets the entry point for APP CPU, de-asserts APP CPU reset, and waits for a global flag to be set by the code running on APP CPU, indicating that it has started. Once this is done, PRO CPU jumps to ``start_cpu0`` function, and APP CPU jumps to ``start_cpu1`` function. +ESP-IDF application entry point is ``call_start_cpu0`` function found in ``components/{IDF_TARGET_PATH_NAME}/cpu_start.c``. Two main things this function does are to enable heap allocator and to make APP CPU jump to its entry point, ``call_start_cpu1``. The code on PRO CPU sets the entry point for APP CPU, de-asserts APP CPU reset, and waits for a global flag to be set by the code running on APP CPU, indicating that it has started. Once this is done, PRO CPU jumps to ``start_cpu0`` function, and APP CPU jumps to ``start_cpu1`` function. -Both ``start_cpu0`` and ``start_cpu1`` are weak functions, meaning that they can be overridden in the application, if some application-specific change to initialization sequence is needed. Default implementation of ``start_cpu0`` enables or initializes components depending on choices made in ``menuconfig``. Please see source code of this function in ``components/esp32/cpu_start.c`` for an up to date list of steps performed. Note that any C++ global constructors present in the application will be called at this stage. Once all essential components are initialized, *main task* is created and FreeRTOS scheduler is started. +Both ``start_cpu0`` and ``start_cpu1`` are weak functions, meaning that they can be overridden in the application, if some application-specific change to initialization sequence is needed. Default implementation of ``start_cpu0`` enables or initializes components depending on choices made in ``menuconfig``. Please see source code of this function in ``components/{IDF_TARGET_PATH_NAME}/cpu_start.c`` for an up to date list of steps performed. Note that any C++ global constructors present in the application will be called at this stage. Once all essential components are initialized, *main task* is created and FreeRTOS scheduler is started. While PRO CPU does initialization in ``start_cpu0`` function, APP CPU spins in ``start_cpu1`` function, waiting for the scheduler to be started on the PRO CPU. Once the scheduler is started on the PRO CPU, code on the APP CPU starts the scheduler as well. @@ -61,7 +61,7 @@ Main task is the task which runs ``app_main`` function. Main task stack size and Application memory layout ------------------------- -ESP32 chip has flexible memory mapping features. This section describes how ESP-IDF uses these features by default. +{IDF_TARGET_NAME} chip has flexible memory mapping features. This section describes how ESP-IDF uses these features by default. Application code in ESP-IDF can be placed into one of the following memory regions. @@ -75,17 +75,17 @@ A few components of ESP-IDF and parts of WiFi stack are placed into this region If some application code needs to be placed into IRAM, it can be done using ``IRAM_ATTR`` define:: #include "esp_attr.h" - + void IRAM_ATTR gpio_isr_handler(void* arg) { - // ... + // ... } Here are the cases when parts of application may or should be placed into IRAM. - Interrupt handlers must be placed into IRAM if ``ESP_INTR_FLAG_IRAM`` is used when registering the interrupt handler. In this case, ISR may only call functions placed into IRAM or functions present in ROM. *Note 1:* all FreeRTOS APIs are currently placed into IRAM, so are safe to call from interrupt handlers. If the ISR is placed into IRAM, all constant data used by the ISR and functions called from ISR (including, but not limited to, ``const char`` arrays), must be placed into DRAM using ``DRAM_ATTR``. -- Some timing critical code may be placed into IRAM to reduce the penalty associated with loading the code from flash. ESP32 reads code and data from flash via a 32 kB cache. In some cases, placing a function into IRAM may reduce delays caused by a cache miss. +- Some timing critical code may be placed into IRAM to reduce the penalty associated with loading the code from flash. {IDF_TARGET_NAME} reads code and data from flash via a 32 kB cache. In some cases, placing a function into IRAM may reduce delays caused by a cache miss. IROM (code executed from Flash) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -140,7 +140,7 @@ DMA Capable Requirement Most DMA controllers (e.g. SPI, sdmmc, etc.) have requirements that sending/receiving buffers should be placed in DRAM and word-aligned. We suggest to place DMA buffers in static variables rather than in the stack. Use macro ``DMA_ATTR`` to declare global/local static variables like:: - + DMA_ATTR uint8_t buffer[]="I want to send something"; void app_main() diff --git a/docs/en/api-guides/hlinterrupts.rst b/docs/en/api-guides/hlinterrupts.rst index 2d094bc33..42dfda799 100644 --- a/docs/en/api-guides/hlinterrupts.rst +++ b/docs/en/api-guides/hlinterrupts.rst @@ -4,7 +4,7 @@ High-Level Interrupts .. toctree:: :maxdepth: 1 -The Xtensa architecture has support for 32 interrupts, divided over 8 levels, plus an assortment of exceptions. On the ESP32, the interrupt mux allows most interrupt sources to be routed to these interrupts using the :doc:`interrupt allocator <../api-reference/system/intr_alloc>`. Normally, interrupts will be written in C, but ESP-IDF allows high-level interrupts to be written in assembly as well, allowing for very low interrupt latencies. +The Xtensa architecture has support for 32 interrupts, divided over 8 levels, plus an assortment of exceptions. On the {IDF_TARGET_NAME}, the interrupt mux allows most interrupt sources to be routed to these interrupts using the :doc:`interrupt allocator <../api-reference/system/intr_alloc>`. Normally, interrupts will be written in C, but ESP-IDF allows high-level interrupts to be written in assembly as well, allowing for very low interrupt latencies. Interrupt Levels ---------------- @@ -28,11 +28,11 @@ Using these symbols is done by creating an assembly file (suffix .S) and definin .align 4 xt_highint5: ... your code here - rsr a0, EXCSAVE_5 + rsr a0, EXCSAVE_5 rfi 5 + For a real-life example, see the :component_file:`{IDF_TARGET_PATH_NAME}/dport_panic_highint_hdl.S` file; the panic handler interrupt is implemented there. -For a real-life example, see the :component_file:`esp32/dport_panic_highint_hdl.S` file; the panic handler interrupt is implemented there. Notes ----- @@ -49,7 +49,7 @@ Notes ld_include_my_isr_file: -(The symbol is called ``ld_include_my_isr_file`` here but can have any arbitrary name not defined anywhere else.) +(The symbol is called ``ld_include_my_isr_file`` here but can have any arbitrary name not defined anywhere else.) Then, in the component.mk, add this file as an unresolved symbol to the ld command line arguments:: COMPONENT_ADD_LDFLAGS := -u ld_include_my_isr_file diff --git a/docs/en/api-guides/index.rst b/docs/en/api-guides/index.rst index bd6e61eaa..d71d81ed8 100644 --- a/docs/en/api-guides/index.rst +++ b/docs/en/api-guides/index.rst @@ -15,7 +15,7 @@ API Guides Error Handling :esp32: ESP-BLE-MESH ESP-MESH (Wi-Fi) - ESP32 Core Dump + {IDF_TARGET_NAME} Core Dump Event Handling External SPI-connected RAM Fatal Errors diff --git a/docs/en/api-guides/jtag-debugging/building-openocd-linux.rst b/docs/en/api-guides/jtag-debugging/building-openocd-linux.rst index 846161881..5dc2c5930 100644 --- a/docs/en/api-guides/jtag-debugging/building-openocd-linux.rst +++ b/docs/en/api-guides/jtag-debugging/building-openocd-linux.rst @@ -11,7 +11,7 @@ The following instructions are alternative to downloading binary OpenOCD from `E Download Sources of OpenOCD =========================== -The sources for the ESP32-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands:: +The sources for the {IDF_TARGET_NAME}-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands:: cd ~/esp git clone --recursive https://github.com/espressif/openocd-esp32.git @@ -61,9 +61,9 @@ Optionally you can add ``sudo make install`` step at the end. Skip it, if you ha .. note:: - * Should an error occur, resolve it and try again until the command ``make`` works. + * Should an error occur, resolve it and try again until the command ``make`` works. * If there is a submodule problem from OpenOCD, please ``cd`` to the ``openocd-esp32`` directory and input ``git submodule update --init``. - * If the ``./configure`` is successfully run, information of enabled JTAG will be printed under ``OpenOCD configuration summary``. + * If the ``./configure`` is successfully run, information of enabled JTAG will be printed under ``OpenOCD configuration summary``. * If the information of your device is not shown in the log, use ``./configure`` to enable it as described in ``../openocd-esp32/doc/INSTALL.txt``. * For details concerning compiling OpenOCD, please refer to ``openocd-esp32/README``. @@ -73,4 +73,4 @@ Once ``make`` process is successfully completed, the executable of OpenOCD will Next Steps ========== -To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-esp32-target`. +To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-target`. diff --git a/docs/en/api-guides/jtag-debugging/building-openocd-macos.rst b/docs/en/api-guides/jtag-debugging/building-openocd-macos.rst index 0edb05149..860db3239 100644 --- a/docs/en/api-guides/jtag-debugging/building-openocd-macos.rst +++ b/docs/en/api-guides/jtag-debugging/building-openocd-macos.rst @@ -10,7 +10,7 @@ The following instructions are alternative to downloading binary OpenOCD from `E Download Sources of OpenOCD =========================== -The sources for the ESP32-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands:: +The sources for the {IDF_TARGET_NAME}-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands:: cd ~/esp git clone --recursive https://github.com/espressif/openocd-esp32.git @@ -39,9 +39,9 @@ Optionally you can add ``sudo make install`` step at the end. Skip it, if you ha .. note:: - * Should an error occur, resolve it and try again until the command ``make`` works. + * Should an error occur, resolve it and try again until the command ``make`` works. * If there is a submodule problem from OpenOCD, please ``cd`` to the ``openocd-esp32`` directory and input ``git submodule update --init``. - * If the ``./configure`` is successfully run, information of enabled JTAG will be printed under ``OpenOCD configuration summary``. + * If the ``./configure`` is successfully run, information of enabled JTAG will be printed under ``OpenOCD configuration summary``. * If the information of your device is not shown in the log, use ``./configure`` to enable it as described in ``../openocd-esp32/doc/INSTALL.txt``. * For details concerning compiling OpenOCD, please refer to ``openocd-esp32/README.OSX``. @@ -50,6 +50,5 @@ Once ``make`` process is successfully completed, the executable of OpenOCD will Next Steps ========== -To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-esp32-target`. +To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-target`. - \ No newline at end of file diff --git a/docs/en/api-guides/jtag-debugging/building-openocd-windows.rst b/docs/en/api-guides/jtag-debugging/building-openocd-windows.rst index 3163c640f..423a177dc 100644 --- a/docs/en/api-guides/jtag-debugging/building-openocd-windows.rst +++ b/docs/en/api-guides/jtag-debugging/building-openocd-windows.rst @@ -29,7 +29,7 @@ Install packages that are required to compile OpenOCD:: Download Sources of OpenOCD =========================== -The sources for the ESP32-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands:: +The sources for the {IDF_TARGET_NAME}-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands:: cd ~/esp git clone --recursive https://github.com/espressif/openocd-esp32.git @@ -62,18 +62,18 @@ Proceed with configuring and building OpenOCD:: make cp ../libusb/MinGW32/dll/libusb-1.0.dll ./src cp /opt/i686-w64-mingw32/bin/libwinpthread-1.dll ./src - + Optionally you can add ``make install`` step at the end. Skip it, if you have an existing OpenOCD (from e.g. another development platform), as it may get overwritten. Also you could use ``export DESTDIR="/custom/install/dir"; make install``. .. note:: - * Should an error occur, resolve it and try again until the command ``make`` works. + * Should an error occur, resolve it and try again until the command ``make`` works. * If there is a submodule problem from OpenOCD, please ``cd`` to the ``openocd-esp32`` directory and input ``git submodule update --init``. - * If the ``./configure`` is successfully run, information of enabled JTAG will be printed under ``OpenOCD configuration summary``. + * If the ``./configure`` is successfully run, information of enabled JTAG will be printed under ``OpenOCD configuration summary``. * If the information of your device is not shown in the log, use ``./configure`` to enable it as described in ``../openocd-esp32/doc/INSTALL.txt``. * For details concerning compiling OpenOCD, please refer to ``openocd-esp32/README.Windows``. - * Don't forget to copy `libusb-1.0.dll` and `libwinpthread-1.dll` into `OOCD_INSTALLDIR/bin` from ``~/esp/openocd-esp32/src``. + * Don't forget to copy `libusb-1.0.dll` and `libwinpthread-1.dll` into `OOCD_INSTALLDIR/bin` from ``~/esp/openocd-esp32/src``. Once ``make`` process is successfully completed, the executable of OpenOCD will be saved in ``~/esp/openocd-esp32/src`` directory. @@ -110,4 +110,4 @@ A complete described previously process is provided below for the faster executi Next Steps ========== -To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-esp32-target`. +To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-target`. diff --git a/docs/en/api-guides/jtag-debugging/configure-other-jtag.rst b/docs/en/api-guides/jtag-debugging/configure-other-jtag.rst index 8c199de6b..9edb50fbc 100644 --- a/docs/en/api-guides/jtag-debugging/configure-other-jtag.rst +++ b/docs/en/api-guides/jtag-debugging/configure-other-jtag.rst @@ -2,44 +2,64 @@ Configure Other JTAG Interface ============================== :link_to_translation:`zh_CN:[中文]` -Refer to section :ref:`jtag-debugging-selecting-jtag-adapter` for guidance what JTAG interface to select, so it is able to operate with OpenOCD and ESP32. Then follow three configuration steps below to get it working. +Refer to section :ref:`jtag-debugging-selecting-jtag-adapter` for guidance what JTAG interface to select, so it is able to operate with OpenOCD and {IDF_TARGET_NAME}. Then follow three configuration steps below to get it working. Configure Hardware ^^^^^^^^^^^^^^^^^^ -1. Identify all pins / signals on JTAG interface and ESP32 board, that should be connected to establish communication. +1. Identify all pins / signals on JTAG interface and {IDF_TARGET_NAME} board, that should be connected to establish communication. - +---+---------------+-------------+ - | | ESP32 Pin | JTAG Signal | - +===+===============+=============+ - | 1 | CHIP_PU | TRST_N | - +---+---------------+-------------+ - | 2 | MTDO / GPIO15 | TDO | - +---+---------------+-------------+ - | 3 | MTDI / GPIO12 | TDI | - +---+---------------+-------------+ - | 4 | MTCK / GPIO13 | TCK | - +---+---------------+-------------+ - | 5 | MTMS / GPIO14 | TMS | - +---+---------------+-------------+ - | 6 | GND | GND | - +---+---------------+-------------+ +.. only:: esp32 -2. Verify if ESP32 pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation. + +---+-----------------------+-------------+ + | | ESP32 Pin | JTAG Signal | + +===+=======================+=============+ + | 1 | CHIP_PU | TRST_N | + +---+-----------------------+-------------+ + | 2 | MTDO / GPIO15 | TDO | + +---+-----------------------+-------------+ + | 3 | MTDI / GPIO12 | TDI | + +---+-----------------------+-------------+ + | 4 | MTCK / GPIO13 | TCK | + +---+-----------------------+-------------+ + | 5 | MTMS / GPIO14 | TMS | + +---+-----------------------+-------------+ + | 6 | GND | GND | + +---+-----------------------+-------------+ -3. Connect identified pin / signals of ESP32 and JTAG interface. +.. only:: esp32s2 + + +---+-----------------------+-------------+ + | | ESP32-S2 Pin | JTAG Signal | + +===+=======================+=============+ + | 1 | CHIP_PU | TRST_N | + +---+-----------------------+-------------+ + | 2 | MTDO / GPIO40 | TDO | + +---+-----------------------+-------------+ + | 3 | MTDI / GPIO41 | TDI | + +---+-----------------------+-------------+ + | 4 | MTCK / GPIO39 | TCK | + +---+-----------------------+-------------+ + | 5 | MTMS / GPIO42 | TMS | + +---+-----------------------+-------------+ + | 6 | GND | GND | + +---+-----------------------+-------------+ + +2. Verify if {IDF_TARGET_NAME} pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation. + +3. Connect identified pin / signals of {IDF_TARGET_NAME} and JTAG interface. Configure Drivers ^^^^^^^^^^^^^^^^^ -You may need to install driver s/w to make JTAG work with computer. Refer to documentation of JTAG adapter, that should provide related details. +You may need to install driver s/w to make JTAG work with computer. Refer to documentation of JTAG adapter, that should provide related details. Connect ^^^^^^^ -Connect JTAG interface to the computer. Power on ESP32 and JTAG interface boards. Check if JTAG interface is visible by computer. +Connect JTAG interface to the computer. Power on {IDF_TARGET_NAME} and JTAG interface boards. Check if JTAG interface is visible by computer. To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-run-openocd`. diff --git a/docs/en/api-guides/jtag-debugging/debugging-examples.rst b/docs/en/api-guides/jtag-debugging/debugging-examples.rst index a8d3d2a29..8f2954bee 100644 --- a/docs/en/api-guides/jtag-debugging/debugging-examples.rst +++ b/docs/en/api-guides/jtag-debugging/debugging-examples.rst @@ -38,7 +38,7 @@ Examples in this section Navigating through the code, call stack and threads ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -When the target is halted, debugger shows the list of threads in "Debug" window. The line of code where program halted is highlighted in another window below, as shown on the following picture. The LED stops blinking. +When the target is halted, debugger shows the list of threads in "Debug" window. The line of code where program halted is highlighted in another window below, as shown on the following picture. The LED stops blinking. .. figure:: ../../../_static/debugging-target-halted.jpg :align: center @@ -47,7 +47,7 @@ When the target is halted, debugger shows the list of threads in "Debug" window. Target halted during debugging -Specific thread where the program halted is expanded showing the call stack. It represents function calls that lead up to the highlighted line of code, where the target halted. The first line of call stack under Thread #1 contains the last called function ``app_main()``, that in turn was called from function ``main_task()`` shown in a line below. Each line of the stack also contains the file name and line number where the function was called. By clicking / highlighting the stack entries, in window below, you will see contents of this file. +Specific thread where the program halted is expanded showing the call stack. It represents function calls that lead up to the highlighted line of code, where the target halted. The first line of call stack under Thread #1 contains the last called function ``app_main()``, that in turn was called from function ``main_task()`` shown in a line below. Each line of the stack also contains the file name and line number where the function was called. By clicking / highlighting the stack entries, in window below, you will see contents of this file. By expanding threads you can navigate throughout the application. Expand Thread #5 that contains much longer call stack. You will see there, besides function calls, numbers like ``0x4000000c``. They represent addresses of binary code not provided in source form. @@ -70,7 +70,7 @@ Setting and clearing breakpoints When debugging, we would like to be able to stop the application at critical lines of code and then examine the state of specific variables, memory and registers / peripherals. To do so we are using breakpoints. They provide a convenient way to quickly get to and halt the application at specific line. -Let's establish two breakpoints when the state of LED changes. Basing on code listing above, this happens at lines 33 and 36. To do so, hold the "Control" on the keyboard and double clink on number ``33`` in file ``blink.c`` file. A dialog will open where you can confirm your selection by pressing "OK" button. If you do not like to see the dialog just double click the line number. Set another breakpoint in line 36. +Let's establish two breakpoints when the state of LED changes. Basing on code listing above, this happens at lines 33 and 36. To do so, hold the "Control" on the keyboard and double clink on number ``33`` in file ``blink.c`` file. A dialog will open where you can confirm your selection by pressing "OK" button. If you do not like to see the dialog just double click the line number. Set another breakpoint in line 36. .. figure:: ../../../_static/debugging-setting-breakpoint.jpg :align: center @@ -141,7 +141,7 @@ If you press "Step Into (F5)" instead, then debugger will step inside subroutine Stepping through the code with "Step Into (F5)" -In this particular case debugger stepped inside ``gpio_set_level(BLINK_GPIO, 0)`` and effectively moved to ``gpio.c`` driver code. +In this particular case debugger stepped inside ``gpio_set_level(BLINK_GPIO, 0)`` and effectively moved to ``gpio.c`` driver code. See :ref:`jtag-debugging-tip-why-next-works-as-step` for potential limitation of using ``next`` command. @@ -150,10 +150,17 @@ See :ref:`jtag-debugging-tip-why-next-works-as-step` for potential limitation of Checking and setting memory ^^^^^^^^^^^^^^^^^^^^^^^^^^^ - To display or set contents of memory use "Memory" tab at the bottom of "Debug" perspective. -With the "Memory" tab, we will read from and write to the memory location ``0x3FF44004`` labeled as ``GPIO_OUT_REG`` used to set and clear individual GPIO's. For more information please refer to `ESP32 Technical Reference Manual `__, chapter IO_MUX and GPIO Matrix. +With the "Memory" tab, we will read from and write to the memory location ``0x3FF44004`` labeled as ``GPIO_OUT_REG`` used to set and clear individual GPIO's. + +.. only:: esp32 + + For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual `__, chapter IO_MUX and GPIO Matrix. + +.. only:: esp32s2beta + + For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual `__, chapter IO_MUX and GPIO Matrix. Being in the same ``blink.c`` project as before, set two breakpoints right after ``gpio_set_level`` instruction. Click "Memory" tab and then "Add Memory Monitor" button. Enter ``0x3FF44004`` in provided dialog. @@ -175,7 +182,7 @@ You should see one bit being flipped over at memory location ``0x3FF44004`` (and Observing memory location 0x3FF44004 changing one bit to "OFF" -To set memory use the same "Monitor" tab and the same memory location. Type in alternate bit pattern as previously observed. Immediately after pressing enter you will see LED changing the state. +To set memory use the same "Monitor" tab and the same memory location. Type in alternate bit pattern as previously observed. Immediately after pressing enter you will see LED changing the state. .. _jtag-debugging-examples-eclipse-06: @@ -209,7 +216,7 @@ To modify ``i`` enter a new number in "Value" column. After pressing "Resume (F8 Setting conditional breakpoints ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Here comes more interesting part. You may set a breakpoint to halt the program execution, if certain condition is satisfied. Right click on the breakpoint to open a context menu and select "Breakpoint Properties". Change the selection under "Type:" to "Hardware" and enter a "Condition:" like ``i == 2``. +Here comes more interesting part. You may set a breakpoint to halt the program execution, if certain condition is satisfied. Right click on the breakpoint to open a context menu and select "Breakpoint Properties". Change the selection under "Type:" to "Hardware" and enter a "Condition:" like ``i == 2``. .. figure:: ../../../_static/debugging-setting-conditional-breakpoint.jpg :align: center @@ -230,7 +237,7 @@ Verify if your target is ready and loaded with :example:`get-started/blink` exam Temporary breakpoint 1, app_main () at /home/user-name/esp/blink/main/./blink.c:43 43 xTaskCreate(&blink_task, "blink_task", configMINIMAL_STACK_SIZE, NULL, 5, NULL); - (gdb) + (gdb) @@ -251,19 +258,19 @@ Examples in this section Navigating through the code, call stack and threads ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -When you see the ``(gdb)`` prompt, the application is halted. LED should not be blinking. +When you see the ``(gdb)`` prompt, the application is halted. LED should not be blinking. To find out where exactly the code is halted, enter ``l`` or ``list``, and debugger will show couple of lines of code around the halt point (line 43 of code in file ``blink.c``) :: (gdb) l 38 } 39 } - 40 + 40 41 void app_main() 42 { 43 xTaskCreate(&blink_task, "blink_task", configMINIMAL_STACK_SIZE, NULL, 5, NULL); 44 } - (gdb) + (gdb) Check how code listing works by entering, e.g. ``l 30, 40`` to see particular range of lines of code. @@ -272,15 +279,15 @@ You can use ``bt`` or ``backtrace`` to see what function calls lead up to this c (gdb) bt #0 app_main () at /home/user-name/esp/blink/main/./blink.c:43 - #1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/esp32/./cpu_start.c:339 - (gdb) + #1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./cpu_start.c:339 + (gdb) -Line #0 of output provides the last function call before the application halted, i.e. ``app_main ()`` we have listed previously. The ``app_main ()`` was in turn called by function ``main_task`` from line 339 of code located in file ``cpu_start.c``. +Line #0 of output provides the last function call before the application halted, i.e. ``app_main ()`` we have listed previously. The ``app_main ()`` was in turn called by function ``main_task`` from line 339 of code located in file ``cpu_start.c``. To get to the context of ``main_task`` in file ``cpu_start.c``, enter ``frame N``, where N = 1, because the ``main_task`` is listed under #1):: (gdb) frame 1 - #1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/esp32/./cpu_start.c:339 + #1 0x400d057e in main_task (args=0x0) at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./cpu_start.c:339 339 app_main(); (gdb) @@ -295,8 +302,8 @@ Enter ``l`` and this will reveal the piece of code that called ``app_main()`` (i 339 app_main(); 340 vTaskDelete(NULL); 341 } - 342 - (gdb) + 342 + (gdb) By listing some lines before, you will see the function name ``main_task`` we have been looking for:: @@ -317,27 +324,27 @@ By listing some lines before, you will see the function name ``main_task`` we ha 339 app_main(); 340 vTaskDelete(NULL); 341 } - (gdb) + (gdb) To see the other code, enter ``i threads``. This will show the list of threads running on target:: (gdb) i threads - Id Target Id Frame + Id Target Id Frame 8 Thread 1073411336 (dport) 0x400d0848 in dport_access_init_core (arg=) - at /home/user-name/esp/esp-idf/components/esp32/./dport_access.c:170 - 7 Thread 1073408744 (ipc0) xQueueGenericReceive (xQueue=0x3ffae694, pvBuffer=0x0, xTicksToWait=1644638200, + at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./dport_access.c:170 + 7 Thread 1073408744 (ipc0) xQueueGenericReceive (xQueue=0x3ffae694, pvBuffer=0x0, xTicksToWait=1644638200, xJustPeeking=0) at /home/user-name/esp/esp-idf/components/freertos/./queue.c:1452 6 Thread 1073431096 (Tmr Svc) prvTimerTask (pvParameters=0x0) at /home/user-name/esp/esp-idf/components/freertos/./timers.c:445 5 Thread 1073410208 (ipc1 : Running) 0x4000bfea in ?? () 4 Thread 1073432224 (dport) dport_access_init_core (arg=0x0) - at /home/user-name/esp/esp-idf/components/esp32/./dport_access.c:150 + at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./dport_access.c:150 3 Thread 1073413156 (IDLE) prvIdleTask (pvParameters=0x0) at /home/user-name/esp/esp-idf/components/freertos/./tasks.c:3282 2 Thread 1073413512 (IDLE) prvIdleTask (pvParameters=0x0) at /home/user-name/esp/esp-idf/components/freertos/./tasks.c:3282 * 1 Thread 1073411772 (main : Running) app_main () at /home/user-name/esp/blink/main/./blink.c:43 - (gdb) + (gdb) The thread list shows the last function calls per each thread together with the name of C source file if available. @@ -360,7 +367,7 @@ Then check the backtrace:: #6 0x4000000c in ?? () #7 0x4000000c in ?? () #8 0x4000000c in ?? () - (gdb) + (gdb) As you see, the backtrace may contain several entries. This will let you check what exact sequence of function calls lead to the code where the target halted. Question marks ``??`` instead of a function name indicate that application is available only in binary format, without any source file in C language. The value like ``0x4000bfea`` is the memory address of the function call. @@ -385,18 +392,18 @@ If you new enter ``c``, the processor will run and halt at a breakpoint. Enterin (gdb) c Continuing. - Target halted. PRO_CPU: PC=0x400DB6F6 (active) APP_CPU: PC=0x400D10D8 + Target halted. PRO_CPU: PC=0x400DB6F6 (active) APP_CPU: PC=0x400D10D8 Breakpoint 2, blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./blink.c:33 33 gpio_set_level(BLINK_GPIO, 0); (gdb) c Continuing. - Target halted. PRO_CPU: PC=0x400DB6F8 (active) APP_CPU: PC=0x400D10D8 - Target halted. PRO_CPU: PC=0x400DB704 (active) APP_CPU: PC=0x400D10D8 + Target halted. PRO_CPU: PC=0x400DB6F8 (active) APP_CPU: PC=0x400D10D8 + Target halted. PRO_CPU: PC=0x400DB704 (active) APP_CPU: PC=0x400D10D8 Breakpoint 3, blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./blink.c:36 36 gpio_set_level(BLINK_GPIO, 1); - (gdb) + (gdb) You will be also able to see that LED is changing the state only if you resume program execution by entering ``c``. @@ -408,16 +415,16 @@ To examine how many breakpoints are set and where, use command ``info break``:: breakpoint already hit 1 time 3 breakpoint keep y 0x400db704 in blink_task at /home/user-name/esp/blink/main/./blink.c:36 breakpoint already hit 1 time - (gdb) + (gdb) Please note that breakpoint numbers (listed under ``Num``) start with ``2``. This is because first breakpoint has been already established at function ``app_main()`` by running command ``thb app_main`` on debugger launch. As it was a temporary breakpoint, it has been automatically deleted and now is not listed anymore. -To remove breakpoints enter ``delete N`` command (in short ``d N``), where ``N`` is the breakpoint number:: +To remove breakpoints enter ``delete N`` command (in short ``d N``), where ``N`` is the breakpoint number:: (gdb) delete 1 No breakpoint number 1. (gdb) delete 2 - (gdb) + (gdb) Read more about breakpoints under :ref:`jtag-debugging-tip-breakpoints` and :ref:`jtag-debugging-tip-where-breakpoints` @@ -438,9 +445,9 @@ To check it delete all breakpoints and enter ``c`` to resume application. Then e Program received signal SIGINT, Interrupt. [Switching to Thread 1073413512] - 0x400d0c00 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/components/esp32/./freertos_hooks.c:52 + 0x400d0c00 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./freertos_hooks.c:52 52 asm("waiti 0"); - (gdb) + (gdb) In particular case above, the application has been halted in line 52 of code in file ``freertos_hooks.c``. Now you can resume it again by enter ``c`` or do some debugging as discussed below. @@ -462,46 +469,46 @@ To demonstrate this functionality, using command ``break`` and ``delete`` discus Num Type Disp Enb Address What 3 breakpoint keep y 0x400db704 in blink_task at /home/user-name/esp/blink/main/./blink.c:36 breakpoint already hit 1 time - (gdb) + (gdb) Resume program by entering ``c`` and let it halt:: (gdb) c Continuing. - Target halted. PRO_CPU: PC=0x400DB754 (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB754 (active) APP_CPU: PC=0x400D1128 Breakpoint 3, blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./blink.c:36 36 gpio_set_level(BLINK_GPIO, 1); - (gdb) + (gdb) Then enter ``n`` couple of times to see how debugger is stepping one program line at a time:: (gdb) n - Target halted. PRO_CPU: PC=0x400DB756 (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DB758 (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DC04C (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DB75B (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB756 (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB758 (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DC04C (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB75B (active) APP_CPU: PC=0x400D1128 37 vTaskDelay(1000 / portTICK_PERIOD_MS); (gdb) n - Target halted. PRO_CPU: PC=0x400DB75E (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400846FC (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DB761 (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DB746 (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB75E (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400846FC (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB761 (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB746 (active) APP_CPU: PC=0x400D1128 33 gpio_set_level(BLINK_GPIO, 0); - (gdb) + (gdb) If you enter ``s`` instead, then debugger will step inside subroutine calls:: (gdb) s - Target halted. PRO_CPU: PC=0x400DB748 (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DB74B (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DC04C (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DC04F (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB748 (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB74B (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DC04C (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DC04F (active) APP_CPU: PC=0x400D1128 gpio_set_level (gpio_num=GPIO_NUM_4, level=0) at /home/user-name/esp/esp-idf/components/driver/./gpio.c:183 183 GPIO_CHECK(GPIO_IS_VALID_OUTPUT_GPIO(gpio_num), "GPIO output gpio_num error", ESP_ERR_INVALID_ARG); - (gdb) + (gdb) -In this particular case debugger stepped inside ``gpio_set_level(BLINK_GPIO, 0)`` and effectively moved to ``gpio.c`` driver code. +In this particular case debugger stepped inside ``gpio_set_level(BLINK_GPIO, 0)`` and effectively moved to ``gpio.c`` driver code. See :ref:`jtag-debugging-tip-why-next-works-as-step` for potential limitation of using ``next`` command. @@ -513,14 +520,22 @@ Checking and setting memory Displaying the contents of memory is done with command ``x``. With additional parameters you may vary the format and count of memory locations displayed. Run ``help x`` to see more details. Companion command to ``x`` is ``set`` that let you write values to the memory. -We will demonstrate how ``x`` and ``set`` work by reading from and writing to the memory location ``0x3FF44004`` labeled as ``GPIO_OUT_REG`` used to set and clear individual GPIO's. For more information please refer to `ESP32 Technical Reference Manual `__, chapter IO_MUX and GPIO Matrix. +We will demonstrate how ``x`` and ``set`` work by reading from and writing to the memory location ``0x3FF44004`` labeled as ``GPIO_OUT_REG`` used to set and clear individual GPIO's. + +.. only:: esp32 + + For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual `__, chapter IO_MUX and GPIO Matrix. + +.. only:: esp32s2beta + + For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual `__, chapter IO_MUX and GPIO Matrix. Being in the same ``blink.c`` project as before, set two breakpoints right after ``gpio_set_level`` instruction. Enter two times ``c`` to get to the break point followed by ``x /1wx 0x3FF44004`` to display contents of ``GPIO_OUT_REG`` memory location:: (gdb) c Continuing. - Target halted. PRO_CPU: PC=0x400DB75E (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DB74E (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB75E (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB74E (active) APP_CPU: PC=0x400D1128 Breakpoint 2, blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./blink.c:34 34 vTaskDelay(1000 / portTICK_PERIOD_MS); @@ -528,14 +543,14 @@ Being in the same ``blink.c`` project as before, set two breakpoints right after 0x3ff44004: 0x00000000 (gdb) c Continuing. - Target halted. PRO_CPU: PC=0x400DB751 (active) APP_CPU: PC=0x400D1128 - Target halted. PRO_CPU: PC=0x400DB75B (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB751 (active) APP_CPU: PC=0x400D1128 + Target halted. PRO_CPU: PC=0x400DB75B (active) APP_CPU: PC=0x400D1128 Breakpoint 3, blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./blink.c:37 37 vTaskDelay(1000 / portTICK_PERIOD_MS); (gdb) x /1wx 0x3FF44004 0x3ff44004: 0x00000010 - (gdb) + (gdb) If your are blinking LED connected to GPIO4, then you should see fourth bit being flipped each time the LED changes the state:: @@ -571,7 +586,7 @@ This will insert so called "watchpoint" in each place of code where variable ``i (gdb) c Continuing. - Target halted. PRO_CPU: PC=0x400DB751 (active) APP_CPU: PC=0x400D0811 + Target halted. PRO_CPU: PC=0x400DB751 (active) APP_CPU: PC=0x400D0811 [New Thread 1073432196] Program received signal SIGTRAP, Trace/breakpoint trap. @@ -584,14 +599,14 @@ Resume application couple more times so ``i`` gets incremented. Now you can ente (gdb) p i $1 = 3 - (gdb) + (gdb) To modify the value of ``i`` use ``set`` command as below (you can then print it out to check if it has been indeed changed):: (gdb) set var i = 0 (gdb) p i $3 = 0 - (gdb) + (gdb) You may have up to two watchpoints, see :ref:`jtag-debugging-tip-breakpoints`. @@ -607,21 +622,21 @@ Here comes more interesting part. You may set a breakpoint to halt the program e Breakpoint 3 at 0x400db753: file /home/user-name/esp/blink/main/./blink.c, line 34. (gdb) -Above command sets conditional breakpoint to halt program execution in line ``34`` of ``blink.c`` if ``i == 2``. +Above command sets conditional breakpoint to halt program execution in line ``34`` of ``blink.c`` if ``i == 2``. If current value of ``i`` is less than ``2`` and program is resumed, it will blink LED in a loop until condition ``i == 2`` gets true and then finally halt:: (gdb) set var i = 0 (gdb) c Continuing. - Target halted. PRO_CPU: PC=0x400DB755 (active) APP_CPU: PC=0x400D112C - Target halted. PRO_CPU: PC=0x400DB753 (active) APP_CPU: PC=0x400D112C - Target halted. PRO_CPU: PC=0x400DB755 (active) APP_CPU: PC=0x400D112C - Target halted. PRO_CPU: PC=0x400DB753 (active) APP_CPU: PC=0x400D112C + Target halted. PRO_CPU: PC=0x400DB755 (active) APP_CPU: PC=0x400D112C + Target halted. PRO_CPU: PC=0x400DB753 (active) APP_CPU: PC=0x400D112C + Target halted. PRO_CPU: PC=0x400DB755 (active) APP_CPU: PC=0x400D112C + Target halted. PRO_CPU: PC=0x400DB753 (active) APP_CPU: PC=0x400D112C Breakpoint 3, blink_task (pvParameter=0x0) at /home/user-name/esp/blink/main/./blink.c:34 34 gpio_set_level(BLINK_GPIO, 0); - (gdb) + (gdb) Obtaining help on commands @@ -635,7 +650,7 @@ Commands presented so for should provide are very basis and intended to let you Unlike "step", if the current source line calls a subroutine, this command does not enter the subroutine, but instead steps over the call, in effect treating it as a single source line. - (gdb) + (gdb) By typing just ``help``, you will get top level list of command classes, to aid you drilling down to more details. Optionally refer to available GDB cheat sheets, for instance http://darkdust.net/files/GDB%20Cheat%20Sheet.pdf. Good to have as a reference (even if not all commands are applicable in an embedded environment). @@ -643,7 +658,7 @@ By typing just ``help``, you will get top level list of command classes, to aid Ending debugger session ^^^^^^^^^^^^^^^^^^^^^^^ -To quit debugger enter ``q``:: +To quit debugger enter ``q``:: (gdb) q A debugging session is active. @@ -653,4 +668,4 @@ To quit debugger enter ``q``:: Quit anyway? (y or n) y Detaching from program: /home/user-name/esp/blink/build/blink.elf, Remote target Ending remote debugging. - user-name@computer-name:~/esp/blink$ + user-name@computer-name:~/esp/blink$ diff --git a/docs/en/api-guides/jtag-debugging/index.rst b/docs/en/api-guides/jtag-debugging/index.rst index 736c8c71e..8e32b0246 100644 --- a/docs/en/api-guides/jtag-debugging/index.rst +++ b/docs/en/api-guides/jtag-debugging/index.rst @@ -2,18 +2,18 @@ JTAG Debugging ============== :link_to_translation:`zh_CN:[中文]` -This document provides a guide to installing OpenOCD for ESP32 and debugging using +This document provides a guide to installing OpenOCD for {IDF_TARGET_NAME} and debugging using GDB. The document is structured as follows: :ref:`jtag-debugging-introduction` Introduction to the purpose of this guide. :ref:`jtag-debugging-how-it-works` - Description how ESP32, JTAG interface, OpenOCD and GDB are interconnected and working together to enable debugging of ESP32. + Description how {IDF_TARGET_NAME}, JTAG interface, OpenOCD and GDB are interconnected and working together to enable debugging of {IDF_TARGET_NAME}. :ref:`jtag-debugging-selecting-jtag-adapter` What are the criteria and options to select JTAG adapter hardware. :ref:`jtag-debugging-setup-openocd` Procedure to install OpenOCD and verify that it is installed. -:ref:`jtag-debugging-configuring-esp32-target` +:ref:`jtag-debugging-configuring-target` Configuration of OpenOCD software and set up JTAG adapter hardware that will make together a debugging target. :ref:`jtag-debugging-launching-debugger` Steps to start up a debug session with GDB from :ref:`jtag-debugging-using-debugger-eclipse` and from :ref:`jtag-debugging-using-debugger-command-line`. @@ -22,7 +22,7 @@ GDB. The document is structured as follows: :ref:`jtag-debugging-building-openocd` Procedure to build OpenOCD from sources for :doc:`Windows `, :doc:`Linux ` and :doc:`MacOS ` operating systems. :ref:`jtag-debugging-tips-and-quirks` - This section provides collection of tips and quirks related JTAG debugging of ESP32 with OpenOCD and GDB. + This section provides collection of tips and quirks related JTAG debugging of {IDF_TARGET_NAME} with OpenOCD and GDB. .. _jtag-debugging-introduction: @@ -30,13 +30,15 @@ GDB. The document is structured as follows: Introduction ------------ -The ESP32 has two powerful Xtensa cores, allowing for a great deal of variety of program architectures. The FreeRTOS OS that comes with ESP-IDF is capable of multi-core preemptive multithreading, allowing for an intuitive way of writing software. +.. only:: esp32 -The downside of the ease of programming is that debugging without the right tools is harder: figuring out a bug that is caused by two threads, running even simultaneously on two different CPU cores, can take a long time when all you have are printf statements. A better and in many cases quicker way to debug such problems is by using a debugger, connected to the processors over a debug port. + The ESP32 has two powerful Xtensa cores, allowing for a great deal of variety of program architectures. The FreeRTOS OS that comes with ESP-IDF is capable of multi-core preemptive multithreading, allowing for an intuitive way of writing software. -Espressif has ported OpenOCD to support the ESP32 processor and the multicore FreeRTOS, which will be the foundation of most ESP32 apps, and has written some tools to help with features OpenOCD does not support natively. + The downside of the ease of programming is that debugging without the right tools is harder: figuring out a bug that is caused by two threads, running even simultaneously on two different CPU cores, can take a long time when all you have are printf statements. A better and in many cases quicker way to debug such problems is by using a debugger, connected to the processors over a debug port. -This document provides a guide to installing OpenOCD for ESP32 and debugging using GDB under Linux, Windows and MacOS. Except for OS specific installation procedures, the s/w user interface and use procedures are the same across all supported operating systems. +Espressif has ported OpenOCD to support the {IDF_TARGET_NAME} processor and the multicore FreeRTOS, which will be the foundation of most {IDF_TARGET_NAME} apps, and has written some tools to help with features OpenOCD does not support natively. + +This document provides a guide to installing OpenOCD for {IDF_TARGET_NAME} and debugging using GDB under Linux, Windows and MacOS. Except for OS specific installation procedures, the s/w user interface and use procedures are the same across all supported operating systems. .. note:: @@ -47,20 +49,22 @@ This document provides a guide to installing OpenOCD for ESP32 and debugging usi How it Works? ------------- -The key software and hardware to perform debugging of ESP32 with OpenOCD over JTAG (Joint Test Action Group) interface is presented below and includes **xtensa-esp32-elf-gdb debugger**, **OpenOCD on chip debugger** and **JTAG adapter** connected to **ESP32** target. +The key software and hardware to perform debugging of {IDF_TARGET_NAME} with OpenOCD over JTAG (Joint Test Action Group) interface is presented below and includes xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb debugger, OpenOCD on chip debugger and JTAG adapter connected to {IDF_TARGET_NAME} target. .. figure:: ../../../_static/jtag-debugging-overview.jpg :align: center - :alt: JTAG debugging - overview diagram + :alt: JTAG debugging - overview diagram :figclass: align-center - JTAG debugging - overview diagram + JTAG debugging - overview diagram -Under "Application Loading and Monitoring" there is another software and hardware to compile, build and flash application to ESP32, as well as to provide means to monitor diagnostic messages from ESP32. +Under "Application Loading and Monitoring" there is another software and hardware to compile, build and flash application to {IDF_TARGET_NAME}, as well as to provide means to monitor diagnostic messages from {IDF_TARGET_NAME}. Debugging using JTAG and application loading / monitoring is integrated under the `Eclipse `_ environment, to provide quick and easy transition from writing, compiling and loading the code to debugging, back to writing the code, and so on. All the software is available for Windows, Linux and MacOS platforms. -If the :doc:`ESP-WROVER-KIT <../../hw-reference/modules-and-boards>` is used, then connection from PC to ESP32 is done effectively with a single USB cable thanks to FT2232H chip installed on WROVER, which provides two USB channels, one for JTAG and the second for UART connection. +.. only:: esp32 + + If the :doc:`ESP-WROVER-KIT <../../hw-reference/modules-and-boards>` is used, then connection from PC to ESP32 is done effectively with a single USB cable thanks to FT2232H chip installed on WROVER, which provides two USB channels, one for JTAG and the second for UART connection. Depending on user preferences, both `debugger` and `idf.py build` can be operated directly from terminal/command line, instead from Eclipse. @@ -70,13 +74,13 @@ Depending on user preferences, both `debugger` and `idf.py build` can be operate Selecting JTAG Adapter ---------------------- -The quickest and most convenient way to start with JTAG debugging is by using :doc:`ESP-WROVER-KIT <../../hw-reference/modules-and-boards>`. Each version of this development board has JTAG interface already build in. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to ESP32. WROVER KIT is using FT2232H JTAG interface operating at 20 MHz clock speed, which is difficult to achieve with an external adapter. +The quickest and most convenient way to start with JTAG debugging is by using :doc:`ESP-WROVER-KIT <../../hw-reference/modules-and-boards>`. Each version of this development board has JTAG interface already build in. No need for an external JTAG adapter and extra wiring / cable to connect JTAG to {IDF_TARGET_NAME}. WROVER KIT is using FT2232H JTAG interface operating at 20 MHz clock speed, which is difficult to achieve with an external adapter. -If you decide to use separate JTAG adapter, look for one that is compatible with both the voltage levels on the ESP32 as well as with the OpenOCD software. The JTAG port on the ESP32 is an industry-standard JTAG port which lacks (and does not need) the TRST pin. The JTAG I/O pins all are powered from the VDD_3P3_RTC pin (which normally would be powered by a 3.3 V rail) so the JTAG adapter needs to be able to work with JTAG pins in that voltage range. +If you decide to use separate JTAG adapter, look for one that is compatible with both the voltage levels on the {IDF_TARGET_NAME} as well as with the OpenOCD software. The JTAG port on the {IDF_TARGET_NAME} is an industry-standard JTAG port which lacks (and does not need) the TRST pin. The JTAG I/O pins all are powered from the VDD_3P3_RTC pin (which normally would be powered by a 3.3 V rail) so the JTAG adapter needs to be able to work with JTAG pins in that voltage range. -On the software side, OpenOCD supports a fair amount of JTAG adapters. See http://openocd.org/doc/html/Debug-Adapter-Hardware.html for an (unfortunately slightly incomplete) list of the adapters OpenOCD works with. This page lists SWD-compatible adapters as well; take note that the ESP32 does not support SWD. JTAG adapters that are hardcoded to a specific product line, e.g. ST-LINK debugging adapters for STM32 families, will not work. +On the software side, OpenOCD supports a fair amount of JTAG adapters. See http://openocd.org/doc/html/Debug-Adapter-Hardware.html for an (unfortunately slightly incomplete) list of the adapters OpenOCD works with. This page lists SWD-compatible adapters as well; take note that the {IDF_TARGET_NAME} does not support SWD. JTAG adapters that are hardcoded to a specific product line, e.g. ST-LINK debugging adapters for STM32 families, will not work. -The minimal signalling to get a working JTAG connection are TDI, TDO, TCK, TMS and GND. Some JTAG debuggers also need a connection from the ESP32 power line to a line called e.g. Vtar to set the working voltage. SRST can optionally be connected to the CH_PD of the ESP32, although for now, support in OpenOCD for that line is pretty minimal. +The minimal signalling to get a working JTAG connection are TDI, TDO, TCK, TMS and GND. Some JTAG debuggers also need a connection from the {IDF_TARGET_NAME} power line to a line called e.g. Vtar to set the working voltage. SRST can optionally be connected to the CH_PD of the {IDF_TARGET_NAME}, although for now, support in OpenOCD for that line is pretty minimal. .. _jtag-debugging-setup-openocd: @@ -94,7 +98,7 @@ If you have already set up ESP-IDF with CMake build system according to the :doc The output should be as follows (although the version may be more recent than listed here):: - Open On-Chip Debugger v0.10.0-esp32-20190708 (2019-07-08-11:04) + Open On-Chip Debugger v0.10.0-{IDF_TARGET_TOOLCHAIN_NAME}-20190708 (2019-07-08-11:04) Licensed under GNU GPL v2 For bug reports, read http://openocd.org/doc/doxygen/bugs.html @@ -107,12 +111,12 @@ If any of these steps do not work, please go back to the :ref:`setting up the to It is also possible to build OpenOCD from source. Please refer to :ref:`jtag-debugging-building-openocd` section for details. -.. _jtag-debugging-configuring-esp32-target: +.. _jtag-debugging-configuring-target: -Configuring ESP32 Target ------------------------- +Configuring {IDF_TARGET_NAME} Target +------------------------------------- -Once OpenOCD is installed, move to configuring ESP32 target (i.e ESP32 board with JTAG interface). You will do it in the following three steps: +Once OpenOCD is installed, move to configuring {IDF_TARGET_NAME} target (i.e {IDF_TARGET_NAME} board with JTAG interface). You will do it in the following three steps: * Configure and connect JTAG interface * Run OpenOCD @@ -122,12 +126,12 @@ Once OpenOCD is installed, move to configuring ESP32 target (i.e ESP32 board wit Configure and connect JTAG interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -This step depends on JTAG and ESP32 board you are using - see the two cases described below. +This step depends on JTAG and {IDF_TARGET_NAME} board you are using - see the two cases described below. .. toctree:: :maxdepth: 1 - configure-wrover + :esp32: configure-wrover configure-other-jtag @@ -168,8 +172,8 @@ You should now see similar output (this log is for ESP-WROVER-KIT):: Info : esp32: Core was reset (pwrstat=0x5F, after clear 0x0F). * If there is an error indicating permission problems, please see the "Permissions delegation" bit in the OpenOCD README file in ``~/esp/openocd-esp32`` directory. -* In case there is an error finding configuration files, e.g. ``Can't find board/esp32-wrover-kit-3.3v.cfg``, check the path after ``-s``. This path is used by OpenOCD to look for the files specified after ``-f``. Also check if the file is indeed under provided path. -* If you see JTAG errors (...all ones/...all zeroes) please check your connections, whether no other signals are connected to JTAG besides ESP32's pins, and see if everything is powered on. +* In case there is an error finding configuration files, e.g. ``Can't find board/esp32-wrover-kit-3.3v.cfg``, check the path after ``-s``. This path is used by OpenOCD to look for the files specified after ``-f``. Also check if the file is indeed under provided path. +* If you see JTAG errors (...all ones/...all zeroes) please check your connections, whether no other signals are connected to JTAG besides {IDF_TARGET_NAME}'s pins, and see if everything is powered on. .. _jtag-upload-app-debug: @@ -177,7 +181,7 @@ You should now see similar output (this log is for ESP-WROVER-KIT):: Upload application for debugging ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Build and upload your application to ESP32 as usual, see :ref:`get-started-build`. +Build and upload your application to {IDF_TARGET_NAME} as usual, see :ref:`get-started-build`. Another option is to write application image to flash using OpenOCD via JTAG with commands like this:: @@ -201,9 +205,9 @@ You are now ready to start application debugging. Follow steps described in sect Launching Debugger ------------------ -The toolchain for ESP32 features GNU Debugger, in short GDB. It is available with other toolchain programs under filename ``xtensa-esp32-elf-gdb``. GDB can be called and operated directly from command line in a terminal. Another option is to call it from within IDE (like Eclipse, Visual Studio Code, etc.) and operate indirectly with help of GUI instead of typing commands in a terminal. +The toolchain for {IDF_TARGET_NAME} features GNU Debugger, in short GDB. It is available with other toolchain programs under filename: xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb. GDB can be called and operated directly from command line in a terminal. Another option is to call it from within IDE (like Eclipse, Visual Studio Code, etc.) and operate indirectly with help of GUI instead of typing commands in a terminal. -Both options of using debugger are discussed under links below. +Both options of using debugger are discussed under links below. * :ref:`jtag-debugging-using-debugger-eclipse` * :ref:`jtag-debugging-using-debugger-command-line` @@ -226,9 +230,9 @@ This section is intended for users not familiar with GDB. It presents example de 6. :ref:`jtag-debugging-examples-eclipse-06` 7. :ref:`jtag-debugging-examples-eclipse-07` -Similar debugging actions are provided using GDB from :ref:`jtag-debugging-examples-command-line`. +Similar debugging actions are provided using GDB from :ref:`jtag-debugging-examples-command-line`. -Before proceeding to examples, set up your ESP32 target and load it with :example:`get-started/blink`. +Before proceeding to examples, set up your {IDF_TARGET_NAME} target and load it with :example:`get-started/blink`. .. _jtag-debugging-building-openocd: diff --git a/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst b/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst index 866977c5b..88a56e75d 100644 --- a/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst +++ b/docs/en/api-guides/jtag-debugging/tips-and-quirks.rst @@ -10,7 +10,7 @@ This section provides collection of all tips and quirks referred to from various Breakpoints and watchpoints available ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -ESP32 debugger supports 2 hardware implemented breakpoints and 64 software ones. Hardware breakpoints are implemented by ESP32 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 ` for details). ESP32 also supports two watchpoints, so two 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 2nd 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 2 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 ` for details). {IDF_TARGET_NAME} also supports two watchpoints, so two 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 2nd 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: @@ -26,9 +26,9 @@ Emulating part of hardware breakpoints using software flash ones means that the Flash Mappings vs SW Flash Breakpoints ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In order to set/clear software breakpoints in flash, OpenOCD needs to know their flash addresses. To accomplish conversion from the ESP32 address space to the flash one, OpenOCD uses mappings of program's code regions resided in flash. Those mappings are kept in the image header which is prepended to program binary data (code and data segments) and is specific to every application image written to the flash. So to support software flash breakpoints OpenOCD should know where application image under debugging is resided in the flash. By default OpenOCD reads partition table at 0x8000 and uses mappings from the first found application image, but there can be the cases when it will not work, e.g. partition table is not at standard flash location or even there can be multiple images: one factory and two OTA and you may want to debbug any of them. To cover all possible debugging scenarios OpenOCD supports special command which can be used to set arbitrary location of application image to debug. The command has the following format: +In order to set/clear software breakpoints in flash, OpenOCD needs to know their flash addresses. To accomplish conversion from the {IDF_TARGET_NAME} address space to the flash one, OpenOCD uses mappings of program's code regions resided in flash. Those mappings are kept in the image header which is prepended to program binary data (code and data segments) and is specific to every application image written to the flash. So to support software flash breakpoints OpenOCD should know where application image under debugging is resided in the flash. By default OpenOCD reads partition table at 0x8000 and uses mappings from the first found application image, but there can be the cases when it will not work, e.g. partition table is not at standard flash location or even there can be multiple images: one factory and two OTA and you may want to debbug any of them. To cover all possible debugging scenarios OpenOCD supports special command which can be used to set arbitrary location of application image to debug. The command has the following format: -``esp32 appimage_offset `` +``esp32 appimage_offset `` Offset should be in hex format. To reset to the default behaviour you can specify ``-1`` as offset. @@ -55,13 +55,7 @@ Support options for OpenOCD at compile time ESP-IDF has some support options for OpenOCD debugging which can be set at compile time: -.. only:: esp32 - - * :ref:`CONFIG_ESP32_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. - -.. only:: esp32s2 - - * :ref:`CONFIG_ESP32S2_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_{IDF_TARGET_CFG_PREFIX}_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. @@ -77,14 +71,16 @@ OpenOCD has explicit support for the ESP-IDF FreeRTOS. GDB can see FreeRTOS task .. _jtag-debugging-tip-code-flash-voltage: -Why to set SPI flash voltage in OpenOCD configuration? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. only:: esp33 -The MTDI pin of ESP32, being among four pins used for JTAG communication, is also one of ESP32's bootstrapping pins. On power up ESP32 is sampling binary level on MTDI to set it's internal voltage regulator used to supply power to external SPI flash chip. If binary level on MDTI pin on power up is low, the voltage regulator is set to deliver 3.3 V, if it is high, then the voltage is set to 1.8 V. The MTDI pin should have a pull-up or may rely on internal weak pull down resistor (see `ESP32 Series Datasheet `_ for details), depending on the type of SPI chip used. Once JTAG is connected, it overrides the pull-up or pull-down resistor that is supposed to do the bootstrapping. + Why to set SPI flash voltage in OpenOCD configuration? + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To handle this issue OpenOCD's board configuration file (e.g. ``boards\esp-wroom-32.cfg`` for ESP32-WROOM-32 module) provides ``ESP32_FLASH_VOLTAGE`` parameter to set the idle state of the ``TDO`` line to a specified binary level, therefore reducing the chance of a bad bootup of application due to incorrect flash voltage. + The MTDI pin of ESP32, being among four pins used for JTAG communication, is also one of ESP32's bootstrapping pins. On power up ESP32 is sampling binary level on MTDI to set it's internal voltage regulator used to supply power to external SPI flash chip. If binary level on MDTI pin on power up is low, the voltage regulator is set to deliver 3.3 V, if it is high, then the voltage is set to 1.8 V. The MTDI pin should have a pull-up or may rely on internal weak pull down resistor (see `ESP32 Series Datasheet `_ for details), depending on the type of SPI chip used. Once JTAG is connected, it overrides the pull-up or pull-down resistor that is supposed to do the bootstrapping. -Check specification of ESP32 module connected to JTAG, what is the power supply voltage of SPI flash chip. Then set ``ESP32_FLASH_VOLTAGE`` accordingly. Most WROOM modules use 3.3 V flash, while WROVER modules use 1.8 V flash. + To handle this issue OpenOCD's board configuration file (e.g. ``boards\esp-wroom-32.cfg`` for ESP32-WROOM-32 module) provides ``ESP32_FLASH_VOLTAGE`` parameter to set the idle state of the ``TDO`` line to a specified binary level, therefore reducing the chance of a bad bootup of application due to incorrect flash voltage. + + Check specification of ESP32 module connected to JTAG, what is the power supply voltage of SPI flash chip. Then set ``ESP32_FLASH_VOLTAGE`` accordingly. Most WROOM modules use 3.3 V flash, while WROVER modules use 1.8 V flash. .. _jtag-debugging-tip-optimize-jtag-speed: @@ -105,9 +101,9 @@ In order to achieve higher data rates and minimize number of dropped packets it 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. +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 2`` — Restrict GDB to using two hardware watchpoints supported by ESP32. For more information see https://sourceware.org/gdb/onlinedocs/gdb/Remote-Configuration.html. +* ``set remote hardware-watchpoint-limit 2`` — Restrict GDB to using two hardware watchpoints supported by the chip, 2 for ESP32. For more information see https://sourceware.org/gdb/onlinedocs/gdb/Remote-Configuration.html. * ``mon reset halt`` — reset the chip and keep the CPUs halted * ``flushregs`` — 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 ``flushregs`` 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 @@ -170,40 +166,42 @@ Power supply voltage of ESP32's SPI flash chip Comment out this line to set 3.3 V, ref: :ref:`jtag-debugging-tip-code-flash-voltage` -Configuration file for ESP32 targets -"""""""""""""""""""""""""""""""""""" +.. only:: esp32 -:: + Configuration file for ESP32 targets + """""""""""""""""""""""""""""""""""" - source [find target/esp32.cfg] + :: -.. note:: + source [find target/esp32.cfg] - Do not change ``source [find target/esp32.cfg]`` line unless you are familiar with OpenOCD internals. + .. note:: -Currently ``target/esp32.cfg`` remains the only configuration file for ESP32 targets (esp108 and esp32). The matrix of supported configurations is as follows: + Do not change ``source [find target/esp32.cfg]`` line unless you are familiar with OpenOCD internals. - +---------------+---------------+---------------+ - | Dual/single | RTOS | Target used | - +===============+===============+===============+ - | dual | FreeRTOS | esp32 | - +---------------+---------------+---------------+ - | single | FreeRTOS | esp108 (*) | - +---------------+---------------+---------------+ - | dual | none | esp108 | - +---------------+---------------+---------------+ - | single | none | esp108 | - +---------------+---------------+---------------+ + Currently ``target/esp32.cfg`` remains the only configuration file for ESP32 targets (esp108 and esp32). The matrix of supported configurations is as follows: - (*) — we plan to fix this and add support for single core debugging with esp32 target in a subsequent commits. + +---------------+---------------+---------------+ + | Dual/single | RTOS | Target used | + +===============+===============+===============+ + | dual | FreeRTOS | esp32 | + +---------------+---------------+---------------+ + | single | FreeRTOS | esp108 (*) | + +---------------+---------------+---------------+ + | dual | none | esp108 | + +---------------+---------------+---------------+ + | single | none | esp108 | + +---------------+---------------+---------------+ -Look inside ``board/esp-wroom-32.cfg`` for additional information provided in comments besides each configuration parameter. + (*) — we plan to fix this and add support for single core debugging with esp32 target in a subsequent commits. + + Look inside ``board/esp-wroom-32.cfg`` for additional information provided in comments besides each configuration parameter. .. _jtag-debugging-tip-reset-by-debugger: -How debugger resets ESP32? -^^^^^^^^^^^^^^^^^^^^^^^^^^ +How debugger resets {IDF_TARGET_NAME}? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The board can be reset by entering ``mon reset`` or ``mon reset halt`` into GDB. @@ -213,21 +211,37 @@ The board can be reset by entering ``mon reset`` or ``mon reset halt`` into GDB. Do not use JTAG pins for something else ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Operation of JTAG may be disturbed, if some other h/w is connected to JTAG pins besides ESP32 module and JTAG adapter. ESP32 JTAG us using the following pins: +Operation of JTAG may be disturbed, if some other h/w is connected to JTAG pins besides {IDF_TARGET_NAME} module and JTAG adapter. {IDF_TARGET_NAME} JTAG us using the following pins: - +---+----------------+-------------+ - | | ESP32 JTAG Pin | JTAG Signal | - +===+================+=============+ - | 1 | MTDO / GPIO15 | TDO | - +---+----------------+-------------+ - | 2 | MTDI / GPIO12 | TDI | - +---+----------------+-------------+ - | 3 | MTCK / GPIO13 | TCK | - +---+----------------+-------------+ - | 4 | MTMS / GPIO14 | TMS | - +---+----------------+-------------+ +.. only:: esp32 -JTAG communication will likely fail, if configuration of JTAG pins is changed by user application. If OpenOCD initializes correctly (detects the two Tensilica cores), but loses sync and spews out a lot of DTR/DIR errors when the program is ran, it is likely that the application reconfigures the JTAG pins to something else, or the user forgot to connect Vtar to a JTAG adapter that needed it. + +---+-----------------------+-------------+ + | | ESP32 Pin | JTAG Signal | + +===+=======================+=============+ + | 1 | MTDO / GPIO15 | TDO | + +---+-----------------------+-------------+ + | 2 | MTDI / GPIO12 | TDI | + +---+-----------------------+-------------+ + | 3 | MTCK / GPIO13 | TCK | + +---+-----------------------+-------------+ + | 4 | MTMS / GPIO14 | TMS | + +---+-----------------------+-------------+ + +.. only:: esp32s2 + + +---+-----------------------+-------------+ + | | ESP32-S2 Pin | JTAG Signal | + +===+=======================+=============+ + | 1 | MTDO / GPIO40 | TDO | + +---+-----------------------+-------------+ + | 2 | MTDI / GPIO41 | TDI | + +---+-----------------------+-------------+ + | 3 | MTCK / GPIO39 | TCK | + +---+-----------------------+-------------+ + | 4 | MTMS / GPIO42 | TMS | + +---+-----------------------+-------------+ + +JTAG communication will likely fail, if configuration of JTAG pins is changed by user application. If OpenOCD initializes correctly (detects the two Tensilica cores), but loses sync and spews out a lot of DTR/DIR errors when the program is ran, it is likely that the application reconfigures the JTAG pins to something else, or the user forgot to connect Vtar to a JTAG adapter that needed it. .. highlight:: none @@ -243,12 +257,14 @@ Below is an excerpt from series of errors reported by GDB after the application .. _jtag-debugging-tip-at-firmware-issue: -JTAG and ESP32-WROOM-32 AT firmware Compatibility Issue -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. only:: esp32 -The ESP32-WROOM series of modules come pre-flashed with AT firmware. This firmware configures the pins GPIO12 to GPIO15 as SPI slave interface, which makes using JTAG impossible. + JTAG and ESP32-WROOM-32 AT firmware Compatibility Issue + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To make JTAG available, build new firmware that is not using pins GPIO12 to GPIO15 dedicated to JTAG communication. After that, flash the firmware onto your module. See also :ref:`jtag-debugging-tip-jtag-pins-reconfigured`. + The ESP32-WROOM series of modules come pre-flashed with AT firmware. This firmware configures the pins GPIO12 to GPIO15 as SPI slave interface, which makes using JTAG impossible. + + To make JTAG available, build new firmware that is not using pins GPIO12 to GPIO15 dedicated to JTAG communication. After that, flash the firmware onto your module. See also :ref:`jtag-debugging-tip-jtag-pins-reconfigured`. .. _jtag-debugging-tip-reporting-issues: @@ -256,7 +272,7 @@ To make JTAG available, build new firmware that is not using pins GPIO12 to GPIO Reporting issues with OpenOCD / GDB ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In case you encounter a problem with OpenOCD or GDB programs itself and do not find a solution searching available resources on the web, open an issue in the OpenOCD issue tracker under https://github.com/espressif/openocd-esp32/issues. +In case you encounter a problem with OpenOCD or GDB programs itself and do not find a solution searching available resources on the web, open an issue in the OpenOCD issue tracker under https://github.com/espressif/openocd-esp32/issues. 1. In issue report provide details of your configuration: diff --git a/docs/en/api-guides/jtag-debugging/using-debugger.rst b/docs/en/api-guides/jtag-debugging/using-debugger.rst index e537f57d0..4e8644593 100644 --- a/docs/en/api-guides/jtag-debugging/using-debugger.rst +++ b/docs/en/api-guides/jtag-debugging/using-debugger.rst @@ -36,9 +36,9 @@ Once installation is complete, configure debugging session following steps below Configuration of GDB Hardware Debugging - Main tab -6. Click "Debugger" tab. In field "GDB Command" enter ``xtensa-esp32-elf-gdb`` to invoke debugger. +6. Click "Debugger" tab. In field "GDB Command" enter ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb`` to invoke debugger. -7. Change default configuration of "Remote host" by entering ``3333`` under the "Port number". +7. Change default configuration of "Remote host" by entering ``3333`` under the "Port number". Configuration entered in points 6 and 7 is shown on the following picture. @@ -65,7 +65,7 @@ Once installation is complete, configure debugging session following steps below For description of ``program_esp`` command see :ref:`jtag-upload-app-debug`. -9. Under "Load Image and Symbols" uncheck "Load image" option. +9. Under "Load Image and Symbols" uncheck "Load image" option. 10. Further down on the same tab, establish an initial breakpoint to halt CPUs after they are reset by debugger. The plugin will set this breakpoint at the beginning of the function entered under "Set break point at:". Checkout this option and enter ``app_main`` in provided field. @@ -82,9 +82,9 @@ Once installation is complete, configure debugging session following steps below If the "Startup" sequence looks convoluted and respective "Initialization Commands" are not clear to you, check :ref:`jtag-debugging-tip-debugger-startup-commands` for additional explanation. -12. If you previously completed :ref:`jtag-debugging-configuring-esp32-target` steps described above, so the target is running and ready to talk to debugger, go right to debugging by pressing "Debug" button. Otherwise press "Apply" to save changes, go back to :ref:`jtag-debugging-configuring-esp32-target` and return here to start debugging. +12. If you previously completed :ref:`jtag-debugging-configuring-target` steps described above, so the target is running and ready to talk to debugger, go right to debugging by pressing "Debug" button. Otherwise press "Apply" to save changes, go back to :ref:`jtag-debugging-configuring-target` and return here to start debugging. -Once all 1 - 12 configuration steps are satisfied, the new Eclipse perspective called "Debug" will open as shown on example picture below. +Once all 1 - 12 configuration steps are satisfied, the new Eclipse perspective called "Debug" will open as shown on example picture below. .. figure:: ../../../_static/debug-perspective.jpg :align: center @@ -101,7 +101,7 @@ If you are not quite sure how to use GDB, check :ref:`jtag-debugging-examples-ec Command Line ^^^^^^^^^^^^ -1. Begin with completing steps described under :ref:`jtag-debugging-configuring-esp32-target`. This is prerequisite to start a debugging session. +1. Begin with completing steps described under :ref:`jtag-debugging-configuring-target`. This is prerequisite to start a debugging session. .. highlight:: bash @@ -124,7 +124,7 @@ Command Line thb app_main c - Save this file in current directory. + Save this file in current directory. For more details what's inside ``gdbinit`` file, see :ref:`jtag-debugging-tip-debugger-startup-commands` @@ -134,7 +134,7 @@ Command Line :: - xtensa-esp32-elf-gdb -x gdbinit build/blink.elf + xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -x gdbinit build/blink.elf .. highlight:: none @@ -142,14 +142,14 @@ Command Line :: - user-name@computer-name:~/esp/blink$ xtensa-esp32-elf-gdb -x gdbinit build/blink.elf + user-name@computer-name:~/esp/blink$ xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -x gdbinit build/blink.elf GNU gdb (crosstool-NG crosstool-ng-1.22.0-61-gab8375a) 7.10 Copyright (C) 2015 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Type "show copying" and "show warranty" for details. - This GDB was configured as "--host=x86_64-build_pc-linux-gnu --target=xtensa-esp32-elf". + This GDB was configured as "--host=x86_64-build_pc-linux-gnu --target=xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf". Type "show configuration" for configuration details. For bug reporting instructions, please see: . @@ -158,20 +158,20 @@ Command Line For help, type "help". Type "apropos word" to search for commands related to "word"... Reading symbols from build/blink.elf...done. - 0x400d10d8 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/components/esp32/./freertos_hooks.c:52 + 0x400d10d8 in esp_vApplicationIdleHook () at /home/user-name/esp/esp-idf/components/{IDF_TARGET_PATH_NAME}/./freertos_hooks.c:52 52 asm("waiti 0"); - JTAG tap: esp32.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) - JTAG tap: esp32.slave tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) - esp32: Debug controller was reset (pwrstat=0x5F, after clear 0x0F). - esp32: Core was reset (pwrstat=0x5F, after clear 0x0F). - Target halted. PRO_CPU: PC=0x5000004B (active) APP_CPU: PC=0x00000000 - esp32: target state: halted - esp32: Core was reset (pwrstat=0x1F, after clear 0x0F). - Target halted. PRO_CPU: PC=0x40000400 (active) APP_CPU: PC=0x40000400 - esp32: target state: halted + JTAG tap: {IDF_TARGET_PATH_NAME}.cpu0 tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) + JTAG tap: {IDF_TARGET_PATH_NAME}.slave tap/device found: 0x120034e5 (mfg: 0x272 (Tensilica), part: 0x2003, ver: 0x1) + {IDF_TARGET_PATH_NAME}: Debug controller was reset (pwrstat=0x5F, after clear 0x0F). + {IDF_TARGET_PATH_NAME}: Core was reset (pwrstat=0x5F, after clear 0x0F). + Target halted. PRO_CPU: PC=0x5000004B (active) APP_CPU: PC=0x00000000 + {IDF_TARGET_PATH_NAME}: target state: halted + {IDF_TARGET_PATH_NAME}: Core was reset (pwrstat=0x1F, after clear 0x0F). + Target halted. PRO_CPU: PC=0x40000400 (active) APP_CPU: PC=0x40000400 + {IDF_TARGET_PATH_NAME}: target state: halted Hardware assisted breakpoint 1 at 0x400db717: file /home/user-name/esp/blink/main/./blink.c, line 43. 0x0: 0x00000000 - Target halted. PRO_CPU: PC=0x400DB717 (active) APP_CPU: PC=0x400D10D8 + Target halted. PRO_CPU: PC=0x400DB717 (active) APP_CPU: PC=0x400D10D8 [New Thread 1073428656] [New Thread 1073413708] [New Thread 1073431316] @@ -180,10 +180,10 @@ Command Line [New Thread 1073432196] [New Thread 1073411552] [Switching to Thread 1073411996] - + Temporary breakpoint 1, app_main () at /home/user-name/esp/blink/main/./blink.c:43 43 xTaskCreate(&blink_task, "blink_task", 512, NULL, 5, NULL); - (gdb) + (gdb) Note the third line from bottom that shows debugger halting at breakpoint established in ``gdbinit`` file at function ``app_main()``. Since the processor is halted, the LED should not be blinking. If this is what you see as well, you are ready to start debugging. diff --git a/docs/en/api-guides/linker-script-generation.rst b/docs/en/api-guides/linker-script-generation.rst index 258a24994..3c377aef3 100644 --- a/docs/en/api-guides/linker-script-generation.rst +++ b/docs/en/api-guides/linker-script-generation.rst @@ -21,15 +21,15 @@ This section presents a guide for quickly placing code/data to RAM and RTC memor For this guide, suppose we have the following:: - components/ - - my_component/ + - my_component/ - CMakeLists.txt - component.mk - - Kconfig + - Kconfig - src/ - - my_src1.c - - my_src2.c - - my_src3.c - - my_linker_fragment_file.lf + - my_src1.c + - my_src2.c + - my_src3.c + - my_linker_fragment_file.lf - a component named ``my_component`` that is archived as library ``libmy_component.a`` during build @@ -65,7 +65,7 @@ created linker fragment file. .. code-block:: cmake - # file paths relative to CMakeLists.txt + # file paths relative to CMakeLists.txt idf_component_register(... LDFRAGMENTS "path/to/linker_fragment_file.lf" "path/to/another_linker_fragment_file.lf" ... @@ -86,7 +86,7 @@ It is possible to specify placements at the following levels of granularity: Placing object files """""""""""""""""""" -Suppose the entirety of ``my_src1.o`` is performance-critical, so it is desirable to place it in RAM. +Suppose the entirety of ``my_src1.o`` is performance-critical, so it is desirable to place it in RAM. On the other hand, the entirety of ``my_src2.o`` contains symbols needed coming out of deep sleep, so it needs to be put under RTC memory. In the the linker fragment file, we can write: @@ -99,7 +99,7 @@ In the the linker fragment file, we can write: my_src2 (rtc) # places all my_src2 code/ data and read-only data under RTC fast memory/RTC slow memory What happens to ``my_src3.o``? Since it is not specified, default placements are used for ``my_src3.o``. More on default placements -:ref:`here`. +:ref:`here`. Placing symbols """""""""""""""" @@ -215,7 +215,7 @@ As the name suggests, it is where code and data are usually placed, i.e. code/co placed in RAM, etc. More on the default scheme :ref:`here`. .. note:: - For an example of an ESP-IDF component using the linker script generation mechanism, see :component_file:`freertos/CMakeLists.txt`. + For an example of an ESP-IDF component using the linker script generation mechanism, see :component_file:`freertos/CMakeLists.txt`. ``freertos`` uses this to place its object files to the instruction RAM for performance reasons. This marks the end of the quick start guide. The following text discusses the internals of the mechanism in a little bit more detail. @@ -226,7 +226,7 @@ Linker Script Generation Internals Linking is the last step in the process of turning C/C++ source files into an executable. It is performed by the toolchain's linker, and accepts linker scripts which specify code/data placements, among other things. With the linker script generation mechanism, this process is no different, except -that the linker script passed to the linker is dynamically generated from: (1) the collected :ref:`linker fragment files` and +that the linker script passed to the linker is dynamically generated from: (1) the collected :ref:`linker fragment files` and (2) :ref:`linker script template`. .. note:: @@ -240,7 +240,7 @@ Linker Fragment Files As mentioned in the quick start guide, fragment files are simple text files with the ``.lf`` extension containing the desired placements. This is a simplified description of what fragment files contain, however. What fragment files actually contain are 'fragments'. Fragments are entities which contain pieces of information which, when put together, form -placement rules that tell where to place sections of object files in the output binary. There are three types of fragments: :ref:`sections`, +placement rules that tell where to place sections of object files in the output binary. There are three types of fragments: :ref:`sections`, :ref:`scheme` and :ref:`mapping`. Grammar @@ -276,7 +276,7 @@ The three fragment types share a common grammar: **Condition Checking** Condition checking enable the linker script generation to be configuration-aware. Depending on whether expressions involving configuration values -are true or not, a particular set of values for a key can be used. The evaluation uses ``eval_string`` from :idf_file:`tools/kconfig_new/kconfiglib.py` +are true or not, a particular set of values for a key can be used. The evaluation uses ``eval_string`` from :idf_file:`tools/kconfig_new/kconfiglib.py` and adheres to its required syntax and limitations. Supported operators are as follows: - comparison @@ -331,7 +331,7 @@ for both key values and entire fragments. The two sample fragments below are equ **Comments** Comment in linker fragment files begin with ``#``. Like in other languages, comment are used to provide helpful descriptions and documentation -and are ignored during processing. +and are ignored during processing. Compatibility with ESP-IDF v3.x Linker Script Fragment Files """""""""""""""""""""""""""""""""""""""""""""""""""""""""""" @@ -426,10 +426,10 @@ will be generated for the target ``flash_text``. These catch-all rules then effectively serve as fallback rules for those whose mappings were not specified. -.. note:: - The ``default scheme`` is defined in :component:`esp32/ld/esp32_fragments.lf`. The ``noflash`` and ``rtc`` scheme fragments which are - built-in schemes referenced in the quick start guide are also defined in this file. +The ``default scheme`` is defined in :component:`{IDF_TARGET_PATH_NAME}/ld/{IDF_TARGET_PATH_NAME}_fragments.lf`. The ``noflash`` and ``rtc`` scheme fragments which are +built-in schemes referenced in the quick start guide are also defined in this file. + .. _ldgen-mapping-fragment : @@ -589,9 +589,5 @@ Then the corresponding excerpt from the generated linker script will be as follo it too is placed wherever ``iram0_text`` is referenced by a marker. Since it is a rule generated from the default scheme, it comes first among all other rules collected under the same target name. -.. note:: - - The linker script template currently used is :component:`esp32/ld/esp32.project.ld.in`, specified by the ``esp32`` component; the + The linker script template currently used is :component:`{IDF_TARGET_PATH_NAME}/ld/{IDF_TARGET_PATH_NAME}.project.ld.in`, specified by the ``{IDF_TARGET_PATH_NAME}`` component; the generated output script is put under its build directory. - - diff --git a/docs/en/api-guides/partition-tables.rst b/docs/en/api-guides/partition-tables.rst index 91fe17e0e..c0cdea82a 100644 --- a/docs/en/api-guides/partition-tables.rst +++ b/docs/en/api-guides/partition-tables.rst @@ -5,7 +5,7 @@ Partition Tables Overview -------- -A single ESP32'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 `) 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 (:ref:`default offset `) 0x8000 in the flash. Partition table length is 0xC00 bytes (maximum 95 partition table entries). An MD5 checksum, which is used for checking the integrity of the partition table, is appended after the table data. If the partition table is signed due to `secure boot`, the signature is appended after the partition table. @@ -23,7 +23,7 @@ Built-in Partition Tables Here is the summary printed for the "Single factory app, no OTA" configuration:: - # Espressif ESP32 Partition Table + # Espressif ESP Partition Table # Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x6000, phy_init, data, phy, 0xf000, 0x1000, @@ -34,7 +34,7 @@ Here is the summary printed for the "Single factory app, no OTA" configuration:: Here is the summary printed for the "Factory app, two OTA definitions" configuration:: - # Espressif ESP32 Partition Table + # Espressif ESP Partition Table # Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x4000, otadata, data, ota, 0xd000, 0x2000, @@ -69,7 +69,7 @@ The CSV format is the same format as printed in the summaries shown above. Howev Name field ~~~~~~~~~~ -Name field can be any meaningful name. It is not significant to the ESP32. Names longer than 16 characters will be truncated. +Name field can be any meaningful name. It is not significant to the {IDF_TARGET_NAME}. Names longer than 16 characters will be truncated. Type field ~~~~~~~~~~ @@ -136,7 +136,7 @@ Only one flag is currently supported, ``encrypted``. If this field is set to ``e Generating Binary Partition Table --------------------------------- -The partition table which is flashed to the ESP32 is in a binary format, not CSV. The tool :component_file:`partition_table/gen_esp32part.py` is used to convert between CSV and binary formats. +The partition table which is flashed to the {IDF_TARGET_NAME} is in a binary format, not CSV. The tool :component_file:`partition_table/gen_esp32part.py` is used to convert between CSV and binary formats. If you configure the partition table CSV name in the project configuration (``idf.py menuconfig``) and then build the project or run ``idf.py partition_table``, this conversion is done as part of the build process. diff --git a/docs/en/api-guides/romconsole.rst b/docs/en/api-guides/romconsole.rst index d33ca0000..e34d8ca9d 100644 --- a/docs/en/api-guides/romconsole.rst +++ b/docs/en/api-guides/romconsole.rst @@ -1,9 +1,9 @@ -***************** -ESP32 ROM console -***************** +***************************** +{IDF_TARGET_NAME} ROM console +***************************** -When an ESP32 is unable to boot from flash ROM (and the fuse disabling it hasn't been blown), it boots into a rom console. The console -is based on TinyBasic, and statements entered should be in the form of BASIC statements. As is common in the BASIC language, without a +When an {IDF_TARGET_NAME} is unable to boot from flash ROM (and the fuse disabling it hasn't been blown), it boots into a rom console. The console +is based on TinyBasic, and statements entered should be in the form of BASIC statements. As is common in the BASIC language, without a preceeding line number, commands entered are executed immediately; lines with a prefixed line number are stored as part of a program. Full list of supported statements and functions @@ -12,7 +12,7 @@ Full list of supported statements and functions System ------ -- BYE - *exits Basic, reboots ESP32, retries booting from flash* +- BYE - *exits Basic, reboots and retries booting from flash* - END - *stops execution from the program, also "STOP"* - MEM - *displays memory usage statistics* - NEW - *clears the current program* diff --git a/docs/en/api-guides/tools/idf-monitor.rst b/docs/en/api-guides/tools/idf-monitor.rst index 2a5022ef0..b5cd8bb4e 100644 --- a/docs/en/api-guides/tools/idf-monitor.rst +++ b/docs/en/api-guides/tools/idf-monitor.rst @@ -89,11 +89,11 @@ IDF Monitor adds more details to the dump:: 0x400dbf56: still_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:47 0x400dbf5e: dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:42 0x400dbf82: app_main at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:33 - 0x400d071d: main_task at /home/gus/esp/32/idf/components/esp32/./cpu_start.c:254 + 0x400d071d: main_task at /home/gus/esp/32/idf/components/{IDF_TARGET_PATH_NAME}/./cpu_start.c:254 To decode each address, IDF Monitor runs the following command in the background:: - xtensa-esp32-elf-addr2line -pfiaC -e build/PROJECT.elf ADDRESS + xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-addr2line -pfiaC -e build/PROJECT.elf ADDRESS Launching GDB with GDBStub @@ -103,19 +103,13 @@ By default, if esp-idf crashes, the panic handler prints relevant registers and Optionally, the panic handler can be configured to run GDBStub, the tool which can communicate with GDB_ project debugger. GDBStub allows to read memory, examine call stack frames and variables, etc. It is not as versatile as JTAG debugging, but this method does not require any special hardware. -.. only:: esp32 - - To enable GDBStub, open the project configuration menu (``idf.py menuconfig``) and set :ref:`CONFIG_ESP32_PANIC` to ``Invoke GDBStub``. - -.. only:: esp32s2 - - To enable GDBStub, open the project configuration menu (``idf.py menuconfig``) and set :ref:`CONFIG_ESP32S2_PANIC` to ``Invoke GDBStub``. +To enable GDBStub, open the project configuration menu (``idf.py menuconfig``) and set :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_PANIC` to ``Invoke GDBStub``. In this case, if the panic handler is triggered, as soon as IDF Monitor sees that GDBStub has loaded, it automatically pauses serial monitoring and runs GDB with necessary arguments. After GDB exits, the board is reset via the RTS serial line. If this line is not connected, please reset the board manually by pressing its Reset button. In the background, IDF Monitor runs the following command:: - xtensa-esp32-elf-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf + xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf :idf_target:`Hello NAME chip` Output Filtering @@ -134,7 +128,7 @@ For example, ``PRINT_FILTER="tag1:W"`` matches and prints only the outputs writt which can be useful for adjusting the filtering options without recompiling the application. -Your app tags must not contain spaces, asterisks ``*``, +Your app tags must not contain spaces, asterisks ``*``, and semicolons ``:`` to be compatible with the output filtering feature. If the last line of the output in your app is not followed by a carriage return, the output filtering might get confused, i.e., the monitor starts to print the line and later finds out that the line should not have been written. This is a known issue and can be avoided by always adding a carriage return (especially when no output follows immediately afterwards). diff --git a/docs/en/api-guides/ulp.rst b/docs/en/api-guides/ulp.rst index 5de0e49f9..a9197465f 100644 --- a/docs/en/api-guides/ulp.rst +++ b/docs/en/api-guides/ulp.rst @@ -6,8 +6,8 @@ ULP Coprocessor programming .. toctree:: :maxdepth: 1 - Instruction set reference for ESP32 ULP - Instruction set reference for ESP32-S2 ULP + :esp32: Instruction set reference for ESP32 ULP + :esp32s2: Instruction set reference for ESP32-S2 ULP Programming using macros (legacy) @@ -31,7 +31,7 @@ To compile the ULP code as part of the component, the following steps must be ta 1. The ULP code, written in assembly, must be added to one or more files with `.S` extension. These files must be placed into a separate directory inside the component directory, for instance `ulp/`. -.. note: When registering the component (via ``idf_component_register``), this directory should not be added to the ``SRC_DIRS`` argument. The logic behind this is that the ESP-IDF build system will compile files found in ``SRC_DIRS`` based on their extensions. For ``.S`` files, ``xtensa-esp32-elf-as`` assembler is used. This is not desirable for ULP assembly files, so the easiest way to achieve the distinction is by placing ULP assembly files into a separate directory. The ULP assembly source files should also **not** be added to ``SRCS`` for the same reason. See the step below for how to properly add ULP assembly source files. +.. note: When registering the component (via ``idf_component_register``), this directory should not be added to the ``SRC_DIRS`` argument. The logic behind this is that the ESP-IDF build system will compile files found in ``SRC_DIRS`` based on their extensions. For ``.S`` files, ``xtensa-{IDF_TARGET_NAME}-elf-as`` assembler is used. This is not desirable for ULP assembly files, so the easiest way to achieve the distinction is by placing ULP assembly files into a separate directory. The ULP assembly source files should also **not** be added to ``SRCS`` for the same reason. See the step below for how to properly add ULP assembly source files. 2. Call ``ulp_embed_binary`` from the component CMakeLists.txt after registration. For example:: @@ -44,11 +44,11 @@ To compile the ULP code as part of the component, the following steps must be ta ulp_embed_binary(${ulp_app_name} ${ulp_s_sources} ${ulp_exp_dep_srcs}) - The first argument to ``ulp_embed_binary`` specifies the ULP binary name. The name specified here will also be used by other generated artifacts - such as the ELF file, map file, header file and linker export file. The second argument specifies the ULP assembly source files. - Finally, the third argument specifies the list of component source files which include the header file to be generated. - This list is needed to build the dependencies correctly and ensure that the generated header file will be created before any of these files are compiled. - See section below for the concept of generated header files for ULP applications. + The first argument to ``ulp_embed_binary`` specifies the ULP binary name. The name specified here will also be used by other generated artifacts + such as the ELF file, map file, header file and linker export file. The second argument specifies the ULP assembly source files. + Finally, the third argument specifies the list of component source files which include the header file to be generated. + This list is needed to build the dependencies correctly and ensure that the generated header file will be created before any of these files are compiled. + See section below for the concept of generated header files for ULP applications. 3. Build the application as usual (e.g. `idf.py app`) diff --git a/docs/en/api-guides/ulp_instruction_set.rst b/docs/en/api-guides/ulp_instruction_set.rst index 6eec2f4b5..fee3a76db 100644 --- a/docs/en/api-guides/ulp_instruction_set.rst +++ b/docs/en/api-guides/ulp_instruction_set.rst @@ -1,7 +1,7 @@ ESP32 ULP coprocessor instruction set ===================================== -This document provides details about the instructions used by ESP32 ULP coprocessor assembler. +This document provides details about the instructions used by {IDF_TARGET_NAME} ULP coprocessor assembler. ULP coprocessor has 4 16-bit general purpose registers, labeled R0, R1, R2, R3. It also has an 8-bit counter register (stage_cnt) which can be used to implement loops. Stage count regiter is accessed using special instructions. @@ -13,7 +13,7 @@ The instruction syntax is case insensitive. Upper and lower case letters can be Note about addressing --------------------- -ESP32 ULP coprocessor's JUMP, ST, LD instructions which take register as an argument (jump address, store/load base address) expect the argument to be expressed in 32-bit words. +{IDF_TARGET_NAME} ULP coprocessor's JUMP, ST, LD instructions which take register as an argument (jump address, store/load base address) expect the argument to be expressed in 32-bit words. Consider the following example program:: @@ -160,9 +160,9 @@ Note that when accessing RTC memories and RTC registers, ULP coprocessor has low **Examples**:: 1: SUB R1, R2, R3 //R1 = R2 - R3 - + 2: sub R1, R2, 0x1234 //R1 = R2 - 0x1234 - + 3: .set value1, 0x03 //constant value1=0x03 SUB R1, R2, value1 //R1 = R2 - value1 4: .global label //declaration of variable label @@ -211,7 +211,7 @@ Note that when accessing RTC memories and RTC registers, ULP coprocessor has low **Syntax** **OR** *Rdst, Rsrc1, Rsrc2* - + **OR** *Rdst, Rsrc1, imm* **Operands** @@ -222,12 +222,12 @@ Note that when accessing RTC memories and RTC registers, ULP coprocessor has low **Cycles** 2 cycles to execute, 4 cycles to fetch next instruction - + **Description** The instruction does logical OR of a source register and another source register or 16-bit signed value and stores result to the destination register. **Examples**:: - + 1: OR R1, R2, R3 //R1 = R2 \| R3 2: OR R1, R2, 0x1234 //R1 = R2 \| 0x1234 @@ -255,7 +255,7 @@ Note that when accessing RTC memories and RTC registers, ULP coprocessor has low - *Rsrc1* - Register R[0..3] - *Rsrc2* - Register R[0..3] - *Imm* - 16-bit signed value - + **Cycles** 2 cycles to execute, 4 cycles to fetch next instruction @@ -373,7 +373,7 @@ Note that when accessing RTC memories and RTC registers, ULP coprocessor has low **Examples**:: 1: ST R1, R2, 0x12 //MEM[R2+0x12] = R1 - + 2: .data //Data section definition Addr1: .word 123 // Define label Addr1 16 bit .set offs, 0x00 // Define constant offs @@ -392,9 +392,9 @@ Note that when accessing RTC memories and RTC registers, ULP coprocessor has low **Operands** *Rdst* – Register R[0..3], destination - + *Rsrc* – Register R[0..3], holds address of destination, in 32-bit words - + *Offset* – 10-bit signed value, offset in bytes **Cycles** @@ -481,8 +481,8 @@ Note that when accessing RTC memories and RTC registers, ULP coprocessor has low - *EQ* (equal) – jump if value in R0 == threshold - *LT* (less than) – jump if value in R0 < threshold - *LE* (less or equal) – jump if value in R0 <= threshold - - *GT* (greater than) – jump if value in R0 > threshold - - *GE* (greater or equal) – jump if value in R0 >= threshold + - *GT* (greater than) – jump if value in R0 > threshold + - *GE* (greater or equal) – jump if value in R0 >= threshold **Cycles** @@ -551,7 +551,7 @@ Note that when accessing RTC memories and RTC registers, ULP coprocessor has low next: // JUMPS target, threshold, GT is implemented as: - + JUMPS next, threshold, LE JUMPS target, threshold, GE next: diff --git a/docs/en/api-guides/unit-tests.rst b/docs/en/api-guides/unit-tests.rst index 7eea5a4e3..bfc1000e3 100644 --- a/docs/en/api-guides/unit-tests.rst +++ b/docs/en/api-guides/unit-tests.rst @@ -1,5 +1,5 @@ -Unit Testing in ESP32 -============================= +Unit Testing in {IDF_TARGET_NAME} +================================= :link_to_translation:`zh_CN:[中文]` ESP-IDF comes with a unit test application that is based on the Unity - unit test framework. Unit tests are integrated in the ESP-IDF repository and are placed in the ``test`` subdirectories of each component respectively. @@ -98,7 +98,7 @@ Once the signal is sent from DUT2, you need to press "Enter" on DUT1, then DUT1 Multi-stage Test Cases ----------------------- -The normal test cases are expected to finish without reset (or only need to check if reset happens). Sometimes we expect to run some specific tests after certain kinds of reset. +The normal test cases are expected to finish without reset (or only need to check if reset happens). Sometimes we expect to run some specific tests after certain kinds of reset. For example, we expect to test if the reset reason is correct after a wakeup from deep sleep. We need to create a deep-sleep reset first and then check the reset reason. To support this, we can define multi-stage test cases, to group a set of test functions:: @@ -114,7 +114,7 @@ To support this, we can define multi-stage test cases, to group a set of test fu TEST_ASSERT(reason == DEEPSLEEP_RESET); } - TEST_CASE_MULTIPLE_STAGES("reset reason check for deepsleep", "[esp32]", trigger_deepsleep, check_deepsleep_reset_reason); + TEST_CASE_MULTIPLE_STAGES("reset reason check for deepsleep", "[{IDF_TARGET_PATH_NAME}]", trigger_deepsleep, check_deepsleep_reset_reason); Multi-stage test cases present a group of test functions to users. It needs user interactions (select cases and select different stages) to run the case. @@ -130,19 +130,19 @@ Change into ``tools/unit-test-app`` directory to configure and build it: * ``idf.py menuconfig`` - configure unit test app. * ``idf.py -T all build`` - build unit test app with tests for each component having tests in the ``test`` subdirectory. -* ``idf.py -T xxx build`` - build unit test app with tests for specific components. +* ``idf.py -T xxx build`` - build unit test app with tests for specific components. * ``idf.py -T all -E xxxbuild`` - build unit test app with all unit tests, except for unit tests of some components. (For instance: ``idf.py -T all -E ulp mbedtls build`` - build all unit tests exludes ``ulp`` and ``mbedtls`` components). When the build finishes, it will print instructions for flashing the chip. You can simply run ``idf.py flash`` to flash all build output. -You can also run ``idf.py -T all flash`` or ``idf.py -T xxx flash`` to build and flash. Everything needed will be rebuilt automatically before flashing. +You can also run ``idf.py -T all flash`` or ``idf.py -T xxx flash`` to build and flash. Everything needed will be rebuilt automatically before flashing. Use menuconfig to set the serial port for flashing. Running Unit Tests ------------------ -After flashing reset the ESP32 and it will boot the unit test app. +After flashing reset the {IDF_TARGET_NAME} and it will boot the unit test app. When unit test app is idle, press "Enter" will make it print test menu with all available tests:: @@ -168,7 +168,7 @@ When unit test app is idle, press "Enter" will make it print test menu with all (17) "SPI Master no response when switch from host1 (HSPI) to host2 (VSPI)" [spi] (18) "SPI Master DMA test, TX and RX in different regions" [spi] (19) "SPI Master DMA test: length, start, not aligned" [spi] - (20) "reset reason check for deepsleep" [esp32][test_env=UT_T2_1][multi_stage] + (20) "reset reason check for deepsleep" [{IDF_TARGET_PATH_NAME}][test_env=UT_T2_1][multi_stage] (1) "trigger_deepsleep" (2) "check_deepsleep_reset_reason" @@ -176,7 +176,7 @@ The normal case will print the case name and description. Master-slave cases wil Test cases can be run by inputting one of the following: -- Test case name in quotation marks to run a single test case +- Test case name in quotation marks to run a single test case - Test case index to run a single test case @@ -223,8 +223,8 @@ between runs and between different builds. A technique for eliminating for some variability is to place code and data in instruction or data RAM (IRAM/DRAM), respectively. The CPU can access IRAM and DRAM directly, eliminating the cache out of the equation. However, this might not always be viable as the size of IRAM and DRAM is limited. -The cache compensated timer is an alternative to placing the code/data to be benchmarked in IRAM/DRAM. This timer uses the processor's internal event counters in order to determine the amount -of time spent on waiting for code/data in case of a cache miss, then subtract that from the recorded wall time. +The cache compensated timer is an alternative to placing the code/data to be benchmarked in IRAM/DRAM. This timer uses the processor's internal event counters in order to determine the amount +of time spent on waiting for code/data in case of a cache miss, then subtract that from the recorded wall time. .. code-block:: c diff --git a/docs/en/api-guides/wifi.rst b/docs/en/api-guides/wifi.rst index b4f755bac..140c61b69 100644 --- a/docs/en/api-guides/wifi.rst +++ b/docs/en/api-guides/wifi.rst @@ -1,8 +1,8 @@ Wi-Fi Driver ============= -ESP32 Wi-Fi Feature List -------------------------- +{IDF_TARGET_NAME} Wi-Fi Feature List +------------------------------------ - Support Station-only mode, AP-only mode, Station/AP-coexistence mode - Support IEEE-802.11B, IEEE-802.11G, IEEE802.11N and APIs to configure the protocol mode - Support WPA/WPA2/WPA2-Enterprise and WPS @@ -21,7 +21,7 @@ How To Write a Wi-Fi Application Preparation +++++++++++ -Generally, the most effective way to begin your own Wi-Fi application is to select an example which is similar to your own application, and port the useful part into your project. It is not a MUST but it is strongly recommended that you take some time to read this article first, especially if you want to program a robust Wi-Fi application. This article is supplementary to the Wi-Fi APIs/Examples. It describes the principles of using the Wi-Fi APIs, the limitations of the current Wi-Fi API implementation, and the most common pitfalls in using Wi-Fi. This article also reveals some design details of the Wi-Fi driver. We recommend that you become familiar at least with the following sections: <`ESP32 Wi-Fi API Error Code`_>, <`ESP32 Wi-Fi Programming Model`_>, and <`ESP32 Wi-Fi Event Description`_>. +Generally, the most effective way to begin your own Wi-Fi application is to select an example which is similar to your own application, and port the useful part into your project. It is not a MUST but it is strongly recommended that you take some time to read this article first, especially if you want to program a robust Wi-Fi application. This article is supplementary to the Wi-Fi APIs/Examples. It describes the principles of using the Wi-Fi APIs, the limitations of the current Wi-Fi API implementation, and the most common pitfalls in using Wi-Fi. This article also reveals some design details of the Wi-Fi driver. We recommend that you become familiar at least with the following sections: <`{IDF_TARGET_NAME} Wi-Fi API Error Code`_>, <`{IDF_TARGET_NAME} Wi-Fi Programming Model`_>, and <`{IDF_TARGET_NAME} Wi-Fi Event Description`_>. Setting Wi-Fi Compile-time Options ++++++++++++++++++++++++++++++++++++ @@ -29,28 +29,28 @@ Refer to <`Wi-Fi Menuconfig`_> Init Wi-Fi +++++++++++ -Refer to <`ESP32 Wi-Fi Station General Scenario`_>, <`ESP32 Wi-Fi AP General Scenario`_>. +Refer to <`{IDF_TARGET_NAME} Wi-Fi Station General Scenario`_>, <`{IDF_TARGET_NAME} Wi-Fi AP General Scenario`_>. Start/Connect Wi-Fi ++++++++++++++++++++ -Refer to <`ESP32 Wi-Fi Station General Scenario`_>, <`ESP32 Wi-Fi AP General Scenario`_>. +Refer to <`{IDF_TARGET_NAME} Wi-Fi Station General Scenario`_>, <`{IDF_TARGET_NAME} Wi-Fi AP General Scenario`_>. Event-Handling ++++++++++++++ -Generally, it is easy to write code in "sunny-day" scenarios, such as <`WIFI_EVENT_STA_START`_>, <`WIFI_EVENT_STA_CONNECTED`_> etc. The hard part is to write routines in "rainy-day" scenarios, such as <`WIFI_EVENT_STA_DISCONNECTED`_> etc. Good handling of "rainy-day" scenarios is fundamental to robust Wi-Fi applications. Refer to <`ESP32 Wi-Fi Event Description`_>, <`ESP32 Wi-Fi Station General Scenario`_>, <`ESP32 Wi-Fi AP General Scenario`_>. See also :doc:`an overview of event handling in ESP-IDF`. +Generally, it is easy to write code in "sunny-day" scenarios, such as <`WIFI_EVENT_STA_START`_>, <`WIFI_EVENT_STA_CONNECTED`_> etc. The hard part is to write routines in "rainy-day" scenarios, such as <`WIFI_EVENT_STA_DISCONNECTED`_> etc. Good handling of "rainy-day" scenarios is fundamental to robust Wi-Fi applications. Refer to <`{IDF_TARGET_NAME} Wi-Fi Event Description`_>, <`{IDF_TARGET_NAME} Wi-Fi Station General Scenario`_>, <`{IDF_TARGET_NAME} Wi-Fi AP General Scenario`_>. See also :doc:`an overview of event handling in ESP-IDF`. -Write Error-Recovery Routines Correctly at All Times +Write Error-Recovery Routines Correctly at All Times ++++++++++++++++++++++++++++++++++++++++++++++++++++ -Just like the handling of "rainy-day" scenarios, a good error-recovery routine is also fundamental to robust Wi-Fi applications. Refer to <`ESP32 Wi-Fi API Error Code`_> +Just like the handling of "rainy-day" scenarios, a good error-recovery routine is also fundamental to robust Wi-Fi applications. Refer to <`{IDF_TARGET_NAME} Wi-Fi API Error Code`_> -ESP32 Wi-Fi API Error Code ---------------------------- -All of the ESP32 Wi-Fi APIs have well-defined return values, namely, the error code. The error code can be categorized into: +{IDF_TARGET_NAME} Wi-Fi API Error Code +-------------------------------------- +All of the {IDF_TARGET_NAME} Wi-Fi APIs have well-defined return values, namely, the error code. The error code can be categorized into: - No errors, e.g. ESP_OK means that the API returns successfully - Recoverable errors, such as ESP_ERR_NO_MEM, etc. - - Non-recoverable, non-critical errors - - Non-recoverable, critical errors + - Non-recoverable, non-critical errors + - Non-recoverable, critical errors Whether the error is critical or not depends on the API and the application scenario, and it is defined by the API user. @@ -63,8 +63,8 @@ Whether the error is critical or not depends on the API and the application scen In esp_err.h, ESP_ERROR_CHECK checks the return values. It is a rather commonplace error-handling code and can be used as the default error-handling code in the application development phase. However, we strongly recommend that API users write their own error-handling code. -ESP32 Wi-Fi API Parameter Initialization ------------------------------------------- +{IDF_TARGET_NAME} Wi-Fi API Parameter Initialization +---------------------------------------------------- When initializing struct parameters for the API, one of two approaches should be followed: - explicitly set all fields of the parameter or @@ -74,9 +74,9 @@ Initializing or getting the entire structure is very important because most of t .. _wifi-programming-model: -ESP32 Wi-Fi Programming Model ------------------------------ -The ESP32 Wi-Fi programming model is depicted as follows: +{IDF_TARGET_NAME} Wi-Fi Programming Model +----------------------------------------- +The {IDF_TARGET_NAME} Wi-Fi programming model is depicted as follows: .. blockdiag:: :caption: Wi-Fi Programming Model @@ -124,8 +124,8 @@ The Wi-Fi driver can be considered a black box that knows nothing about high-lay Wi-Fi event handling is based on the :doc:`esp_event library <../api-reference/system/esp_event>`. Events are sent by the Wi-Fi driver to the :ref:`default event loop `. Application may handle these events in callbacks registered using :cpp:func:`esp_event_handler_register`. Wi-Fi events are also handled by :doc:`esp_netif component <../api-reference/network/esp_netif>` to provide a set of default behaviors. For example, when Wi-Fi station connects to an AP, esp_netif will automatically start the DHCP client (by default). -ESP32 Wi-Fi Event Description ------------------------------------- +{IDF_TARGET_NAME} Wi-Fi Event Description +----------------------------------------- WIFI_EVENT_WIFI_READY ++++++++++++++++++++++++++++++++++++ @@ -137,15 +137,15 @@ The scan-done event is triggered by esp_wifi_scan_start() and will arise in the - The scan is completed, e.g., the target AP is found successfully, or all channels have been scanned. - The scan is stopped by esp_wifi_scan_stop(). - - The esp_wifi_scan_start() is called before the scan is completed. A new scan will override the current scan and a scan-done event will be generated. + - The esp_wifi_scan_start() is called before the scan is completed. A new scan will override the current scan and a scan-done event will be generated. The scan-done event will not arise in the following scenarios: - It is a blocked scan. - The scan is caused by esp_wifi_connect(). -Upon receiving this event, the event task does nothing. The application event callback needs to call esp_wifi_scan_get_ap_num() and esp_wifi_scan_get_ap_records() to fetch the scanned AP list and trigger the Wi-Fi driver to free the internal memory which is allocated during the scan **(do not forget to do this)**! -Refer to 'ESP32 Wi-Fi Scan' for a more detailed description. +Upon receiving this event, the event task does nothing. The application event callback needs to call esp_wifi_scan_get_ap_num() and esp_wifi_scan_get_ap_records() to fetch the scanned AP list and trigger the Wi-Fi driver to free the internal memory which is allocated during the scan **(do not forget to do this)**! +Refer to '{IDF_TARGET_NAME} Wi-Fi Scan' for a more detailed description. WIFI_EVENT_STA_START ++++++++++++++++++++++++++++++++++++ @@ -158,14 +158,14 @@ If esp_wifi_stop() returns ESP_OK and the current Wi-Fi mode is Station or AP+St WIFI_EVENT_STA_CONNECTED ++++++++++++++++++++++++++++++++++++ If esp_wifi_connect() returns ESP_OK and the station successfully connects to the target AP, the connection event will arise. Upon receiving this event, the event task starts the DHCP client and begins the DHCP process of getting the IP address. Then, the Wi-Fi driver is ready for sending and receiving data. This moment is good for beginning the application work, provided that the application does not depend on LwIP, namely the IP address. However, if the application is LwIP-based, then you need to wait until the *got ip* event comes in. - + WIFI_EVENT_STA_DISCONNECTED ++++++++++++++++++++++++++++++++++++ This event can be generated in the following scenarios: - When esp_wifi_disconnect(), or esp_wifi_stop(), or esp_wifi_deinit(), or esp_wifi_restart() is called and the station is already connected to the AP. - When esp_wifi_connect() is called, but the Wi-Fi driver fails to set up a connection with the AP due to certain reasons, e.g. the scan fails to find the target AP, authentication times out, etc. If there are more than one AP with the same SSID, the disconnected event is raised after the station fails to connect all of the found APs. - - When the Wi-Fi connection is disrupted because of specific reasons, e.g., the station continuously loses N beacons, the AP kicks off the station, the AP's authentication mode is changed, etc. + - When the Wi-Fi connection is disrupted because of specific reasons, e.g., the station continuously loses N beacons, the AP kicks off the station, the AP's authentication mode is changed, etc. Upon receiving this event, the default behavior of the event task is: - Shuts down the station's LwIP netif. @@ -180,7 +180,7 @@ Another thing deserves our attention is that the default behavior of LwIP is to - Five seconds later, the Wi-Fi connection is restored because esp_wifi_connect() is called in the application event callback function. **Moreover, the station connects to the same AP and gets the same IPV4 address as before**. - Sixty seconds later, when the application sends out data with the keep-alive socket, the socket returns an error and the application closes the socket and re-creates it when necessary. -In above scenario, ideally, the application sockets and the network layer should not be affected, since the Wi-Fi connection only fails temporarily and recovers very quickly. The application can enable "Keep TCP connections when IP changed" via LwIP menuconfig. +In above scenario, ideally, the application sockets and the network layer should not be affected, since the Wi-Fi connection only fails temporarily and recovers very quickly. The application can enable "Keep TCP connections when IP changed" via LwIP menuconfig. WIFI_EVENT_STA_AUTHMODE_CHANGE ++++++++++++++++++++++++++++++++++++ @@ -202,13 +202,13 @@ The socket is based on the IPV4 address, which means that, if the IPV4 changes, IP_EVENT_GOT_IP6 ++++++++++++++++++++++++++++++++++++ -This event arises when the IPV6 SLAAC support auto-configures an address for the ESP32, or when this address changes. The event means that everything is ready and the application can begin its tasks (e.g., creating sockets). +This event arises when the IPV6 SLAAC support auto-configures an address for the {IDF_TARGET_NAME}, or when this address changes. The event means that everything is ready and the application can begin its tasks (e.g., creating sockets). IP_STA_LOST_IP ++++++++++++++++++++++++++++++++++++ This event arises when the IPV4 address become invalid. -IP_STA_LOST_IP doesn't arise immediately after the WiFi disconnects, instead it starts an IPV4 address lost timer, if the IPV4 address is got before ip lost timer expires, IP_EVENT_STA_LOST_IP doesn't happen. Otherwise, the event arises when IPV4 address lost timer expires. +IP_STA_LOST_IP doesn't arise immediately after the WiFi disconnects, instead it starts an IPV4 address lost timer, if the IPV4 address is got before ip lost timer expires, IP_EVENT_STA_LOST_IP doesn't happen. Otherwise, the event arises when IPV4 address lost timer expires. Generally the application don't need to care about this event, it is just a debug event to let the application know that the IPV4 address is lost. @@ -222,7 +222,7 @@ Similar to <`WIFI_EVENT_STA_STOP`_>. WIFI_EVENT_AP_STACONNECTED ++++++++++++++++++++++++++++++++++++ -Every time a station is connected to ESP32 AP, the <`WIFI_EVENT_AP_STACONNECTED`_> will arise. Upon receiving this event, the event task will do nothing, and the application callback can also ignore it. However, you may want to do something, for example, to get the info of the connected STA, etc. +Every time a station is connected to {IDF_TARGET_NAME} AP, the <`WIFI_EVENT_AP_STACONNECTED`_> will arise. Upon receiving this event, the event task will do nothing, and the application callback can also ignore it. However, you may want to do something, for example, to get the info of the connected STA, etc. WIFI_EVENT_AP_STADISCONNECTED ++++++++++++++++++++++++++++++++++++ @@ -240,8 +240,8 @@ WIFI_EVENT_AP_PROBEREQRECVED This event is disabled by default. The application can enable it via API esp_wifi_set_event_mask(). When this event is enabled, it will be raised each time the AP receives a probe request. -ESP32 Wi-Fi Station General Scenario ---------------------------------------- +{IDF_TARGET_NAME} Wi-Fi Station General Scenario +------------------------------------------------ Below is a "big scenario" which describes some small scenarios in Station mode: .. seqdiag:: @@ -255,9 +255,9 @@ Below is a "big scenario" which describes some small scenarios in Station mode: edge_length = 140; span_height = 5; default_shape = roundedbox; - default_fontsize = 12; + default_fontsize = 12; - MAIN_TASK [label = "Main\ntask"]; + MAIN_TASK [label = "Main\ntask"]; APP_TASK [label = "App\ntask"]; EVENT_TASK [label = "Event\ntask"]; LwIP_TASK [label = "LwIP\ntask"]; @@ -302,7 +302,7 @@ Below is a "big scenario" which describes some small scenarios in Station mode: ++++++++++++++++++++++++++++++ - s1.1: The main task calls esp_netif_init() to create an LwIP core task and initialize LwIP-related work. - - s1.2: The main task calls esp_event_loop_init() to create a system Event task and initialize an application event's callback function. In the scenario above, the application event's callback function does nothing but relaying the event to the application task. + - s1.2: The main task calls esp_event_loop_init() to create a system Event task and initialize an application event's callback function. In the scenario above, the application event's callback function does nothing but relaying the event to the application task. - s1.3: The main task calls esp_netif_create_default_wifi_ap() or esp_netif_create_default_wifi_sta() to create default network interface instance binding station or AP with TCP/IP stack. @@ -314,7 +314,7 @@ Step 1.1~1.5 is a recommended sequence that initializes a Wi-Fi-/LwIP-based appl 2. Wi-Fi Configuration Phase +++++++++++++++++++++++++++++++ -Once the Wi-Fi driver is initialized, you can start configuring the Wi-Fi driver. In this scenario, the mode is Station, so you may need to call esp_wifi_set_mode(WIFI_MODE_STA) to configure the Wi-Fi mode as Station. You can call other esp_wifi_set_xxx APIs to configure more settings, such as the protocol mode, country code, bandwidth, etc. Refer to <`ESP32 Wi-Fi Configuration`_>. +Once the Wi-Fi driver is initialized, you can start configuring the Wi-Fi driver. In this scenario, the mode is Station, so you may need to call esp_wifi_set_mode(WIFI_MODE_STA) to configure the Wi-Fi mode as Station. You can call other esp_wifi_set_xxx APIs to configure more settings, such as the protocol mode, country code, bandwidth, etc. Refer to <`{IDF_TARGET_NAME} Wi-Fi Configuration`_>. Generally, we configure the Wi-Fi driver before setting up the Wi-Fi connection, but this is **NOT** mandatory, which means that you can configure the Wi-Fi connection anytime, provided that the Wi-Fi driver is initialized successfully. However, if the configuration does not need to change after the Wi-Fi connection is set up, you should configure the Wi-Fi driver at this stage, because the configuration APIs (such as esp_wifi_set_protocol) will cause the Wi-Fi to reconnect, which may not be desirable. @@ -325,12 +325,12 @@ If the Wi-Fi NVS flash is enabled by menuconfig, all Wi-Fi configuration in this - s3.1: Call esp_wifi_start to start the Wi-Fi driver. - s3.2: The Wi-Fi driver posts <`WIFI_EVENT_STA_START`_> to the event task; then, the event task will do some common things and will call the application event callback function. - s3.3: The application event callback function relays the <`WIFI_EVENT_STA_START`_> to the application task. We recommend that you call esp_wifi_connect(). However, you can also call esp_wifi_connect() in other phrases after the <`WIFI_EVENT_STA_START`_> arises. - + 4. Wi-Fi Connect Phase +++++++++++++++++++++++++++++++++ - s4.1: Once esp_wifi_connect() is called, the Wi-Fi driver will start the internal scan/connection process. - - s4.2: If the internal scan/connection process is successful, the <`WIFI_EVENT_STA_CONNECTED`_> will be generated. In the event task, it starts the DHCP client, which will finally trigger the DHCP process. + - s4.2: If the internal scan/connection process is successful, the <`WIFI_EVENT_STA_CONNECTED`_> will be generated. In the event task, it starts the DHCP client, which will finally trigger the DHCP process. - s4.3: In the above-mentioned scenario, the application event callback will relay the event to the application task. Generally, the application needs to do nothing, and you can do whatever you want, e.g., print a log, etc. @@ -347,7 +347,7 @@ In step 4.2, the Wi-Fi connection may fail because, for example, the password is +++++++++++++++++++++++++++++++++ - s6.1: When the Wi-Fi connection is disrupted, e.g. because the AP is powered off, the RSSI is poor, etc., <`WIFI_EVENT_STA_DISCONNECTED`_> will arise. This event may also arise in phase 3. Here, the event task will notify the LwIP task to clear/remove all UDP/TCP connections. Then, all application sockets will be in a wrong status. In other words, no socket can work properly when this event happens. - s6.2: In the scenario described above, the application event callback function relays <`WIFI_EVENT_STA_DISCONNECTED`_> to the application task. We recommend that esp_wifi_connect() be called to reconnect the Wi-Fi, close all sockets and re-create them if necessary. Refer to <`WIFI_EVENT_STA_DISCONNECTED`_>. - + 7. Wi-Fi IP Change Phase ++++++++++++++++++++++++++++++++++ @@ -363,7 +363,7 @@ In step 4.2, the Wi-Fi connection may fail because, for example, the password is - s8.3: Call esp_wifi_deinit() to unload the Wi-Fi driver. -ESP32 Wi-Fi AP General Scenario +{IDF_TARGET_NAME} Wi-Fi AP General Scenario --------------------------------------------- Below is a "big scenario" which describes some small scenarios in AP mode: @@ -378,9 +378,9 @@ Below is a "big scenario" which describes some small scenarios in AP mode: edge_length = 140; span_height = 5; default_shape = roundedbox; - default_fontsize = 12; + default_fontsize = 12; - MAIN_TASK [label = "Main\ntask"]; + MAIN_TASK [label = "Main\ntask"]; APP_TASK [label = "App\ntask"]; EVENT_TASK [label = "Event\ntask"]; LwIP_TASK [label = "LwIP\ntask"]; @@ -411,46 +411,46 @@ Below is a "big scenario" which describes some small scenarios in AP mode: } -ESP32 Wi-Fi Scan +{IDF_TARGET_NAME} Wi-Fi Scan ------------------------ Currently, the esp_wifi_scan_start() API is supported only in Station or Station+AP mode. -Scan Type +Scan Type +++++++++++++++++++++++++ +------------------+--------------------------------------------------------------+ -| Mode | Description | +| Mode | Description | +==================+==============================================================+ | Active Scan | Scan by sending a probe request. | -| | The default scan is an active scan. | -| | | +| | The default scan is an active scan. | +| | | +------------------+--------------------------------------------------------------+ | Passive Scan | No probe request is sent out. Just switch to the specific | -| | channel and wait for a beacon. | +| | channel and wait for a beacon. | | | Application can enable it via the scan_type field of | -| | wifi_scan_config_t. | -| | | +| | wifi_scan_config_t. | +| | | +------------------+--------------------------------------------------------------+ | Foreground Scan | This scan is applicable when there is no Wi-Fi connection | | | in Station mode. Foreground or background scanning is | -| | controlled by the Wi-Fi driver and cannot be configured by | -| | the application. | +| | controlled by the Wi-Fi driver and cannot be configured by | +| | the application. | +------------------+--------------------------------------------------------------+ | Background Scan | This scan is applicable when there is a Wi-Fi connection in | -| | Station mode or in Station+AP mode. | +| | Station mode or in Station+AP mode. | | | Whether it is a foreground scan or background scan depends on| -| | the Wi-Fi driver and cannot be configured by the application.| -| | | +| | the Wi-Fi driver and cannot be configured by the application.| +| | | +------------------+--------------------------------------------------------------+ -| All-Channel Scan | It scans all of the channels. | +| All-Channel Scan | It scans all of the channels. | | | If the channel field of wifi_scan_config_t is set to 0, it is| | | an all-channel scan. | | | | +------------------+--------------------------------------------------------------+ | Specific Channel | It scans specific channels only. | | Scan | If the channel field of wifi_scan_config_t set to 1, it is a | -| | specific-channel scan. | +| | specific-channel scan. | | | | +------------------+--------------------------------------------------------------+ @@ -533,7 +533,7 @@ Scenario: edge_length = 160; span_height = 5; default_shape = roundedbox; - default_fontsize = 12; + default_fontsize = 12; APP_TASK [label = "App\ntask"]; EVENT_TASK [label = "Event\ntask"]; @@ -550,7 +550,7 @@ Scenario: } -The scenario above describes an all-channel, foreground scan. The foreground scan can only occur in Station mode where the station does not connect to any AP. Whether it is a foreground or background scan is totally determined by the Wi-Fi driver, and cannot be configured by the application. +The scenario above describes an all-channel, foreground scan. The foreground scan can only occur in Station mode where the station does not connect to any AP. Whether it is a foreground or background scan is totally determined by the Wi-Fi driver, and cannot be configured by the application. Detailed scenario description: @@ -589,7 +589,7 @@ Scenario: edge_length = 160; span_height = 5; default_shape = roundedbox; - default_fontsize = 12; + default_fontsize = 12; APP_TASK [label = "App\ntask"]; EVENT_TASK [label = "Event\ntask"]; @@ -625,7 +625,7 @@ Scenario: edge_length = 160; span_height = 5; default_shape = roundedbox; - default_fontsize = 12; + default_fontsize = 12; APP_TASK [label = "App\ntask"]; EVENT_TASK [label = "Event\ntask"]; @@ -662,7 +662,7 @@ If the block parameter of esp_wifi_scan_start() is true, then the scan is a bloc Parallel Scan +++++++++++++ -Two application tasks may call esp_wifi_scan_start() at the same time, or the same application task calls esp_wifi_scan_start() before it gets a scan-done event. Both scenarios can happen. **However, the Wi-Fi driver does not support multiple concurrent scans adequately. As a result, concurrent scans should be avoided.** Support for concurrent scan will be enhanced in future releases, as the ESP32's Wi-Fi functionality improves continuously. +Two application tasks may call esp_wifi_scan_start() at the same time, or the same application task calls esp_wifi_scan_start() before it gets a scan-done event. Both scenarios can happen. **However, the Wi-Fi driver does not support multiple concurrent scans adequately. As a result, concurrent scans should be avoided.** Support for concurrent scan will be enhanced in future releases, as the {IDF_TARGET_NAME}'s Wi-Fi functionality improves continuously. Scan When Wi-Fi Is Connecting +++++++++++++++++++++++++++++++ @@ -681,10 +681,10 @@ In above scenario the scan will never succeed because the connecting is in proce The application can define its own reconnect strategy to avoid the scan starve to death. Refer to <`Wi-Fi Reconnect`_>. -ESP32 Wi-Fi Station Connecting Scenario ----------------------------------------- +{IDF_TARGET_NAME} Wi-Fi Station Connecting Scenario +--------------------------------------------------- -This scenario only depicts the case when there is only one target AP are found in scan phase, for the scenario that more than one AP with the same SSID are found, refer to <`ESP32 Wi-Fi Station Connecting When Multiple APs Are Found`_>. +This scenario only depicts the case when there is only one target AP are found in scan phase, for the scenario that more than one AP with the same SSID are found, refer to <`{IDF_TARGET_NAME} Wi-Fi Station Connecting When Multiple APs Are Found`_>. Generally, the application does not need to care about the connecting process. Below is a brief introduction to the process for those who are really interested. @@ -701,7 +701,7 @@ Scenario: edge_length = 160; span_height = 5; default_shape = roundedbox; - default_fontsize = 12; + default_fontsize = 12; EVENT_TASK [label = "Event\ntask"]; WIFI_TASK [label = "Wi-Fi\ntask"]; @@ -737,13 +737,13 @@ Scan Phase +++++++++++++++++++++ - s1.1, The Wi-Fi driver begins scanning in "Wi-Fi Connect". Refer to <`Scan in Wi-Fi Connect`_> for more details. - - s1.2, If the scan fails to find the target AP, <`WIFI_EVENT_STA_DISCONNECTED`_> will arise and the reason-code will be WIFI_REASON_NO_AP_FOUND. Refer to <`Wi-Fi Reason Code`_>. + - s1.2, If the scan fails to find the target AP, <`WIFI_EVENT_STA_DISCONNECTED`_> will arise and the reason-code will be WIFI_REASON_NO_AP_FOUND. Refer to <`Wi-Fi Reason Code`_>. Auth Phase +++++++++++++++++++++ - s2.1, The authentication request packet is sent and the auth timer is enabled. - - s2.2, If the authentication response packet is not received before the authentication timer times out, <`WIFI_EVENT_STA_DISCONNECTED`_> will arise and the reason-code will be WIFI_REASON_AUTH_EXPIRE. Refer to <`Wi-Fi Reason Code`_>. + - s2.2, If the authentication response packet is not received before the authentication timer times out, <`WIFI_EVENT_STA_DISCONNECTED`_> will arise and the reason-code will be WIFI_REASON_AUTH_EXPIRE. Refer to <`Wi-Fi Reason Code`_>. - s2.3, The auth-response packet is received and the auth-timer is stopped. - s2.4, The AP rejects authentication in the response and <`WIFI_EVENT_STA_DISCONNECTED`_> arises, while the reason-code is WIFI_REASON_AUTH_FAIL or the reasons specified by the AP. Refer to <`Wi-Fi Reason Code`_>. @@ -753,22 +753,22 @@ Association Phase - s3.1, The association request is sent and the association timer is enabled. - s3.2, If the association response is not received before the association timer times out, <`WIFI_EVENT_STA_DISCONNECTED`_> will arise and the reason-code will be WIFI_REASON_ASSOC_EXPIRE. Refer to <`Wi-Fi Reason Code`_>. - s3.3, The association response is received and the association timer is stopped. - - s3.4, The AP rejects the association in the response and <`WIFI_EVENT_STA_DISCONNECTED`_> arises, while the reason-code is the one specified in the association response. Refer to <`Wi-Fi Reason Code`_>. + - s3.4, The AP rejects the association in the response and <`WIFI_EVENT_STA_DISCONNECTED`_> arises, while the reason-code is the one specified in the association response. Refer to <`Wi-Fi Reason Code`_>. Four-way Handshake Phase ++++++++++++++++++++++++++ - s4.1, The four-way handshake is sent out and the association timer is enabled. - - s4.2, If the association response is not received before the association timer times out, <`WIFI_EVENT_STA_DISCONNECTED`_> will arise and the reason-code will be WIFI_REASON_ASSOC_EXPIRE. Refer to <`Wi-Fi Reason Code`_>. + - s4.2, If the association response is not received before the association timer times out, <`WIFI_EVENT_STA_DISCONNECTED`_> will arise and the reason-code will be WIFI_REASON_ASSOC_EXPIRE. Refer to <`Wi-Fi Reason Code`_>. - s4.3, The association response is received and the association timer is stopped. - - s4.4, The AP rejects the association in the response and <`WIFI_EVENT_STA_DISCONNECTED`_> arises and the reason-code will be the one specified in the association response. Refer to <`Wi-Fi Reason Code`_>. + - s4.4, The AP rejects the association in the response and <`WIFI_EVENT_STA_DISCONNECTED`_> arises and the reason-code will be the one specified in the association response. Refer to <`Wi-Fi Reason Code`_>. Wi-Fi Reason Code +++++++++++++++++++++ -The table below shows the reason-code defined in ESP32. The first column is the macro name defined in esp_wifi_types.h. The common prefix *WIFI_REASON* is removed, which means that *UNSPECIFIED* actually stands for *WIFI_REASON_UNSPECIFIED* and so on. The second column is the value of the reason. The third column is the standard value to which this reason is mapped in section 8.4.1.7 of ieee802.11-2012. (For more information, refer to the standard mentioned above.) The last column is a description of the reason. +The table below shows the reason-code defined in {IDF_TARGET_NAME}. The first column is the macro name defined in esp_wifi_types.h. The common prefix *WIFI_REASON* is removed, which means that *UNSPECIFIED* actually stands for *WIFI_REASON_UNSPECIFIED* and so on. The second column is the value of the reason. The third column is the standard value to which this reason is mapped in section 8.4.1.7 of ieee802.11-2012. (For more information, refer to the standard mentioned above.) The last column is a description of the reason. +---------------------------+-------+---------+-------------------------------------------------------------+ | Reason code | Value |Mapped To| Description | @@ -779,12 +779,12 @@ The table below shows the reason-code defined in ESP32. The first column is the +---------------------------+-------+---------+-------------------------------------------------------------+ | AUTH_EXPIRE | 2 | 2 | The previous authentication is no longer valid. | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | +| | | | For the ESP Station, this reason is reported when: | | | | | | | | | | - auth is timed out | | | | | - the reason is received from the AP. | | | | | | -| | | | For the ESP32 AP, this reason is reported when: | +| | | | For the ESP AP, this reason is reported when: | | | | | | | | | | - the AP has not received any packets from the station | | | | | in the past five minutes. | @@ -795,18 +795,18 @@ The table below shows the reason-code defined in ESP32. The first column is the | AUTH_LEAVE | 3 | 3 | De-authenticated, because the sending STA is | | | | | leaving (or has left). | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | +| | | | For the ESP Station, this reason is reported when: | | | | | | | | | | - it is received from the AP. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | ASSOC_EXPIRE | 4 | 4 | Disassociated due to inactivity. | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | +| | | | For the ESP Station, this reason is reported when: | | | | | | | | | | - it is received from the AP. | -| | | | | -| | | | For the ESP32 AP, this reason is reported when: | +| | | | | +| | | | For the ESP AP, this reason is reported when: | | | | | | | | | | - the AP has not received any packets from the | | | | | station in the past five minutes. | @@ -817,111 +817,111 @@ The table below shows the reason-code defined in ESP32. The first column is the | ASSOC_TOOMANY | 5 | 5 | Disassociated, because the AP is unable to handle | | | | | all currently associated STAs at the same time. | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | +| | | | For the ESP Station, this reason is reported when: | | | | | | | | | | - it is received from the AP. | -| | | | | -| | | | For the ESP32 AP, this reason is reported when: | +| | | | | +| | | | For the ESP AP, this reason is reported when: | | | | | | | | | | - the stations associated with the AP reach the | | | | | maximum number that the AP can support. | -| | | | | +| | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | NOT_AUTHED | 6 | 6 | Class-2 frame received from a non-authenticated STA. | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | +| | | | For the ESP Station, this reason is reported when: | | | | | | | | | | - it is received from the AP. | | | | | | -| | | | For the ESP32 AP, this reason is reported when: | -| | | | | +| | | | For the ESP AP, this reason is reported when: | +| | | | | | | | | - the AP receives a packet with data from a | | | | | non-authenticated station. | -| | | | | +| | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | NOT_ASSOCED | 7 | 7 | Class-3 frame received from a non-associated STA. | -| | | | | -| | | | For the ESP32 Station, this reason is reported when: | -| | | | | +| | | | | +| | | | For the ESP Station, this reason is reported when: | +| | | | | | | | | - it is received from the AP. | -| | | | | -| | | | For the ESP32 AP, this reason is reported when: | -| | | | | +| | | | | +| | | | For the ESP AP, this reason is reported when: | +| | | | | | | | | - the AP receives a packet with data from a | | | | | non-associated station. | -| | | | | +| | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | ASSOC_LEAVE | 8 | 8 | Disassociated, because the sending STA is leaving (or has | | | | | left) BSS. | -| | | | | -| | | | For the ESP32 Station, this reason is reported when: | +| | | | | +| | | | For the ESP Station, this reason is reported when: | | | | | | | | | | - it is received from the AP. | | | | | - the station is disconnected by esp_wifi_disconnect() and | | | | | other APIs. | -| | | | | +| | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | ASSOC_NOT_AUTHED | 9 | 9 | STA requesting (re)association is not authenticated by the | | | | | responding STA. | -| | | | | -| | | | For the ESP32 Station, this reason is reported when: | +| | | | | +| | | | For the ESP Station, this reason is reported when: | | | | | | | | | | - it is received from the AP. | -| | | | | -| | | | For the ESP32 AP, this reason is reported when: | -| | | | | +| | | | | +| | | | For the ESP AP, this reason is reported when: | +| | | | | | | | | - the AP receives packets with data from an | | | | | associated, yet not authenticated, station. | -| | | | | +| | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | DISASSOC_PWRCAP_BAD | 10 | 10 | Disassociated, because the information in the Power | | | | | Capability element is unacceptable. | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | +| | | | For the ESP Station, this reason is reported when: | | | | | | | | | | - it is received from the AP. | -| | | | | +| | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | DISASSOC_SUPCHAN_BAD | 11 | 11 | Disassociated, because the information in the Supported | | | | | Channels element is unacceptable. | -| | | | | -| | | | For the ESP32 Station, this reason is reported when: | -| | | | | +| | | | | +| | | | For the ESP Station, this reason is reported when: | +| | | | | | | | | - it is received from the AP. | -| | | | | +| | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | IE_INVALID | 13 | 13 | Invalid element, i.e. an element whose content does not meet| | | | | the specifications of the Standard in Clause 8. | -| | | | | -| | | | For the ESP32 Station, this reason is reported when: | +| | | | | +| | | | For the ESP Station, this reason is reported when: | | | | | | | | | | - it is received from the AP | | | | | | -| | | | For the ESP32 AP, this reason is reported when: | -| | | | | +| | | | For the ESP AP, this reason is reported when: | +| | | | | | | | | - the AP parses a wrong WPA or RSN IE. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | MIC_FAILURE | 14 | 14 | Message integrity code (MIC) failure. | -| | | | | -| | | | For the ESP32 Station, this reason is reported when: | -| | | | | +| | | | | +| | | | For the ESP Station, this reason is reported when: | +| | | | | | | | | - it is received from the AP. | -| | | | | +| | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ -| 4WAY_HANDSHAKE_TIMEOUT | 15 | 15 | Four-way handshake times out. For legacy reasons, in ESP32 | +| 4WAY_HANDSHAKE_TIMEOUT | 15 | 15 | Four-way handshake times out. For legacy reasons, in ESP | | | | | this reason-code is replaced with | | | | | WIFI_REASON_HANDSHAKE_TIMEOUT. | -| | | | | -| | | | For the ESP32 Station, this reason is reported when: | +| | | | | +| | | | For the ESP Station, this reason is reported when: | | | | | | | | | | - the handshake times out | | | | | - it is received from the AP. | -| | | | | +| | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | GROUP_KEY_UPDATE_TIMEOUT | 16 | 16 | Group-Key Handshake times out. | -| | | | | -| | | | For the ESP32 station, this reason is reported when: | +| | | | | +| | | | For the ESP station, this reason is reported when: | | | | | | | | | | - it is received from the AP. | | | | | | @@ -929,7 +929,7 @@ The table below shows the reason-code defined in ESP32. The first column is the | IE_IN_4WAY_DIFFERS | 17 | 17 | The element in the four-way handshake is different from the | | | | | (Re-)Association Request/Probe and Response/Beacon frame. | | | | | | -| | | | For the ESP32 station, this reason is reported when: | +| | | | For the ESP station, this reason is reported when: | | | | | | | | | | - it is received from the AP. | | | | | - the station finds that the four-way handshake IE differs | @@ -939,59 +939,59 @@ The table below shows the reason-code defined in ESP32. The first column is the +---------------------------+-------+---------+-------------------------------------------------------------+ | GROUP_CIPHER_INVALID | 18 | 18 | Invalid group cipher. | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | -| | | | | +| | | | For the ESP Station, this reason is reported when: | +| | | | | | | | | - it is received from the AP. | -| | | | | +| | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | PAIRWISE_CIPHER_INVALID | 19 | 19 | Invalid pairwise cipher. | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | -| | | | | +| | | | For the ESP Station, this reason is reported when: | +| | | | | | | | | - it is received from the AP. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | AKMP_INVALID | 20 | 20 | Invalid AKMP. | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | -| | | | | +| | | | For the ESP Station, this reason is reported when: | +| | | | | | | | | - it is received from the AP. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | UNSUPP_RSN_IE_VERSION | 21 | 21 | Unsupported RSNE version. | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | -| | | | | +| | | | For the ESP Station, this reason is reported when: | +| | | | | | | | | - it is received from the AP. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | INVALID_RSN_IE_CAP | 22 | 22 | Invalid RSNE capabilities. | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | +| | | | For the ESP Station, this reason is reported when: | | | | | | | | | | - it is received from the AP. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | 802_1X_AUTH_FAILED | 23 | 23 | IEEE 802.1X. authentication failed. | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | +| | | | For the ESP Station, this reason is reported when: | | | | | | | | | | - it is received from the AP. | | | | | | -| | | | For the ESP32 AP, this reason is reported when: | -| | | | | +| | | | For the ESP AP, this reason is reported when: | +| | | | | | | | | - 802.1 x authentication fails. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | CIPHER_SUITE_REJECTED | 24 | 24 | Cipher suite rejected due to security policies. | | | | | | -| | | | For the ESP32 Station, this reason is reported when: | -| | | | | +| | | | For the ESP Station, this reason is reported when: | +| | | | | | | | | - it is received from the AP. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | BEACON_TIMEOUT | 200 |reserved | Espressif-specific Wi-Fi reason-code: when the station | -| | | | loses N beacons continuously, it will disrupt the connection| +| | | | loses N beacons continuously, it will disrupt the connection| | | | | and report this reason. | | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ @@ -1005,7 +1005,7 @@ The table below shows the reason-code defined in ESP32. The first column is the +---------------------------+-------+---------+-------------------------------------------------------------+ | ASSOC_FAIL | 203 |reserved | Espressif-specific Wi-Fi reason-code: the association | | | | | fails, but not because of ASSOC_EXPIRE or ASSOC_TOOMANY. | -| | | | | +| | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ | HANDSHAKE_TIMEOUT | 204 |reserved | Espressif-specific Wi-Fi reason-code: the | | | | | handshake fails for the same reason as that in | @@ -1013,10 +1013,10 @@ The table below shows the reason-code defined in ESP32. The first column is the | | | | | +---------------------------+-------+---------+-------------------------------------------------------------+ -ESP32 Wi-Fi Station Connecting When Multiple APs Are Found ---------------------------------------------------------------- +{IDF_TARGET_NAME} Wi-Fi Station Connecting When Multiple APs Are Found +---------------------------------------------------------------------- -This scenario is similar as <`ESP32 Wi-Fi Station Connecting Scenario`_>, the difference is the station will not raise the event <`WIFI_EVENT_STA_DISCONNECTED`_> unless it fails to connect all of the found APs. +This scenario is similar as <`{IDF_TARGET_NAME} Wi-Fi Station Connecting Scenario`_>, the difference is the station will not raise the event <`WIFI_EVENT_STA_DISCONNECTED`_> unless it fails to connect all of the found APs. Wi-Fi Reconnect @@ -1033,12 +1033,12 @@ Another thing we need to consider is the reconnect may not connect the same AP i Wi-Fi Beacon Timeout --------------------------- -The beacon timeout mechanism is used by ESP32 station to detect whether the AP is alive or not. If the station continuously loses 60 beacons of the connected AP, the beacon timeout happens. +The beacon timeout mechanism is used by {IDF_TARGET_NAME} station to detect whether the AP is alive or not. If the station continuously loses 60 beacons of the connected AP, the beacon timeout happens. After the beacon timeout happens, the station sends 5 probe requests to AP, it disconnects the AP and raises the event <`WIFI_EVENT_STA_DISCONNECTED`_> if still no probe response or beacon is received from AP. -ESP32 Wi-Fi Configuration ---------------------------- +{IDF_TARGET_NAME} Wi-Fi Configuration +------------------------------------- All configurations will be stored into flash when the Wi-Fi NVS is enabled; otherwise, refer to <`Wi-Fi NVS Flash`_>. @@ -1054,7 +1054,7 @@ Call esp_wifi_set_mode() to set the Wi-Fi mode. | | station and AP interfaces are not initialized for | | | RX/TX Wi-Fi data. Generally, this mode is used for Sniffer, | | | or when you only want to stop both the STA and the AP | -| | without calling esp_wifi_deinit() to unload the whole Wi-Fi | +| | without calling esp_wifi_deinit() to unload the whole Wi-Fi | | | driver. | +------------------+--------------------------------------------------------------+ | WIFI_MODE_STA | Station mode: in this mode, esp_wifi_start() will init the | @@ -1071,8 +1071,8 @@ Call esp_wifi_set_mode() to set the Wi-Fi mode. | WIFI_MODE_APSTA | Station-AP coexistence mode: in this mode, esp_wifi_start() | | | will simultaneously init both the station and the AP. | | | This is done in station mode and AP mode. Please note | -| | that the channel of the external AP, which the ESP32 Station | -| | is connected to, has higher priority over the ESP32 AP | +| | that the channel of the external AP, which the ESP Station | +| | is connected to, has higher priority over the ESP AP | | | channel. | +------------------+--------------------------------------------------------------+ @@ -1169,7 +1169,7 @@ API esp_wifi_set_config() can be used to configure the AP. The table below descr | | sure the channel is within the required range. | | | For more details, refer to <`Wi-Fi Country Code`_>. | +------------------+--------------------------------------------------------------+ -| authmode | Auth mode of ESP32 AP; currently, ESP32 Wi-Fi does not | +| authmode | Auth mode of ESP AP; currently, ESP Wi-Fi does not | | | support AUTH_WEP. If the authmode is an invalid value, | | | AP defaults the value to WIFI_AUTH_OPEN. | | | | @@ -1178,7 +1178,7 @@ API esp_wifi_set_config() can be used to configure the AP. The table below descr | | otherwise, it does broadcast the SSID. | | | | +------------------+--------------------------------------------------------------+ -| max_connection | Currently, ESP32 Wi-Fi supports up to 10 Wi-Fi connections. | +| max_connection | Currently, ESP Wi-Fi supports up to 10 Wi-Fi connections. | | | If max_connection > 10, AP defaults the value to 10. | | | | +------------------+--------------------------------------------------------------+ @@ -1219,18 +1219,18 @@ Currently, the IDF supports the following protocol modes: | | **This mode is an Espressif-patented mode which can achieve| | | a one-kilometer line of sight range. Please, make sure both| | | the station and the AP are connected to an | -| | ESP32 device** | +| | ESP device** | +--------------------+------------------------------------------------------------+ Long Range (LR) +++++++++++++++++++++++++ -Long Range (LR) mode is an Espressif-patented Wi-Fi mode which can achieve a one-kilometer line of sight range. It has better reception sensitivity, stronger anti-interference ability and longer transmission distance than the traditional 802.11B mode. +Long Range (LR) mode is an Espressif-patented Wi-Fi mode which can achieve a one-kilometer line of sight range. It has better reception sensitivity, stronger anti-interference ability and longer transmission distance than the traditional 802.11B mode. LR Compitability ************************* -Since LR is Espressif unique Wi-Fi mode, only ESP32 devices can transmit and receive the LR data. In other words, the ESP32 device should NOT transmit the data in LR data rate if the connected device doesn't support LR. The application can achieve this by configuring suitable Wi-Fi mode. If the negotiated mode supports LR, the ESP32 may transmit data in LR rate, otherwise, ESP32 will transmit all data in traditional Wi-Fi data rate. +Since LR is Espressif unique Wi-Fi mode, only {IDF_TARGET_NAME} devices can transmit and receive the LR data. In other words, the {IDF_TARGET_NAME} device should NOT transmit the data in LR data rate if the connected device doesn't support LR. The application can achieve this by configuring suitable Wi-Fi mode. If the negotiated mode supports LR, the {IDF_TARGET_NAME} may transmit data in LR rate, otherwise, {IDF_TARGET_NAME} will transmit all data in traditional Wi-Fi data rate. Following table depicts the Wi-Fi mode negotiation: @@ -1255,11 +1255,11 @@ Following table depicts the Wi-Fi mode negotiation: In above table, the row is the Wi-Fi mode of AP and the column is the Wi-Fi mode of station. The "-" indicates Wi-Fi mode of the AP and station are not compatible. According to the table, we can conclude that: - - For LR enabled in ESP32 AP, it's incompatible with traditional 802.11 mode because the beacon is sent in LR mode. - - For LR enabled in ESP32 station and the mode is NOT LR only mode, it's compatible with traditional 802.11 mode. - - If both station and AP are ESP32 devices and both of them enable LR mode, the negotiated mode supports LR. + - For LR enabled in {IDF_TARGET_NAME} AP, it's incompatible with traditional 802.11 mode because the beacon is sent in LR mode. + - For LR enabled in {IDF_TARGET_NAME} station and the mode is NOT LR only mode, it's compatible with traditional 802.11 mode. + - If both station and AP are {IDF_TARGET_NAME} devices and both of them enable LR mode, the negotiated mode supports LR. -If the negotiated Wi-Fi mode supports both traditional 802.11 mode and LR mode, it's the WiFi driver's responsibility to automatically select the best data rate in different Wi-Fi mode and the application don't need to care about it. +If the negotiated Wi-Fi mode supports both traditional 802.11 mode and LR mode, it's the WiFi driver's responsibility to automatically select the best data rate in different Wi-Fi mode and the application don't need to care about it. LR Impacts to Traditional Wi-Fi device *************************************** @@ -1284,7 +1284,7 @@ When to Use LR ************************* The general conditions for using LR are: - - Both the AP and station are ESP32 devices. + - Both the AP and station are devices. - Long distance WiFi connection and data transmission is required. - Data throughput requirements are very small, such as remote device control, etc. @@ -1387,23 +1387,23 @@ Following table depicts which country info is used in different WiFi Mode and di Home Channel ************************* -In AP mode, the home channel is defined as that of the AP channel. In Station mode, the home channel is defined as the channel of the AP to which the station is connected. In Station+AP mode, the home channel of AP and station must be the same. If the home channels of Station and AP are different, the station's home channel is always in priority. Take the following as an example: at the beginning, the AP is on channel 6, then the station connects to an AP whose channel is 9. Since the station's home channel has a higher priority, the AP needs to switch its channel from 6 to 9 to make sure that both station and AP have the same home channel. While switching channel, the ESP32 in SoftAP mode will notify the connected stations about the channel migration using a Channel Switch Announcement (CSA). Stations that support channel switching will transition smoothly whereas stations who do not will disconnect and reconnect to the SoftAP. +In AP mode, the home channel is defined as that of the AP channel. In Station mode, the home channel is defined as the channel of the AP to which the station is connected. In Station+AP mode, the home channel of AP and station must be the same. If the home channels of Station and AP are different, the station's home channel is always in priority. Take the following as an example: at the beginning, the AP is on channel 6, then the station connects to an AP whose channel is 9. Since the station's home channel has a higher priority, the AP needs to switch its channel from 6 to 9 to make sure that both station and AP have the same home channel. While switching channel, the {IDF_TARGET_NAME} in SoftAP mode will notify the connected stations about the channel migration using a Channel Switch Announcement (CSA). Stations that support channel switching will transition smoothly whereas stations who do not will disconnect and reconnect to the SoftAP. Wi-Fi Vendor IE Configuration +++++++++++++++++++++++++++++++++++ -By default, all Wi-Fi management frames are processed by the Wi-Fi driver, and the application does not need to care about them. Some applications, however, may have to handle the beacon, probe request, probe response and other management frames. For example, if you insert some vendor-specific IE into the management frames, it is only the management frames which contain this vendor-specific IE that will be processed. In ESP32, esp_wifi_set_vendor_ie() and esp_wifi_set_vendor_ie_cb() are responsible for this kind of tasks. +By default, all Wi-Fi management frames are processed by the Wi-Fi driver, and the application does not need to care about them. Some applications, however, may have to handle the beacon, probe request, probe response and other management frames. For example, if you insert some vendor-specific IE into the management frames, it is only the management frames which contain this vendor-specific IE that will be processed. In {IDF_TARGET_NAME}, esp_wifi_set_vendor_ie() and esp_wifi_set_vendor_ie_cb() are responsible for this kind of tasks. Wi-Fi Security ------------------------------- -In addition to traditional security methods (WEP/WPA-TKIP/WPA2-CCMP), ESP32 Wi-Fi now supports state-of-the-art security protocols, namely Protected Management Frames based on 802.11w standard and Wi-Fi Protected Access 3 (WPA3-Personal). Together, PMF and WPA3 provide better privacy and robustness against known attacks in traditional modes. +In addition to traditional security methods (WEP/WPA-TKIP/WPA2-CCMP), {IDF_TARGET_NAME} Wi-Fi now supports state-of-the-art security protocols, namely Protected Management Frames based on 802.11w standard and Wi-Fi Protected Access 3 (WPA3-Personal). Together, PMF and WPA3 provide better privacy and robustness against known attacks in traditional modes. Protected Management Frames (PMF) ++++++++++++++++++++++++++++++++++ -In Wi-Fi, management frames such as beacons, probes, (de)authentication, (dis)association are used by non-AP stations to scan and connect to an AP. Unlike data frames, these frames are sent unencrypted. +In Wi-Fi, management frames such as beacons, probes, (de)authentication, (dis)association are used by non-AP stations to scan and connect to an AP. Unlike data frames, these frames are sent unencrypted. An attacker can use eavesdropping and packet injection to send spoofed (de)authentication/(dis)association frames at the right time, leading to following attacks in case of unprotected management frame exchanges. - DOS attack on one or all clients in the range of the attacker. @@ -1414,11 +1414,11 @@ An attacker can use eavesdropping and packet injection to send spoofed (de)authe PMF provides protection against these attacks by encrypting unicast management frames and providing integrity checks for broadcast management frames. These include deauthentication, disassociation and robust management frames. It also provides Secure Association (SA) teardown mechanism to prevent spoofed association/authentication frames from disconnecting already connected clients. -ESP32 supports the following three modes of operation with respect to PMF. +{IDF_TARGET_NAME} supports the following three modes of operation with respect to PMF. - - PMF not supported: In this mode, ESP32 indicates to AP that it is not capable of supporting management protection during association. In effect, security in this mode will be equivalent to that in traditional mode. - - PMF capable, but not required: In this mode, ESP32 indicates to AP that it is capable of supporting PMF. The management protection will be used if AP mandates PMF or is at least capable of supporting PMF. - - PMF capable and required: In this mode, ESP32 will only connect to AP, if AP supports PMF. If not, ESP32 will refuse to connect to the AP. + - PMF not supported: In this mode, {IDF_TARGET_NAME} indicates to AP that it is not capable of supporting management protection during association. In effect, security in this mode will be equivalent to that in traditional mode. + - PMF capable, but not required: In this mode, {IDF_TARGET_NAME} indicates to AP that it is capable of supporting PMF. The management protection will be used if AP mandates PMF or is at least capable of supporting PMF. + - PMF capable and required: In this mode, {IDF_TARGET_NAME} will only connect to AP, if AP supports PMF. If not, {IDF_TARGET_NAME} will refuse to connect to the AP. :cpp:func:`esp_wifi_set_config` can be used to configure PMF mode by setting appropriate flags in `pmf_cfg` parameter. Currently, PMF is supported only in Station mode. @@ -1428,17 +1428,17 @@ WPA3-Personal Wi-Fi Protected Access-3 (WPA3) is a set of enhancements to Wi-Fi access security intended to replace the current WPA2 standard. In order to provide more robust authentication, WPA3 uses Simultaneous Authentication of Equals (SAE), which is password-authenticated key agreement method based on Diffie-Hellman key exchange. Unlike WPA2, the technology is resistant to offline-dictionary attack, where the attacker attempts to determine shared password based on captured 4-way handshake without any further network interaction. WPA3 also provides forward secrecy, which means the captured data cannot be decrypted even if password is compromised after data transmission. Please refer to `Security `_ section of Wi-Fi Alliance's official website for further details. -In order to enable WPA3-Personal, "Enable WPA3-Personal" should be selected in menuconfig. If enabled, ESP32 uses SAE for authentication if supported by the AP. Since PMF is a mandatory requirement for WPA3, PMF capability should be at least set to "PMF capable, but not required" for ESP32 to use WPA3 mode. Application developers need not worry about the underlying security mode as highest available is chosen from security standpoint. Note that Wi-Fi stack size requirement will increase approximately by 3k when WPA3 is used. Currently, WPA3 is supported only in Station mode. +In order to enable WPA3-Personal, "Enable WPA3-Personal" should be selected in menuconfig. If enabled, {IDF_TARGET_NAME} uses SAE for authentication if supported by the AP. Since PMF is a mandatory requirement for WPA3, PMF capability should be at least set to "PMF capable, but not required" for {IDF_TARGET_NAME} to use WPA3 mode. Application developers need not worry about the underlying security mode as highest available is chosen from security standpoint. Note that Wi-Fi stack size requirement will increase approximately by 3k when WPA3 is used. Currently, WPA3 is supported only in Station mode. -ESP32 Wi-Fi Power-saving Mode ------------------------------------ +{IDF_TARGET_NAME} Wi-Fi Power-saving Mode +----------------------------------------- Station Sleep ++++++++++++++++++++++ -Currently, ESP32 Wi-Fi supports the Modem-sleep mode which refers to the legacy power-saving mode in the IEEE 802.11 protocol. Modem-sleep mode works in Station-only mode and the station must connect to the AP first. If the Modem-sleep mode is enabled, station will switch between active and sleep state periodically. In sleep state, RF, PHY and BB are turned off in order to reduce power consumption. Station can keep connection with AP in modem-sleep mode. +Currently, {IDF_TARGET_NAME} Wi-Fi supports the Modem-sleep mode which refers to the legacy power-saving mode in the IEEE 802.11 protocol. Modem-sleep mode works in Station-only mode and the station must connect to the AP first. If the Modem-sleep mode is enabled, station will switch between active and sleep state periodically. In sleep state, RF, PHY and BB are turned off in order to reduce power consumption. Station can keep connection with AP in modem-sleep mode. -Modem-sleep mode includes minimum and maximum power save modes. In minimum power save mode, station wakes up every DTIM to receive beacon. Broadcast data will not be lost because it is transmitted after DTIM. However, it can not save much more power if DTIM is short for DTIM is determined by AP. +Modem-sleep mode includes minimum and maximum power save modes. In minimum power save mode, station wakes up every DTIM to receive beacon. Broadcast data will not be lost because it is transmitted after DTIM. However, it can not save much more power if DTIM is short for DTIM is determined by AP. In maximum power save mode, station wakes up every listen interval to receive beacon. This listen interval can be set longer than the AP DTIM period. Broadcast data may be lost because station may be in sleep state at DTIM time. If listen interval is longer, more power is saved but broadcast data is more easy to lose. Listen interval can be configured by calling API :cpp:func:`esp_wifi_set_config` before connecting to AP. @@ -1451,20 +1451,20 @@ The default Modem-sleep mode is WIFI_PS_MIN_MODEM. AP Sleep +++++++++++++++++++++++++++++++ -Currently ESP32 AP doesn't support all of the power save feature defined in Wi-Fi specification. To be specific, the AP only caches unicast data for the stations connect to this AP, but doesn't cache the multicast data for the stations. If stations connected to the ESP32 AP are power save enabled, they may experience multicast packet loss. +Currently {IDF_TARGET_NAME} AP doesn't support all of the power save feature defined in Wi-Fi specification. To be specific, the AP only caches unicast data for the stations connect to this AP, but doesn't cache the multicast data for the stations. If stations connected to the {IDF_TARGET_NAME} AP are power save enabled, they may experience multicast packet loss. -In future, all power save features will be supported on ESP32 AP. +In future, all power save features will be supported on {IDF_TARGET_NAME} AP. -ESP32 Wi-Fi Connect Crypto ------------------------------------ -Now ESP32 have two group crypto functions can be used when do wifi connect, one is the original functions, the other is optimized by ESP hardware: +{IDF_TARGET_NAME} Wi-Fi Connect Crypto +-------------------------------------- +Now {IDF_TARGET_NAME} have two group crypto functions can be used when do wifi connect, one is the original functions, the other is optimized by ESP hardware: 1. Original functions which is the source code used in the folder components/wpa_supplicant/src/crypto function; 2. The optimized functions is in the folder components/wpa_supplicant/src/fast_crypto, these function used the hardware crypto to make it faster than origin one, the type of function's name add `fast_` to distinguish with the original one. For example, the API aes_wrap() is used to encrypt frame information when do 4 way handshake, the fast_aes_wrap() has the same result but can be faster. -Two groups of crypto function can be used when register in the wpa_crypto_funcs_t, wpa2_crypto_funcs_t and wps_crypto_funcs_t structure, also we have given the recommend functions to register in the -fast_crypto_ops.c, you can register the function as the way you need, however what should make action is that the crypto_hash_xxx function and crypto_cipher_xxx function need to register with the same function to operation. For example, if you register crypto_hash_init() function to initialize the esp_crypto_hash structure, you need use the crypto_hash_update() and crypto_hash_finish() function to finish the operation, rather than fast_crypto_hash_update() or fast_crypto_hash_finish(). +Two groups of crypto function can be used when register in the wpa_crypto_funcs_t, wpa2_crypto_funcs_t and wps_crypto_funcs_t structure, also we have given the recommend functions to register in the +fast_crypto_ops.c, you can register the function as the way you need, however what should make action is that the crypto_hash_xxx function and crypto_cipher_xxx function need to register with the same function to operation. For example, if you register crypto_hash_init() function to initialize the esp_crypto_hash structure, you need use the crypto_hash_update() and crypto_hash_finish() function to finish the operation, rather than fast_crypto_hash_update() or fast_crypto_hash_finish(). -ESP32 Wi-Fi Throughput +{IDF_TARGET_NAME} Wi-Fi Throughput ----------------------------------- The table below shows the best throughput results we got in Espressif's lab and in a shield box. @@ -1504,7 +1504,7 @@ Preconditions of Using esp_wifi_80211_tx ++++++++++++++++++++++++++++++++++++++++++++ - The Wi-Fi mode is Station, or AP, or Station+AP. - - Either esp_wifi_set_promiscuous(true), or esp_wifi_start(), or both of these APIs return ESP_OK. This is because we need to make sure that Wi-Fi hardware is initialized before esp_wifi_80211_tx() is called. In ESP32, both esp_wifi_set_promiscuous(true) and esp_wifi_start() can trigger the initialization of Wi-Fi hardware. + - Either esp_wifi_set_promiscuous(true), or esp_wifi_start(), or both of these APIs return ESP_OK. This is because we need to make sure that Wi-Fi hardware is initialized before esp_wifi_80211_tx() is called. In {IDF_TARGET_NAME}, both esp_wifi_set_promiscuous(true) and esp_wifi_start() can trigger the initialization of Wi-Fi hardware. - The parameters of esp_wifi_80211_tx are hereby correctly provided. Data rate @@ -1533,7 +1533,7 @@ Theoretically, if we do not consider the side-effects the API imposes on the Wi- | | with the same MAC/BSSID. | | | | | | Side-effect example#1 | -| | The application calls esp_wifi_80211_tx to send | +| | The application calls esp_wifi_80211_tx to send | | | a beacon with BSSID == mac_x in AP mode, but | | | the mac_x is not the MAC of the AP interface. | | | Moreover, there is another AP, say | @@ -1636,9 +1636,9 @@ The Wi-Fi multiple antennas selecting can be depicted as following picture:: |__________| -ESP32 supports up to sixteen antennas through external antenna switch. The antenna switch can be controlled by up to four address pins - antenna_select[0:3]. Different input value of antenna_select[0:3] means selecting different antenna. E.g. the value '0b1011' means the antenna 11 is selected. The default value of antenna_select[3:0] is '0b0000', it means the antenna 0 is selected by default. +{IDF_TARGET_NAME} supports up to sixteen antennas through external antenna switch. The antenna switch can be controlled by up to four address pins - antenna_select[0:3]. Different input value of antenna_select[0:3] means selecting different antenna. E.g. the value '0b1011' means the antenna 11 is selected. The default value of antenna_select[3:0] is '0b0000', it means the antenna 0 is selected by default. -Up to four GPIOs are connected to the four active high antenna_select pins. ESP32 can select the antenna by control the GPIO[0:3]. The API :cpp:func:`esp_wifi_set_ant_gpio()` is used to configure which GPIOs are connected to antenna_selects. If GPIO[x] is connected to antenna_select[x], then gpio_config->gpio_cfg[x].gpio_select should be set to 1 and gpio_config->gpio_cfg[x].gpio_num should be provided. +Up to four GPIOs are connected to the four active high antenna_select pins. {IDF_TARGET_NAME} can select the antenna by control the GPIO[0:3]. The API :cpp:func:`esp_wifi_set_ant_gpio()` is used to configure which GPIOs are connected to antenna_selects. If GPIO[x] is connected to antenna_select[x], then gpio_config->gpio_cfg[x].gpio_select should be set to 1 and gpio_config->gpio_cfg[x].gpio_num should be provided. Although up to sixteen anteenas are supported, only one or two antennas can be simultaneously enabled for RX/TX. The API :cpp:func:`esp_wifi_set_ant()` is used to configure which antennas are enabled. @@ -1679,7 +1679,7 @@ Generally, following steps can be taken to configure the multiple antennas: Wi-Fi Channel State Information ------------------------------------ -Channel state information (CSI) refers to the channel information of a Wi-Fi connection. In ESP32, this information consists of channel frequency responses of sub-carriers and is estimated when packets are received from the transmitter. Each channel frequency response of sub-carrier is recorded by two bytes of signed characters. The first one is imaginary part and the second one is real part. There are up to three fields of channel frequency responses according to the type of received packet. They are legacy long training field (LLTF), high throughput LTF (HT-LTF) and space time block code HT-LTF (STBC-HT-LTF). For different types of packets which are received on channels with different state, the sub-carrier index and total bytes of signed characters of CSI is shown in the following table. +Channel state information (CSI) refers to the channel information of a Wi-Fi connection. In {IDF_TARGET_NAME}, this information consists of channel frequency responses of sub-carriers and is estimated when packets are received from the transmitter. Each channel frequency response of sub-carrier is recorded by two bytes of signed characters. The first one is imaginary part and the second one is real part. There are up to three fields of channel frequency responses according to the type of received packet. They are legacy long training field (LLTF), high throughput LTF (HT-LTF) and space time block code HT-LTF (STBC-HT-LTF). For different types of packets which are received on channels with different state, the sub-carrier index and total bytes of signed characters of CSI is shown in the following table. +-------------+--------------------+-----------------------------------------+--------------------------------------------------------+----------------------------------------------------------+ | channel | secondary channel | none | below | above | @@ -1699,21 +1699,21 @@ Channel state information (CSI) refers to the channel information of a Wi-Fi con | total bytes | 128 | 256 | 384 | 128 | 256 | 380 | 384 | 612 | 128 | 256 | 376 | 384 | 612 | +----------------------------------+-------------+-------------+-------------+----------+----------+------+-------------+-------------+----------+----------+--------+-------------+-------------+ -All of the information in the table can be found in the structure wifi_csi_info_t. +All of the information in the table can be found in the structure wifi_csi_info_t. - - Secondary channel refers to secondary_channel field of rx_ctrl field. - - Signal mode of packet refers to sig_mode field of rx_ctrl field. - - Channel bandwidth refers to cwb field of rx_ctrl field. - - STBC refers to stbc field of rx_ctrl field. - - Total bytes refers to len field. - - The CSI data corresponding to each Long Training Field(LTF) type is stored in a buffer starting from the buf field. Each item is stored as two bytes: imaginary part followed by real part. The order of each item is the same as the sub-carrier in the table. The order of LTF is: LLTF, HT-LTF, STBC-HT-LTF. However all 3 LTFs may not be present, depending on the channel and packet information (see above). - - If first_word_invalid field of wifi_csi_info_t is true, it means that the first four bytes of CSI data is invalid due to a hardware limitation in ESP32. + - Secondary channel refers to secondary_channel field of rx_ctrl field. + - Signal mode of packet refers to sig_mode field of rx_ctrl field. + - Channel bandwidth refers to cwb field of rx_ctrl field. + - STBC refers to stbc field of rx_ctrl field. + - Total bytes refers to len field. + - The CSI data corresponding to each Long Training Field(LTF) type is stored in a buffer starting from the buf field. Each item is stored as two bytes: imaginary part followed by real part. The order of each item is the same as the sub-carrier in the table. The order of LTF is: LLTF, HT-LTF, STBC-HT-LTF. However all 3 LTFs may not be present, depending on the channel and packet information (see above). + - If first_word_invalid field of wifi_csi_info_t is true, it means that the first four bytes of CSI data is invalid due to a hardware limitation in {IDF_TARGET_NAME}. - More information like RSSI, noise floor of RF, receiving time and antenna is in the rx_ctrl field. .. note:: - For STBC packet, CSI is provided for every space-time stream without CSD (cyclic shift delay). As each cyclic shift on the additional chains shall be -200ns, only the CSD angle of first space-time stream is recorded in sub-carrier 0 of HT-LTF and STBC-HT-LTF for there is no channel frequency response in sub-carrier 0. CSD[10:0] is 11 bits, ranging from -pi to pi. - - If LLTF, HT-LTF or STBC-HT-LTF is not enabled by calling API :cpp:func:`esp_wifi_set_csi_config`, the total bytes of CSI data will be fewer than that in the table. For example, if LLTF and HT-LTF is not enabled and STBC-HT-LTF is enabled, when a packet is received with the condition above/HT/40MHz/STBC, the total bytes of CSI data is 244 ((61 + 60) * 2 + 2 = 244, the result is aligned to four bytes and the last two bytes is invalid). + - If LLTF, HT-LTF or STBC-HT-LTF is not enabled by calling API :cpp:func:`esp_wifi_set_csi_config`, the total bytes of CSI data will be fewer than that in the table. For example, if LLTF and HT-LTF is not enabled and STBC-HT-LTF is enabled, when a packet is received with the condition above/HT/40MHz/STBC, the total bytes of CSI data is 244 ((61 + 60) * 2 + 2 = 244, the result is aligned to four bytes and the last two bytes is invalid). Wi-Fi Channel State Information Configure ------------------------------------------- @@ -1730,24 +1730,24 @@ The CSI receiving callback function runs from Wi-Fi task. So, do not do lengthy Wi-Fi HT20/40 ------------------------- -ESP32 supports Wi-Fi bandwidth HT20 or HT40, it doesn't support HT20/40 coexist. `esp_wifi_set_bandwidth` can be used to change the default bandwidth of station or AP. The default bandwidth for ESP32 station and AP is HT40. +{IDF_TARGET_NAME} supports Wi-Fi bandwidth HT20 or HT40, it doesn't support HT20/40 coexist. `esp_wifi_set_bandwidth` can be used to change the default bandwidth of station or AP. The default bandwidth for {IDF_TARGET_NAME} station and AP is HT40. In station mode, the actual bandwidth is firstly negotiated during the Wi-Fi connection. It is HT40 only if both the station and the connected AP support HT40, otherwise it's HT20. If the bandwidth of connected AP is changes, the actual bandwidth is negotiated again without Wi-Fi disconnecting. Similarly, in AP mode, the actual bandwidth is negotiated between AP and the stations that connect to the AP. It's HT40 if the AP and one of the stations support HT40, otherwise it's HT20. -In station/AP coexist mode, the station/AP can configure HT20/40 seperately. If both station and AP are negotiated to HT40, the HT40 channel should be the channel of station because the station always has higher priority than AP in ESP32. E.g. the configured bandwidth of AP is HT40, the configured primary channel is 6 and the configured secondary channel is 10. The station is connected to an router whose primary channel is 6 and secondary channel is 2, then the actual channel of AP is changed to primary 6 and secondary 2 automatically. +In station/AP coexist mode, the station/AP can configure HT20/40 seperately. If both station and AP are negotiated to HT40, the HT40 channel should be the channel of station because the station always has higher priority than AP in {IDF_TARGET_NAME}. E.g. the configured bandwidth of AP is HT40, the configured primary channel is 6 and the configured secondary channel is 10. The station is connected to an router whose primary channel is 6 and secondary channel is 2, then the actual channel of AP is changed to primary 6 and secondary 2 automatically. -Theoretically the HT40 can gain better throughput because the maximum raw physicial (PHY) data rate for HT40 is 150Mbps while it's 72Mbps for HT20. However, if the device is used in some special environment, e.g. there are too many other Wi-Fi devices around the ESP32 device, the performance of HT40 may be degraded. So if the applications need to support same or similar scenarios, it's recommended that the bandwidth is always configured to HT20. +Theoretically the HT40 can gain better throughput because the maximum raw physicial (PHY) data rate for HT40 is 150Mbps while it's 72Mbps for HT20. However, if the device is used in some special environment, e.g. there are too many other Wi-Fi devices around the {IDF_TARGET_NAME} device, the performance of HT40 may be degraded. So if the applications need to support same or similar scenarios, it's recommended that the bandwidth is always configured to HT20. Wi-Fi QoS ------------------------- -ESP32 supports all the mandatory features required in WFA Wi-Fi QoS Certification. +{IDF_TARGET_NAME} supports all the mandatory features required in WFA Wi-Fi QoS Certification. Four ACs(Access Category) are defined in Wi-Fi specification, each AC has a its own priority to access the Wi-Fi channel. Moreover a map rule is defined to map the QoS priority of other protocol, such as 802.11D or TCP/IP precedence to Wi-Fi AC. -Below is a table describes how the IP Precedences are mapped to Wi-Fi ACs in ESP32, it also indicates whether the AMPDU is supported for this AC. The table is sorted with priority descending order, namely, the AC_VO has highest priority. +Below is a table describes how the IP Precedences are mapped to Wi-Fi ACs in {IDF_TARGET_NAME}, it also indicates whether the AMPDU is supported for this AC. The table is sorted with priority descending order, namely, the AC_VO has highest priority. +------------------+------------------------+-----------------+ | IP Precedence | Wi-Fi AC | Support AMPDU? | @@ -1776,17 +1776,17 @@ Theoretically the higher priority AC has better performance than the low priorit Wi-Fi AMSDU ------------------------- -ESP32 supports receiving AMSDU but doesn't support transmitting AMSDU. The transmitting AMSDU is not necessary since ESP32 has transmitting AMPDU. +{IDF_TARGET_NAME} supports receiving AMSDU but doesn't support transmitting AMSDU. The transmitting AMSDU is not necessary since {IDF_TARGET_NAME} has transmitting AMPDU. Wi-Fi Fragment ------------------------- -ESP32 supports Wi-Fi receiving fragment, but doesn't support Wi-Fi transmitting fragment. The Wi-Fi transmitting fragment will be supported in future release. +{IDF_TARGET_NAME} supports Wi-Fi receiving fragment, but doesn't support Wi-Fi transmitting fragment. The Wi-Fi transmitting fragment will be supported in future release. WPS Enrolle ------------------------- -ESP32 supports WPS enrollee feature in Wi-Fi mode WIFI_MODE_STA or WIFI_MODE_APSTA. Currently ESP32 supports WPS enrollee type PBC and PIN. +{IDF_TARGET_NAME} supports WPS enrollee feature in Wi-Fi mode WIFI_MODE_STA or WIFI_MODE_APSTA. Currently {IDF_TARGET_NAME} supports WPS enrollee type PBC and PIN. .. _wifi-buffer-usage: @@ -1799,11 +1799,11 @@ Why Buffer Configuration Is Important +++++++++++++++++++++++++++++++++++++++ In order to get a robust, high-performance system, we need to consider the memory usage/configuration very carefully, because: - - the available memory in ESP32 is limited. + - the available memory in {IDF_TARGET_NAME} is limited. - currently, the default type of buffer in LwIP and Wi-Fi drivers is "dynamic", **which means that both the LwIP and Wi-Fi share memory with the application**. Programmers should always keep this in mind; otherwise, they will face a memory issue, such as "running out of heap memory". - - it is very dangerous to run out of heap memory, as this will cause ESP32 an "undefined behavior". Thus, enough heap memory should be reserved for the application, so that it never runs out of it. + - it is very dangerous to run out of heap memory, as this will cause {IDF_TARGET_NAME} an "undefined behavior". Thus, enough heap memory should be reserved for the application, so that it never runs out of it. - the Wi-Fi throughput heavily depends on memory-related configurations, such as the TCP window size, Wi-Fi RX/TX dynamic buffer number, etc. - - the peak heap memory that the ESP32 LwIP/Wi-Fi may consume depends on a number of factors, such as the maximum TCP/UDP connections that the application may have, etc. + - the peak heap memory that the {IDF_TARGET_NAME} LwIP/Wi-Fi may consume depends on a number of factors, such as the maximum TCP/UDP connections that the application may have, etc. - the total memory that the application requires is also an important factor when considering memory configuration. Due to these reasons, there is not a good-for-all application configuration. Rather, we have to consider memory configurations separately for every different application. @@ -1827,9 +1827,9 @@ The peak heap memory that Wi-Fi consumes is the **theoretically-maximum memory** - the maximum packet size that the Wi-Fi driver can send: wifi_tx_pkt_size_max So, the peak memory that the Wi-Fi driver consumes can be calculated with the following formula: - wifi_dynamic_peek_memory = (wifi_rx_dynamic_buf_num * wifi_rx_pkt_size_max) + (wifi_tx_dynamic_buf_num * wifi_tx_pkt_size_max) - -Generally, we do not need to care about the dynamic tx long buffers and dynamic tx long long buffers, because they are management frames which only have a small impact on the system. + wifi_dynamic_peek_memory = (wifi_rx_dynamic_buf_num * wifi_rx_pkt_size_max) + (wifi_tx_dynamic_buf_num * wifi_tx_pkt_size_max) + +Generally, we do not need to care about the dynamic tx long buffers and dynamic tx long long buffers, because they are management frames which only have a small impact on the system. Wi-Fi Menuconfig ----------------------- @@ -1853,13 +1853,13 @@ If you are going to modify the default number or type of buffer, it would be hel default_shape = roundedbox; # labels of diagram nodes - APPL_TASK [label="Application\n task", fontsize=12]; - LwIP_TASK [label="LwIP\n task", fontsize=12]; + APPL_TASK [label="Application\n task", fontsize=12]; + LwIP_TASK [label="LwIP\n task", fontsize=12]; WIFI_TASK [label="Wi-Fi\n task", fontsize=12]; # labels of description nodes - APPL_DESC [label="1> User data", width=120, height=25, shape=note, color=yellow]; - LwIP_DESC [label="2> Pbuf", width=120, height=25, shape=note, color=yellow]; + APPL_DESC [label="1> User data", width=120, height=25, shape=note, color=yellow]; + LwIP_DESC [label="2> Pbuf", width=120, height=25, shape=note, color=yellow]; WIFI_DESC [label="3> Dynamic (Static)\n TX Buffer", width=150, height=40, shape=note, color=yellow]; # node connections @@ -1889,14 +1889,14 @@ The following diagram shows how buffer is allocated/freed in the RX direction: default_shape = roundedbox; # labels of diagram nodes - APPL_TASK [label="Application\n task", fontsize=12]; - LwIP_TASK [label="LwIP\n task", fontsize=12]; + APPL_TASK [label="Application\n task", fontsize=12]; + LwIP_TASK [label="LwIP\n task", fontsize=12]; WIFI_TASK [label="Wi-Fi\n task", fontsize=12]; WIFI_INTR [label="Wi-Fi\n interrupt", fontsize=12]; # labels of description nodes - APPL_DESC [label="4> User\n Data Buffer", height=40, shape=note, color=yellow]; - LwIP_DESC [label="3> Pbuf", height=40, shape=note, color=yellow]; + APPL_DESC [label="4> User\n Data Buffer", height=40, shape=note, color=yellow]; + LwIP_DESC [label="3> Pbuf", height=40, shape=note, color=yellow]; WIFI_DESC [label="2> Dynamic\n RX Buffer", height=40, shape=note, color=yellow]; INTR_DESC [label="1> Static\n RX Buffer", height=40, shape=note, color=yellow]; @@ -1940,7 +1940,7 @@ The diagram shows the configuration of the Wi-Fi internal buffer. +------------------+------------+------------+--------------+---------------------------------------+ | Dynamic RX Buffer| Dynamic | 32 | Yes | The buffer length is variable and it | | | | | | depends on the received frames' | -| | | | | length. When the Wi-Fi driver receives| +| | | | | length. When the Wi-Fi driver receives| | | | | | a frame from the 'Hardware Rx Buffer',| | | | | | the 'Dynamic Rx Buffer' needs to be | | | | | | allocated from the heap. The number of| @@ -1963,7 +1963,7 @@ The diagram shows the configuration of the Wi-Fi internal buffer. | | | 1600Bytes | | initialized in esp_wifi_init() and | | | | | | freed in esp_wifi_deinit(). | | | | | | When the upper-layer (LwIP) sends | -| | | | | packets to the Wi-Fi driver, it | +| | | | | packets to the Wi-Fi driver, it | | | | | | firstly allocates a 'Static TX Buffer'| | | | | | and makes a copy of the upper-layer | | | | | | buffer. | @@ -1991,10 +1991,10 @@ Wi-Fi NVS Flash +++++++++++++++++++++ If the Wi-Fi NVS flash is enabled, all Wi-Fi configurations set via the Wi-Fi APIs will be stored into flash, and the Wi-Fi driver will start up with these configurations next time it powers on/reboots. However, the application can choose to disable the Wi-Fi NVS flash if it does not need to store the configurations into persistent memory, or has its own persistent storage, or simply due to debugging reasons, etc. -Wi-Fi AMPDU +Wi-Fi AMPDU +++++++++++++++++++++++++++ -ESP32 supports both receiving and transmitting AMPDU, the AMPDU can greatly improve the Wi-Fi throughput. +{IDF_TARGET_NAME} supports both receiving and transmitting AMPDU, the AMPDU can greatly improve the Wi-Fi throughput. Generally, the AMPDU should be enabled. Disabling AMPDU is usually for debugging purposes. @@ -2007,4 +2007,4 @@ Please refer to a separate document with :doc:`wireshark-user-guide`. :hidden: wireshark-user-guide - + diff --git a/docs/en/api-reference/network/esp_wifi.rst b/docs/en/api-reference/network/esp_wifi.rst index 17dde21e3..5397aadaf 100644 --- a/docs/en/api-reference/network/esp_wifi.rst +++ b/docs/en/api-reference/network/esp_wifi.rst @@ -6,11 +6,11 @@ Wi-Fi Introduction ------------ -The WiFi libraries provide support for configuring and monitoring the ESP32 WiFi networking functionality. This includes configuration for: +The WiFi libraries provide support for configuring and monitoring the {IDF_TARGET_NAME} WiFi networking functionality. This includes configuration for: -- Station mode (aka STA mode or WiFi client mode). ESP32 connects to an access point. -- AP mode (aka Soft-AP mode or Access Point mode). Stations connect to the ESP32. -- Combined AP-STA mode (ESP32 is concurrently an access point and a station connected to another access point). +- Station mode (aka STA mode or WiFi client mode). {IDF_TARGET_NAME} connects to an access point. +- AP mode (aka Soft-AP mode or Access Point mode). Stations connect to the {IDF_TARGET_NAME}. +- Combined AP-STA mode ({IDF_TARGET_NAME} is concurrently an access point and a station connected to another access point). - Various security modes for the above (WPA, WPA2, WEP, etc.) - Scanning for access points (active & passive scanning). diff --git a/docs/en/api-reference/peripherals/adc.rst b/docs/en/api-reference/peripherals/adc.rst index 4fcf6cb74..0dba625dc 100644 --- a/docs/en/api-reference/peripherals/adc.rst +++ b/docs/en/api-reference/peripherals/adc.rst @@ -4,24 +4,27 @@ Analog to Digital Converter Overview -------- -The ESP32 integrates two 12-bit SAR (`Successive Approximation Register `_) ADCs supporting a total of 18 measurement channels (analog enabled pins). +The {IDF_TARGET_NAME} integrates two 12-bit SAR (`Successive Approximation Register `_) ADCs supporting a total of 18 measurement channels (analog enabled pins). -The ADC driver API supports ADC1 (8 channels, attached to GPIOs 32 - 39), and ADC2 (10 channels, attached to GPIOs 0, 2, 4, 12 - 15 and 25 - 27). However, the usage of ADC2 has some restrictions for the application: -1. ADC2 is used by the Wi-Fi driver. Therefore the application can only use ADC2 when the Wi-Fi driver has not started. -2. Some of the ADC2 pins are used as strapping pins (GPIO 0, 2, 15) thus cannot be used freely. Such is the case in the following official Development Kits: +..only:: esp32 - - :ref:`ESP32 DevKitC `: GPIO 0 cannot be used due to external auto program circuits. - - :ref:`ESP-WROVER-KIT `: GPIO 0, 2, 4 and 15 cannot be used due to external connections for different purposes. + The ADC driver API supports ADC1 (8 channels, attached to GPIOs 32 - 39), and ADC2 (10 channels, attached to GPIOs 0, 2, 4, 12 - 15 and 25 - 27). However, the usage of ADC2 has some restrictions for the application: + + 1. ADC2 is used by the Wi-Fi driver. Therefore the application can only use ADC2 when the Wi-Fi driver has not started. + 2. Some of the ADC2 pins are used as strapping pins (GPIO 0, 2, 15) thus cannot be used freely. Such is the case in the following official Development Kits: + + - :ref:`ESP32 DevKitC `: GPIO 0 cannot be used due to external auto program circuits. + - :ref:`ESP-WROVER-KIT `: GPIO 0, 2, 4 and 15 cannot be used due to external connections for different purposes. Configuration and Reading ADC ----------------------------- The ADC should be configured before reading is taken. - - For ADC1, configure desired precision and attenuation by calling functions :cpp:func:`adc1_config_width` and :cpp:func:`adc1_config_channel_atten`. + - For ADC1, configure desired precision and attenuation by calling functions :cpp:func:`adc1_config_width` and :cpp:func:`adc1_config_channel_atten`. - For ADC2, configure the attenuation by :cpp:func:`adc2_config_channel_atten`. The reading width of ADC2 is configured every time you take the reading. - + Attenuation configuration is done per channel, see :cpp:type:`adc1_channel_t` and :cpp:type:`adc2_channel_t`, set as a parameter of above functions. Then it is possible to read ADC conversion result with :cpp:func:`adc1_get_raw` and :cpp:func:`adc2_get_raw`. Reading width of ADC2 should be set as a parameter of :cpp:func:`adc2_get_raw` instead of in the configuration functions. @@ -55,7 +58,7 @@ Reading voltage on ADC2 channel 7 (GPIO 27):: #include ... - + int read_raw; adc2_config_channel_atten( ADC2_CHANNEL_7, ADC_ATTEN_0db ); @@ -87,23 +90,23 @@ The value read in both these examples is 12 bits wide (range 0-4095). Minimizing Noise ---------------- -The ESP32 ADC can be sensitive to noise leading to large discrepancies in ADC readings. To minimize noise, users may connect a 0.1uF capacitor to the ADC input pad in use. Multisampling may also be used to further mitigate the effects of noise. +The {IDF_TARGET_NAME} ADC can be sensitive to noise leading to large discrepancies in ADC readings. To minimize noise, users may connect a 0.1uF capacitor to the ADC input pad in use. Multisampling may also be used to further mitigate the effects of noise. .. figure:: ../../../_static/adc-noise-graph.jpg :align: center :alt: ADC noise mitigation - + Graph illustrating noise mitigation using capacitor and multisampling of 64 samples. ADC Calibration --------------- -The :component_file:`esp_adc_cal/include/esp_adc_cal.h` API provides functions to correct for differences in measured voltages caused by variation of ADC reference voltages (Vref) between chips. Per design the ADC reference voltage is 1100mV, however the true reference voltage can range from 1000mV to 1200mV amongst different ESP32s. +The :component_file:`esp_adc_cal/include/esp_adc_cal.h` API provides functions to correct for differences in measured voltages caused by variation of ADC reference voltages (Vref) between chips. Per design the ADC reference voltage is 1100mV, however the true reference voltage can range from 1000mV to 1200mV amongst different {IDF_TARGET_NAME}s. .. figure:: ../../../_static/adc-vref-graph.jpg :align: center :alt: ADC reference voltage comparison - + Graph illustrating effect of differing reference voltages on the ADC voltage curve. Correcting ADC readings using this API involves characterizing one of the ADCs at a given attenuation to obtain a characteristics curve (ADC-Voltage curve) that takes into account the difference in ADC reference voltage. The characteristics curve is in the form of ``y = coeff_a * x + coeff_b`` and is used to convert ADC readings to voltages in mV. Calculation of the characteristics curve is based on calibration values which can be stored in eFuse or provided by the user. @@ -111,21 +114,23 @@ Correcting ADC readings using this API involves characterizing one of the ADCs a Calibration Values ^^^^^^^^^^^^^^^^^^ -Calibration values are used to generate characteristic curves that account for the unique ADC reference voltage of a particular ESP32. There are currently three sources of calibration values. The availability of these calibration values will depend on the type and production date of the ESP32 chip/module. +Calibration values are used to generate characteristic curves that account for the unique ADC reference voltage of a particular {IDF_TARGET_NAME}. There are currently three sources of calibration values. The availability of these calibration values will depend on the type and production date of the {IDF_TARGET_NAME} chip/module. * **Two Point** values represent each of the ADCs’ readings at 150mV and 850mV. To obtain more accurate calibration results these values should be measured by user and burned into eFuse ``BLOCK3``. -* **eFuse Vref** represents the true ADC reference voltage. This value is measured and burned into eFuse ``BLOCK0`` during factory calibration. +* **eFuse Vref** represents the true ADC reference voltage. This value is measured and burned into eFuse ``BLOCK0`` during factory calibration. * **Default Vref** is an estimate of the ADC reference voltage provided by the user as a parameter during characterization. If Two Point or eFuse Vref values are unavailable, **Default Vref** will be used. -Individual measurement and burning of the **eFuse Vref** has been applied to ESP32-D0WD and ESP32-D0WDQ6 chips produced on/after the 1st week of 2018. Such chips may be recognized by date codes on/later than 012018 (see Line 4 on figure below). +.. only:: esp32 -.. figure:: ../../../_static/chip_surface_marking.png - :align: center - :alt: ESP32 Chip Surface Marking - - ESP32 Chip Surface Marking + Individual measurement and burning of the **eFuse Vref** has been applied to ESP32-D0WD and ESP32-D0WDQ6 chips produced on/after the 1st week of 2018. Such chips may be recognized by date codes on/later than 012018 (see Line 4 on figure below). + + .. figure:: ../../../_static/chip_surface_marking.png + :align: center + :alt: ESP32 Chip Surface Marking + + ESP32 Chip Surface Marking If you would like to purchase chips or modules with calibration, double check with distributor or Espressif directly. @@ -135,7 +140,7 @@ If you are unable to check the date code (i.e. the chip may be enclosed inside a $IDF_PATH/components/esptool_py/esptool/espefuse.py --port /dev/ttyUSB0 adc_info -Replace ``/dev/ttyUSB0`` with ESP32 board's port name. +Replace ``/dev/ttyUSB0`` with {IDF_TARGET_NAME} board's port name. A chip that has specific **eFuse Vref** value programmed (in this case 1093mV) will be reported as follows:: @@ -163,9 +168,9 @@ Characterizing an ADC at a particular attenuation:: #include "driver/adc.h" #include "esp_adc_cal.h" - + ... - + //Characterize ADC at particular atten esp_adc_cal_characteristics_t *adc_chars = calloc(1, sizeof(esp_adc_cal_characteristics_t)); esp_adc_cal_value_t val_type = esp_adc_cal_characterize(unit, atten, ADC_WIDTH_BIT_12, DEFAULT_VREF, adc_chars); @@ -182,15 +187,15 @@ Reading an ADC then converting the reading to a voltage:: #include "driver/adc.h" #include "esp_adc_cal.h" - + ... uint32_t reading = adc1_get_raw(ADC1_CHANNEL_5); uint32_t voltage = esp_adc_cal_raw_to_voltage(reading, adc_chars); - + Routing ADC reference voltage to GPIO, so it can be manually measured (for **Default Vref**):: #include "driver/adc.h" - + ... esp_err_t status = adc2_vref_to_gpio(GPIO_NUM_25); diff --git a/docs/en/api-reference/peripherals/can.rst b/docs/en/api-reference/peripherals/can.rst index d6d986722..bb63366d9 100644 --- a/docs/en/api-reference/peripherals/can.rst +++ b/docs/en/api-reference/peripherals/can.rst @@ -6,10 +6,10 @@ Controller Area Network (CAN) Overview -------- -The ESP32's peripherals contains a CAN Controller that supports Standard Frame Format (11-bit ID) and Extended Frame Format (29-bit ID) of the CAN2.0B specification. +The {IDF_TARGET_NAME}'s peripherals contains a CAN Controller that supports Standard Frame Format (11-bit ID) and Extended Frame Format (29-bit ID) of the CAN2.0B specification. .. warning:: - The ESP32 CAN controller is not compatible with CAN FD frames and will interpret such frames as errors. + The {IDF_TARGET_NAME} CAN controller is not compatible with CAN FD frames and will interpret such frames as errors. This programming guide is split into the following sections: @@ -199,9 +199,11 @@ Bit timing **macro initializers** are also available for commonly used CAN bus b - ``CAN_TIMING_CONFIG_800KBITS()`` - ``CAN_TIMING_CONFIG_1MBITS()`` -.. note:: - The macro initializers for 12.5K, 16K, and 20K bit rates are only available - for ESP32 revision 2 or later. +.. only::esp32 + + .. note:: + The macro initializers for 12.5K, 16K, and 20K bit rates are only available + for ESP32 revision 2 or later. Acceptance Filter ^^^^^^^^^^^^^^^^^ @@ -477,7 +479,7 @@ The following example shows how the calculate the acceptance mask given multiple Application Examples ^^^^^^^^^^^^^^^^^^^^ -**Network Example:** The CAN Network example demonstrates communication between two ESP32s using the CAN driver API. One CAN node acts as a network master initiate and ceasing the transfer of a data from another CAN node acting as a network slave. The example can be found via :example:`peripherals/can/can_network`. +**Network Example:** The CAN Network example demonstrates communication between two {IDF_TARGET_NAME}s using the CAN driver API. One CAN node acts as a network master initiate and ceasing the transfer of a data from another CAN node acting as a network slave. The example can be found via :example:`peripherals/can/can_network`. **Alert and Recovery Example:** This example demonstrates how to use the CAN driver's alert and bus recovery API. The example purposely introduces errors on the CAN bus to put the CAN controller into the Bus-Off state. An alert is used to detect the Bus-Off state and trigger the bus recovery process. The example can be found via :example:`peripherals/can/can_alert_and_recovery`. diff --git a/docs/en/api-reference/peripherals/dac.rst b/docs/en/api-reference/peripherals/dac.rst index d6581e7b7..e9496f0ec 100644 --- a/docs/en/api-reference/peripherals/dac.rst +++ b/docs/en/api-reference/peripherals/dac.rst @@ -4,7 +4,13 @@ Digital To Analog Converter Overview -------- -ESP32 has two 8-bit DAC (digital to analog converter) channels, connected to GPIO25 (Channel 1) and GPIO26 (Channel 2). +.. only:: esp32 + + {IDF_TARGET_NAME} has two 8-bit DAC (digital to analog converter) channels, connected to GPIO25 (Channel 1) and GPIO26 (Channel 2). + +.. only:: esp32s2beta + + {IDF_TARGET_NAME} has two 8-bit DAC (digital to analog converter) channels, connected to GPIO17 (Channel 1) and GPIO18 (Channel 2). The DAC driver allows these channels to be set to arbitrary voltages. diff --git a/docs/en/api-reference/peripherals/esp_slave_protocol.rst b/docs/en/api-reference/peripherals/esp_slave_protocol.rst index e99f7830a..c0650a966 100644 --- a/docs/en/api-reference/peripherals/esp_slave_protocol.rst +++ b/docs/en/api-reference/peripherals/esp_slave_protocol.rst @@ -6,7 +6,7 @@ Communication with ESP SDIO Slave ESP SDIO slave initialization ------------------------------ -The host should initialize the ESP32 SDIO slave according to the standard +The host should initialize the {IDF_TARGET_NAME} SDIO slave according to the standard SDIO initialization process (Sector 3.1.2 of `SDIO Simplified Specification `_). In this specification and below, the SDIO slave is also called an (SD)IO card. All the diff --git a/docs/en/api-reference/peripherals/gpio.rst b/docs/en/api-reference/peripherals/gpio.rst index fb340e0ca..87a472975 100644 --- a/docs/en/api-reference/peripherals/gpio.rst +++ b/docs/en/api-reference/peripherals/gpio.rst @@ -4,10 +4,18 @@ GPIO & RTC GPIO Overview -------- -The ESP32 chip features 40 physical GPIO pads. Some GPIO pads cannot be used or do not have the corresponding pin on the chip package(refer to technical reference manual). Each pad can be used as a general purpose I/O or can be connected to an internal peripheral signal. +.. only:: esp32 + + The {IDF_TARGET_NAME} chip features 40 physical GPIO pads. Some GPIO pads cannot be used or do not have the corresponding pin on the chip package(refer to technical reference manual). Each pad can be used as a general purpose I/O or can be connected to an internal peripheral signal. + + - Note that GPIO6-11 are usually used for SPI flash. + - GPIO34-39 can only be set as input mode and do not have software pullup or pulldown functions. + +.. only:: esp32s2beta + + The {IDF_TARGET_NAME} chip features 43 physical GPIO pads. Some GPIO pads cannot be used or do not have the corresponding pin on the chip package(refer to technical reference manual). Each pad can be used as a general purpose I/O or can be connected to an internal peripheral signal. + -- Note that GPIO6-11 are usually used for SPI flash. -- GPIO34-39 can only be set as input mode and do not have software pullup or pulldown functions. There is also separate "RTC GPIO" support, which functions when GPIOs are routed to the "RTC" low-power and analog subsystem. These pin functions can be used when in deep sleep, when the :doc:`Ultra Low Power co-processor <../../api-guides/ulp>` is running, or when analog functions such as ADC/DAC/etc are in use. diff --git a/docs/en/api-reference/peripherals/i2c.rst b/docs/en/api-reference/peripherals/i2c.rst index 59e58bb7f..0a4967871 100644 --- a/docs/en/api-reference/peripherals/i2c.rst +++ b/docs/en/api-reference/peripherals/i2c.rst @@ -8,7 +8,7 @@ I2C is a serial, synchronous, half-duplex communication protocol that allows co- With such advantages as simplicity and low manufacturing cost, I2C is mostly used for communication of low-speed peripheral devices over short distances (within one foot). -ESP32 has two I2C controllers (also referred to as ports) which are responsible for handling communications on two I2C buses. Each I2C controller can operate as master or slave. As an example, one controller can act as a master and the other as a slave at the same time. +{IDF_TARGET_NAME} has two I2C controllers (also referred to as ports) which are responsible for handling communications on two I2C buses. Each I2C controller can operate as master or slave. As an example, one controller can act as a master and the other as a slave at the same time. Driver Features @@ -50,7 +50,7 @@ To establish I2C communication, start by configuring the driver. This is done by - Configure **communication pins** - Assign GPIO pins for SDA and SCL signals - - Set whether to enable ESP32's internal pull-ups + - Set whether to enable {IDF_TARGET_NAME}'s internal pull-ups - (Master only) Set I2C **clock speed** - (Slave only) Configure the following @@ -81,9 +81,9 @@ After the I2C driver is configured, install it by calling the function :cpp:func Communication as Master ^^^^^^^^^^^^^^^^^^^^^^^ -After installing the I2C driver, ESP32 is ready to communicate with other I2C devices. +After installing the I2C driver, {IDF_TARGET_NAME} is ready to communicate with other I2C devices. -ESP32's I2C controller operating as master is responsible for establishing communication with I2C slave devices and sending commands to trigger a slave to action, for example, to take a measurement and send the readings back to the master. +{IDF_TARGET_NAME}'s I2C controller operating as master is responsible for establishing communication with I2C slave devices and sending commands to trigger a slave to action, for example, to take a measurement and send the readings back to the master. For better process organization, the driver provides a container, called a "command link", that should be populated with a sequence of commands and then passed to the I2C controller for execution. @@ -155,7 +155,7 @@ Likewise, the command link to read from the slave looks as follows: Communication as Slave ^^^^^^^^^^^^^^^^^^^^^^ -After installing the I2C driver, ESP32 is ready to communicate with other I2C devices. +After installing the I2C driver, {IDF_TARGET_NAME} is ready to communicate with other I2C devices. The API provides the following functions for slaves @@ -179,7 +179,6 @@ During driver installation, an interrupt handler is installed by default. Howeve To delete an interrupt handler, call :cpp:func:`i2c_isr_free`. - .. _i2c-api-customized-configuration: Customized Configuration @@ -217,7 +216,7 @@ You can also select different pins for SDA and SCL signals and alter the configu .. note:: - ESP32's internal pull-ups are in the range of tens of kOhm, which is, in most cases, insufficient for use as I2C pull-ups. Users are advised to use external pull-ups with values described in the `I2C specification `_. + {IDF_TARGET_NAME}'s internal pull-ups are in the range of tens of kOhm, which is, in most cases, insufficient for use as I2C pull-ups. Users are advised to use external pull-ups with values described in the `I2C specification `_. .. _i2c-api-error-handling: diff --git a/docs/en/api-reference/peripherals/i2s.rst b/docs/en/api-reference/peripherals/i2s.rst index 37907c046..7f4148d7c 100644 --- a/docs/en/api-reference/peripherals/i2s.rst +++ b/docs/en/api-reference/peripherals/i2s.rst @@ -6,7 +6,7 @@ Overview I2S (Inter-IC Sound) is a serial, synchronous communication protocol that is usually used for transmitting audio data between two digital audio devices. -ESP32 integrates two I2S controllers, referred to as I2S0 and I2S1, both of which can be used for streaming audio and video digital data. +{IDF_TARGET_NAME} integrates two I2S controllers, referred to as I2S0 and I2S1, both of which can be used for streaming audio and video digital data. An I2S bus consists of the following lines: @@ -30,7 +30,9 @@ The I2S peripherals also support LCD mode for communicating data over a parallel - Camera slave receiving mode - ADC/DAC mode -For more information, see the `ESP32 Technical Reference Manual `_. +.. only:: esp32 + + For more information, see the `ESP32 Technical Reference Manual `_. .. note:: @@ -198,7 +200,7 @@ Configuring I2S to use internal DAC for analog output i2s_set_pin(i2s_num, NULL); //for internal DAC, this will enable both of the internal channels //You can call i2s_set_dac_mode to set built-in DAC output mode. - //i2s_set_dac_mode(I2S_DAC_CHANNEL_BOTH_EN); + //i2s_set_dac_mode(I2S_DAC_CHANNEL_BOTH_EN); i2s_set_sample_rates(i2s_num, 22050); //set sample rates diff --git a/docs/en/api-reference/peripherals/ledc.rst b/docs/en/api-reference/peripherals/ledc.rst index a726c83aa..17587e3b4 100644 --- a/docs/en/api-reference/peripherals/ledc.rst +++ b/docs/en/api-reference/peripherals/ledc.rst @@ -6,7 +6,7 @@ LED Control Introduction ------------ -The LED control (LEDC) peripheral is primarily designed to control the intensity of LEDs, although it can also be used to generate PWM signals for other purposes as well. It has 16 channels which can generate independent waveforms that can be used, for example, to drive RGB LED devices. +The LED control (LEDC) peripheral is primarily designed to control the intensity of LEDs, although it can also be used to generate PWM signals for other purposes as well. It has 16 channels which can generate independent waveforms that can be used, for example, to drive RGB LED devices. A half of LEDC's channels operate in high speed mode. This mode is implemented in hardware and offers automatic and glitch-free changing of the PWM duty cycle. The other half of channels operate in low speed mode, where the moment of change depends on the application software. Each group of channels is also able to use different clock sources. @@ -121,7 +121,7 @@ The first two functions are called "behind the scenes" by :cpp:func:`ledc_channe Use Interrupts ^^^^^^^^^^^^^^ -When configuring an LEDC channel, one of the parameters selected within :cpp:type:`ledc_channel_config_t` is :cpp:type:`ledc_intr_type_t` which triggers an interrupt on fade completion. +When configuring an LEDC channel, one of the parameters selected within :cpp:type:`ledc_channel_config_t` is :cpp:type:`ledc_intr_type_t` which triggers an interrupt on fade completion. For registration of a handler to address this interrupt, call :cpp:func:`ledc_isr_register`. @@ -135,8 +135,13 @@ Of the total 8 timers and 16 channels available in the LED PWM Controller, half The advantage of high speed mode is glitch-free changeover of the timer settings. This means that if the timer settings are modified, the changes will be applied automatically on the next overflow interrupt of the timer. In contrast, when updating the low-speed timer, the change of settings should be explicitly triggered by software. The LEDC driver handles it in the background, e.g., when :cpp:func:`ledc_timer_config` or :cpp:func:`ledc_timer_set` is called. -For additional details regarding speed modes, refer to `ESP32 Technical Reference Manual `_ (PDF). Please note that the support for ``SLOW_CLOCK`` mentioned in this manual is not yet supported in the LEDC driver. +.. only:: esp32 + For additional details regarding speed modes, refer to `ESP32 Technical Reference Manual `_ (PDF). Please note that the support for ``SLOW_CLOCK`` mentioned in this manual is not yet supported in the LEDC driver. + +.. only:: esp32s2beta + + For additional details regarding speed modes, refer to `ESP32-S2 Technical Reference Manual `_ (PDF). Please note that the support for ``SLOW_CLOCK`` mentioned in this manual is not yet supported in the LEDC driver. .. _ledc-api-supported-range-frequency-duty-resolution: @@ -163,7 +168,7 @@ The LEDC driver will also capture and report attempts to configure frequency / d E (196) ledc: requested frequency and duty resolution cannot be achieved, try increasing freq_hz or duty_resolution. div_param=128000000 -The duty resolution is normally set using :cpp:type:`ledc_timer_bit_t`. This enumeration covers the range from 10 to 15 bits. If a smaller duty resolution is required (from 10 down to 1), enter the equivalent numeric values directly. +The duty resolution is normally set using :cpp:type:`ledc_timer_bit_t`. This enumeration covers the range from 10 to 15 bits. If a smaller duty resolution is required (from 10 down to 1), enter the equivalent numeric values directly. Application Example diff --git a/docs/en/api-reference/peripherals/mcpwm.rst b/docs/en/api-reference/peripherals/mcpwm.rst index d21d25c60..55743df6c 100644 --- a/docs/en/api-reference/peripherals/mcpwm.rst +++ b/docs/en/api-reference/peripherals/mcpwm.rst @@ -1,7 +1,7 @@ MCPWM ===== -ESP32 has two MCPWM units which can be used to control different types of motors. Each unit has three pairs of PWM outputs. +{IDF_TARGET_NAME} has two MCPWM units which can be used to control different types of motors. Each unit has three pairs of PWM outputs. .. figure:: ../../../_static/mcpwm-overview.png :align: center @@ -53,7 +53,7 @@ In this case we will describe a simple configuration to control a brushed DC mot Configuration covers the following steps: -1. Selection of a MPWn unit that will be used to drive the motor. There are two units available on-board of ESP32 and enumerated in :cpp:type:`mcpwm_unit_t`. +1. Selection of a MPWn unit that will be used to drive the motor. There are two units available on-board of {IDF_TARGET_NAME} and enumerated in :cpp:type:`mcpwm_unit_t`. 2. Initialization of two GPIOs as output signals within selected unit by calling :cpp:func:`mcpwm_gpio_init`. The two output signals are typically used to command the motor to rotate right or left. All available signal options are listed in :cpp:type:`mcpwm_io_signals_t`. To set more than a single pin at a time, use function :cpp:func:`mcpwm_set_pin` together with :cpp:type:`mcpwm_pin_config_t`. 3. Selection of a timer. There are three timers available within the unit. The timers are listed in :cpp:type:`mcpwm_timer_t`. 4. Setting of the timer frequency and initial duty within :cpp:type:`mcpwm_config_t` structure. @@ -89,8 +89,13 @@ There are couple of ways to adjust a signal on the outputs and changing how the Synchronization signals are referred to using two different enumerations. First one :cpp:type:`mcpwm_io_signals_t` is used together with function :cpp:func:`mcpwm_gpio_init` when selecting a GPIO as the signal input source. The second one :cpp:type:`mcpwm_sync_signal_t` is used when enabling or disabling synchronization with :cpp:func:`mcpwm_sync_enable` or :cpp:func:`mcpwm_sync_disable`. -* Vary the pattern of the A/B output signals by getting MCPWM counters to count up, down and up/down (automatically changing the count direction). Respective configuration is done when calling :cpp:func:`mcpwm_init`, as discussed in section `Configure`_, and selecting one of counter types from :cpp:type:`mcpwm_counter_type_t`. For explanation of how A/B PWM output signals are generated please refer to `ESP32 Technical Reference Manual`_. +.. only:: esp32 + * Vary the pattern of the A/B output signals by getting MCPWM counters to count up, down and up/down (automatically changing the count direction). Respective configuration is done when calling :cpp:func:`mcpwm_init`, as discussed in section `Configure`_, and selecting one of counter types from :cpp:type:`mcpwm_counter_type_t`. For explanation of how A/B PWM output signals are generated please refer to `ESP32 Technical Reference Manual`_. + +.. only:: esp32s2beta + + * Vary the pattern of the A/B output signals by getting MCPWM counters to count up, down and up/down (automatically changing the count direction). Respective configuration is done when calling :cpp:func:`mcpwm_init`, as discussed in section `Configure`_, and selecting one of counter types from :cpp:type:`mcpwm_counter_type_t`. For explanation of how A/B PWM output signals are generated please refer to `ESP32-S2 Technical Reference Manual`_. Capture ------- @@ -171,6 +176,8 @@ Examples of using MCPWM for motor control: :example:`peripherals/mcpwm`: .. _ESP32 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf +.. _ESP32-S2 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32s2_technical_reference_manual_en.pdf + API Reference ------------- diff --git a/docs/en/api-reference/peripherals/rmt.rst b/docs/en/api-reference/peripherals/rmt.rst index c4c798549..005333a01 100644 --- a/docs/en/api-reference/peripherals/rmt.rst +++ b/docs/en/api-reference/peripherals/rmt.rst @@ -105,7 +105,7 @@ Common Parameters * The **channel** to be configured, select one from the :cpp:type:`rmt_channel_t` enumerator. * The RMT **operation mode** - whether this channel is used to transmit or receive data, selected by setting a **rmt_mode** members to one of the values from :cpp:type:`rmt_mode_t`. -* What is the **pin number** to transmit or receive RMT signals, selected by setting **gpio_num**. +* What is the **pin number** to transmit or receive RMT signals, selected by setting **gpio_num**. * How many **memory blocks** will be used by the channel, set with **mem_block_num**. * A **clock divider**, that will determine the range of pulse length generated by the RMT transmitter or discriminated by the receiver. Selected by setting **clk_div** to a value within [1 .. 255] range. The RMT source clock is typically APB CLK, 80Mhz by default. @@ -123,7 +123,7 @@ When configuring channel in transmit mode, set **tx_config** and the following m * Transmit the currently configured data items in a loop - **loop_en** * Enable the RMT carrier signal - **carrier_en** -* Frequency of the carrier in Hz - **carrier_freq_hz** +* Frequency of the carrier in Hz - **carrier_freq_hz** * Duty cycle of the carrier signal in percent (%) - **carrier_duty_percent** * Level of the RMT output, when the carrier is applied - **carrier_level** * Enable the RMT output if idle - **idle_output_en** @@ -153,14 +153,14 @@ Now, depending on how the channel is configured, we are ready to either `Transmi Transmit Data ------------- -Before being able to transmit some RMT pulses, we need to define the pulse pattern. The minimum pattern recognized by the RMT controller, later called an 'item', is provided in a structure :cpp:type:`rmt_item32_t`, see :component_file:`soc/esp32/include/soc/rmt_caps.h`. Each item consists of two pairs of two values. The first value in a pair describes the signal duration in ticks and is 15 bits long, the second provides the signal level (high or low) and is contained in a single bit. A block of couple of items and the structure of an item is presented below. +Before being able to transmit some RMT pulses, we need to define the pulse pattern. The minimum pattern recognized by the RMT controller, later called an 'item', is provided in a structure :cpp:type:`rmt_item32_t`, see :component_file:`soc/{IDF_TARGET_PATH_NAME}/include/soc/rmt_caps.h`. Each item consists of two pairs of two values. The first value in a pair describes the signal duration in ticks and is 15 bits long, the second provides the signal level (high or low) and is contained in a single bit. A block of couple of items and the structure of an item is presented below. .. packetdiag:: :caption: Structure of RMT items (L - signal level) :align: center packetdiag rmt_items { - colwidth = 32 + colwidth = 32 node_width = 10 node_height = 24 default_fontsize = 12 @@ -180,7 +180,7 @@ For a simple example how to define a block of items see :example:`peripherals/rm The items are provided to the RMT controller by calling function :cpp:func:`rmt_write_items`. This function also automatically triggers start of transmission. It may be called to wait for transmission completion or exit just after transmission start. In such case you can wait for the transmission end by calling :cpp:func:`rmt_wait_tx_done`. This function does not limit the number of data items to transmit. It is using an interrupt to successively copy the new data chunks to RMT's internal memory as previously provided data are sent out. -Another way to provide data for transmission is by calling :cpp:func:`rmt_fill_tx_items`. In this case transmission is not started automatically. To control the transmission process use :cpp:func:`rmt_tx_start` and :cpp:func:`rmt_tx_stop`. The number of items to sent is restricted by the size of memory blocks allocated in the RMT controller's internal memory, see :cpp:func:`rmt_set_mem_block_num`. +Another way to provide data for transmission is by calling :cpp:func:`rmt_fill_tx_items`. In this case transmission is not started automatically. To control the transmission process use :cpp:func:`rmt_tx_start` and :cpp:func:`rmt_tx_stop`. The number of items to sent is restricted by the size of memory blocks allocated in the RMT controller's internal memory, see :cpp:func:`rmt_set_mem_block_num`. Receive Data @@ -227,11 +227,11 @@ Receive Mode Parameters Use Interrupts -------------- -Registering of an interrupt handler for the RMT controller is done be calling :cpp:func:`rmt_isr_register`. +Registering of an interrupt handler for the RMT controller is done be calling :cpp:func:`rmt_isr_register`. .. note:: - When calling :cpp:func:`rmt_driver_install` to use the system RMT driver, a default ISR is being installed. In such a case you cannot register a generic ISR handler with :cpp:func:`rmt_isr_register`. + When calling :cpp:func:`rmt_driver_install` to use the system RMT driver, a default ISR is being installed. In such a case you cannot register a generic ISR handler with :cpp:func:`rmt_isr_register`. The RMT controller triggers interrupts on four specific events describes below. To enable interrupts on these events, the following functions are provided: @@ -242,7 +242,7 @@ The RMT controller triggers interrupts on four specific events describes below. Setting or clearing an interrupt enable mask for specific channels and events may be also done by calling :cpp:func:`rmt_set_intr_enable_mask` or :cpp:func:`rmt_clr_intr_enable_mask`. -When servicing an interrupt within an ISR, the interrupt need to explicitly cleared. To do so, set specific bits described as ``RMT.int_clr.val.chN_event_name`` and defined as a ``volatile struct`` in :component_file:`soc/esp32/include/soc/rmt_struct.h`, where N is the RMT channel number [0, 7] and the ``event_name`` is one of four events described above. +When servicing an interrupt within an ISR, the interrupt need to explicitly cleared. To do so, set specific bits described as ``RMT.int_clr.val.chN_event_name`` and defined as a ``volatile struct`` in :component_file:`soc/{IDT_TARGET_PATH_NAME}/include/soc/rmt_struct.h`, where N is the RMT channel number [0, 7] and the ``event_name`` is one of four events described above. If you do not need an ISR anymore, you can deregister it by calling a function :cpp:func:`rmt_isr_deregister`. diff --git a/docs/en/api-reference/protocols/esp_http_server.rst b/docs/en/api-reference/protocols/esp_http_server.rst index 0fffb0873..ed414c2e6 100644 --- a/docs/en/api-reference/protocols/esp_http_server.rst +++ b/docs/en/api-reference/protocols/esp_http_server.rst @@ -5,7 +5,7 @@ HTTP Server Overview -------- -The HTTP Server component provides an ability for running a lightweight web server on ESP32. Following are detailed steps to use the API exposed by HTTP Server: +The HTTP Server component provides an ability for running a lightweight web server on {IDF_TARGET_NAME}. Following are detailed steps to use the API exposed by HTTP Server: * :cpp:func:`httpd_start`: Creates an instance of HTTP server, allocate memory/resources for it depending upon the specified configuration and outputs a handle to the server instance. The server has both, a listening socket (TCP) for HTTP traffic, and a control socket (UDP) for control signals, which are selected in a round robin fashion in the server task loop. The task priority and stack size are configurable during server instance creation by passing httpd_config_t structure to httpd_start(). TCP traffic is parsed as HTTP requests and, depending on the requested URI, user registered handlers are invoked which are supposed to send back HTTP response packets. * :cpp:func:`httpd_stop`: This stops the server with the provided handle and frees up any associated memory/resources. This is a blocking function that first signals a halt to the server task and then waits for the task to terminate. While stopping, the task will close all open connections, remove registered URI handlers and reset all session context data to empty. diff --git a/docs/en/api-reference/protocols/mdns.rst b/docs/en/api-reference/protocols/mdns.rst index 960169b0f..1370b3015 100644 --- a/docs/en/api-reference/protocols/mdns.rst +++ b/docs/en/api-reference/protocols/mdns.rst @@ -12,8 +12,8 @@ mDNS is installed by default on most operating systems or is available as separa mDNS Properties ^^^^^^^^^^^^^^^ - * ``hostname``: the hostname that the device will respond to. If not set, the ``hostname`` will be read from the interface. Example: ``my-esp32`` will resolve to ``my-esp32.local`` - * ``default_instance``: friendly name for your device, like ``Jhon's ESP32 Thing``. If not set, ``hostname`` will be used. + * ``hostname``: the hostname that the device will respond to. If not set, the ``hostname`` will be read from the interface. Example: ``my-{IDF_TARGET_PATH_NAME}`` will resolve to ``my-{IDF_TARGET_PATH_NAME}.local`` + * ``default_instance``: friendly name for your device, like ``Jhon's {IDF_TARGET_NAME} Thing``. If not set, ``hostname`` will be used. Example method to start mDNS for the STA interface and set ``hostname`` and ``default_instance``: @@ -29,11 +29,11 @@ Example method to start mDNS for the STA interface and set ``hostname`` and ``de printf("MDNS Init failed: %d\n", err); return; } - + //set hostname - mdns_hostname_set("my-esp32"); + mdns_hostname_set("my-{IDF_TARGET_PATH_NAME}"); //set default instance - mdns_instance_name_set("Jhon's ESP32 Thing"); + mdns_instance_name_set("Jhon's {IDF_TARGET_NAME} Thing"); } mDNS Services @@ -41,9 +41,9 @@ mDNS Services mDNS can advertise information about network services that your device offers. Each service is defined by a few properties. - * ``instance_name``: friendly name for your service, like ``Jhon's ESP32 Web Server``. If not defined, ``default_instance`` will be used. + * ``instance_name``: friendly name for your service, like ``Jhon's E{IDF_TARGET_NAME} Web Server``. If not defined, ``default_instance`` will be used. * ``service_type``: (required) service type, prepended with underscore. Some common types can be found `here `_. - * ``proto``: (required) protocol that the service runs on, prepended with underscore. Example: ``_tcp`` or ``_udp`` + * ``proto``: (required) protocol that the service runs on, prepended with underscore. Example: ``_tcp`` or ``_udp`` * ``port``: (required) network port that the service runs on * ``txt``: ``{var, val}`` array of strings, used to define properties for your service @@ -55,19 +55,19 @@ Example method to add a few services and different properties:: mdns_service_add(NULL, "_http", "_tcp", 80, NULL, 0); mdns_service_add(NULL, "_arduino", "_tcp", 3232, NULL, 0); mdns_service_add(NULL, "_myservice", "_udp", 1234, NULL, 0); - + //NOTE: services must be added before their properties can be set //use custom instance for the web server - mdns_service_instance_name_set("_http", "_tcp", "Jhon's ESP32 Web Server"); + mdns_service_instance_name_set("_http", "_tcp", "Jhon's {IDF_TARGET_NAME} Web Server"); mdns_txt_item_t serviceTxtData[3] = { - {"board","esp32"}, + {"board","{{IDF_TARGET_PATH_NAME}}"}, {"u","user"}, {"p","password"} }; //set txt data for service (will free and replace current data) mdns_service_txt_set("_http", "_tcp", serviceTxtData, 3); - + //change service port mdns_service_port_set("_myservice", "_udp", 4321); } @@ -161,9 +161,9 @@ Example method to resolve local services:: Example of using the methods above:: void my_app_some_method(){ - //search for esp32-mdns.local - resolve_mdns_host("esp32-mdns"); - + //search for {IDF_TARGET_PATH_NAME}-mdns.local + resolve_mdns_host("{IDF_TARGET_PATH_NAME}-mdns"); + //search for HTTP servers find_mdns_service("_http", "_tcp"); //or file servers diff --git a/docs/en/api-reference/storage/nvs_flash.rst b/docs/en/api-reference/storage/nvs_flash.rst index 642483cf5..ac02e5168 100644 --- a/docs/en/api-reference/storage/nvs_flash.rst +++ b/docs/en/api-reference/storage/nvs_flash.rst @@ -14,15 +14,15 @@ You can find two code examples in the :example:`storage` directory of ESP-IDF ex Demonstrates how to read a single integer value from, and write it to NVS. - The value checked in this example holds the number of the ESP32 module restarts. The value's function as a counter is only possible due to its storing in NVS. + The value checked in this example holds the number of the {IDF_TARGET_NAME} module restarts. The value's function as a counter is only possible due to its storing in NVS. The example also shows how to check if a read / write operation was successful, or if a certain value has not been initialized in NVS. The diagnostic procedure is provided in plain text to help you track the program flow and capture any issues on the way. :example:`storage/nvs_rw_blob` - Demonstrates how to read a single integer value and a blob (binary large object), and write them to NVS to preserve this value between ESP32 module restarts. + Demonstrates how to read a single integer value and a blob (binary large object), and write them to NVS to preserve this value between {IDF_TARGET_NAME} module restarts. - * value - tracks the number of the ESP32 module soft and hard restarts. + * value - tracks the number of the {IDF_TARGET_NAME} module soft and hard restarts. * blob - contains a table with module run times. The table is read from NVS to dynamically allocated RAM. A new run time is added to the table on each manually triggered soft restart, and then the added run time is written to NVS. Triggering is done by pulling down GPIO0. The example also shows how to implement the diagnostic procedure to check if the read / write operation was successful. diff --git a/docs/en/api-reference/storage/spiffs.rst b/docs/en/api-reference/storage/spiffs.rst index 2bf5ee848..82a054402 100644 --- a/docs/en/api-reference/storage/spiffs.rst +++ b/docs/en/api-reference/storage/spiffs.rst @@ -75,11 +75,11 @@ in CMake:: If FLASH_IN_PROJECT/SPIFFS_IMAGE_FLASH_IN_PROJECT is not specified, the image will still be generated, but you will have to flash it manually using ``esptool.py``, ``parttool.py``, or a custom build system target. There are cases where the contents of the base directory itself is generated at build time. Users can use DEPENDS/SPIFFS_IMAGE_DEPENDS to specify targets -that should be executed before generating the image. +that should be executed before generating the image. in Make:: - dep: + dep: ... SPIFFS_IMAGE_DEPENDS := dep @@ -111,9 +111,9 @@ To pack a folder into a 1-Megabyte image, run:: mkspiffs -c [src_folder] -b 4096 -p 256 -s 0x100000 spiffs.bin -To flash the image onto ESP32 at offset 0x110000, run:: +To flash the image onto {IDF_TARGET_NAME} at offset 0x110000, run:: - python esptool.py --chip esp32 --port [port] --baud [baud] write_flash -z 0x110000 spiffs.bin + python esptool.py --chip {IDF_TARGET_PATH_NAME} --port [port] --baud [baud] write_flash -z 0x110000 spiffs.bin Notes on which SPIFFS tool to use diff --git a/docs/en/api-reference/system/app_image_format.rst b/docs/en/api-reference/system/app_image_format.rst index 4dfe4f537..a2e61ea45 100644 --- a/docs/en/api-reference/system/app_image_format.rst +++ b/docs/en/api-reference/system/app_image_format.rst @@ -4,7 +4,7 @@ App Image Format An application image consists of the following structures: 1. The :cpp:type:`esp_image_header_t` structure describes the mode of SPI flash and the count of memory segments. -2. The :cpp:type:`esp_image_segment_header_t` structure describes each segment, its length, and its location in ESP32's memory, followed by the data with a length of ``data_len``. The data offset for each segment in the image is calculated in the following way: +2. The :cpp:type:`esp_image_segment_header_t` structure describes each segment, its length, and its location in {IDF_TARGET_NAME}'s memory, followed by the data with a length of ``data_len``. The data offset for each segment in the image is calculated in the following way: * offset for 0 Segment = sizeof(:cpp:type:`esp_image_header_t`) + sizeof(:cpp:type:`esp_image_segment_header_t`). * offset for 1 Segment = offset for 0 Segment + length of 0 Segment + sizeof(:cpp:type:`esp_image_segment_header_t`). @@ -17,7 +17,7 @@ To get the list of your image segments, please run the following command: :: - esptool.py --chip esp32 image_info build/app.bin + esptool.py --chip {IDF_TARGET_PATH_NAME} image_info build/app.bin :: @@ -58,8 +58,8 @@ You can also see the information on segments in the IDF logs while your applicat I (971) esp_image: segment 11: paddr=0x000a9b74 vaddr=0x50000004 size=0x00000 ( 0) load I (1012) esp_image: segment 12: paddr=0x000a9b7c vaddr=0x50000004 size=0x00000 ( 0) load -For more details on the type of memory segments and their address ranges, see the ESP32 Technical Reference Manual, Section 1.3.2 *Embedded Memory*. - +For more details on the type of memory segments and their address ranges, see the {IDF_TARGET_NAME} Technical Reference Manual, Section 1.3.2 *Embedded Memory*. + 3. The image has a single checksum byte after the last segment. This byte is written on a sixteen byte padded boundary, so the application image might need padding. 4. If the ``hash_appended`` field from :cpp:type:`esp_image_header_t` is set then a SHA256 checksum will be appended. The value of SHA256 is calculated on the range from first byte and up to this field. The length of this field is 32 bytes. 5. If the options :ref:`CONFIG_SECURE_SIGNED_APPS_NO_SECURE_BOOT` or :ref:`CONFIG_SECURE_BOOT_ENABLED` are enabled then the application image will have additional 68 bytes for an ECDSA signature, which includes: diff --git a/docs/en/api-reference/system/app_trace.rst b/docs/en/api-reference/system/app_trace.rst index 1fb97edca..4e1771a62 100644 --- a/docs/en/api-reference/system/app_trace.rst +++ b/docs/en/api-reference/system/app_trace.rst @@ -4,7 +4,7 @@ Application Level Tracing Overview -------- -IDF provides useful feature for program behaviour analysis: application level tracing. It is implemented in the corresponding library and can be enabled via menuconfig. This feature allows to transfer arbitrary data between host and ESP32 via JTAG interface with small overhead on program execution. +IDF provides useful feature for program behaviour analysis: application level tracing. It is implemented in the corresponding library and can be enabled via menuconfig. This feature allows to transfer arbitrary data between host and {IDF_TARGET_NAME} via JTAG interface with small overhead on program execution. Developers can use this library to send application specific state of execution to the host and receive commands or other type of info in the opposite direction at runtime. The main use cases of this library are: 1. Collecting application specific data, see :ref:`app_trace-application-specific-tracing` diff --git a/docs/en/api-reference/system/efuse.rst b/docs/en/api-reference/system/efuse.rst index 34c741404..f50bda763 100644 --- a/docs/en/api-reference/system/efuse.rst +++ b/docs/en/api-reference/system/efuse.rst @@ -11,15 +11,27 @@ The eFuse Manager library is designed to structure access to eFuse bits and make Hardware description -------------------- -The ESP32 has a number of eFuses which can store system and user parameters. Each eFuse is a one-bit field which can be programmed to 1 after which it cannot be reverted back to 0. -Some of system parameters are using these eFuse bits directly by hardware modules and have special place (for example EFUSE_BLK0). For more details see `ESP32 Technical Reference Manual `_ in part 20 eFuse controller. Some eFuse bits are available for user applications. +The {IDF_TARGET_NAME} has a number of eFuses which can store system and user parameters. Each eFuse is a one-bit field which can be programmed to 1 after which it cannot be reverted back to 0. +Some of system parameters are using these eFuse bits directly by hardware modules and have special place (for example EFUSE_BLK0). + +.. only:: esp32 + + For more details see `ESP32 Technical Reference Manual `_ in part 20 eFuse controller. Some eFuse bits are available for user applications. + + ESP32 has 4 eFuse blocks each of the size of 256 bits (not all bits are available): + + * EFUSE_BLK0 is used entirely for system purposes; + * EFUSE_BLK1 is used for flash encrypt key. If not using that Flash Encryption feature, they can be used for another purpose; + * EFUSE_BLK2 is used for security boot key. If not using that Secure Boot feature, they can be used for another purpose; + * EFUSE_BLK3 can be partially reserved for the custom MAC address, or used entirely for user application. Note that some bits are already used in IDF. + +.. only:: esp32s2 + + For more details see `ESP32-S2 Technical Reference Manual `_. Some eFuse bits are available for user applications. + + {IDF_TARGET_NAME} has 11 eFuse blocks each of the size of 256 bits (not all bits are available): -ESP32 has 4 eFuse blocks each of the size of 256 bits (not all bits are available): -* EFUSE_BLK0 is used entirely for system purposes; -* EFUSE_BLK1 is used for flash encrypt key. If not using that Flash Encryption feature, they can be used for another purpose; -* EFUSE_BLK2 is used for security boot key. If not using that Secure Boot feature, they can be used for another purpose; -* EFUSE_BLK3 can be partially reserved for the custom MAC address, or used entirely for user application. Note that some bits are already used in IDF. Each block is divided into 8 32-bits registers. @@ -62,7 +74,7 @@ bit_count comment This param is using for comment field, it also move to C-header file. The comment field can be omitted. - + If a non-sequential bit order is required to describe a field, then the field description in the following lines should be continued without specifying a name, this will indicate that it belongs to one field. For example two fields MAC_FACTORY and MAC_FACTORY_CRC: :: @@ -76,7 +88,7 @@ If a non-sequential bit order is required to describe a field, then the field de , EFUSE_BLK0, 40, 8, Factory MAC addr [4] , EFUSE_BLK0, 32, 8, Factory MAC addr [5] MAC_FACTORY_CRC, EFUSE_BLK0, 80, 8, CRC8 for factory MAC address - + This field will available in code as ESP_EFUSE_MAC_FACTORY and ESP_EFUSE_MAC_FACTORY_CRC. efuse_table_gen.py tool @@ -87,11 +99,11 @@ The tool is designed to generate C-source files from CSV file and validate field To generate a `common` files, use the following command ``idf.py efuse_common_table`` or: :: - - cd $IDF_PATH/components/efuse/ - ./efuse_table_gen.py esp32/esp_efuse_table.csv -After generation in the folder `esp32` create: + cd $IDF_PATH/components/efuse/ + ./efuse_table_gen.py {IDF_TARGET_PATH_NAME}/esp_efuse_table.csv + +After generation in the folder `{IDF_TARGET_PATH_NAME}` create: * `esp_efuse_table.c` file. * In `include` folder `esp_efuse_table.c` file. @@ -101,7 +113,7 @@ To generate a `custom` files, use the following command ``idf.py efuse_custom_ta :: cd $IDF_PATH/components/efuse/ - ./efuse_table_gen.py esp32/esp_efuse_table.csv PROJECT_PATH/main/esp_efuse_custom_table.csv + ./efuse_table_gen.py {IDF_TARGET_PATH_NAME}/esp_efuse_table.csv PROJECT_PATH/main/esp_efuse_custom_table.csv After generation in the folder PROJECT_PATH/main create: @@ -124,7 +136,7 @@ eFuse have three coding schemes: * ``3/4`` (value 1). * ``Repeat`` (value 2). -The coding scheme affects only EFUSE_BLK1, EFUSE_BLK2 and EFUSE_BLK3 blocks. EUSE_BLK0 block always has a coding scheme ``None``. +The coding scheme affects only EFUSE_BLK1, EFUSE_BLK2 and EFUSE_BLK3 blocks. EUSE_BLK0 block always has a coding scheme ``None``. Coding changes the number of bits that can be written into a block, the block length is constant 256, some of these bits are used for encoding and are not used. When using a coding scheme, the length of the payload that can be written is limited (for more details ``20.3.1.3 System Parameter coding_scheme``): @@ -136,7 +148,7 @@ When using a coding scheme, the length of the payload that can be written is lim You can find out the coding scheme of your chip: * run a ``espefuse.py -p COM4 summary`` command. -* from ``esptool`` utility logs (during flashing). +* from ``esptool`` utility logs (during flashing). * calling the function in the code :cpp:func:`esp_efuse_get_coding_scheme` for the EFUSE_BLK3 block. eFuse tables must always comply with the coding scheme in the chip. There is an :envvar:`EFUSE_CODE_SCHEME_SELECTOR` option to select the coding type for tables in a Kconfig. When generating source files, if your tables do not follow the coding scheme, an error message will be displayed. Adjust the length or offset fields. @@ -181,7 +193,7 @@ How add a new field :: - $ ./efuse_table_gen.py esp32/esp_efuse_table.csv --info + $ ./efuse_table_gen.py {IDF_TARGET_PATH_NAME}/esp_efuse_table.csv --info eFuse coding scheme: NONE # field_name efuse_block bit_start bit_count 1 WR_DIS_FLASH_CRYPT_CNT EFUSE_BLK0 2 1 @@ -226,23 +238,23 @@ How add a new field 40 ADC2_TP_HIGH EFUSE_BLK3 119 9 41 SECURE_VERSION EFUSE_BLK3 128 32 42 MAC_CUSTOM_VER EFUSE_BLK3 184 8 - + Used bits in eFuse table: EFUSE_BLK0 [2 2] [7 9] [16 18] [20 27] [32 87] [96 97] [105 109] [111 111] [136 144] [188 191] [194 194] [196 196] [198 201] - + EFUSE_BLK1 [0 255] - + EFUSE_BLK2 [0 255] - + EFUSE_BLK3 [0 55] [96 159] [184 191] - + Note: Not printed ranges are free for using. (bits in EFUSE_BLK0 are reserved for Espressif) - - Parsing eFuse CSV input file $IDF_PATH/components/efuse/esp32/esp_efuse_table.csv ... + + Parsing eFuse CSV input file $IDF_PATH/components/efuse/{IDF_TARGET_PATH_NAME}/esp_efuse_table.csv ... Verifying eFuse table... @@ -263,12 +275,12 @@ The Kconfig option :envvar:`CONFIG_EFUSE_VIRTUAL` will virtualize eFuse values i espefuse.py ^^^^^^^^^^^ -esptool includes a useful tool for reading/writing ESP32 eFuse bits - `espefuse.py `_. +esptool includes a useful tool for reading/writing {IDF_TARGET_NAME} eFuse bits - `espefuse.py `_. :: espefuse.py -p COM4 summary - + espefuse.py v2.3.1 Connecting........_ Security fuses: @@ -287,13 +299,13 @@ esptool includes a useful tool for reading/writing ESP32 eFuse bits - `espefuse. = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 R/W BLK3 Variable Block 3 = 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 fa 87 02 91 00 00 00 00 00 00 00 00 00 00 00 00 R/W - + Efuse fuses: WR_DIS Efuse write disable mask = 0 R/W (0x0) RD_DIS Efuse read disablemask = 0 R/W (0x0) CODING_SCHEME Efuse variable block length scheme = 1 R/W (0x1) (3/4) KEY_STATUS Usage of efuse block 3 (reserved) = 0 R/W (0x0) - + Config fuses: XPD_SDIO_FORCE Ignore MTDI pin (GPIO12) for VDD_SDIO on reset = 0 R/W (0x0) XPD_SDIO_REG If XPD_SDIO_FORCE, enable VDD_SDIO reg on reset = 0 R/W (0x0) @@ -304,14 +316,14 @@ esptool includes a useful tool for reading/writing ESP32 eFuse bits - `espefuse. SPI_PAD_CONFIG_HD Override SD_DATA_2 pad (GPIO9/SPIHD) = 0 R/W (0x0) SPI_PAD_CONFIG_CS0 Override SD_CMD pad (GPIO11/SPICS0) = 0 R/W (0x0) DISABLE_SDIO_HOST Disable SDIO host = 0 R/W (0x0) - + Identity fuses: MAC MAC Address = 84:0d:8e:18:8e:44 (CRC ad OK) R/W CHIP_VER_REV1 Silicon Revision 1 = 1 R/W (0x1) CHIP_VERSION Reserved for future chip versions = 2 R/W (0x2) CHIP_PACKAGE Chip package identifier = 0 R/W (0x0) - + Calibration fuses: BLK3_PART_RESERVE BLOCK3 partially served for ADC calibration data = 1 R/W (0x1) ADC_VREF Voltage reference calibration = 1114 R/W (0x2) @@ -319,13 +331,13 @@ esptool includes a useful tool for reading/writing ESP32 eFuse bits - `espefuse. ADC1_TP_HIGH ADC1 850mV reading = 3285 R/W (0x5) ADC2_TP_LOW ADC2 150mV reading = 449 R/W (0x7) ADC2_TP_HIGH ADC2 850mV reading = 3362 R/W (0x1f5) - + Flash voltage (VDD_SDIO) determined by GPIO12 on reset (High for 1.8V, Low/NC for 3.3V). To get a dump for all eFuse registers. :: - + espefuse.py -p COM4 dump $ espefuse.py -p COM4 dump diff --git a/docs/en/api-reference/system/heap_debug.rst b/docs/en/api-reference/system/heap_debug.rst index d00f17e48..92f74be40 100644 --- a/docs/en/api-reference/system/heap_debug.rst +++ b/docs/en/api-reference/system/heap_debug.rst @@ -280,7 +280,7 @@ To gather and analyse heap trace do the following on the host: Using this file GDB will connect to the target, reset it, and start tracing when program hits breakpoint at :cpp:func:`heap_trace_start`. Trace data will be saved to ``/tmp/heap_log.svdat``. Tracing will be stopped when program hits breakpoint at :cpp:func:`heap_trace_stop`. -4. Run GDB using the following command ``xtensa-esp32-elf-gdb -x gdbinit `` +4. Run GDB using the following command ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -x gdbinit `` 5. Quit GDB when program stops at :cpp:func:`heap_trace_stop`. Trace data are saved in ``/tmp/heap.svdat`` diff --git a/docs/en/api-reference/system/index.rst b/docs/en/api-reference/system/index.rst index dab87a1278..d990ef60d 100644 --- a/docs/en/api-reference/system/index.rst +++ b/docs/en/api-reference/system/index.rst @@ -16,8 +16,8 @@ System API Heap Memory Allocation Heap Memory Debugging High Resolution Timer - Himem (large external SPI RAM) API - Inter-Processor Call + :esp32: Himem (large external SPI RAM) API + :esp32: Inter-Processor Call Call function with external stack Interrupt Allocation Logging diff --git a/docs/en/api-reference/system/intr_alloc.rst b/docs/en/api-reference/system/intr_alloc.rst index da1599243..9d200820c 100644 --- a/docs/en/api-reference/system/intr_alloc.rst +++ b/docs/en/api-reference/system/intr_alloc.rst @@ -4,9 +4,17 @@ Interrupt allocation Overview -------- -The ESP32 has two cores, with 32 interrupts each. Each interrupt has a certain priority level, most (but not all) interrupts are connected -to the interrupt mux. Because there are more interrupt sources than interrupts, sometimes it makes sense to share an interrupt in -multiple drivers. The esp_intr_alloc abstraction exists to hide all these implementation details. +.. only:: esp32 + + The {IDF_TARGET_NAME} has two cores, with 32 interrupts each. Each interrupt has a certain priority level, most (but not all) interrupts are connected + to the interrupt mux. Because there are more interrupt sources than interrupts, sometimes it makes sense to share an interrupt in + multiple drivers. The esp_intr_alloc abstraction exists to hide all these implementation details. + +.. only.. esp32s2 + + The {IDF_TARGET_NAME} has one cores, with 32 interrupts each. Each interrupt has a certain priority level, most (but not all) interrupts are connected + to the interrupt mux. Because there are more interrupt sources than interrupts, sometimes it makes sense to share an interrupt in + multiple drivers. The esp_intr_alloc abstraction exists to hide all these implementation details. A driver can allocate an interrupt for a certain peripheral by calling esp_intr_alloc (or esp_intr_alloc_sintrstatus). It can use the flags passed to this function to set the type of interrupt allocated, specifying a specific level or trigger method. The @@ -15,7 +23,7 @@ install the given interrupt handler and ISR to it. This code has two different types of interrupts it handles differently: Shared interrupts and non-shared interrupts. The simplest of the two are non-shared interrupts: a separate interrupt is allocated per esp_intr_alloc call and this interrupt is solely used for -the peripheral attached to it, with only one ISR that will get called. Shared interrupts can have multiple peripherals triggering +the peripheral attached to it, with only one ISR that will get called. Shared interrupts can have multiple peripherals triggering it, with multiple ISRs being called when one of the peripherals attached signals an interrupt. Thus, ISRs that are intended for shared interrupts should check the interrupt status of the peripheral they service in order to see if any action is required. @@ -24,7 +32,7 @@ only be level interrupts (because of the chance of missed interrupts when edge i used.) (The logic behind this: DevA and DevB share an int. DevB signals an int. Int line goes high. ISR handler calls code for DevA -> does nothing. ISR handler calls code for DevB, but while doing that, -DevA signals an int. ISR DevB is done, clears int for DevB, exits interrupt code. Now an +DevA signals an int. ISR DevB is done, clears int for DevB, exits interrupt code. Now an interrupt for DevA is still pending, but because the int line never went low (DevA kept it high even when the int for DevB was cleared) the interrupt is never serviced.) @@ -34,7 +42,7 @@ Multicore issues Peripherals that can generate interrupts can be divided in two types: - - External peripherals, within the ESP32 but outside the Xtensa cores themselves. Most ESP32 peripherals are of this type. + - External peripherals, within the {IDF_TARGET_NAME} but outside the Xtensa cores themselves. Most {IDF_TARGET_NAME} peripherals are of this type. - Internal peripherals, part of the Xtensa CPU cores themselves. Interrupt handling differs slightly between these two types of peripherals. @@ -89,7 +97,7 @@ Multiple Handlers Sharing A Source Several handlers can be assigned to a same source, given that all handlers are allocated using the ``ESP_INTR_FLAG_SHARED`` flag. They'll be all allocated to the interrupt, which the source is attached to, and called sequentially when the source is active. The handlers can be disabled and freed individually. The source is attached to the interrupt (enabled), if one or more handlers are enabled, otherwise detached. -A handler will never be called when disabled, while **its source may still be triggered** if any one of its handler enabled. +A handler will never be called when disabled, while **its source may still be triggered** if any one of its handler enabled. Sources attached to non-shared interrupt do not support this feature. diff --git a/docs/en/api-reference/system/mem_alloc.rst b/docs/en/api-reference/system/mem_alloc.rst index 65ab94043..44512aa2c 100644 --- a/docs/en/api-reference/system/mem_alloc.rst +++ b/docs/en/api-reference/system/mem_alloc.rst @@ -8,7 +8,7 @@ ESP-IDF applications use the common computer architecture patterns of *stack* (d Because ESP-IDF is a multi-threaded RTOS environment, each RTOS task has its own stack. By default, each of these stacks is allocated from the heap when the task is created. (See :cpp:func:`xTaskCreateStatic` for the alternative where stacks are statically allocated.) -Because ESP32 uses multiple types of RAM, it also contains multiple heaps with different capabilities. A capabilities-based memory allocator allows apps to make heap allocations for different purposes. +Because {IDF_TARGET_NAME} uses multiple types of RAM, it also contains multiple heaps with different capabilities. A capabilities-based memory allocator allows apps to make heap allocations for different purposes. For most purposes, the standard libc ``malloc()`` and ``free()`` functions can be used for heap allocation without any special consideration. @@ -18,7 +18,7 @@ capabilities-based heap memory allocator. If you want to have memory with certai Memory Capabilities ------------------- -The ESP32 contains multiple types of RAM: +The {IDF_TARGET_NAME} contains multiple types of RAM: - DRAM (Data RAM) is memory used to hold data. This is the most common kind of memory accessed as heap. - IRAM (Instruction RAM) usually holds executable data only. If accessed as generic memory, all accesses must be :ref:`32-bit aligned<32-Bit Accessible Memory>`. @@ -26,7 +26,7 @@ The ESP32 contains multiple types of RAM: For more details on these internal memory types, see :ref:`memory-layout`. -It's also possible to connect external SPI RAM to the ESP32 - :doc:`external RAM ` can be integrated into the ESP32's memory map using the flash cache, and accessed similarly to DRAM. +It's also possible to connect external SPI RAM to the {IDF_TARGET_NAME} - :doc:`external RAM ` can be integrated into the {IDF_TARGET_NAME}'s memory map using the flash cache, and accessed similarly to DRAM. DRAM uses capability ``MALLOC_CAP_8BIT`` (accessible in single byte reads and writes). When calling ``malloc()``, the ESP-IDF ``malloc()`` implementation internally calls ``heap_caps_malloc(size, MALLOC_CAP_8BIT)`` in order to allocate DRAM that is byte-addressable. To test the free DRAM heap size at runtime, call cpp:func:`heap_caps_get_free_size(MALLOC_CAP_8BIT)`. @@ -57,7 +57,7 @@ The :ref:`idf.py size ` command can be used to find the amount of I D/IRAM ^^^^^^ -Some memory in the ESP32 is available as either DRAM or IRAM. If memory is allocated from a D/IRAM region, the free heap size for both types of memory will decrease. +Some memory in the {IDF_TARGET_NAME} is available as either DRAM or IRAM. If memory is allocated from a D/IRAM region, the free heap size for both types of memory will decrease. Heap Sizes ^^^^^^^^^^ @@ -95,7 +95,7 @@ Use the ``MALLOC_CAP_DMA`` flag to allocate memory which is suitable for use wit If a certain memory structure is only addressed in 32-bit units, for example an array of ints or pointers, it can be useful to allocate it with the ``MALLOC_CAP_32BIT`` flag. This also allows the allocator to give out IRAM memory; something -which it can't do for a normal malloc() call. This can help to use all the available memory in the ESP32. +which it can't do for a normal malloc() call. This can help to use all the available memory in the {IDF_TARGET_NAME}. Memory allocated with ``MALLOC_CAP_32BIT`` can *only* be accessed via 32-bit reads and writes, any other type of access will generate a fatal LoadStoreError exception. @@ -105,7 +105,9 @@ External SPI Memory When :doc:`external RAM ` is enabled, external SPI RAM under 4MiB in size can be allocated using standard ``malloc`` calls, or via ``heap_caps_malloc(MALLOC_CAP_SPIRAM)``, depending on configuration. See :ref:`external_ram_config` for more details. -To use the region above the 4MiB limit, you can use the :doc:`himem API`. +..only:: esp32 + + To use the region above the 4MiB limit, you can use the :doc:`himem API`. API Reference - Heap Allocation diff --git a/docs/en/api-reference/system/ota.rst b/docs/en/api-reference/system/ota.rst index 941c68bb2..110c1dabe 100644 --- a/docs/en/api-reference/system/ota.rst +++ b/docs/en/api-reference/system/ota.rst @@ -139,7 +139,7 @@ This function works if set :ref:`CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK` option. In A typical anti-rollback scheme is ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- New firmware released with the elimination of vulnerabilities with the previous version of security. +- New firmware released with the elimination of vulnerabilities with the previous version of security. - After the developer makes sure that this firmware is working. He can increase the security version and release a new firmware. - Download new application. - To make it bootable, run the function :cpp:func:`esp_ota_set_boot_partition`. If the security version of the new application is smaller than the version in the chip, the new application will be erased. Update to new firmware is not possible. @@ -148,7 +148,7 @@ A typical anti-rollback scheme is - New application booted. Then the application should perform diagnostics of the operation and if it is completed successfully, you should call :cpp:func:`esp_ota_mark_app_valid_cancel_rollback` function to mark the running application with the ``ESP_OTA_IMG_VALID`` state and update the secure version on chip. Note that if was called :cpp:func:`esp_ota_mark_app_invalid_rollback_and_reboot` function a rollback may not happend due to the device may not have any bootable apps then it will return ``ESP_ERR_OTA_ROLLBACK_FAILED`` error and stay in the ``ESP_OTA_IMG_PENDING_VERIFY`` state. - The next update of app is possible if a running app is in the ``ESP_OTA_IMG_VALID`` state. -Recommendation: +Recommendation: If you want to avoid the download/erase overhead in case of the app from the server has security version lower then running app you have to get ``new_app_info.secure_version`` from the first package of an image and compare it with the secure version of efuse. Use ``esp_efuse_check_secure_version(new_app_info.secure_version)`` function if it is true then continue downloading otherwise abort. @@ -169,7 +169,7 @@ If you want to avoid the download/erase overhead in case of the app from the ser http_cleanup(client); task_fatal_error(); } - + image_header_was_checked = true; esp_ota_begin(update_partition, OTA_SIZE_UNKNOWN, &update_handle); @@ -189,7 +189,10 @@ Restrictions: ``security_version``: - In application image it is stored in ``esp_app_desc`` structure. The number is set :ref:`CONFIG_BOOTLOADER_APP_SECURE_VERSION`. -- In ESP32 it is stored in efuse ``EFUSE_BLK3_RDATA4_REG``. (when a eFuse bit is programmed to 1, it can never be reverted to 0). The number of bits set in this register is the ``security_version`` from app. + +.. only:: esp32 + + - In ESP32 it is stored in efuse ``EFUSE_BLK3_RDATA4_REG``. (when a eFuse bit is programmed to 1, it can never be reverted to 0). The number of bits set in this register is the ``security_version`` from app. .. _secure-ota-updates: @@ -267,13 +270,13 @@ The command-line interface of `otatool.py` has the following structure: otatool.py [command-args] [subcommand] [subcommand-args] - command-args - these are arguments that are needed for executing the main command (parttool.py), mostly pertaining to the target device - - subcommand - this is the operation to be performed + - subcommand - this is the operation to be performed - subcommand-args - these are arguments that are specific to the chosen operation .. code-block:: bash # Erase otadata, resetting the device to factory app - otatool.py --port "/dev/ttyUSB1" erase_otadata + otatool.py --port "/dev/ttyUSB1" erase_otadata # Erase contents of OTA app slot 0 otatool.py --port "/dev/ttyUSB1" erase_ota_partition --slot 0 diff --git a/docs/en/api-reference/system/perfmon.rst b/docs/en/api-reference/system/perfmon.rst index d13544611..70aa31b95 100644 --- a/docs/en/api-reference/system/perfmon.rst +++ b/docs/en/api-reference/system/perfmon.rst @@ -1,13 +1,13 @@ Performance Monitor =================== -The Performance Monitor component provides APIs to use ESP32 internal performance counters to profile functions and +The Performance Monitor component provides APIs to use {IDF_TARGET_NAME} internal performance counters to profile functions and applications. Application Example ------------------- -An example which combines performance monitor is provided in ``examples/system/perfmon`` directory. +An example which combines performance monitor is provided in ``examples/system/perfmon`` directory. This example initializes the performance monitor structure and execute them with printing the statistics. High level API Reference diff --git a/docs/en/api-reference/system/power_management.rst b/docs/en/api-reference/system/power_management.rst index 49acb39f8..b26602d52 100644 --- a/docs/en/api-reference/system/power_management.rst +++ b/docs/en/api-reference/system/power_management.rst @@ -31,13 +31,8 @@ Dynamic frequency scaling (DFS) and automatic light sleep can be enabled in an a - ``min_freq_mhz``: Minimum CPU frequency in MHz, i.e., the frequency used when only the ``ESP_PM_APB_FREQ_MAX`` lock is acquired. This field can be set to the XTAL frequency value, or the XTAL frequency divided by an integer. Note that 10 MHz is the lowest frequency at which the default REF_TICK clock of 1 MHz can be generated. - ``light_sleep_enable``: Whether the system should automatically enter light sleep when no locks are acquired (``true``/``false``). -.. only:: esp32 - Alternatively, if you enable the option :ref:`CONFIG_PM_DFS_INIT_AUTO` in menuconfig, the maximum CPU frequency will be determined by the :ref:`CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ` setting, and the minimum CPU frequency will be locked to the XTAL frequency. - -.. only:: esp32s2beta - - Alternatively, if you enable the option :ref:`CONFIG_PM_DFS_INIT_AUTO` in menuconfig, the maximum CPU frequency will be determined by the :ref:`CONFIG_ESP32S2_DEFAULT_CPU_FREQ_MHZ` setting, and the minimum CPU frequency will be locked to the XTAL frequency. + Alternatively, if you enable the option :ref:`CONFIG_PM_DFS_INIT_AUTO` in menuconfig, the maximum CPU frequency will be determined by the :ref:`CONFIG_{IDF_TARGET_CFG_PREFIX}_DEFAULT_CPU_FREQ_MHZ` setting, and the minimum CPU frequency will be locked to the XTAL frequency. .. note:: @@ -55,14 +50,14 @@ Applications have the ability to acquire/release locks in order to control the p Power management locks have acquire/release counters. If the lock has been acquired a number of times, it needs to be released the same number of times to remove associated restrictions. -ESP32 supports three types of locks described in the table below. +{IDF_TARGET_NAME} supports three types of locks described in the table below. ============================ ====================================================== Lock Description ============================ ====================================================== -``ESP_PM_CPU_FREQ_MAX`` Requests CPU frequency to be at the maximum value set with :cpp:func:`esp_pm_configure`. For ESP32, this value can be set to 80 MHz, 160 MHz, or 240 MHz. +``ESP_PM_CPU_FREQ_MAX`` Requests CPU frequency to be at the maximum value set with :cpp:func:`esp_pm_configure`. For {IDF_TARGET_NAME}, this value can be set to 80 MHz, 160 MHz, or 240 MHz. -``ESP_PM_APB_FREQ_MAX`` Requests the APB frequency to be at the maximum supported value. For ESP32, this is 80 MHz. +``ESP_PM_APB_FREQ_MAX`` Requests the APB frequency to be at the maximum supported value. For {IDF_TARGET_NAME}, this is 80 MHz. ``ESP_PM_NO_LIGHT_SLEEP`` Disables automatic switching to light sleep. ============================ ====================================================== diff --git a/docs/en/api-reference/system/sleep_modes.rst b/docs/en/api-reference/system/sleep_modes.rst index ab536aba2..74ee75821 100644 --- a/docs/en/api-reference/system/sleep_modes.rst +++ b/docs/en/api-reference/system/sleep_modes.rst @@ -4,13 +4,13 @@ Sleep Modes Overview -------- -ESP32 is capable of light sleep and deep sleep power saving modes. +{IDF_TARGET_NAME} is capable of light sleep and deep sleep power saving modes. In light sleep mode, digital peripherals, most of the RAM, and CPUs are clock-gated, and supply voltage is reduced. Upon exit from light sleep, peripherals and CPUs resume operation, their internal state is preserved. In deep sleep mode, CPUs, most of the RAM, and all the digital peripherals which are clocked from APB_CLK are powered off. The only parts of the chip which can still be powered on are: RTC controller, RTC peripherals (including ULP coprocessor), and RTC memories (slow and fast). -Wakeup from deep and light sleep modes can be done using several sources. These sources can be combined, in this case the chip will wake up when any one of the sources is triggered. Wakeup sources can be enabled using ``esp_sleep_enable_X_wakeup`` APIs and can be disabled using :cpp:func:`esp_sleep_disable_wakeup_source` API. Next section describes these APIs in detail. Wakeup sources can be configured at any moment before entering light or deep sleep mode. +Wakeup from deep and light sleep modes can be done using several sources. These sources can be combined, in this case the chip will wake up when any one of the sources is triggered. Wakeup sources can be enabled using ``esp_sleep_enable_X_wakeup`` APIs and can be disabled using :cpp:func:`esp_sleep_disable_wakeup_source` API. Next section describes these APIs in detail. Wakeup sources can be configured at any moment before entering light or deep sleep mode. Additionally, the application can force specific powerdown modes for the RTC peripherals and RTC memories using :cpp:func:`esp_sleep_pd_config` API. @@ -29,7 +29,7 @@ Wakeup sources Timer ^^^^^ -RTC controller has a built in timer which can be used to wake up the chip after a predefined amount of time. Time is specified at microsecond precision, but the actual resolution depends on the clock source selected for RTC SLOW_CLK. See chapter "Reset and Clock" of the ESP32 Technical Reference Manual for details about RTC clock options. +RTC controller has a built in timer which can be used to wake up the chip after a predefined amount of time. Time is specified at microsecond precision, but the actual resolution depends on the clock source selected for RTC SLOW_CLK. See chapter "Reset and Clock" of the {IDF_TARGET_NAME} Technical Reference Manual for details about RTC clock options. This wakeup mode doesn't require RTC peripherals or RTC memories to be powered on during sleep. @@ -40,7 +40,9 @@ Touch pad RTC IO module contains logic to trigger wakeup when a touch sensor interrupt occurs. You need to configure the touch pad interrupt before the chip starts deep sleep. -Revisions 0 and 1 of the ESP32 only support this wakeup mode when RTC peripherals are not forced to be powered on (i.e. ESP_PD_DOMAIN_RTC_PERIPH should be set to ESP_PD_OPTION_AUTO). +.. only:: esp32 + + Revisions 0 and 1 of the ESP32 only support this wakeup mode when RTC peripherals are not forced to be powered on (i.e. ESP_PD_DOMAIN_RTC_PERIPH should be set to ESP_PD_OPTION_AUTO). :cpp:func:`esp_sleep_enable_touchpad_wakeup` function can be used to enable this wakeup source. @@ -48,11 +50,13 @@ Revisions 0 and 1 of the ESP32 only support this wakeup mode when RTC peripheral External wakeup (ext0) ^^^^^^^^^^^^^^^^^^^^^^ -RTC IO module contains logic to trigger wakeup when one of RTC GPIOs is set to a predefined logic level. RTC IO is part of RTC peripherals power domain, so RTC peripherals will be kept powered on during deep sleep if this wakeup source is requested. +RTC IO module contains logic to trigger wakeup when one of RTC GPIOs is set to a predefined logic level. RTC IO is part of RTC peripherals power domain, so RTC peripherals will be kept powered on during deep sleep if this wakeup source is requested. Because RTC IO module is enabled in this mode, internal pullup or pulldown resistors can also be used. They need to be configured by the application using :cpp:func:`rtc_gpio_pullup_en` and :cpp:func:`rtc_gpio_pulldown_en` functions, before calling :cpp:func:`esp_sleep_start`. -In revisions 0 and 1 of the ESP32, this wakeup source is incompatible with ULP and touch wakeup sources. +.. only:: esp32 + + In revisions 0 and 1 of the ESP32, this wakeup source is incompatible with ULP and touch wakeup sources. :cpp:func:`esp_sleep_enable_ext0_wakeup` function can be used to enable this wakeup source. @@ -73,7 +77,7 @@ This wakeup source is implemented by the RTC controller. As such, RTC peripheral gpio_pulldown_en(gpio_num); .. warning:: After wake up from sleep, IO pad(s) used for wakeup will be configured as RTC IO. Before using these pads as digital GPIOs, reconfigure them using ``rtc_gpio_deinit(gpio_num)`` function. - + :cpp:func:`esp_sleep_enable_ext1_wakeup` function can be used to enable this wakeup source. ULP coprocessor wakeup @@ -81,7 +85,9 @@ ULP coprocessor wakeup ULP coprocessor can run while the chip is in sleep mode, and may be used to poll sensors, monitor ADC or touch sensor values, and wake up the chip when a specific event is detected. ULP coprocessor is part of RTC peripherals power domain, and it runs the program stored in RTC slow memory. RTC slow memory will be powered on during sleep if this wakeup mode is requested. RTC peripherals will be automatically powered on before ULP coprocessor starts running the program; once the program stops running, RTC peripherals are automatically powered down again. -Revisions 0 and 1 of the ESP32 only support this wakeup mode when RTC peripherals are not forced to be powered on (i.e. ESP_PD_DOMAIN_RTC_PERIPH should be set to ESP_PD_OPTION_AUTO). +.. only:: esp32 + + Revisions 0 and 1 of the ESP32 only support this wakeup mode when RTC peripherals are not forced to be powered on (i.e. ESP_PD_DOMAIN_RTC_PERIPH should be set to ESP_PD_OPTION_AUTO). :cpp:func:`esp_sleep_enable_ulp_wakeup` function can be used to enable this wakeup source. @@ -95,7 +101,7 @@ In addition to EXT0 and EXT1 wakeup sources described above, one more method of UART wakeup (light sleep only) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -When ESP32 receives UART input from external devices, it is often required to wake up the chip when input data is available. UART peripheral contains a feature which allows waking up the chip from light sleep when a certain number of positive edges on RX pin are seen. This number of positive edges can be set using :cpp:func:`uart_set_wakeup_threshold` function. Note that the character which triggers wakeup (and any characters before it) will not be received by the UART after wakeup. This means that the external device typically needs to send an extra character to the ESP32 to trigger wakeup, before sending the data. +When {IDF_TARGET_NAME} receives UART input from external devices, it is often required to wake up the chip when input data is available. UART peripheral contains a feature which allows waking up the chip from light sleep when a certain number of positive edges on RX pin are seen. This number of positive edges can be set using :cpp:func:`uart_set_wakeup_threshold` function. Note that the character which triggers wakeup (and any characters before it) will not be received by the UART after wakeup. This means that the external device typically needs to send an extra character to the {IDF_TARGET_NAME} to trigger wakeup, before sending the data. :cpp:func:`esp_sleep_enable_uart_wakeup` function can be used to enable this wakeup source. @@ -105,7 +111,9 @@ Power-down of RTC peripherals and memories By default, :cpp:func:`esp_deep_sleep_start` and :cpp:func:`esp_light_sleep_start` functions will power down all RTC power domains which are not needed by the enabled wakeup sources. To override this behaviour, :cpp:func:`esp_sleep_pd_config` function is provided. -Note: in revision 0 of the ESP32, RTC fast memory will always be kept enabled in deep sleep, so that the deep sleep stub can run after reset. This can be overridden, if the application doesn't need clean reset behaviour after deep sleep. +.. only:: esp32 + + Note: in revision 0 of the ESP32, RTC fast memory will always be kept enabled in deep sleep, so that the deep sleep stub can run after reset. This can be overridden, if the application doesn't need clean reset behaviour after deep sleep. If some variables in the program are placed into RTC slow memory (for example, using ``RTC_DATA_ATTR`` attribute), RTC slow memory will be kept powered on by default. This can be overridden using :cpp:func:`esp_sleep_pd_config` function, if desired. @@ -123,7 +131,7 @@ Entering deep sleep Configuring IOs --------------- -Some ESP32 IOs have internal pullups or pulldowns, which are enabled by default. If an external circuit drives this pin in deep sleep mode, current consumption may increase due to current flowing through these pullups and pulldowns. +Some {IDF_TARGET_NAME} IOs have internal pullups or pulldowns, which are enabled by default. If an external circuit drives this pin in deep sleep mode, current consumption may increase due to current flowing through these pullups and pulldowns. To isolate a pin, preventing extra current draw, call :cpp:func:`rtc_gpio_isolate` function. @@ -155,7 +163,7 @@ Previously configured wakeup source can be disabled later using :cpp:func:`esp_s Application Example ------------------- - + Implementation of basic functionality of deep sleep is shown in :example:`protocols/sntp` example, where ESP module is periodically waken up to retrieve time from NTP server. More extensive example in :example:`system/deep_sleep` illustrates usage of various deep sleep wakeup triggers and ULP coprocessor programming. diff --git a/docs/en/api-reference/system/system.rst b/docs/en/api-reference/system/system.rst index d0c8221cb..a34213ab5 100644 --- a/docs/en/api-reference/system/system.rst +++ b/docs/en/api-reference/system/system.rst @@ -26,7 +26,7 @@ Note that ESP-IDF supports multiple heaps with different capabilities. Functions Random number generation ------------------------ -ESP32 contains a hardware random number generator, values from it can be obtained using :cpp:func:`esp_random`. +{IDF_TARGET_NAME} contains a hardware random number generator, values from it can be obtained using :cpp:func:`esp_random`. When Wi-Fi or Bluetooth are enabled, numbers returned by hardware random number generator (RNG) can be considered true random numbers. Without Wi-Fi or Bluetooth enabled, hardware RNG is a pseudo-random number generator. At startup, ESP-IDF bootloader seeds the hardware RNG with entropy, but care must be taken when reading random values between the start of ``app_main`` and initialization of Wi-Fi or Bluetooth drivers. @@ -38,32 +38,32 @@ These APIs allow querying and customizing MAC addresses for different network in In ESP-IDF these addresses are calculated from *Base MAC address*. Base MAC address can be initialized with factory-programmed value from internal eFuse, or with a user-defined value. In addition to setting the base MAC address, applications can specify the way in which MAC addresses are allocated to devices. See `Number of universally administered MAC address`_ section for more details. -For ESP32: +.. only:: esp32 -+---------------+--------------------------------+----------------------------------+ -| Interface | MAC address | MAC address | -| | (4 universally administered) | (2 universally administered) | -+===============+================================+==================================+ -| Wi-Fi Station | base_mac | base_mac | -+---------------+--------------------------------+----------------------------------+ -| Wi-Fi SoftAP | base_mac, +1 to the last octet | base_mac, first octet randomized | -+---------------+--------------------------------+----------------------------------+ -| Bluetooth | base_mac, +2 to the last octet | base_mac, +1 to the last octet | -+---------------+--------------------------------+----------------------------------+ -| Ethernet | base_mac, +3 to the last octet | base_mac, +1 to the last octet, | -| | | first octet randomized | -+---------------+--------------------------------+----------------------------------+ + +---------------+--------------------------------+----------------------------------+ + | Interface | MAC address | MAC address | + | | (4 universally administered) | (2 universally administered) | + +===============+================================+==================================+ + | Wi-Fi Station | base_mac | base_mac | + +---------------+--------------------------------+----------------------------------+ + | Wi-Fi SoftAP | base_mac, +1 to the last octet | base_mac, first octet randomized | + +---------------+--------------------------------+----------------------------------+ + | Bluetooth | base_mac, +2 to the last octet | base_mac, +1 to the last octet | + +---------------+--------------------------------+----------------------------------+ + | Ethernet | base_mac, +3 to the last octet | base_mac, +1 to the last octet, | + | | | first octet randomized | + +---------------+--------------------------------+----------------------------------+ -For ESP32-S2: +.. only:: esp32s2 -+---------------+--------------------------------+----------------------------------+ -| Interface | MAC address | MAC address | -| | (2 universally administered) | (1 universally administered) | -+===============+================================+==================================+ -| Wi-Fi Station | base_mac | base_mac | -+---------------+--------------------------------+----------------------------------+ -| Wi-Fi SoftAP | base_mac, +1 to the last octet | base_mac, first octet randomized | -+---------------+--------------------------------+----------------------------------+ + +---------------+--------------------------------+----------------------------------+ + | Interface | MAC address | MAC address | + | | (2 universally administered) | (1 universally administered) | + +===============+================================+==================================+ + | Wi-Fi Station | base_mac | base_mac | + +---------------+--------------------------------+----------------------------------+ + | Wi-Fi SoftAP | base_mac, +1 to the last octet | base_mac, first octet randomized | + +---------------+--------------------------------+----------------------------------+ Base MAC address ^^^^^^^^^^^^^^^^ @@ -101,7 +101,7 @@ Number of universally administered MAC address Several MAC addresses (universally administered by IEEE) are uniquely assigned to the networking interfaces (Wi-Fi/BT/Ethernet). The final octet of each universally administered MAC address increases by one. Only the first one of them (which is called base MAC address) is stored in eFuse or external storage, the others are generated from it. Here, 'generate' means adding 0, 1, 2 and 3 (respectively) to the final octet of the base MAC address. -If the universally administered MAC addresses are not enough for all of the networking interfaces, locally administered MAC addresses which are derived from universally administered MAC addresses are assigned to the rest of networking interfaces. +If the universally administered MAC addresses are not enough for all of the networking interfaces, locally administered MAC addresses which are derived from universally administered MAC addresses are assigned to the rest of networking interfaces. See `this article `_ for the definition of local and universally administered MAC addresses. @@ -136,7 +136,7 @@ To get the version at build time, additional version macros are provided. They c * :c:macro:`ESP_IDF_VERSION_MAJOR`, :c:macro:`ESP_IDF_VERSION_MINOR`, :c:macro:`ESP_IDF_VERSION_PATCH` are defined to integers representing major, minor, and patch version. * :c:macro:`ESP_IDF_VERSION_VAL` and :c:macro:`ESP_IDF_VERSION` can be used when implementing version checks: - + .. code-block:: c #include "esp_idf_version.h" @@ -148,7 +148,7 @@ To get the version at build time, additional version macros are provided. They c App version ----------- -Application version is stored in :cpp:class:`esp_app_desc_t` structure. It is located in DROM sector and has a fixed offset from the beginning of the binary file. +Application version is stored in :cpp:class:`esp_app_desc_t` structure. It is located in DROM sector and has a fixed offset from the beginning of the binary file. The structure is located after :cpp:class:`esp_image_header_t` and :cpp:class:`esp_image_segment_header_t` structures. The field version has string type and max length 32 chars. To set version in your project manually you need to set ``PROJECT_VER`` variable in your project CMakeLists.txt/Makefile: diff --git a/docs/en/api-reference/system/wdts.rst b/docs/en/api-reference/system/wdts.rst index e185f7bac..55e858898 100644 --- a/docs/en/api-reference/system/wdts.rst +++ b/docs/en/api-reference/system/wdts.rst @@ -17,11 +17,11 @@ Interrupt watchdog The interrupt watchdog makes sure the FreeRTOS task switching interrupt isn't blocked for a long time. This is bad because no other tasks, including potentially important ones like the WiFi task and the idle task, -can't get any CPU runtime. A blocked task switching interrupt can happen because a program runs into an +can't get any CPU runtime. A blocked task switching interrupt can happen because a program runs into an infinite loop with interrupts disabled or hangs in an interrupt. The default action of the interrupt watchdog is to invoke the panic handler. causing a register dump and an opportunity -for the programmer to find out, using either OpenOCD or gdbstub, what bit of code is stuck with interrupts +for the programmer to find out, using either OpenOCD or gdbstub, what bit of code is stuck with interrupts disabled. Depending on the configuration of the panic handler, it can also blindly reset the CPU, which may be preferred in a production environment. @@ -32,54 +32,54 @@ it will hard-reset the SOC. Task Watchdog Timer ^^^^^^^^^^^^^^^^^^^ -The Task Watchdog Timer (TWDT) is responsible for detecting instances of tasks -running for a prolonged period of time without yielding. This is a symptom of +The Task Watchdog Timer (TWDT) is responsible for detecting instances of tasks +running for a prolonged period of time without yielding. This is a symptom of CPU starvation and is usually caused by a higher priority task looping without yielding to a lower-priority task thus starving the lower priority task from CPU time. This can be an indicator of poorly written code that spinloops on a -peripheral, or a task that is stuck in an infinite loop. +peripheral, or a task that is stuck in an infinite loop. -By default the TWDT will watch the Idle Tasks of each CPU, however any task can +By default the TWDT will watch the Idle Tasks of each CPU, however any task can elect to be watched by the TWDT. Each watched task must 'reset' the TWDT -periodically to indicate that they have been allocated CPU time. If a task does -not reset within the TWDT timeout period, a warning will be printed with -information about which tasks failed to reset the TWDT in time and which -tasks are currently running on the ESP32 CPUs. -And also there is a possibility to redefine the function `esp_task_wdt_isr_user_handler` +periodically to indicate that they have been allocated CPU time. If a task does +not reset within the TWDT timeout period, a warning will be printed with +information about which tasks failed to reset the TWDT in time and which +tasks are currently running on the {IDF_TARGET_NAME} CPUs. +And also there is a possibility to redefine the function `esp_task_wdt_isr_user_handler` in the user code to receive this event. The TWDT is built around the Hardware Watchdog Timer in Timer Group 0. The TWDT can be initialized by calling :cpp:func:`esp_task_wdt_init` which will configure -the hardware timer. A task can then subscribe to the TWDT using -:cpp:func:`esp_task_wdt_add` in order to be watched. Each subscribed task must -periodically call :cpp:func:`esp_task_wdt_reset` to reset the TWDT. Failure by +the hardware timer. A task can then subscribe to the TWDT using +:cpp:func:`esp_task_wdt_add` in order to be watched. Each subscribed task must +periodically call :cpp:func:`esp_task_wdt_reset` to reset the TWDT. Failure by any subscribed tasks to periodically call :cpp:func:`esp_task_wdt_reset` indicates that one or more tasks have been starved of CPU time or are stuck in a loop somewhere. -A watched task can be unsubscribed from the TWDT using -:cpp:func:`esp_task_wdt_delete()`. A task that has been unsubscribed should no +A watched task can be unsubscribed from the TWDT using +:cpp:func:`esp_task_wdt_delete()`. A task that has been unsubscribed should no longer call :cpp:func:`esp_task_wdt_reset`. Once all tasks have unsubscribed -form the TWDT, the TWDT can be deinitialized by calling +form the TWDT, the TWDT can be deinitialized by calling :cpp:func:`esp_task_wdt_deinit()`. By default :ref:`CONFIG_ESP_TASK_WDT` in :ref:`project-configuration-menu` be enabled causing the TWDT to be initialized automatically during startup. Likewise -:ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU0` and +:ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU0` and :ref:`CONFIG_ESP_TASK_WDT_CHECK_IDLE_TASK_CPU1` are also enabled by default causing the two Idle Tasks to be subscribed to the TWDT during startup. JTAG and watchdogs ^^^^^^^^^^^^^^^^^^ -While debugging using OpenOCD, the CPUs will be halted every time a breakpoint -is reached. However if the watchdog timers continue to run when a breakpoint is -encountered, they will eventually trigger a reset making it very difficult to -debug code. Therefore OpenOCD will disable the hardware timers of both the -interrupt and task watchdogs at every breakpoint. Moreover, OpenOCD will not +While debugging using OpenOCD, the CPUs will be halted every time a breakpoint +is reached. However if the watchdog timers continue to run when a breakpoint is +encountered, they will eventually trigger a reset making it very difficult to +debug code. Therefore OpenOCD will disable the hardware timers of both the +interrupt and task watchdogs at every breakpoint. Moreover, OpenOCD will not reenable them upon leaving the breakpoint. This means that interrupt watchdog -and task watchdog functionality will essentially be disabled. No warnings or -panics from either watchdogs will be generated when the ESP32 is connected to +and task watchdog functionality will essentially be disabled. No warnings or +panics from either watchdogs will be generated when the {IDF_TARGET_NAME} is connected to OpenOCD via JTAG. @@ -89,12 +89,12 @@ Interrupt Watchdog API Reference Header File ^^^^^^^^^^^ - * :component_file:`esp32/include/esp_int_wdt.h` + * :component_file:`{IDF_TARGET_PATH_NAME}/include/esp_int_wdt.h` Functions --------- - + .. doxygenfunction:: esp_int_wdt_init Task Watchdog API Reference diff --git a/docs/en/contribute/add-ons-reference.rst b/docs/en/contribute/add-ons-reference.rst index 30fedb8ed..d715c4170 100644 --- a/docs/en/contribute/add-ons-reference.rst +++ b/docs/en/contribute/add-ons-reference.rst @@ -119,7 +119,6 @@ Other Extensions :idf_file:`docs/idf_extensions/include_build_file.py` The ``include-build-file`` directive is like the built-in ``include-file`` directive, but file path is evaluated relative to ``build_dir``. - :idf_file:`docs/idf_extensions/kconfig_reference.py` Subscribes to ``idf-info`` event and uses confgen to generate ``kconfig.inc`` from the components included in the default project build. This file is then included into :doc:`/api-reference/kconfig`. @@ -147,6 +146,12 @@ Other Extensions :idf_file:`docs/idf_extensions/util.py` A collection of utility functions useful primarily when building documentation locally (see :ref:`setup-for-building-documentation`) to reduce the time to generate documentation on a second and subsequent builds. +:idf_file:`docs/idf_extensions/format_idf_target.py` + An extension for replacing generic target related names with the idf_target passed to the Sphinx command line. + This is a {\IDF_TARGET_NAME}, with /{\IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{\IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG{\IDF_TARGET_CFG_PREFIX}_MULTI_DOC` will, if the backspaces are removed, render as This is a {IDF_TARGET_NAME}, with /{IDF_TARGET_PATH_NAME}/soc.c, compiled with `xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gcc` with `CONFIG{IDF_TARGET_CFG_PREFIX}_MULTI_DOC`. + + This cannot be used inside tables. + Related Documents ----------------- diff --git a/docs/en/get-started/establish-serial-connection.rst b/docs/en/get-started/establish-serial-connection.rst index 2b1568264..903cdea1e 100644 --- a/docs/en/get-started/establish-serial-connection.rst +++ b/docs/en/get-started/establish-serial-connection.rst @@ -1,38 +1,39 @@ -Establish Serial Connection with ESP32 -============================================== +Establish Serial Connection with {IDF_TARGET_NAME} +================================================== :link_to_translation:`zh_CN:[中文]` -This section provides guidance how to establish serial connection between ESP32 and PC. +This section provides guidance how to establish serial connection between {IDF_TARGET_NAME} and PC. -Connect ESP32 to PC --------------------- +Connect {IDF_TARGET_NAME} to PC +------------------------------- -Connect the ESP32 board to the PC using the USB cable. If device driver does not install automatically, identify USB to serial converter chip on your ESP32 board (or external converter dongle), search for drivers in internet and install them. +Connect the {IDF_TARGET_NAME} board to the PC using the USB cable. If device driver does not install automatically, identify USB to serial converter chip on your {IDF_TARGET_NAME} board (or external converter dongle), search for drivers in internet and install them. -Below are the links to drivers for ESP32 boards produced by Espressif: +Below are the links to drivers for {IDF_TARGET_NAME} boards produced by Espressif: +.. only:: esp32 -.. csv-table:: - :header: Development Board, USB Driver, Remarks - :widths: 40, 20, 40 + .. csv-table:: + :header: Development Board, USB Driver, Remarks + :widths: 40, 20, 40 - :ref:`ESP32-DevKitC `, `CP210x`_ - `ESP32-LyraT `_, `CP210x`_ - `ESP32-LyraTD-MSC `_, `CP210x`_ - :ref:`ESP32-PICO-KIT `, `CP210x`_ - :ref:`ESP-WROVER-KIT `, `FTDI`_ - :ref:`ESP32 Demo Board `, `FTDI`_ - `ESP-Prog`_, `FTDI`_, Programmer board (w/o ESP32) - `ESP32-MeshKit-Sense `_, n/a, Use with `ESP-Prog`_ - `ESP32-Sense Kit `_, n/a, Use with `ESP-Prog`_ + :ref:`ESP32-DevKitC `, `CP210x`_ + `ESP32-LyraT `_, `CP210x`_ + `ESP32-LyraTD-MSC `_, `CP210x`_ + :ref:`ESP32-PICO-KIT `, `CP210x`_ + :ref:`ESP-WROVER-KIT `, `FTDI`_ + :ref:`ESP32 Demo Board `, `FTDI`_ + `ESP-Prog`_, `FTDI`_, Programmer board (w/o ESP32) + `ESP32-MeshKit-Sense `_, n/a, Use with `ESP-Prog`_ + `ESP32-Sense Kit `_, n/a, Use with `ESP-Prog`_ -.. _CP210x: https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers -.. _FTDI: http://www.ftdichip.com/Drivers/VCP.htm -.. _ESP-Prog: https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/ESP-Prog_guide_en.md#introduction-to-the-esp-prog-board + .. _CP210x: https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers + .. _FTDI: http://www.ftdichip.com/Drivers/VCP.htm + .. _ESP-Prog: https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/ESP-Prog_guide_en.md#introduction-to-the-esp-prog-board -* CP210x: `CP210x USB to UART Bridge VCP Drivers `_ +* CP210x: `CP210x USB to UART Bridge VCP Drivers `_ * FTDI: `FTDI Virtual COM Port Drivers `_ The drivers above are primarily for reference. Under normal circumstances, the drivers should be bundled with and operating system and automatically installed upon connecting one of the listed boards to the PC. @@ -41,7 +42,7 @@ The drivers above are primarily for reference. Under normal circumstances, the d Check port on Windows --------------------- -Check the list of identified COM ports in the Windows Device Manager. Disconnect ESP32 and connect it back, to verify which port disappears from the list and then shows back again. +Check the list of identified COM ports in the Windows Device Manager. Disconnect {IDF_TARGET_NAME} and connect it back, to verify which port disappears from the list and then shows back again. Figures below show serial port for ESP32 DevKitC and ESP32 WROVER KIT @@ -63,7 +64,7 @@ Figures below show serial port for ESP32 DevKitC and ESP32 WROVER KIT Check port on Linux and MacOS ----------------------------- -To check the device name for the serial port of your ESP32 board (or external converter dongle), run this command two times, first with the board / dongle unplugged, then with plugged in. The port which appears the second time is the one you need: +To check the device name for the serial port of your {IDF_TARGET_NAME} board (or external converter dongle), run this command two times, first with the board / dongle unplugged, then with plugged in. The port which appears the second time is the one you need: Linux :: @@ -91,7 +92,7 @@ on Arch Linux this is done by adding the user to ``uucp`` group with the followi sudo usermod -a -G uucp $USER -Make sure you re-login to enable read and write permissions for the serial port. +Make sure you re-login to enable read and write permissions for the serial port. Verify serial connection @@ -116,7 +117,7 @@ Run terminal, set identified serial port, baud rate = 115200, data bits = 8, sto Setting Serial Communication in PuTTY on Linux -Then open serial port in terminal and check, if you see any log printed out by ESP32. The log contents will depend on application loaded to ESP32. An example log by ESP32 is shown below. +Then open serial port in terminal and check, if you see any log printed out by {IDF_TARGET_NAME}. The log contents will depend on application loaded to {IDF_TARGET_NAME}. An example log by {IDF_TARGET_NAME} is shown below. .. highlight:: none @@ -141,16 +142,16 @@ Then open serial port in terminal and check, if you see any log printed out by E ... -If you can see readable log output, it means serial connection is working and you are ready to proceed with installation and finally upload of application to ESP32. +If you can see readable log output, it means serial connection is working and you are ready to proceed with installation and finally upload of application to {IDF_TARGET_NAME}. .. note:: - For some serial port wiring configurations, the serial RTS & DTR pins need to be disabled in the terminal program before the ESP32 will boot and produce serial output. This depends on the hardware itself, most development boards (including all Espressif boards) *do not* have this issue. The issue is present if RTS & DTR are wired directly to the EN & GPIO0 pins. See the `esptool documentation`_ for more details. + For some serial port wiring configurations, the serial RTS & DTR pins need to be disabled in the terminal program before the {IDF_TARGET_NAME} will boot and produce serial output. This depends on the hardware itself, most development boards (including all Espressif boards) *do not* have this issue. The issue is present if RTS & DTR are wired directly to the EN & GPIO0 pins. See the `esptool documentation`_ for more details. .. note:: - Close serial terminal after verification that communication is working. In the next step we are going to use a different application to upload a new firmware to ESP32. This application will not be able to access serial port while it is open in terminal. + Close serial terminal after verification that communication is working. In the next step we are going to use a different application to upload a new firmware to {IDF_TARGET_NAME}. This application will not be able to access serial port while it is open in terminal. -If you got here from :ref:`get-started-connect` when installing s/w for ESP32 development, then you can continue with :ref:`get-started-configure`. +If you got here from :ref:`get-started-connect` when installing s/w for {IDF_TARGET_NAME} development, then you can continue with :ref:`get-started-configure`. .. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst index 23f04922a..6adb9dc4c 100644 --- a/docs/en/get-started/index.rst +++ b/docs/en/get-started/index.rst @@ -4,64 +4,76 @@ Get Started :link_to_translation:`zh_CN:[中文]` -This document is intended to help you set up the software development environment for the hardware based on the ESP32 chip by Espressif. +This document is intended to help you set up the software development environment for the hardware based on the {IDF_TARGET_NAME} chip by Espressif. -After that, a simple example will show you how to use ESP-IDF (Espressif IoT Development Framework) for menu configuration, then building, and flashing firmware onto an ESP32 board. +After that, a simple example will show you how to use ESP-IDF (Espressif IoT Development Framework) for menu configuration, then building, and flashing firmware onto an {IDF_TARGET_NAME} board. .. include-build-file:: inc/version-note.inc Introduction ============ -ESP32 is a system on a chip that integrates the following features: +..only:: esp32 -* Wi-Fi (2.4 GHz band) -* Bluetooth 4.2 -* Dual high performance cores -* Ultra Low Power co-processor -* Several peripherals + {IDF_TARGET_NAME} is a system on a chip that integrates the following features: -Powered by 40 nm technology, ESP32 provides a robust, highly integrated platform, which helps meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability. + * Wi-Fi (2.4 GHz band) + * Bluetooth 4.2 + * Dual high performance cores + * Ultra Low Power co-processor + * Several peripherals -Espressif provides basic hardware and software resources to help application developers realize their ideas using the ESP32 series hardware. The software development framework by Espressif is intended for development of Internet-of-Things (IoT) applications with Wi-Fi, Bluetooth, power management and several other system features. +.. only:: esp32s2 + + {IDF_TARGET_NAME} is a system on a chip that integrates the following features: + + * Wi-Fi (2.4 GHz band) + * Ultra Low Power co-processor + * Several peripherals + +Powered by 40 nm technology, {IDF_TARGET_NAME} provides a robust, highly integrated platform, which helps meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability. + +Espressif provides basic hardware and software resources to help application developers realize their ideas using the {IDF_TARGET_NAME} series hardware. The software development framework by Espressif is intended for development of Internet-of-Things (IoT) applications with Wi-Fi, Bluetooth, power management and several other system features. What You Need ============= Hardware: -* An **ESP32** board +* An **{IDF_TARGET_NAME}** board * **USB cable** - USB A / micro USB B * **Computer** running Windows, Linux, or macOS Software: -* **Toolchain** to compile code for ESP32 -* **Build tools** - CMake and Ninja to build a full **Application** for ESP32 -* **ESP-IDF** that essentially contains API (software libraries and source code) for ESP32 and scripts to operate the **Toolchain** +* **Toolchain** to compile code for {IDF_TARGET_NAME} +* **Build tools** - CMake and Ninja to build a full **Application** for {IDF_TARGET_NAME} +* **ESP-IDF** that essentially contains API (software libraries and source code) for {IDF_TARGET_NAME} and scripts to operate the **Toolchain** * **Text editor** to write programs (**Projects**) in C, e.g., `Eclipse `_ .. figure:: ../../_static/what-you-need.png :align: center - :alt: Development of applications for ESP32 + :alt: Development of applications for {IDF_TARGET_NAME} :figclass: align-center - Development of applications for ESP32 + Development of applications for {IDF_TARGET_NAME} Development Board Overviews =========================== -If you have one of ESP32 development boards listed below, you can click on the link to learn more about its hardware. +If you have one of {IDF_TARGET_NAME} development boards listed below, you can click on the link to learn more about its hardware. -.. toctree:: - :maxdepth: 1 +.. only:: esp32 - ESP32-DevKitC <../hw-reference/get-started-devkitc> - ESP-WROVER-KIT <../hw-reference/get-started-wrover-kit> - ESP32-PICO-KIT <../hw-reference/get-started-pico-kit> - ESP32-Ethernet-Kit <../hw-reference/get-started-ethernet-kit> + .. toctree:: + :maxdepth: 1 + + ESP32-DevKitC <../hw-reference/get-started-devkitc> + ESP-WROVER-KIT <../hw-reference/get-started-wrover-kit> + ESP32-PICO-KIT <../hw-reference/get-started-pico-kit> + ESP32-Ethernet-Kit <../hw-reference/get-started-ethernet-kit> .. _get-started-step-by-step: @@ -128,7 +140,7 @@ Some tools need to be installed on the computer before proceeding to the next st Step 2. Get ESP-IDF =================== -To build applications for the ESP32, you need the software libraries provided by Espressif in `ESP-IDF repository `_. +To build applications for the {IDF_TARGET_NAME}, you need the software libraries provided by Espressif in `ESP-IDF repository `_. To get ESP-IDF, navigate to your installation directory and clone the repository with ``git clone``, following instructions below specific to your operating system. @@ -239,7 +251,7 @@ You can also automate this step, making ESP-IDF tools available in every termina Step 5. Start a Project ======================= -Now you are ready to prepare your application for ESP32. You can start with :example:`get-started/hello_world` project from :idf:`examples` directory in IDF. +Now you are ready to prepare your application for {IDF_TARGET_NAME}. You can start with :example:`get-started/hello_world` project from :idf:`examples` directory in IDF. Copy :example:`get-started/hello_world` to ``~/esp`` directory: @@ -272,9 +284,9 @@ It is also possible to build examples in-place, without copying them first. Step 6. Connect Your Device =========================== -Now connect your ESP32 board to the computer and check under what serial port the board is visible. +Now connect your {IDF_TARGET_NAME} board to the computer and check under what serial port the board is visible. -Serial ports have the following patterns in their names: +Serial ports have the following patterns in their names: - **Windows**: names like ``COM1`` - **Linux**: starting with ``/dev/tty`` @@ -336,9 +348,11 @@ To navigate and use ``menuconfig``, press the following keys: * ``?`` while highlighting a configuration item to display help about that item * ``/`` to find configuration items -.. attention:: +.. only:: esp32 - If you use ESP32-DevKitC board with the **ESP32-SOLO-1** module, enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing examples. + .. attention:: + + If you use ESP32-DevKitC board with the **ESP32-SOLO-1** module, enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing examples. .. _get-started-build: @@ -361,12 +375,12 @@ This command will compile the application and all ESP-IDF components, then it wi -- Building empty aws_iot component due to configuration -- Component names: ... -- Component paths: ... - + ... (more lines of build system output) - + [527/527] Generating hello-world.bin esptool.py v2.3.1 - + Project build complete. To flash, run this command: ../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin or run 'idf.py -p PORT flash' @@ -379,17 +393,17 @@ If there are no errors, the build will finish by generating the firmware binary Step 9. Flash onto the Device ============================= -Flash the binaries that you just built onto your ESP32 board by running:: +Flash the binaries that you just built onto your {IDF_TARGET_NAME} board by running:: idf.py -p PORT [-b BAUD] flash -Replace PORT with your ESP32 board's serial port name from :ref:`get-started-connect`. +Replace PORT with your {IDF_TARGET_NAME} board's serial port name from :ref:`get-started-connect`. You can also change the flasher baud rate by replacing BAUD with the baud rate you need. The default baud rate is ``460800``. For more information on idf.py arguments, see :ref:`idf.py`. -.. note:: +.. note:: The option ``flash`` automatically builds and flashes the project, so running ``idf.py build`` is not necessary. @@ -400,8 +414,8 @@ For more information on idf.py arguments, see :ref:`idf.py`. esptool.py -b 460800 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x1000 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello-world.bin esptool.py v2.3.1 Connecting.... - Detecting chip type... ESP32 - Chip is ESP32D0WDQ6 (revision 1) + Detecting chip type... {IDF_TARGET_NAME} + Chip is {IDF_TARGET_NAME}D0WDQ6 (revision 1) Features: WiFi, BT, Dual Core Uploading stub... Running stub... @@ -420,7 +434,7 @@ For more information on idf.py arguments, see :ref:`idf.py`. Compressed 136672 bytes to 67544... Wrote 136672 bytes (67544 compressed) at 0x00010000 in 1.9 seconds (effective 567.5 kbit/s)... Hash of data verified. - + Leaving... Hard resetting via RTS pin... @@ -471,9 +485,9 @@ To exit IDF monitor use the shortcut ``Ctrl+]``. :align: center :alt: Garbled output :figclass: align-center - + If you have such a problem, do the following: - + 1. Exit the monitor. 2. Go back to :ref:`menuconfig `. 3. Go to Component config --> ESP32-specific --> Main XTAL frequency, then change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz. diff --git a/docs/en/get-started/linux-setup-scratch.rst b/docs/en/get-started/linux-setup-scratch.rst index 361b54499..cd684a645 100644 --- a/docs/en/get-started/linux-setup-scratch.rst +++ b/docs/en/get-started/linux-setup-scratch.rst @@ -66,22 +66,22 @@ Download ``crosstool-NG`` and build it: Build the toolchain:: - ./ct-ng xtensa-esp32-elf + ./ct-ng xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf ./ct-ng build - chmod -R u+w builds/xtensa-esp32-elf + chmod -R u+w builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf -Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. +Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf``. Add Toolchain to PATH ===================== The custom toolchain needs to be copied to a binary directory and added to the ``PATH``. -Choose a directory, for example ``~/esp/xtensa-esp32-elf/``, and copy the build output to this directory. +Choose a directory, for example ``~/esp/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf/``, and copy the build output to this directory. -To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file:: +To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file:: - export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH" + export PATH="$HOME/esp/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf/bin:$PATH" .. note:: @@ -94,7 +94,7 @@ Log off and log in back to make the ``.profile`` changes effective. Run the foll You are looking for similar result containing toolchain's path at the beginning of displayed string:: $ printenv PATH - /home/user-name/esp/xtensa-esp32-elf/bin:/home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin + /home/user-name/esp/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf/bin:/home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin Instead of ``/home/user-name`` there should be a home path specific to your installation. diff --git a/docs/en/get-started/linux-setup.rst b/docs/en/get-started/linux-setup.rst index e647b7976..b54a4820c 100644 --- a/docs/en/get-started/linux-setup.rst +++ b/docs/en/get-started/linux-setup.rst @@ -30,7 +30,7 @@ Additional Tips Permission issues /dev/ttyUSB0 ------------------------------ -With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the ESP32. :ref:`This can be solved by adding the current user to the dialout group`. +With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the {IDF_TARGET_NAME}. :ref:`This can be solved by adding the current user to the dialout group`. Next Steps ========== diff --git a/docs/en/get-started/macos-setup-scratch.rst b/docs/en/get-started/macos-setup-scratch.rst index e46ea346b..e906b9fe7 100644 --- a/docs/en/get-started/macos-setup-scratch.rst +++ b/docs/en/get-started/macos-setup-scratch.rst @@ -73,11 +73,11 @@ Download ``crosstool-NG`` and build it: Build the toolchain:: - ./ct-ng xtensa-esp32-elf + ./ct-ng xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf ./ct-ng build - chmod -R u+w builds/xtensa-esp32-elf + chmod -R u+w builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf -Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``. To use it, you need to add ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf/bin`` to ``PATH`` environment variable. +Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf``. To use it, you need to add ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf/bin`` to ``PATH`` environment variable. Next Steps diff --git a/docs/en/get-started/windows-setup-scratch.rst b/docs/en/get-started/windows-setup-scratch.rst index 3ff02717c..fb542877f 100644 --- a/docs/en/get-started/windows-setup-scratch.rst +++ b/docs/en/get-started/windows-setup-scratch.rst @@ -81,12 +81,12 @@ Download the precompiled Windows toolchain: |download_link_win32| -Unzip the zip file to ``C:\Program Files`` (or some other location). The zip file contains a single directory ``xtensa-esp32-elf``. +Unzip the zip file to ``C:\Program Files`` (or some other location). The zip file contains a single directory ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf``. -Next, the ``bin`` subdirectory of this directory must be :ref:`added to your Path `. For example, the directory to add may be ``C:\Program Files\xtensa-esp32-elf\bin``. +Next, the ``bin`` subdirectory of this directory must be :ref:`added to your Path `. For example, the directory to add may be ``C:\Program Files\xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf\bin``. .. note:: - If you already have the MSYS2 environment (for use with the "GNU Make" build system) installed, you can skip the separate download and add the directory ``C:\msys32\opt\xtensa-esp32-elf\bin`` to the Path instead, as the toolchain is included in the MSYS2 environment. + If you already have the MSYS2 environment (for use with the "GNU Make" build system) installed, you can skip the separate download and add the directory ``C:\msys32\opt\xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf\bin`` to the Path instead, as the toolchain is included in the MSYS2 environment. .. _add-directory-windows-path: diff --git a/docs/en/hw-reference/index.rst b/docs/en/hw-reference/index.rst index acbd376d4..2cf714b69 100644 --- a/docs/en/hw-reference/index.rst +++ b/docs/en/hw-reference/index.rst @@ -1,16 +1,30 @@ -************************ -ESP32 Hardware Reference -************************ +************************************ +{IDF_TARGET_NAME} Hardware Reference +************************************ :link_to_translation:`zh_CN:[中文]` -.. toctree:: - :maxdepth: 3 +.. only:: esp32 - Technical Reference Manual (PDF) - Datasheet (PDF) - Hardware Design Guidelines (PDF) - Silicon Errata (PDF) - Modules and Boards - Previous Versions of Modules and Boards - Espressif Products Ordering Information (PDF) - Regulatory Certificates \ No newline at end of file + .. toctree:: + :maxdepth: 3 + + Technical Reference Manual (PDF) + Datasheet (PDF) + Hardware Design Guidelines (PDF) + Silicon Errata (PDF) + Modules and Boards + Previous Versions of Modules and Boards + Espressif Products Ordering Information (PDF) + Regulatory Certificates + +.. only:: esp32s2beta + + .. toctree:: + :maxdepth: 3 + + Technical Reference Manual (PDF) + Datasheet (PDF) + Modules and Boards + Previous Versions of Modules and Boards + Espressif Products Ordering Information (PDF) + Regulatory Certificates \ No newline at end of file diff --git a/docs/en/libraries-and-frameworks/cloud-frameworks.rst b/docs/en/libraries-and-frameworks/cloud-frameworks.rst index d58cf0058..407d94580 100644 --- a/docs/en/libraries-and-frameworks/cloud-frameworks.rst +++ b/docs/en/libraries-and-frameworks/cloud-frameworks.rst @@ -1,21 +1,21 @@ Cloud Frameworks ================ -ESP32 supports multiple cloud frameworks using agents built on top of ESP-IDF. Here are the pointers to various supported cloud frameworks' agents and examples: +{IDF_TARGET_NAME} supports multiple cloud frameworks using agents built on top of ESP-IDF. Here are the pointers to various supported cloud frameworks' agents and examples: AWS IoT ------- -`https://github.com/espressif/esp-aws-iot `_ is an open source repository for ESP32 based on Amazon Web Services' `aws-iot-device-sdk-embedded-C `_. +`https://github.com/espressif/esp-aws-iot `_ is an open source repository for {IDF_TARGET_NAME} based on Amazon Web Services' `aws-iot-device-sdk-embedded-C `_. Azure IoT --------- -`https://github.com/espressif/esp-azure `_ is an open source repository for ESP32 based on Microsoft Azure's `azure-iot-sdk-c SDK `_. +`https://github.com/espressif/esp-azure `_ is an open source repository for {IDF_TARGET_NAME} based on Microsoft Azure's `azure-iot-sdk-c SDK `_. -Google IoT Core +Google IoT Core --------------- -`https://github.com/espressif/esp-google-iot `_ is an open source repository for ESP32 based on Google's `iot-device-sdk-embedded-c SDK `_. +`https://github.com/espressif/esp-google-iot `_ is an open source repository for {IDF_TARGET_NAME} based on Google's `iot-device-sdk-embedded-c SDK `_. diff --git a/docs/en/security/flash-encryption.rst b/docs/en/security/flash-encryption.rst index 47749e03a..f35ffbd70 100644 --- a/docs/en/security/flash-encryption.rst +++ b/docs/en/security/flash-encryption.rst @@ -4,14 +4,23 @@ Flash Encryption :link_to_translation:`zh_CN:[中文]` -This document provides introduction to Flash encryption concept on ESP32 and demonstrates how this feature can be used during development as well as production by the user using a sample example. The primary intention of the document is to act as a quick start guide to test and verify flash encryption operations. The details of the flash encryption block can be found in the `ESP32 Technical reference manual`_. +.. only:: esp32 + + This document provides introduction to Flash encryption concept on {IDF_TARGET_NAME} and demonstrates how this feature can be used during development as well as production by the user using a sample example. The primary intention of the document is to act as a quick start guide to test and verify flash encryption operations. The details of the flash encryption block can be found in the `ESP32 Technical reference manual`_. + + .. _ESP32 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf + +.. only:: esp32s2beta + + This document provides introduction to Flash encryption concept on {IDF_TARGET_NAME} and demonstrates how this feature can be used during development as well as production by the user using a sample example. The primary intention of the document is to act as a quick start guide to test and verify flash encryption operations. The details of the flash encryption block can be found in the `ESP32-S2 Technical reference manual`_. + + .. _ESP32-S2 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32s2_technical_reference_manual_en.pdf -.. _ESP32 Technical Reference Manual: https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf Introduction ------------ -Flash encryption is a feature for encrypting the contents of the ESP32's attached SPI flash. When flash encryption is enabled, physical readout of the SPI flash is not sufficient to recover most flash contents. Encryption is applied by flashing the ESP32 with plaintext data, and (if encryption is enabled) the bootloader encrypts the data in place on first boot. +Flash encryption is a feature for encrypting the contents of the {IDF_TARGET_NAME}'s attached SPI flash. When flash encryption is enabled, physical readout of the SPI flash is not sufficient to recover most flash contents. Encryption is applied by flashing the {IDF_TARGET_NAME} with plaintext data, and (if encryption is enabled) the bootloader encrypts the data in place on first boot. With flash encryption enabled, following kinds of flash data are encrypted by default: @@ -30,13 +39,13 @@ Flash encryption is separate from the :doc:`Secure Boot ` feature, For production use, flash encryption should be enabled in the "Release" mode only. .. important:: - Enabling flash encryption limits the options for further updates of the ESP32. Make sure to read this document (including :ref:`flash-encryption-limitations`) and understand the implications of enabling flash encryption. + Enabling flash encryption limits the options for further updates of the {IDF_TARGET_NAME}. Make sure to read this document (including :ref:`flash-encryption-limitations`) and understand the implications of enabling flash encryption. .. _flash-encryption-efuse: eFuse Used During Flash Encryption Process ------------------------------------------- -The flash encryption operation is controlled by various eFuses available on ESP32. Below is the list of eFuse and their description: +The flash encryption operation is controlled by various eFuses available on {IDF_TARGET_NAME}. Below is the list of eFuse and their description: :: @@ -79,7 +88,7 @@ The flash encryption operation is controlled by various eFuses available on ESP3 not encrypt flash at boot time -Read and write access to above bits is controlled by appropriate bits in ``efuse_wr_disable`` and ``efuse_rd_disable`` registers. More information about ESP32 eFuse can be found at :doc:`eFuse manager <../api-reference/system/efuse>`. +Read and write access to above bits is controlled by appropriate bits in ``efuse_wr_disable`` and ``efuse_rd_disable`` registers. More information about {IDF_TARGET_NAME} eFuse can be found at :doc:`eFuse manager <../api-reference/system/efuse>`. Flash Encryption Process @@ -96,7 +105,7 @@ Assuming the eFuse values are in default state and second stage bootloader is co - For :ref:`flash_enc_development_mode` second stage bootloader will program only ``download_dis_decrypt`` & ``download_dis_cache`` eFuse bits to allow UART bootloader reflashing of encrypted binaries. Also ``FLASH_CRYPT_CNT`` eFuse bits will NOT be write protected. - The second stage bootloader then reboots the device to start executing encrypted image. It will transparently decrypt the flash contents and load into IRAM. -During development stage there is a frequent need to program different plaintext flash images and test the flash encryption process. This requires UART download mode to be able to load new plaintext images as many number of times as required. However during manufacturing or production UART download mode should not be allowed to access flash contents due to security reason. Hence this requires two different ESP32 configurations: one for development and other for production. Following section describes :ref:`flash_enc_development_mode` and :ref:`flash_enc_release_mode` for flash encryption and a step by step process to use them. +During development stage there is a frequent need to program different plaintext flash images and test the flash encryption process. This requires UART download mode to be able to load new plaintext images as many number of times as required. However during manufacturing or production UART download mode should not be allowed to access flash contents due to security reason. Hence this requires two different {IDF_TARGET_NAME} configurations: one for development and other for production. Following section describes :ref:`flash_enc_development_mode` and :ref:`flash_enc_release_mode` for flash encryption and a step by step process to use them. .. important:: Development mode as the name suggests should be used ONLY DURING DEVELOPMENT as it does not prevent modification and possible read back of encrypted flash contents. @@ -110,16 +119,16 @@ Steps to Setup Flash Encryption Development Mode ^^^^^^^^^^^^^^^^ -It is possible to run flash encryption process for development using either ESP32 internally generated key or external host generated keys. +It is possible to run flash encryption process for development using either {IDF_TARGET_NAME} internally generated key or external host generated keys. -Using ESP32 Generated Flash Encryption Key -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Using {IDF_TARGET_NAME} Generated Flash Encryption Key +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ As mentioned above :ref:`flash_enc_development_mode` allows user to download as many plaintext images using UART download mode. Following steps needs to be done to test flash encryption process: -- Ensure you have a ESP32 device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`. +- Ensure you have a {IDF_TARGET_NAME} device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`. -- Navigate to flash encryption sample application in ``$IDF_PATH/examples/security/flash_encryption`` folder. This sample application will print the status of flash encryption: enabled or disabled. It will print the ``FLASH_CRYPT_CNT`` eFuse value. +- Navigate to flash encryption sample application in ``$IDF_PATH/examples/security/flash_encryption`` folder. This sample application will print the status of flash encryption: enabled or disabled. It will print the ``FLASH_CRYPT_CNT`` eFuse value. - Enable flash encryption support in second stage bootloader. In :ref:`project-configuration-menu`, navigate to "Security Features". @@ -130,7 +139,7 @@ As mentioned above :ref:`flash_enc_development_mode` allows user to download as - Select appropriate Bootloader log verbosity under Bootloader config. - Update to the partition table offset may be required since after enabling flash encryption the size of bootloader is increased. See :ref:`secure-boot-bootloader-size` - + - Save the configuration and exit. Build and flash the complete image including: bootloader, partition table and app. These partitions are initially written to the flash unencrypted. @@ -139,7 +148,7 @@ Build and flash the complete image including: bootloader, partition table and ap idf.py flash monitor -Once the flashing is complete device will reset and on next boot second stage bootloader will encrypt the flash app partition and then reset. Now the sample application would get decrypted at runtime and executed. Below is a sample output when ESP32 boots after flash encryption is enabled for the first time. +Once the flashing is complete device will reset and on next boot second stage bootloader will encrypt the flash app partition and then reset. Now the sample application would get decrypted at runtime and executed. Below is a sample output when {IDF_TARGET_NAME} boots after flash encryption is enabled for the first time. :: @@ -190,20 +199,20 @@ Once the flashing is complete device will reset and on next boot second stage bo I (201) flash_encrypt: Disable UART bootloader MMU cache... I (208) flash_encrypt: Disable JTAG... I (212) flash_encrypt: Disable ROM BASIC interpreter fallback... - I (219) esp_image: segment 0: paddr=0x00001020 vaddr=0x3fff0018 size=0x00004 ( 4) - I (227) esp_image: segment 1: paddr=0x0000102c vaddr=0x3fff001c size=0x02104 ( 8452) - I (239) esp_image: segment 2: paddr=0x00003138 vaddr=0x40078000 size=0x03528 ( 13608) - I (249) esp_image: segment 3: paddr=0x00006668 vaddr=0x40080400 size=0x01a08 ( 6664) + I (219) esp_image: segment 0: paddr=0x00001020 vaddr=0x3fff0018 size=0x00004 ( 4) + I (227) esp_image: segment 1: paddr=0x0000102c vaddr=0x3fff001c size=0x02104 ( 8452) + I (239) esp_image: segment 2: paddr=0x00003138 vaddr=0x40078000 size=0x03528 ( 13608) + I (249) esp_image: segment 3: paddr=0x00006668 vaddr=0x40080400 size=0x01a08 ( 6664) I (657) esp_image: segment 0: paddr=0x00020020 vaddr=0x3f400020 size=0x0808c ( 32908) map - I (669) esp_image: segment 1: paddr=0x000280b4 vaddr=0x3ffb0000 size=0x01ea4 ( 7844) - I (672) esp_image: segment 2: paddr=0x00029f60 vaddr=0x40080000 size=0x00400 ( 1024) + I (669) esp_image: segment 1: paddr=0x000280b4 vaddr=0x3ffb0000 size=0x01ea4 ( 7844) + I (672) esp_image: segment 2: paddr=0x00029f60 vaddr=0x40080000 size=0x00400 ( 1024) 0x40080000: _WindowOverflow4 at esp-idf/esp-idf/components/freertos/xtensa_vectors.S:1778 - I (676) esp_image: segment 3: paddr=0x0002a368 vaddr=0x40080400 size=0x05ca8 ( 23720) + I (676) esp_image: segment 3: paddr=0x0002a368 vaddr=0x40080400 size=0x05ca8 ( 23720) I (692) esp_image: segment 4: paddr=0x00030018 vaddr=0x400d0018 size=0x126a8 ( 75432) map 0x400d0018: _flash_cache_start at ??:? - I (719) esp_image: segment 5: paddr=0x000426c8 vaddr=0x400860a8 size=0x01f4c ( 8012) + I (719) esp_image: segment 5: paddr=0x000426c8 vaddr=0x400860a8 size=0x01f4c ( 8012) 0x400860a8: prvAddNewTaskToReadyList at esp-idf/esp-idf/components/freertos/tasks.c:4561 I (722) flash_encrypt: Encrypting partition 2 at offset 0x20000... @@ -261,7 +270,7 @@ Once the flashing is complete device will reset and on next boot second stage bo I (211) cpu_start: ELF file SHA256: 8770c886bdf561a7... I (217) cpu_start: ESP-IDF: v4.0-dev-850-gc4447462d-dirty I (224) cpu_start: Starting app cpu, entry point is 0x40080e4c - 0x40080e4c: call_start_cpu1 at esp-idf/esp-idf/components/esp32/cpu_start.c:265 + 0x40080e4c: call_start_cpu1 at esp-idf/esp-idf/components/{IDF_TARGET_PATH_NAME}/cpu_start.c:265 I (0) cpu_start: App cpu up. I (235) heap_init: Initializing. RAM available for dynamic allocation: @@ -275,7 +284,7 @@ Once the flashing is complete device will reset and on next boot second stage bo I (0) cpu_start: Starting scheduler on APP CPU. Sample program to check Flash Encryption - This is ESP32 chip with 2 CPU cores, WiFi/BT/BLE, silicon revision 1, 4MB external flash + This is {IDF_TARGET_NAME} chip with 2 CPU cores, WiFi/BT/BLE, silicon revision 1, 4MB external flash Flash encryption feature is enabled Flash encryption mode is DEVELOPMENT Flash in encrypted mode with flash_crypt_cnt = 1 @@ -303,17 +312,17 @@ If all partitions needs to be updated in encrypted format, it can be done as Using Host Generated Flash Encryption Key ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -It is possible to pregenerate the flash encryption key on the host computer and burn it into the ESP32's eFuse key block. This allows data to be pre-encrypted on the host and flashed to the ESP32 without needing a plaintext flash update. This feature allows encrypted flashing in both :ref:`flash_enc_development_mode` and :ref:`flash_enc_release_mode` modes. +It is possible to pregenerate the flash encryption key on the host computer and burn it into the {IDF_TARGET_NAME}'s eFuse key block. This allows data to be pre-encrypted on the host and flashed to the {IDF_TARGET_NAME} without needing a plaintext flash update. This feature allows encrypted flashing in both :ref:`flash_enc_development_mode` and :ref:`flash_enc_release_mode` modes. .. note:: This option is not recommended for production unless a separate key is generated for each individual device. -- Ensure you have a ESP32 device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`. +- Ensure you have a {IDF_TARGET_NAME} device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`. - Generate a random key with espsecure.py:: espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin -- Burn the key to the device (one time only). **This must be done before first encrypted boot**, otherwise the ESP32 will generate a random key that software can't access or modify:: +- Burn the key to the device (one time only). **This must be done before first encrypted boot**, otherwise the {IDF_TARGET_NAME} will generate a random key that software can't access or modify:: espefuse.py --port PORT burn_key flash_encryption my_flash_encryption_key.bin @@ -353,7 +362,7 @@ Release Mode In Release mode UART bootloader can not perform flash encryption operations and new plaintext images can be downloaded ONLY using OTA scheme which will encrypt the plaintext image before writing to flash. -- Ensure you have a ESP32 device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`. +- Ensure you have a {IDF_TARGET_NAME} device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`. - Enable flash encryption support in second stage bootloader. In :ref:`project-configuration-menu`, navigate to "Security Features". @@ -382,7 +391,7 @@ For subsequent plaintext update in field :ref:`OTA scheme ` for more details. @@ -489,7 +498,7 @@ Key Points About Flash Encryption .. note:: The bootloader app binary ``bootloader.bin`` may become too large when both secure boot and flash encryption are enabled. See :ref:`secure-boot-bootloader-size`. .. important:: - Do not interrupt power to the ESP32 while the first boot encryption pass is running. If power is interrupted, the flash contents will be corrupted and require flashing with unencrypted data again. A reflash like this will not count towards the flashing limit. + Do not interrupt power to the {IDF_TARGET_NAME} while the first boot encryption pass is running. If power is interrupted, the flash contents will be corrupted and require flashing with unencrypted data again. A reflash like this will not count towards the flashing limit. .. _using-encrypted-flash: @@ -497,7 +506,7 @@ Key Points About Flash Encryption Using Encrypted Flash --------------------- -ESP32 app code can check if flash encryption is currently enabled by calling :cpp:func:`esp_flash_encryption_enabled`. Also, device can identify the flash encryption mode by calling :cpp:func:`esp_get_flash_encryption_mode`. +{IDF_TARGET_NAME} app code can check if flash encryption is currently enabled by calling :cpp:func:`esp_flash_encryption_enabled`. Also, device can identify the flash encryption mode by calling :cpp:func:`esp_get_flash_encryption_mode`. Once flash encryption is enabled, some care needs to be taken when accessing flash contents from code. @@ -558,7 +567,7 @@ Please refer to :doc:`OTA <../api-reference/system/ota>` for general information Disabling Flash Encryption -------------------------- -If you've accidentally enabled flash encryption for some reason, the next flash of plaintext data will soft-brick the ESP32 (the device will reboot continuously, printing the error ``flash read err, 1000``). +If you've accidentally enabled flash encryption for some reason, the next flash of plaintext data will soft-brick the {IDF_TARGET_NAME} (the device will reboot continuously, printing the error ``flash read err, 1000``). If flash encryption is enabled in Development mode, you can disable flash encryption again by writing ``FLASH_CRYPT_CNT`` eFuse. This can only be done three times per chip. @@ -569,7 +578,7 @@ If flash encryption is enabled in Development mode, you can disable flash encryp - Run ``espefuse.py`` (in ``components/esptool_py/esptool``) to disable the FLASH_CRYPT_CNT:: espefuse.py burn_efuse FLASH_CRYPT_CNT -Reset the ESP32 and flash encryption should be disabled, the bootloader will boot as normal. +Reset the {IDF_TARGET_NAME} and flash encryption should be disabled, the bootloader will boot as normal. .. _flash-encryption-limitations: @@ -596,7 +605,7 @@ Flash Encryption and Secure Boot It is recommended to use flash encryption and secure boot together. However, if Secure Boot is enabled then additional restrictions apply to reflashing the device: - :ref:`updating-encrypted-flash-ota` are not restricted (provided the new app is signed correctly with the Secure Boot signing key). -- :ref:`Plaintext serial flash updates ` are only possible if the :ref:`Reflashable ` Secure Boot mode is selected and a Secure Boot key was pre-generated and burned to the ESP32 (refer to :ref:`Secure Boot ` docs.). In this configuration, ``idf.py bootloader`` will produce a pre-digested bootloader and secure boot digest file for flashing at offset 0x0. When following the plaintext serial reflashing steps it is necessary to re-flash this file before flashing other plaintext data. +- :ref:`Plaintext serial flash updates ` are only possible if the :ref:`Reflashable ` Secure Boot mode is selected and a Secure Boot key was pre-generated and burned to the {IDF_TARGET_NAME} (refer to :ref:`Secure Boot ` docs.). In this configuration, ``idf.py bootloader`` will produce a pre-digested bootloader and secure boot digest file for flashing at offset 0x0. When following the plaintext serial reflashing steps it is necessary to re-flash this file before flashing other plaintext data. - :ref:`Reflashing via Pregenerated Flash Encryption Key ` is still possible, provided the bootloader is not reflashed. Reflashing the bootloader requires the same :ref:`Reflashable ` option to be enabled in the Secure Boot config. .. _flash-encryption-advanced-features: diff --git a/docs/en/security/secure-boot.rst b/docs/en/security/secure-boot.rst index 6ff969d90..e13b285a3 100644 --- a/docs/en/security/secure-boot.rst +++ b/docs/en/security/secure-boot.rst @@ -7,7 +7,7 @@ Secure Boot is separate from the :doc:`Flash Encryption ` feat .. important:: - Enabling secure boot limits your options for further updates of your ESP32. Make sure to read this document throughly and understand the implications of enabling secure boot. + Enabling secure boot limits your options for further updates of your {IDF_TARGET_NAME}. Make sure to read this document throughly and understand the implications of enabling secure boot. Background ---------- @@ -49,7 +49,17 @@ The following keys are used by the secure boot process: - "secure bootloader key" is a 256-bit AES key that is stored in Efuse block 2. The bootloader can generate this key itself from the internal hardware random number generator, the user does not need to supply it (it is optionally possible to supply this key, see :ref:`secure-boot-reflashable`). The Efuse holding this key is read & write protected (preventing software access) before secure boot is enabled. - - By default, the Efuse Block 2 Coding Scheme is "None" and a 256 bit key is stored in this block. On some ESP32s, the Coding Scheme is set to 3/4 Encoding (CODING_SCHEME efuse has value 1) and a 192 bit key must be stored in this block. See ESP32 Technical Reference Manual section 20.3.1.3 *System Parameter coding_scheme* for more details. The algorithm operates on a 256 bit key in all cases, 192 bit keys are extended by repeating some bits (:ref:`details`). + - By default, the Efuse Block 2 Coding Scheme is "None" and a 256 bit key is stored in this block. On some {IDF_TARGET_NAME}s, the Coding Scheme is set to 3/4 Encoding (CODING_SCHEME efuse has value 1) and a 192 bit key must be stored in this block. + + .. only:: esp32 + + See ESP32 Technical Reference Manual section 20.3.1.3 *System Parameter coding_scheme* for more details. + + .. only:: esp32s2 + + See ESP32-S2 Technical Reference Manual for more details. + + The algorithm operates on a 256 bit key in all cases, 192 bit keys are extended by repeating some bits (:ref:`details`). - "secure boot signing key" is a standard ECDSA public/private key pair (see :ref:`secure-boot-image-signing-algorithm`) in PEM format. @@ -64,7 +74,7 @@ Bootloader Size When secure boot is enabled the bootloader app binary ``bootloader.bin`` may exceed the default bootloader size limit. This is especially likely if flash encryption is enabled as well. The default size limit is 0x7000 (28672) bytes (partition table offset 0x8000 - bootloader offset 0x1000). -If the bootloader becomes too large, the ESP32 will fail to boot - errors will be logged about either invalid partition table or invalid bootloader checksum. +If the bootloader becomes too large, 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: @@ -100,11 +110,11 @@ How To Enable Secure Boot .. note:: ``idf.py flash`` doesn't flash the bootloader if secure boot is enabled. -8. Reset the ESP32 and it will boot the software bootloader you flashed. The software bootloader will enable secure boot on the chip, and then it verifies the app image signature and boots the app. You should watch the serial console output from the ESP32 to verify that secure boot is enabled and no errors have occurred due to the build configuration. +8. Reset the {IDF_TARGET_NAME} and it will boot the software bootloader you flashed. The software bootloader will enable secure boot on the chip, and then it verifies the app image signature and boots the app. You should watch the serial console output from the {IDF_TARGET_NAME} to verify that secure boot is enabled and no errors have occurred due to the build configuration. .. note:: Secure boot won't be enabled until after a valid partition table and app image have been flashed. This is to prevent accidents before the system is fully configured. -.. note:: If the ESP32 is reset or powered down during the first boot, it will start the process again on the next boot. +.. note:: If the {IDF_TARGET_NAME} is reset or powered down during the first boot, it will start the process again on the next boot. 9. On subsequent boots, the secure boot hardware will verify the software bootloader has not changed (using the secure bootloader key) and then the software bootloader will verify the signed partition table and app image (using the public key portion of the secure boot signing key). @@ -194,7 +204,7 @@ The following sections contain low-level reference descriptions of various secur Secure Boot Hardware Support ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The first stage of secure boot verification (checking the software bootloader) is done via hardware. The ESP32's Secure Boot support hardware can perform three basic operations: +The first stage of secure boot verification (checking the software bootloader) is done via hardware. The {IDF_TARGET_NAME}'s Secure Boot support hardware can perform three basic operations: 1. Generate a random sequence of bytes from a hardware random number generator.