alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2025-09-23 01:05:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: initial update of programming guide for C3

Browse Source 
Updates "front page" content, get-started, and api-guides with C3 content

Enable building and publishing of C3 docs in CI
This commit is contained in:
Marius Vikhammer
2021-01-27 10:12:58 +08:00
parent bd1578f2e3
commit 548fd02d10
58 changed files with 442 additions and 281 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
docs/en/api-guides/app_trace.rst
View File

@@ -171,7 +171,7 @@ Below is the description of available OpenOCD application tracing commands.
Command usage:
``esp32 apptrace [start <options>] | [stop] | [status] | [dump <cores_num> <outfile>]``
``esp apptrace [start <options>] | [stop] | [status] | [dump <cores_num> <outfile>]``
Sub-commands:
@@ -214,7 +214,7 @@ Command usage examples:
::
esp32 apptrace start file://trace.log 1 2048 5 0 0
esp 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.
@@ -226,15 +226,15 @@ Command usage examples:
::
esp32 apptrace start file://trace.log 1 -1 -1 0 0
esp apptrace start file://trace.log 1 -1 -1 0 0
There is no limitation on the size of collected data and there is no any data timeout set. This process may be stopped by issuing ``esp32 apptrace stop`` command on OpenOCD telnet prompt, or by pressing Ctrl+C in OpenOCD window.
There is no limitation on the size of collected data and there is no any data timeout set. This process may be stopped by issuing ``esp apptrace stop`` command on OpenOCD telnet prompt, or by pressing Ctrl+C in OpenOCD window.
3. Retrieve tracing data and save them indefinitely.
::
esp32 apptrace start file://trace.log 0 -1 -1 0 0
esp apptrace start file://trace.log 0 -1 -1 0 0
OpenOCD telnet command line prompt will not be available until tracing is stopped. To stop tracing press Ctrl+C in OpenOCD window.
@@ -242,7 +242,7 @@ Command usage examples:
::
esp32 apptrace start file://trace.log 0 2048 -1 1 0
esp apptrace start file://trace.log 0 2048 -1 1 0
To configure tracing immediately after reset use the openocd ``reset halt`` command.
@@ -351,7 +351,7 @@ OpenOCD SystemView Tracing Command Options
Command usage:
``esp32 sysview [start <options>] | [stop] | [status]``
``esp sysview [start <options>] | [stop] | [status]``
Sub-commands:
@@ -389,15 +389,15 @@ Command usage examples:
::
esp32 sysview start file://pro-cpu.SVDat file://app-cpu.SVDat
esp sysview start file://pro-cpu.SVDat file://app-cpu.SVDat
The tracing data will be retrieved and saved in non-blocking mode. To stop data this process enter ``esp32 apptrace stop`` command on OpenOCD telnet prompt, optionally pressing Ctrl+C in OpenOCD window.
The tracing data will be retrieved and saved in non-blocking mode. To stop data this process enter ``esp apptrace stop`` command on OpenOCD telnet prompt, optionally pressing Ctrl+C in OpenOCD window.
2. Retrieve tracing data and save them indefinitely.
::
esp32 sysview start file://pro-cpu.SVDat file://app-cpu.SVDat 0 -1 -1
esp sysview start file://pro-cpu.SVDat file://app-cpu.SVDat 0 -1 -1
OpenOCD telnet command line prompt will not be available until tracing is stopped. To stop tracing, press Ctrl+C in OpenOCD window.
@@ -405,7 +405,11 @@ 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 {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.
After trace data are collected user can use special tool to visualize the results and inspect behavior of the program.
.. only:: not CONFIG_FREERTOS_UNICORE
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.
@@ -416,25 +420,26 @@ Good instruction on how to install, configure and visualize data in Impulse from
IDF uses its own mapping for SystemView FreeRTOS events IDs, so user needs to replace original file with mapping ``$SYSVIEW_INSTALL_DIR/Description/SYSVIEW_FreeRTOS.txt`` with ``$IDF_PATH/docs/api-guides/SYSVIEW_FreeRTOS.txt``.
Also contents of that IDF specific file should be used when configuring SystemView serializer using above link.
.. only:: not CONFIG_FREERTOS_UNICORE
Configure Impulse for Dual Core Traces
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Configure Impulse for Dual Core Traces
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
After installing Impulse and ensuring that it can successfully load trace files for each core in separate tabs user can add special Multi Adapter port and load both files into one view. To do this user needs to do the following in Eclipse:
After installing Impulse and ensuring that it can successfully load trace files for each core in separate tabs user can add special Multi Adapter port and load both files into one view. To do this user needs to do the following in Eclipse:
1. Open 'Signal Ports' view. Go to Windows->Show View->Other menu. Find 'Signal Ports' view in Impulse folder and double-click on it.
2. In 'Signal Ports' view right-click on 'Ports' and select 'Add ...'->New Multi Adapter Port
3. In open dialog Press 'Add' button and select 'New Pipe/File'.
4. In open dialog select 'SystemView Serializer' as Serializer and set path to PRO CPU trace file. Press OK.
5. Repeat steps 3-4 for APP CPU trace file.
6. Double-click on created port. View for this port should open.
7. Click Start/Stop Streaming button. Data should be loaded.
8. Use 'Zoom Out', 'Zoom In' and 'Zoom Fit' button to inspect data.
9. For settings measurement cursors and other features please see `Impulse documentation <https://toem.de/index.php/projects/impulse>`_).
1. Open 'Signal Ports' view. Go to Windows->Show View->Other menu. Find 'Signal Ports' view in Impulse folder and double-click on it.
2. In 'Signal Ports' view right-click on 'Ports' and select 'Add ...'->New Multi Adapter Port
3. In open dialog Press 'Add' button and select 'New Pipe/File'.
4. In open dialog select 'SystemView Serializer' as Serializer and set path to PRO CPU trace file. Press OK.
5. Repeat steps 3-4 for APP CPU trace file.
6. Double-click on created port. View for this port should open.
7. Click Start/Stop Streaming button. Data should be loaded.
8. Use 'Zoom Out', 'Zoom In' and 'Zoom Fit' button to inspect data.
9. For settings measurement cursors and other features please see `Impulse documentation <https://toem.de/index.php/projects/impulse>`_).
.. note::
.. note::
If you have problems with visualization (no data are shown or strange behavior of zoom action is observed) you can try to delete current signal hierarchy and double click on the necessary file or port. Eclipse will ask you to create new signal hierarchy.
If you have problems with visualization (no data are shown or strange behavior of zoom action is observed) you can try to delete current signal hierarchy and double click on the necessary file or port. Eclipse will ask you to create new signal hierarchy.
.. _app_trace-gcov-source-code-coverage:
@@ -511,24 +516,24 @@ 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 {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.
An Instant Run-Time Dump is triggered by calling the ``{IDF_TARGET_NAME} 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 {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.
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 ``esp gcov dump`` OpenOCD command (via a telnet session). The ``esp 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).
GDB can be used to set a breakpoint on :cpp:func:`esp_gcov_dump`, then call ``mon esp32 gcov dump`` automatically via the use a ``gdbinit`` script (see Using GDB from :ref:`jtag-debugging-using-debugger-command-line`).
GDB can be used to set a breakpoint on :cpp:func:`esp_gcov_dump`, then call ``mon esp gcov dump`` automatically via the use a ``gdbinit`` script (see Using GDB from :ref:`jtag-debugging-using-debugger-command-line`).
The following GDB script is will add a breakpoint at :cpp:func:`esp_gcov_dump`, then call the ``mon esp32 gcov dump`` OpenOCD command.
The following GDB script is will add a breakpoint at :cpp:func:`esp_gcov_dump`, then call the ``mon esp gcov dump`` OpenOCD command.
.. code-block:: none
b esp_gcov_dump
commands
mon esp32 gcov dump
mon esp gcov dump
end

48
docs/en/api-guides/blufi.rst
View File

@@ -153,13 +153,13 @@ The format of Ack Frame（8 bit）：
| 0x0 (b’000000) | Ack | The data field of the Ack frame uses the same | The data field consumes a byte and its value is |
| | | sequence value of the frame to reply to. | the same as the sequence field of the frame to reply to. |
+-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+
| 0x1 (b’000001) | Set ESP32 to the security mode. | To inform ESP32 of the security mode to use | The data field consumes a byte. |
| 0x1 (b’000001) | Set ESP device to the security mode. | To inform ESP device of the security mode to use | The data field consumes a byte. |
| | | when sending data, which is allowed to be reset | The higher 4 bits are for the security mode setting |
| | | multiple times during the process. | of the control frame, and the lower 4 bits are for |
| | | Each setting affects the subsequent security mode used. | the security mode setting of the data frame. |
+ + + If it is not set, ESP32 will send the control frame +---------------------------------------------------------------+
+ + + If it is not set, ESP device will send the control frame +---------------------------------------------------------------+
| | | and data frame with no checksum and encryption by default. | b’0000: no checksum and no encryption; |
+ + + The data transmission from the mobile phone to ESP32 is +---------------------------------------------------------------+
+ + + The data transmission from the mobile phone to ESP device is +---------------------------------------------------------------+
| | | controlled by this control frame. | b’0001: with checksum but no encryption; |
+ + + +---------------------------------------------------------------+
| | | | b’0010: no checksum but with encryption; |
@@ -167,7 +167,7 @@ The format of Ack Frame（8 bit）：
| | | | b’0011: with both checksum and encryption. |
+-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+
| 0x2 (b’000010) | Set the opmode of Wi-Fi. | The frame contains opmode settings for | data[0] is for opmode settings, including: |
+ + + configuring for the Wi-Fi mode of ESP32. +---------------------------------------------------------------+
+ + + configuring for the Wi-Fi mode of ESP device. +---------------------------------------------------------------+
| | | | 0x00: NULL； |
+ + + +---------------------------------------------------------------+
| | | | 0x01: STA; |
@@ -179,13 +179,13 @@ The format of Ack Frame（8 bit）：
| | | | Please set the SSID/Password/Max Connection Number of |
| | | | the AP mode in the first place if an AP gets involved. |
+-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+
| 0x3 (b’000011) | Connect ESP32 to the AP. | To notify ESP32 that the essential information has been sent | No data field is contained. |
| | | and it is allowed to connect to the AP. | |
| 0x3 (b’000011) | Connect ESP device to the AP. | To notify ESP device that the essential information has been | No data field is contained. |
| | | sent and it is allowed to connect to the AP. | |
+-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+
| 0x4 (b’000100) | Disconnect ESP32 from the AP. | | No data field is contained. |
| 0x4 (b’000100) | Disconnect ESP device from the AP. | | No data field is contained. |
+-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+
| 0x5 (b’000101) | To get the information of ESP32’s Wi-Fi mode and its status. | | No data field is contained. |
| | | | When receiving this control frame, ESP32 will send back |
| 0x5 (b’000101) | To get the information of ESP device’s Wi-Fi mode and | | No data field is contained. |
| | it's status. | | When receiving this control frame, ESP device will send back |
| | | | a follow-up frame of Wi-Fi connection state report to |
| | | | the mobile phone with the information of the current opmode, |
| | | | connection status, SSID and so on. |
@@ -198,12 +198,12 @@ The format of Ack Frame（8 bit）：
+-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+
| 0x7 (b'000111) | Get the version information. | | |
+-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+
| 0x8 (b’001000) | Disconnect the BLE GATT link. | | ESP32 will disconnect the BLE GATT link |
| 0x8 (b’001000) | Disconnect the BLE GATT link. | | ESP device will disconnect the BLE GATT link |
| | | | after receives this command. |
+-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+
| 0x9 (b’001001) | Get the Wi-Fi list. | To get ESP32 to scan the Wi-Fi access points around. | No data field is contained. |
| 0x9 (b’001001) | Get the Wi-Fi list. | To get ESP device to scan the Wi-Fi access points around. | No data field is contained. |
| | | | When receiving this control frame, |
| | | | ESP32 will send back a follow-up frame of Wi-Fi list |
| | | | ESP device will send back a follow-up frame of Wi-Fi lis |
| | | | report to the mobile phone. |
+-------------------------+--------------------------------------------------------------+---------------------------------------------------------------+---------------------------------------------------------------+
@@ -216,27 +216,27 @@ The format of Ack Frame（8 bit）：
| | | function registered in the application layer. | |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0x1 (b’000001) | Send the BSSID for STA mode. | To send the BSSID of the AP for the STA device to | The length of the data depends on the length field. |
| | | connect under the condition that the SSID is hidden. | When the transmission direction is ESP32 to the mobile phone, |
| | | connect under the condition that the SSID is hidden. | When the transmission direction is ESP device to the mobile phone, |
| | | | it means to provide the mobile phone with the needed information. |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0x2 (b’000010) | Send the SSID for STA mode. | To send the SSID of the AP for the STA device to connect. | The length of the data depends on the length field. |
| | | | When the transmission direction is ESP32 to the mobile phone, |
| | | | When the transmission direction is ESP device to the mobile phone, |
| | | | it means to provide the mobile phone with the needed information. |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0x3 (b’000011) | Send the password for STA mode. | To send the password of the AP for the STA device to connect. | The length of the data depends on the length field. |
| | | | When the transmission direction is ESP32 to the mobile phone, |
| | | | When the transmission direction is ESP device to the mobile phone, |
| | | | it means to provide the mobile phone with the needed information. |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0x4 (b’000100) | Send the SSID for SoftAP mode. | | The length of the data depends on the length field. |
| | | | When the transmission direction is ESP32 to the mobile phone, |
| | | | When the transmission direction is ESP device to the mobile phone, |
| | | | it means to provide the mobile phone with the needed information. |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0x5 (b’000101) | Send the password for SoftAPmode. | | The length of the data depends on the length field. |
| | | | When the transmission direction is ESP32 to the mobile phone, |
| | | | When the transmission direction is ESP device to the mobile phone, |
| | | | it means to provide the mobile phone with the needed information. |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0x6 (b’000110) | Set the maximum connection number for SoftAP mode. | | data[0] represents the value of the connection number, |
| | | | ranging from 1 to 4. When the transmission direction is ESP32 |
| | | | ranging from 1 to 4. When the transmission direction is ESP device |
| | | | to the mobile phone, it means to provide the mobile phone with |
| | | | the needed information. |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
@@ -252,12 +252,12 @@ The format of Ack Frame（8 bit）：
+ + + +-----------------------------------------------------------------------+
| | | | 0x04: WPA_WPA2_PSK |
+ + + +-----------------------------------------------------------------------+
| | | | When the transmission direction is ESP32 to the mobile phone, |
| | | | When the transmission direction is ESP device to the mobile phone, |
| | | | it means to provide the mobile phone with the needed information. |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0x8 (b’001000) | Set the channel amount for SoftAP mode. | | data[0] represents the quantity of the supported channels, |
| | | | ranging from 1 to 14. |
| | | | When the transmission direction is ESP32 to the mobile phone, |
| | | | When the transmission direction is ESP device to the mobile phone, |
| | | | it means to provide the mobile phone with the needed information. |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0x9 (b’001001) | Username | It provides the username of the GATT client when using | The length of the data depends on the length field. |
@@ -281,7 +281,7 @@ The format of Ack Frame（8 bit）：
| 0xe (b’001110) | ServerPrivate Key | It provides the private key of the sever when | The length of the data depends on the length field. |
| | | using encryption of enterprise level. | The frame supports to be fragmented if the data length is not enough. |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0xf (b’001111) | Wi-Fi Connection State Report | To notify the phone of the ESP32's Wi-Fi status, | data[0] represents opmode, including: |
| 0xf (b’001111) | Wi-Fi Connection State Report | To notify the phone of the ESP device's Wi-Fi status, | data[0] represents opmode, including: |
+ + + including STA status and SoftAP status. +-----------------------------------------------------------------------+
| | | It is for the STA device to connect to the | 0x00: NULL |
+ + + mobile phone or the SoftAP. +-----------------------------------------------------------------------+
@@ -303,7 +303,7 @@ The format of Ack Frame（8 bit）：
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0x10 (b’010000) | Version | | data[0]= great versiondata[1]= sub version |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
| 0x11 (b’010001) | Wi-Fi List | To send the Wi-Fi list to ESP32. | The format of the data frame is length + RSSI + SSID |
| 0x11 (b’010001) | Wi-Fi List | To send the Wi-Fi list to ESP device. | The format of the data frame is length + RSSI + SSID |
| | | | and it supports to be sent into fragments |
| | | | if the data length is too long. |
+------------------+----------------------------------------------------+---------------------------------------------------------------+-----------------------------------------------------------------------+
@@ -352,9 +352,9 @@ The format of Ack Frame（8 bit）：
+--------------------+------------------------------------------------------------------------------------------------+
| 0x04 | Represents the data direction. |
+--------------------+------------------------------------------------------------------------------------------------+
| | 0 means the mobile phone to ESP32; |
| | 0 means the mobile phone to ESP device; |
+--------------------+------------------------------------------------------------------------------------------------+
| | 1 means ESP32 to the mobile phone. |
| | 1 means ESP device to the mobile phone. |
+--------------------+------------------------------------------------------------------------------------------------+
| 0x08 | Indicates whether the other person is required to reply to an ACK. |
+--------------------+------------------------------------------------------------------------------------------------+

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

@@ -36,7 +36,7 @@ Concepts
- "components" are modular pieces of standalone code which are compiled into static libraries (.a files) and linked into an app. Some are provided by ESP-IDF itself, others may be sourced from other places.
- "Target" is the hardware for which an application is built. At the moment, ESP-IDF supports ``esp32`` and ``esp32s2`` targets.
- "Target" is the hardware for which an application is built. At the moment, ESP-IDF supports ``esp32``, ``esp32s2`` and ``esp32c3`` targets.
Some things are not part of the project:
@@ -618,7 +618,7 @@ Common component requirements
To avoid duplication, every component automatically requires some "common" IDF components even if they are not mentioned explicitly. Headers from these components can always be included.
The list of common components is: freertos, newlib, heap, log, soc, esp_rom, esp_common, xtensa, cxx.
The list of common components is: freertos, newlib, heap, log, soc, esp_rom, esp_common, xtensa/riscv, cxx.
Including components in the build
----------------------------------
@@ -1007,6 +1007,7 @@ ESP-IDF supports multiple targets (chips). The identifiers used for each chip ar
* ``esp32`` — for ESP32-D0WD, ESP32-D2WD, ESP32-S0WD (ESP-SOLO), ESP32-U4WDH, ESP32-PICO-D4
* ``esp32s2``— for ESP32-S2
* ``esp32c3``— for ESP32-C3
To select the target before building the project, use ``idf.py set-target <target>`` command, for example::

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

@@ -4,11 +4,11 @@ Core Dump
Overview
--------
.. only:: esp32s2
.. only:: not esp32
.. note::
The python utility does not currently support ESP32-S2
The python utility does not fully support {IDF_TARGET_NAME}
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
@@ -127,14 +127,14 @@ Example
2. In your project, create a global variable in DRAM area as such as:
.. code-block:: bash
// uint8_t global_var;
COREDUMP_DRAM_ATTR uint8_t global_var;
3. In main application, set the variable to any value and `assert(0)` to cause a crash.
.. code-block:: bash
global_var = 25;
assert(0);
@@ -143,13 +143,13 @@ Example
5. Run the command below to start core dumping in GDB, where ``PORT`` is the device USB port:
.. code-block:: bash
espcoredump.py -p PORT dbg_corefile <path/to/elf>
6. In GDB shell, type ``p global_var`` to get the variable content:
.. code-block:: bash
(gdb) p global_var
$1 = 25 '\031'

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

@@ -55,7 +55,11 @@ The first way is simpler for very short and simple code, or for source files whe
Loading Data Into RTC Memory
----------------------------
Data used by stub code must be resident in RTC memory. The data can be placed in RTC Fast memory or in RTC Slow memory which is also used by the ULP.
Data used by stub code must be resident in RTC memory.
.. only:: SOC_RTC_SLOW_MEM_SUPPORTED
The data can be placed in RTC Fast memory or in RTC Slow memory which is also used by the ULP.
Specifying this data can be done in one of two ways:
@@ -69,11 +73,16 @@ The first way is to use the ``RTC_DATA_ATTR`` and ``RTC_RODATA_ATTR`` to specify
esp_rom_printf(fmt_str, wake_count++);
}
.. only:: esp32
.. only:: SOC_RTC_SLOW_MEM_SUPPORTED
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 RTC memory area where this data will be placed can be configured via menuconfig option named ``CONFIG_{IDF_TARGET_CFG_PREFIX}_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.
.. only:: not SOC_RTC_SLOW_MEM_SUPPORTED
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, but for {IDF_TARGET_NAME} there is only RTC fast memory, so both attributes will map to this region.
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/fatal-errors.rst
View File

@@ -41,7 +41,7 @@ In all cases, error cause will be printed in parens. See `Guru Meditation Errors
Subsequent behavior of the panic handler can be set using :ref:`CONFIG_ESP_SYSTEM_PANIC` configuration choice. The available options are:
- Print registers and reboot (``CONFIG_ESP_SYSTEM_PANIC_PRINT_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 (``CONFIG_ESP_SYSTEM_PANIC_PRINT_HALT``)
@@ -169,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-{IDF_TARGET_TOOLCHAIN_NAME}-elf".
This GDB was configured as "--host=x86_64-build_apple-darwin16.3.0 --target={IDF_TARGET_TOOLCHAIN_PREFIX}".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>.

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

@@ -11,7 +11,7 @@ API Guides
Build System <build-system>
:esp32: Build System (Legacy GNU Make) <build-system-legacy>
Deep Sleep Wake Stubs <deep-sleep-stub>
:esp32s2: Device Firmware Upgrade through USB <dfu>
:SOC_USB_SUPPORTED: Device Firmware Upgrade through USB <dfu>
Error Handling <error-handling>
:SOC_BT_SUPPORTED: ESP-BLE-MESH <esp-ble-mesh/ble-mesh-index>
ESP-MESH (Wi-Fi) <mesh>
@@ -29,15 +29,15 @@ API Guides
lwIP TCP/IP Stack <lwip>
Partition Tables <partition-tables>
:esp32: RF Calibration <RF_calibration>
ROM debug console <romconsole>
:esp32: ROM debug console <romconsole>
:esp32: Secure Boot <../security/secure-boot-v1>
Secure Boot V2 <../security/secure-boot-v2>
Thread Local Storage <thread-local-storage>
Tools <tools/index>
:SOC_ULP_SUPPORTED: ULP Coprocessor <ulp>
:esp32: ULP Coprocessor (Legacy GNU Make) <ulp-legacy>
:esp32s2: ULP-RISC-V Coprocessor <ulp-risc-v>
:SOC_RISCV_COPROC_SUPPORTED: ULP-RISC-V Coprocessor <ulp-risc-v>
Unit Testing <unit-tests>
:esp32: Unit Testing (Legacy GNU Make) <unit-tests-legacy>
:esp32s2: USB Console <usb-console>
:SOC_USB_SUPPORTED: USB Console <usb-console>
WiFi Driver <wifi>

8
docs/en/api-guides/jtag-debugging/configure-ft2232h-jtag.rst
View File

@@ -1,4 +1,4 @@
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: devkit-defs
:end-before: ---
@@ -12,13 +12,13 @@ All versions of |devkit-name| boards have built-in JTAG functionality. Putting i
Configure Hardware
^^^^^^^^^^^^^^^^^^
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: devkit-hw-config
:end-before: ---
* Verify if {IDF_TARGET_NAME} pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation:
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: jtag-pins
:end-before: ---
@@ -118,7 +118,7 @@ Manually unloading the driver
4. Run OpenOCD:
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: run-openocd
:end-before: ---

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

@@ -10,7 +10,7 @@ Configure Hardware
1. Identify all pins / signals on JTAG interface and {IDF_TARGET_NAME} board, that should be connected to establish communication.
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: jtag-pins
:end-before: ---

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

@@ -25,7 +25,7 @@ GDB. The document is structured as follows:
This section provides collection of tips and quirks related JTAG debugging of {IDF_TARGET_NAME} with OpenOCD and GDB.
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: devkit-defs
:end-before: ---
@@ -54,7 +54,7 @@ This document provides a guide to installing OpenOCD for {IDF_TARGET_NAME} and d
How it Works?
-------------
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.
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 {IDF_TARGET_TOOLCHAIN_PREFIX}-gdb debugger, OpenOCD on chip debugger and JTAG adapter connected to {IDF_TARGET_NAME} target.
.. figure:: ../../../_static/jtag-debugging-overview.jpg
:align: center
@@ -149,7 +149,7 @@ Once target is configured and connected to computer, you are ready to launch Ope
Open a terminal and set it up for using the ESP-IDF as described in the :ref:`setting up the environment <get-started-set-up-env>` section of the Getting Started Guide. Then run OpenOCD (this command works on Windows, Linux, and macOS):
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: run-openocd
:end-before: ---
@@ -161,7 +161,7 @@ Open a terminal and set it up for using the ESP-IDF as described in the :ref:`se
You should now see similar output (this log is for |run-openocd-device-name|):
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: run-openocd-output
:end-before: ---
@@ -179,7 +179,7 @@ Build and upload your application to {IDF_TARGET_NAME} as usual, see :ref:`get-s
Another option is to write application image to flash using OpenOCD via JTAG with commands like this:
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: run-openocd-upload
:end-before: ---
@@ -201,7 +201,7 @@ You are now ready to start application debugging. Follow steps described in sect
Launching Debugger
------------------
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.
The toolchain for {IDF_TARGET_NAME} features GNU Debugger, in short GDB. It is available with other toolchain programs under filename: {IDF_TARGET_TOOLCHAIN_PREFIX}-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.
@@ -263,13 +263,13 @@ For Windows:
Example of invoking OpenOCD build locally from sources, for Linux and macOS:
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: run-openocd-src-linux
:end-before: ---
and Windows:
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: run-openocd-src-win
:end-before: ---

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

@@ -37,7 +37,7 @@ Offset should be in hex format. To reset to the default behaviour you can specif
.. highlight:: bash
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: run-openocd-appimage-offset
:end-before: ---
@@ -128,7 +128,7 @@ There are several kinds of OpenOCD configuration files (``*.cfg``). All configur
The following configuration files are available for {IDF_TARGET_NAME}:
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: openocd-cfg-files
:end-before: ---
@@ -176,7 +176,7 @@ It is important to set the variable before including the ESP-specific configurat
* - ``ESP_SEMIHOST_BASEDIR``
- Set to the path (on the host) which will be the default directory for semihosting functions.
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: openocd-target-specific-config-vars
:end-before: ---
@@ -195,7 +195,7 @@ 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 {IDF_TARGET_NAME} module and JTAG adapter. {IDF_TARGET_NAME} JTAG is using the following pins:
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: jtag-pins
:end-before: ---
@@ -263,19 +263,19 @@ In case you encounter a problem with OpenOCD or GDB programs itself and do not f
OpenOCD:
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: run-openocd-d3
:end-before: ---
Logging to a file this way will prevent information displayed on the terminal. This may be a good thing taken amount of information provided, when increased debug level ``-d3`` is set. If you still like to see the log on the screen, then use another command instead:
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: run-openocd-d3-tee
:end-before: ---
Debugger:
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: run-gdb-remotelog
:end-before: ---

12
docs/en/api-guides/jtag-debugging/using-debugger.rst
View File

@@ -43,7 +43,7 @@ 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-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb`` to invoke debugger.
6. Click "Debugger" tab. In field "GDB Command" enter ``{IDF_TARGET_TOOLCHAIN_PREFIX}-gdb`` to invoke debugger.
7. Change default configuration of "Remote host" by entering ``3333`` under the "Port number".
@@ -141,7 +141,7 @@ Command Line
::
xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -x gdbinit build/blink.elf
{IDF_TARGET_TOOLCHAIN_PREFIX}-gdb -x gdbinit build/blink.elf
.. highlight:: none
@@ -149,14 +149,14 @@ Command Line
::
user-name@computer-name:~/esp/blink$ xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-gdb -x gdbinit build/blink.elf
user-name@computer-name:~/esp/blink$ {IDF_TARGET_TOOLCHAIN_PREFIX}-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-{IDF_TARGET_TOOLCHAIN_NAME}-elf".
This GDB was configured as "--host=x86_64-build_pc-linux-gnu --target={IDF_TARGET_TOOLCHAIN_PREFIX}".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>.
@@ -211,7 +211,7 @@ It is also possible to execute the described debugging tools conveniently from `
from an Export script (``export.sh`` or ``export.bat``). It is possible to override the script location
using command line argument ``--openocd-scripts``.
.. include:: {IDF_TARGET_TOOLCHAIN_NAME}.inc
.. include:: {IDF_TARGET_PATH_NAME}.inc
:start-after: idf-py-openocd-default-cfg
:end-before: ---
@@ -236,7 +236,7 @@ It is also possible to execute the described debugging tools conveniently from `
Starts `gdbgui <https://www.gdbgui.com>`_ debugger frontend enabling out-of-the-box debugging in a browser window.
It is possible to combine these debugging actions on a single command line allowing convenient
It is possible to combine these debugging actions on a single command line allowing convenient
setup of blocking and non-blocking actions in one step. ``idf.py`` implements a simple logic to move the background
actions (such as openocd) to the beginning and the interactive ones (such as gdb, monitor) to the end of the action list.

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

@@ -122,7 +122,7 @@ Get the error reason code
Example::
int err;
if (select(sockfd + 1, NULL, NULL, &exfds, &tval) <= 0) {
err = errno;
return err;
@@ -156,17 +156,17 @@ Below is a list of common error codes. For more detailed list of standard POSIX/
| ETIMEDOUT | Connection timed out |
+-----------------+-------------------------------------+
| EHOSTDOWN | Host is down |
+-----------------+-------------------------------------+
+-----------------+-------------------------------------+
| EHOSTUNREACH | Host is unreachable |
+-----------------+-------------------------------------+
+-----------------+-------------------------------------+
| EINPROGRESS | Connection already in progress |
+-----------------+-------------------------------------+
+-----------------+-------------------------------------+
| EALREADY | Socket already connected |
+-----------------+-------------------------------------+
+-----------------+-------------------------------------+
| EDESTADDRREQ | Destination address required |
+-----------------+-------------------------------------+
+-----------------+-------------------------------------+
| EPROTONOSUPPORT | Unknown protocol |
+-----------------+-------------------------------------+
+-----------------+-------------------------------------+
Socket Options
^^^^^^^^^^^^^^
@@ -324,14 +324,13 @@ IP layer features
Limitations
^^^^^^^^^^^
Calling ``send()`` or ``sendto()`` repeatedly on a UDP socket may eventually fail with ``errno`` equal to ``ENOMEM``. This is a limitation of buffer sizes in the lower layer network interface drivers. If all driver transmit buffers are full then UDP transmission will fail. Applications sending a high volume of UDP datagrams who don't wish for any to be dropped by the sender should check for this error code and re-send the datagram after a short delay.
- Calling ``send()`` or ``sendto()`` repeatedly on a UDP socket may eventually fail with ``errno`` equal to ``ENOMEM``. This is a limitation of buffer sizes in the lower layer network interface drivers. If all driver transmit buffers are full then UDP transmission will fail. Applications sending a high volume of UDP datagrams who don't wish for any to be dropped by the sender should check for this error code and re-send the datagram after a short delay.
.. only::esp32
.. only:: esp32
Increasing the number of TX buffers in the :ref:`Wi-Fi <CONFIG_ESP32_WIFI_TX_BUFFER>` or :ref:`Ethernet <CONFIG_ETH_DMA_TX_BUFFER_NUM>` project configuration (as applicable) may also help.
.. only::esp32s2
.. only:: not esp32
Increasing the number of TX buffers in the :ref:`Wi-Fi <CONFIG_ESP32_WIFI_TX_BUFFER>` project configuration may also help.

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

@@ -73,43 +73,109 @@ Whenever ESP-IDF outputs a hexadecimal code address of the form ``0x4_______``,
.. highlight:: none
If an ESP-IDF app crashes and panics, a register dump and backtrace is produced, such as the following::
.. only:: CONFIG_IDF_TARGET_ARCH_XTENSA
Guru Meditation Error of type StoreProhibited occurred on core 0. Exception was unhandled.
Register dump:
PC : 0x400f360d PS : 0x00060330 A0 : 0x800dbf56 A1 : 0x3ffb7e00
A2 : 0x3ffb136c A3 : 0x00000005 A4 : 0x00000000 A5 : 0x00000000
A6 : 0x00000000 A7 : 0x00000080 A8 : 0x00000000 A9 : 0x3ffb7dd0
A10 : 0x00000003 A11 : 0x00060f23 A12 : 0x00060f20 A13 : 0x3ffba6d0
A14 : 0x00000047 A15 : 0x0000000f SAR : 0x00000019 EXCCAUSE: 0x0000001d
EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0x00000000
If an ESP-IDF app crashes and panics, a register dump and backtrace is produced, such as the following::
Backtrace: 0x400f360d:0x3ffb7e00 0x400dbf56:0x3ffb7e20 0x400dbf5e:0x3ffb7e40 0x400dbf82:0x3ffb7e60 0x400d071d:0x3ffb7e90
Guru Meditation Error of type StoreProhibited occurred on core 0. Exception was unhandled.
Register dump:
PC : 0x400f360d PS : 0x00060330 A0 : 0x800dbf56 A1 : 0x3ffb7e00
A2 : 0x3ffb136c A3 : 0x00000005 A4 : 0x00000000 A5 : 0x00000000
A6 : 0x00000000 A7 : 0x00000080 A8 : 0x00000000 A9 : 0x3ffb7dd0
A10 : 0x00000003 A11 : 0x00060f23 A12 : 0x00060f20 A13 : 0x3ffba6d0
A14 : 0x00000047 A15 : 0x0000000f SAR : 0x00000019 EXCCAUSE: 0x0000001d
EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0x00000000
IDF Monitor adds more details to the dump::
Backtrace: 0x400f360d:0x3ffb7e00 0x400dbf56:0x3ffb7e20 0x400dbf5e:0x3ffb7e40 0x400dbf82:0x3ffb7e60 0x400d071d:0x3ffb7e90
Guru Meditation Error of type StoreProhibited occurred on core 0. Exception was unhandled.
Register dump:
PC : 0x400f360d PS : 0x00060330 A0 : 0x800dbf56 A1 : 0x3ffb7e00
0x400f360d: do_something_to_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:57
(inlined by) inner_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:52
A2 : 0x3ffb136c A3 : 0x00000005 A4 : 0x00000000 A5 : 0x00000000
A6 : 0x00000000 A7 : 0x00000080 A8 : 0x00000000 A9 : 0x3ffb7dd0
A10 : 0x00000003 A11 : 0x00060f23 A12 : 0x00060f20 A13 : 0x3ffba6d0
A14 : 0x00000047 A15 : 0x0000000f SAR : 0x00000019 EXCCAUSE: 0x0000001d
EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0x00000000
IDF Monitor adds more details to the dump::
Backtrace: 0x400f360d:0x3ffb7e00 0x400dbf56:0x3ffb7e20 0x400dbf5e:0x3ffb7e40 0x400dbf82:0x3ffb7e60 0x400d071d:0x3ffb7e90
0x400f360d: do_something_to_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:57
(inlined by) inner_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:52
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/{IDF_TARGET_PATH_NAME}/./cpu_start.c:254
Guru Meditation Error of type StoreProhibited occurred on core 0. Exception was unhandled.
Register dump:
PC : 0x400f360d PS : 0x00060330 A0 : 0x800dbf56 A1 : 0x3ffb7e00
0x400f360d: do_something_to_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:57
(inlined by) inner_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:52
A2 : 0x3ffb136c A3 : 0x00000005 A4 : 0x00000000 A5 : 0x00000000
A6 : 0x00000000 A7 : 0x00000080 A8 : 0x00000000 A9 : 0x3ffb7dd0
A10 : 0x00000003 A11 : 0x00060f23 A12 : 0x00060f20 A13 : 0x3ffba6d0
A14 : 0x00000047 A15 : 0x0000000f SAR : 0x00000019 EXCCAUSE: 0x0000001d
EXCVADDR: 0x00000000 LBEG : 0x4000c46c LEND : 0x4000c477 LCOUNT : 0x00000000
Backtrace: 0x400f360d:0x3ffb7e00 0x400dbf56:0x3ffb7e20 0x400dbf5e:0x3ffb7e40 0x400dbf82:0x3ffb7e60 0x400d071d:0x3ffb7e90
0x400f360d: do_something_to_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:57
(inlined by) inner_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:52
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/{IDF_TARGET_PATH_NAME}/./cpu_start.c:254
.. only:: CONFIG_IDF_TARGET_ARCH_RISCV
If an ESP-IDF app crashes and panics, a register dump and backtrace is produced, such as the following::
abort() was called at PC 0x42067cd5 on core 0
Stack dump detected
Core 0 register dump:
MEPC : 0x40386488 RA : 0x40386b02 SP : 0x3fc9a350 GP : 0x3fc923c0
TP : 0xa5a5a5a5 T0 : 0x37363534 T1 : 0x7271706f T2 : 0x33323130
S0/FP : 0x00000004 S1 : 0x3fc9a3b4 A0 : 0x3fc9a37c A1 : 0x3fc9a3b2
A2 : 0x00000000 A3 : 0x3fc9a3a9 A4 : 0x00000001 A5 : 0x3fc99000
A6 : 0x7a797877 A7 : 0x76757473 S2 : 0xa5a5a5a5 S3 : 0xa5a5a5a5
S4 : 0xa5a5a5a5 S5 : 0xa5a5a5a5 S6 : 0xa5a5a5a5 S7 : 0xa5a5a5a5
S8 : 0xa5a5a5a5 S9 : 0xa5a5a5a5 S10 : 0xa5a5a5a5 S11 : 0xa5a5a5a5
T3 : 0x6e6d6c6b T4 : 0x6a696867 T5 : 0x66656463 T6 : 0x62613938
MSTATUS : 0x00001881 MTVEC : 0x40380001 MCAUSE : 0x00000007 MTVAL : 0x00000000
MHARTID : 0x00000000
Stack memory:
3fc9a350: 0xa5a5a5a5 0xa5a5a5a5 0x3fc9a3b0 0x403906cc 0xa5a5a5a5 0xa5a5a5a5 0xa5a5a5a50
3fc9a370: 0x3fc9a3b4 0x3fc9423c 0x3fc9a3b0 0x726f6261 0x20292874 0x20736177 0x6c6c61635
3fc9a390: 0x43502074 0x34783020 0x37363032 0x20356463 0x63206e6f 0x2065726f 0x000000300
3fc9a3b0: 0x00000030 0x36303234 0x35646337 0x3c093700 0x0000002a 0xa5a5a5a5 0x3c0937f48
3fc9a3d0: 0x00000001 0x3c0917f8 0x3c0937d4 0x0000002a 0xa5a5a5a5 0xa5a5a5a5 0xa5a5a5a5e
3fc9a3f0: 0x0001f24c 0x000006c8 0x00000000 0x0001c200 0xffffffff 0xffffffff 0x000000200
3fc9a410: 0x00001000 0x00000002 0x3c093818 0x3fccb470 0xa5a5a5a5 0xa5a5a5a5 0xa5a5a5a56
.....
IDF Monitor adds more details to the dump by analyzing the stack dump::
abort() was called at PC 0x42067cd5 on core 0
0x42067cd5: __assert_func at /builds/idf/crosstool-NG/.build/riscv32-esp-elf/src/newlib/newlib/libc/stdlib/assert.c:62 (discriminator 8)
Stack dump detected
Core 0 register dump:
MEPC : 0x40386488 RA : 0x40386b02 SP : 0x3fc9a350 GP : 0x3fc923c0
0x40386488: panic_abort at /home/marius/esp-idf_2/components/esp_system/panic.c:367
0x40386b02: rtos_int_enter at /home/marius/esp-idf_2/components/freertos/port/riscv/portasm.S:35
TP : 0xa5a5a5a5 T0 : 0x37363534 T1 : 0x7271706f T2 : 0x33323130
S0/FP : 0x00000004 S1 : 0x3fc9a3b4 A0 : 0x3fc9a37c A1 : 0x3fc9a3b2
A2 : 0x00000000 A3 : 0x3fc9a3a9 A4 : 0x00000001 A5 : 0x3fc99000
A6 : 0x7a797877 A7 : 0x76757473 S2 : 0xa5a5a5a5 S3 : 0xa5a5a5a5
S4 : 0xa5a5a5a5 S5 : 0xa5a5a5a5 S6 : 0xa5a5a5a5 S7 : 0xa5a5a5a5
S8 : 0xa5a5a5a5 S9 : 0xa5a5a5a5 S10 : 0xa5a5a5a5 S11 : 0xa5a5a5a5
T3 : 0x6e6d6c6b T4 : 0x6a696867 T5 : 0x66656463 T6 : 0x62613938
MSTATUS : 0x00001881 MTVEC : 0x40380001 MCAUSE : 0x00000007 MTVAL : 0x00000000
MHARTID : 0x00000000
Backtrace:
panic_abort (details=details@entry=0x3fc9a37c "abort() was called at PC 0x42067cd5 on core 0") at /home/marius/esp-idf_2/components/esp_system/panic.c:367
367 *((int *) 0) = 0; // NOLINT(clang-analyzer-core.NullDereference) should be an invalid operation on targets
#0 panic_abort (details=details@entry=0x3fc9a37c "abort() was called at PC 0x42067cd5 on core 0") at /home/marius/esp-idf_2/components/esp_system/panic.c:367
#1 0x40386b02 in esp_system_abort (details=details@entry=0x3fc9a37c "abort() was called at PC 0x42067cd5 on core 0") at /home/marius/esp-idf_2/components/esp_system/system_api.c:108
#2 0x403906cc in abort () at /home/marius/esp-idf_2/components/newlib/abort.c:46
#3 0x42067cd8 in __assert_func (file=file@entry=0x3c0937f4 "", line=line@entry=42, func=func@entry=0x3c0937d4 <__func__.8540> "", failedexpr=failedexpr@entry=0x3c0917f8 "") at /builds/idf/crosstool-NG/.build/riscv32-esp-elf/src/newlib/newlib/libc/stdlib/assert.c:62
#4 0x4200729e in app_main () at ../main/iperf_example_main.c:42
#5 0x42086cd6 in main_task (args=<optimized out>) at /home/marius/esp-idf_2/components/freertos/port/port_common.c:133
#6 0x40389f3a in vPortEnterCritical () at /home/marius/esp-idf_2/components/freertos/port/riscv/port.c:129
To decode each address, IDF Monitor runs the following command in the background::
xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf-addr2line -pfiaC -e build/PROJECT.elf ADDRESS
{IDF_TARGET_TOOLCHAIN_PREFIX}-addr2line -pfiaC -e build/PROJECT.elf ADDRESS
.. note::
@@ -128,7 +194,7 @@ In this case, if the panic handler is triggered, as soon as IDF Monitor sees tha
In the background, IDF Monitor runs the following command::
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`
{IDF_TARGET_TOOLCHAIN_PREFIX}-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf :idf_target:`Hello NAME chip`
Output Filtering

16
docs/en/api-guides/ulp.rst
View File

@@ -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-{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.
.. 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, ``{IDF_TARGET_TOOLCHAIN_PREFIX}-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::
@@ -150,9 +150,9 @@ Declaration of the entry point symbol comes from the generated header file menti
ESP32 ULP program flow
-----------------------
ESP32 ULP coprocessor is started by a timer. The timer is started once ``ulp_run`` is called. The timer counts a number of RTC_SLOW_CLK ticks
(by default, produced by an internal 150 kHz RC oscillator). The number of ticks is set using ``SENS_ULP_CP_SLEEP_CYCx_REG`` registers (x = 0..4).
When starting the ULP for the first time, ``SENS_ULP_CP_SLEEP_CYC0_REG`` will be used to set the number of timer ticks.
ESP32 ULP coprocessor is started by a timer. The timer is started once ``ulp_run`` is called. The timer counts a number of RTC_SLOW_CLK ticks
(by default, produced by an internal 150 kHz RC oscillator). The number of ticks is set using ``SENS_ULP_CP_SLEEP_CYCx_REG`` registers (x = 0..4).
When starting the ULP for the first time, ``SENS_ULP_CP_SLEEP_CYC0_REG`` will be used to set the number of timer ticks.
Later the ULP program can select another ``SENS_ULP_CP_SLEEP_CYCx_REG`` register using ``sleep`` instruction.
The application can set ULP timer period values (SENS_ULP_CP_SLEEP_CYCx_REG, x = 0..4) using ``ulp_set_wakeup_period`` function.
@@ -171,19 +171,19 @@ Declaration of the entry point symbol comes from the generated header file menti
ESP32-S2 ULP program flow
-------------------------
ESP32-S2 ULP coprocessor is started by a timer. The timer is started once ``ulp_run`` is called. The timer counts a number of RTC_SLOW_CLK ticks
(by default, produced by an internal 90 kHz RC oscillator). The number of ticks is set using ``RTC_CNTL_ULP_CP_TIMER_1_REG`` register.
ESP32-S2 ULP coprocessor is started by a timer. The timer is started once ``ulp_run`` is called. The timer counts a number of RTC_SLOW_CLK ticks
(by default, produced by an internal 90 kHz RC oscillator). The number of ticks is set using ``RTC_CNTL_ULP_CP_TIMER_1_REG`` register.
The application can set ULP timer period values by ``ulp_set_wakeup_period`` function.
.. doxygenfunction:: ulp_set_wakeup_period
Once the timer counts the number of ticks set in the selected ``RTC_CNTL_ULP_CP_TIMER_1_REG`` register, ULP coprocessor powers up and starts running the program
Once the timer counts the number of ticks set in the selected ``RTC_CNTL_ULP_CP_TIMER_1_REG`` register, ULP coprocessor powers up and starts running the program
from the entry point set in the call to ``ulp_run``.
The program runs until it encounters a ``halt`` instruction or an illegal instruction. Once the program halts, ULP coprocessor powers down, and the timer is started again.
To disable the timer (effectively preventing the ULP program from running again), clear the ``RTC_CNTL_ULP_CP_SLP_TIMER_EN`` bit in the ``RTC_CNTL_STATE0_REG`` register.
To disable the timer (effectively preventing the ULP program from running again), clear the ``RTC_CNTL_ULP_CP_SLP_TIMER_EN`` bit in the ``RTC_CNTL_STATE0_REG`` register.
This can be done both from ULP code and from the main program.