mirror
/
esp-idf
kopia lustrzana https://github.com/espressif/esp-idf
1
0
Forkuj 0
Kod Zgłoszenia Projekty Wydania Wiki Aktywność

doc: Update English pages with generic target name

pull/2405/merge
Marius Vikhammer 2019-12-09 11:01:09 +08:00 zatwierdzone przez Angus Gratton
rodzic c848aa74ac
commit 9352899d69
72 zmienionych plików z 1346 dodań i 1175 usunięć
Pokaż statystyki Ściągnij plik aktualizacji Ściągnij plik porównania Expand all files Collapse all files

6
docs/conf_common.py
Wyświetl plik

@ -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']:

15
docs/en/about.rst
Wyświetl plik

@ -2,9 +2,18 @@ About
=====
:link_to_translation:`zh_CN:[中文]`
This is documentation of `ESP-IDF <https://github.com/espressif/esp-idf>`_, the framework to develop applications for `ESP32 <https://espressif.com/en/products/hardware/esp32/overview>`_ chip by `Espressif <https://espressif.com>`_.
.. 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 <https://github.com/espressif/esp-idf>`_, the framework to develop applications for `{IDF_TARGET_NAME} <https://espressif.com/en/products/hardware/esp32/overview>`_ chip by `Espressif <https://espressif.com>`_.
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 <https://github.com/espressif/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.

39
docs/en/api-guides/RF_calibration.rst
Wyświetl plik

@ -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`.

27
docs/en/api-guides/app_trace.rst
Wyświetl plik

@ -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).

70
docs/en/api-guides/blufi.rst
Wyświetl plik

@ -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

32
docs/en/api-guides/build-system-legacy.rst
Wyświetl plik

@ -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 <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 <linker-script-generation>` for a quick start guide as well as a detailed discussion
of the mechanism.

4
docs/en/api-guides/console.rst
Wyświetl plik

@ -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.

10
docs/en/api-guides/core_dump.rst
Wyświetl plik

@ -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.

10
docs/en/api-guides/deep-sleep-stub.rst
Wyświetl plik

@ -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.

4
docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst
Wyświetl plik

@ -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`.

12
docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst
Wyświetl plik

@ -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 <https://launchstudio.bluetooth.com/ListingDetails/94304>`_ 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 <https://launchstudio.bluetooth.com/ListingDetails/94304>`_ 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 <get-started-ble-mesh-check-hardware>`.
* Three {IDF_TARGET_NAME} boards, see :ref:`options <get-started-ble-mesh-check-hardware>`.
* 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 <https://github.com/EspressifApp/EspBLEMeshForAndroid/releases/tag/v1.0.0>`_ Android App
@ -219,7 +219,7 @@ ESP-BLE-MESH Examples
* ESP-BLE-MESH Fast Provisioning - :example:`Client <bluetooth/esp_ble_mesh/ble_mesh_fast_provision/ble_mesh_fast_prov_client/tutorial/BLE_Mesh_Fast_Prov_Client_Example_Walkthrough.md>` and :example:`Server <bluetooth/esp_ble_mesh/ble_mesh_fast_provision/ble_mesh_fast_prov_server/tutorial/BLE_Mesh_Fast_Prov_Server_Example_Walkthrough.md>` - 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 <bluetooth/esp_ble_mesh/ble_mesh_fast_provision/ble_mesh_fast_prov_client>` and :example:`example server code <bluetooth/esp_ble_mesh/ble_mesh_fast_provision/ble_mesh_fast_prov_server>`.
* :example:`ESP-BLE-MESH and Wi-Fi Coexistence <bluetooth/esp_ble_mesh/ble_mesh_wifi_coexist/tutorial/BLE_Mesh_WiFi_Coexist_Example_Walkthrough.md>` - 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 <bluetooth/esp_ble_mesh/ble_mesh_wifi_coexist>`.
* :example:`ESP-BLE-MESH and Wi-Fi Coexistence <bluetooth/esp_ble_mesh/ble_mesh_wifi_coexist/tutorial/BLE_Mesh_WiFi_Coexist_Example_Walkthrough.md>` - 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 <bluetooth/esp_ble_mesh/ble_mesh_wifi_coexist>`.
* 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 <bluetooth/esp_ble_mesh/ble_mesh_console/ble_mesh_node>` and :example:`example Provisioner code <bluetooth/esp_ble_mesh/ble_mesh_console/ble_mesh_provisioner>`.

12
docs/en/api-guides/external-ram.rst
Wyświetl plik

@ -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.

70
docs/en/api-guides/fatal-errors.rst
Wyświetl plik

@ -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 <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 <tools/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 <tools/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 <tools/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:
<http://www.gnu.org/software/gdb/bugs/>.
@ -194,7 +182,7 @@ If :doc:`IDF Monitor <tools/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::

241
docs/en/api-guides/freertos-smp.rst
Wyświetl plik

@ -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!

22
docs/en/api-guides/general-notes.rst
Wyświetl plik

@ -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 <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 <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()

8
docs/en/api-guides/hlinterrupts.rst
Wyświetl plik

@ -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

2
docs/en/api-guides/index.rst
Wyświetl plik

@ -15,7 +15,7 @@ API Guides
Error Handling <error-handling>
:esp32: ESP-BLE-MESH <esp-ble-mesh/ble-mesh-index>
ESP-MESH (Wi-Fi) <mesh>
ESP32 Core Dump <core_dump>
{IDF_TARGET_NAME} Core Dump <core_dump>
Event Handling <event-handling>
External SPI-connected RAM <external-ram>
Fatal Errors <fatal-errors>

8
docs/en/api-guides/jtag-debugging/building-openocd-linux.rst
Wyświetl plik

@ -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`.

9
docs/en/api-guides/jtag-debugging/building-openocd-macos.rst
Wyświetl plik

@ -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`.

12
docs/en/api-guides/jtag-debugging/building-openocd-windows.rst
Wyświetl plik

@ -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`.

62
docs/en/api-guides/jtag-debugging/configure-other-jtag.rst
Wyświetl plik

@ -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`.

155
docs/en/api-guides/jtag-debugging/debugging-examples.rst
Wyświetl plik

@ -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 <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`__, 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 <https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`__, chapter IO_MUX and GPIO Matrix.
.. only:: esp32s2beta
For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual <https://www.espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_en.pdf>`__, 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=<optimized out>)
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 <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`__, 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 <https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`__, chapter IO_MUX and GPIO Matrix.
.. only:: esp32s2beta
For more information please refer to `{IDF_TARGET_NAME} Technical Reference Manual <https://www.espressif.com/sites/default/files/documentation/esp32-s2_technical_reference_manual_en.pdf>`__, 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$

66
docs/en/api-guides/jtag-debugging/index.rst
Wyświetl plik

@ -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 <building-openocd-windows>`, :doc:`Linux <building-openocd-linux>` and :doc:`MacOS <building-openocd-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 <https://www.eclipse.org/>`_ 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:

130
docs/en/api-guides/jtag-debugging/tips-and-quirks.rst
Wyświetl plik

@ -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 <jtag-debugging-tip-where-breakpoints>` 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 <jtag-debugging-tip-where-breakpoints>` 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 <offset>``
``esp32 appimage_offset <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 <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ 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 <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ 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:

46
docs/en/api-guides/jtag-debugging/using-debugger.rst
Wyświetl plik

@ -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 <http://gnu.org/licenses/gpl.html>
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:
<http://www.gnu.org/software/gdb/bugs/>.
@ -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.

40
docs/en/api-guides/linker-script-generation.rst
Wyświetl plik

@ -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<ldgen-default-placements>`.
:ref:`here<ldgen-default-placements>`.
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<ldgen-default-scheme>`.
.. 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<ldgen-linker-fragment-files>` and
that the linker script passed to the linker is dynamically generated from: (1) the collected :ref:`linker fragment files<ldgen-linker-fragment-files>` and
(2) :ref:`linker script template<ldgen-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<ldgen-sections-fragment>`,
placement rules that tell where to place sections of object files in the output binary. There are three types of fragments: :ref:`sections<ldgen-sections-fragment>`,
:ref:`scheme<ldgen-scheme-fragment>` and :ref:`mapping<ldgen-mapping-fragment>`.
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.

10
docs/en/api-guides/partition-tables.rst
Wyświetl plik

@ -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 <CONFIG_PARTITION_TABLE_OFFSET>`) 0x8000 in the flash.
A single {IDF_TARGET_NAME}'s flash can contain multiple apps, as well as many different kinds of data (calibration data, filesystems, parameter storage, etc). For this reason a partition table is flashed to (:ref:`default offset <CONFIG_PARTITION_TABLE_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.

12
docs/en/api-guides/romconsole.rst
Wyświetl plik

@ -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*

16
docs/en/api-guides/tools/idf-monitor.rst
Wyświetl plik

@ -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).

16
docs/en/api-guides/ulp.rst
Wyświetl plik

@ -6,8 +6,8 @@ ULP Coprocessor programming
.. toctree::
:maxdepth: 1
Instruction set reference for ESP32 ULP <ulp_instruction_set>
Instruction set reference for ESP32-S2 ULP <ulps2_instruction_set>
:esp32: Instruction set reference for ESP32 ULP <ulp_instruction_set>
:esp32s2: Instruction set reference for ESP32-S2 ULP <ulps2_instruction_set>
Programming using macros (legacy) <ulp_macros>
@ -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`)

28
docs/en/api-guides/ulp_instruction_set.rst
Wyświetl plik

@ -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:

22
docs/en/api-guides/unit-tests.rst
Wyświetl plik

@ -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

440
docs/en/api-guides/wifi.rst
Wyświetl plik

Plik diff jest za duży Load Diff

8
docs/en/api-reference/network/esp_wifi.rst
Wyświetl plik

@ -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).

59
docs/en/api-reference/peripherals/adc.rst
Wyświetl plik

@ -4,24 +4,27 @@ Analog to Digital Converter
Overview
--------
The ESP32 integrates two 12-bit SAR (`Successive Approximation Register <https://en.wikipedia.org/wiki/Successive_approximation_ADC>`_) ADCs supporting a total of 18 measurement channels (analog enabled pins).
The {IDF_TARGET_NAME} integrates two 12-bit SAR (`Successive Approximation Register <https://en.wikipedia.org/wiki/Successive_approximation_ADC>`_) 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 <esp-modules-and-boards-esp32-devkitc>`: GPIO 0 cannot be used due to external auto program circuits.
- :ref:`ESP-WROVER-KIT <esp-modules-and-boards-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 <esp-modules-and-boards-esp32-devkitc>`: GPIO 0 cannot be used due to external auto program circuits.
- :ref:`ESP-WROVER-KIT <esp-modules-and-boards-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 <driver/adc.h>
...
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);

14
docs/en/api-reference/peripherals/can.rst
Wyświetl plik

@ -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`.

8
docs/en/api-reference/peripherals/dac.rst
Wyświetl plik

@ -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.

2
docs/en/api-reference/peripherals/esp_slave_protocol.rst
Wyświetl plik

@ -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 <https://www.sdcard.org/downloads/pls/>`_). In this specification
and below, the SDIO slave is also called an (SD)IO card. All the

14
docs/en/api-reference/peripherals/gpio.rst
Wyświetl plik

@ -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.

13
docs/en/api-reference/peripherals/i2c.rst
Wyświetl plik

@ -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 <https://www.nxp.com/docs/en/user-guide/UM10204.pdf>`_.
{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 <https://www.nxp.com/docs/en/user-guide/UM10204.pdf>`_.
.. _i2c-api-error-handling:

8
docs/en/api-reference/peripherals/i2s.rst
Wyświetl plik

@ -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 <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#page=306>`_.
.. only:: esp32
For more information, see the `ESP32 Technical Reference Manual <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#page=306>`_.
.. 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

13
docs/en/api-reference/peripherals/ledc.rst
Wyświetl plik

@ -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 <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`_ (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 <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`_ (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 <https://espressif.com/sites/default/files/documentation/esp32s2_technical_reference_manual_en.pdf>`_ (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

13
docs/en/api-reference/peripherals/mcpwm.rst
Wyświetl plik

@ -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
-------------

16
docs/en/api-reference/peripherals/rmt.rst
Wyświetl plik

@ -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`.

2
docs/en/api-reference/protocols/esp_http_server.rst
Wyświetl plik

@ -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.

28
docs/en/api-reference/protocols/mdns.rst
Wyświetl plik

@ -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 <http://www.dns-sd.org/serviceTypes.html>`_.
* ``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

6
docs/en/api-reference/storage/nvs_flash.rst
Wyświetl plik

@ -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.

8
docs/en/api-reference/storage/spiffs.rst
Wyświetl plik

@ -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

8
docs/en/api-reference/system/app_image_format.rst
Wyświetl plik

@ -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:

2
docs/en/api-reference/system/app_trace.rst
Wyświetl plik

@ -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`

76
docs/en/api-reference/system/efuse.rst
Wyświetl plik

@ -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 <https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`_ 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 <https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>`_ 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 <https://www.espressif.com/sites/default/files/documentation/esp32s2_technical_reference_manual_en.pdf>`_. 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 <https://github.com/espressif/esptool/wiki/espefuse>`_.
esptool includes a useful tool for reading/writing {IDF_TARGET_NAME} eFuse bits - `espefuse.py <https://github.com/espressif/esptool/wiki/espefuse>`_.
::
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

2
docs/en/api-reference/system/heap_debug.rst
Wyświetl plik

@ -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 </path/to/program/elf>``
4. Run GDB using the following command ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -x gdbinit </path/to/program/elf>``
5. Quit GDB when program stops at :cpp:func:`heap_trace_stop`. Trace data are saved in ``/tmp/heap.svdat``

4
docs/en/api-reference/system/index.rst
Wyświetl plik

@ -16,8 +16,8 @@ System API
Heap Memory Allocation <mem_alloc>
Heap Memory Debugging <heap_debug>
High Resolution Timer <esp_timer>
Himem (large external SPI RAM) API <himem>
Inter-Processor Call <ipc>
:esp32: Himem (large external SPI RAM) API <himem>
:esp32: Inter-Processor Call <ipc>
Call function with external stack <esp_expression_with_stack>
Interrupt Allocation <intr_alloc>
Logging <log>

22
docs/en/api-reference/system/intr_alloc.rst
Wyświetl plik

@ -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.

14
docs/en/api-reference/system/mem_alloc.rst
Wyświetl plik

@ -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 </api-guides/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 </api-guides/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 <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 </api-guides/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</api-reference/system/himem>`.
..only:: esp32
To use the region above the 4MiB limit, you can use the :doc:`himem API</api-reference/system/himem>`.
API Reference - Heap Allocation

15
docs/en/api-reference/system/ota.rst
Wyświetl plik

@ -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

4
docs/en/api-reference/system/perfmon.rst
Wyświetl plik

@ -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

13
docs/en/api-reference/system/power_management.rst
Wyświetl plik

@ -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.
============================ ======================================================

32
docs/en/api-reference/system/sleep_modes.rst
Wyświetl plik

@ -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.

54
docs/en/api-reference/system/system.rst
Wyświetl plik

@ -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 <https://en.wikipedia.org/wiki/MAC_address#Universal_vs._local>`_ 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:

54
docs/en/api-reference/system/wdts.rst
Wyświetl plik

@ -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

7
docs/en/contribute/add-ons-reference.rst
Wyświetl plik

@ -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
-----------------

63
docs/en/get-started/establish-serial-connection.rst
Wyświetl plik

@ -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 <esp-modules-and-boards-esp32-devkitc>`, `CP210x`_
`ESP32-LyraT <https://www.espressif.com/en/products/hardware/esp32-lyrat>`_, `CP210x`_
`ESP32-LyraTD-MSC <https://www.espressif.com/en/products/hardware/esp32-lyratd-msc>`_, `CP210x`_
:ref:`ESP32-PICO-KIT <esp-modules-and-boards-esp32-pico-kit>`, `CP210x`_
:ref:`ESP-WROVER-KIT <esp-modules-and-boards-esp-wrover-kit>`, `FTDI`_
:ref:`ESP32 Demo Board <esp-modules-and-boards-esp32-demo-board>`, `FTDI`_
`ESP-Prog`_, `FTDI`_, Programmer board (w/o ESP32)
`ESP32-MeshKit-Sense <https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/ESP32-MeshKit-Sense_guide_en.md#esp32-meshkit-sense-hardware-design-guidelines>`_, n/a, Use with `ESP-Prog`_
`ESP32-Sense Kit <https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/esp32_sense_kit_guide_en.md#guide-for-esp32-sense-development-kit>`_, n/a, Use with `ESP-Prog`_
:ref:`ESP32-DevKitC <esp-modules-and-boards-esp32-devkitc>`, `CP210x`_
`ESP32-LyraT <https://www.espressif.com/en/products/hardware/esp32-lyrat>`_, `CP210x`_
`ESP32-LyraTD-MSC <https://www.espressif.com/en/products/hardware/esp32-lyratd-msc>`_, `CP210x`_
:ref:`ESP32-PICO-KIT <esp-modules-and-boards-esp32-pico-kit>`, `CP210x`_
:ref:`ESP-WROVER-KIT <esp-modules-and-boards-esp-wrover-kit>`, `FTDI`_
:ref:`ESP32 Demo Board <esp-modules-and-boards-esp32-demo-board>`, `FTDI`_
`ESP-Prog`_, `FTDI`_, Programmer board (w/o ESP32)
`ESP32-MeshKit-Sense <https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/ESP32-MeshKit-Sense_guide_en.md#esp32-meshkit-sense-hardware-design-guidelines>`_, n/a, Use with `ESP-Prog`_
`ESP32-Sense Kit <https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/esp32_sense_kit_guide_en.md#guide-for-esp32-sense-development-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 <https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers>`_
* CP210x: `CP210x USB to UART Bridge VCP Drivers <https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers>`_
* FTDI: `FTDI Virtual COM Port Drivers <http://www.ftdichip.com/Drivers/VCP.htm>`_
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

94
docs/en/get-started/index.rst
Wyświetl plik

@ -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 <https://www.eclipse.org/>`_
.. 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 <https://github.com/espressif/esp-idf>`_.
To build applications for the {IDF_TARGET_NAME}, you need the software libraries provided by Espressif in `ESP-IDF repository <https://github.com/espressif/esp-idf>`_.
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 <get-started-configure>`.
3. Go to Component config --> ESP32-specific --> Main XTAL frequency, then change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz.

14
docs/en/get-started/linux-setup-scratch.rst
Wyświetl plik

@ -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.

2
docs/en/get-started/linux-setup.rst
Wyświetl plik

@ -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<linux-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<linux-dialout-group>`.
Next Steps
==========

6
docs/en/get-started/macos-setup-scratch.rst
Wyświetl plik

@ -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

6
docs/en/get-started/windows-setup-scratch.rst
Wyświetl plik

@ -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 <add-directory-windows-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 <add-directory-windows-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:

40
docs/en/hw-reference/index.rst
Wyświetl plik

@ -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) <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>
Datasheet (PDF) <https://espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>
Hardware Design Guidelines (PDF) <https://espressif.com/sites/default/files/documentation/esp32_hardware_design_guidelines_en.pdf>
Silicon Errata (PDF) <https://espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf>
Modules and Boards <modules-and-boards>
Previous Versions of Modules and Boards <modules-and-boards-previous>
Espressif Products Ordering Information (PDF) <http://www.espressif.com/sites/default/files/documentation/espressif_products_ordering_information_en.pdf>
Regulatory Certificates <https://www.espressif.com/en/certificates>
.. toctree::
:maxdepth: 3
Technical Reference Manual (PDF) <https://espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>
Datasheet (PDF) <https://espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>
Hardware Design Guidelines (PDF) <https://espressif.com/sites/default/files/documentation/esp32_hardware_design_guidelines_en.pdf>
Silicon Errata (PDF) <https://espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf>
Modules and Boards <modules-and-boards>
Previous Versions of Modules and Boards <modules-and-boards-previous>
Espressif Products Ordering Information (PDF) <http://www.espressif.com/sites/default/files/documentation/espressif_products_ordering_information_en.pdf>
Regulatory Certificates <https://www.espressif.com/en/certificates>
.. only:: esp32s2beta
.. toctree::
:maxdepth: 3
Technical Reference Manual (PDF) <https://espressif.com/sites/default/files/documentation/esp32s2_technical_reference_manual_en.pdf>
Datasheet (PDF) <https://espressif.com/sites/default/files/documentation/esp32s2_datasheet_en.pdf>
Modules and Boards <modules-and-boards>
Previous Versions of Modules and Boards <modules-and-boards-previous>
Espressif Products Ordering Information (PDF) <http://www.espressif.com/sites/default/files/documentation/espressif_products_ordering_information_en.pdf>
Regulatory Certificates <https://www.espressif.com/en/certificates>

10
docs/en/libraries-and-frameworks/cloud-frameworks.rst
Wyświetl plik

@ -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 <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/aws/aws-iot-device-sdk-embedded-C>`_.
`https://github.com/espressif/esp-aws-iot <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 <https://github.com/aws/aws-iot-device-sdk-embedded-C>`_.
Azure IoT
---------
`https://github.com/espressif/esp-azure <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/Azure/azure-iot-sdk-c>`_.
`https://github.com/espressif/esp-azure <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 <https://github.com/Azure/azure-iot-sdk-c>`_.
Google IoT Core
Google IoT Core
---------------
`https://github.com/espressif/esp-google-iot <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/GoogleCloudPlatform/iot-device-sdk-embedded-c>`_.
`https://github.com/espressif/esp-google-iot <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 <https://github.com/GoogleCloudPlatform/iot-device-sdk-embedded-c>`_.

89
docs/en/security/flash-encryption.rst
Wyświetl plik

@ -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 <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 <updating-encrypted-fl
Possible Failures
^^^^^^^^^^^^^^^^^
Once flash encryption is enabled and if the ``FLASH_CRYPT_CNT`` eFuse value has an odd number of bits set then all the partitions (which are marked with encryption flag) are expected to contain encrypted ciphertext. Below are three typical failure cases if the ESP32 is loaded with plaintext data:
Once flash encryption is enabled and if the ``FLASH_CRYPT_CNT`` eFuse value has an odd number of bits set then all the partitions (which are marked with encryption flag) are expected to contain encrypted ciphertext. Below are three typical failure cases if the {IDF_TARGET_NAME} is loaded with plaintext data:
1. In case the bootloader partition is re-updated with plaintext bootloader image the ROM loader will fail to load the bootloader and following type of failure will be displayed:
@ -390,27 +399,27 @@ Once flash encryption is enabled and if the ``FLASH_CRYPT_CNT`` eFuse value has
rst:0x3 (SW_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
flash read err, 1000
ets_main.c 371
ets_main.c 371
ets Jun 8 2016 00:22:57
rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
flash read err, 1000
ets_main.c 371
ets_main.c 371
ets Jun 8 2016 00:22:57
rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
flash read err, 1000
ets_main.c 371
ets_main.c 371
ets Jun 8 2016 00:22:57
rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
flash read err, 1000
ets_main.c 371
ets_main.c 371
ets Jun 8 2016 00:22:57
rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
flash read err, 1000
ets_main.c 371
ets_main.c 371
ets Jun 8 2016 00:22:57
.. note:: This error also appears in the flash contents is erased or corrupted.
@ -477,7 +486,7 @@ Key Points About Flash Encryption
- The `flash encryption algorithm` is AES-256, where the key is "tweaked" with the offset address of each 32 byte block of flash. This means every 32 byte block (two consecutive 16 byte AES blocks) is encrypted with a unique key derived from the flash encryption key.
- Flash access is transparent via the flash cache mapping feature of ESP32 - any flash regions which are mapped to the address space will be transparently decrypted when read.
- Flash access is transparent via the flash cache mapping feature of {IDF_TARGET_NAME} - any flash regions which are mapped to the address space will be transparently decrypted when read.
It may be desirable for some data partitions to remain unencrypted for ease of access, or to use flash-friendly update algorithms that are ineffective if the data is encrypted. NVS partitions for non-volatile storage cannot be encrypted since NVS library is not directly compatible with flash encryption. Refer to :ref:`NVS Encryption <nvs_encryption>` 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 <updating-encrypted-flash-serial>` are only possible if the :ref:`Reflashable <CONFIG_SECURE_BOOTLOADER_MODE>` Secure Boot mode is selected and a Secure Boot key was pre-generated and burned to the ESP32 (refer to :ref:`Secure Boot <secure-boot-reflashable>` 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 <updating-encrypted-flash-serial>` are only possible if the :ref:`Reflashable <CONFIG_SECURE_BOOTLOADER_MODE>` 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 <secure-boot-reflashable>` 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 <pregenerated-flash-encryption-key>` is still possible, provided the bootloader is not reflashed. Reflashing the bootloader requires the same :ref:`Reflashable <CONFIG_SECURE_BOOTLOADER_MODE>` option to be enabled in the Secure Boot config.
.. _flash-encryption-advanced-features:

22
docs/en/security/secure-boot.rst
Wyświetl plik

@ -7,7 +7,7 @@ Secure Boot is separate from the :doc:`Flash Encryption <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<secure-bootloader-digest-algorithm>`).
- 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-bootloader-digest-algorithm>`).
- "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.